refactor: improve structure and alien-signals integration

packages/charm-sync/src/__tests__/client.spec.luau

@@ -0,0 +1,121 @@
+local Charm = require("../../Charm")
+local CharmSync = require("../")
+local suite = require("../../../../test/suite")
+
+local atom = Charm.atom
+local subscribe = Charm.subscribe
+local client = CharmSync.client
+local test = suite.test
+
+test("should sync state payload", function()
+	local a = atom(1)
+	local client = client({ atoms = { a = a } })
+
+	client:sync({
+		type = "init",
+		data = { a = 2 },
+	})
+
+	assert(a() == 2, "should set a to the initial value")
+end)
+
+test("should sync state patch", function()
+	local a = atom({ b = 1, c = 2 })
+	local previous = a()
+	local client = client({ atoms = { a = a } })
+
+	client:sync({
+		type = "init",
+		data = { a = a() },
+	})
+
+	assert(a() == previous, "should set a to the initial value")
+
+	client:sync({
+		type = "patch",
+		data = { a = { b = 3 } },
+	})
+
+	assert(a() ~= previous, "should apply patch")
+	assert(a().b == 3, "should set b to the new value")
+	assert(a().c == 2, "should not change c")
+end)
+
+test("should fix sparse array patches", function()
+	local a = atom({ 1 })
+	local client = client({ atoms = { a = a } })
+
+	client:sync({
+		type = "init",
+		data = { a = a() },
+	})
+
+	-- This patch would be the result of a diff between { 1 } and { 1, 2 } that
+	-- was JSON-serialized and deserialized. The client should be able to catch
+	-- this and convert the string key back to a number.
+	client:sync({
+		type = "patch",
+		data = { a = { ["2"] = 2 } },
+	})
+
+	assert(a()["2" :: any] == nil, "should convert serialized arrays to use numbers")
+	assert(a()[2] == 2, "should convert serialized arrays to use numbers")
+end)
+
+test("should apply multiple patches", function()
+	local a = atom(1)
+	local client = client({ atoms = { a = a } })
+	local calls = {}
+
+	subscribe(a, function(value)
+		table.insert(calls, value)
+	end)
+
+	client:sync({
+		type = "init",
+		data = { a = a() },
+	})
+
+	client:sync({
+		type = "patch",
+		data = { a = 2 },
+	}, {
+		type = "patch",
+		data = { a = 3 },
+	})
+
+	assert(a() == 3, "should apply the last patch")
+	assert(table.concat(calls) == "23", `wrong order: {table.concat(calls)}`)
+end)
+
+test("should batch patches", function()
+	local a = atom(0)
+	local b = atom(0)
+	local client = client({ atoms = { a = a, b = b } })
+	local states = {}
+
+	subscribe(a, function()
+		states.b = b()
+	end)
+
+	subscribe(b, function()
+		states.a = a()
+	end)
+
+	client:sync({
+		type = "init",
+		data = { a = a(), b = b() },
+	})
+
+	client:sync({
+		type = "patch",
+		data = { a = 1, b = 2 },
+	})
+
+	assert(a() == 1, "should set a to the new value")
+	assert(b() == 2, "should set b to the new value")
+	assert(states.a == 1, "sub to a should run after b updates")
+	assert(states.b == 2, "sub to b should run after a updates")
+end)
+
+return {}

packages/charm-sync/src/__tests__/flatten.spec.luau

@@ -0,0 +1,25 @@
+local Charm = require("../../Charm")
+local CharmSync = require("../")
+local suite = require("../../../../test/suite")
+
+local atom = Charm.atom
+local flatten = CharmSync.flatten
+local test = suite.test
+
+test("should flatten atoms", function()
+	local input = {
+		a = atom(0),
+		b = { c = atom(0) },
+		d = { e = { f = atom(0) } },
+	}
+	local result = flatten(input)
+
+	assert(result.a == input.a, "should flatten the first level")
+	assert(result["b/c"] == input.b.c, "should flatten the second level")
+	assert(result["d/e/f"] == input.d.e.f, "should flatten the third level")
+
+	assert(result.b == nil, "should remove the original nested tables")
+	assert(result.d == nil, "should remove the original nested tables")
+end)
+
+return {}

packages/charm-sync/src/__tests__/patch.spec.luau

@@ -0,0 +1,128 @@
+local HttpService = game:GetService("HttpService")
+
+local CharmSync = require("../")
+local suite = require("../../../../test/suite")
+
+local patch = CharmSync.patch
+local test = suite.test
+
+local function serdes(value: { [any]: any })
+	return HttpService:JSONDecode(HttpService:JSONEncode(value))
+end
+
+test("returns a patch", function()
+	local prevState = { foo = "bar", baz = "qux" }
+	local nextState = { foo = "bar", baz = "quux" }
+	local patches = patch.diff(prevState, nextState)
+
+	assert(patches ~= nil, "should return a patch")
+	assert(patches.baz == "quux", "should return the changed value")
+	assert(patches.foo == nil, "should omit unchanged values")
+end)
+
+test("applies a patch", function()
+	local prevState = { foo = "bar", baz = "qux" }
+	local patches = { baz = "quux", qaz = "qux" }
+	local applied = patch.apply(prevState, patches)
+
+	assert(applied ~= nil, "should return a new state")
+	assert(applied.baz == "quux", "should apply the changed value")
+	assert(applied.foo == "bar", "should keep the unchanged value")
+	assert(applied.qaz == "qux", "should add the new value")
+end)
+
+test("allows nested patches", function()
+	local prevState = { foo = { bar = "baz" } }
+	local nextState = { foo = { bar = "qux" } }
+	local patches = patch.diff(prevState, nextState)
+	local applied = patch.apply(prevState, patches)
+
+	assert(applied.foo.bar == "qux", "should apply the nested patch")
+end)
+
+test("preserves array density when applying", function()
+	local prevState = { "a", "b", "c", "d" }
+	local nextState = { ["2"] = "B", ["4"] = "D" }
+	local applied = patch.apply(prevState, nextState)
+
+	assert(applied[1] == "a", "should keep a")
+	assert(applied[2] == "B", "should apply B")
+	assert(applied[3] == "c", "should keep c")
+	assert(applied[4] == "D", "should apply D")
+
+	assert(applied["2"] == nil, "should convert serialized arrays to use numbers")
+	assert(applied["4"] == nil, "should convert serialized arrays to use numbers")
+end)
+
+test("preserves array density after serdes", function()
+	-- This particular change results in a patch that cannot be serialized
+	-- without losing information. Charm resolves this issue internally.
+	local prevState = { "a", "b", "c", "d", "e" }
+	local nextState = { "A", "b", "c", "D" }
+
+	local patches = serdes(patch.diff(prevState, nextState))
+	local applied = patch.apply(prevState, patches)
+
+	for index in next, prevState do
+		assert(applied[index] == nextState[index], `expected {applied[index]} to be {nextState[index]}`)
+	end
+
+	for index in next, applied do
+		assert(applied[index] == nextState[index], `expected {applied[index]} to be {nextState[index]}`)
+	end
+end)
+
+test("preserves large gaps between keys", function()
+	local prevState = table.create(10000, "foo")
+	local nextState = table.move(prevState, 2, 9998, 2, { [1] = "bar", [9999] = "bar" })
+
+	local start = os.clock()
+
+	local patches = serdes(patch.diff(prevState, nextState))
+	local applied = patch.apply(prevState, patches)
+
+	assert(os.clock() - start < 10e-3, `Performance is not acceptable ({(os.clock() - start) * 1e3}ms)`)
+
+	for index in next, prevState do
+		assert(applied[index] == nextState[index], `expected {applied[index]} to be {nextState[index]}`)
+	end
+end)
+
+test("cannot preserve sparse arrays", function()
+	local prevState = {}
+	local nextState = { [2] = "foo" }
+
+	local patches = serdes(patch.diff(prevState, nextState))
+	local applied = patch.apply(prevState, patches)
+
+	-- Not enough information is available to determine whether 'patches'
+	-- should keep the string keys added during remote event serialization.
+	assert(applied["2"] ~= nil, "will fail to convert string keys to numbers")
+	assert(applied[2] == nil, "will fail to convert string keys to numbers")
+end)
+
+test("optionally fixes sparse arrays", function()
+	for index in next, patch.diff({ 1, 1, 1, 1, 1 }, { 2, 1, 1, 2 }, true) do
+		assert(type(index) == "string", `expected {type(index)} {index} to be string`)
+	end
+
+	for index in next, patch.diff({ 1, 1, 1, 1, 1 }, { 2, 1, 1, 2 }, false) do
+		assert(type(index) == "number", `expected {type(index)} {index} to be number`)
+	end
+end)
+
+test("optionally validates state", function()
+	local success = pcall(function()
+		patch.diff({}, { [0.1] = true }, true)
+	end)
+
+	assert(not success, "should not allow non-integer keys")
+
+	success = pcall(function()
+		patch.diff({}, { [0.1] = true }, false)
+	end)
+
+	assert(success, "should skip validation if not requested")
+end)
+
+return {}

packages/charm-sync/src/__tests__/server.spec.luau

@@ -0,0 +1,99 @@
+local Charm = require("../../Charm")
+local CharmSync = require("../")
+local suite = require("../../../../test/suite")
+
+type SyncPayload = CharmSync.SyncPayload
+
+local atom = Charm.atom
+local server = CharmSync.server
+local patch = CharmSync.patch
+local test = suite.test
+
+local target: Player = {} :: any
+
+test("sends state to new players", function()
+	local a = atom(1)
+	local server = server({ atoms = { a = a }, interval = -1 })
+	local player: Player, payload: SyncPayload
+
+	local disconnect = server:connect(function(...)
+		player, payload = ...
+	end)
+
+	server:hydrate(target)
+
+	assert(player == target, "should send to the target player")
+	assert(payload.type == "init", "should be an init payload")
+	assert(payload.data.a == 1, "should send the initial state")
+
+	disconnect()
+end)
+
+test("sends state patches", function()
+	local a = atom({ b = 1, c = 2 } :: { [string]: number? })
+	local server = server({ atoms = { a = a }, interval = -1 })
+	local player: Player, payload: SyncPayload
+
+	local disconnect = server:connect(function(...)
+		player, payload = ...
+	end)
+
+	a({ b = 1, c = 5 })
+	server:_sendPatch(target)
+
+	assert(player == target, "should send to the target player")
+	assert(payload.type == "patch", "should be a patch payload")
+	assert(payload.data.a.b == nil, "should not send unchanged values")
+	assert(payload.data.a.c == 5, "should send changed values")
+
+	a({ b = 1, d = 1 })
+	server:_sendPatch(target)
+
+	assert(payload.data.a.b == nil, "should not send unchanged values")
+	assert(patch.isNone(payload.data.a.c) == true, "should send None for removed values")
+	assert(payload.data.a.d == 1, "should send new values")
+
+	disconnect()
+end)
+
+test("preserves history", function()
+	local a = atom(1)
+	local b = atom(1)
+	local payloads: { SyncPayload }
+
+	local server = server({
+		atoms = { a = a, b = b },
+		interval = -1,
+		preserveHistory = true,
+	})
+
+	local disconnect = server:connect(function(_, ...)
+		payloads = { ... }
+	end)
+
+	a(2)
+	b(2)
+	server:_sendPatch(target)
+
+	assert(#payloads == 1, "should only have one payload")
+	assert(payloads[1].type == "patch", "should be a patch payload")
+	assert(payloads[1].data.a == 2, "should send the new value of a")
+	assert(payloads[1].data.b == 2, "should send the new value of b")
+
+	a(3)
+	a(4)
+	b(3)
+	server:_sendPatch(target)
+
+	assert(#payloads == 2, "should have two payloads")
+	assert(payloads[1].type == "patch", "1 should be a patch payload")
+	assert(payloads[1].data.a == 3, "1 should send the new value of a")
+	assert(payloads[1].data.b == nil, "1 should not send unchanged values")
+	assert(payloads[2].type == "patch", "2 should be a patch payload")
+	assert(payloads[2].data.a == 4, "2 should send the new value of a")
+	assert(payloads[2].data.b == 3, "2 should send the new value of b")
+
+	disconnect()
+end)
+
+return {}

packages/charm-sync/src/__tests__/spec.luau

@@ -0,0 +1,24 @@
+local suite = require("../../../../test/suite")
+
+suite.describe("charm-sync", function()
+	if not game then
+		return suite.skip()
+	end
+	suite.describe("client", function()
+		require("./client.spec")
+	end)
+	suite.describe("server", function()
+		require("./server.spec")
+	end)
+	suite.describe("flatten", function()
+		require("./flatten.spec")
+	end)
+	suite.describe("patch", function()
+		require("./patch.spec")
+	end)
+	suite.describe("validate", function()
+		require("./validate.spec")
+	end)
+end)
+
+return {}

packages/charm-sync/src/__tests__/validate.spec.luau

@@ -0,0 +1,35 @@
+local Charm = require("../../Charm")
+local CharmSync = require("../")
+local suite = require("../../../../test/suite")
+
+local atom = Charm.atom
+local validate = CharmSync.validate
+local test = suite.test
+
+test("validates inputs", function()
+	local cases: { [string]: { value: any, expected: any } } = {
+		array = { value = { 1, 2, 3 }, expected = true },
+		array_sparse = { value = { 1, nil :: any, 3 }, expected = true },
+		array_sparse_invalid = { value = { [1] = 0, [3] = 0 }, expected = false },
+
+		map_decimal_key = { value = { [1.5] = 0 }, expected = false },
+		map_infinity_key = { value = { [math.huge] = true }, expected = false },
+		map_mixed_key = { value = { [1] = 0, a = 0 }, expected = false },
+
+		nested_atom = { value = atom(0), expected = false },
+	}
+
+	for key, case in next, cases do
+		local success, result = pcall(function()
+			validate(case.value, key)
+		end)
+
+		if case.expected and not success then
+			error(`Expected {key} to be valid, threw {result}`)
+		elseif not case.expected and success then
+			error(`Expected {key} to be invalid, but it was valid`)
+		end
+	end
+end)
+
+return {}