@e280/strata 0.0.0-5 → 0.0.0-7

package/README.md

@@ -1,26 +1,119 @@
 
 ![](https://i.imgur.com/h7FohWa.jpeg)
 
+<br/>
+
 # ⛏️ strata
 
-**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
+### get in loser, we're managing state
+📦 `npm install @e280/strata`  
+🧙‍♂️ probably my tenth state management library, lol  
+
+🚦 **signals** — ephemeral view-level state  
+🌳 **tree** — persistent app-level state  
+🪄 **tracker** — reactivity integration hub  
 
 <br/>
 
-## get in loser, we're managing state
+> [!TIP]  
+> incredibly, signals and trees are interoperable.  
+> that means, effects and computeds are responsive to changes in tree state.  
+
+<br/>
+
+## 🚦 signals — *ephemeral view-level state*
+```ts
+import {signal, effect, computed} from "@e280/strata"
+```
+
+### each signal holds a value
+- **create a signal**
+  ```ts
+  const count = signal(0)
+  ```
+- **read a signal**
+  ```ts
+  count() // 0
+  ```
+- **set a signal**
+  ```ts
+  count(1)
+  ```
+- **set a signal, and await effect propagation**
+  ```ts
+  await count(2)
+  ```
+- **signals are for auto rerendering your ui.**  
+  components/views will auto rerender when relevant signals change  
+  — well only if your ui lib is cool and integrates `tracker`.
 
-### `Strata` is your app's state tree root
+### pick your poison
+- **signals hipster fn syntax**
+  ```ts
+  count() // get
+  await count(2) // set
+  ```
+- **signals get/set syntax**
+  ```ts
+  count.get() // get
+  await count.set(2) // set
+  ```
+- **signals .value accessor syntax**
+  ```ts
+  count.value // get
+  count.value = 2 // set
+  ```
+  value pattern is nice for this vibe
+  ```ts
+  count.value++
+  count.value += 1
+  ```
+
+### effects
+- **effects run when the relevant signals change**
+  ```ts
+  effect(() => console.log(count()))
+    // 1
+    // the system detects 'count' is relevant
+
+  count.value++
+    // 2
+    // when count is changed, the effect fn is run
+  ```
+- **computed signals are super lazy**  
+  they only run if and when you get the value
+  ```ts
+  const tenly = computed(() => {
+    console.log("recomputed!")
+    return count() * 10
+  })
+
+  console.log(tenly())
+    // "recomputed!"
+    // 20
+
+  await count(3)
+
+  console.log(tenly.value)
+    // "recomputed!"
+    // 30
+  ```
+
+<br/>
+
+## 🌳 tree — *persistent app-level state*
+- single-source-of-truth state tree
+- immutable except for `mutate(fn)` calls
+- undo/redo history, cross-tab sync, localStorage persistence
+- no spooky-dookie proxy magic — just god's honest javascript
+- separate but compatible with signals
+
+#### `Trunk` is your app's state tree root
 - better stick to json-friendly serializable data
   ```ts
-  import {Strata} from "@e280/strata"
+  import {Trunk} from "@e280/strata"
 
-  const strata = new Strata({
+  const trunk = new Trunk({
     count: 0,
     snacks: {
       peanuts: 8,
@@ -28,26 +121,26 @@
     },
   })
 
-  strata.state.count // 0
-  strata.state.snacks.peanuts // 8
+  trunk.state.count // 0
+  trunk.state.snacks.peanuts // 8
   ```
 
-### formal mutations to change state
+#### formal mutations to change state
 - ⛔ informal mutations are denied
   ```ts
-  strata.state.count++ // error is thrown
+  trunk.state.count++ // error is thrown
   ```
 - ✅ formal mutations are allowed
   ```ts
-  await strata.mutate(s => s.count++)
+  await trunk.mutate(s => s.count++)
   ```
 
-### `Substrata` is a view into a subtree
+#### `Branch` is a view into a subtree
 - it's a lens, make lots of them, pass 'em around your app
   ```ts
-  const snacks = strata.substrata(s => s.snacks)
+  const snacks = trunk.branch(s => s.snacks)
   ```
-- run substrata mutations
+- run branch mutations
   ```ts
   await snacks.mutate(s => s.peanuts++)
   ```
@@ -55,43 +148,42 @@
   ```ts
   await snacks.mutate(s => s.bag.push("salt"))
   ```
-- you can make a substrata of another substrata
+- you can branch a branch
 
-### watch mutations
-- you can listen to global mutations on the strata
+#### watch for mutations
+- on the trunk, we can listen deeply for mutations within the whole tree
   ```ts
-  strata.watch(s => console.log(s.count))
+  trunk.watch(s => console.log(s.count))
   ```
-- substrata listeners don't care about outside changes
+- whereas branch listeners don't care about changes outside their scope
   ```ts
   snacks.watch(s => console.log(s.peanuts))
   ```
 - watch returns a fn to stop listening
   ```ts
-  const stop = strata.watch(s => console.log(s.count))
+  const stop = trunk.watch(s => console.log(s.count))
   stop() // stop listening
   ```
 
-<br/>
-
-## only high-class discerning aristocrats permitted beyond this point
+### only discerning high-class aristocrats are permitted beyond this point
 
-### `Strata.setup` for localStorage persistence etc
+#### `Trunk.setup` for localStorage persistence etc
 - simple setup
   ```ts
-  const {strata} = await Strata.setup({
+  const {trunk} = await Trunk.setup({
     version: 1, // 👈 bump whenever your 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"
 
   const kv = new Kv(new StorageDriver())
-  const store = kv.store<any>("strata")
+  const store = kv.store<any>("appState")
 
-  const {strata} = await Strata.setup({
+  const {trunk} = await Trunk.setup({
     version: 1,
     initialState: {count: 0},
     persistence: {
@@ -101,21 +193,21 @@
   })
   ```
 
-### `Chronstrata` for undo/redo history
+#### `Chronobranch` for undo/redo history
 - first, put a `Chronicle` into your state tree
   ```ts
-  const strata = new Strata({
+  const trunk = new Trunk({
     count: 0,
-    snacks: Strata.chronicle({
+    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 `Chronstrata` which is like a substrata
+- second, make a `Chronobranch` which is like a branch, but is concerned with history
   ```ts
-  const snacks = strata.chronstrata(64, s => s.snacks)
+  const snacks = trunk.chronobranch(64, s => s.snacks)
     //                               \
     //               how many past snapshots to store
   ```
@@ -134,8 +226,17 @@
   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
+- 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 💀
+
+<br/>
+
+## 🪄 tracker — integrations
+- ```ts
+  import {tracker} from "@e280/strata/tracker"
+  ```
+- all reactivity is orchestrated by the `tracker`
+- if you are integrating a new state object, or a new view layer that needs to react to state changes, just read [tracker.ts](./s/tracker/tracker.ts)
 
 <br/>
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/strata",
-	"version": "0.0.0-5",
+	"version": "0.0.0-7",
 	"description": "state management",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -10,6 +10,13 @@
 		"x",
 		"s"
 	],
+	"exports": {
+		".": "./x/index.js",
+		"./signals": "./x/signals/index.js",
+		"./tracker": "./x/tracker/index.js",
+		"./tree": "./x/tree/index.js",
+		"./*": "./*"
+	},
 	"scripts": {
 		"build": "run-s _clean _links _tsc",
 		"test": "node x/tests.test.js",
@@ -24,7 +31,7 @@
 	},
 	"devDependencies": {
 		"@e280/science": "^0.0.5",
-		"@types/node": "^24.0.4",
+		"@types/node": "^24.0.7",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.8.3"
 	},

package/s/index.ts

@@ -1,7 +1,5 @@
 
-export * from "./parts/chronstrata.js"
-export * from "./parts/persistence.js"
-export * from "./parts/strata.js"
-export * from "./parts/substrata.js"
-export * from "./parts/types.js"
+export * from "./signals/index.js"
+export * from "./tracker/index.js"
+export * from "./tree/index.js"
 

package/s/signals/index.ts

@@ -0,0 +1,5 @@
+
+export * from "./parts/computed.js"
+export * from "./parts/effect.js"
+export * from "./parts/signal.js"
+

package/s/signals/parts/computed.ts

@@ -0,0 +1,53 @@
+
+import {initEffect} from "./effect.js"
+import {SignalCore} from "./signal.js"
+
+export type Computed<V> = {(): V} & ComputedCore<V>
+
+export function computed<V>(fn: () => V) {
+	const core = new ComputedCore<V>(fn)
+
+	function f(): V {
+		return (f as any).value
+	}
+
+	Object.setPrototypeOf(f, ComputedCore.prototype)
+	Object.assign(f, core)
+
+	return f as Computed<V>
+}
+
+export class ComputedCore<V> extends SignalCore<V> {
+	_dirty = false
+	_formula: () => V
+	_effect: (() => void) | undefined
+
+	constructor(formula: () => V) {
+		super(undefined as any)
+		this._formula = formula
+	}
+
+	get() {
+		if (!this._effect) {
+			const {result, dispose} = initEffect(this._formula, () => this._dirty = true)
+			this._effect = dispose
+			this.sneak = result
+		}
+		if (this._dirty) {
+			this._dirty = false
+			super.set(this._formula())
+		}
+		return super.get()
+	}
+
+	async set() {
+		throw new Error("computed is readonly")
+	}
+
+	dispose() {
+		if (this._effect)
+			this._effect()
+		super.dispose()
+	}
+}
+

package/s/signals/parts/effect.ts

@@ -0,0 +1,23 @@
+
+import {debounce} from "@e280/stz"
+import {tracker} from "../../tracker/tracker.js"
+
+export function effect<C = void>(collector: () => C, responder: () => void = collector) {
+	return initEffect<C>(collector, responder).dispose
+}
+
+export function initEffect<C = void>(collector: () => C, responder: () => void = collector) {
+	const {seen, result} = tracker.seen(collector)
+	const fn = debounce(0, responder)
+
+	const disposers: (() => void)[] = []
+	const dispose = () => disposers.forEach(d => d())
+
+	for (const saw of seen) {
+		const dispose = tracker.changed(saw, fn)
+		disposers.push(dispose)
+	}
+
+	return {result, dispose}
+}
+

package/s/signals/parts/signal.ts

@@ -0,0 +1,66 @@
+
+import {sub} from "@e280/stz"
+import {tracker} from "../../tracker/tracker.js"
+
+export type Signal<V> = {
+	(): V
+	(v: V): Promise<void>
+	(v?: V): V | Promise<void>
+} & SignalCore<V>
+
+export function signal<V>(value: V) {
+	const core = new SignalCore(value)
+
+	function fn(): V
+	function fn(v: V): Promise<void>
+	function fn(v?: V): V | Promise<void> {
+		return v !== undefined
+			? (fn as any).set(v)
+			: (fn as any).get()
+	}
+
+	Object.setPrototypeOf(fn, SignalCore.prototype)
+	Object.assign(fn, core)
+
+	return fn as Signal<V>
+}
+
+export class SignalCore<V> {
+	on = sub<[V]>()
+	published: Promise<V>
+
+	constructor(public sneak: V) {
+		this.published = Promise.resolve(sneak)
+	}
+
+	get() {
+		tracker.see(this)
+		return this.sneak
+	}
+
+	async set(v: V) {
+		if (v !== this.sneak)
+			await this.publish(v)
+	}
+
+	get value() {
+		return this.get()
+	}
+
+	set value(v: V) {
+		this.set(v)
+	}
+
+	async publish(v = this.get()) {
+		this.sneak = v
+		await Promise.all([
+			tracker.change(this),
+			this.published = this.on.pub(v).then(() => v),
+		])
+	}
+
+	dispose() {
+		this.on.clear()
+	}
+}
+

package/s/signals/signals.test.ts

@@ -0,0 +1,181 @@
+
+import {Science, test, expect} from "@e280/science"
+
+import {effect} from "./parts/effect.js"
+import {signal} from "./parts/signal.js"
+import {computed} from "./parts/computed.js"
+
+export default Science.suite({
+	"signal get/set value": test(async() => {
+		const count = signal(0)
+		expect(count.value).is(0)
+
+		count.value++
+		expect(count.value).is(1)
+
+		count.value = 5
+		expect(count.value).is(5)
+	}),
+
+	"signal fn syntax": test(async() => {
+		const count = signal(0)
+		expect(count()).is(0)
+
+		count(count() + 1)
+		expect(count()).is(1)
+
+		count(5)
+		expect(count()).is(5)
+	}),
+
+	"signal syntax interop": test(async() => {
+		const count = signal(0)
+
+		count.value = 1
+		expect(count()).is(1)
+	}),
+
+	"signal on is not debounced": test(async() => {
+		const count = signal(1)
+		let runs = 0
+		count.on(() => void runs++)
+		await count.set(2)
+		await count.set(3)
+		expect(runs).is(2)
+	}),
+
+	"signal on only fires on change": test(async() => {
+		const count = signal(1)
+		let runs = 0
+		count.on(() => void runs++)
+		await count.set(2)
+		await count.set(2)
+		expect(runs).is(1)
+	}),
+
+	"effect tracks signal changes": test(async() => {
+		const count = signal(1)
+		let doubled = 0
+
+		effect(() => doubled = count.value * 2)
+		expect(doubled).is(2)
+
+		await count.set(3)
+		expect(doubled).is(6)
+	}),
+
+	"effect is only called when signal actually changes": test(async() => {
+		const count = signal(1)
+		let runs = 0
+		effect(() => {
+			count.get()
+			runs++
+		})
+		expect(runs).is(1)
+		await count.set(999)
+		expect(runs).is(2)
+		await count.set(999)
+		expect(runs).is(2)
+	}),
+
+	"effects are debounced": test(async() => {
+		const count = signal(1)
+		let runs = 0
+		effect(() => {
+			count.get()
+			runs++
+		})
+		expect(runs).is(1)
+		count.value++
+		count.value++
+		await count.set(count.get() + 1)
+		expect(runs).is(2)
+	}),
+
+	"effects can be disposed": test(async() => {
+		const count = signal(1)
+		let doubled = 0
+
+		const dispose = effect(() => doubled = count.value * 2)
+		expect(doubled).is(2)
+
+		await count.set(3)
+		expect(doubled).is(6)
+
+		dispose()
+		await count.set(4)
+		expect(doubled).is(6) // old value
+	}),
+
+	"signal set promise waits for effects": test(async() => {
+		const count = signal(1)
+		let doubled = 0
+
+		effect(() => doubled = count.value * 2)
+		expect(doubled).is(2)
+
+		await count.set(3)
+		expect(doubled).is(6)
+	}),
+
+	"effect only runs on change": test(async() => {
+		const sig = signal("a")
+		let runs = 0
+
+		effect(() => {
+			sig.value
+			runs++
+		})
+		expect(runs).is(1)
+
+		await sig.set("a")
+		expect(runs).is(1)
+
+		await sig.set("b")
+		expect(runs).is(2)
+	}),
+
+	"computed values": test(async() => {
+		const a = signal(2)
+		const b = signal(3)
+		const sum = computed(() => a.value + b.value)
+		expect(sum.value).is(5)
+
+		await a.set(5)
+		expect(sum.value).is(8)
+
+		await b.set(7)
+		expect(sum.value).is(12)
+	}),
+
+	"computed is lazy": test(async() => {
+		const a = signal(1)
+		let runs = 0
+
+		const comp = computed(() => {
+			runs++
+			return a.value * 10
+		})
+
+		expect(runs).is(0)
+		expect(comp.value).is(10)
+		expect(runs).is(1)
+
+		await a.set(2)
+		expect(runs).is(1)
+		expect(comp.value).is(20)
+		expect(runs).is(2)
+	}),
+
+	"computed fn syntax": test(async() => {
+		const a = signal(2)
+		const b = signal(3)
+		const sum = computed(() => a.value + b.value)
+		expect(sum.value).is(5)
+
+		await a.set(5)
+		expect(sum.value).is(8)
+		expect(sum()).is(8)
+	}),
+})
+