refactor: move modules to packages (#41)

* refactor: move modules to `packages`

* chore: remove .vscode

packages/charm-sync/default.project.json

@@ -0,0 +1,6 @@
+{
+	"name": "CharmSync",
+	"tree": {
+		"$path": "src"
+	}
+}

packages/charm-sync/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "@rbxts/charm-sync",
+	"version": "0.1.1",
+	"description": "Sync server state with clients using Charm",
+	"repository": "littensy/charm",
+	"license": "MIT",
+	"main": "src/init.luau",
+	"types": "src/index.d.ts",
+	"scripts": {
+		"prepare": "cp ../../LICENSE.md . && cp ../../README.md .",
+		"publish:wally": "wally publish"
+	},
+	"dependencies": {
+		"@rbxts/charm": "workspace:*"
+	}
+}

packages/charm-sync/src/client.luau

@@ -0,0 +1,82 @@
+local Charm = require(script.Parent.Parent.Charm)
+local patch = require(script.Parent.patch)
+local types = require(script.Parent.types)
+type SyncPayload = types.SyncPayload
+
+type ClientOptions = {
+	--[=[
+		The atoms to synchronize with the server.
+	]=]
+	atoms: { [string | number]: Charm.Atom<any> },
+	--[=[
+		Whether to ignore patches sent before the client has been hydrated.
+		Default is `true`.
+	]=]
+	ignoreUnhydrated: boolean?,
+}
+
+type ClientSyncer = {
+	--[=[
+		Applies a patch or initializes the state of the atoms with the given
+		payload from the server.
+		
+		@param ...payloads The patches or hydration payloads to apply.
+	]=]
+	sync: (self: ClientSyncer, ...SyncPayload) -> (),
+}
+
+--[=[
+	Creates a `ClientSyncer` object that receives patches from the server and
+	applies them to the local state.
+	
+	@param options The atoms to synchronize with the server.
+	@return A `ClientSyncer` object.
+]=]
+local function client(options: ClientOptions): ClientSyncer
+	local self = {} :: ClientSyncer
+
+	local atoms = options.atoms
+	local ignoreUnhydrated = options.ignoreUnhydrated ~= false
+	local hydrated = false
+
+	local function hydrate(state: { [string | number]: any })
+		hydrated = true
+
+		for key, value in next, state do
+			local atom = atoms[key]
+			atom(value)
+		end
+	end
+
+	local function apply(data: { [string | number]: any })
+		local target = {}
+
+		for key, atom in next, atoms do
+			target[key] = atom()
+		end
+
+		target = patch.apply(target, data)
+
+		for key, atom in next, atoms do
+			atom(target[key])
+		end
+	end
+
+	function self:sync(...)
+		for index = 1, select("#", ...) do
+			local payload: SyncPayload = select(index, ...)
+
+			Charm.batch(function()
+				if payload.type == "init" then
+					hydrate(payload.data)
+				elseif not ignoreUnhydrated or hydrated then
+					apply(payload.data)
+				end
+			end)
+		end
+	end
+
+	return self
+end
+
+return client

packages/charm-sync/src/index.d.ts

@@ -0,0 +1,176 @@
+import { Atom, Selector } from "@rbxts/charm";
+
+export = CharmSync;
+export as namespace CharmSync;
+
+type Cleanup = () => void;
+
+declare namespace CharmSync {
+	type AtomMap = Record<string, Atom<any>>;
+
+	type SelectorMap = Record<string, Selector<any>>;
+
+	/**
+	 * @deprecated Use `SelectorMap` instead.
+	 */
+	type MoleculeMap = SelectorMap;
+
+	/**
+	 * Infers the type of the return values produced by a map of functions.
+	 */
+	type StateOfMap<T> = {
+		readonly [P in keyof T]: T[P] extends Selector<infer State> ? State : never;
+	};
+
+	/**
+	 * Represents the removal of a value from the state.
+	 */
+	interface None {
+		readonly __none: "__none";
+	}
+
+	type MaybeNone<T> = undefined extends T ? None : never;
+
+	/**
+	 * Creates a `ClientSyncer` object that receives patches from the server and
+	 * applies them to the local state.
+	 *
+	 * @client
+	 * @param options The atoms to synchronize with the server.
+	 * @returns A `ClientSyncer` object.
+	 */
+	function client<Atoms extends AtomMap>(options: ClientOptions<Atoms>): ClientSyncer<Atoms>;
+
+	/**
+	 * Creates a `ServerSyncer` object that sends patches to the client and
+	 * hydrates the client's state.
+	 *
+	 * @server
+	 * @param options The atoms to synchronize with the client.
+	 * @returns A `ServerSyncer` object.
+	 */
+	function server<Selectors extends SelectorMap>(options: ServerOptions<Selectors>): ServerSyncer<Selectors>;
+
+	/**
+	 * Checks whether a value is `None`. If `true`, the value is scheduled to be
+	 * removed from the state when the patch is applied.
+	 *
+	 * @param value The value to check.
+	 * @returns `true` if the value is `None`, otherwise `false`.
+	 */
+	function isNone(value: unknown): value is None;
+
+	type DataTypes = {
+		[P in keyof CheckableTypes as P extends keyof CheckablePrimitives ? never : P]: CheckableTypes[P];
+	};
+
+	/**
+	 * A type that should not be made partial in patches.
+	 */
+	type DataType = DataTypes[keyof DataTypes];
+
+	/**
+	 * A partial patch that can be applied to the state to update it. Represents
+	 * the difference between the current state and the next state.
+	 *
+	 * If a value was removed, it is replaced with `None`. This can be checked
+	 * using the `sync.isNone` function.
+	 */
+	type SyncPatch<State> =
+		| MaybeNone<State>
+		| (State extends ReadonlyMap<infer K, infer V> | Map<infer K, infer V>
+				? ReadonlyMap<K, SyncPatch<V> | None>
+				: State extends Set<infer T> | ReadonlySet<infer T>
+					? ReadonlyMap<T, true | None>
+					: State extends readonly (infer T)[]
+						? readonly (SyncPatch<T> | None | undefined)[]
+						: State extends DataType
+							? State
+							: State extends object
+								? { readonly [P in keyof State]?: SyncPatch<State[P]> }
+								: State);
+
+	/**
+	 * A payload that can be sent from the server to the client to synchronize
+	 * state between the two.
+	 */
+	type SyncPayload<Selectors extends SelectorMap> =
+		| { readonly type: "init"; readonly data: StateOfMap<Selectors> }
+		| { readonly type: "patch"; readonly data: SyncPatch<StateOfMap<Selectors>> };
+
+	interface ClientOptions<Atoms extends AtomMap> {
+		/**
+		 * The atoms to synchronize with the server.
+		 */
+		atoms: Atoms;
+		/**
+		 * Whether to ignore patches sent before the client has been hydrated.
+		 * Defaults to `true`.
+		 */
+		ignoreUnhydrated?: boolean;
+	}
+
+	interface ServerOptions<Selectors extends SelectorMap> {
+		/**
+		 * The atoms to synchronize with the client.
+		 */
+		atoms: Selectors;
+		/**
+		 * The interval at which to send patches to the client, in seconds.
+		 * Defaults to `0` (patches are sent up to once per frame). Set to a
+		 * negative value to disable automatic syncing.
+		 */
+		interval?: number;
+		/**
+		 * Whether the history of state changes since the client's last update
+		 * should be preserved. This is useful for values that change multiple times
+		 * per frame, where each individual change is important. Defaults to `false`.
+		 *
+		 * If `true`, the broadcaster will send a list of payloads to the client
+		 * instead of a single payload. The client will apply each payload in order
+		 * to reconstruct the state's changes over time.
+		 */
+		preserveHistory?: boolean;
+		/**
+		 * When `true`, convert problematic sparse arrays into dictionaries
+		 * with string keys. Defaults to `true`.
+		 *
+		 * While this is mandatory for safely syncing arrays over vanilla Roblox
+		 * remotes, it can be disabled if your network library uses a custom
+		 * serialization method (i.e. Zap, ByteNet).
+		 */
+		serializeArrays?: boolean;
+	}
+
+	interface ClientSyncer<Atoms extends AtomMap> {
+		/**
+		 * Applies a patch or initializes the state of the atoms with the given
+		 * payload from the server.
+		 *
+		 * @param payloads The patches or hydration payloads to apply.
+		 */
+		sync(...payloads: SyncPayload<Atoms>[]): void;
+	}
+
+	interface ServerSyncer<Selectors extends SelectorMap> {
+		/**
+		 * Sets up a subscription to each atom that schedules a patch to be sent to
+		 * the client whenever the state changes. When a change occurs, the `callback`
+		 * is called with the player and the payloads to send.
+		 *
+		 * Note that a `payload` object should not be mutated. If you need to modify
+		 * a payload, apply the changes to a copy of the object.
+		 *
+		 * @param callback The function to call when the state changes.
+		 * @returns A cleanup function that unsubscribes all listeners.
+		 */
+		connect(callback: (player: Player, ...payloads: SyncPayload<Selectors>[]) => void): Cleanup;
+		/**
+		 * Hydrates the client's state with the server's state. This should be
+		 * called when a player joins the game and requires the server's state.
+		 *
+		 * @param player The player to hydrate.
+		 */
+		hydrate(player: Player): void;
+	}
+}

packages/charm-sync/src/init.luau

@@ -0,0 +1,16 @@
+local client = require(script.client)
+local patch = require(script.patch)
+local server = require(script.server)
+local types = require(script.types)
+
+export type SyncPayload = types.SyncPayload
+
+--[=[
+	Synchronizes state between the client and server. The server sends patches
+	to the client, which applies them to its local state.
+]=]
+return {
+	client = client,
+	server = server,
+	isNone = patch.isNone,
+}

packages/charm-sync/src/interval.luau

@@ -0,0 +1,30 @@
+local RunService = game:GetService("RunService")
+
+--[=[
+	Schedules a function to be called at a fixed interval of `seconds`.
+	
+	@param callback The function to call.
+	@param seconds The interval in seconds.
+	@return A function that cancels the interval.
+]=]
+local function interval(callback: () -> (), seconds: number): () -> ()
+	if seconds < 0 then
+		return function() end
+	end
+
+	local clock = 0
+
+	local connection = RunService.Heartbeat:Connect(function(delta)
+		clock += delta
+		if clock >= seconds then
+			clock = 0
+			callback()
+		end
+	end)
+
+	return function()
+		connection:Disconnect()
+	end
+end
+
+return interval

packages/charm-sync/src/patch.luau

@@ -0,0 +1,121 @@
+local validate = require(script.Parent.validate)
+
+local __DEV__ = _G.__DEV__
+
+--[=[
+	A special symbol that denotes the absence of a value. Used to represent
+	deleted values in patches.
+]=]
+local None = { __none = "__none" }
+
+local function isNone(value: any): boolean
+	return type(value) == "table" and value.__none == "__none"
+end
+
+--[=[
+	JSON serialization can drop the last values of a sparse array. For example,
+	`{ [1] = 1, [3] = 3 }` becomes `[1]` in some cases. Ambiguity in the
+	serialization of sparse arrays can be resolved by converting them to
+	dictionaries with string keys.
+
+	The `apply` function will convert these dictionaries back into arrays as
+	long as the target array is not sparse. This function ensures that the diff
+	function produces a patch that can be correctly applied.
+]=]
+local function stringifySparseArray(object: { any }): { [string | number]: any }
+	local maxn = table.maxn(object)
+
+	if maxn == 0 or maxn == #object then
+		-- The object is either not an array or a dense array
+		return object
+	end
+
+	local dictionary = {}
+
+	for index, value in next, object do
+		dictionary[tostring(index)] = value
+	end
+
+	return dictionary
+end
+
+--[=[
+	Compares two states and returns a patch that can be applied to the previous
+	state to produce the next state.
+
+	@param prevState The previous state.
+	@param nextState The next state.
+	@param serializeArrays Whether to convert sparse arrays into dictionaries. Defaults to `true`.
+	@returns A patch that can be applied to the previous state.
+]=]
+local function diff(prevState: { [any]: any }, nextState: { [any]: any }, serializeArrays: boolean?)
+	local patches = table.clone(nextState)
+
+	for key, previous in next, prevState do
+		local current = nextState[key]
+
+		if previous == current then
+			patches[key] = nil
+		elseif current == nil then
+			patches[key] = None
+		elseif type(previous) == "table" and type(current) == "table" then
+			patches[key] = diff(previous, current, serializeArrays)
+		end
+	end
+
+	-- Coerce sparse array patches into dictionaries
+	if serializeArrays ~= false and (prevState[1] ~= nil or nextState[1] ~= nil) then
+		patches = stringifySparseArray(patches)
+	end
+
+	if __DEV__ then
+		for key, value in next, prevState do
+			validate(value, key)
+		end
+
+		for key, value in nextState do
+			if prevState[key] ~= value then
+				validate(value, key)
+			end
+		end
+	end
+
+	return patches
+end
+
+--[=[
+	Applies a patch to a state and returns the next state.
+
+	@param state The current state.
+	@param patches The patches to apply.
+	@returns The next state.
+]=]
+local function apply(state: any, patches: any): any
+	if type(patches) == "table" and patches.__none == "__none" then
+		return nil
+	elseif type(state) ~= "table" or type(patches) ~= "table" then
+		return patches
+	end
+
+	local nextState = table.clone(state)
+	local stateIsArray = state[1] ~= nil
+
+	for key, patch in next, patches do
+		-- Diff-checking an array produces a sparse array, which will not be
+		-- preserved when converted to JSON. To prevent this, we turn string
+		-- keys back into numeric keys.
+		if stateIsArray and type(key) == "string" then
+			key = tonumber(key) or key
+		end
+
+		nextState[key] = apply(nextState[key], patch)
+	end
+
+	return nextState
+end
+
+return {
+	isNone = isNone,
+	diff = diff,
+	apply = apply,
+}

packages/charm-sync/src/server.luau

@@ -0,0 +1,262 @@
+local Players = game:GetService("Players")
+
+local Charm = require(script.Parent.Parent.Charm)
+local interval = require(script.Parent.interval)
+local patch = require(script.Parent.patch)
+local types = require(script.Parent.types)
+type SyncPayload = types.SyncPayload
+
+type ServerOptions = {
+	--[=[
+		The atoms to synchronize with the client.
+	]=]
+	atoms: { [string | number]: Charm.Atom<any> },
+	--[=[
+		The interval at which to send patches to the client, in seconds.
+		Defaults to `0` (patches are sent up to once per frame). Set to a
+		negative value to disable automatic syncing.
+	]=]
+	interval: number?,
+	--[=[
+		Whether the history of state changes since the client's last update
+		should be preserved. This is useful for values that change multiple times
+		per frame, where each individual change is important. Defaults to `false`.
+	]=]
+	preserveHistory: boolean?,
+	--[=[
+		Whether to convert problematic sparse arrays into dictionaries with
+		string keys. Defaults to `true`.
+
+		While this is mandatory for safely syncing arrays over vanilla Roblox
+		remotes, it can be disabled if your network library uses a custom
+		serialization method (i.e. Zap, ByteNet).
+	]=]
+	serializeArrays: boolean?,
+}
+
+type ServerSyncer = {
+	--[=[
+		Sets up a subscription to each atom that schedules a patch to be sent to
+		the client whenever the state changes. When a change occurs, the `callback`
+		is called with the player and the payload to send.
+
+		Note that the `payload` object should not be mutated. If you need to
+		modify the payload, apply the changes to a copy of the object.
+
+		@param callback The function to call when the state changes.
+		@return A cleanup function that unsubscribes all listeners.
+	]=]
+	connect: (self: ServerSyncer, callback: (player: Player, ...SyncPayload) -> ()) -> () -> (),
+	--[=[
+		Hydrates the client's state with the server's state. This should be
+		called when a player joins the game and requires the server's state.
+
+		@param player The player to hydrate.
+	]=]
+	hydrate: (self: ServerSyncer, player: Player) -> (),
+	--[=[
+		@deprecated For internal use only.
+	]=]
+	_sendPatch: (self: ServerSyncer, player: Player) -> (),
+}
+
+--[=[
+	Creates a `ServerSyncer` object that sends patches to the client and
+	hydrates the client's state.
+	
+	@param options The atoms to synchronize with the client.
+	@return A `ServerSyncer` object.
+]=]
+local function server(options: ServerOptions): ServerSyncer
+	local self = {} :: ServerSyncer
+	local sync: (player: Player, payload: SyncPayload) -> ()
+
+	local function createSnapshot()
+		local snapshot = {}
+
+		for key, atom in next, options.atoms do
+			snapshot[key] = atom()
+		end
+
+		return snapshot
+	end
+
+	-- Send the initial state to a player when they join the server.
+	function self:hydrate(player)
+		assert(sync, "connect() must be called before hydrate()")
+
+		sync(player, {
+			type = "init",
+			data = createSnapshot(),
+		})
+	end
+
+	-- If the history of state changes should be preserved, keep a list of
+	-- previous snapshots and diff-check each one from the last.
+	if options.preserveHistory then
+		local snapshots = { createSnapshot() }
+		local changed = false
+
+		function self:connect(callback)
+			local subscriptions = {}
+
+			sync = callback
+
+			local function pushSnapshot(key: string | number, current: any, previous: any)
+				local lastSnapshot = snapshots[#snapshots]
+				local previousSnapshot = snapshots[#snapshots - 1]
+
+				-- Optimize snapshots by updating the most recent snapshot if the
+				-- previous and current values are the same, since this allows us
+				-- to group multiple changes into a single snapshot.
+				if previousSnapshot and previousSnapshot[key] == previous and lastSnapshot[key] == previous then
+					lastSnapshot[key] = current
+				else
+					local nextSnapshot = table.clone(lastSnapshot)
+					nextSnapshot[key] = current
+					table.insert(snapshots, nextSnapshot)
+				end
+			end
+
+			-- Populate the snapshot with the initial state of each atom.
+			-- Subscribe to each atom and update the state when it changes.
+			for key, atom in next, options.atoms do
+				subscriptions[key] = Charm.subscribe(atom, function(current, previous)
+					pushSnapshot(key, current, previous)
+					changed = true
+				end)
+			end
+
+			local disconnect = interval(function()
+				if not changed then
+					return
+				end
+
+				local payloads: { SyncPayload } = {}
+				local lastSnapshot
+
+				for index, snapshot in next, snapshots do
+					lastSnapshot = snapshot
+
+					if index == 1 then
+						continue
+					end
+
+					table.insert(payloads, {
+						type = "patch",
+						data = patch.diff(snapshots[index - 1], snapshot, options.serializeArrays),
+					})
+				end
+
+				snapshots = { lastSnapshot }
+				changed = false
+
+				for _, player in next, Players:GetPlayers() do
+					callback(player, unpack(payloads))
+				end
+			end, options.interval or 0)
+
+			return function()
+				disconnect()
+
+				for _, unsubscribe in next, subscriptions do
+					unsubscribe()
+				end
+			end
+		end
+
+		function self:_sendPatch(player: Player)
+			assert(sync, "connect() must be called before _sendPatch()")
+
+			if not changed then
+				return
+			end
+
+			local payloads: { SyncPayload } = {}
+
+			for index, snapshot in next, snapshots do
+				if index == 1 then
+					continue
+				end
+
+				table.insert(payloads, {
+					type = "patch",
+					data = patch.diff(snapshots[index - 1], snapshot, options.serializeArrays),
+				})
+			end
+
+			snapshots = { snapshots[#snapshots] }
+			changed = false
+
+			sync(player, unpack(payloads))
+		end
+
+		return self
+	end
+
+	local previousSnapshot = createSnapshot()
+	local currentSnapshot = table.clone(previousSnapshot)
+	local changed = false
+
+	function self:connect(callback)
+		local subscriptions = {}
+
+		sync = callback
+
+		-- Subscribe to each atom and update the state when one changes.
+		for key, atom in next, options.atoms do
+			subscriptions[key] = Charm.subscribe(atom, function(state)
+				currentSnapshot[key] = state
+				changed = true
+			end)
+		end
+
+		local disconnect = interval(function()
+			if not changed then
+				return
+			end
+
+			local payload: SyncPayload = {
+				type = "patch",
+				data = patch.diff(previousSnapshot, currentSnapshot, options.serializeArrays),
+			}
+
+			previousSnapshot = table.clone(currentSnapshot)
+			changed = false
+
+			for _, player in next, Players:GetPlayers() do
+				callback(player, payload)
+			end
+		end, options.interval or 0)
+
+		return function()
+			disconnect()
+
+			for _, unsubscribe in next, subscriptions do
+				unsubscribe()
+			end
+		end
+	end
+
+	function self:_sendPatch(player)
+		assert(sync, "connect() must be called before _sendPatch()")
+
+		if not changed then
+			return
+		end
+
+		local payload: SyncPayload = {
+			type = "patch",
+			data = patch.diff(previousSnapshot, currentSnapshot, options.serializeArrays),
+		}
+
+		previousSnapshot = table.clone(currentSnapshot)
+		changed = false
+
+		sync(player, payload)
+	end
+
+	return self
+end
+
+return server

packages/charm-sync/src/types.luau

@@ -0,0 +1,13 @@
+--[=[
+	A payload that can be sent from the server to the client to synchronize
+	state between the two.
+]=]
+export type SyncPayload = {
+	type: "init",
+	data: { [string | number]: any },
+} | {
+	type: "patch",
+	data: { [string | number]: any },
+}
+
+return nil

packages/charm-sync/src/validate.luau

@@ -0,0 +1,74 @@
+local SAFE_KEYS = { string = true, number = true }
+local SAFE_VALUES = { string = true, number = true, boolean = true, table = true, userdata = true, vector = true }
+
+local function isTableUnsafe(object: { [any]: any })
+	local keyType = nil
+	local objectSize = 0
+
+	-- All keys must have the same type
+	for key in next, object do
+		local currentType = type(key)
+
+		if not keyType and SAFE_KEYS[currentType] then
+			keyType = currentType
+		elseif keyType ~= currentType then
+			return true
+		end
+
+		objectSize += 1
+	end
+
+	-- If there are more keys than the length of the array, it's an array with
+	-- non-sequential keys.
+	if objectSize > #object and keyType == "number" then
+		return true
+	end
+
+	return false
+end
+
+--[=[
+	Validates a value to ensure it can be synced over a remote event.
+
+	@param value The value to validate.
+	@param key The key of the value in the table.
+	@error Throws an error if the value cannot be synced.
+]=]
+local function validate(value: any, key: any)
+	local typeOfKey = type(key)
+	local typeOfValue = type(value)
+
+	if not SAFE_KEYS[typeOfKey] then
+		error(`Invalid key type '{typeOfKey}' at key '{key}'`)
+	elseif not SAFE_VALUES[typeOfValue] then
+		error(`Invalid value type '{typeOfValue}' at key '{key}'`)
+	elseif typeOfValue == "table" then
+		if getmetatable(value) ~= nil then
+			error(`Cannot sync tables with metatables! Got {value} at key '{key}'`)
+		elseif isTableUnsafe(value) then
+			error(
+				`Cannot sync tables unsupported by remote events! The value has the key '{key}'.\n\n`
+					.. "This can be for the following reasons:\n"
+					.. "1. The object is an array with non-sequential keys\n"
+					.. "2. The object is a dictionary with mixed key types (e.g. string and number)\n\n"
+					.. "Read more: https://create.roblox.com/docs/scripting/events/remote#argument-limitations"
+			)
+		end
+	end
+
+	if typeOfValue == "number" then
+		if value ~= value then
+			error(`Cannot sync NaN at key '{key}'`)
+		elseif value == math.huge or value == -math.huge then
+			error(`Cannot sync infinity at key '{key}'`)
+		end
+	elseif typeOfKey == "number" then
+		if key == math.huge or key == -math.huge then
+			error("Cannot sync infinity as key")
+		elseif key ~= math.floor(key) then
+			error("Cannot sync non-integer number as key")
+		end
+	end
+end
+
+return validate

packages/charm-sync/wally.toml

@@ -0,0 +1,8 @@
+[package]
+name = "littensy/charm-sync"
+version = "0.1.1"
+registry = "https://github.com/UpliftGames/wally-index"
+realm = "shared"
+
+[dependencies]
+Charm = "littensy/charm@^0.8"

packages/charm/default.project.json

@@ -0,0 +1,6 @@
+{
+	"name": "Charm",
+	"tree": {
+		"$path": "src"
+	}
+}

packages/charm/package.json

@@ -0,0 +1,13 @@
+{
+	"name": "@rbxts/charm",
+	"version": "0.8.1",
+	"description": "An atomic state management library for Roblox",
+	"repository": "littensy/charm",
+	"license": "MIT",
+	"main": "src/init.luau",
+	"types": "src/index.d.ts",
+	"scripts": {
+		"prepare": "cp ../../LICENSE.md . && cp ../../README.md .",
+		"publish:wally": "wally publish"
+	}
+}

packages/charm/src/atom.luau

@@ -0,0 +1,42 @@
+local store = require(script.Parent.store)
+local types = require(script.Parent.types)
+type Atom<T> = types.Atom<T>
+type AtomOptions<T> = types.AtomOptions<T>
+
+--[=[
+	Creates a new atom with the given state.
+	
+	@param state The initial state.
+	@param options Optional configuration.
+	@return A new atom.
+]=]
+local function atom<T>(state: T, options: AtomOptions<T>?): Atom<T>
+	local equals = options and options.equals
+
+	local function atom(...)
+		if select("#", ...) == 0 then
+			local index = store.capturing.index
+
+			if index > 0 then
+				store.capturing.stack[index][atom] = true
+			end
+
+			return state
+		end
+
+		local nextState = store.peek(..., state)
+
+		if state ~= nextState and not (equals and equals(state, nextState)) then
+			state = nextState
+			store.notify(atom)
+		end
+
+		return state
+	end
+
+	store.listeners[atom] = setmetatable({}, { __mode = "v" })
+
+	return atom
+end
+
+return atom

packages/charm/src/computed.luau

@@ -0,0 +1,37 @@
+local atom = require(script.Parent.atom)
+local store = require(script.Parent.store)
+local types = require(script.Parent.types)
+type AtomOptions<T> = types.AtomOptions<T>
+type Selector<T> = types.Selector<T>
+
+--[=[
+	Creates a read-only atom that derives its state from one or more atoms.
+	Used to avoid unnecessary recomputations if multiple listeners depend on
+	the same atoms.
+
+	@param callback The function that produces the state.
+	@param options Optional configuration.
+	@return A new read-only atom.
+]=]
+local function computed<T>(callback: Selector<T>, options: AtomOptions<T>?): Selector<T>
+	local dependencies, state = store.capture(callback)
+	local computedAtom = atom(state, options)
+	local computedRef = setmetatable({ current = computedAtom }, { __mode = "v" })
+
+	local function listener()
+		local computedAtom = computedRef.current
+
+		if computedAtom then
+			store.disconnect(dependencies, listener)
+			dependencies, state = store.capture(callback)
+			store.connect(dependencies, listener, computedAtom)
+			computedAtom(state)
+		end
+	end
+
+	store.connect(dependencies, listener, computedAtom)
+
+	return computedAtom
+end
+
+return computed

packages/charm/src/effect.luau

@@ -0,0 +1,53 @@
+local store = require(script.Parent.store)
+
+type Cleanup = () -> ()
+
+--[=[
+	Runs the given callback immediately and whenever any atom it depends on
+	changes. Returns a cleanup function that unsubscribes the callback.
+	
+	@param callback The function to run.
+	@return A function that unsubscribes the callback.
+]=]
+local function effect(callback: (cleanup: Cleanup) -> Cleanup?): Cleanup
+	local dependencies = {}
+	local cleanup: Cleanup?
+	local disconnected = false
+	local disconnect
+
+	local function listener()
+		if cleanup then
+			cleanup()
+		end
+
+		store.disconnect(dependencies, listener)
+		dependencies, cleanup = store.capture(callback, disconnect)
+
+		if not disconnected then
+			store.connect(dependencies, listener)
+		end
+	end
+
+	function disconnect()
+		if disconnected then
+			return
+		end
+
+		disconnected = true
+		store.disconnect(dependencies, listener)
+
+		if cleanup then
+			cleanup()
+		end
+	end
+
+	dependencies, cleanup = store.capture(callback, disconnect)
+
+	if not disconnected then
+		store.connect(dependencies, listener)
+	end
+
+	return disconnect
+end
+
+return effect :: (callback: ((cleanup: Cleanup) -> ()) | ((cleanup: Cleanup) -> Cleanup?)) -> Cleanup

packages/charm/src/index.d.ts

@@ -0,0 +1,187 @@
+export = Charm;
+export as namespace Charm;
+
+type Cleanup = () => void;
+
+declare namespace Charm {
+	/**
+	 * A primitive state container that can be read from or written to. When
+	 * the state changes, all subscribers are notified.
+	 *
+	 * @param state The next state or a function that produces the next state.
+	 * @returns The current state.
+	 */
+	interface Atom<State> extends Selector<State> {
+		(nextState: State | ((prevState: State) => State)): State;
+	}
+
+	/**
+	 * A function that depends on one or more atoms and produces a value. Can be
+	 * used to derive state from atoms.
+	 *
+	 * @returns The current state.
+	 */
+	type Selector<State> = () => State;
+
+	/**
+	 * A function that depends on one or more atoms and produces a value. Can be
+	 * used to derive state from atoms.
+	 *
+	 * @deprecated Use `Selector<T>` instead.
+	 * @returns The current state.
+	 */
+	type Molecule<State> = Selector<State>;
+
+	/**
+	 * Infers the type of the state produced by the given function.
+	 */
+	type StateOf<T> = T extends Selector<infer State> ? State : never;
+
+	interface AtomOptions<State> {
+		/**
+		 * A function that determines whether the state has changed. By default,
+		 * a strict equality check (`===`) is used.
+		 */
+		equals?: (prev: State, next: State) => boolean;
+	}
+
+	/**
+	 * Creates a new atom with the given state.
+	 *
+	 * @param state The initial state.
+	 * @param options Optional configuration.
+	 * @returns A new atom.
+	 */
+	function atom<State>(state: State, options?: AtomOptions<State>): Atom<State>;
+
+	// Overload for no arguments
+	function atom<State>(state?: State, options?: AtomOptions<State>): Atom<State | undefined>;
+
+	/**
+	 * Creates a read-only atom that derives its state from one or more atoms.
+	 * Used to avoid unnecessary recomputations if multiple listeners depend on
+	 * the same atoms.
+	 *
+	 * @param callback The function that produces the state.
+	 * @param options Optional configuration.
+	 * @returns A new read-only atom.
+	 */
+	function computed<State>(callback: Selector<State>, options?: AtomOptions<State>): Selector<State>;
+
+	/**
+	 * Subscribes to changes in the given atom or selector. The callback is
+	 * called with the current state and the previous state immediately after a
+	 * change occurs.
+	 *
+	 * @param callback The atom or selector to subscribe to.
+	 * @param listener The function to call when the state changes.
+	 * @returns A function that unsubscribes the callback.
+	 */
+	function subscribe<State>(callback: Selector<State>, listener: (state: State, prev: State) => void): Cleanup;
+
+	/**
+	 * Runs the given callback immediately and whenever any atom it depends on
+	 * changes. Returns a cleanup function that unsubscribes the callback.
+	 *
+	 * @param callback The function to run.
+	 * @returns A function that unsubscribes the callback.
+	 */
+	function effect(callback: () => Cleanup | void): Cleanup;
+
+	/**
+	 * Returns the result of the function without subscribing to changes. If a
+	 * non-function value is provided, it is returned as is.
+	 *
+	 * @param callback The atom or selector to get the state of.
+	 * @param args Arguments to pass to the function.
+	 * @returns The current state.
+	 */
+	function peek<State, Args extends unknown[]>(callback: State | ((...args: Args) => State), ...args: Args): State;
+
+	/**
+	 * Returns whether the given value is an atom.
+	 *
+	 * @param value The value to check.
+	 * @returns `true` if the value is an atom, otherwise `false`.
+	 */
+	function isAtom(value: unknown): value is Atom<any>;
+
+	/**
+	 * Runs the given function and schedules listeners to be notified only once
+	 * after the function has completed. Useful for batching multiple changes.
+	 *
+	 * @param callback The function to run.
+	 */
+	function batch(callback: () => void): void;
+
+	/**
+	 * Captures all atoms that are read during the function call and returns them
+	 * along with the result of the function. Useful for tracking dependencies.
+	 *
+	 * @param callback The function to run.
+	 * @returns A tuple containing the captured atoms and the result of the function.
+	 */
+	function capture<State>(callback: Selector<State>): LuaTuple<[dependencies: Set<Atom<unknown>>, state: State]>;
+
+	/**
+	 * Notifies all subscribers of the given atom that the state has changed.
+	 * Mainly for running effects, since subscriptions check for equality.
+	 *
+	 * @param atom The atom to notify.
+	 */
+	function notify<State>(atom: Atom<State>): void;
+
+	/**
+	 * Creates an instance of `factory` for each item in the atom's state, and
+	 * cleans up the instance when the item is removed. Returns a cleanup function
+	 * that unsubscribes all instances.
+	 *
+	 * @param callback The atom or selector to observe.
+	 * @param factory The function that tracks the lifecycle of each item.
+	 * @returns A function that unsubscribes all instances.
+	 */
+	function observe<Item>(
+		callback: Selector<readonly Item[]>,
+		factory: (item: Item, index: number) => Cleanup | void,
+	): Cleanup;
+
+	function observe<Key, Item>(
+		callback: Selector<Map<Key, Item> | ReadonlyMap<Key, Item>>,
+		factory: (item: Item, key: Key) => Cleanup | void,
+	): Cleanup;
+
+	function observe<Key extends string | number | symbol, Item>(
+		callback: Selector<{ readonly [P in Key]: Item }>,
+		factory: (item: Item, key: Key) => Cleanup | void,
+	): Cleanup;
+
+	/**
+	 * Maps each entry in the atom's state to a new key-value pair. If the `mapper`
+	 * function returns `undefined`, the entry is omitted from the resulting map.
+	 * When the atom changes, the `mapper` is called for each entry in the state
+	 * to compute the new state.
+	 *
+	 * @param callback The atom or selector to map.
+	 * @param mapper The function that maps each entry.
+	 * @returns A new atom with the mapped state.
+	 */
+	function mapped<V0, K1, V1>(
+		callback: Selector<readonly V0[]>,
+		mapper: (value: V0, index: number) => LuaTuple<[value: V1 | undefined, key: K1]>,
+	): Selector<ReadonlyMap<K1, V1>>;
+
+	function mapped<V0, V1>(
+		callback: Selector<readonly V0[]>,
+		mapper: (value: V0, index: number) => V1,
+	): Selector<readonly V1[]>;
+
+	function mapped<K0, V0, K1 = K0, V1 = V0>(
+		callback: Selector<Map<K0, V0> | ReadonlyMap<K0, V0>>,
+		mapper: (value: V0, key: K0) => LuaTuple<[value: V1 | undefined, key: K1]> | V1,
+	): Selector<ReadonlyMap<K1, V1>>;
+
+	function mapped<K0 extends string | number | symbol, V0, K1 = K0, V1 = V0>(
+		callback: Selector<{ readonly [P in K0]: V0 }>,
+		mapper: (value: V0, key: K0) => LuaTuple<[value: V1 | undefined, key: K1]> | V1,
+	): Selector<ReadonlyMap<K1, V1>>;
+}

packages/charm/src/init.luau

@@ -0,0 +1,27 @@
+local atom = require(script.atom)
+local computed = require(script.computed)
+local effect = require(script.effect)
+local mapped = require(script.mapped)
+local observe = require(script.observe)
+local store = require(script.store)
+local subscribe = require(script.subscribe)
+local types = require(script.types)
+
+export type Atom<State> = types.Atom<State>
+export type Selector<State> = types.Selector<State>
+export type Molecule<State> = types.Selector<State>
+export type SyncPayload = types.SyncPayload
+
+return {
+	atom = atom,
+	computed = computed,
+	effect = effect,
+	mapped = mapped,
+	observe = observe,
+	subscribe = subscribe,
+	batch = store.batch,
+	capture = store.capture,
+	isAtom = store.isAtom,
+	notify = store.notify,
+	peek = store.peek,
+}

packages/charm/src/mapped.luau

@@ -0,0 +1,71 @@
+local atom = require(script.Parent.atom)
+local store = require(script.Parent.store)
+local subscribe = require(script.Parent.subscribe)
+local types = require(script.Parent.types)
+type Atom<T> = types.Atom<T>
+type Selector<T> = types.Selector<T>
+
+type Map =
+	(<K0, V0, K1, V1>(fn: Selector<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1)) -> Selector<{ [K1]: V1 }>)
+	& (<K0, V0, V1>(fn: Selector<{ [K0]: V0 }>, mapper: (V0, K0) -> V1?) -> Selector<{ [K0]: V1 }>)
+	& (<K0, V0, K1, V1>(fn: Selector<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1?)) -> Selector<{ [K1]: V1 }>)
+
+--[=[
+	Maps each entry in the atom's state to a new key-value pair. If the `mapper`
+	function returns `undefined`, the entry is omitted from the resulting map.
+	When the atom changes, the `mapper` is called for each entry in the state
+	to compute the new state.
+	
+	@param callback The atom or selector to map.
+	@param mapper The function that maps each entry.
+	@return A new atom with the mapped state.
+]=]
+local function mapped<K0, V0, K1, V1>(callback: Selector<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1?)): Selector<{ [K1]: V1 }>
+	local mappedAtom = atom({})
+	local mappedAtomRef = setmetatable({ current = mappedAtom }, { __mode = "v" })
+	local prevMappedItems: { [K1]: V1 } = {}
+	local unsubscribe
+
+	local function listener(items: { [K0]: V0 })
+		local mappedAtom = mappedAtomRef.current
+
+		if not mappedAtom then
+			return unsubscribe()
+		end
+
+		local mappedItems = table.clone(mappedAtom())
+		local mappedKeys = {}
+
+		-- TODO: Only call mapper if the item has changed.
+		for key, item in next, items do
+			local newItem, newKey = mapper(item, key)
+			if newKey == nil then
+				newKey = key :: any
+			end
+			if mappedItems[newKey :: K1] ~= newItem then
+				mappedItems[newKey :: K1] = newItem :: V1
+			else
+				mappedKeys[newKey] = key
+			end
+		end
+
+		for key in next, prevMappedItems do
+			if mappedKeys[key] == nil and mappedItems[key] == prevMappedItems[key] then
+				mappedItems[key] = nil
+			end
+		end
+
+		prevMappedItems = mappedItems
+		mappedAtom(mappedItems)
+	end
+
+	unsubscribe = subscribe(callback, listener)
+
+	store.peek(function(): ()
+		listener(callback())
+	end)
+
+	return mappedAtom
+end
+
+return mapped :: Map

packages/charm/src/observe.luau

@@ -0,0 +1,50 @@
+local store = require(script.Parent.store)
+local subscribe = require(script.Parent.subscribe)
+local types = require(script.Parent.types)
+type Selector<T> = types.Selector<T>
+
+local function noop() end
+
+--[=[
+	Creates an instance of `factory` for each item in the atom's state, and
+	cleans up the instance when the item is removed. Returns a cleanup function
+	that unsubscribes all instances.
+	
+	@param callback The atom or selector to observe.
+	@param factory The function that tracks the lifecycle of each item.
+	@return A function that unsubscribes all instances.
+]=]
+local function observe<K, V>(callback: Selector<{ [K]: V }>, factory: (value: V, key: K) -> (() -> ())?): () -> ()
+	local connections: { [K]: () -> () } = {}
+
+	local function listener(state: { [K]: V })
+		for key, disconnect in next, connections do
+			if state[key] == nil then
+				connections[key] = nil
+				disconnect()
+			end
+		end
+
+		for key, value in next, state do
+			if not connections[key] then
+				connections[key] = factory(value, key) or noop
+			end
+		end
+	end
+
+	local unsubscribe = subscribe(callback, listener)
+
+	store.peek(function(): ()
+		listener(callback())
+	end)
+
+	return function()
+		unsubscribe()
+		for _, disconnect in next, connections do
+			disconnect()
+		end
+		table.clear(connections)
+	end
+end
+
+return observe

packages/charm/src/store.luau

@@ -0,0 +1,214 @@
+local types = require(script.Parent.types)
+type Atom<T> = types.Atom<T>
+type Set<T> = types.Set<T>
+type WeakMap<K, V> = types.WeakMap<K, V>
+
+local __DEV__ = _G.__DEV__
+
+local listeners: WeakMap<Atom<any>, WeakMap<() -> (), unknown>> = setmetatable({}, { __mode = "k" })
+
+local batched: Set<() -> ()> = {}
+local batching = false
+
+local capturing = {
+	stack = {} :: { Set<Atom<any>> },
+	index = 0,
+}
+
+--[=[
+	Calls the given function and returns the result. If the function yields or
+	throws an error, the thread is closed and an error is thrown. Regardless of
+	the outcome, the `finally` function is called to clean up any resources.
+	
+	@param callback The function to run.
+	@param finally Cleanup logic to run before error handling.
+	@param ... Arguments to pass to the callback.
+	@return The result of the callback.
+]=]
+local function try<T, U...>(callback: (U...) -> T | any, finally: (() -> ())?, ...: U...): T
+	if __DEV__ then
+		local thread = coroutine.create(callback)
+		local success, result = coroutine.resume(thread, ...)
+
+		if finally then
+			finally()
+		end
+
+		if coroutine.status(thread) == "suspended" then
+			local source, line, name = debug.info(callback, "sln")
+
+			coroutine.close(thread)
+
+			error(
+				"Yielding is not allowed in atom functions. Consider wrapping this code in a Promise or task.defer instead."
+					.. `\nFunction defined at: {source}:{line}`
+					.. if name == "" then "" else ` function {name}`
+			)
+		elseif not success then
+			local source, line, name = debug.info(callback, "sln")
+
+			error(
+				"An error occurred while running an atom function"
+					.. `\nFunction defined at: {source}:{line}`
+					.. (if name == "" then "" else ` function {name}`)
+					.. `\nError: {result}`
+			)
+		end
+
+		return result
+	end
+
+	if not finally then
+		return callback(...)
+	end
+
+	local success, result = pcall(callback, ...)
+
+	finally()
+	assert(success, result)
+
+	return result
+end
+
+--[=[
+	Returns whether the given value is an atom.
+
+	@param value The value to check.
+	@return `true` if the value is an atom, otherwise `false`.
+]=]
+local function isAtom(value: any): boolean
+	return not not (value and listeners[value])
+end
+
+--[=[
+	Notifies all subscribers of the given atom that the state has changed.
+	
+	@param atom The atom to notify.
+]=]
+local function notify(atom: Atom<any>)
+	if batching then
+		for listener in next, listeners[atom] do
+			batched[listener] = true
+		end
+		return
+	end
+
+	for listener in next, table.clone(listeners[atom]) do
+		try(listener)
+	end
+end
+
+--[=[
+	Returns the result of the function without subscribing to changes. If a
+	non-function value is provided, it is returned as is.
+	
+	@param callback The atom or selector to get the state of.
+	@param args Arguments to pass to the function.
+	@return The current state.
+]=]
+local function peek<T, U...>(callback: ((U...) -> T) | T, ...: U...): T
+	if type(callback) ~= "function" then
+		return callback
+	end
+
+	if capturing.index == 0 then
+		return callback(...)
+	end
+
+	capturing.index += 1
+	capturing.stack[capturing.index] = {}
+
+	local result = try(callback, function()
+		capturing.stack[capturing.index] = nil
+		capturing.index -= 1
+	end, ...)
+
+	return result
+end
+
+--[=[
+	Captures all atoms that are read during the function call and returns them
+	along with the result of the function. Useful for tracking dependencies.
+	
+	@param callback The function to run.
+	@return A tuple containing the captured atoms and the result of the function.
+]=]
+local function capture<T, U...>(callback: (U...) -> T, ...: U...): (Set<Atom<any>>, T)
+	-- If the callback is an atom, return it immediately
+	if listeners[callback :: any] then
+		return { [callback :: any] = true }, peek(callback)
+	end
+
+	local dependencies: Set<Atom<any>> = {}
+
+	capturing.index += 1
+	capturing.stack[capturing.index] = dependencies
+
+	local result = try(callback, function()
+		capturing.stack[capturing.index] = nil
+		capturing.index -= 1
+	end, ...)
+
+	return dependencies, result
+end
+
+--[=[
+	Runs the given function and schedules listeners to be notified only once
+	after the function has completed. Useful for batching multiple changes.
+	
+	@param callback The function to run.
+]=]
+local function batch(callback: () -> ())
+	if batching then
+		return callback()
+	end
+
+	batching = true
+
+	try(callback, function()
+		batching = false
+	end)
+
+	for listener in next, batched do
+		try(listener)
+	end
+
+	table.clear(batched)
+end
+
+--[=[
+	Subscribes the listener to the changes of the given atoms.
+	
+	@param atoms The atoms to listen to.
+	@param listener The function to call when the atoms change.
+	@param ref Optionally bind the lifetime of the listener to a value.
+]=]
+local function connect(atoms: Set<Atom<any>>, listener: () -> (), ref: unknown?)
+	for atom in next, atoms do
+		listeners[atom][listener] = ref or true
+	end
+end
+
+--[=[
+	Unsubscribes the listener from every atom it was connected to.
+	
+	@param atoms The atoms to stop listening to.
+	@param listener The function to stop calling when the atoms change.
+]=]
+local function disconnect(atoms: Set<Atom<any>>, listener: () -> ())
+	for atom in next, atoms do
+		listeners[atom][listener] = nil
+	end
+end
+
+return {
+	listeners = listeners,
+	capturing = capturing,
+	isAtom = isAtom,
+	notify = notify,
+	capture = capture,
+	batch = batch,
+	peek = peek,
+	connect = connect,
+	disconnect = disconnect,
+}

packages/charm/src/subscribe.luau

@@ -0,0 +1,43 @@
+local store = require(script.Parent.store)
+local types = require(script.Parent.types)
+type Selector<T> = types.Selector<T>
+
+--[=[
+	Subscribes to changes in the given atom or selector. The callback is
+	called with the current state and the previous state immediately after a
+	change occurs.
+	
+	@param callback The atom or selector to subscribe to.
+	@param listener The function to call when the state changes.
+	@return A function that unsubscribes the callback.
+]=]
+local function subscribe<T>(callback: Selector<T>, listener: (state: T, prev: T) -> ()): () -> ()
+	local dependencies, state = store.capture(callback)
+	local disconnected = false
+
+	local function handler()
+		local prevState = state
+
+		store.disconnect(dependencies, handler)
+		dependencies, state = store.capture(callback)
+
+		if not disconnected then
+			store.connect(dependencies, handler)
+		end
+
+		if state ~= prevState then
+			listener(state, prevState)
+		end
+	end
+
+	store.connect(dependencies, handler)
+
+	return function()
+		if not disconnected then
+			disconnected = true
+			store.disconnect(dependencies, handler)
+		end
+	end
+end
+
+return subscribe

packages/charm/src/types.luau

@@ -0,0 +1,43 @@
+export type Set<T> = { [T]: true }
+
+export type WeakMap<K, V> = typeof(setmetatable({} :: { [K]: V }, { __mode = "k" }))
+
+--[=[
+	A primitive state container that can be read from and written to. When the
+	state changes, all subscribers are notified.
+
+	@param state The next state or a function that produces the next state.
+	@return The current state, if no arguments are provided.
+]=]
+export type Atom<T> = (state: (T | (T) -> T)?) -> T
+
+--[=[
+	A function that depends on one or more atoms and produces a state. Can be
+	used to derive state from atoms.
+
+	@template State The type of the state.
+	@return The current state.
+]=]
+export type Selector<T> = () -> T
+
+--[=[
+	Optional configuration for creating an atom.
+]=]
+export type AtomOptions<T> = {
+	--[=[
+		A function that determines whether the state has changed. By default,
+		a strict equality check (`===`) is used.
+	]=]
+	equals: (prev: T, next: T) -> boolean,
+}
+
+--[=[
+	A payload that can be sent from the server to the client to synchronize
+	state between the two.
+]=]
+export type SyncPayload = {
+	type: "patch" | "init",
+	data: { [any]: any },
+}
+
+return nil

packages/charm/wally.toml

@@ -0,0 +1,7 @@
+[package]
+name = "littensy/charm"
+version = "0.8.1"
+registry = "https://github.com/UpliftGames/wally-index"
+realm = "shared"
+
+[dependencies]

packages/react/default.project.json

@@ -0,0 +1,6 @@
+{
+	"name": "ReactCharm",
+	"tree": {
+		"$path": "src"
+	}
+}

packages/react/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@rbxts/react-charm",
+	"version": "0.1.1",
+	"description": "React bindings for Charm",
+	"repository": "littensy/charm",
+	"license": "MIT",
+	"main": "src/init.luau",
+	"types": "src/index.d.ts",
+	"scripts": {
+		"prepare": "cp ../../LICENSE.md . && cp ../../README.md .",
+		"publish:wally": "wally publish"
+	},
+	"dependencies": {
+		"@rbxts/charm": "workspace:*"
+	},
+	"peerDependencies": {
+		"@rbxts/react": "*"
+	}
+}

packages/react/src/index.d.ts

@@ -0,0 +1,15 @@
+import { Selector } from "@rbxts/charm";
+
+/**
+ * A hook that subscribes to changes in the given atom or selector. The
+ * component is re-rendered whenever the state changes.
+ *
+ * If the `dependencies` array is provided, the subscription to the atom or
+ * selector is re-created whenever the dependencies change. Otherwise, the
+ * subscription is created once when the component is mounted.
+ *
+ * @param callback The atom or selector to subscribe to.
+ * @param dependencies An array of values that the subscription depends on.
+ * @returns The current state.
+ */
+export function useAtom<State>(callback: Selector<State>, dependencies?: unknown[]): State;

packages/react/src/init.luau

@@ -0,0 +1,31 @@
+local Charm = require(script.Parent.Charm)
+local React = if script.Parent:FindFirstChild("react")
+	then require(script.Parent.react) :: never
+	else require(script.Parent.React)
+
+--[=[
+	A hook that subscribes to changes in the given atom or selector. The
+	component is re-rendered whenever the state changes.
+	
+	If the `dependencies` array is provided, the subscription to the atom or
+	selector is re-created whenever the dependencies change. Otherwise, the
+	subscription is created once when the component is mounted.
+	
+	@param callback The atom or selector to subscribe to.
+	@param dependencies An array of values that the subscription depends on.
+	@return The current state.
+]=]
+local function useAtom<State>(callback: Charm.Selector<State>, dependencies: { any }?): State
+	local state, setState = React.useState(callback)
+
+	React.useEffect(function()
+		setState(callback())
+		return Charm.subscribe(callback, setState)
+	end, dependencies or {})
+
+	return state
+end
+
+return {
+	useAtom = useAtom,
+}

packages/react/wally.toml

@@ -0,0 +1,9 @@
+[package]
+name = "littensy/react-charm"
+version = "0.1.1"
+registry = "https://github.com/UpliftGames/wally-index"
+realm = "shared"
+
+[dependencies]
+Charm = "littensy/charm@^0.8"
+React = "jsdotlua/react@^17"

packages/vide/default.project.json

@@ -0,0 +1,6 @@
+{
+	"name": "VideCharm",
+	"tree": {
+		"$path": "src"
+	}
+}

packages/vide/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@rbxts/vide-charm",
+	"version": "0.1.1",
+	"description": "Vide bindings for Charm",
+	"repository": "littensy/charm",
+	"license": "MIT",
+	"main": "src/init.luau",
+	"types": "src/index.d.ts",
+	"scripts": {
+		"prepare": "cp ../../LICENSE.md . && cp ../../README.md .",
+		"publish:wally": "wally publish"
+	},
+	"dependencies": {
+		"@rbxts/charm": "workspace:*"
+	},
+	"peerDependencies": {
+		"@rbxts/vide": "*"
+	}
+}

packages/vide/src/index.d.ts

@@ -0,0 +1,9 @@
+import { Selector } from "@rbxts/charm";
+
+/**
+ * Subscribes to the state of an atom and returns a Vide source.
+ *
+ * @param callback The atom or selector to subscribe to.
+ * @returns The reactive source.
+ */
+export function useAtom<T>(callback: Selector<T>): () => T;

packages/vide/src/init.luau

@@ -0,0 +1,27 @@
+local Charm = require(script.Parent.Charm)
+local Vide = if script.Parent:FindFirstChild("vide")
+	then require(script.Parent.vide.src) :: never
+	else require(script.Parent.Vide)
+
+--[=[
+	Subscribes to the state of an atom and returns a Vide source.
+	
+	@param callback The atom or selector to subscribe to.
+	@return The reactive source.
+]=]
+local function useAtom<State>(callback: () -> State): () -> State
+	local state = Vide.source(callback())
+	local unsubscribe = Charm.subscribe(callback, function(value)
+		task.spawn(function()
+			state(value)
+		end)
+	end)
+
+	Vide.cleanup(unsubscribe)
+
+	return state
+end
+
+return {
+	useAtom = useAtom,
+}

packages/vide/wally.toml

@@ -0,0 +1,9 @@
+[package]
+name = "littensy/vide-charm"
+version = "0.1.1"
+registry = "https://github.com/UpliftGames/wally-index"
+realm = "shared"
+
+[dependencies]
+Charm = "littensy/charm@^0.8"
+Vide = "centau/vide@^0.3"