@vielzeug/stateit 2.0.0

package/README.md

@@ -0,0 +1,337 @@
+# @vielzeug/stateit
+
+> Tiny, zero-dependency reactive state — signals, computed values, effects, and typed object stores
+
+[![npm version](https://img.shields.io/npm/v/@vielzeug/stateit)](https://www.npmjs.com/package/@vielzeug/stateit) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Stateit** is a tiny, zero-dependency reactive library with two complementary primitives:
+
+- **Signals** — fine-grained reactive atoms with `signal()`, `computed()`, `effect()`, `watch()`, `batch()`, and more
+- **Stores** — typed reactive object containers with partial patching, updater functions, selectors, and freeze
+
+A `Store<T>` extends `Signal<T>`, so every signal primitive — `effect`, `watch`, `computed`, `batch` — works seamlessly on stores.
+
+## Installation
+
+```sh
+pnpm add @vielzeug/stateit
+# npm install @vielzeug/stateit
+# yarn add @vielzeug/stateit
+```
+
+## Quick Start
+
+### Signals
+
+```typescript
+import { signal, computed, effect, watch, batch } from '@vielzeug/stateit';
+
+const count = signal(0);
+const doubled = computed(() => count.value * 2);
+
+// effect runs immediately and re-runs on every dependency change
+const sub = effect(() => {
+  console.log(`count=${count.value}, doubled=${doubled.value}`);
+});
+// → count=0, doubled=0
+
+count.value = 3;
+// → count=3, doubled=6
+
+// Update via function — shorthand for count.value = count.value + n
+count.update((n) => n + 1);
+// → count=4, doubled=8
+
+// Watch explicitly (does not fire immediately by default)
+const stopWatch = watch(count, (next, prev) => console.log(prev, '→', next));
+count.value = 5; // → 4 → 5
+
+// Batch coalesces notifications into one flush
+batch(() => {
+  count.value = 10;
+  count.value = 20;
+});
+// One notification: → 5 → 20
+
+sub.dispose(); // or: sub() — direct call also disposes
+doubled.dispose();
+stopWatch.dispose();
+```
+
+### Stores
+
+```typescript
+import { store, watch, batch } from '@vielzeug/stateit';
+
+const counter = store({ count: 0, user: null as User | null });
+
+// Read
+console.log(counter.value); // { count: 0, user: null }
+
+// Partial patch
+counter.patch({ count: 1 });
+
+// Updater function
+counter.update((s) => ({ ...s, count: s.count + 1 }));
+
+// Watch a slice — compose store.select() with watch()
+const countSignal = counter.select((s) => s.count);
+const stopWatch = watch(countSignal, (count, prev) => {
+  console.log('count:', prev, '→', count);
+});
+
+// Batch updates into one notification
+batch(() => {
+  counter.patch({ count: 10 });
+  counter.patch({ user: currentUser });
+});
+
+// Reset to initial state
+counter.reset();
+
+stopWatch.dispose();
+counter.freeze();
+```
+
+## Features
+
+- ✅ **Signals** — reactive atoms with `.value` getter/setter, `.update(fn)`, and `.peek()` for untracked reads
+- ✅ **Computed** — lazy derived signals; call `.dispose()` to stop tracking dependencies
+- ✅ **Effects** — run immediately and re-run when dependencies change; support cleanup returns; return a `Subscription`
+- ✅ **Watch** — explicit subscriptions with `{ immediate?, once?, equals? }` options; returns a `Subscription`
+- ✅ **Batch** — coalesce multiple writes into a single downstream notification
+- ✅ **Untrack** — read signals without registering reactive dependencies
+- ✅ **derived** — multi-source computed from an array of signals
+- ✅ **nextValue** — `Promise` that resolves on the next matching signal emission
+- ✅ **Custom equality** — `signal/computed/watch/store` all accept a custom `equals` function
+- ✅ **Stores** — object state with `patch(partial)`, `update(fn)`, `reset()`, `select()`, and `freeze()`
+- ✅ **Writable computed** — bidirectional computed with `writable(get, set)`
+- ✅ **Symbol.dispose** — all dispose handles support `using` declarations (TC39 explicit resource management)
+- ✅ **Type guards** — `isSignal(v)` and `isStore(v)`
+- ✅ **Zero dependencies** — no supply-chain risk, minimal bundle size
+- ✅ **Framework agnostic** — works in React, Vue, Svelte, or plain TypeScript
+
+## Usage
+
+### Signals
+
+```typescript
+import { signal, readonly } from '@vielzeug/stateit';
+
+const count = signal(0);
+count.value = 5;
+count.peek(); // read without tracking
+count.update((n) => n + 1); // derive next value in place
+
+// Narrow to read-only view (no proxy overhead)
+const ro = readonly(count);
+```
+
+### Computed
+
+```typescript
+import { signal, computed } from '@vielzeug/stateit';
+
+const first = signal('Ada');
+const last = signal('Lovelace');
+const full = computed(() => `${first.value} ${last.value}`);
+
+console.log(full.value); // 'Ada Lovelace'
+full.stale; // false — just computed
+first.value = 'Grace';
+full.stale; // true — deps changed, not yet re-read
+
+// Dispose (stop tracking dependencies)
+full.dispose();
+// or: using full = computed(...) — TC39 using declaration
+```
+
+### Effects
+
+```typescript
+import { signal, effect, onCleanup } from '@vielzeug/stateit';
+
+const name = signal('Ada');
+
+const sub = effect(() => {
+  console.log('Hello,', name.value);
+  return () => console.log('cleanup'); // optional teardown
+});
+
+name.value = 'Grace'; // logs 'cleanup' then 'Hello, Grace'
+sub.dispose(); // logs 'cleanup', effect is removed
+```
+
+### Watch
+
+```typescript
+import { signal, store, watch } from '@vielzeug/stateit';
+
+const count = signal(0);
+
+// Plain watch
+const sub = watch(count, (next, prev) => console.log(prev, '→', next));
+
+// Slice watch — compose with store.select()
+const user = store({ name: 'Ada', age: 30 });
+const nameSig = user.select((s) => s.name);
+watch(nameSig, (name) => console.log('name:', name));
+
+// Options
+watch(count, (v) => console.log(v), { immediate: true, once: true });
+
+sub.dispose();
+```
+
+### Stores
+
+```typescript
+import { store, watch, batch } from '@vielzeug/stateit';
+
+const cart = store({ items: [] as string[], total: 0 });
+
+// Partial patch
+cart.patch({ total: 42 });
+
+// Updater function
+cart.update((s) => ({ ...s, items: [...s.items, 'apple'] }));
+
+// Derived slice
+const totalSignal = cart.select((s) => s.total);
+
+// Watch slice
+watch(totalSignal, (total) => console.log('total:', total));
+
+// Batch
+batch(() => {
+  cart.patch({ total: 0 });
+  cart.update((s) => ({ ...s, items: [] }));
+});
+
+cart.reset();
+cart.freeze();
+```
+
+### Writable Computed
+
+```typescript
+import { signal, writable } from '@vielzeug/stateit';
+
+const celsius = signal(0);
+const fahrenheit = writable(
+  () => (celsius.value * 9) / 5 + 32,
+  (f) => {
+    celsius.value = ((f - 32) * 5) / 9;
+  },
+);
+
+fahrenheit.value = 212;
+console.log(celsius.value); // 100
+
+fahrenheit.update((f) => f + 10); // increment via fn
+fahrenheit.dispose();
+```
+
+### `nextValue` — Async Watch
+
+```typescript
+import { signal, nextValue } from '@vielzeug/stateit';
+
+const status = signal<'idle' | 'loading' | 'done'>('idle');
+
+// Wait for the next change (any value)
+const next = await nextValue(status);
+
+// Wait for a specific condition
+const done = await nextValue(status, (v) => v === 'done');
+
+// Abortable wait
+const controller = new AbortController();
+const p = nextValue(status, (v) => v === 'done', { signal: controller.signal });
+controller.abort(new Error('cancelled'));
+```
+
+### Custom Equality
+
+```typescript
+import { signal, computed } from '@vielzeug/stateit';
+
+// Signal only notifies when the array reference AND contents differ
+const tags = signal(['ts'], { equals: (a, b) => JSON.stringify(a) === JSON.stringify(b) });
+
+// Computed suppresses downstream when result is structurally unchanged
+const sorted = computed(() => [...tags.value].sort(), { equals: (a, b) => a.join() === b.join() });
+```
+
+## API
+
+### Signal Functions
+
+| Export             | Signature                                                | Returns                  |
+| ------------------ | -------------------------------------------------------- | ------------------------ |
+| `signal`           | `signal(initial, options?)`                              | `Signal<T>`              |
+| `computed`         | `computed(fn, options?)`                                 | `ComputedSignal<T>`      |
+| `writable`         | `writable(get, set, options?)`                           | `WritableSignal<T>`      |
+| `derived`          | `derived(sources, fn, options?)`                         | `ComputedSignal<R>`      |
+| `effect`           | `effect(fn, options?)`                                   | `Subscription`           |
+| `watch`            | `watch(source, cb, options?)`                            | `Subscription`           |
+| `nextValue`        | `nextValue(source, predicate?, { signal? }?)`           | `Promise<T>`             |
+| `batch`            | `batch(fn)`                                              | `T`                      |
+| `untrack`          | `untrack(fn)`                                            | `T`                      |
+| `onCleanup`        | `onCleanup(fn)`                                          | `void`                   |
+| `readonly`         | `readonly(sig)`                                          | `ReadonlySignal<T>`      |
+| `toValue`          | `toValue(v)`                                             | `T`                      |
+| `peekValue`        | `peekValue(v)`                                           | `T`                      |
+| `isSignal`         | `isSignal(v)`                                            | `v is ReadonlySignal<T>` |
+| `isStore`          | `isStore(v)`                                             | `v is Store<T>`          |
+| `shallowEqual`     | `shallowEqual(a, b)`                                     | `boolean`                |
+| `configureStateit` | `configureStateit(opts)`                                 | `void`                   |
+| `_resetContextForTesting` | `_resetContextForTesting()`                       | `void`                   |
+
+### Store Functions
+
+| Export  | Signature                  | Returns    |
+| ------- | -------------------------- | ---------- |
+| `store` | `store(initial, options?)` | `Store<T>` |
+
+### `Store<T>` Methods
+
+| Member                        | Description                                                             |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `.value`                      | Read the current state (tracked)                                        |
+| `.peek()`                     | Read the current state (untracked)                                      |
+| `.update(fn)`                 | Derive next state via `fn(copy) => next`                                |
+| `.patch(partial)`             | Shallow-merge a `Partial<T>` into state                                 |
+| `.reset()`                    | Restore the original initial state                                      |
+| `.select(selector, options?)` | Lazily derived `ComputedSignal<U>` from a slice; compose with `watch()` |
+| `.frozen`                     | `true` after `freeze()` has been called                                 |
+| `.freeze()`                   | Freeze the store; further writes are silently ignored                   |
+
+### Types
+
+| Type                 | Description                                                                          |
+| -------------------- | ------------------------------------------------------------------------------------ |
+| `Signal<T>`          | Readable/writable reactive atom with `.update(fn)`                                   |
+| `ReadonlySignal<T>`  | Read-only signal (no setter)                                                         |
+| `ComputedSignal<T>`  | `ReadonlySignal<T> & Disposable` — has `.stale`, `.dispose()`                        |
+| `WritableSignal<T>`  | `Signal<T> & Disposable` — has `.stale`, `.update(fn)`, `.dispose()`                 |
+| `Store<T>`           | Object store extending `Signal<T>`                                                   |
+| `Subscription`       | Callable + `.dispose()` + `[Symbol.dispose]` — returned by `effect`/`watch`          |
+| `Disposable`         | `.dispose()` + `[Symbol.dispose]` — implemented by `ComputedSignal`/`WritableSignal` |
+| `CleanupFn`          | `() => void`                                                                         |
+| `EffectCallback`     | `() => CleanupFn \| void`                                                            |
+| `EffectOptions`      | `{ maxIterations?, onError? }`                                                       |
+| `EqualityFn<T>`      | `(a: T, b: T) => boolean`                                                            |
+| `ReactiveOptions<T>` | `{ equals?: EqualityFn<T> }`                                                         |
+| `WatchOptions<T>`    | `{ immediate?, once?, equals? }`                                                     |
+| `StoreOptions<T>`    | `{ equals?: EqualityFn<T> }`                                                         |
+
+## Documentation
+
+Full docs at **[vielzeug.dev/stateit](https://vielzeug.dev/stateit)**
+
+|                                                   |                                        |
+| ------------------------------------------------- | -------------------------------------- |
+| [Usage Guide](https://vielzeug.dev/stateit/usage) | Concepts, patterns, and best practices |
+| [API Reference](https://vielzeug.dev/stateit/api) | Complete type signatures               |
+| [Examples](https://vielzeug.dev/stateit/examples) | Framework integrations and recipes     |

package/dist/batch.cjs

@@ -0,0 +1,2 @@
+const e=require(`./runtime.cjs`);var t=()=>{let t=[...e.queue.pending];e.queue.pending.clear();let n=[];for(let e of t)try{e()}catch(e){n.push(e)}if(n.length)throw n.length===1?n[0]:AggregateError(n,`[stateit] batch errors`)},n=n=>{e.queue.depth++;try{let r=n();return--e.queue.depth===0&&t(),r}catch(n){if(--e.queue.depth===0)try{t()}catch{}throw n}};exports._flushPending=t,exports.batch=n;
+//# sourceMappingURL=batch.cjs.map

package/dist/batch.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.cjs","names":[],"sources":["../src/batch.ts"],"sourcesContent":["import { _DEV, queue } from './runtime';\n\n/** @internal Drain and run all pending effects from the batch queue, collecting errors. */\nexport const _flushPending = (): void => {\n  const toFlush = [...queue.pending];\n\n  queue.pending.clear();\n\n  const errors: unknown[] = [];\n\n  for (const f of toFlush) {\n    try {\n      f();\n    } catch (e) {\n      errors.push(e);\n    }\n  }\n\n  if (errors.length) throw errors.length === 1 ? errors[0] : new AggregateError(errors, '[stateit] batch errors');\n};\n\n/** Runs fn and defers all Signal notifications until fn returns, then flushes once. */\nexport const batch = <T>(fn: () => T): T => {\n  queue.depth++;\n\n  try {\n    const result = fn();\n\n    if (--queue.depth === 0) _flushPending();\n\n    return result;\n  } catch (e) {\n    if (--queue.depth === 0) {\n      try {\n        _flushPending();\n      } catch (flushErr) {\n        if (_DEV)\n          console.error(\n            '[stateit] batch: a secondary flush error was suppressed (callback error takes precedence)',\n            flushErr,\n          );\n      }\n    }\n\n    throw e;\n  }\n};\n"],"mappings":"iCAGA,IAAa,MAA4B,CACvC,IAAM,EAAU,CAAC,GAAG,EAAA,MAAM,QAAQ,CAElC,EAAA,MAAM,QAAQ,OAAO,CAErB,IAAM,EAAoB,EAAE,CAE5B,IAAK,IAAM,KAAK,EACd,GAAI,CACF,GAAG,OACI,EAAG,CACV,EAAO,KAAK,EAAE,CAIlB,GAAI,EAAO,OAAQ,MAAM,EAAO,SAAW,EAAI,EAAO,GAAS,eAAe,EAAQ,yBAAyB,EAIpG,EAAY,GAAmB,CAC1C,EAAA,MAAM,QAEN,GAAI,CACF,IAAM,EAAS,GAAI,CAInB,MAFI,EAAE,EAAA,MAAM,QAAU,GAAG,GAAe,CAEjC,QACA,EAAG,CACV,GAAI,EAAE,EAAA,MAAM,QAAU,EACpB,GAAI,CACF,GAAe,MACE,EASrB,MAAM"}

package/dist/batch.d.ts

@@ -0,0 +1,5 @@
+/** @internal Drain and run all pending effects from the batch queue, collecting errors. */
+export declare const _flushPending: () => void;
+/** Runs fn and defers all Signal notifications until fn returns, then flushes once. */
+export declare const batch: <T>(fn: () => T) => T;
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAEA,2FAA2F;AAC3F,eAAO,MAAM,aAAa,QAAO,IAgBhC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,IAAI,MAAM,CAAC,KAAG,CAwBtC,CAAC"}

package/dist/batch.js

@@ -0,0 +1,28 @@
+import { queue as e } from "./runtime.js";
+//#region src/batch.ts
+var t = () => {
+	let t = [...e.pending];
+	e.pending.clear();
+	let n = [];
+	for (let e of t) try {
+		e();
+	} catch (e) {
+		n.push(e);
+	}
+	if (n.length) throw n.length === 1 ? n[0] : AggregateError(n, "[stateit] batch errors");
+}, n = (n) => {
+	e.depth++;
+	try {
+		let r = n();
+		return --e.depth === 0 && t(), r;
+	} catch (n) {
+		if (--e.depth === 0) try {
+			t();
+		} catch {}
+		throw n;
+	}
+};
+//#endregion
+export { t as _flushPending, n as batch };
+
+//# sourceMappingURL=batch.js.map

package/dist/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","names":[],"sources":["../src/batch.ts"],"sourcesContent":["import { _DEV, queue } from './runtime';\n\n/** @internal Drain and run all pending effects from the batch queue, collecting errors. */\nexport const _flushPending = (): void => {\n  const toFlush = [...queue.pending];\n\n  queue.pending.clear();\n\n  const errors: unknown[] = [];\n\n  for (const f of toFlush) {\n    try {\n      f();\n    } catch (e) {\n      errors.push(e);\n    }\n  }\n\n  if (errors.length) throw errors.length === 1 ? errors[0] : new AggregateError(errors, '[stateit] batch errors');\n};\n\n/** Runs fn and defers all Signal notifications until fn returns, then flushes once. */\nexport const batch = <T>(fn: () => T): T => {\n  queue.depth++;\n\n  try {\n    const result = fn();\n\n    if (--queue.depth === 0) _flushPending();\n\n    return result;\n  } catch (e) {\n    if (--queue.depth === 0) {\n      try {\n        _flushPending();\n      } catch (flushErr) {\n        if (_DEV)\n          console.error(\n            '[stateit] batch: a secondary flush error was suppressed (callback error takes precedence)',\n            flushErr,\n          );\n      }\n    }\n\n    throw e;\n  }\n};\n"],"mappings":";;AAGA,IAAa,UAA4B;CACvC,IAAM,IAAU,CAAC,GAAG,EAAM,QAAQ;AAElC,GAAM,QAAQ,OAAO;CAErB,IAAM,IAAoB,EAAE;AAE5B,MAAK,IAAM,KAAK,EACd,KAAI;AACF,KAAG;UACI,GAAG;AACV,IAAO,KAAK,EAAE;;AAIlB,KAAI,EAAO,OAAQ,OAAM,EAAO,WAAW,IAAI,EAAO,KAAS,eAAe,GAAQ,yBAAyB;GAIpG,KAAY,MAAmB;AAC1C,GAAM;AAEN,KAAI;EACF,IAAM,IAAS,GAAI;AAInB,SAFI,EAAE,EAAM,UAAU,KAAG,GAAe,EAEjC;UACA,GAAG;AACV,MAAI,EAAE,EAAM,UAAU,EACpB,KAAI;AACF,MAAe;UACE;AASrB,QAAM"}

package/dist/computed.cjs

@@ -0,0 +1,2 @@
+const e=require(`./runtime.cjs`),t=require(`./types.cjs`);var n=class extends e.ReactiveNode{[t._SIGNAL_BRAND]=!0;#e;#t=e._UNINITIALIZED;#n=!0;#r=!1;#i;#a=new Set;#o=()=>{this.#n||(this.#n=!0,this._notify())};constructor(e,t){super(),this.#e=e,this.#i=t?.equals??Object.is,t?.lazy||this.#s()}#s(){for(let e of this.#a)e();this.#a.clear();let t=e._withCtx(this.#o,this.#a,null,this.#e);this.#n=!1,(this.#t===e._UNINITIALIZED||!this.#i(this.#t,t))&&(this.#t=t)}get value(){return this.#r?this.#t:(this.#n&&this.#s(),this._track(),this.#t)}peek(){if(this.#t===e._UNINITIALIZED){if(this.#r)return;this.#s()}return this.#t}get stale(){return this.#n||this.#r}dispose(){if(!this.#r){this.#r=!0;for(let e of this.#a)e();this.#a.clear()}}[Symbol.dispose](){this.dispose()}},r=(e,t)=>new n(e,t),i=class extends n{#e;constructor(e,t,n){super(e,n),this.#e=t}get value(){return super.value}set value(e){this.#e(e)}update(e){this.#e(e(this.peek()))}},a=(e,t,n)=>new i(e,t,n),o=(e,t,n)=>r(()=>t(...e.map(e=>e.value)),n);exports.ComputedNode=n,exports.WritableNode=i,exports.computed=r,exports.derived=o,exports.writable=a;
+//# sourceMappingURL=computed.cjs.map

package/dist/computed.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.cjs","names":["#onDepChange","#dirty","#compute","#equals","#recompute","#deps","#value","#disposed","#set"],"sources":["../src/computed.ts"],"sourcesContent":["import { ReactiveNode, _DEV, _UNINITIALIZED, _withCtx } from './runtime';\nimport {\n  type CleanupFn,\n  type Disposable,\n  type EffectCallback,\n  type EqualityFn,\n  type ReactiveOptions,\n  type ReadonlySignal,\n  type Signal,\n  _SIGNAL_BRAND,\n} from './types';\n\n/** A derived read-only signal with an explicit dispose method. */\nexport interface ComputedSignal<T> extends ReadonlySignal<T>, Disposable {\n  /** True when the computed value is stale (deps changed but not yet re-read) or disposed. */\n  readonly stale: boolean;\n}\n\n/** @internal\n * Lazy computed node. Seeded once at construction so .peek() is immediately valid\n * (unless { lazy: true } is passed, in which case first compute defers to first read).\n *  - On dep change: marks dirty, notifies downstream (no recompute yet).\n *  - On .value read: recomputes if dirty, re-tracks fresh deps.\n *  - After dispose: _track() is skipped to prevent leaking outer effects.\n */\nexport class ComputedNode<T> extends ReactiveNode implements ComputedSignal<T> {\n  readonly [_SIGNAL_BRAND] = true as const;\n  #compute: () => T;\n  #value: T | typeof _UNINITIALIZED = _UNINITIALIZED;\n  #dirty = true;\n  #disposed = false;\n  #equals: EqualityFn<T>;\n  #deps = new Set<CleanupFn>();\n\n  readonly #onDepChange: EffectCallback = () => {\n    if (!this.#dirty) {\n      this.#dirty = true;\n      this._notify();\n    }\n  };\n\n  constructor(compute: () => T, options?: ReactiveOptions<T> & { lazy?: boolean }) {\n    super();\n    this.#compute = compute;\n    this.#equals = options?.equals ?? Object.is;\n\n    if (!options?.lazy) this.#recompute(); // seed: ensures peek() is valid immediately\n  }\n\n  #recompute(): void {\n    for (const unsub of this.#deps) unsub();\n    this.#deps.clear();\n\n    const result = _withCtx(this.#onDepChange, this.#deps, null, this.#compute);\n\n    this.#dirty = false;\n\n    if (this.#value === _UNINITIALIZED || !this.#equals(this.#value as T, result)) {\n      this.#value = result;\n    }\n  }\n\n  get value(): T {\n    if (this.#disposed) {\n      if (_DEV) console.warn('[stateit] Reading a disposed ComputedSignal returns a stale value.');\n\n      return this.#value as T;\n    }\n\n    if (this.#dirty) this.#recompute();\n\n    this._track();\n\n    return this.#value as T;\n  }\n\n  peek(): T {\n    if (this.#value === _UNINITIALIZED) {\n      if (this.#disposed) {\n        if (_DEV)\n          console.warn(\n            '[stateit] peek() called on a disposed lazy ComputedSignal that was never read — returning undefined.',\n          );\n\n        return undefined as unknown as T;\n      }\n\n      this.#recompute();\n    }\n\n    return this.#value as T;\n  }\n\n  get stale(): boolean {\n    return this.#dirty || this.#disposed;\n  }\n\n  dispose(): void {\n    if (this.#disposed) return;\n\n    this.#disposed = true;\n    for (const unsub of this.#deps) unsub();\n    this.#deps.clear();\n  }\n\n  [Symbol.dispose](): void {\n    this.dispose();\n  }\n}\n\n/** Creates a derived read-only Signal whose value is recomputed lazily on `.value` read\n * when dependencies have changed. Call `.dispose()` to stop tracking and free dependencies.\n * Pass `{ lazy: true }` to defer the initial computation until the first `.value` read. */\nexport const computed = <T>(compute: () => T, options?: ReactiveOptions<T> & { lazy?: boolean }): ComputedSignal<T> =>\n  new ComputedNode(compute, options);\n\n/** A bidirectional computed Signal with an explicit dispose method. */\nexport interface WritableSignal<T> extends Signal<T>, Disposable {\n  /** True when the backing computed value is stale (deps changed but not yet re-read) or disposed. */\n  readonly stale: boolean;\n}\n\n/** @internal */\nexport class WritableNode<T> extends ComputedNode<T> implements WritableSignal<T> {\n  readonly #set: (v: T) => void;\n\n  constructor(get: () => T, set: (v: T) => void, options?: ReactiveOptions<T>) {\n    super(get, options);\n    this.#set = set;\n  }\n\n  override get value(): T {\n    return super.value;\n  }\n\n  set value(v: T) {\n    this.#set(v);\n  }\n\n  update(fn: (current: T) => T): void {\n    this.#set(fn(this.peek()));\n  }\n}\n\n/** Creates a bidirectional computed Signal. Reads track the getter reactively;\n * writes are forwarded to `set`. Call `.dispose()` to stop tracking and free dependencies. */\nexport const writable = <T>(get: () => T, set: (value: T) => void, options?: ReactiveOptions<T>): WritableSignal<T> =>\n  new WritableNode(get, set, options);\n\n/**\n * Creates a derived ComputedSignal by combining multiple source signals through a projector\n * function. Each source is passed as a positional argument to `fn`; the projector is\n * re-evaluated whenever any source changes.\n *\n * @example\n * const total = derived([price, quantity, discount], (p, q, d) => p * q * (1 - d));\n */\nexport const derived = <const Srcs extends ReadonlyArray<ReadonlySignal<unknown>>, R>(\n  sources: Srcs,\n  fn: (...values: { [K in keyof Srcs]: Srcs[K] extends ReadonlySignal<infer V> ? V : never }) => R,\n  options?: ReactiveOptions<R>,\n): ComputedSignal<R> => computed(() => (fn as (...args: any[]) => R)(...sources.map((s) => s.value)), options);\n"],"mappings":"0DAyBA,IAAa,EAAb,cAAqC,EAAA,YAA0C,CAC7E,CAAU,EAAA,eAAiB,GAC3B,GACA,GAAoC,EAAA,eACpC,GAAS,GACT,GAAY,GACZ,GACA,GAAQ,IAAI,IAEZ,OAA8C,CACvC,MAAA,IACH,MAAA,EAAc,GACd,KAAK,SAAS,GAIlB,YAAY,EAAkB,EAAmD,CAC/E,OAAO,CACP,MAAA,EAAgB,EAChB,MAAA,EAAe,GAAS,QAAU,OAAO,GAEpC,GAAS,MAAM,MAAA,GAAiB,CAGvC,IAAmB,CACjB,IAAK,IAAM,KAAS,MAAA,EAAY,GAAO,CACvC,MAAA,EAAW,OAAO,CAElB,IAAM,EAAS,EAAA,SAAS,MAAA,EAAmB,MAAA,EAAY,KAAM,MAAA,EAAc,CAE3E,MAAA,EAAc,IAEV,MAAA,IAAgB,EAAA,gBAAkB,CAAC,MAAA,EAAa,MAAA,EAAkB,EAAO,IAC3E,MAAA,EAAc,GAIlB,IAAI,OAAW,CAWb,OAVI,MAAA,EAGK,MAAA,GAGL,MAAA,GAAa,MAAA,GAAiB,CAElC,KAAK,QAAQ,CAEN,MAAA,GAGT,MAAU,CACR,GAAI,MAAA,IAAgB,EAAA,eAAgB,CAClC,GAAI,MAAA,EAMF,OAGF,MAAA,GAAiB,CAGnB,OAAO,MAAA,EAGT,IAAI,OAAiB,CACnB,OAAO,MAAA,GAAe,MAAA,EAGxB,SAAgB,CACV,UAAA,EAEJ,OAAA,EAAiB,GACjB,IAAK,IAAM,KAAS,MAAA,EAAY,GAAO,CACvC,MAAA,EAAW,OAAO,EAGpB,CAAC,OAAO,UAAiB,CACvB,KAAK,SAAS,GAOL,GAAe,EAAkB,IAC5C,IAAI,EAAa,EAAS,EAAQ,CASvB,EAAb,cAAqC,CAA6C,CAChF,GAEA,YAAY,EAAc,EAAqB,EAA8B,CAC3E,MAAM,EAAK,EAAQ,CACnB,MAAA,EAAY,EAGd,IAAa,OAAW,CACtB,OAAO,MAAM,MAGf,IAAI,MAAM,EAAM,CACd,MAAA,EAAU,EAAE,CAGd,OAAO,EAA6B,CAClC,MAAA,EAAU,EAAG,KAAK,MAAM,CAAC,CAAC,GAMjB,GAAe,EAAc,EAAyB,IACjE,IAAI,EAAa,EAAK,EAAK,EAAQ,CAUxB,GACX,EACA,EACA,IACsB,MAAgB,EAA6B,GAAG,EAAQ,IAAK,GAAM,EAAE,MAAM,CAAC,CAAE,EAAQ"}

package/dist/computed.d.ts

@@ -0,0 +1,58 @@
+import { ReactiveNode } from './runtime';
+import { type Disposable, type ReactiveOptions, type ReadonlySignal, type Signal, _SIGNAL_BRAND } from './types';
+/** A derived read-only signal with an explicit dispose method. */
+export interface ComputedSignal<T> extends ReadonlySignal<T>, Disposable {
+    /** True when the computed value is stale (deps changed but not yet re-read) or disposed. */
+    readonly stale: boolean;
+}
+/** @internal
+ * Lazy computed node. Seeded once at construction so .peek() is immediately valid
+ * (unless { lazy: true } is passed, in which case first compute defers to first read).
+ *  - On dep change: marks dirty, notifies downstream (no recompute yet).
+ *  - On .value read: recomputes if dirty, re-tracks fresh deps.
+ *  - After dispose: _track() is skipped to prevent leaking outer effects.
+ */
+export declare class ComputedNode<T> extends ReactiveNode implements ComputedSignal<T> {
+    #private;
+    readonly [_SIGNAL_BRAND]: true;
+    constructor(compute: () => T, options?: ReactiveOptions<T> & {
+        lazy?: boolean;
+    });
+    get value(): T;
+    peek(): T;
+    get stale(): boolean;
+    dispose(): void;
+    [Symbol.dispose](): void;
+}
+/** Creates a derived read-only Signal whose value is recomputed lazily on `.value` read
+ * when dependencies have changed. Call `.dispose()` to stop tracking and free dependencies.
+ * Pass `{ lazy: true }` to defer the initial computation until the first `.value` read. */
+export declare const computed: <T>(compute: () => T, options?: ReactiveOptions<T> & {
+    lazy?: boolean;
+}) => ComputedSignal<T>;
+/** A bidirectional computed Signal with an explicit dispose method. */
+export interface WritableSignal<T> extends Signal<T>, Disposable {
+    /** True when the backing computed value is stale (deps changed but not yet re-read) or disposed. */
+    readonly stale: boolean;
+}
+/** @internal */
+export declare class WritableNode<T> extends ComputedNode<T> implements WritableSignal<T> {
+    #private;
+    constructor(get: () => T, set: (v: T) => void, options?: ReactiveOptions<T>);
+    get value(): T;
+    set value(v: T);
+    update(fn: (current: T) => T): void;
+}
+/** Creates a bidirectional computed Signal. Reads track the getter reactively;
+ * writes are forwarded to `set`. Call `.dispose()` to stop tracking and free dependencies. */
+export declare const writable: <T>(get: () => T, set: (value: T) => void, options?: ReactiveOptions<T>) => WritableSignal<T>;
+/**
+ * Creates a derived ComputedSignal by combining multiple source signals through a projector
+ * function. Each source is passed as a positional argument to `fn`; the projector is
+ * re-evaluated whenever any source changes.
+ *
+ * @example
+ * const total = derived([price, quantity, discount], (p, q, d) => p * q * (1 - d));
+ */
+export declare const derived: <const Srcs extends ReadonlyArray<ReadonlySignal<unknown>>, R>(sources: Srcs, fn: (...values: { [K in keyof Srcs]: Srcs[K] extends ReadonlySignal<infer V> ? V : never; }) => R, options?: ReactiveOptions<R>) => ComputedSignal<R>;
+//# sourceMappingURL=computed.d.ts.map

package/dist/computed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../src/computed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAkC,MAAM,WAAW,CAAC;AACzE,OAAO,EAEL,KAAK,UAAU,EAGf,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,kEAAkE;AAClE,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU;IACtE,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,qBAAa,YAAY,CAAC,CAAC,CAAE,SAAQ,YAAa,YAAW,cAAc,CAAC,CAAC,CAAC;;IAC5E,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAG,IAAI,CAAU;gBAe7B,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE;IAqB/E,IAAI,KAAK,IAAI,CAAC,CAYb;IAED,IAAI,IAAI,CAAC;IAiBT,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,OAAO,IAAI,IAAI;IAQf,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED;;2FAE2F;AAC3F,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,SAAS,MAAM,CAAC,EAAE,UAAU,eAAe,CAAC,CAAC,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,KAAG,cAAc,CAAC,CAAC,CAC9E,CAAC;AAErC,uEAAuE;AACvE,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU;IAC9D,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,gBAAgB;AAChB,qBAAa,YAAY,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAE,YAAW,cAAc,CAAC,CAAC,CAAC;;gBAGnE,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC;IAK3E,IAAa,KAAK,IAAI,CAAC,CAEtB;IAED,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,EAEb;IAED,MAAM,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI;CAGpC;AAED;8FAC8F;AAC9F,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,UAAU,eAAe,CAAC,CAAC,CAAC,KAAG,cAAc,CAAC,CAAC,CAC7E,CAAC;AAEtC;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,CAAC,IAAI,SAAS,aAAa,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAClF,SAAS,IAAI,EACb,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,GAAE,KAAK,CAAC,EAChG,UAAU,eAAe,CAAC,CAAC,CAAC,KAC3B,cAAc,CAAC,CAAC,CAA2F,CAAC"}

package/dist/computed.js

@@ -0,0 +1,65 @@
+import { ReactiveNode as e, _UNINITIALIZED as t, _withCtx as n } from "./runtime.js";
+import { _SIGNAL_BRAND as r } from "./types.js";
+//#region src/computed.ts
+var i = class extends e {
+	[r] = !0;
+	#e;
+	#t = t;
+	#n = !0;
+	#r = !1;
+	#i;
+	#a = /* @__PURE__ */ new Set();
+	#o = () => {
+		this.#n || (this.#n = !0, this._notify());
+	};
+	constructor(e, t) {
+		super(), this.#e = e, this.#i = t?.equals ?? Object.is, t?.lazy || this.#s();
+	}
+	#s() {
+		for (let e of this.#a) e();
+		this.#a.clear();
+		let e = n(this.#o, this.#a, null, this.#e);
+		this.#n = !1, (this.#t === t || !this.#i(this.#t, e)) && (this.#t = e);
+	}
+	get value() {
+		return this.#r ? this.#t : (this.#n && this.#s(), this._track(), this.#t);
+	}
+	peek() {
+		if (this.#t === t) {
+			if (this.#r) return;
+			this.#s();
+		}
+		return this.#t;
+	}
+	get stale() {
+		return this.#n || this.#r;
+	}
+	dispose() {
+		if (!this.#r) {
+			this.#r = !0;
+			for (let e of this.#a) e();
+			this.#a.clear();
+		}
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+}, a = (e, t) => new i(e, t), o = class extends i {
+	#e;
+	constructor(e, t, n) {
+		super(e, n), this.#e = t;
+	}
+	get value() {
+		return super.value;
+	}
+	set value(e) {
+		this.#e(e);
+	}
+	update(e) {
+		this.#e(e(this.peek()));
+	}
+}, s = (e, t, n) => new o(e, t, n), c = (e, t, n) => a(() => t(...e.map((e) => e.value)), n);
+//#endregion
+export { i as ComputedNode, o as WritableNode, a as computed, c as derived, s as writable };
+
+//# sourceMappingURL=computed.js.map

package/dist/computed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.js","names":["#onDepChange","#dirty","#compute","#equals","#recompute","#deps","#value","#disposed","#set"],"sources":["../src/computed.ts"],"sourcesContent":["import { ReactiveNode, _DEV, _UNINITIALIZED, _withCtx } from './runtime';\nimport {\n  type CleanupFn,\n  type Disposable,\n  type EffectCallback,\n  type EqualityFn,\n  type ReactiveOptions,\n  type ReadonlySignal,\n  type Signal,\n  _SIGNAL_BRAND,\n} from './types';\n\n/** A derived read-only signal with an explicit dispose method. */\nexport interface ComputedSignal<T> extends ReadonlySignal<T>, Disposable {\n  /** True when the computed value is stale (deps changed but not yet re-read) or disposed. */\n  readonly stale: boolean;\n}\n\n/** @internal\n * Lazy computed node. Seeded once at construction so .peek() is immediately valid\n * (unless { lazy: true } is passed, in which case first compute defers to first read).\n *  - On dep change: marks dirty, notifies downstream (no recompute yet).\n *  - On .value read: recomputes if dirty, re-tracks fresh deps.\n *  - After dispose: _track() is skipped to prevent leaking outer effects.\n */\nexport class ComputedNode<T> extends ReactiveNode implements ComputedSignal<T> {\n  readonly [_SIGNAL_BRAND] = true as const;\n  #compute: () => T;\n  #value: T | typeof _UNINITIALIZED = _UNINITIALIZED;\n  #dirty = true;\n  #disposed = false;\n  #equals: EqualityFn<T>;\n  #deps = new Set<CleanupFn>();\n\n  readonly #onDepChange: EffectCallback = () => {\n    if (!this.#dirty) {\n      this.#dirty = true;\n      this._notify();\n    }\n  };\n\n  constructor(compute: () => T, options?: ReactiveOptions<T> & { lazy?: boolean }) {\n    super();\n    this.#compute = compute;\n    this.#equals = options?.equals ?? Object.is;\n\n    if (!options?.lazy) this.#recompute(); // seed: ensures peek() is valid immediately\n  }\n\n  #recompute(): void {\n    for (const unsub of this.#deps) unsub();\n    this.#deps.clear();\n\n    const result = _withCtx(this.#onDepChange, this.#deps, null, this.#compute);\n\n    this.#dirty = false;\n\n    if (this.#value === _UNINITIALIZED || !this.#equals(this.#value as T, result)) {\n      this.#value = result;\n    }\n  }\n\n  get value(): T {\n    if (this.#disposed) {\n      if (_DEV) console.warn('[stateit] Reading a disposed ComputedSignal returns a stale value.');\n\n      return this.#value as T;\n    }\n\n    if (this.#dirty) this.#recompute();\n\n    this._track();\n\n    return this.#value as T;\n  }\n\n  peek(): T {\n    if (this.#value === _UNINITIALIZED) {\n      if (this.#disposed) {\n        if (_DEV)\n          console.warn(\n            '[stateit] peek() called on a disposed lazy ComputedSignal that was never read — returning undefined.',\n          );\n\n        return undefined as unknown as T;\n      }\n\n      this.#recompute();\n    }\n\n    return this.#value as T;\n  }\n\n  get stale(): boolean {\n    return this.#dirty || this.#disposed;\n  }\n\n  dispose(): void {\n    if (this.#disposed) return;\n\n    this.#disposed = true;\n    for (const unsub of this.#deps) unsub();\n    this.#deps.clear();\n  }\n\n  [Symbol.dispose](): void {\n    this.dispose();\n  }\n}\n\n/** Creates a derived read-only Signal whose value is recomputed lazily on `.value` read\n * when dependencies have changed. Call `.dispose()` to stop tracking and free dependencies.\n * Pass `{ lazy: true }` to defer the initial computation until the first `.value` read. */\nexport const computed = <T>(compute: () => T, options?: ReactiveOptions<T> & { lazy?: boolean }): ComputedSignal<T> =>\n  new ComputedNode(compute, options);\n\n/** A bidirectional computed Signal with an explicit dispose method. */\nexport interface WritableSignal<T> extends Signal<T>, Disposable {\n  /** True when the backing computed value is stale (deps changed but not yet re-read) or disposed. */\n  readonly stale: boolean;\n}\n\n/** @internal */\nexport class WritableNode<T> extends ComputedNode<T> implements WritableSignal<T> {\n  readonly #set: (v: T) => void;\n\n  constructor(get: () => T, set: (v: T) => void, options?: ReactiveOptions<T>) {\n    super(get, options);\n    this.#set = set;\n  }\n\n  override get value(): T {\n    return super.value;\n  }\n\n  set value(v: T) {\n    this.#set(v);\n  }\n\n  update(fn: (current: T) => T): void {\n    this.#set(fn(this.peek()));\n  }\n}\n\n/** Creates a bidirectional computed Signal. Reads track the getter reactively;\n * writes are forwarded to `set`. Call `.dispose()` to stop tracking and free dependencies. */\nexport const writable = <T>(get: () => T, set: (value: T) => void, options?: ReactiveOptions<T>): WritableSignal<T> =>\n  new WritableNode(get, set, options);\n\n/**\n * Creates a derived ComputedSignal by combining multiple source signals through a projector\n * function. Each source is passed as a positional argument to `fn`; the projector is\n * re-evaluated whenever any source changes.\n *\n * @example\n * const total = derived([price, quantity, discount], (p, q, d) => p * q * (1 - d));\n */\nexport const derived = <const Srcs extends ReadonlyArray<ReadonlySignal<unknown>>, R>(\n  sources: Srcs,\n  fn: (...values: { [K in keyof Srcs]: Srcs[K] extends ReadonlySignal<infer V> ? V : never }) => R,\n  options?: ReactiveOptions<R>,\n): ComputedSignal<R> => computed(() => (fn as (...args: any[]) => R)(...sources.map((s) => s.value)), options);\n"],"mappings":";;;AAyBA,IAAa,IAAb,cAAqC,EAA0C;CAC7E,CAAU,KAAiB;CAC3B;CACA,KAAoC;CACpC,KAAS;CACT,KAAY;CACZ;CACA,qBAAQ,IAAI,KAAgB;CAE5B,WAA8C;AAC5C,EAAK,MAAA,MACH,MAAA,IAAc,IACd,KAAK,SAAS;;CAIlB,YAAY,GAAkB,GAAmD;AAK/E,EAJA,OAAO,EACP,MAAA,IAAgB,GAChB,MAAA,IAAe,GAAS,UAAU,OAAO,IAEpC,GAAS,QAAM,MAAA,GAAiB;;CAGvC,KAAmB;AACjB,OAAK,IAAM,KAAS,MAAA,EAAY,IAAO;AACvC,QAAA,EAAW,OAAO;EAElB,IAAM,IAAS,EAAS,MAAA,GAAmB,MAAA,GAAY,MAAM,MAAA,EAAc;AAI3E,EAFA,MAAA,IAAc,KAEV,MAAA,MAAgB,KAAkB,CAAC,MAAA,EAAa,MAAA,GAAkB,EAAO,MAC3E,MAAA,IAAc;;CAIlB,IAAI,QAAW;AAWb,SAVI,MAAA,IAGK,MAAA,KAGL,MAAA,KAAa,MAAA,GAAiB,EAElC,KAAK,QAAQ,EAEN,MAAA;;CAGT,OAAU;AACR,MAAI,MAAA,MAAgB,GAAgB;AAClC,OAAI,MAAA,EAMF;AAGF,SAAA,GAAiB;;AAGnB,SAAO,MAAA;;CAGT,IAAI,QAAiB;AACnB,SAAO,MAAA,KAAe,MAAA;;CAGxB,UAAgB;AACV,aAAA,GAEJ;SAAA,IAAiB;AACjB,QAAK,IAAM,KAAS,MAAA,EAAY,IAAO;AACvC,SAAA,EAAW,OAAO;;;CAGpB,CAAC,OAAO,WAAiB;AACvB,OAAK,SAAS;;GAOL,KAAe,GAAkB,MAC5C,IAAI,EAAa,GAAS,EAAQ,EASvB,IAAb,cAAqC,EAA6C;CAChF;CAEA,YAAY,GAAc,GAAqB,GAA8B;AAE3E,EADA,MAAM,GAAK,EAAQ,EACnB,MAAA,IAAY;;CAGd,IAAa,QAAW;AACtB,SAAO,MAAM;;CAGf,IAAI,MAAM,GAAM;AACd,QAAA,EAAU,EAAE;;CAGd,OAAO,GAA6B;AAClC,QAAA,EAAU,EAAG,KAAK,MAAM,CAAC,CAAC;;GAMjB,KAAe,GAAc,GAAyB,MACjE,IAAI,EAAa,GAAK,GAAK,EAAQ,EAUxB,KACX,GACA,GACA,MACsB,QAAgB,EAA6B,GAAG,EAAQ,KAAK,MAAM,EAAE,MAAM,CAAC,EAAE,EAAQ"}

package/dist/effect.cjs

@@ -0,0 +1,2 @@
+const e=require(`./runtime.cjs`);var t=(t,n)=>{let r,i=new Set,a=!1,o=!1,s=!1,c=n?.maxIterations??e._maxEffectIterations,l=()=>{r?.(),r=void 0;for(let e of i)e();i.clear()},u=()=>{o=!1,l();let a=[],c,u=!1;try{e._withCtx(d,i,a,()=>{let e=t();typeof e==`function`&&a.push(e)})}catch(e){if(n?.onError)u=!0,c=e;else throw e}return r=a.length>0?()=>{for(let e of a)e()}:void 0,u&&(l(),n.onError(c),s=!0),u},d=()=>{if(s||a){a&&(o=!0);return}a=!0;try{let e=0;do{if(++e>c)throw Error(`[stateit] effect: possible infinite reactive loop (> ${c} iterations)`);if(u())break}while(o)}finally{a=!1}};d();let f=()=>{s||(s=!0,l())};return Object.assign(f,{dispose:f,[Symbol.dispose]:f})},n=t=>e._withCtx(null,null,null,t),r=t=>{e.scope.cleanups?.push(t)};exports.effect=t,exports.onCleanup=r,exports.untrack=n;
+//# sourceMappingURL=effect.cjs.map

package/dist/effect.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.cjs","names":[],"sources":["../src/effect.ts"],"sourcesContent":["import { _DEV, _maxEffectIterations, _withCtx, scope } from './runtime';\nimport { type CleanupFn, type EffectCallback, type Subscription } from './types';\n\n/** Options for the `effect()` primitive. */\nexport type EffectOptions = {\n  /**\n   * Maximum re-entrant iterations before throwing to prevent infinite loops.\n   * Overrides the global value set via `configureStateit` for this specific effect.\n   */\n  maxIterations?: number;\n  /**\n   * Called when the effect function throws. When provided, the effect is automatically\n   * disposed after the first error — it won't re-run on subsequent dependency changes.\n   */\n  onError?: (error: unknown) => void;\n};\n\n/** Runs fn immediately and re-runs it whenever any Signal read inside it changes. Returns a dispose handle. */\nexport const effect = (fn: EffectCallback, options?: EffectOptions): Subscription => {\n  let cleanup: CleanupFn | undefined;\n  const deps = new Set<CleanupFn>();\n  let running = false;\n  let dirty = false;\n  let disposed = false;\n  const maxIter = options?.maxIterations ?? _maxEffectIterations;\n\n  /** Tears down the current run: calls cleanup and unsubscribes all deps. */\n  const teardown = (): void => {\n    cleanup?.();\n    cleanup = undefined;\n    for (const unsub of deps) unsub();\n    deps.clear();\n  };\n\n  /** Runs a single iteration: tears down previous deps/cleanup, re-executes fn, registers fresh deps.\n   *  Returns true if onError handled a throw (caller should break the loop). */\n  const runIteration = (): boolean => {\n    dirty = false;\n    teardown();\n\n    const cleanups: CleanupFn[] = [];\n    let thrownError: unknown;\n    let threw = false;\n\n    try {\n      _withCtx(runner, deps, cleanups, () => {\n        const result = fn();\n\n        if (typeof result === 'function') cleanups.push(result);\n      });\n    } catch (e) {\n      if (options?.onError) {\n        threw = true;\n        thrownError = e;\n      } else throw e;\n    }\n\n    cleanup =\n      cleanups.length > 0\n        ? () => {\n            for (const c of cleanups) c();\n          }\n        : undefined;\n\n    if (threw) {\n      teardown(); // flush onCleanup registrations from the throwing run\n      options!.onError!(thrownError);\n      disposed = true;\n    }\n\n    return threw;\n  };\n\n  const runner: EffectCallback = () => {\n    if (disposed || running) {\n      if (running) dirty = true;\n\n      return;\n    }\n\n    running = true;\n\n    try {\n      let iterations = 0;\n\n      do {\n        if (++iterations > maxIter)\n          throw new Error(`[stateit] effect: possible infinite reactive loop (> ${maxIter} iterations)`);\n\n        if (runIteration()) break;\n      } while (dirty);\n    } finally {\n      running = false;\n    }\n  };\n\n  runner();\n\n  const dispose = (): void => {\n    if (disposed) return;\n\n    disposed = true;\n    teardown();\n  };\n\n  return Object.assign(dispose, { dispose, [Symbol.dispose]: dispose }) as Subscription;\n};\n\n/** Runs fn without registering any reactive dependencies. */\nexport const untrack = <T>(fn: () => T): T => _withCtx(null, null, null, fn);\n\n/**\n * Registers a cleanup function within the currently running effect.\n * Called before the effect re-runs and on final dispose.\n * Allows nested helpers to register teardown without needing the effect's return value.\n *\n * @example\n * effect(() => {\n *   const id = setInterval(() => { ... }, 1000);\n *   onCleanup(() => clearInterval(id));\n * });\n */\nexport const onCleanup = (fn: CleanupFn): void => {\n  if (_DEV && scope.cleanups === null) {\n    console.warn('[stateit] onCleanup() called outside of an active effect — the cleanup will never run.');\n  }\n\n  scope.cleanups?.push(fn);\n};\n"],"mappings":"iCAkBA,IAAa,GAAU,EAAoB,IAA0C,CACnF,IAAI,EACE,EAAO,IAAI,IACb,EAAU,GACV,EAAQ,GACR,EAAW,GACT,EAAU,GAAS,eAAiB,EAAA,qBAGpC,MAAuB,CAC3B,KAAW,CACX,EAAU,IAAA,GACV,IAAK,IAAM,KAAS,EAAM,GAAO,CACjC,EAAK,OAAO,EAKR,MAA8B,CAClC,EAAQ,GACR,GAAU,CAEV,IAAM,EAAwB,EAAE,CAC5B,EACA,EAAQ,GAEZ,GAAI,CACF,EAAA,SAAS,EAAQ,EAAM,MAAgB,CACrC,IAAM,EAAS,GAAI,CAEf,OAAO,GAAW,YAAY,EAAS,KAAK,EAAO,EACvD,OACK,EAAG,CACV,GAAI,GAAS,QACX,EAAQ,GACR,EAAc,OACT,MAAM,EAgBf,MAbA,GACE,EAAS,OAAS,MACR,CACJ,IAAK,IAAM,KAAK,EAAU,GAAG,EAE/B,IAAA,GAEF,IACF,GAAU,CACV,EAAS,QAAS,EAAY,CAC9B,EAAW,IAGN,GAGH,MAA+B,CACnC,GAAI,GAAY,EAAS,CACnB,IAAS,EAAQ,IAErB,OAGF,EAAU,GAEV,GAAI,CACF,IAAI,EAAa,EAEjB,EAAG,CACD,GAAI,EAAE,EAAa,EACjB,MAAU,MAAM,wDAAwD,EAAQ,cAAc,CAEhG,GAAI,GAAc,CAAE,YACb,UACD,CACR,EAAU,KAId,GAAQ,CAER,IAAM,MAAsB,CACtB,IAEJ,EAAW,GACX,GAAU,GAGZ,OAAO,OAAO,OAAO,EAAS,CAAE,WAAU,OAAO,SAAU,EAAS,CAAC,EAI1D,EAAc,GAAmB,EAAA,SAAS,KAAM,KAAM,KAAM,EAAG,CAa/D,EAAa,GAAwB,CAKhD,EAAA,MAAM,UAAU,KAAK,EAAG"}

package/dist/effect.d.ts

@@ -0,0 +1,31 @@
+import { type CleanupFn, type EffectCallback, type Subscription } from './types';
+/** Options for the `effect()` primitive. */
+export type EffectOptions = {
+    /**
+     * Maximum re-entrant iterations before throwing to prevent infinite loops.
+     * Overrides the global value set via `configureStateit` for this specific effect.
+     */
+    maxIterations?: number;
+    /**
+     * Called when the effect function throws. When provided, the effect is automatically
+     * disposed after the first error — it won't re-run on subsequent dependency changes.
+     */
+    onError?: (error: unknown) => void;
+};
+/** Runs fn immediately and re-runs it whenever any Signal read inside it changes. Returns a dispose handle. */
+export declare const effect: (fn: EffectCallback, options?: EffectOptions) => Subscription;
+/** Runs fn without registering any reactive dependencies. */
+export declare const untrack: <T>(fn: () => T) => T;
+/**
+ * Registers a cleanup function within the currently running effect.
+ * Called before the effect re-runs and on final dispose.
+ * Allows nested helpers to register teardown without needing the effect's return value.
+ *
+ * @example
+ * effect(() => {
+ *   const id = setInterval(() => { ... }, 1000);
+ *   onCleanup(() => clearInterval(id));
+ * });
+ */
+export declare const onCleanup: (fn: CleanupFn) => void;
+//# sourceMappingURL=effect.d.ts.map

package/dist/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEjF,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF,+GAA+G;AAC/G,eAAO,MAAM,MAAM,GAAI,IAAI,cAAc,EAAE,UAAU,aAAa,KAAG,YAwFpE,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,IAAI,MAAM,CAAC,KAAG,CAAmC,CAAC;AAE7E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAI,IAAI,SAAS,KAAG,IAMzC,CAAC"}