@e280/strata 0.2.0-1 → 0.2.0-11

package/README.md

@@ -1,7 +1,9 @@
 
 ![](https://i.imgur.com/h7FohWa.jpeg)
 
-<br/>
+
+
+<br/><br/>
 
 # ⛏️ strata
 
@@ -9,14 +11,16 @@
 📦 `npm install @e280/strata`  
 🧙‍♂️ probably my tenth state management library, lol  
 💁 it's all about rerendering ui when data changes  
-🦝 used by our view library [@e280/sly](https://github.com/e280/sly)  
+🦝 powers reactivity in our view library [@e280/sly](https://github.com/e280/sly)  
 🧑‍💻 a project by https://e280.org/
 
 🚦 **signals** — ephemeral view-level state  
 🌳 **tree** — persistent app-level state  
 🪄 **tracker** — reactivity integration hub  
 
-<br/>
+
+
+<br/><br/>
 
 ## 🚦 strata signals
 > *ephemeral view-level state*
@@ -26,95 +30,125 @@ import {signal, effect} from "@e280/strata"
 ```
 
 ### 🚦 each signal holds a value
-- **create a signal**
+- **make signal**
   ```ts
-  const count = signal(0)
+  const $count = signal(0)
   ```
-- **read a signal**
+  > *maybe you like the `$` prefix convention for signals?*
+- **read signal**
   ```ts
-  count.get() // 0
+  $count() // 0
   ```
-- **set a signal**
+- **write signal**
   ```ts
-  count.set(1)
+  $count(1)
   ```
-- **set a signal, and await effect propagation**
+- **write signal *(and await all downstream effects)***
   ```ts
-  await count.set(2)
+  await $count(2)
   ```
+  > *this is supposed to impress you*
 
 ### 🚦 pick your poison
+- **signal hipster-fn syntax**
+  ```ts
+  $count()        // read
+  await $count(2) // write
+  ```
 - **signal get/set syntax**
   ```ts
-  count.get() // get
-  await count.set(2) // set
+  $count.get()        // read
+  await $count.set(2) // write
   ```
 - **signal .value accessor syntax**
   ```ts
-  count.value // get
-  count.value = 2 // set
+  $count.value     // read
+  $count.value = 2 // write
   ```
-  value pattern is nice for these vibes
+  value pattern is super nice for these vibes
   ```ts
-  count.value++
-  count.value += 1
+  $count.value++
+  $count.value += 1
   ```
-- **signal hipster fn syntax**
-  - turn a signal into a hipster fn
-    ```ts
-    const count = signal.fn(1)
-    ```
-  - now you can directly invoke it
-    ```ts
-    count() // get
-    await count(2) // set
-    ```
-  - it has all the stuff that a signal has
-    ```ts
-    count.get()
-    await count.publish(5)
-    count.on(x => console.log(x))
-    ```
-  - mint a fresh new signal fn
-    ```ts
-    const count = signal.fn(1)
-    ```
 
 ### 🚦 effects
 - **effects run when the relevant signals change**
   ```ts
-  effect(() => console.log(count.get()))
+  effect(() => console.log($count()))
     // 1
-    // the system detects 'count' is relevant
+    // the system detects '$count' is relevant
 
-  count.value++
+  $count.value++
     // 2
-    // when count is changed, the effect fn is run
+    // when $count is changed, the effect fn is run
   ```
 
-### 🚦 `signal.derive` and `signal.lazy` are computed signals
-- **signal.derive**  
-  is for combining signals
+### 🚦 `signal.derived` and `signal.lazy` are computed signals
+- **signal.derived**  
+  is for combining signals, like a formula
   ```ts
-  const a = signal(1)
-  const b = signal(10)
-  const product = signal.derive(() => a.get() * b.get())
+  const $a = signal(1)
+  const $b = signal(10)
+  const $product = signal.derived(() => $a() * $b())
 
-  product.get() // 10
+  $product() // 10
 
   // change a dependency,
   // and the derived signal is automatically updated
-  await a.set(2)
+  await $a(2)
 
-  product.get() // 20
+  $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.  
+  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!*
 
-<br/>
+### 🚦 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>`
+  - 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
+
+
+
+<br/><br/>
 
 ## 🌳 strata trees
 > *persistent app-level state*
@@ -249,7 +283,9 @@ import {Trunk} from "@e280/strata"
 - 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/>
+
+
+<br/><br/>
 
 ## 🪄 strata tracker
 > *reactivity integration hub*
@@ -324,9 +360,11 @@ note, the *items* that the tracker tracks can be any object, or symbol.. the tra
     }
     ```
 
-<br/>
 
-## 🧑‍💻 an e280 project
+
+<br/><br/>
+
+## 🧑‍💻 strata is by e280
 free and open source by https://e280.org/  
 join us if you're cool and good at dev  
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/strata",
-	"version": "0.2.0-1",
+	"version": "0.2.0-11",
 	"description": "state management",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -29,11 +29,11 @@
 		"_tscw": "tsc -w"
 	},
 	"dependencies": {
-		"@e280/stz": "^0.2.0"
+		"@e280/stz": "^0.2.3"
 	},
 	"devDependencies": {
-		"@e280/science": "^0.1.1",
-		"@types/node": "^24.3.0",
+		"@e280/science": "^0.1.2",
+		"@types/node": "^24.3.1",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.9.2"
 	},

package/s/signals/core/derived.ts

@@ -0,0 +1,65 @@
+
+import {collectorEffect} from "./effect.js"
+import {Reactive} from "./parts/reactive.js"
+import {tracker} from "../../tracker/tracker.js"
+import {DerivedFn, SignalOptions} from "../types.js"
+import {defaultCompare} from "../utils/default-compare.js"
+
+export class Derived<V> extends Reactive<V> {
+	#dispose: () => void
+
+	constructor(formula: () => V, options?: Partial<SignalOptions>) {
+		const compare = options?.compare ?? defaultCompare
+		const {result, dispose} = collectorEffect(formula, async() => {
+			const value = formula()
+			const isChanged = !compare(this.sneak, value)
+			if (isChanged) {
+				this.sneak = value
+				await Promise.all([
+					tracker.notifyWrite(this),
+					this.on.pub(value),
+				])
+			}
+		})
+		super(result)
+		this.#dispose = dispose
+	}
+
+	toString() {
+		return `(derived "${String(this.get())}")`
+	}
+
+	dispose() {
+		super.dispose()
+		this.#dispose()
+	}
+
+	get core() {
+		return this
+	}
+
+	fn() {
+		const that = this as Derived<V>
+
+		function f(): V {
+			return that.get()
+		}
+
+		f.core = that
+		f.get = that.get.bind(that)
+		f.on = that.on
+		f.dispose = that.dispose.bind(that)
+		f.fn = that.fn.bind(that)
+
+		Object.defineProperty(f, "value", {
+			get: () => that.value,
+		})
+
+		Object.defineProperty(f, "sneak", {
+			get: () => that.sneak,
+		})
+
+		return f as DerivedFn<V>
+	}
+}
+

package/s/signals/{effect.ts → core/effect.ts}

@@ -1,6 +1,6 @@
 
 import {debounce} from "@e280/stz"
-import {tracker} from "../tracker/tracker.js"
+import {tracker} from "../../tracker/tracker.js"
 
 export function effect(
 		collector: () => void,

package/s/signals/{lazy.ts → core/lazy.ts}

@@ -1,9 +1,9 @@
 
-import {SignalOptions} from "./types.js"
 import {collectorEffect} from "./effect.js"
 import {Readable} from "./parts/readable.js"
-import {tracker} from "../tracker/tracker.js"
-import {defaultCompare} from "./utils/default-compare.js"
+import {tracker} from "../../tracker/tracker.js"
+import {LazyFn, SignalOptions} from "../types.js"
+import {defaultCompare} from "../utils/default-compare.js"
 
 export class Lazy<V> extends Readable<V> {
 	#formula: () => V
@@ -17,6 +17,10 @@ export class Lazy<V> extends Readable<V> {
 		this.#compare = options?.compare ?? defaultCompare
 	}
 
+	toString() {
+		return `($lazy "${String(this.get())}")`
+	}
+
 	get() {
 		if (!this.#effect) {
 			const {result, dispose} = collectorEffect(
@@ -43,5 +47,32 @@ export class Lazy<V> extends Readable<V> {
 		if (this.#effect)
 			this.#effect()
 	}
+
+	get core() {
+		return this
+	}
+
+	fn() {
+		const that = this as Lazy<V>
+
+		function f(): V {
+			return that.get()
+		}
+
+		f.core = that
+		f.get = that.get.bind(that)
+		f.dispose = that.dispose.bind(that)
+		f.fn = that.fn.bind(that)
+
+		Object.defineProperty(f, "value", {
+			get: () => that.value,
+		})
+
+		Object.defineProperty(f, "sneak", {
+			get: () => that.sneak,
+		})
+
+		return f as LazyFn<V>
+	}
 }
 

package/s/signals/{parts → core/parts}/readable.ts

@@ -1,5 +1,5 @@
 
-import {tracker} from "../../tracker/tracker.js"
+import {tracker} from "../../../tracker/tracker.js"
 
 export class Readable<V> {
 	constructor(public sneak: V) {}

package/s/signals/core/signal.ts

@@ -0,0 +1,97 @@
+
+import {Reactive} from "./parts/reactive.js"
+import {tracker} from "../../tracker/tracker.js"
+import {SignalFn, SignalOptions} from "../types.js"
+import {defaultCompare} from "../utils/default-compare.js"
+
+export class Signal<V> extends Reactive<V> {
+	#lock = false
+	#compare: (a: any, b: any) => boolean
+
+	constructor(value: V, options?: Partial<SignalOptions>) {
+		super(value)
+		this.#compare = options?.compare ?? defaultCompare
+	}
+
+	toString() {
+		return `($signal "${String(this.get())}")`
+	}
+
+	async set(v: V) {
+		const isChanged = !this.#compare(this.sneak, v)
+		if (isChanged) await this.publish(v)
+		return v
+	}
+
+	get value() {
+		return this.get()
+	}
+
+	set value(v: V) {
+		void this.set(v)
+	}
+
+	async publish(v: V) {
+		// only wizards are allowed beyond this point.
+		// - the implementation is subtle
+		// - it looks wrong, but it's right
+		// - tarnished alchemists, take heed: lock engages only for sync activity of the async fns (think of the value setter!)
+
+		if (this.#lock)
+			throw new Error("forbid circularity")
+
+		let promise: Promise<any> = Promise.resolve()
+
+		try {
+			this.#lock = true
+			this.sneak = v
+			promise = Promise.all([
+				tracker.notifyWrite(this),
+				this.on.publish(v),
+			])
+		}
+		finally {
+			this.#lock = false
+		}
+
+		await promise
+		return v
+	}
+
+	get core() {
+		return this
+	}
+
+	fn() {
+		const that = this as Signal<V>
+
+		function f(): V
+		function f(v: V): Promise<V>
+		function f(_v?: V): V | Promise<V> {
+			return (arguments.length === 0)
+				? that.get()
+				: that.set(arguments[0])
+		}
+
+		f.core = that
+		f.get = that.get.bind(that)
+		f.set = that.set.bind(that)
+		f.on = that.on
+		f.dispose = that.dispose.bind(that)
+		f.publish = that.publish.bind(that)
+		f.fn = that.fn.bind(that)
+
+		Object.defineProperty(f, "value", {
+			get: () => that.value,
+			set: (v) => that.value = v,
+		})
+
+		Object.defineProperty(f, "sneak", {
+			get: () => that.sneak,
+			set: (v) => that.sneak = v,
+		})
+
+		return f as SignalFn<V>
+	}
+}
+

package/s/signals/index.ts

@@ -1,11 +1,14 @@
 
-export * from "./parts/reactive.js"
-export * from "./parts/readable.js"
-
-export * from "./derive.js"
-export * from "./effect.js"
-export * from "./fns.js"
-export * from "./lazy.js"
-export * from "./signal.js"
+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 "./r/map.js"
+export * from "./r/set.js"
+
+export * from "./porcelain.js"
 export * from "./types.js"
 

package/s/signals/porcelain.ts

@@ -0,0 +1,30 @@
+
+import {SignalOptions} from "./types.js"
+import {Lazy} from "./core/lazy.js"
+import {Signal} from "./core/signal.js"
+import {Derived} from "./core/derived.js"
+
+export function lazy<V>(
+		formula: () => V,
+		options?: Partial<SignalOptions>,
+	) {
+	return new Lazy<V>(formula, options).fn()
+}
+
+export function derived<V>(
+		formula: () => V,
+		options?: Partial<SignalOptions>,
+	) {
+	return new Derived<V>(formula, options).fn()
+}
+
+export function signal<V>(
+		value: V,
+		options?: Partial<SignalOptions>,
+	) {
+	return new Signal<V>(value, options).fn()
+}
+
+signal.lazy = lazy
+signal.derived = derived
+

package/s/signals/r/map.ts

@@ -0,0 +1,63 @@
+
+import {MapG} from "@e280/stz"
+import {tracker} from "../../tracker/tracker.js"
+
+export class RMap<K, V> extends MapG<K, V> {
+	get size() {
+		tracker.notifyRead(this)
+		return super.size
+	}
+
+	;[Symbol.iterator]() {
+		tracker.notifyRead(this)
+		return super[Symbol.iterator]()
+	}
+
+	keys() {
+		tracker.notifyRead(this)
+		return super.keys()
+	}
+
+	values() {
+		tracker.notifyRead(this)
+		return super.values()
+	}
+
+	entries() {
+		tracker.notifyRead(this)
+		return super.entries()
+	}
+
+	forEach(callbackFn: (value: V, key: K, map: Map<K, V>) => void) {
+		tracker.notifyRead(this)
+		return super.forEach(callbackFn)
+	}
+
+	has(key: K) {
+		tracker.notifyRead(this)
+		return super.has(key)
+	}
+
+	get(key: K) {
+		tracker.notifyRead(this)
+		return super.get(key)
+	}
+
+	set(key: K, value: V) {
+		const r = super.set(key, value)
+		tracker.notifyWrite(this)
+		return r
+	}
+
+	delete(key: K) {
+		const r = super.delete(key)
+		tracker.notifyWrite(this)
+		return r
+	}
+
+	clear() {
+		super.clear()
+		tracker.notifyWrite(this)
+	}
+}
+

package/s/signals/r/set.ts

@@ -0,0 +1,43 @@
+
+import {SetG} from "@e280/stz"
+import {tracker} from "../../tracker/tracker.js"
+
+export class RSet<T> extends SetG<T> {
+	get size() {
+		tracker.notifyRead(this)
+		return super.size
+	}
+
+	;[Symbol.iterator]() {
+		tracker.notifyRead(this)
+		return super[Symbol.iterator]()
+	}
+
+	values() {
+		tracker.notifyRead(this)
+		return super.values()
+	}
+
+	has(item: T) {
+		tracker.notifyRead(this)
+		return super.has(item)
+	}
+
+	add(item: T) {
+		super.add(item)
+		tracker.notifyWrite(this)
+		return this
+	}
+
+	delete(item: T) {
+		const r = super.delete(item)
+		tracker.notifyWrite(this)
+		return r
+	}
+
+	clear() {
+		super.clear()
+		tracker.notifyWrite(this)
+	}
+}
+

package/s/signals/signals.test.ts

@@ -1,16 +1,15 @@
 
 import {Science} from "@e280/science"
-import signalTest from "./tests/signal.test.js"
-import signalFnTest from "./tests/signal-fn.test.js"
+
 import effectTest from "./tests/effect.test.js"
+import signalTest from "./tests/signal.test.js"
+import derivedTest from "./tests/derived.test.js"
 import lazyTest from "./tests/lazy.test.js"
-import deriveTest from "./tests/derive.test.js"
 
 export default Science.suite({
-	"signal": signalTest,
-	"signal.fn": signalFnTest,
 	"effect": effectTest,
+	"signal": signalTest,
+	"derived": derivedTest,
 	"lazy": lazyTest,
-	"derive": deriveTest,
 })