@e280/strata 0.0.0-0 → 0.0.0-10

package/README.md

@@ -1,71 +1,247 @@
 
+![](https://i.imgur.com/h7FohWa.jpeg)
+
+<br/>
+
 # ⛏️ strata
 
-**my 10th state management library, probably**
-- 📦 `npm install @e280/strata`
+### get in loser, we're managing state
+📦 `npm install @e280/strata`  
+🧙‍♂️ probably my tenth state management library, lol  
+💁 it's all about rerendering ui when data changes  
+
+🚦 **signals** — ephemeral view-level state  
+🌳 **tree** — persistent app-level state  
+🪄 **tracker** — reactivity integration hub  
+
+<br/>
+
+> [!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)
+  ```
+
+### pick your poison
+- **signals hipster fn syntax**
+  ```ts
+  count() // get
+  await count(2) // set
+  ```
+  > to achieve this hipster syntax i had to make the implementation so damn cursed, lol 💀
+- **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
+  ```
+
+### `signal.derive` and `signal.lazy` are computed signals
+- **signal.derive**  
+  is for combining signals
+  ```ts
+  const a = signal(1)
+  const b = signal(10)
+  const product = signal.derive(() => a() * b())
+
+  product() // 10
+
+  // change a dependency,
+  // and the derived signal is automatically updated
+  await a.set(2)
+
+  product() // 20
+  ```
+- **signal.lazy**  
+  is for making special optimizations.  
+  it's like derive, except it cannot trigger effects,  
+  because it's so lazy it only computes the value on read, and only when necessary.  
+  > ⚠️ *i repeat: lazy signals cannot trigger effects!*
+
+<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
+- localStorage persistence, cross-tab sync, undo/redo history
+- no spooky-dookie proxy magic — just god's honest javascript
 
-## good state management
-
-### establish a strata with some state
+#### `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,
-    stuff: {
+    snacks: {
       peanuts: 8,
-      items: ["hello", "world"],
+      bag: ["popcorn", "butter"],
     },
   })
 
-  strata.state.count // 0
-  strata.state.stuff.peanuts // 8
+  trunk.state.count // 0
+  trunk.state.snacks.peanuts // 8
   ```
 
-### how mutations work
+#### formal mutations to change state
 - ⛔ informal mutations are denied
   ```ts
-  strata.state.count++ // error is thrown
+  trunk.state.count++ // error is thrown
   ```
-- ✅ formal mutation is allowed
+- ✅ formal mutations are allowed
   ```ts
-  await strata.mutate(s => s.count++)
+  await trunk.mutate(s => s.count++)
   ```
 
-### substrata and selectors
-- a substrata is a view into a subset of the state tree
+#### `Branch` 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 = trunk.branch(s => s.snacks)
   ```
-- run substrata mutations
+- run branch 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 branch a branch
 
-### onMutation events
-- you can listen to global mutations on the strata
+#### `on` to watch for mutations
+- on the trunk, we can listen deeply for mutations within the whole tree
   ```ts
-  strata.onMutation(s => console.log(s.count))
+  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
   ```
 
-- substrata listeners don't care about outside changes
+### only discerning high-class aristocrats are permitted beyond this point
+
+#### `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
-  stuff.onMutation(s => console.log(s.peanuts))
+  import {Kv, StorageDriver} from "@e280/kv"
+
+  const kv = new Kv(new StorageDriver())
+  const store = kv.store<any>("appState")
+
+  const {trunk} = await Trunk.setup({
+    version: 1,
+    initialState: {count: 0},
+    persistence: {
+      store,
+      onChange: StorageDriver.onStorageEvent,
+    },
+  })
   ```
 
-- onMutation returns a fn to stop listening
+#### `Chronobranch` for undo/redo history
+- first, put a `Chronicle` into your state tree
   ```ts
-  const stop = strata.onMutation(s => console.log(s.count))
-  stop() // stop listening
+  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 💀
+
+<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/>
 
 ## a buildercore e280 project
 free and open source by https://e280.org/  

package/package.json

@@ -1,15 +1,21 @@
 {
 	"name": "@e280/strata",
-	"version": "0.0.0-0",
+	"version": "0.0.0-10",
 	"description": "state management",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
 	"type": "module",
-	"main": "x/index.js",
+	"main": "./x/index.js",
 	"files": [
 		"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",
@@ -22,11 +28,14 @@
 		"_tsc": "tsc",
 		"_tscw": "tsc -w"
 	},
+	"dependencies": {
+		"@e280/stz": "^0.0.0-35"
+	},
 	"devDependencies": {
-		"@e280/science": "^0.0.5",
-		"@types/node": "^24.0.3",
+		"@e280/science": "^0.0.6",
+		"@types/node": "^24.3.0",
 		"npm-run-all": "^4.1.5",
-		"typescript": "^5.8.3"
+		"typescript": "^5.9.2"
 	},
 	"keywords": [
 		"state",
@@ -39,8 +48,5 @@
 	},
 	"bugs": {
 		"url": "https://github.com/e280/strata/issues"
-	},
-	"dependencies": {
-		"@e280/stz": "^0.0.0-24"
 	}
 }

package/s/index.ts

@@ -1,5 +1,5 @@
 
-export {Strata} from "./parts/strata.js"
-export {Substrata} from "./parts/substrata.js"
-export {Options, Mutator, Selector} 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,6 @@
+
+export * from "./parts/lazy.js"
+export * from "./parts/effect.js"
+export * from "./parts/signal.js"
+export * from "./parts/types.js"
+

package/s/signals/parts/derive.ts

@@ -0,0 +1,29 @@
+
+import {Sub} from "@e280/stz"
+import {SignalOptions} from "./types.js"
+import {DerivedCore, processSignalOptions} from "./units.js"
+
+export type DerivedSignal<V> = {
+	(): V
+	kind: "derived"
+
+	sneak: V
+	on: Sub<[V]>
+	get(): V
+	get value(): V
+	dispose(): void
+}
+
+export function derive<V>(formula: () => V, options: Partial<SignalOptions> = {}) {
+	function fn(): V {
+		return (fn as any).value
+	}
+
+	const o = processSignalOptions(options)
+	const core = DerivedCore.make<V>(fn as any, formula, o)
+	Object.setPrototypeOf(fn, DerivedCore.prototype)
+	Object.assign(fn, core)
+
+	return fn as DerivedSignal<V>
+}
+

package/s/signals/parts/effect.ts

@@ -0,0 +1,23 @@
+
+import {debounce} from "@e280/stz"
+import {tracker} from "../../tracker/tracker.js"
+
+export function effect(collector: () => void, responder: () => void = collector) {
+	return collectorEffect(collector, responder).dispose
+}
+
+export function collectorEffect<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/lazy.ts

@@ -0,0 +1,27 @@
+
+import {SignalOptions} from "./types.js"
+import {LazyCore, processSignalOptions} from "./units.js"
+
+export type LazySignal<V> = {
+	(): V
+	kind: "lazy"
+
+	sneak: V
+	get(): V
+	get value(): V
+	dispose(): void
+}
+
+export function lazy<V>(formula: () => V, options: Partial<SignalOptions> = {}) {
+	function fn(): V {
+		return (fn as any).value
+	}
+
+	const o = processSignalOptions(options)
+	const core = new LazyCore<V>(formula, o)
+	Object.setPrototypeOf(fn, LazyCore.prototype)
+	Object.assign(fn, core)
+
+	return fn as LazySignal<V>
+}
+

package/s/signals/parts/signal.ts

@@ -0,0 +1,44 @@
+
+import {Sub} from "@e280/stz"
+
+import {lazy} from "./lazy.js"
+import {derive} from "./derive.js"
+import {SignalOptions} from "./types.js"
+import {processSignalOptions, SignalCore} from "./units.js"
+
+export type Signal<V> = {
+	(): V
+	(v: V): Promise<V>
+	(v?: V): V | Promise<V>
+
+	kind: "signal"
+
+	sneak: V
+	value: V
+	on: Sub<[V]>
+	get(): V
+	set(v: V): Promise<V>
+	publish(v?: V): Promise<V>
+	dispose(): void
+} & SignalCore<V>
+
+export function signal<V>(value: V, options: Partial<SignalOptions> = {}) {
+	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()
+	}
+
+	const o = processSignalOptions(options)
+	const core = new SignalCore(value, o)
+	Object.setPrototypeOf(fn, SignalCore.prototype)
+	Object.assign(fn, core)
+
+	return fn as Signal<V>
+}
+
+signal.lazy = lazy
+signal.derive = derive
+

package/s/signals/parts/types.ts

@@ -0,0 +1,11 @@
+
+import {Signal} from "./signal.js"
+import {LazySignal} from "./lazy.js"
+import {DerivedSignal} from "./derive.js"
+
+export type Signaloid<V> = Signal<V> | DerivedSignal<V> | LazySignal<V>
+
+export type SignalOptions = {
+	compare: (a: any, b: any) => boolean
+}
+

package/s/signals/parts/units.ts

@@ -0,0 +1,152 @@
+
+import {sub} from "@e280/stz"
+import {SignalOptions} from "./types.js"
+import {collectorEffect} from "./effect.js"
+import {tracker} from "../../tracker/tracker.js"
+
+const defaultSignalOptions: SignalOptions = {
+	compare: (a, b) => a === b
+}
+
+export function processSignalOptions(options: Partial<SignalOptions> = {}) {
+	return {...defaultSignalOptions, ...options}
+}
+
+export class ReadableSignal<V> {
+	constructor(public sneak: V) {}
+
+	get() {
+		tracker.see(this)
+		return this.sneak
+	}
+
+	get value() {
+		return this.get()
+	}
+}
+
+export class ReactiveSignal<V> extends ReadableSignal<V> {
+	on = sub<[V]>()
+
+	dispose() {
+		this.on.clear()
+	}
+}
+
+export class SignalCore<V> extends ReactiveSignal<V> {
+	kind: "signal" = "signal"
+	_lock = false
+
+	constructor(sneak: V, public _options: SignalOptions) {
+		super(sneak)
+	}
+
+	async set(v: V) {
+		const isChanged = !this._options.compare(this.sneak, v)
+		if (isChanged)
+			await this.publish(v)
+		return v
+	}
+
+	get value() {
+		return this.get()
+	}
+
+	set value(v: V) {
+		this.set(v)
+	}
+
+	async publish(v = this.get()) {
+		if (this._lock)
+			throw new Error("forbid circularity")
+
+		let promise = Promise.resolve()
+
+		try {
+			this._lock = true
+			this.sneak = v
+			promise = Promise.all([
+				tracker.change(this),
+				this.on.pub(v),
+			]) as any
+		}
+		finally {
+			this._lock = false
+		}
+
+		await promise
+		return v
+	}
+}
+
+export class LazyCore<V> extends ReadableSignal<V> {
+	kind: "lazy" = "lazy"
+
+	_dirty = false
+	_effect: (() => void) | undefined
+
+	constructor(public _formula: () => V, public _options: SignalOptions) {
+		super(undefined as any)
+	}
+
+	get() {
+		if (!this._effect) {
+			const {result, dispose} = collectorEffect(this._formula, () => this._dirty = true)
+			this._effect = dispose
+			this.sneak = result
+		}
+		if (this._dirty) {
+			this._dirty = false
+
+			const v = this._formula()
+			const isChanged = !this._options.compare(this.sneak, v)
+			if (isChanged) {
+				this.sneak = v
+				tracker.change(this)
+			}
+		}
+		return super.get()
+	}
+
+	get value() {
+		return this.get()
+	}
+
+	dispose() {
+		if (this._effect)
+			this._effect()
+	}
+}
+
+export class DerivedCore<V> extends ReactiveSignal<V> {
+	static make<V>(that: DerivedCore<V>, formula: () => V, options: SignalOptions) {
+		const {result, dispose} = collectorEffect(formula, async() => {
+			const value = formula()
+			const isChanged = !options.compare(that.sneak, value)
+			if (isChanged) {
+				that.sneak = value
+				await Promise.all([
+					tracker.change(that),
+					that.on.pub(value),
+				])
+			}
+		})
+		return new this(result, dispose)
+	}
+
+	kind: "derived" = "derived"
+
+	constructor(initialValue: V, public _effect: () => void) {
+		super(initialValue)
+	}
+
+	get value() {
+		return this.get()
+	}
+
+	dispose() {
+		super.dispose()
+		this._effect()
+	}
+}
+