@e280/strata 0.0.0-7 → 0.0.0-8

package/README.md

@@ -8,6 +8,7 @@
 ### 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  
@@ -43,9 +44,6 @@ import {signal, effect, computed} from "@e280/strata"
   ```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`.
 
 ### pick your poison
 - **signals hipster fn syntax**
@@ -53,6 +51,7 @@ import {signal, effect, computed} from "@e280/strata"
   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
@@ -80,33 +79,36 @@ import {signal, effect, computed} from "@e280/strata"
     // 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
+
+### `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!"
-    // 20
+  product() // 10
 
-  await count(3)
+  // change a dependency,
+  // and the derived signal is automatically updated
+  await a.set(2)
 
-  console.log(tenly.value)
-    // "recomputed!"
-    // 30
+  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
-- separate but compatible with signals
 
 #### `Trunk` is your app's state tree root
 - better stick to json-friendly serializable data
@@ -150,28 +152,29 @@ import {signal, effect, computed} from "@e280/strata"
   ```
 - 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},
   })
   ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/strata",
-	"version": "0.0.0-7",
+	"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()
+	}
+}
+

package/s/signals/signals.test.ts

@@ -1,9 +1,9 @@
 
-import {Science, test, expect} from "@e280/science"
+import {Science, test, expect, spy} from "@e280/science"
 
+import {lazy} from "./parts/lazy.js"
 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() => {
@@ -53,6 +53,19 @@ export default Science.suite({
 		expect(runs).is(1)
 	}),
 
+	"signal on circularity forbidden": test(async() => {
+		const count = signal(1)
+		let runs = 0
+		count.on(async() => {
+			await count.set(99)
+			runs++
+		})
+		expect(async() => {
+			await count.set(2)
+		}).throwsAsync()
+		expect(runs).is(0)
+	}),
+
 	"effect tracks signal changes": test(async() => {
 		const count = signal(1)
 		let doubled = 0
@@ -135,10 +148,10 @@ export default Science.suite({
 		expect(runs).is(2)
 	}),
 
-	"computed values": test(async() => {
+	"lazy values": test(async() => {
 		const a = signal(2)
 		const b = signal(3)
-		const sum = computed(() => a.value + b.value)
+		const sum = lazy(() => a.value + b.value)
 		expect(sum.value).is(5)
 
 		await a.set(5)
@@ -148,11 +161,93 @@ export default Science.suite({
 		expect(sum.value).is(12)
 	}),
 
-	"computed is lazy": test(async() => {
+	"effect reacts to derived changes": test(async() => {
+		const a = signal(1)
+		const b = signal(10)
+		const product = signal.derive(() => a.value * b.value)
+
+		let mutations = 0
+		effect(() => {
+			void product.get()
+			mutations++
+		})
+		expect(product.value).is(10)
+		expect(mutations).is(1)
+
+		await a.set(2)
+		expect(product.value).is(20)
+		expect(mutations).is(2)
+
+		await a.set(3)
+		expect(product.value).is(30)
+		expect(mutations).is(3)
+	}),
+
+	"effect doesn't overreact to derived": test(async() => {
+		const a = signal(1)
+		const b = signal(10)
+		const product = signal.derive(() => a.value * b.value)
+
+		const derivedSpy = spy(() => {})
+		product.on(derivedSpy)
+
+		let mutations = 0
+		effect(() => {
+			a.get()
+			product.get()
+			mutations++
+		})
+		expect(product.value).is(10)
+		expect(mutations).is(1)
+		expect(derivedSpy.spy.calls.length).is(0)
+
+		await a.set(2)
+		expect(product.value).is(20)
+		expect(mutations).is(2)
+		expect(derivedSpy.spy.calls.length).is(1)
+	}),
+
+	"derived.on": test(async() => {
+		const a = signal(1)
+		const b = signal(10)
+		const product = signal.derive(() => a.value * b.value)
+		expect(product.value).is(10)
+
+		const mole = spy((_v: number) => {})
+		product.on(mole)
+		expect(mole.spy.calls.length).is(0)
+
+		await a.set(2)
+		expect(product.value).is(20)
+		expect(mole.spy.calls.length).is(1)
+		expect(mole.spy.calls[0].args[0]).is(20)
+	}),
+
+	"derived.on not called if result doesn't change": test(async() => {
+		const a = signal(1)
+		const b = signal(10)
+		const product = signal.derive(() => a.value * b.value)
+		expect(product.value).is(10)
+
+		const mole = spy((_v: number) => {})
+		product.on(mole)
+		expect(mole.spy.calls.length).is(0)
+
+		await a.set(2)
+		expect(product.value).is(20)
+		expect(mole.spy.calls.length).is(1)
+		expect(mole.spy.calls[0].args[0]).is(20)
+
+		await a.set(2)
+		expect(product.value).is(20)
+		expect(mole.spy.calls.length).is(1)
+	}),
+
+	"lazy is lazy": test(async() => {
 		const a = signal(1)
 		let runs = 0
 
-		const comp = computed(() => {
+		const comp = lazy(() => {
 			runs++
 			return a.value * 10
 		})
@@ -167,10 +262,10 @@ export default Science.suite({
 		expect(runs).is(2)
 	}),
 
-	"computed fn syntax": test(async() => {
+	"lazy fn syntax": test(async() => {
 		const a = signal(2)
 		const b = signal(3)
-		const sum = computed(() => a.value + b.value)
+		const sum = lazy(() => a.value + b.value)
 		expect(sum.value).is(5)
 
 		await a.set(5)

package/s/tests.test.ts

@@ -47,7 +47,7 @@ await Science.run({
 			expect(order[2]).is("after")
 		}),
 
-		"branch can include signal value": test.skip(async() => {
+		"branch can include signal value": test(async() => {
 			const bingus = signal(101)
 			const trunk = new Trunk({count: 1})
 			const branch = trunk.branch(s => ({

package/s/tree/index.ts

@@ -1,7 +1,7 @@
 
+export * from "./parts/branch.js"
 export * from "./parts/chronobranch.js"
 export * from "./parts/persistence.js"
 export * from "./parts/trunk.js"
-export * from "./parts/branch.js"
 export * from "./parts/types.js"