@e280/strata 0.0.0-0 → 0.0.0-2

package/README.md

@@ -1,72 +1,129 @@
 
+![](https://i.imgur.com/h7FohWa.jpeg)
+
 # ⛏️ strata
 
-**my 10th state management library, probably**
+**strata isn't just state management. *it's pure sex.***
 - 📦 `npm install @e280/strata`
 - single-source-of-truth state tree
 - immutable except for `mutate(fn)` calls
+- no spooky-dookie proxy magic — just god's honest javascript
 - undo/redo history, cross-tab sync, localStorage persistence
+- probably my 10th state management library, lol
+
+<br/>
 
-## good state management
+## get in loser, we're managing state
 
-### establish a strata with some state
+### `Strata` is your app's state tree root
 - better stick to json-friendly serializable data
   ```ts
   import {Strata} from "@e280/strata"
 
   const strata = new Strata({
     count: 0,
-    stuff: {
+    snacks: {
       peanuts: 8,
-      items: ["hello", "world"],
+      bag: ["popcorn", "butter"],
     },
   })
 
   strata.state.count // 0
-  strata.state.stuff.peanuts // 8
+  strata.state.snacks.peanuts // 8
   ```
 
-### how mutations work
+### formal mutations to change state
 - ⛔ informal mutations are denied
   ```ts
   strata.state.count++ // error is thrown
   ```
-- ✅ formal mutation is allowed
+- ✅ formal mutations are allowed
   ```ts
   await strata.mutate(s => s.count++)
   ```
 
-### substrata and selectors
-- a substrata is a view into a subset of the state tree
+### `Substrata` is a view into a subtree
+- it's a lens, make lots of them, pass 'em around your app
   ```ts
-  const stuff = strata.substrata(s => s.stuff)
+  const snacks = strata.substrata(s => s.snacks)
   ```
 - run substrata mutations
   ```ts
-  await stuff.mutate(s => s.peanuts++)
+  await snacks.mutate(s => s.peanuts++)
   ```
-- array mutations are cool, actually
+- array mutations are unironically based, actually
   ```ts
-  await stuff.mutate(s => s.items.push("lol"))
+  await snacks.mutate(s => s.bag.push("salt"))
   ```
+- you can make a substrata of another substrata
 
-### onMutation events
+### watch mutations
 - you can listen to global mutations on the strata
   ```ts
-  strata.onMutation(s => console.log(s.count))
+  strata.watch(s => console.log(s.count))
   ```
-
 - substrata listeners don't care about outside changes
   ```ts
-  stuff.onMutation(s => console.log(s.peanuts))
+  snacks.watch(s => console.log(s.peanuts))
   ```
-
-- onMutation returns a fn to stop listening
+- watch returns a fn to stop listening
   ```ts
-  const stop = strata.onMutation(s => console.log(s.count))
+  const stop = strata.watch(s => console.log(s.count))
   stop() // stop listening
   ```
 
+<br/>
+
+## only high-class discerning aristocrats permitted beyond this point
+
+### `Chronstrata` for undo/redo history
+- first, put a `Chronicle` into your state tree
+  ```ts
+  const strata = new Strata({
+    count: 0,
+    snacks: Strata.chronicle({
+      peanuts: 8,
+      bag: ["popcorn", "butter"],
+    }),
+  })
+  ```
+  - *big-brain moment:* the whole chronicle *itself* is stored in the state.. serializable.. think persistence — user can close their project, reopen, and their undo/redo history is still chillin' — *brat girl summer*
+- second, make a `Chronstrata` which is like a substrata
+  ```ts
+  const snacks = strata.chronstrata(64, s => s.snacks)
+    //                               \
+    //               how many past snapshots to store
+  ```
+- mutations will advance history (undoable/redoable)
+  ```ts
+  await snacks.mutate(s => s.peanuts = 101)
+
+  await snacks.undo()
+    // back to 8 peanuts
+
+  await snacks.redo()
+    // forward to 101 peanuts
+  ```
+- you can check how many undoable or redoable steps are available
+  ```ts
+  snacks.undoable // 0
+
+  await snacks.mutate(s => s.peanuts = 101)
+  await snacks.mutate(s => s.peanuts = 102)
+  await snacks.mutate(s => s.peanuts = 103)
+
+  snacks.undoable // 3
+
+  await snacks.undo()
+
+  snacks.undoable // 2
+  snacks.redoable // 1
+  ```
+- chronstrata can have its own substrata — all their mutations advance history
+- plz pinky-swear right now, that you won't create a chronstrata under a substrata under a chronstrata
+
+<br/>
+
 ## a buildercore e280 project
 free and open source by https://e280.org/  
 join us if you're cool and good at dev  

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/strata",
-	"version": "0.0.0-0",
+	"version": "0.0.0-2",
 	"description": "state management",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -24,7 +24,7 @@
 	},
 	"devDependencies": {
 		"@e280/science": "^0.0.5",
-		"@types/node": "^24.0.3",
+		"@types/node": "^24.0.4",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.8.3"
 	},

package/s/index.ts

@@ -1,5 +1,6 @@
 
-export {Strata} from "./parts/strata.js"
-export {Substrata} from "./parts/substrata.js"
-export {Options, Mutator, Selector} from "./parts/types.js"
+export * from "./parts/chronstrata.js"
+export * from "./parts/strata.js"
+export * from "./parts/substrata.js"
+export * from "./parts/types.js"
 

package/s/parts/chronstrata.ts

@@ -0,0 +1,84 @@
+
+import {Substrata} from "./substrata.js"
+import {Chronicle, Mutator, Options, Selector, Stratum, Substate} from "./types.js"
+
+export class Chronstrata<ParentState extends Substate, S extends Substate> implements Stratum<S> {
+	#substrata: Substrata<ParentState, Chronicle<S>>
+
+	constructor(
+			public limit: number,
+			public parent: Stratum<ParentState>,
+			public selector: Selector<ParentState, Chronicle<S>>,
+			public options: Options,
+		) {
+		this.#substrata = parent.substrata(selector)
+	}
+
+	get state() {
+		return this.#substrata.state.present
+	}
+
+	get undoable() {
+		return this.#substrata.state.past.length
+	}
+
+	get redoable() {
+		return this.#substrata.state.future.length
+	}
+
+	watch(fn: (state: S) => void) {
+		return this.#substrata.watch(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 => {
+			mutator(chronicle.present)
+			chronicle.past.push(snapshot)
+			chronicle.past = chronicle.past.slice(-limit)
+			chronicle.future = []
+		})
+		return this.state
+	}
+
+	/** step backwards into the past, by n steps */
+	async undo(n = 1) {
+		await this.#substrata.mutate(chronicle => {
+			const snapshots = chronicle.past.slice(-n)
+			if (snapshots.length >= n) {
+				const oldPresent = chronicle.present
+				chronicle.present = snapshots.shift()!
+				chronicle.past = chronicle.past.slice(0, -n)
+				chronicle.future.unshift(oldPresent, ...snapshots)
+			}
+		})
+	}
+
+	/** step forwards into the future, by n steps */
+	async redo(n = 1) {
+		await this.#substrata.mutate(chronicle => {
+			const snapshots = chronicle.future.slice(0, n)
+			if (snapshots.length >= n) {
+				const oldPresent = chronicle.present
+				chronicle.present = snapshots.shift()!
+				chronicle.past.push(oldPresent, ...snapshots)
+				chronicle.future = chronicle.future.slice(n)
+			}
+		})
+	}
+
+	/** wipe past and future snapshots */
+	async wipe() {
+		await this.#substrata.mutate(chronicle => {
+			chronicle.past = []
+			chronicle.future = []
+		})
+	}
+
+	substrata<Sub extends Substate>(selector: Selector<S, Sub>): Substrata<S, Sub> {
+		return new Substrata(this, selector, this.options)
+	}
+}
+

package/s/parts/strata.ts

@@ -2,39 +2,51 @@
 import {debounce, deep, sub} from "@e280/stz"
 
 import {Substrata} from "./substrata.js"
+import {Chronstrata} from "./chronstrata.js"
 import {processOptions} from "./utils/process-options.js"
-import {Mutator, Options, Selector, State, Substate} from "./types.js"
+import {Chronicle, Mutator, Options, Selector, State, Stratum, Substate} from "./types.js"
 
-export class Strata<S extends State> {
-	onMutation = sub<[state: S]>()
+export class Strata<S extends State> implements Stratum<S> {
+	static chronicle = <S extends Substate>(state: S): Chronicle<S> => ({
+		present: state,
+		past: [],
+		future: [],
+	})
+
+	options: Options
+	watch = sub<[state: S]>()
 
-	#options: Options
 	#mutable: S
 	#immutable: S
-	#dispatchMutation = debounce(0, (state: S) => this.onMutation.pub(state))
+	#mutationLock = 0
+	#dispatchMutation = debounce(0, async(state: S) => {
+		this.#mutationLock++
+		try { await this.watch.pub(state) }
+		finally { this.#mutationLock-- }
+	})
 
 	constructor(state: S, options: Partial<Options> = {}) {
-		this.#options = processOptions(options)
+		this.options = processOptions(options)
 		this.#mutable = state
-		this.#immutable = deep.freeze(this.#options.clone(state))
+		this.#immutable = deep.freeze(this.options.clone(state))
 	}
 
 	#updateState(state: S) {
 		this.#mutable = state
-		this.#immutable = deep.freeze(this.#options.clone(state))
+		this.#immutable = deep.freeze(this.options.clone(state))
 	}
 
 	get state() {
 		return this.#immutable
 	}
 
-	substrata<Sub extends Substate>(selector: Selector<S, Sub>) {
-		return new Substrata(this, selector, this.#options)
-	}
-
 	async mutate(mutator: Mutator<S>) {
-		const oldState = this.#options.clone(this.#mutable)
-		mutator(this.#mutable)
+		const oldState = this.options.clone(this.#mutable)
+		if (this.#mutationLock > 0)
+			throw new Error("nested mutations are forbidden")
+		this.#mutationLock++
+		try { mutator(this.#mutable) }
+		finally { this.#mutationLock-- }
 		const newState = this.#mutable
 		const isChanged = !deep.equal(newState, oldState)
 		if (isChanged) {
@@ -44,5 +56,16 @@ export class Strata<S extends State> {
 		}
 		return this.#immutable
 	}
+
+	substrata<Sub extends Substate>(selector: Selector<S, Sub>): Substrata<S, Sub> {
+		return new Substrata(this, selector, this.options)
+	}
+
+	chronstrata<Sub extends Substate>(
+			limit: number,
+			selector: Selector<S, Chronicle<Sub>>,
+		) {
+		return new Chronstrata(limit, this, selector, this.options)
+	}
 }
 

package/s/parts/substrata.ts

@@ -1,29 +1,25 @@
 
 import {debounce, deep, sub} from "@e280/stz"
+import {Chronstrata} from "./chronstrata.js"
+import {Chronicle, Mutator, Options, Selector, Stratum, Substate} from "./types.js"
 
-import {Strata} from "./strata.js"
-import {processOptions} from "./utils/process-options.js"
-import {Mutator, Options, Selector, State, Substate} from "./types.js"
-
-export class Substrata<ParentState extends State, S extends Substate> {
+export class Substrata<ParentState extends Substate, S extends Substate> implements Stratum<S> {
 	dispose: () => void
-	onMutation = sub<[state: S]>()
+	watch = sub<[state: S]>()
 
-	#options: Options
 	#immutable: S
-	#dispatchMutation = debounce(0, (state: S) => this.onMutation.pub(state))
+	#dispatchMutation = debounce(0, (state: S) => this.watch.pub(state))
 
 	constructor(
-			private strata: Strata<ParentState>,
+			private parent: Stratum<ParentState>,
 			private selector: Selector<ParentState, S>,
-			options: Partial<Options> = {},
+			private options: Options,
 		) {
 
-		this.#options = processOptions(options)
-		const state = this.selector(this.strata.state)
-		this.#immutable = deep.freeze(this.#options.clone(state))
+		const state = this.selector(this.parent.state)
+		this.#immutable = deep.freeze(this.options.clone(state))
 
-		this.dispose = this.strata.onMutation(async parentState => {
+		this.dispose = this.parent.watch(async parentState => {
 			const oldState = this.#immutable
 			const newState = this.selector(parentState)
 			const isChanged = !deep.equal(newState, oldState)
@@ -36,7 +32,7 @@ export class Substrata<ParentState extends State, S extends Substate> {
 	}
 
 	#updateState(state: S) {
-		this.#immutable = deep.freeze(this.#options.clone(state))
+		this.#immutable = deep.freeze(this.options.clone(state))
 	}
 
 	get state(): S {
@@ -44,12 +40,19 @@ export class Substrata<ParentState extends State, S extends Substate> {
 	}
 
 	async mutate(mutator: Mutator<S>) {
-		await this.strata.mutate(parentState => mutator(this.selector(parentState)))
+		await this.parent.mutate(parentState => mutator(this.selector(parentState)))
 		return this.#immutable
 	}
 
-	substrata<Sub extends Substate>(selector: Selector<S, Sub>) {
-		return this.strata.substrata(parentState => selector(this.selector(parentState)))
+	substrata<Sub extends Substate>(selector: Selector<S, Sub>): Substrata<S, Sub> {
+		return new Substrata(this, selector, this.options)
+	}
+
+	chronstrata<Sub extends Substate>(
+			limit: number,
+			selector: Selector<S, Chronicle<Sub>>,
+		) {
+		return new Chronstrata(limit, this, selector, this.options)
 	}
 }
 

package/s/parts/types.ts

@@ -1,4 +1,6 @@
 
+import {Substrata} from "./substrata.js"
+
 export type Options = {
 	clone: <X>(x: X) => X
 }
@@ -9,3 +11,21 @@ export type Mutator<S> = (state: S) => void
 export type State = {}
 export type Substate = {} | null | undefined
 
+export type Stratum<S extends Substate> = {
+	readonly state: S
+	watch(fn: (s: S) => void): () => void
+	mutate(mutator: Mutator<S>): Promise<S>
+	substrata<Sub extends Substate>(selector: Selector<S, Sub>): Substrata<S, Sub>
+}
+
+export type Chronicle<S extends Substate> = {
+	// [abc] d [efg]
+	//    \   \   \
+	//     \   \   future
+	//      \   present
+	//       past
+	past: S[]
+	present: S
+	future: S[]
+}
+

package/s/tests.test.ts

@@ -23,38 +23,64 @@ await Science.run({
 			expect(strata.state.count).is(2)
 		}),
 
+		"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()
+		}),
+
 		"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()
 		}),
 
-		"onMutation is published": Science.test(async() => {
+		"watch is published": Science.test(async() => {
 			const strata = new Strata({count: 0})
 			let mutationCount = 0
-			strata.onMutation.sub(() => {mutationCount++})
+			strata.watch.sub(() => {mutationCount++})
 			await strata.mutate(state => state.count++)
 			expect(mutationCount).is(1)
 		}),
 
-		"onMutation is debounced": Science.test(async() => {
+		"watch is debounced": Science.test(async() => {
 			const strata = new Strata({count: 0})
 			let mutationCount = 0
-			strata.onMutation.sub(() => {mutationCount++})
+			strata.watch.sub(() => {mutationCount++})
 			const promise = strata.mutate(state => state.count++)
 			expect(mutationCount).is(0)
 			await promise
 			expect(mutationCount).is(1)
 		}),
 
-		"onMutation is fired when array item is pushed": Science.test(async() => {
+		"watch is fired when array item is pushed": Science.test(async() => {
 			const strata = new Strata({items: ["hello", "world"]})
 			let mutationCount = 0
-			strata.onMutation.sub(() => {mutationCount++})
+			strata.watch.sub(() => {mutationCount++})
 			await strata.mutate(state => state.items.push("lol"))
 			expect(mutationCount).is(1)
 			expect(strata.state.items.length).is(3)
 		}),
+
+		"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)
+		}),
 	}),
 
 	"substrata": Science.suite({
@@ -105,15 +131,177 @@ await Science.run({
 			expect(b.state.c).is(103)
 		}),
 
-		"onMutation ignores outside mutations": Science.test(async() => {
+		"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.onMutation.sub(() => {counted++})
+			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()
+		}),
+
+		"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()
+		}),
 	}),
+
+	"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)
+			}),
+		})
+	})(),
 })