@e280/strata 0.0.0-6 → 0.0.0-8

package/README.md

@@ -4,12 +4,12 @@
 <br/>
 
 # ⛏️ strata
-📦 `npm install @e280/strata`  
-🫩 probably my tenth state management library, lol  
-
-<br/>
 
 ### 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  
@@ -23,70 +23,91 @@
 <br/>
 
 ## 🚦 signals — *ephemeral view-level state*
-- `@e280/strata/signals`
+```ts
+import {signal, effect, computed} from "@e280/strata"
+```
+
+### each signal holds a value
+- **create a signal**
   ```ts
-  import {signal, effect, computed} from "@e280/strata"
+  const count = signal(0)
   ```
-- **signals are little bundles of joy**
+- **read a signal**
   ```ts
-  const count = signal(0)
-
-  console.log(count.get())
-    // 0
-
-  count.set(1)
+  count() // 0
+  ```
+- **set a signal**
+  ```ts
+  count(1)
+  ```
+- **set a signal, and await effect propagation**
+  ```ts
+  await count(2)
+  ```
 
-  console.log(count.value)
-    // 1
+### 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
   ```
-  - components/views will auto rerender when relevant signals change  
-    (if your component/view library is cool an integrates with `tracker`)
-  - three ways to get it
-    ```ts
-    count() // 1
-    count.get() // 1
-    count.value // 1
-    ```
-  - three ways to set it
-    ```ts
-    await count(2)
-    await count.set(2)
-    count.value = 2
-    ```
-  - using `await` here allows you to wait for downstream effects to finish
-- **effects are run when the relevant signals change**
+  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()))
-    // 2
+    // 1
+    // the system detects 'count' is relevant
 
   count.value++
-    // 3
+    // 2
+    // when count is changed, the effect fn is run
   ```
-- **computed signals are super lazy**
+
+### `signal.derive` and `signal.lazy` are computed signals
+- **signal.derive**  
+  is for combining signals
   ```ts
-  const tenly = computed(() => {
-    console.log("recomputed!")
-    return count() * 10
-  })
+  const a = signal(1)
+  const b = signal(10)
+  const product = signal.derive(() => a() * b())
 
-  console.log(tenly())
-    // "recomputed!"
-    // 30
+  product() // 10
 
-  await count(4)
+  // change a dependency,
+  // and the derived signal is automatically updated
+  await a.set(2)
 
-  console.log(tenly.value)
-    // "recomputed!"
-    // 40
+  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*
-- `@e280/strata/tree`
 - 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
 
 #### `Trunk` is your app's state tree root
@@ -131,28 +152,29 @@
   ```
 - you can branch a branch
 
-#### watch for mutations
+#### `on` to watch for mutations
 - on the trunk, we can listen deeply for mutations within the whole tree
   ```ts
-  trunk.watch(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.watch(s => console.log(s.peanuts))
+  snacks.on(s => console.log(s.peanuts))
   ```
-- watch returns a fn to stop listening
+- on returns a fn to stop listening
   ```ts
-  const stop = trunk.watch(s => console.log(s.count))
+  const stop = trunk.on(s => console.log(s.count))
   stop() // stop listening
   ```
 
 ### 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 your change state schema!
+    version: 1, // 👈 bump whenever you change state schema!
     initialState: {count: 0},
   })
   ```
@@ -186,7 +208,7 @@
   })
   ```
   - *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
+- second, make a `Chronobranch` which is like a branch, but is concerned with history
   ```ts
   const snacks = trunk.chronobranch(64, s => s.snacks)
     //                               \
@@ -207,13 +229,15 @@
   snacks.undoable // 2
   snacks.redoable // 1
   ```
-- chronobranch can have its own branch — all their mutations advance history
+- 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
-- `@e280/strata/tracker`
+- ```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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/strata",
-	"version": "0.0.0-6",
+	"version": "0.0.0-8",
 	"description": "state management",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -29,9 +29,12 @@
 		"_tsc": "tsc",
 		"_tscw": "tsc -w"
 	},
+	"dependencies": {
+		"@e280/stz": "^0.0.0-28"
+	},
 	"devDependencies": {
 		"@e280/science": "^0.0.5",
-		"@types/node": "^24.0.7",
+		"@types/node": "^24.0.10",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.8.3"
 	},
@@ -46,8 +49,5 @@
 	},
 	"bugs": {
 		"url": "https://github.com/e280/strata/issues"
-	},
-	"dependencies": {
-		"@e280/stz": "^0.0.0-27"
 	}
 }

package/s/signals/index.ts

@@ -1,5 +1,6 @@
 
-export * from "./parts/computed.js"
+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

@@ -2,11 +2,11 @@
 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 effect(collector: () => void, responder: () => void = collector) {
+	return collectorEffect(collector, responder).dispose
 }
 
-export function initEffect<C = void>(collector: () => C, responder: () => void = collector) {
+export function collectorEffect<C = void>(collector: () => C, responder: () => void = collector) {
 	const {seen, result} = tracker.seen(collector)
 	const fn = debounce(0, responder)
 

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

@@ -1,16 +1,28 @@
 
-import {sub} from "@e280/stz"
-import {tracker} from "../../tracker/tracker.js"
+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<void>
 	(v?: V): V | Promise<void>
-} & SignalCore<V>
 
-export function signal<V>(value: V) {
-	const core = new SignalCore(value)
+	kind: "signal"
 
+	sneak: V
+	value: V
+	on: Sub<[V]>
+	get(): V
+	set(v: V): Promise<void>
+	publish(v?: V): Promise<void>
+	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> {
@@ -19,48 +31,14 @@ export function signal<V>(value: 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>
 }
 
-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()
-	}
-}
+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,150 @@
+
+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)
+	}
+
+	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
+		}
+
+		return promise
+	}
+}
+
+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()
+	}
+}
+