@e280/strata 0.2.7 → 0.3.0-0

package/LICENSE

@@ -1,7 +1,7 @@
 
 MIT License
 
-Copyright (c) 2025 Chase Moskal
+Copyright (c) 2026 Chase Moskal
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -17,6 +17,7 @@
 🚦 [**signals**](#signals) — ephemeral view-level state  
 🔮 [**prism**](#prism) — app-level state tree  
 🪄 [**tracker**](#tracker) — reactivity integration hub  
+⚛️ [**react**](#react) — optional bindings for react  
 
 
 
@@ -28,7 +29,7 @@
 > *ephemeral view-level state*
 
 ```ts
-import {signal, effect} from "@e280/strata"
+import {signal, effect, derived, lazy} from "@e280/strata"
 ```
 
 ### 🚦 each signal holds a value
@@ -45,7 +46,7 @@ import {signal, effect} from "@e280/strata"
   ```ts
   $count(1)
   ```
-- **write signal *(and await all downstream effects)***
+- 🤯 **await all downstream effects***
   ```ts
   await $count(2)
   ```
@@ -85,13 +86,12 @@ import {signal, effect} from "@e280/strata"
     // when $count is changed, the effect fn is run
   ```
 
-### 🚦 `signal.derived` and `signal.lazy` are computed signals
-- **signal.derived**  
-  is for combining signals, like a formula
+### 🚦 computed signals
+- **derived,** for combining signals, like a formula
   ```ts
   const $a = signal(1)
   const $b = signal(10)
-  const $product = signal.derived(() => $a() * $b())
+  const $product = derived(() => $a() * $b())
 
   $product() // 10
 
@@ -101,52 +101,17 @@ import {signal, effect} from "@e280/strata"
 
   $product() // 20
   ```
-- **signal.lazy**  
-  is for making special optimizations.  
+- **lazy,** for making special optimizations.  
   it's like derived, except it cannot trigger effects,  
   because it's so damned lazy, it only computes the value on read, and only when necessary.  
   > *i repeat: lazy signals cannot trigger effects!*
 
-### 🚦 core primitive classes
-- **the hipster-fn syntax has a slight performance cost**
-- **you can instead use the core primitive classes**
-  ```ts
-  const $count = new Signal(1)
-  ```
-  core signals work mostly the same
-  ```ts
-  // ✅ legal
-  $count.get()
-  $count.set(2)
-  ```
-  except you cannot directly invoke them
-  ```ts
-  // ⛔ illegal on core primitives
-  $count()
-  $count(2)
-  ```
-- **same thing for derived/lazy**
-  ```ts
-  const $product = new Derived(() => $a() * $b())
-  ```
-  ```ts
-  const $product = new Lazy(() => $a() * $b())
-  ```
-- **conversions**
-  - all core primitives (signal/derived/lazy) have a convert-to-hipster-fn method
-    ```ts
-    new Signal(1).fn() // SignalFn<number>, hipster-fn
-    ```
-  - and all hipster fns (signal/derived/lazy) have a `.core` property to get the primitive
-    ```ts
-    signal(0).core // Signal<number>, primitive instance
-    ```
-
-### 🚦 types
-- **`Signaly<V>`** — can be `Signal<V>` or `Derived<V>` or `Lazy<V>`
+### 🚦 types and such
+- **`Signaly<Value>`** — can be `Signal<Value>` or `Derived<Value>` or `Lazy<Value>`
   - these are types for the core primitive classes
-- **`SignalyFn<V>`** — can be `SignalFn<V>` or `DerivedFn<V>` or `LazyFn<V>`
-  - these `*Fn` types are for the hipster-fn-syntax enabled variants
+- **the classes are funky**
+  - Signal, Derived, and Lazy classes cannot be subclassed or extended, due to spooky magic we've done to make the instances callable as functions (hipster syntax).
+  - however, at least `$count instanceof Signal` works, so at least that's working.
 
 
 
@@ -363,6 +328,50 @@ note, the *items* that the tracker tracks can be any object, or symbol.. the tra
 
 
 
+<br/><br/>
+
+<a id="react"></a>
+
+## 🍋 react bindings
+> *easy peasy*
+
+### ⚛️ react setup
+
+1. setup your `strata.ts` module
+    ```ts
+    import * as react from "react"
+    import {react as strata} from "@e280/strata"
+
+    export const {component, useStrata} = strata(react)
+    ```
+1. now you import `component` and `useStrata` from your module
+    ```ts
+    import {component, useStrata} from "./strata.js"
+    ```
+
+### ⚛️ `component` enables fully automatic reactive re-rendering
+```ts
+const $count = signal(0)
+
+export const MyCounter = component(() => {
+  const add = () => $count.value++
+  return <button onClick={add}>{$count()}</button>
+})
+```
+
+### ⚛️ `useStrata` for a manual hands-on approach
+```ts
+const $count = signal(0)
+
+export const MyCounter = () => {
+  const count = useStrata(() => $count())
+  const add = () => $count.value++
+  return <button onClick={add}>{count}</button>
+}
+```
+
+
+
 <br/><br/>
 
 ## 🧑‍💻 strata is by e280

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/strata",
-	"version": "0.2.7",
+	"version": "0.3.0-0",
 	"description": "state management",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -30,12 +30,12 @@
 		"_tscw": "tsc -w"
 	},
 	"dependencies": {
-		"@e280/stz": "^0.2.21"
+		"@e280/stz": "^0.2.22"
 	},
 	"devDependencies": {
 		"@e280/science": "^0.1.8",
 		"@e280/scute": "^0.2.2",
-		"@types/node": "^25.3.2",
+		"@types/node": "^25.3.5",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.9.3"
 	},

package/s/index.ts

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

package/s/prism/prism.test.ts

@@ -4,7 +4,7 @@ import {suite, test, expect} from "@e280/science"
 import {Prism} from "./prism.js"
 import {Chrono} from "./chrono/chrono.js"
 import {chronicle} from "./chrono/chronicle.js"
-import {effect} from "../signals/core/effect.js"
+import {effect} from "../signals/effect/effect.js"
 
 export default suite({
 	"prism": suite({
@@ -14,6 +14,7 @@ export default suite({
 			await prism.set({count: 2})
 			expect(prism.get().count).is(2)
 		}),
+
 		"get/set state can trigger effects": test(async() => {
 			const prism = new Prism({count: 1})
 			let triggered = 0

package/s/prism/prism.ts

@@ -1,7 +1,7 @@
 
 import {microbounce, sub} from "@e280/stz"
 import {Lens} from "./lens.js"
-import { tracker } from "../tracker/tracker.js"
+import {tracker} from "../tracker/tracker.js"
 
 /** state mangagement source-of-truth */
 export class Prism<State> {

package/s/signals/derived/class.ts

@@ -0,0 +1,34 @@
+
+import {Sub} from "@e280/stz"
+import {derived} from "./fn.js"
+import {SignalOptions} from "../types.js"
+import {tracker} from "../../tracker/tracker.js"
+
+export interface Derived<Value> {
+	(): Value
+}
+
+export class Derived<Value> {
+	sneak!: Value
+	on!: Sub<[Value]>
+	dispose!: () => void
+
+	constructor(formula: () => Value, options?: Partial<SignalOptions>) {
+		if (new.target !== Derived) throw new Error("Derived cannot be subclassed")
+		return derived(formula, options)
+	}
+
+	get value() {
+		return (this as Derived<any>).get()
+	}
+
+	get() {
+		tracker.notifyRead(this)
+		return this.sneak
+	}
+
+	toString() {
+		return `(derived "${String(this.get())}")`
+	}
+}
+

package/s/signals/derived/fn.ts

@@ -0,0 +1,36 @@
+
+import {sub} from "@e280/stz"
+import {Derived} from "./class.js"
+import {watch} from "../effect/watch.js"
+import {SignalOptions} from "../types.js"
+import {tracker} from "../../tracker/tracker.js"
+import {defaultCompare} from "../utils/default-compare.js"
+
+export function derived<Value>(formula: () => Value, options?: Partial<SignalOptions>) {
+	function fn(): Value {
+		return (fn as Derived<Value>).get()
+	}
+
+	const compare = options?.compare ?? defaultCompare
+
+	Object.setPrototypeOf(fn, Derived.prototype)
+	fn.on = sub<[Value]>()
+
+	const {result, dispose} = watch(formula, async() => {
+		const value = formula()
+		const isChanged = !compare(fn.sneak, value)
+		if (isChanged) {
+			fn.sneak = value
+			await Promise.all([
+				tracker.notifyWrite(fn),
+				fn.on.pub(value),
+			])
+		}
+	})
+
+	fn.sneak = result
+	fn.dispose = dispose
+
+	return fn as Derived<Value>
+}
+

package/s/signals/{tests/derived.test.ts → derived/test.ts}

@@ -1,7 +1,8 @@
 
 import {Science, test, expect, spy} from "@e280/science"
-import {effect} from "../core/effect.js"
-import {derived, signal} from "../porcelain.js"
+import {derived} from "./fn.js"
+import {signal} from "../signal/fn.js"
+import {effect} from "../effect/effect.js"
 
 export default Science.suite({
 	"basic": test(async() => {
@@ -39,7 +40,7 @@ export default Science.suite({
 	"effect doesn't overreact to derived": test(async() => {
 		const a = signal(1)
 		const b = signal(10)
-		const product = signal.derived(() => a.value * b.value)
+		const product = derived(() => a.value * b.value)
 
 		const derivedSpy = spy(() => {})
 		product.on(derivedSpy)
@@ -63,7 +64,7 @@ export default Science.suite({
 	"derived.on": test(async() => {
 		const a = signal(1)
 		const b = signal(10)
-		const product = signal.derived(() => a.value * b.value)
+		const product = derived(() => a.value * b.value)
 		expect(product.value).is(10)
 
 		const mole = spy((_v: number) => {})
@@ -79,7 +80,7 @@ export default Science.suite({
 	"derived.on not called if result doesn't change": test(async() => {
 		const a = signal(1)
 		const b = signal(10)
-		const product = signal.derived(() => a.value * b.value)
+		const product = derived(() => a.value * b.value)
 		expect(product.value).is(10)
 
 		const mole = spy((_v: number) => {})
@@ -96,16 +97,14 @@ export default Science.suite({
 		expect(mole.spy.calls.length).is(1)
 	}),
 
-	"hipster fns": Science.suite({
-		"basic": test(async() => {
-			const a = signal(1)
-			const b = signal(10)
-			const product = derived(() => a() * b())
-			expect(product()).is(10)
+	"hipster syntax": test(async() => {
+		const a = signal(1)
+		const b = signal(10)
+		const product = derived(() => a() * b())
+		expect(product()).is(10)
 
-			await a(2)
-			expect(product()).is(20)
-		}),
+		await a(2)
+		expect(product()).is(20)
 	}),
 })
 

package/s/signals/effect/effect.ts

@@ -0,0 +1,7 @@
+
+import {watch} from "./watch.js"
+
+export function effect(collector: () => void, responder?: () => void) {
+	return watch(collector, responder).dispose
+}
+

package/s/signals/effect/test.ts

@@ -0,0 +1,172 @@
+
+import {Science, test, expect} from "@e280/science"
+import {watch} from "./watch.js"
+import {effect} from "./effect.js"
+import {signal} from "../signal/fn.js"
+
+export default Science.suite({
+	"watch": Science.suite({
+		"responder gets value": test(async() => {
+			const count = signal(1)
+			let collected = 0
+			watch(
+				() => count(),
+				x => { collected = x }
+			)
+			expect(collected).is(0)
+			await count(2)
+			expect(collected).is(2)
+		}),
+
+		"responder not called until change": test(async() => {
+			const count = signal(1)
+			let calls = 0
+			watch(
+				() => count(),
+				() => { calls++ }
+			)
+			expect(calls).is(0)
+			await count(2)
+			expect(calls).is(1)
+		}),
+
+		"watch updates dynamic dependencies": test(async() => {
+			const toggle = signal(true)
+			const a = signal(1)
+			const b = signal(10)
+
+			let collected = 0
+
+			watch(
+				() => toggle() ? a() : b(),
+				x => { collected = x }
+			)
+
+			await a(2)
+			expect(collected).is(2)
+
+			await toggle(false)
+			expect(collected).is(10)
+
+			collected = 0
+			await a(3)
+			expect(collected).is(0)
+
+			await b(11)
+			expect(collected).is(11)
+		})
+	}),
+
+	"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)
+	}),
+
+	"correct signal effect order": test(async() => {
+		let order: string[] = []
+		const count = signal(0)
+
+		effect(() => {
+			if (count.value)
+				order.push("effect")
+		})
+
+		order.push("before")
+		await count.set(1)
+		order.push("after")
+
+		expect(order.length).is(3)
+		expect(order[0]).is("before")
+		expect(order[1]).is("effect")
+		expect(order[2]).is("after")
+	}),
+
+	"simple effect called the correct number of times": test(async() => {
+		const count = signal(0)
+		let runs = 0
+		effect(() => { count(); runs++ })
+		expect(runs).is(1)
+		await count(1)
+		expect(runs).is(2)
+		await count(2)
+		expect(runs).is(3)
+	}),
+
+	"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)
+	}),
+
+	"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)
+	}),
+
+	"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)
+	}),
+
+	"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)
+	}),
+})
+

package/s/signals/effect/watch.ts

@@ -0,0 +1,32 @@
+
+import {microbounce} from "@e280/stz"
+import {tracker} from "../../tracker/tracker.js"
+
+export function watch<Value>(
+		collector: () => Value,
+		responder?: (value: Value) => void,
+	) {
+
+	let disposers: (() => void)[] = []
+
+	const dispose = () => {
+		for (const d of disposers) d()
+		disposers = []
+	}
+
+	const run = () => {
+		const {seen, result} = tracker.observe(collector)
+		for (const saw of seen)
+			disposers.push(tracker.subscribe(saw, reset))
+		return result
+	}
+
+	const reset = microbounce(() => {
+		dispose()
+		if (responder) responder(run())
+		else run()
+	})
+
+	return {result: run(), dispose}
+}
+

package/s/signals/index.ts

@@ -1,14 +1,18 @@
 
-export * from "./core/parts/reactive.js"
-export * from "./core/parts/readable.js"
-export * from "./core/derived.js"
-export * from "./core/effect.js"
-export * from "./core/lazy.js"
-export * from "./core/signal.js"
+export * from "./derived/fn.js"
+export * from "./derived/class.js"
+
+export * from "./effect/effect.js"
+export * from "./effect/watch.js"
+
+export * from "./lazy/fn.js"
+export * from "./lazy/class.js"
 
 export * from "./r/map.js"
 export * from "./r/set.js"
 
-export * from "./porcelain.js"
+export * from "./signal/fn.js"
+export * from "./signal/class.js"
+
 export * from "./types.js"
 

package/s/signals/lazy/class.ts

@@ -0,0 +1,74 @@
+
+import {lazy} from "./fn.js"
+import {SignalOptions} from "../types.js"
+import {tracker} from "../../tracker/tracker.js"
+import {_collect, _compare, _dirty, _disposers, _effect, _formula} from "../utils/symbols.js"
+
+export interface Lazy<Value> {
+	(): Value
+}
+
+export class Lazy<Value> {
+	sneak!: Value
+	;[_formula]!: () => Value
+	;[_dirty]!: boolean
+	;[_disposers]!: (() => void)[]
+	;[_effect]!: (() => void) | undefined
+	;[_compare]!: (a: any, b: any) => boolean
+
+	constructor(formula: () => Value, options?: Partial<SignalOptions>) {
+		if (new.target !== Lazy) throw new Error("Lazy cannot be subclassed")
+		return lazy(formula, options)
+	}
+
+	get value() {
+		return this.get()
+	}
+
+	[_collect]() {
+		for (const d of this[_disposers]) d()
+		this[_disposers] = []
+
+		const {seen, result} = tracker.observe(this[_formula])
+
+		const markDirty = async() => { this[_dirty] = true }
+		for (const saw of seen)
+			this[_disposers].push(tracker.subscribe(saw, markDirty))
+
+		this[_effect] = () => {
+			for (const d of this[_disposers]) d()
+			this[_disposers] = []
+		}
+
+		return result
+	}
+
+	get() {
+		if (!this[_effect]) {
+			this.sneak = this[_collect]()
+			this[_dirty] = false
+		}
+		else if (this[_dirty]) {
+			this[_dirty] = false
+			const value = this[_collect]()
+			const isChanged = !this[_compare](this.sneak, value)
+			if (isChanged) {
+				this.sneak = value
+				tracker.notifyWrite(this)
+			}
+		}
+
+		tracker.notifyRead(this)
+		return this.sneak
+	}
+
+	dispose() {
+		if (this[_effect])
+			this[_effect]()
+	}
+
+	toString() {
+		return `($lazy "${String(this.get())}")`
+	}
+}
+

package/s/signals/lazy/fn.ts

@@ -0,0 +1,22 @@
+
+import {Lazy} from "./class.js"
+import {SignalOptions} from "../types.js"
+import {defaultCompare} from "../utils/default-compare.js"
+import {_compare, _dirty, _disposers, _effect, _formula} from "../utils/symbols.js"
+
+export function lazy<Value>(formula: () => Value, options?: Partial<SignalOptions>) {
+	function fn(): Value {
+		return (fn as Lazy<Value>).get()
+	}
+
+	Object.setPrototypeOf(fn, Lazy.prototype)
+	fn.sneak = undefined
+	fn[_formula] = formula
+	fn[_dirty] = false
+	fn[_effect] = undefined
+	fn[_disposers] = [] as any
+	fn[_compare] = options?.compare ?? defaultCompare
+
+	return fn as Lazy<Value>
+}
+