@e280/strata 0.0.0-5 → 0.0.0-7

package/s/tests.test.ts

@@ -1,307 +1,66 @@
 
-import {expect, Science} from "@e280/science"
-import {Strata} from "./parts/strata.js"
+import {expect, Science, test} from "@e280/science"
 
-await Science.run({
-	"strata": Science.suite({
-		"get state": Science.test(async() => {
-			const strata = new Strata({count: 0})
-			expect(strata.state.count).is(0)
-		}),
-
-		"state is immutable": Science.test(async() => {
-			const strata = new Strata({count: 0})
-			expect(() => strata.state.count++).throws()
-		}),
-
-		"run a proper mutation": Science.test(async() => {
-			const strata = new Strata({count: 0})
-			expect(strata.state.count).is(0)
-			await strata.mutate(state => state.count++)
-			expect(strata.state.count).is(1)
-			await strata.mutate(state => state.count++)
-			expect(strata.state.count).is(2)
-		}),
+import tree from "./tree/tree.test.js"
+import signals from "./signals/signals.test.js"
+import tracker from "./tracker/tracker.test.js"
 
-		"forbidden mutation nesting": Science.test(async() => {
-			const strata = new Strata({count: 0})
-			await expect(async() => {
-				let promise!: Promise<any>
-				await strata.mutate(() => {
-					promise = strata.mutate(() => {})
-				})
-				await promise
-			}).throwsAsync()
-		}),
+import {Trunk} from "./tree/parts/trunk.js"
+import {effect} from "./signals/parts/effect.js"
+import {signal} from "./signals/parts/signal.js"
 
-		"state after mutation is frozen": Science.test(async () => {
-			const strata = new Strata({x: 1})
-			await strata.mutate(s => { s.x = 2 })
-			expect(() => strata.state.x = 3).throws()
-		}),
+await Science.run({
+	tree,
+	signals,
+	tracker,
 
-		"watch is published": Science.test(async() => {
-			const strata = new Strata({count: 0})
-			let mutationCount = 0
-			strata.watch.sub(() => {mutationCount++})
-			await strata.mutate(state => state.count++)
-			expect(mutationCount).is(1)
-		}),
+	interop: Science.suite({
+		"effect responds to trunk change": test(async() => {
+			const trunk = new Trunk({count: 1})
 
-		"watch is debounced": Science.test(async() => {
-			const strata = new Strata({count: 0})
-			let mutationCount = 0
-			strata.watch.sub(() => {mutationCount++})
-			const promise = strata.mutate(state => state.count++)
-			expect(mutationCount).is(0)
-			await promise
-			expect(mutationCount).is(1)
-		}),
+			let copy = 0
+			expect(copy).is(0)
 
-		"watch is fired when array item is pushed": Science.test(async() => {
-			const strata = new Strata({items: ["hello", "world"]})
-			let mutationCount = 0
-			strata.watch.sub(() => {mutationCount++})
-			await strata.mutate(state => state.items.push("lol"))
-			expect(mutationCount).is(1)
-			expect(strata.state.items.length).is(3)
-		}),
+			effect(() => copy = trunk.state.count)
+			expect(copy).is(1)
 
-		"prevent mutation loops": Science.test(async() => {
-			const strata = new Strata({count: 0})
-			let mutationCount = 0
-			strata.watch.sub(async() => {
-				mutationCount++
-				if (mutationCount > 100)
-					return
-				await strata.mutate(s => s.count++)
-			})
-			await expect(async() => {
-				await strata.mutate(state => state.count++)
-			}).throwsAsync()
-			expect(mutationCount).is(1)
+			await trunk.mutate(s => s.count++)
+			expect(copy).is(2)
 		}),
-	}),
 
-	"substrata": Science.suite({
-		"get state": Science.test(async() => {
-			const strata = new Strata({count: 0, sub: {rofls: 0}})
-			const substrata = strata.substrata(s => s.sub)
-			expect(substrata.state.rofls).is(0)
-		}),
+		"signal.set participates in flush": test(async() => {
+			let order: string[] = []
+			const count = signal(0)
 
-		"nullable selector": Science.test(async () => {
-			const strata = new Strata({
-				a: {b: 0}  as (null | {b: number}),
+			effect(() => {
+				if (count.value)
+					order.push("effect")
 			})
-			const a = strata.substrata(s => s.a)
-			expect(strata.state.a?.b).is(0)
-			expect(a.state?.b).is(0)
-			await a.mutate(a => { a!.b = 1 })
-			expect(strata.state.a?.b).is(1)
-			expect(a.state?.b).is(1)
-			await strata.mutate(s => s.a = null)
-			expect(strata.state.a?.b).is(undefined)
-			expect(a.state?.b).is(undefined)
-		}),
 
-		"composition": Science.test(async () => {
-			const strata = new Strata({a: {b: {c: 0}}})
-			const a = strata.substrata(s => s.a)
-			const b = a.substrata(s => s.b)
-			expect(strata.state.a.b.c).is(0)
-			expect(b.state.c).is(0)
-		}),
+			order.push("before")
+			await count.set(1)
+			order.push("after")
 
-		"deep mutations": Science.test(async () => {
-			const strata = new Strata({a: {b: {c: 0}}})
-			const a = strata.substrata(s => s.a)
-			const b = a.substrata(s => s.b)
-			await b.mutate(b => { b.c = 101 })
-			expect(strata.state.a.b.c).is(101)
-			expect(a.state.b.c).is(101)
-			expect(b.state.c).is(101)
-			await a.mutate(a => { a.b = {c: 102} })
-			expect(strata.state.a.b.c).is(102)
-			expect(a.state.b.c).is(102)
-			expect(b.state.c).is(102)
-			await strata.mutate(s => { s.a = {b: {c: 103}} })
-			expect(strata.state.a.b.c).is(103)
-			expect(a.state.b.c).is(103)
-			expect(b.state.c).is(103)
+			expect(order.length).is(3)
+			expect(order[0]).is("before")
+			expect(order[1]).is("effect")
+			expect(order[2]).is("after")
 		}),
 
-		"watch ignores outside mutations": Science.test(async() => {
-			const strata = new Strata({a: {x: 0}, b: {x: 0}})
-			const a = strata.substrata(s => s.a)
-			const b = strata.substrata(s => s.b)
-			let counted = 0
-			b.watch.sub(() => {counted++})
-			await a.mutate(a => a.x = 1)
-			expect(counted).is(0)
-		}),
-
-		"forbid submutation in mutation": Science.test(async() => {
-			const strata = new Strata({a: {b: 0}})
-			const a = strata.substrata(s => s.a)
-			await expect(async() => {
-				let promise!: Promise<any>
-				await strata.mutate(() => {
-					promise = a.mutate(() => {})
-				})
-				await promise
-			}).throwsAsync()
-		}),
+		"branch can include signal value": test.skip(async() => {
+			const bingus = signal(101)
+			const trunk = new Trunk({count: 1})
+			const branch = trunk.branch(s => ({
+				count: s.count,
+				bingus: bingus.value,
+			}))
+			expect(branch.state.count).is(1)
+			expect(branch.state.bingus).is(101)
 
-		"forbid mutation in submutation": Science.test(async() => {
-			const strata = new Strata({a: {b: 0}})
-			const a = strata.substrata(s => s.a)
-			await expect(async() => {
-				let promise!: Promise<any>
-				await a.mutate(() => {
-					promise = strata.mutate(() => {})
-				})
-				await promise
-			}).throwsAsync()
+			await bingus.set(102)
+			expect(branch.state.count).is(1)
+			expect(branch.state.bingus).is(102)
 		}),
 	}),
-
-	"chronstrata": (() => {
-		const setup = () => {
-			const strata = new Strata({
-				chron: Strata.chronicle({count: 0}),
-			})
-			const chron = strata.chronstrata(64, s => s.chron)
-			return {strata, chron}
-		}
-
-		return Science.suite({
-			"get state": Science.test(async() => {
-				const {chron} = setup()
-				expect(chron.state.count).is(0)
-			}),
-
-			"mutate": Science.test(async() => {
-				const {chron} = setup()
-				expect(chron.state.count).is(0)
-				await chron.mutate(s => s.count++)
-				expect(chron.state.count).is(1)
-				await chron.mutate(s => s.count++)
-				expect(chron.state.count).is(2)
-			}),
-
-			"undoable/redoable": Science.test(async() => {
-				const {chron} = setup()
-				expect(chron.undoable).is(0)
-				expect(chron.redoable).is(0)
-				expect(chron.state.count).is(0)
-				await chron.mutate(s => s.count++)
-				expect(chron.undoable).is(1)
-				await chron.mutate(s => s.count++)
-				expect(chron.undoable).is(2)
-				await chron.undo()
-				expect(chron.undoable).is(1)
-				expect(chron.redoable).is(1)
-				await chron.undo()
-				expect(chron.undoable).is(0)
-				expect(chron.redoable).is(2)
-				await chron.redo()
-				expect(chron.undoable).is(1)
-				expect(chron.redoable).is(1)
-			}),
-
-			"undo": Science.test(async() => {
-				const {chron} = setup()
-				await chron.mutate(s => s.count++)
-				await chron.undo()
-				expect(chron.state.count).is(0)
-			}),
-
-			"redo": Science.test(async() => {
-				const {chron} = setup()
-				await chron.mutate(s => s.count++)
-				await chron.undo()
-				expect(chron.state.count).is(0)
-				await chron.redo()
-				expect(chron.state.count).is(1)
-			}),
-
-			"undo/redo well ordered": Science.test(async() => {
-				const {chron} = setup()
-				await chron.mutate(s => s.count++)
-				await chron.mutate(s => s.count++)
-				await chron.mutate(s => s.count++)
-				expect(chron.state.count).is(3)
-
-				await chron.undo()
-				expect(chron.state.count).is(2)
-
-				await chron.undo()
-				expect(chron.state.count).is(1)
-
-				await chron.redo()
-				expect(chron.state.count).is(2)
-
-				await chron.redo()
-				expect(chron.state.count).is(3)
-
-				await chron.undo()
-				expect(chron.state.count).is(2)
-
-				await chron.undo()
-				expect(chron.state.count).is(1)
-
-				await chron.undo()
-				expect(chron.state.count).is(0)
-			}),
-
-			"undo nothing does nothing": Science.test(async() => {
-				const {chron} = setup()
-				await chron.undo()
-				expect(chron.state.count).is(0)
-			}),
-
-			"redo nothing does nothing": Science.test(async() => {
-				const {chron} = setup()
-				await chron.redo()
-				expect(chron.state.count).is(0)
-			}),
-
-			"undo 2x": Science.test(async() => {
-				const {chron} = setup()
-				await chron.mutate(s => s.count++)
-				await chron.mutate(s => s.count++)
-				expect(chron.state.count).is(2)
-				await chron.undo(2)
-				expect(chron.state.count).is(0)
-			}),
-
-			"redo 2x": Science.test(async() => {
-				const {chron} = setup()
-				await chron.mutate(s => s.count++)
-				await chron.mutate(s => s.count++)
-				expect(chron.state.count).is(2)
-				await chron.undo(2)
-				expect(chron.state.count).is(0)
-				await chron.redo(2)
-				expect(chron.state.count).is(2)
-			}),
-
-			"substrata mutations are tracked": Science.test(async() => {
-				const strata = new Strata({
-					chron: Strata.chronicle({
-						group: {count: 0},
-					}),
-				})
-				const chron = strata.chronstrata(64, s => s.chron)
-				const group = chron.substrata(s => s.group)
-				expect(group.state.count).is(0)
-				await group.mutate(g => g.count = 101)
-				expect(group.state.count).is(101)
-				await chron.undo()
-				expect(group.state.count).is(0)
-			}),
-		})
-	})(),
 })
 

package/s/tracker/index.ts

@@ -0,0 +1,3 @@
+
+export * from "./tracker.js"
+

package/s/tracker/tracker.test.ts

@@ -0,0 +1,40 @@
+
+import {Science, test, expect} from "@e280/science"
+import {Tracker} from "./tracker.js"
+
+export default Science.suite({
+	"change waits for downstream effects to settle": test(async() => {
+		const tracker = new Tracker()
+		let order: string[] = []
+
+		const item = {}
+		tracker.changed(item, async () => {
+			await Promise.resolve()
+			order.push("effect")
+		})
+
+		order.push("before")
+		await tracker.change(item)
+		order.push("after")
+
+		expect(order.length).is(3)
+		expect(order[0]).is("before")
+		expect(order[1]).is("effect")
+		expect(order[2]).is("after")
+	}),
+
+	"circularity forbidden": test(async() => {
+		const tracker = new Tracker()
+		const item = {}
+
+		// effect re-publishes the same change, creating a cycle
+		tracker.changed(item, async() => {
+			await tracker.change(item)
+		})
+
+		expect(async() => {
+			await tracker.change(item)
+		}).throwsAsync()
+	}),
+})
+

package/s/tracker/tracker.ts

@@ -0,0 +1,73 @@
+
+import {sub, Sub} from "@e280/stz"
+
+export type TrackableItem = object | symbol
+
+/**
+ * tracking system for state management
+ *  - it tracks when items are seen or changed
+ *
+ * for state item integration (like you're integrating a new kind of state object)
+ *  - items can call `tracker.see(this)` when they are accessed
+ *  - items can call `tracker.change(this)` when they are reassigned
+ *
+ * for reactivity integration (like you're integrating a new view library that reacts to state changes)
+ *  - run `tracker.seen(renderFn)`, collecting a set of seen items
+ *  - loop over each seen item, attach a changed handler `tracker.changed(item, handlerFn)`
+ */
+export class Tracker<Item extends TrackableItem = any> {
+	#seeables: Set<Item>[] = []
+	#changeables = new WeakMap<Item, Sub>()
+	#changeStack: Set<Promise<void>>[] = []
+	#busy = new Set<Item>()
+
+	/** indicate item was accessed */
+	see(item: Item) {
+		this.#seeables.at(-1)?.add(item)
+	}
+
+	/** collect which items were seen during fn */
+	seen<R>(fn: () => R) {
+		this.#seeables.push(new Set())
+		const result = fn()
+		const seen = this.#seeables.pop()!
+		return {seen, result}
+	}
+
+	/** indicate item was changed */
+	async change(item: Item) {
+		if (this.#busy.has(item))
+			throw new Error("circularity forbidden")
+		const prom = this.#guaranteeChangeable(item).pub()
+		this.#changeStack.at(-1)?.add(prom)
+		return prom
+	}
+
+	/** respond to changes by calling fn */
+	changed(item: Item, fn: () => Promise<void>) {
+		return this.#guaranteeChangeable(item)(async() => {
+			const collected = new Set<Promise<void>>()
+			this.#changeStack.push(collected)
+			this.#busy.add(item)
+			collected.add(fn())
+			this.#busy.delete(item)
+			await Promise.all(collected)
+			this.#changeStack.pop()
+		})
+	}
+
+	#guaranteeChangeable(item: Item) {
+		let on = this.#changeables.get(item)
+		if (!on) {
+			on = sub()
+			this.#changeables.set(item, on)
+		}
+		return on
+	}
+}
+
+const key = Symbol.for("e280.tracker.v2")
+
+/** standard global tracker for integrations */
+export const tracker: Tracker = (globalThis as any)[key] ??= new Tracker()
+

package/s/tree/index.ts

@@ -0,0 +1,7 @@
+
+export * from "./parts/chronobranch.js"
+export * from "./parts/persistence.js"
+export * from "./parts/trunk.js"
+export * from "./parts/branch.js"
+export * from "./parts/types.js"
+

package/s/{parts/substrata.ts → tree/parts/branch.ts}

@@ -1,21 +1,22 @@
 
-import {debounce, deep, sub, tracker} from "@e280/stz"
+import {debounce, deep, sub} from "@e280/stz"
 
-import {Chronstrata} from "./chronstrata.js"
-import {Chronicle, Mutator, Options, Selector, Stratum, Substate} from "./types.js"
+import {Chronobranch} from "./chronobranch.js"
+import {tracker} from "../../tracker/tracker.js"
+import {Chronicle, Mutator, Options, Selector, Tree, Branchstate} from "./types.js"
 
-export class Substrata<S extends Substate, ParentState extends Substate = any> implements Stratum<S> {
+export class Branch<S extends Branchstate, ParentState extends Branchstate = any> implements Tree<S> {
 	dispose: () => void
 	watch = sub<[state: S]>()
 
 	#immutable: S
 	#dispatchMutation = debounce(0, async(state: S) => {
 		await this.watch.pub(state)
-		tracker.change(this)
+		await tracker.change(this)
 	})
 
 	constructor(
-			private parent: Stratum<ParentState>,
+			private parent: Tree<ParentState>,
 			private selector: Selector<S, ParentState>,
 			private options: Options,
 		) {
@@ -49,15 +50,15 @@ export class Substrata<S extends Substate, ParentState extends Substate = any> i
 		return this.#immutable
 	}
 
-	substrata<Sub extends Substate>(selector: Selector<Sub, S>): Substrata<Sub, S> {
-		return new Substrata(this, selector, this.options)
+	branch<Sub extends Branchstate>(selector: Selector<Sub, S>): Branch<Sub, S> {
+		return new Branch(this, selector, this.options)
 	}
 
-	chronstrata<Sub extends Substate>(
+	chronobranch<Sub extends Branchstate>(
 			limit: number,
 			selector: Selector<Chronicle<Sub>, S>,
 		) {
-		return new Chronstrata(limit, this, selector, this.options)
+		return new Chronobranch(limit, this, selector, this.options)
 	}
 }
 

package/s/{parts/chronstrata.ts → tree/parts/chronobranch.ts}

@@ -1,17 +1,17 @@
 
-import {Substrata} from "./substrata.js"
-import {Chronicle, Mutator, Options, Selector, Stratum, Substate} from "./types.js"
+import {Branch} from "./branch.js"
+import {Chronicle, Mutator, Options, Selector, Tree, Branchstate} from "./types.js"
 
-export class Chronstrata<S extends Substate, ParentState extends Substate = any> implements Stratum<S> {
-	#substrata: Substrata<Chronicle<S>, ParentState>
+export class Chronobranch<S extends Branchstate, ParentState extends Branchstate = any> implements Tree<S> {
+	#substrata: Branch<Chronicle<S>, ParentState>
 
 	constructor(
 			public limit: number,
-			public parent: Stratum<ParentState>,
+			public parent: Tree<ParentState>,
 			public selector: Selector<Chronicle<S>, ParentState>,
 			public options: Options,
 		) {
-		this.#substrata = parent.substrata(selector)
+		this.#substrata = parent.branch(selector)
 	}
 
 	get state() {
@@ -77,8 +77,8 @@ export class Chronstrata<S extends Substate, ParentState extends Substate = any>
 		})
 	}
 
-	substrata<Sub extends Substate>(selector: Selector<Sub, S>): Substrata<Sub, S> {
-		return new Substrata(this, selector, this.options)
+	branch<Sub extends Branchstate>(selector: Selector<Sub, S>): Branch<Sub, S> {
+		return new Branch(this, selector, this.options)
 	}
 }
 

package/s/{parts/strata.ts → tree/parts/trunk.ts}

@@ -1,15 +1,16 @@
 
-import {debounce, deep, sub, tracker} from "@e280/stz"
+import {debounce, deep, sub} from "@e280/stz"
 
-import {Substrata} from "./substrata.js"
-import {strataSetup} from "./utils/setup.js"
-import {Chronstrata} from "./chronstrata.js"
+import {Branch} from "./branch.js"
+import {trunkSetup} from "./utils/setup.js"
+import {Chronobranch} from "./chronobranch.js"
+import {tracker} from "../../tracker/tracker.js"
 import {processOptions} from "./utils/process-options.js"
-import {Chronicle, Mutator, Options, Selector, State, Stratum, Substate} from "./types.js"
+import {Chronicle, Mutator, Options, Selector, Treestate, Tree, Branchstate} from "./types.js"
 
-export class Strata<S extends State> implements Stratum<S> {
-	static setup = strataSetup
-	static chronicle = <S extends Substate>(state: S): Chronicle<S> => ({
+export class Trunk<S extends Treestate> implements Tree<S> {
+	static setup = trunkSetup
+	static chronicle = <S extends Branchstate>(state: S): Chronicle<S> => ({
 		present: state,
 		past: [],
 		future: [],
@@ -52,22 +53,22 @@ export class Strata<S extends State> implements Stratum<S> {
 		await this.#dispatchMutation()
 	}
 
-	substrata<Sub extends Substate>(selector: Selector<Sub, S>): Substrata<Sub, S> {
-		return new Substrata(this, selector, this.options)
+	branch<Sub extends Branchstate>(selector: Selector<Sub, S>): Branch<Sub, S> {
+		return new Branch(this, selector, this.options)
 	}
 
-	chronstrata<Sub extends Substate>(
+	chronobranch<Sub extends Branchstate>(
 			limit: number,
 			selector: Selector<Chronicle<Sub>, S>,
 		) {
-		return new Chronstrata(limit, this, selector, this.options)
+		return new Chronobranch(limit, this, selector, this.options)
 	}
 
 	#dispatchMutation = debounce(0, async() => {
 		this.#mutationLock++
 		try { await this.watch.pub(this.#immutable) }
 		finally { this.#mutationLock-- }
-		tracker.change(this)
+		await tracker.change(this)
 	})
 }
 

package/s/{parts → tree/parts}/types.ts

@@ -1,5 +1,5 @@
 
-import {Substrata} from "./substrata.js"
+import {Branch} from "./branch.js"
 
 export type Options = {
 	clone: <X>(x: X) => X
@@ -8,29 +8,29 @@ export type Options = {
 export type Selector<Sub, S> = (state: S) => Sub
 export type Mutator<S> = (state: S) => void
 
-export type State = {}
-export type Substate = {} | null | undefined
+export type Treestate = {}
+export type Branchstate = {} | null | undefined
 
-export type Versioned<S extends State> = {
+export type Versioned<S extends Treestate> = {
 	state: S
 	version: number
 }
 
-export type Stratum<S extends Substate> = {
+export type Tree<S extends Branchstate> = {
 	readonly state: S
 	watch(fn: (s: S) => void): () => void
 	mutate(mutator: Mutator<S>): Promise<S>
-	substrata<Sub extends Substate>(selector: Selector<Sub, S>): Substrata<Sub, S>
+	branch<Sub extends Branchstate>(selector: Selector<Sub, S>): Branch<Sub, S>
 }
 
-export type SetupOptions<S extends State> = {
+export type SetupOptions<S extends Treestate> = {
 	version: number
 	initialState: S
 	saveDebounceTime?: number
 	persistence?: Persistence<Versioned<S>>
 }
 
-export type Chronicle<S extends Substate> = {
+export type Chronicle<S extends Branchstate> = {
 	// [abc] d [efg]
 	//    \   \   \
 	//     \   \   future