@e280/strata 0.0.0-1 → 0.0.0-10

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/branch.js"
+export * from "./parts/chronobranch.js"
+export * from "./parts/persistence.js"
+export * from "./parts/trunk.js"
+export * from "./parts/types.js"
+

package/s/tree/parts/branch.ts

@@ -0,0 +1,41 @@
+
+import {deep} from "@e280/stz"
+import {signal} from "../../signals/parts/signal.js"
+import {DerivedSignal} from "../../signals/parts/derive.js"
+import {Branchstate, Immutable, Mutator, Options, Selector, Tree} from "./types.js"
+
+export class Branch<S extends Branchstate, ParentState extends Branchstate = any> implements Tree<S> {
+	#immutable: DerivedSignal<Immutable<S>>
+
+	constructor(
+			private parent: Tree<ParentState>,
+			private selector: Selector<S, ParentState>,
+			private options: Options,
+		) {
+
+		this.#immutable = signal.derive(() => {
+			const state = selector(parent.state as any)
+			return deep.freeze(options.clone(state)) as Immutable<S>
+		}, {compare: deep.equal})
+	}
+
+	get state() {
+		return this.#immutable.get()
+	}
+
+	get on() {
+		return this.#immutable.on
+	}
+
+	async mutate(mutator: Mutator<S>) {
+		await this.parent.mutate(parentState =>
+			mutator(this.selector(parentState))
+		)
+		return this.#immutable.get()
+	}
+
+	branch<Sub extends Branchstate>(selector: Selector<Sub, S>): Branch<Sub, S> {
+		return new Branch(this, selector, this.options)
+	}
+}
+

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

@@ -1,40 +1,40 @@
 
-import {Substrata} from "./substrata.js"
-import {Chronicle, Mutator, Options, Selector, Stratum, Substate} from "./types.js"
+import {Branch} from "./branch.js"
+import {Branchstate, Chronicle, Immutable, Mutator, Options, Selector, Tree} from "./types.js"
 
-export class Chronstrata<ParentState extends Substate, S extends Substate> implements Stratum<S> {
-	#substrata: Substrata<ParentState, Chronicle<S>>
+export class Chronobranch<S extends Branchstate, ParentState extends Branchstate = any> implements Tree<S> {
+	#branch: Branch<Chronicle<S>, ParentState>
 
 	constructor(
 			public limit: number,
-			public parent: Stratum<ParentState>,
-			public selector: Selector<ParentState, Chronicle<S>>,
+			public parent: Tree<ParentState>,
+			public selector: Selector<Chronicle<S>, ParentState>,
 			public options: Options,
 		) {
-		this.#substrata = parent.substrata(selector)
+		this.#branch = parent.branch(selector)
 	}
 
 	get state() {
-		return this.#substrata.state.present
+		return this.#branch.state.present
 	}
 
 	get undoable() {
-		return this.#substrata.state.past.length
+		return this.#branch.state.past.length
 	}
 
 	get redoable() {
-		return this.#substrata.state.future.length
+		return this.#branch.state.future.length
 	}
 
-	onMutation(fn: (state: S) => void) {
-		return this.#substrata.onMutation(chronicle => fn(chronicle.present))
+	on(fn: (state: Immutable<S>) => void) {
+		return this.#branch.on(chronicle => fn(chronicle.present))
 	}
 
 	/** progress forwards in history */
 	async mutate(mutator: Mutator<S>) {
 		const limit = Math.max(0, this.limit)
-		const snapshot = this.options.clone(this.#substrata.state.present)
-		await this.#substrata.mutate(chronicle => {
+		const snapshot = this.options.clone(this.#branch.state.present) as S
+		await this.#branch.mutate(chronicle => {
 			mutator(chronicle.present)
 			chronicle.past.push(snapshot)
 			chronicle.past = chronicle.past.slice(-limit)
@@ -45,7 +45,7 @@ export class Chronstrata<ParentState extends Substate, S extends Substate> imple
 
 	/** step backwards into the past, by n steps */
 	async undo(n = 1) {
-		await this.#substrata.mutate(chronicle => {
+		await this.#branch.mutate(chronicle => {
 			const snapshots = chronicle.past.slice(-n)
 			if (snapshots.length >= n) {
 				const oldPresent = chronicle.present
@@ -58,7 +58,7 @@ export class Chronstrata<ParentState extends Substate, S extends Substate> imple
 
 	/** step forwards into the future, by n steps */
 	async redo(n = 1) {
-		await this.#substrata.mutate(chronicle => {
+		await this.#branch.mutate(chronicle => {
 			const snapshots = chronicle.future.slice(0, n)
 			if (snapshots.length >= n) {
 				const oldPresent = chronicle.present
@@ -71,14 +71,14 @@ export class Chronstrata<ParentState extends Substate, S extends Substate> imple
 
 	/** wipe past and future snapshots */
 	async wipe() {
-		await this.#substrata.mutate(chronicle => {
+		await this.#branch.mutate(chronicle => {
 			chronicle.past = []
 			chronicle.future = []
 		})
 	}
 
-	substrata<Sub extends Substate>(selector: Selector<S, Sub>): Substrata<S, Sub> {
-		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/tree/parts/persistence.ts

@@ -0,0 +1,31 @@
+
+import {Persistence} from "./types.js"
+
+export const localPersistence = <X>(
+		key: string,
+		storage: Storage = window.localStorage,
+	): Persistence<X> => ({
+
+	store: {
+		async get() {
+			const json = storage.getItem(key)
+			return json
+				? JSON.parse(json)
+				: undefined
+		},
+		async set(state) {
+			const json = JSON.stringify(state)
+			storage.setItem(key, json)
+		},
+	},
+
+	onChange: (fn: () => void) => {
+		const listener = (event: StorageEvent) => {
+			if (event.storageArea === storage && event.key === key)
+				fn()
+		}
+		window.addEventListener("storage", listener)
+		return () => window.removeEventListener("storage", listener)
+	},
+})
+

package/s/tree/parts/trunk.ts

@@ -0,0 +1,72 @@
+
+import {deep} from "@e280/stz"
+import {Branch} from "./branch.js"
+import {trunkSetup} from "./utils/setup.js"
+import {Chronobranch} from "./chronobranch.js"
+import {processOptions} from "./utils/process-options.js"
+import {DerivedSignal} from "../../signals/parts/derive.js"
+import {signal, Signal} from "../../signals/parts/signal.js"
+import {Branchstate, Chronicle, Immutable, Mutator, Options, Selector, Tree, Trunkstate} from "./types.js"
+
+export class Trunk<S extends Trunkstate> implements Tree<S> {
+	static setup = trunkSetup
+	static chronicle = <S extends Branchstate>(state: S): Chronicle<S> => ({
+		present: state,
+		past: [],
+		future: [],
+	})
+
+	options: Options
+
+	#immutable: DerivedSignal<Immutable<S>>
+	#mutable: Signal<S>
+	#mutationLock = 0
+
+	constructor(state: S, options: Partial<Options> = {}) {
+		this.options = processOptions(options)
+		this.#mutable = signal(state)
+		this.#immutable = signal.derive(() =>
+			deep.freeze(this.options.clone(this.#mutable.get())) as Immutable<S>
+		)
+	}
+
+	get state() {
+		return this.#immutable.get()
+	}
+
+	get on() {
+		return this.#immutable.on
+	}
+
+	async mutate(mutator: Mutator<S>) {
+		const oldState = this.options.clone(this.#mutable.get())
+		if (this.#mutationLock > 0)
+			throw new Error("nested mutations are forbidden")
+		try {
+			this.#mutationLock++
+			mutator(this.#mutable())
+			const newState = this.#mutable.get()
+			const isChanged = !deep.equal(newState, oldState)
+			if (isChanged)
+				await this.overwrite(newState)
+		}
+		finally { this.#mutationLock-- }
+		return this.#immutable.get()
+	}
+
+	async overwrite(state: S) {
+		await this.#mutable.publish(state)
+	}
+
+	branch<Sub extends Branchstate>(selector: Selector<Sub, S>): Branch<Sub, S> {
+		return new Branch(this, selector, this.options)
+	}
+
+	chronobranch<Sub extends Branchstate>(
+			limit: number,
+			selector: Selector<Chronicle<Sub>, S>,
+		) {
+		return new Chronobranch(limit, this, selector, this.options)
+	}
+}
+

package/s/tree/parts/types.ts

@@ -0,0 +1,65 @@
+
+import {Branch} from "./branch.js"
+
+export type Options = {
+	clone: <X>(x: X) => X
+}
+
+export type Selector<Sub, S> = (state: S) => Sub
+export type Mutator<S> = (state: S) => void
+
+export type Trunkstate = {}
+export type Branchstate = {} | null | undefined
+
+export type Versioned<S extends Trunkstate> = {
+	state: S
+	version: number
+}
+
+export type Immutable<T> =
+	T extends (...args: any[]) => any ? T :
+	T extends readonly any[] ? ReadonlyArray<Immutable<T[number]>> :
+	T extends object ? { readonly [K in keyof T]: Immutable<T[K]> } :
+	T
+
+export type Mutable<T> =
+	T extends (...args: any[]) => any ? T :
+	T extends ReadonlyArray<infer U> ? Mutable<U>[] :
+	T extends object ? { -readonly [K in keyof T]: Mutable<T[K]> } :
+	T
+
+export type Tree<S extends Branchstate> = {
+	get state(): Immutable<S>
+	on(fn: (state: Immutable<S>) => void): () => void
+	mutate(mutator: Mutator<S>): Promise<Immutable<S>>
+	branch<Sub extends Branchstate>(selector: Selector<Sub, S>): Branch<Sub, S>
+}
+
+export type SetupOptions<S extends Trunkstate> = {
+	version: number
+	initialState: S
+	saveDebounceTime?: number
+	persistence?: Persistence<Versioned<S>>
+}
+
+export type Chronicle<S extends Branchstate> = {
+	// [abc] d [efg]
+	//    \   \   \
+	//     \   \   future
+	//      \   present
+	//       past
+	past: S[]
+	present: S
+	future: S[]
+}
+
+export type EzStore<X> = {
+	get(): Promise<X | undefined>
+	set(state: X | undefined): Promise<void>
+}
+
+export type Persistence<X> = {
+	store: EzStore<X>
+	onChange: (fn: () => void) => (() => void)
+}
+

package/s/{parts → tree/parts}/utils/process-options.ts

@@ -2,6 +2,6 @@
 import {Options} from "../types.js"
 
 export const processOptions = (options: Partial<Options>): Options => ({
-	clone: options.clone ?? structuredClone,
+	clone: options.clone ?? (<X>(x: X) => structuredClone(x)),
 })
 

package/s/tree/parts/utils/setup.ts

@@ -0,0 +1,40 @@
+
+import {debounce} from "@e280/stz"
+
+import {Trunk} from "../trunk.js"
+import {localPersistence} from "../persistence.js"
+import {SetupOptions, Trunkstate} from "../types.js"
+
+export async function trunkSetup<S extends Trunkstate>(options: SetupOptions<S>) {
+	const {
+		version,
+		initialState,
+		saveDebounceTime = 500,
+		persistence = localPersistence("strataTree"),
+	} = options
+
+	const trunk = new Trunk<S>(initialState)
+
+	async function load() {
+		const pickle = await persistence.store.get()
+		if (pickle && pickle.version === version)
+			await trunk.overwrite(pickle.state)
+	}
+
+	const save = debounce(saveDebounceTime, async() => persistence.store.set({
+		version,
+		state: trunk.state as any,
+	}))
+
+	// persistence: initial load from store
+	await load()
+
+	// persistence: save to store
+	trunk.on(save)
+
+	// cross-tab sync
+	const dispose = persistence.onChange(load)
+
+	return {trunk, load, save, dispose}
+}
+