diff --git a/README.md b/README.md index 2f447fc..ee858a4 100644 --- a/README.md +++ b/README.md @@ -47,55 +47,37 @@ Charm = "littensy/charm@VERSION" ## 📚 Documentation -### Core +### `atom(state)` -#### `atom(state)` +### `derive(atom, comparator?)` -#### `derive(...atoms, combiner)` +### `subscribe(atom, listener)` -#### `subscribe(atom, listener)` +### `effect(callback)` -#### `observe(atom, observer)` +### `observe(atom, observer)` -#### `mapAtom(atom, mapper)` +### `mapAtom(atom, mapper)` -### Atom +## 📚 React API -#### `Atom(state?)` +### `useAtom(atom, selector?)` -#### `Atom.get(selector?)` +### `useAtomState(atom)` -#### `Atom.set(state)` +### `useSetAtom(atom)` -#### `Atom.memo(areEqual)` +## 📚 Sync API -#### `Atom.readonly()` +### `sync.client(options)` -#### `Atom.writable(onSet?)` +### `sync.server(options)` -#### `Atom.named(label)` +### `Client.sync(payload)` -#### `Atom.unmount()` +### `Server.onSync(callback)` -### React - -#### `useAtom(atom, selector?)` - -#### `useAtomState(atom)` - -#### `useSetAtom(atom)` - -### Sync - -#### `sync.client(options)` - -#### `Client.sync(payload)` - -#### `sync.server(options)` - -#### `Server.onSync(callback)` - -#### `Server.hydrate(player)` +### `Server.hydrate(player)` ## 🚀 Examples @@ -105,7 +87,7 @@ Charm = "littensy/charm@VERSION" import { atom, derive, subscribe } from "@rbxts/charm"; const counterAtom = atom(0); -const doubleCounterAtom = derive(counterAtom, (counter) => counter * 2); +const doubleCounterAtom = derive(() => counterAtom() * 2); subscribe(doubleCounterAtom, (value) => { print(value); @@ -137,12 +119,6 @@ function Counter() { } ``` -## 🙋 Concerns - -In Jotai, `atom()` returns an [atom config](https://jotai.org/docs/core/atom), and its state is managed entirely by the Provider. However, in Charm, `atom()` returns something closer to a store, and its state is managed by the atom itself. - -Charm does this for simplicity in use cases outside of React, but this might go against Jotai's focus on pure functional programming. More insight is needed to determine if this is a good idea. - ---

diff --git a/src/__tests__/atom.spec.luau b/src/__tests__/atom.spec.luau index c41fa63..78cfd1b 100644 --- a/src/__tests__/atom.spec.luau +++ b/src/__tests__/atom.spec.luau @@ -1,4 +1,5 @@ local atom = require(script.Parent.Parent.atom) +local store = require(script.Parent.Parent.store) return function() it("updates state", function() @@ -14,10 +15,10 @@ return function() it("calls listeners", function() local source = atom(1) local value - local function listener(state) - value = state + local function listener() + value = source() end - source.listeners[listener] = true + store.listeners[source][listener] = true source(2) expect(value).to.equal(2) end) @@ -31,9 +32,9 @@ return function() local function listener() inner += 1 end - source.listeners[listener] = true + store.listeners[source][listener] = true end - source.listeners[listener] = true + store.listeners[source][listener] = true source(2) expect(outer).to.equal(1) expect(inner).to.equal(0) @@ -41,45 +42,4 @@ return function() expect(outer).to.equal(2) expect(inner).to.equal(1) end) - - it("can be readonly", function() - local readonly = atom(1):readonly() - - expect(function() - (readonly :: any)(2) - end).to.throw() - - local writable = readonly:writable() - - writable(2) - expect(writable()).to.equal(2) - end) - - it("calls the setter", function() - local source = atom(1):writable(function(_, value: number) - return value + 1 - end) - source(1) - expect(source()).to.equal(2) - end) - - it("cancels if setter returns nil", function() - local source = atom(1):writable(function(value: number) - return if value == 2 then nil else value - end) - source(2) - expect(source()).to.equal(1) - source(3) - expect(source()).to.equal(3) - end) - - it("can be memoized", function() - local source = atom(1):memo(function(prev, next) - return next < prev - end) - source(2) - expect(source()).to.equal(2) - source(1) - expect(source()).to.equal(2) - end) end diff --git a/src/__tests__/benchmarks/atom.bench.luau b/src/__tests__/benchmarks/atom.bench.luau index 2bca275..7746117 100644 --- a/src/__tests__/benchmarks/atom.bench.luau +++ b/src/__tests__/benchmarks/atom.bench.luau @@ -6,48 +6,39 @@ local Package = game:GetService("ReplicatedStorage").Packages.charm local atom = require(Package.atom) local derive = require(Package.derive) -return { - ParameterGenerator = function() - return atom({ count = 0 }) +local function parameterGenerator() + return atom({ count = 0 }) +end + +local benchmarks = { + atom = function(_, source: any) + for _ = 1, 500 do + source({ count = math.random(1, 2) }) + end end, - Functions = { - atom = function(_, source: any) - for _ = 1, 500 do - source({ count = math.random(1, 2) }) - end - end, + derived = function(_, source: any) + derive(function() + return { count = 2 * source().count } + end) + for _ = 1, 500 do + source({ count = math.random(1, 2) }) + end + end, - derived = function(_, source: any) - derive(source, function(state) - return { count = 2 * state.count } - end) - for _ = 1, 500 do - source({ count = math.random(1, 2) }) - end - end, - - derived_memo = function(_, source: any) - source:memo(function(previous, current) - return previous.count == current.count - end) - derive(source, function(state) - return { count = 2 * state.count } - end) - for _ = 1, 500 do - source({ count = math.random(1, 2) }) - end - end, - - derived_writable = function(_, source: any) - local derived = derive(source, function(state) - return { count = 2 * state.count } - end):writable(function(update) - source({ count = 0.5 * update.count }) - end) - for _ = 1, 500 do - derived({ count = 2 * math.random(1, 2) }) - end - end, - }, + derived_memo = function(_, source: any) + derive(function() + return { count = 2 * source().count } + end, function(previous, current) + return previous.count == current.count + end) + for _ = 1, 500 do + source({ count = math.random(1, 2) }) + end + end, +} + +return { + ParameterGenerator = parameterGenerator, + Functions = benchmarks, } diff --git a/src/__tests__/derive.spec.luau b/src/__tests__/derive.spec.luau index 00b60a2..b7c65f0 100644 --- a/src/__tests__/derive.spec.luau +++ b/src/__tests__/derive.spec.luau @@ -1,64 +1,53 @@ local atom = require(script.Parent.Parent.atom) local derive = require(script.Parent.Parent.derive) +local store = require(script.Parent.Parent.store) return function() - it("derives from dependencies", function() - local a = atom(1) - local b = atom(2) - local sum = derive(a, b, function(a: number, b: number) - return a + b - end) - expect(sum()).to.equal(3) - a(2) - expect(sum()).to.equal(4) - b(3) - expect(sum()).to.equal(5) - expect(function() - (sum :: any)(2) - end).to.throw() - end) - it("memoizes the result", function() local calls = 0 - local source = atom(1) - local double = derive(source, function(value: number) + local a = atom(1) + local b = atom(2) + local double = derive(function() calls += 1 - return value * 2 + return a() * b() end) expect(calls).to.equal(1) - source(1) + a(1) expect(calls).to.equal(1) - source(2) + a(2) expect(calls).to.equal(2) + b(3) + expect(calls).to.equal(3) double() - expect(calls).to.equal(2) + expect(calls).to.equal(3) end) - it("can be a dependency", function() + it("takes a custom comparator", function() local source = atom(1) - local double = derive(source, function(value: number) - return value * 2 + local derived = derive(function() + return source() + end, function(prev, next) + return next < prev end) - local quadruple = derive(double, function(value: number) - return value * 2 + source(2) + expect(derived()).to.equal(2) + source(1) + expect(derived()).to.equal(2) + end) + + it("can be nested", function() + local source = atom(1) + local double = derive(function() + return source() * 2 + end) + local quadruple = derive(function() + return double() * 2 end) expect(quadruple()).to.equal(4) source(2) expect(quadruple()).to.equal(8) end) - it("allows custom setter", function() - local source = atom(1) - local double = derive(source, function(value: number) - return value * 2 - end):writable(function(update: number) - source(update / 2) - end) - double(4) - expect(source()).to.equal(2) - expect(double()).to.equal(4) - end) - it("garbage collects", function() -- large values coerce the garbage collector to run local source = atom(string.rep("x", 1e5)) @@ -66,7 +55,7 @@ return function() local function listenersDecreased() local count = 0 - for _ in source.listeners do + for _ in pairs(store.listeners[source]) do count += 1 end max = math.max(max, count) @@ -74,11 +63,11 @@ return function() end for index = 1, 500 do - derive(source, function(value) - return string.upper(value) + derive(function() + return string.upper(source()) end) if index % 50 == 0 then - -- derived atoms check if they are collected when they are updated + -- derived atoms should be collected when memory is stressed source(source() .. "x") task.wait() end @@ -89,14 +78,4 @@ return function() error("None of the derived atoms were collected") end) - - it("unmounts from parent atom", function() - local source = atom(1) - local derived = derive(source, function(value) - return value - end) - expect((next(source.listeners))).to.be.ok() - derived:unmount() - expect((next(source.listeners))).to.never.be.ok() - end) end diff --git a/src/__tests__/effect.spec.luau b/src/__tests__/effect.spec.luau new file mode 100644 index 0000000..d1b0337 --- /dev/null +++ b/src/__tests__/effect.spec.luau @@ -0,0 +1,30 @@ +local atom = require(script.Parent.Parent.atom) +local effect = require(script.Parent.Parent.effect) + +return function() + it("runs on state change", function() + local a = atom(0) + local b = atom(0) + local current + local unsubscribe = effect(function() + current = a() + b() + end) + + expect(current).to.equal(0) + + for index = 1, 3 do + a(index) + expect(current).to.equal(index) + end + + for index = 1, 3 do + b(index) + expect(current).to.equal(a() + index) + end + + unsubscribe() + a(4) + + expect(current).to.equal(6) + end) +end diff --git a/src/__tests__/init.spec.luau b/src/__tests__/init.spec.luau index c37cf45..a7878dc 100644 --- a/src/__tests__/init.spec.luau +++ b/src/__tests__/init.spec.luau @@ -1,4 +1,4 @@ -local reference = require(script.Parent.Parent.utils.reference) +local store = require(script.Parent.Parent.store) return function() local previous = _G.__DEV__ @@ -12,6 +12,6 @@ return function() end) afterEach(function() - reference.clear() + table.clear(store.listeners :: any) end) end diff --git a/src/__tests__/mapAtom.spec.luau b/src/__tests__/mapAtom.spec.luau index 05ec132..4b68b5c 100644 --- a/src/__tests__/mapAtom.spec.luau +++ b/src/__tests__/mapAtom.spec.luau @@ -1,6 +1,7 @@ local atom = require(script.Parent.Parent.atom) local mapAtom = require(script.Parent.Parent.mapAtom) local observe = require(script.Parent.Parent.observe) +local store = require(script.Parent.Parent.store) return function() it("returns mapped atoms", function() @@ -10,7 +11,7 @@ return function() end) local updates = 0 - mappedAtom.listeners[function() + store.listeners[mappedAtom][function() updates += 1 end] = true @@ -67,7 +68,7 @@ return function() local added = 0 local deleted = 0 - local _, flush = observe(mappedAtom, function(item, key) + observe(mappedAtom, function(item, key) expect(item).to.equal(itemsAtom()[key]) added += 1 @@ -81,25 +82,13 @@ return function() expect(deleted).to.equal(0) itemsAtom({ itemsAtom()[1], itemsAtom()[3] }) - flush() expect(added).to.equal(3) expect(deleted).to.equal(1) itemsAtom({}) - flush() expect(added).to.equal(3) expect(deleted).to.equal(3) end) - - it("unmounts from parent atom", function() - local itemsAtom = atom({}) - local mappedAtom = mapAtom(itemsAtom, function(item, key) - return item, key - end) - expect((next(itemsAtom.listeners))).to.be.ok() - mappedAtom:unmount() - expect((next(itemsAtom.listeners))).to.never.be.ok() - end) end diff --git a/src/__tests__/observe.spec.luau b/src/__tests__/observe.spec.luau index 79e8953..a4e6b63 100644 --- a/src/__tests__/observe.spec.luau +++ b/src/__tests__/observe.spec.luau @@ -6,7 +6,7 @@ return function() local itemsAtom = atom({ "a", "b", "c" }) local state = {} - local cleanup, flush = observe(itemsAtom, function(item, key) + local cleanup = observe(itemsAtom, function(item, key) state[key] = item return function() state[key] = nil @@ -14,14 +14,13 @@ return function() end) for key = 1, 3 do - expect(state[key]).to.equal(itemsAtom:get()[key]) + expect(state[key]).to.equal(itemsAtom()[key]) end - itemsAtom:set({ [4] = "d", [5] = "e", [6] = "f" }) - flush() + itemsAtom({ [4] = "d", [5] = "e", [6] = "f" }) for key = 1, 6 do - expect(state[key]).to.equal(itemsAtom:get()[key]) + expect(state[key]).to.equal(itemsAtom()[key]) end cleanup() diff --git a/src/__tests__/react/helpers/renderHook.luau b/src/__tests__/react/helpers/renderHook.luau index 1714a66..020b2ae 100644 --- a/src/__tests__/react/helpers/renderHook.luau +++ b/src/__tests__/react/helpers/renderHook.luau @@ -2,7 +2,7 @@ _G.__ROACT_17_MOCK_SCHEDULER__ = true local Package = script:FindFirstAncestor("__tests__").Parent -local React = require(Package.modules.React) +local React = require(Package.modules.React)() local ReactRoblox = require(Package.modules.ReactRoblox) type RenderedHook = { diff --git a/src/__tests__/react/useSetAtom.spec.luau b/src/__tests__/react/useSetAtom.spec.luau index c838be9..325af5f 100644 --- a/src/__tests__/react/useSetAtom.spec.luau +++ b/src/__tests__/react/useSetAtom.spec.luau @@ -24,11 +24,11 @@ return function() end) it("memoizes the function", function() - local hook = renderHook(function(source) - return useSetAtom(source) - end, atom(0)) + local hook = renderHook(function(props) + return useSetAtom(props.source) + end, { source = atom(0) }) local fn = hook.result - hook.rerender(atom(1)) + hook.rerender({ source = atom(1) }) expect(hook.result).to.never.equal(fn) end) end diff --git a/src/__tests__/subscribe.spec.luau b/src/__tests__/subscribe.spec.luau index 99c33f5..cf6d379 100644 --- a/src/__tests__/subscribe.spec.luau +++ b/src/__tests__/subscribe.spec.luau @@ -6,62 +6,23 @@ return function() it("runs on state change", function() local current, previous local source = atom(0) - local unsubscribe, flush = subscribe(source, function(...) + local unsubscribe = subscribe(source, function(...) current, previous = ... end) for index = 1, 3 do source(index) - flush() expect(current).to.equal(index) expect(previous).to.equal(index - 1) end unsubscribe() source(4) - flush() expect(current).to.equal(3) expect(previous).to.equal(2) end) - it("batches updates", function() - local current, previous - local source = atom(0) - local _, flush = subscribe(source, function(...) - current, previous = ... - end) - - source(1) - source(2) - flush() - - expect(current).to.equal(2) - expect(previous).to.equal(0) - end) - - it("checks equality", function() - local current, previous - local source = atom(0):memo(function(previous, current) - return current < previous - end) - local _, flush = subscribe(source, function(...) - current, previous = ... - end) - - source(1) - flush() - - expect(current).to.equal(1) - expect(previous).to.equal(0) - - source(0) - flush() - - expect(current).to.equal(1) - expect(previous).to.equal(0) - end) - it("prevents garbage collect", function() local source = atom(1) local updates = 0 @@ -70,15 +31,13 @@ return function() -- The idea here is to test whether subscribe() prevents every derived -- atom in a chain from being garbage collected. If any are GCed, then -- the subscription will stop updating and the test will fail. + local derived = derive(function() + return source() + end) subscribe( - derive( - derive(source, function(x) - return x - end), - function(x) - return 2 * x - end - ), + derive(function() + return derived() * 2 + end), function() updates += 1 end diff --git a/src/atom.luau b/src/atom.luau index d26d976..8af2c8f 100644 --- a/src/atom.luau +++ b/src/atom.luau @@ -1,126 +1,31 @@ -local reference = require(script.Parent.utils.reference) +local store = require(script.Parent.store) +local types = require(script.Parent.types) +type Atom = types.Atom -type AtomInternal = { - setForced: (self: AtomInternal, state: T | ((T) -> T)) -> (), - listeners: { [(T) -> ()]: true }, - debugTraceback: string, - debugLabel: string, - owners: { [any]: true }, -} - -export type Atom = (() -> T) & ((state: T | ((T) -> T)) -> ()) & { - get: ((self: Atom) -> T) & ((self: Atom, selector: (T) -> Result) -> Result), - set: (self: Atom, state: T | ((T) -> T)) -> (), - memo: (self: Atom, areEqual: (previous: T, current: T) -> boolean) -> Atom, - writable: (self: Atom, onSet: ((update: T, previous: T) -> T?) & (update: T, previous: T) -> ()) -> Atom, - readonly: (self: Atom) -> ReadonlyAtom, - named: (self: Atom, label: string) -> Atom, - unmount: (self: Atom) -> (), -} & AtomInternal - -export type ReadonlyAtom = (() -> T) & { - get: ((self: ReadonlyAtom) -> T) & ((self: ReadonlyAtom, selector: (T) -> Result) -> Result), - memo: (self: ReadonlyAtom, areEqual: (previous: T, current: T) -> boolean) -> ReadonlyAtom, - writable: ((self: Atom) -> Atom) - & ((self: Atom, onSet: ((update: T, previous: T) -> T?) & (update: T, previous: T) -> ()) -> Atom), - readonly: (self: ReadonlyAtom) -> ReadonlyAtom, - named: (self: ReadonlyAtom, label: string) -> ReadonlyAtom, - unmount: (self: ReadonlyAtom) -> (), -} & AtomInternal - -local atomCount = 0 - -local function atom(state: State): Atom - atomCount += 1 - - local atom = { - listeners = {}, - debugTraceback = debug.traceback(nil, 2), - debugLabel = `atom{atomCount}`, - owners = {}, - } :: Atom - - local equals: ((State, State) -> boolean)? - local setter: ((State, State) -> State?)? - - function atom:get(selector: ((State) -> Result)?): any - return if selector then selector(state) else state - end - - function atom:set(update: State | ((State) -> State)) - local nextState = if type(update) == "function" then update(state) else update - - if setter then - local result = setter(nextState, state) - - if result ~= nil then - nextState = result - else - return +local function atom(state: T): Atom + local function atom(...) + if select("#", ...) == 0 then + if store.shouldCapture() then + store.captured[atom] = true end + + return state end - if not (if equals then equals(state, nextState) else state == nextState) then + local nextState = if type(...) == "function" then (...)(state) else ... + + if state ~= nextState then state = nextState - for listener in table.clone(self.listeners) do - listener(state) + for listener in pairs(table.clone(store.listeners[atom])) do + listener() end end + + return state end - function atom:setForced(update: State | ((State) -> State)) - local nextState = if type(update) == "function" then update(state) else update - - if not (if equals then equals(state, nextState) else state == nextState) then - state = nextState - - for listener in table.clone(self.listeners) do - listener(state) - end - end - end - - function atom:memo(areEqual: (State, State) -> boolean): Atom - equals = areEqual - return self - end - - function atom:writable(onSet: ((State, State) -> State?)?): Atom - setter = onSet - return self - end - - function atom:readonly(): ReadonlyAtom - function setter(_, _) - if _G.__DEV__ then - error(`Attempt to set read-only atom '{self.debugLabel}' created at: {self.debugTraceback}`, 3) - end - end - return self - end - - function atom:named(name: string): Atom - self.debugLabel = name - return self - end - - function atom:unmount() - table.clear(self.listeners) - table.clear(self.owners) - reference.release(self) - end - - setmetatable(atom :: AtomInternal, { - __type = "Atom", - __call = function(self, ...) - if select("#", ...) > 0 then - return self:set((...)) - else - return self:get() - end - end, - }) + store.listeners[atom] = setmetatable({}, { __mode = "v" }) return atom end diff --git a/src/derive.luau b/src/derive.luau index b67d2c9..2ebe14b 100644 --- a/src/derive.luau +++ b/src/derive.luau @@ -1,65 +1,32 @@ local atom = require(script.Parent.atom) -type Atom = atom.Atom -type ReadonlyAtom = atom.ReadonlyAtom -local reference = require(script.Parent.utils.reference) +local store = require(script.Parent.store) +local types = require(script.Parent.types) +type Atom = types.Atom +type ReadonlyAtom = types.ReadonlyAtom -type Derive = - ((Atom, (A) -> T) -> ReadonlyAtom) - & ((Atom, Atom, (A, B) -> T) -> ReadonlyAtom) - & ((Atom, Atom, Atom, (A, B, C) -> T) -> ReadonlyAtom) - & ((Atom, Atom, Atom, Atom, (A, B, C, D) -> T) -> ReadonlyAtom) - & ((Atom, Atom, Atom, Atom, Atom, (A, B, C, D, E) -> T) -> ReadonlyAtom) - & ((...(Atom | ((...any) -> T))) -> ReadonlyAtom) +local function derive(source: ReadonlyAtom, comparator: ((old: T, new: T) -> boolean)?): ReadonlyAtom + local atoms, state = store.capture(source) + local derived = atom(state) + local derivedRef = setmetatable({ current = derived }, { __mode = "v" }) -local function derive(...): ReadonlyAtom - local atoms: { Atom } = { ... } - local combiner: (...unknown) -> Result = table.remove(atoms) :: any - local size = 0 - local dependencies: { unknown } = {} - local listeners: { [() -> ()]: boolean } = {} + local function listener() + if not derivedRef.current then + return + end - for index, atom in atoms do - dependencies[index] = atom:get() - size += 1 - end + local nextState = source() - local derivedAtom = atom(combiner(table.unpack(dependencies, 1, size))):readonly() - local derivedAtomUnmount = derivedAtom.unmount - local getDerivedAtom = reference.weak(derivedAtom) - - function derivedAtom:unmount() - derivedAtomUnmount(self) - - for listener in listeners do - for _, atom in atoms do - atom.listeners[listener] = nil - end + if state ~= nextState and not (comparator and comparator(state, nextState)) then + state = nextState + derivedRef.current(nextState) end end - for index, atom in atoms do - local function listener(state: unknown) - -- Remove the listener if the derived atom has been garbage collected, - -- typically because no subscriptions to it exist. - local derivedAtom = getDerivedAtom() - - if derivedAtom then - dependencies[index] = state - derivedAtom:setForced(combiner(table.unpack(dependencies, 1, size))) - else - atom.listeners[listener] = nil - end - end - - -- Tie the lifetime of the derived atom to the lifetime of its dependencies - -- without creating a strong reference cycle. As long as an atom is in use, - -- its derived atoms will be in use as well. - derivedAtom.owners[atom] = true - atom.listeners[listener] = true - listeners[listener] = true + for atom in atoms do + store.listeners[atom][listener] = derived end - return derivedAtom + return derived end -return derive :: Derive +return derive diff --git a/src/effect.luau b/src/effect.luau new file mode 100644 index 0000000..8b74b5c --- /dev/null +++ b/src/effect.luau @@ -0,0 +1,23 @@ +local store = require(script.Parent.store) +local types = require(script.Parent.types) +type ReadonlyAtom = types.ReadonlyAtom + +local function effect(source: ReadonlyAtom): () -> () + local atoms = store.capture(source) + + local function listener() + source() + end + + for atom in atoms do + store.listeners[atom][listener] = true + end + + return function() + for atom in atoms do + store.listeners[atom][listener] = nil + end + end +end + +return effect diff --git a/src/index.d.ts b/src/index.d.ts index 127055e..2b6cb9d 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -2,91 +2,74 @@ export = Charm; export as namespace Charm; declare namespace Charm { - interface InternalAtom { - /** @hidden */ - readonly listeners: Set<(value: State) => void>; - /** @hidden */ - readonly debugTraceback: string; - /** @hidden */ - readonly debugLabel: string; - /** @hidden */ - setForced(state: State | ((current: State) => State)): void; + interface Atom extends ReadonlyAtom { + readonly __nominal: unique symbol; + (state: T | ((state: T) => T)): T; } - interface BaseAtom extends InternalAtom { - get(): State; - get(selector: (state: State) => Result): Result; - set(state: State | ((current: State) => State)): void; - memo(areEqual: (previous: State, current: State) => boolean): this; - writable(onSet?: (update: State, previous: State) => State | void): Atom; - readonly(): ReadonlyAtom; - named(label: string): this; - unmount(): void; + interface ReadonlyAtom { + (): T; } - interface Atom extends BaseAtom { - (): State; - (state: State | ((previous: State) => State)): void; - } - - interface ReadonlyAtom extends BaseAtom { - (): State; - set: never; - } - - type AtomArrayToStates[]> = { - [Key in keyof Atoms]: Atoms[Key] extends Atom ? State : never; + type AtomArrayToStates[]> = { + [Key in keyof Atoms]: Atoms[Key] extends ReadonlyAtom ? State : never; }; function atom(state: State): Atom; function isAtom(value: unknown): value is Atom; - function derive[], Result>( - ...args: [...atoms: Atoms, combiner: (...atoms: AtomArrayToStates) => Result] - ): ReadonlyAtom; + function derive( + atom: ReadonlyAtom, + comparator?: (previous: State, current: State) => boolean, + ): ReadonlyAtom; - function subscribe(atom: Atom, callback: (state: State) => void): () => void; + function subscribe( + atom: ReadonlyAtom, + callback: (state: State, previousState: State) => void, + ): () => void; + + function effect(callback: () => void): () => void; function observe( - atom: Atom | ReadonlyMap>, + atom: ReadonlyAtom | ReadonlyMap>, factory: (value: V, key: K) => (() => void) | void, ): () => void; - function observe(atom: Atom, factory: (value: unknown, key: unknown) => (() => void) | void): () => void; + function observe(atom: ReadonlyAtom, factory: (value: unknown, key: unknown) => (() => void) | void): () => void; function mapAtom( - atom: Atom | Atom, + atom: ReadonlyAtom | ReadonlyAtom, mapper: (value: V0, index: number) => LuaTuple<[V1 | undefined, K1]>, ): ReadonlyAtom>; function mapAtom( - atom: Atom | Atom, + atom: ReadonlyAtom | ReadonlyAtom, mapper: (value: V0, index: number) => V1, ): ReadonlyAtom; function mapAtom( - atom: Atom> | Atom>, + atom: ReadonlyAtom> | ReadonlyAtom>, mapper: (value: V0, key: K0) => LuaTuple<[V1 | undefined, K1]> | V1, ): ReadonlyAtom>; function mapAtom( - atom: Atom<{ readonly [K in K0]: V0 }>, + atom: ReadonlyAtom<{ readonly [K in K0]: V0 }>, mapper: (value: V0, key: K0) => LuaTuple<[V1 | undefined, K1]> | V1, ): ReadonlyAtom>; - function useAtomState(atom: Atom): State; + function useAtomState(atom: ReadonlyAtom): State; - function useAtomState(atom: Atom, selector: (state: State) => Result): Result; + function useAtomState(atom: ReadonlyAtom, selector: (state: State) => Result): Result; - function useSetAtom(atom: Atom): (state: State | ((previous: State) => State)) => void; + function useSetAtom(atom: ReadonlyAtom): (state: State | ((previous: State) => State)) => void; function useAtom( - atom: Atom, + atom: ReadonlyAtom, ): LuaTuple<[state: State, setState: (state: State | ((previous: State) => State)) => void]>; function useAtom( - atom: Atom, + atom: ReadonlyAtom, selector: (state: State) => Result, ): LuaTuple<[state: Result, setState: (state: Result | ((previous: Result) => Result)) => void]>; diff --git a/src/init.luau b/src/init.luau index 95549b4..a0b6286 100644 --- a/src/init.luau +++ b/src/init.luau @@ -2,6 +2,7 @@ _G[script.modules.Promise] = _G[script] local atom = require(script.atom) local derive = require(script.derive) +local effect = require(script.effect) local isAtom = require(script.isAtom) local mapAtom = require(script.mapAtom) local observe = require(script.observe) @@ -10,16 +11,18 @@ local useAtomState = require(script.react.useAtomState) local useSetAtom = require(script.react.useSetAtom) local subscribe = require(script.subscribe) local sync = require(script.sync) +local types = require(script.types) -export type Atom = atom.Atom -export type ReadonlyAtom = atom.ReadonlyAtom +export type Atom = types.Atom +export type ReadonlyAtom = types.ReadonlyAtom return { atom = atom, derive = derive, + effect = effect, isAtom = isAtom, - observe = observe, mapAtom = mapAtom, + observe = observe, subscribe = subscribe, sync = sync, useAtom = useAtom, diff --git a/src/isAtom.luau b/src/isAtom.luau index bd96e97..8ba9e3a 100644 --- a/src/isAtom.luau +++ b/src/isAtom.luau @@ -1,5 +1,7 @@ +local store = require(script.Parent.store) + local function isAtom(value: any) - return type(value) == "table" and getmetatable(value) and getmetatable(value).__type == "Atom" or false + return type(value) == "function" and store.listeners[value] :: any ~= nil end return isAtom diff --git a/src/mapAtom.luau b/src/mapAtom.luau index 572455d..fd63710 100644 --- a/src/mapAtom.luau +++ b/src/mapAtom.luau @@ -1,23 +1,21 @@ local atom = require(script.Parent.atom) -type Atom = atom.Atom -type ReadonlyAtom = atom.ReadonlyAtom -local reference = require(script.Parent.utils.reference) +local subscribe = require(script.Parent.subscribe) +local types = require(script.Parent.types) +type Atom = types.Atom +type ReadonlyAtom = types.ReadonlyAtom local function mapAtom(itemsAtom: Atom<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1?)): ReadonlyAtom<{ [K1]: V1 }> - local mappedAtom: ReadonlyAtom<{ [K1]: V1 }> = atom({}):readonly() - local mappedAtomUnmount = mappedAtom.unmount - local getMappedAtom = reference.weak(mappedAtom) + local mappedAtom = atom({}) + local mappedAtomRef = setmetatable({ current = mappedAtom }, { __mode = "v" }) local previousMappedItems: { [K1]: V1 } = {} + local unsubscribe - local function listener(items) - local mappedAtom = getMappedAtom() - - if not mappedAtom then - itemsAtom.listeners[listener] = nil - return + local function listener(items: { [K0]: V0 }) + if not mappedAtomRef.current then + return unsubscribe() end - local mappedItems = table.clone(mappedAtom:get()) + local mappedItems = table.clone(mappedAtomRef.current()) local mappedKeys = {} for key, item in items do @@ -39,16 +37,11 @@ local function mapAtom(itemsAtom: Atom<{ [K0]: V0 }>, mapper: (V end previousMappedItems = mappedItems - mappedAtom:setForced(mappedItems) + mappedAtom(mappedItems) end - function mappedAtom:unmount() - mappedAtomUnmount(self) - itemsAtom.listeners[listener] = nil - end - - itemsAtom.listeners[listener] = true - listener(itemsAtom:get()) + unsubscribe = subscribe(itemsAtom, listener) + listener(itemsAtom()) return mappedAtom end diff --git a/src/modules/React.luau b/src/modules/React.luau index 0ae6f64..1f24cb1 100644 --- a/src/modules/React.luau +++ b/src/modules/React.luau @@ -5,4 +5,11 @@ local Packages = if Package.Parent:FindFirstChild("React") type React = typeof(require(Package.Parent.React)) -return (if Packages then require(Packages.React) else nil) :: React +local React: React + +return function() + if not React then + React = Packages and require(Packages.React) :: React + end + return React +end diff --git a/src/observe.luau b/src/observe.luau index a8619df..8bef5c3 100644 --- a/src/observe.luau +++ b/src/observe.luau @@ -1,11 +1,13 @@ -local atom = require(script.Parent.atom) -type Atom = atom.Atom -local subscribe = require(script.Parent.subscribe) +local effect = require(script.Parent.effect) +local types = require(script.Parent.types) +type ReadonlyAtom = types.ReadonlyAtom -local function observe(atom: Atom<{ [Key]: Item }>, factory: (value: Item, key: Key) -> () -> ()): (() -> (), () -> ()) - local connections: { [Key]: () -> () } = {} +local function observe(source: ReadonlyAtom<{ [K]: V }>, factory: (value: V, key: K) -> () -> ()): () -> () + local connections: { [K]: () -> () } = {} + + local unsubscribe = effect(function() + local state = source() - local function update(state: { [Key]: Item }) for key, disconnect in connections do if state[key] == nil then connections[key] = nil @@ -18,9 +20,7 @@ local function observe(atom: Atom<{ [Key]: Item }>, factory: (value: connections[key] = factory(value, key) end end - end - - local unsubscribe, flush = subscribe(atom, update) + end) local function cleanup() unsubscribe() @@ -29,9 +29,7 @@ local function observe(atom: Atom<{ [Key]: Item }>, factory: (value: end end - update(atom:get()) - - return cleanup, flush + return cleanup end return observe diff --git a/src/react/useAtom.luau b/src/react/useAtom.luau index ed06093..c2f9f29 100644 --- a/src/react/useAtom.luau +++ b/src/react/useAtom.luau @@ -1,5 +1,5 @@ -local atom = require(script.Parent.Parent.atom) -type Atom = atom.Atom +local types = require(script.Parent.Parent.types) +type Atom = types.Atom local useAtomState = require(script.Parent.useAtomState) local useSetAtom = require(script.Parent.useSetAtom) diff --git a/src/react/useAtomState.luau b/src/react/useAtomState.luau index bcedd38..e04f557 100644 --- a/src/react/useAtomState.luau +++ b/src/react/useAtomState.luau @@ -1,7 +1,8 @@ -local React = require(script.Parent.Parent.modules.React) +local requireReact = require(script.Parent.Parent.modules.React) +local subscribe = require(script.Parent.Parent.subscribe) -local atom = require(script.Parent.Parent.atom) -type Atom = atom.Atom +local types = require(script.Parent.Parent.types) +type Atom = types.Atom type UseAtomState = ((atom: Atom) -> State) @@ -9,24 +10,20 @@ type UseAtomState = & ((atom: Atom, selector: (State) -> Result) -> Result) local function useAtomState(atom: Atom, selector: ((State) -> State)?): State + local React = requireReact() + local state, setState = React.useState(function() - return atom:get(selector :: (State) -> State) + return if selector then atom(selector) else atom() end) local latestSelector = React.useRef(selector) latestSelector.current = selector React.useEffect(function() - local function listener(state: State) + return subscribe(atom, function(state) local selector = latestSelector.current setState(if selector then selector(state) else state) - end - - atom.listeners[listener] = true - - return function() - atom.listeners[listener] = nil - end + end) end, { atom }) return state diff --git a/src/react/useSetAtom.luau b/src/react/useSetAtom.luau index debb1ca..e6686fd 100644 --- a/src/react/useSetAtom.luau +++ b/src/react/useSetAtom.luau @@ -1,13 +1,13 @@ -local React = require(script.Parent.Parent.modules.React) +local requireReact = require(script.Parent.Parent.modules.React) -local atom = require(script.Parent.Parent.atom) -type Atom = atom.Atom +local types = require(script.Parent.Parent.types) +type Atom = types.Atom export type SetState = (T | ((T) -> T)) -> () local function useSetAtom(atom: Atom): SetState - return React.useCallback(function(value) - atom:set(value) + return requireReact().useCallback(function(value) + atom(value) end, { atom }) end diff --git a/src/store.luau b/src/store.luau new file mode 100644 index 0000000..abcba41 --- /dev/null +++ b/src/store.luau @@ -0,0 +1,38 @@ +local types = require(script.Parent.types) +type Atom = types.Atom +type ReadonlyAtom = types.ReadonlyAtom +type WeakMap = types.WeakMap + +local listeners: WeakMap, WeakMap<() -> (), unknown>> = setmetatable({}, { __mode = "k" }) +local captured: { [Atom]: true } = {} +local capturing = false + +local function capture(source: ReadonlyAtom): ({ [Atom]: true }, T) + if listeners[source] then + return { [source] = true }, source() + end + + capturing = true + local success, result = pcall(source) + capturing = false + + local dependencies = table.clone(captured) + table.clear(captured) + + if not success then + warn("An error occurred while calling an atom:", result) + end + + return dependencies, result +end + +local function shouldCapture() + return capturing +end + +return { + listeners = listeners, + captured = captured, + capture = capture, + shouldCapture = shouldCapture, +} diff --git a/src/subscribe.luau b/src/subscribe.luau index 1f80104..c0e55da 100644 --- a/src/subscribe.luau +++ b/src/subscribe.luau @@ -1,45 +1,25 @@ -local atom = require(script.Parent.atom) -type Atom = atom.Atom -local reference = require(script.Parent.utils.reference) +local store = require(script.Parent.store) +local types = require(script.Parent.types) +type ReadonlyAtom = types.ReadonlyAtom -local function subscribe(atom: Atom, callback: (state: State, previous: State) -> ()): (() -> (), () -> ()) - local pending: thread? = nil - local state = atom:get() +local function subscribe(source: ReadonlyAtom, callback: (state: T, previous: T) -> ()): () -> () + local atoms, state = store.capture(source) - local function emit() + local function listener() local lastState = state - state = atom:get() + state = source() callback(state, lastState) end - local function update() - pending = pending or task.defer(function() - pending = nil - emit() - end) + for atom in atoms do + store.listeners[atom][listener] = true end - local function flush() - if pending then - pending = task.cancel(pending) - emit() + return function() + for atom in atoms do + store.listeners[atom][listener] = nil end end - - local function unsubscribe() - reference.release(atom) - atom.listeners[update] = nil - - if pending then - pending = task.cancel(pending) - end - end - - -- Ensure the atom is held in memory while the subscription is active - reference.hold(atom) - atom.listeners[update] = true - - return unsubscribe, flush end return subscribe diff --git a/src/sync/client.luau b/src/sync/client.luau index d651a5c..b82ca14 100644 --- a/src/sync/client.luau +++ b/src/sync/client.luau @@ -1,14 +1,15 @@ -local atom = require(script.Parent.Parent.atom) -type Atom = atom.Atom +local atomTypes = require(script.Parent.Parent.types) +type Atom = atomTypes.Atom local patch = require(script.Parent.patch) local types = require(script.Parent.types) +type SyncPayload = types.SyncPayload type ClientSyncOptions = { atoms: { [string]: Atom }, } type ClientSyncer = { - sync: (self: ClientSyncer, payload: types.SyncPayload) -> (), + sync: (self: ClientSyncer, payload: SyncPayload) -> (), } local function client(options: ClientSyncOptions): ClientSyncer @@ -18,9 +19,9 @@ local function client(options: ClientSyncOptions): ClientSyncer function self:sync(payload) for key, state in payload.data do if payload.type == "patch" then - atoms[key]:set(patch.apply(atoms[key]:get(), state)) + atoms[key](patch.apply(atoms[key](), state)) else - atoms[key]:set(state) + atoms[key](state) end end end diff --git a/src/sync/patch.luau b/src/sync/patch.luau index 8827645..eb5b76c 100644 --- a/src/sync/patch.luau +++ b/src/sync/patch.luau @@ -3,17 +3,17 @@ local validate = require(script.Parent.validate) local NONE = { __none = "__none" } local function diff(previousState: { [any]: any }, nextState: { [any]: any }) - local patch = table.clone(nextState) + local patches = table.clone(nextState) for key, previous in previousState do local next = nextState[key] if previous == next then - patch[key] = nil + patches[key] = nil elseif next == nil then - patch[key] = NONE + patches[key] = NONE elseif type(previous) == "table" and type(next) == "table" then - patch[key] = diff(previous, next) + patches[key] = diff(previous, next) end end @@ -23,7 +23,9 @@ local function diff(previousState: { [any]: any }, nextState: { [any]: any }) validate(value, key) end for key, value in nextState do - validate(value, key) + if previousState[key] ~= value then + validate(value, key) + end end end) @@ -32,13 +34,13 @@ local function diff(previousState: { [any]: any }, nextState: { [any]: any }) end end - return patch + return patches end -local function apply(state: { [any]: any }, patchState: { [any]: any }) +local function apply(state: { [any]: any }, patches: { [any]: any }) local nextState = table.clone(state) - for key, patch in patchState do + for key, patch in patches do local current = nextState[key] if type(patch) == "table" and patch.__none == "__none" then diff --git a/src/sync/server.luau b/src/sync/server.luau index 55c6ef0..e8e43a9 100644 --- a/src/sync/server.luau +++ b/src/sync/server.luau @@ -1,10 +1,11 @@ local Players = game:GetService("Players") -local atom = require(script.Parent.Parent.atom) -type Atom = atom.Atom +local atomTypes = require(script.Parent.Parent.types) +type Atom = atomTypes.Atom local setInterval = require(script.Parent.Parent.utils.setInterval) local patch = require(script.Parent.patch) local types = require(script.Parent.types) +type SyncPayload = types.SyncPayload type ServerSyncOptions = { atoms: { [string]: Atom }, @@ -12,7 +13,7 @@ type ServerSyncOptions = { } type ServerSyncer = { - onSync: (self: ServerSyncer, callback: (player: Player, payload: types.SyncPayload) -> ()) -> () -> (), + onSync: (self: ServerSyncer, callback: (player: Player, payload: SyncPayload) -> ()) -> () -> (), flush: (self: ServerSyncer, player: Player?) -> (), hydrate: (self: ServerSyncer, player: Player) -> (), } @@ -21,13 +22,13 @@ local function server(options: ServerSyncOptions): ServerSyncer local atoms = options.atoms local interval = options.interval or 0 local self = {} :: ServerSyncer - local sync: (player: Player, payload: types.SyncPayload) -> () + local sync: (player: Player, payload: SyncPayload) -> () local state: {} local function getState() local state = {} for key, atom in atoms do - state[key] = atom:get() + state[key] = atom() end return state end @@ -47,7 +48,7 @@ local function server(options: ServerSyncOptions): ServerSyncer state = current if current ~= previous then - local payload: types.SyncPayload = { + local payload: SyncPayload = { type = "patch", data = patch.diff(previous, current), } diff --git a/src/types.luau b/src/types.luau new file mode 100644 index 0000000..5992614 --- /dev/null +++ b/src/types.luau @@ -0,0 +1,5 @@ +export type Atom = (() -> T) & ((T | (T) -> T) -> T) +export type ReadonlyAtom = () -> T +export type WeakMap = typeof(setmetatable({} :: { [K]: V }, { __mode = "k" })) + +return nil