@e280/strata 0.2.2 → 0.2.4

package/README.md

@@ -9,13 +9,13 @@
 
 ### get in loser, we're managing state
 📦 `npm install @e280/strata`  
+✨ it's all about automagically rerendering ui when data changes  
+🦝 powers auto-reactivity in our view library [@e280/sly](https://github.com/e280/sly)  
 🧙‍♂️ probably my tenth state management library, lol  
-💁 it's all about rerendering ui when data changes  
-🦝 powers reactivity in our view library [@e280/sly](https://github.com/e280/sly)  
-🧑‍💻 a project by https://e280.org/
+🧑‍💻 a project by https://e280.org/  
 
 🚦 [**signals**](#signals) — ephemeral view-level state  
-🌳 [**tree**](#tree) — persistent app-level state  
+🔮 [**prism**](#prism) — app-level state tree  
 🪄 [**tracker**](#tracker) — reactivity integration hub  
 
 
@@ -24,7 +24,7 @@
 
 <a id="signals"></a>
 
-## 🚦 strata signals
+## 🍋 strata signals
 > *ephemeral view-level state*
 
 ```ts
@@ -152,140 +152,135 @@ import {signal, effect} from "@e280/strata"
 
 <br/><br/>
 
-<a id="tree"></a>
+<a id="prism"></a>
 
-## 🌳 strata tree
+## 🍋 strata prism
 > *persistent app-level state*
 
-```ts
-import {Trunk} from "@e280/strata"
-```
-
 - single-source-of-truth state tree
-- immutable except for `mutate(fn)` calls
-- localStorage persistence, cross-tab sync, undo/redo history
 - no spooky-dookie proxy magic — just god's honest javascript
+- immutable except for `mutate(fn)` calls
+- use many lenses, efficient reactivity
+- chrono provides undo/redo history
+- persistence, localstorage, cross-tab sync
 
-#### 🌳 `Trunk` is your app's state tree root
-- better stick to json-friendly serializable data
-  ```ts
-  const trunk = new Trunk({
-    count: 0,
-    snacks: {
-      peanuts: 8,
-      bag: ["popcorn", "butter"],
-    },
-  })
-
-  trunk.state.count // 0
-  trunk.state.snacks.peanuts // 8
-  ```
-
-#### 🌳 formal mutations to change state
-- ⛔ informal mutations are denied
-  ```ts
-  trunk.state.count++ // error is thrown
-  ```
-- ✅ formal mutations are allowed
-  ```ts
-  await trunk.mutate(s => s.count++)
-  ```
-
-#### 🌳 `Branch` is a view into a subtree
-- it's a lens, make lots of them, pass 'em around your app
-  ```ts
-  const snacks = trunk.branch(s => s.snacks)
-  ```
-- run branch mutations
-  ```ts
-  await snacks.mutate(s => s.peanuts++)
-  ```
-- array mutations are unironically based, actually
-  ```ts
-  await snacks.mutate(s => s.bag.push("salt"))
-  ```
-- you can branch a branch
+### 🔮 prism and lenses
+- **import prism**
+    ```ts
+    import {Prism} from "@e280/strata"
+    ```
+- **prism is a state tree**
+    ```ts
+    const prism = new Prism({
+      snacks: {
+        peanuts: 8,
+        bag: ["popcorn", "butter"],
+        person: {
+          name: "chase",
+          incredi: true,
+        },
+      },
+    })
+    ```
+- **create lenses, which are views into state subtrees**
+    ```ts
+    const snacks = prism.lens(state => state.snacks)
+    const person = snacks.lens(state => state.person)
+    ```
+    - you can lens another lens
+- **lenses provide immutable access to state**
+    ```ts
+    snacks.state.peanuts // 8
+    person.state.name // "chase"
+    ```
+- **only formal mutations can change state**
+    ```ts
+    snacks.state.peanuts++
+      // ⛔ error: casual mutations forbidden
+    ```
+    ```ts
+    snacks.mutate(state => state.peanuts++)
+      // ✅ only proper mutations can make state changes
 
-#### 🌳 `on` to watch for mutations
-- on the trunk, we can listen deeply for mutations within the whole tree
-  ```ts
-  trunk.on(s => console.log(s.count))
-  ```
-- whereas branch listeners don't care about changes outside their scope
-  ```ts
-  snacks.on(s => console.log(s.peanuts))
-  ```
-- on returns a fn to stop listening
-  ```ts
-  const stop = trunk.on(s => console.log(s.count))
-  stop() // stop listening
-  ```
+    snacks.state.peanuts // 9
+    ```
+- **array mutations are unironically based, actually**
+    ```ts
+    await snacks.mutate(state => state.bag.push("salt"))
+    ```
 
-### 🌳 fancy advanced usage
-> *only discerning high-class aristocrats are permitted beyond this point*
+### 🔮 chrono for time travel
+- **import stuff**
+    ```ts
+    import {Chrono, chronicle} from "@e280/strata"
+    ```
+- **create a chronicle in your state**
+    ```ts
+    const prism = new Prism({
+
+        // chronicle stores history
+        //        👇
+      snacks: chronicle({
+        peanuts: 8,
+        bag: ["popcorn", "butter"],
+        person: {
+          name: "chase",
+          incredi: true,
+        },
+      }),
+    })
+    ```
+    - *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*
+- **create a chrono-wrapped lens to interact with your chronicle**
+    ```ts
+    const snacks = new Chrono(64, prism.lens(state => state.snacks))
+      //                      👆
+      // how many past snapshots to store
+    ```
+- **mutations will advance history,** and undo/redo works
+    ```ts
+    snacks.mutate(s => s.peanuts = 101)
 
-#### 🌳 `Trunk.setup` for localStorage persistence etc
-- it automatically handles persistence to localStorage and cross-tab synchronization
-- simple setup
-  ```ts
-  const {trunk} = await Trunk.setup({
-    version: 1, // 👈 bump whenever you change state schema!
-    initialState: {count: 0},
-  })
-  ```
-  - uses localStorage by default
-- it's compatible with [`@e280/kv`](https://github.com/e280/kv)
-  ```ts
-  import {Kv, StorageDriver} from "@e280/kv"
+    snacks.undo()
+      // back to 8 peanuts
 
-  const kv = new Kv(new StorageDriver())
-  const store = kv.store<any>("appState")
+    snacks.redo()
+      // forward to 101 peanuts
+    ```
+- **check how many undoable or redoable steps are available**
+    ```ts
+    snacks.undoable // 1
+    snacks.redoable // 0
+    ```
+- **you can make sub-lenses of a chrono,** all their mutations advance history too
+- **plz pinky-swear right now,** that you won't create a chrono under a lens under another chrono 💀
 
-  const {trunk} = await Trunk.setup({
-    version: 1,
-    initialState: {count: 0},
-    persistence: {
+### 🔮 persistence to localStorage
+- **import prism**
+    ```ts
+    import {Vault, LocalStore} from "@e280/strata"
+    ```
+- **create a local storage store**
+    ```ts
+    const store = new LocalStore("myAppState")
+    ```
+- **make a vault for your prism**
+    ```ts
+    const vault = new Vault({
+      prism,
       store,
-      onChange: StorageDriver.onStorageEvent,
-    },
-  })
-  ```
-
-#### 🌳 `Chronobranch` for undo/redo history
-- first, put a `Chronicle` into your state tree
-  ```ts
-  const trunk = new Trunk({
-    count: 0,
-    snacks: Trunk.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 `Chronobranch` which is like a branch, but is concerned with history
-  ```ts
-  const snacks = trunk.chronobranch(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 // 2
-  snacks.redoable // 1
-  ```
-- chronobranch can have its own branches — all their mutations advance history
-- plz pinky-swear right now, that you won't create a chronobranch under a branch under another chronobranch 💀
+      version: 1, // 👈 bump this when you break your state schema!
+    })
+    ```
+    - `store` type is compatible with [`@e280/kv`](https://github.com/e280/kv)
+- **cross-tab sync (load on storage events)**
+    ```ts
+    store.onStorageEvent(vault.load)
+    ```
+- **initial load**
+    ```ts
+    await vault.load()
+    ```
 
 
 
@@ -293,7 +288,7 @@ import {Trunk} from "@e280/strata"
 
 <a id="tracker"></a>
 
-## 🪄 strata tracker
+## 🍋 strata tracker
 > *reactivity integration hub*
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/strata",
-	"version": "0.2.2",
+	"version": "0.2.4",
 	"description": "state management",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -12,6 +12,7 @@
 	],
 	"exports": {
 		".": "./x/index.js",
+		"./prism": "./x/prism/index.js",
 		"./signals": "./x/signals/index.js",
 		"./tracker": "./x/tracker/index.js",
 		"./tree": "./x/tree/index.js"
@@ -22,7 +23,7 @@
 		"test-watch": "node --watch x/tests.test.js",
 		"test-inspect": "node inspect x/tests.test.js",
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +",
-		"watch": "run-p _tscw test-watch",
+		"start": "octo 'npm run _tscw -s' 'npm run test-watch -s'",
 		"_clean": "rm -rf x && mkdir x",
 		"_links": "ln -s \"$(realpath node_modules)\" x/node_modules",
 		"_tsc": "tsc",
@@ -32,8 +33,9 @@
 		"@e280/stz": "^0.2.14"
 	},
 	"devDependencies": {
-		"@e280/science": "^0.1.3",
-		"@types/node": "^24.9.1",
+		"@e280/science": "^0.1.4",
+		"@e280/scute": "^0.1.1",
+		"@types/node": "^24.10.0",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.9.3"
 	},

package/s/index.ts

@@ -1,4 +1,5 @@
 
+export * from "./prism/index.js"
 export * from "./signals/index.js"
 export * from "./tracker/index.js"
 export * from "./tree/index.js"

package/s/prism/chrono/chronicle.ts

@@ -0,0 +1,11 @@
+
+import {Chronicle} from "./types.js"
+
+export function chronicle<State>(state: State): Chronicle<State> {
+	return {
+		past: [],
+		present: state,
+		future: [],
+	}
+}
+

package/s/prism/chrono/chrono.ts

@@ -0,0 +1,91 @@
+
+import {deep} from "@e280/stz"
+import {Lens} from "../lens.js"
+import {Chronicle} from "./types.js"
+import {LensLike} from "../types.js"
+import {_optic} from "../utils/optic-symbol.js"
+
+export class Chrono<State> implements LensLike<State> {
+	constructor(
+		public limit: number,
+		private basis: Lens<Chronicle<State>>,
+	) {}
+
+	get chronicle() {
+		return this.basis.state
+	}
+
+	get state() {
+		return this.basis.state.present
+	}
+
+	get undoable() {
+		return this.chronicle.past.length
+	}
+
+	get redoable() {
+		return this.chronicle.future.length
+	}
+
+	#mut<R>(chronicle: Chronicle<State>, fn: (state: State) => R) {
+		const limit = Math.max(0, this.limit)
+		const snapshot = deep.clone(this.chronicle.present) as State
+		const result = fn(chronicle.present)
+		chronicle.past.push(snapshot)
+		chronicle.past = chronicle.past.slice(-limit)
+		chronicle.future = []
+		return result
+	}
+
+	/** progress forwards, depositing history into the past */
+	async mutate<R>(fn: (state: State) => R): Promise<R> {
+		return this.basis.mutate(chronicle => this.#mut(chronicle, fn))
+	}
+
+	/** step backwards into the past, by n steps */
+	async undo(n = 1) {
+		await this.basis.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.basis.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.basis.mutate(chronicle => {
+			chronicle.past = []
+			chronicle.future = []
+		})
+	}
+
+	lens<State2>(selector: (state: State) => State2) {
+		const lens = new Lens<State2>({
+			registerLens: this.basis[_optic].registerLens,
+			getState: () => selector(this.basis[_optic].getState().present),
+			mutate: fn => this.basis[_optic].mutate(chronicle => {
+				return this.#mut(chronicle, state => fn(selector(state)))
+			}),
+		})
+		this.basis[_optic].registerLens(lens)
+		return lens
+	}
+}
+

package/s/prism/chrono/types.ts

@@ -0,0 +1,12 @@
+
+export type Chronicle<State> = {
+	// [abc] d [efg]
+	//    \   \   \
+	//     \   \   future
+	//      \   present
+	//       past
+	past: State[]
+	present: State
+	future: State[]
+}
+

package/s/prism/index.ts

@@ -0,0 +1,11 @@
+
+export * from "./chrono/chronicle.js"
+export * from "./chrono/chrono.js"
+export * from "./chrono/types.js"
+export * from "./vault/local-store.js"
+export * from "./vault/vault.js"
+export * from "./vault/types.js"
+export * from "./lens.js"
+export * from "./prism.js"
+export * from "./types.js"
+

package/s/prism/lens.ts

@@ -0,0 +1,54 @@
+
+import {deep, microbounce, sub} from "@e280/stz"
+import {immute} from "./utils/immute.js"
+import {tracker} from "../tracker/tracker.js"
+import {_optic} from "./utils/optic-symbol.js"
+import {CacheCell} from "./utils/cache-cell.js"
+import {Immutable, LensLike, Optic} from "./types.js"
+
+/** reactive view into a state prism, with formalized mutations */
+export class Lens<State> implements LensLike<State> {
+	on = sub<[state: Immutable<State>]>()
+
+	;[_optic]: Optic<State>
+	#previous: State
+	#immutable: CacheCell<Immutable<State>>
+	#onPublishDebounced = microbounce(() => this.on.publish(this.state))
+
+	constructor(optic: Optic<State>) {
+		this[_optic] = optic
+		this.#previous = deep.clone(optic.getState())
+		this.#immutable = new CacheCell(() => immute(optic.getState()))
+	}
+
+	async update() {
+		const state = this[_optic].getState()
+		const isChanged = !deep.equal(state, this.#previous)
+		if (isChanged) {
+			this.#immutable.invalidate()
+			this.#previous = deep.clone(state)
+			this.#onPublishDebounced()
+			await tracker.notifyWrite(this)
+		}
+	}
+
+	get state() {
+		tracker.notifyRead(this)
+		return this.#immutable.get()
+	}
+
+	async mutate<R>(fn: (state: State) => R) {
+		return this[_optic].mutate(fn)
+	}
+
+	lens<State2>(selector: (state: State) => State2) {
+		const lens = new Lens<State2>({
+			getState: () => selector(this[_optic].getState()),
+			mutate: fn => this[_optic].mutate(state => fn(selector(state))),
+			registerLens: this[_optic].registerLens,
+		})
+		this[_optic].registerLens(lens)
+		return lens
+	}
+}
+