@hoosk/minisignals 1.1.0 → 1.2.0

package/README.md

@@ -18,8 +18,9 @@ import { signal, effect, computed, batch, untracked } from '@hoosk/minisignals';
 const count = signal(0);
 const double = computed(() => count.value * 2);
 
-effect(() => {
+const stop = effect(() => {
   console.log(`Count: ${count.value}, Double: ${double.value}`);
+  return () => console.log('cleanup'); // runs before each re-run and on stop()
 });
 
 count.value = 1; // Logs: Count: 1, Double: 2
@@ -29,11 +30,35 @@ batch(() => {
   count.value = 10;
   count.value = 20;
 }); // Logs once: Count: 20, Double: 40
+
+stop();
+```
+
+### `peek()` and cleanup
+
+`Signal` and `Computed` expose `.peek()` to read the current value without subscribing the active effect/computed:
+
+```typescript
+effect(() => {
+  count.value; // tracked
+  double.peek(); // not tracked
+});
 ```
 
+`effect()` callbacks may return a cleanup function that runs before every re-execution and when the effect is stopped.
+
+## Reactivity model
+
+Writes are processed in two phases:
+
+1. **Push**: every affected `computed` is marked dirty synchronously.
+2. **Pull**: queued effects refresh derived values and run once with consistent data.
+
+This makes diamond graphs glitch-free, keeps `computed` reads inside `batch()` fresh, and enables early bailout: if a recomputed value is unchanged, downstream effects are skipped.
+
 ## Performance
 
-The core is built on a linked-list dependency graph with O(1) dependency lookup (`currentLink` pointer), lazy computed evaluation (dirty flag, no eager recomputation), and class-based signal instances for V8 monomorphization.
+The core is built on a linked-list dependency graph with O(1) dependency lookup (`currentLink` pointer), push-pull invalidation (glitch-free diamonds + lazy computed evaluation with version-based early bailout), and class-based signal/computed instances for V8 monomorphization.
 
 Benchmark results on Node.js (warmup 150 ms, sample 350 ms):
 
@@ -41,26 +66,26 @@ Benchmark results on Node.js (warmup 150 ms, sample 350 ms):
 ── Signal ────────────────────────────────────────────────────
 scenario                               ops/s        time/op
 ─────────────────────────────────────────────────────────────
-signal-read                    420.38M ops/s      2.38 ns/op
-signal-write-no-subscribers    210.86M ops/s      4.74 ns/op
-signal-write-same-value        760.84M ops/s      1.31 ns/op
+signal-read                    533.34M ops/s      1.87 ns/op
+signal-write-no-subscribers    407.35M ops/s      2.45 ns/op
+signal-write-same-value        843.42M ops/s      1.19 ns/op
 
 ── Effect ────────────────────────────────────────────────────
 scenario                               ops/s        time/op
 ─────────────────────────────────────────────────────────────
-effect-fanout-write             17.77K ops/s     56.27 µs/op
-effect-create-dispose            5.86M ops/s    170.66 ns/op
-effect-dynamic-deps              7.08M ops/s    141.15 ns/op
+effect-fanout-write             18.98K ops/s     52.70 µs/op
+effect-create-dispose            8.94M ops/s    111.83 ns/op
+effect-dynamic-deps              7.34M ops/s    136.20 ns/op
 
 ── Computed ──────────────────────────────────────────────────
 scenario                               ops/s        time/op
 ─────────────────────────────────────────────────────────────
-computed-chain                  51.07K ops/s     19.58 µs/op
-computed-cached-read            44.59M ops/s     22.42 ns/op
-computed-batched-writes-no-read 742.71K ops/s     1.35 µs/op
-computed-batched-writes-then-read 706.54K ops/s   1.42 µs/op
+computed-chain                 115.71K ops/s      8.64 µs/op
+computed-cached-read           344.12M ops/s      2.91 ns/op
+computed-batched-writes-no-read 469.72K ops/s     2.13 µs/op
+computed-batched-writes-then-read 525.06K ops/s   1.90 µs/op
 ```
 
 Run `npm run bench` to reproduce locally.
 
-For full documentation and advanced features, please refer to the [main repository README](../../README.md).
+For full documentation and advanced features, please refer to the [main repository README](https://github.com/Hoosk/minisignals#readme).

package/dist/computed.d.ts

@@ -1,4 +1,4 @@
-import { ReadonlySignal } from './signal.js';
+import type { ReadonlySignal } from './signal.js';
 export interface Computed<T> extends ReadonlySignal<T> {
     /**
      * Stops the computed signal from observing dependencies.

package/dist/computed.js

@@ -1,4 +1,83 @@
-import { cleanupSubscriber, createDependencySource, getActiveSubscriber, scheduleSource, trackDependency, trackSubscriber, } from './effect.js';
+import { _activeSubscriber, cleanupSubscriber, createDependencySource, invalidateSource, trackDependency, trackSubscriber, untracked, } from './effect.js';
+// Same rationale as SignalImpl: a single prototype keeps V8 happy and lets the
+// getter inline the active-subscriber null check on the hot read path.
+// Implementing Subscriber directly avoids allocating a separate observer node.
+class ComputedImpl {
+    /** @internal */ _source;
+    depsHead = null;
+    depsTail = null;
+    trackId = 0;
+    flags = 0;
+    initialized = false;
+    isComputed = true;
+    pendingNext = null;
+    _fn;
+    _cachedValue;
+    _dirty = true;
+    _disposed = false;
+    constructor(fn) {
+        this._fn = fn;
+        const source = createDependencySource();
+        this._source = source;
+        source.refresh = () => {
+            if (!this._disposed && (!this.initialized || this._dirty)) {
+                this._refresh();
+            }
+        };
+    }
+    notify() { }
+    invalidate() {
+        if (this._disposed || this._dirty)
+            return;
+        this._dirty = true;
+        // Keep pushing downstream immediately so every computed in the graph
+        // is invalidated before any effect runs (glitch-free diamonds).
+        // Skip the walk entirely when nobody observes this computed.
+        if (this._source.subsHead !== null)
+            invalidateSource(this._source);
+    }
+    get value() {
+        if (this._disposed) {
+            if (!this.initialized) {
+                // Freeze the first read after disposal without subscribing to the
+                // signals read inside fn.
+                this._cachedValue = untracked(this._fn);
+                this.initialized = true;
+                this._dirty = false;
+            }
+            if (_activeSubscriber !== null)
+                trackDependency(this._source);
+            return this._cachedValue;
+        }
+        if (!this.initialized || this._dirty)
+            this._refresh();
+        if (_activeSubscriber !== null)
+            trackDependency(this._source);
+        return this._cachedValue;
+    }
+    peek() {
+        return untracked(() => this.value);
+    }
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._dirty = false;
+        cleanupSubscriber(this);
+    }
+    _refresh() {
+        const previousValue = this._cachedValue;
+        const wasInitialized = this.initialized;
+        this._cachedValue = trackSubscriber(this, this._fn);
+        this.initialized = true;
+        this._dirty = false;
+        // Early bailout: equal derived values do not advance the version, so
+        // downstream subscribers can detect that nothing actually changed.
+        if (!wasInitialized || this._cachedValue !== previousValue) {
+            this._source.version++;
+        }
+    }
+}
 /**
  * Creates a computed signal that derives its value from other signals.
  * It only calculates and subscribes when its value is read for the first time.
@@ -7,53 +86,5 @@ import { cleanupSubscriber, createDependencySource, getActiveSubscriber, schedul
  * @returns A read-only signal with a dispose method.
  */
 export function computed(fn) {
-    const source = createDependencySource();
-    const observer = {
-        notify() {
-            if (isDisposed || dirty)
-                return;
-            dirty = true;
-            scheduleSource(source);
-        },
-        depsHead: null,
-        depsTail: null,
-        trackId: 0,
-        pending: false,
-    };
-    let initialized = false;
-    let isDisposed = false;
-    let dirty = true;
-    let cachedValue;
-    function refreshValue() {
-        // Clear pending so a batch flush after an eager read inside the same batch
-        // does not re-trigger notify() on an already-fresh computed.
-        // We do NOT call cleanupSubscriber here: trackSubscriber increments trackId
-        // and pruneStaleDependencies removes only stale links, reusing stable ones.
-        observer.pending = false;
-        cachedValue = trackSubscriber(observer, fn);
-        initialized = true;
-        dirty = false;
-    }
-    return {
-        get value() {
-            if (getActiveSubscriber())
-                trackDependency(source);
-            if (isDisposed) {
-                if (!initialized) {
-                    cachedValue = fn();
-                    initialized = true;
-                    dirty = false;
-                }
-                return cachedValue;
-            }
-            if (!initialized || dirty)
-                refreshValue();
-            return cachedValue;
-        },
-        dispose() {
-            isDisposed = true;
-            dirty = false;
-            cleanupSubscriber(observer);
-        },
-    };
+    return new ComputedImpl(fn);
 }

package/dist/effect.d.ts

@@ -1,11 +1,19 @@
+export declare const PENDING: number;
+export declare const RUNNING: number;
+export declare const NEEDS_RERUN: number;
+export declare const DISPOSED: number;
 export interface DependencySource {
     subsHead: DependencyLink | null;
     currentLink: DependencyLink | null;
+    version: number;
+    refresh: (() => void) | null;
+    computedCount: number;
 }
-interface DependencyLink {
+export interface DependencyLink {
     source: DependencySource;
     subscriber: Subscriber;
     trackId: number;
+    seenVersion: number;
     rollbackCurrentLink: DependencyLink | null;
     nextInSource: DependencyLink | null;
     prevInSource: DependencyLink | null;
@@ -14,10 +22,14 @@ interface DependencyLink {
 }
 export interface Subscriber {
     notify: () => void;
+    invalidate: () => void;
     depsHead: DependencyLink | null;
     depsTail: DependencyLink | null;
     trackId: number;
-    pending: boolean;
+    flags: number;
+    initialized: boolean;
+    isComputed: boolean;
+    pendingNext: Subscriber | null;
 }
 declare let _activeSubscriber: Subscriber | null;
 export { _activeSubscriber };
@@ -26,12 +38,17 @@ export declare function getActiveSubscriber(): Subscriber | null;
 export declare function trackDependency(source: DependencySource): void;
 export declare function trackSubscriber<T>(subscriber: Subscriber, fn: () => T): T;
 export declare function cleanupSubscriber(subscriber: Subscriber): void;
+export declare function invalidateSource(source: DependencySource): void;
 export declare function scheduleSource(source: DependencySource): void;
 export declare function batch<T>(fn: () => T): T;
 export declare function untracked<T>(fn: () => T): T;
 /**
  * Creates an effect that runs immediately and tracks dependencies.
+ *
+ * The callback may return a cleanup function. It is invoked before every
+ * re-run and when the effect is stopped.
+ *
  * @param fn The function to execute.
  * @returns An unsubscribe function.
  */
-export declare function effect(fn: () => void): () => void;
+export declare function effect(fn: () => void | (() => void)): () => void;

package/dist/effect.js

@@ -1,10 +1,14 @@
-// ─── Dependency graph types ───────────────────────────────────────────────────
+// ─── Subscriber flags ───────────────────────────────────────────────────────
+export const PENDING = 1 << 0; // queued in the notification scheduler
+export const RUNNING = 1 << 1; // effect is currently executing
+export const NEEDS_RERUN = 1 << 2; // dependency changed while RUNNING
+export const DISPOSED = 1 << 3; // subscriber was cleaned up and must not run again
 let _activeSubscriber = null;
-// Exported so signal.ts can do an inline null-check in the getter hot path,
-// avoiding a function call when there is no active subscriber.
+// Exported so signal.ts/computed.ts can do an inline null-check in the getter
+// hot path, avoiding a function call when there is no active subscriber.
 export { _activeSubscriber };
 export function createDependencySource() {
-    return { subsHead: null, currentLink: null };
+    return { subsHead: null, currentLink: null, version: 0, refresh: null, computedCount: 0 };
 }
 export function getActiveSubscriber() {
     return _activeSubscriber;
@@ -24,8 +28,9 @@ function prepareSources(subscriber) {
 function linkDependency(source, subscriber) {
     const existing = source.currentLink;
     if (existing !== null && existing.subscriber === subscriber) {
-        // Stable dep: just mark as seen in this run.
+        // Stable dep: mark as seen in this run and record the observed version.
         existing.trackId = subscriber.trackId;
+        existing.seenVersion = source.version;
         return;
     }
     // New dep: create a link and install it. Save whatever was in currentLink
@@ -34,6 +39,7 @@ function linkDependency(source, subscriber) {
         source,
         subscriber,
         trackId: subscriber.trackId,
+        seenVersion: source.version,
         rollbackCurrentLink: existing,
         nextInSource: source.subsHead,
         prevInSource: null,
@@ -43,6 +49,8 @@ function linkDependency(source, subscriber) {
     if (source.subsHead)
         source.subsHead.prevInSource = link;
     source.subsHead = link;
+    if (subscriber.isComputed)
+        source.computedCount++;
     if (subscriber.depsTail) {
         subscriber.depsTail.nextInSubscriber = link;
     }
@@ -54,6 +62,8 @@ function linkDependency(source, subscriber) {
 }
 function unlinkDependency(link) {
     const { source, subscriber } = link;
+    if (subscriber.isComputed)
+        source.computedCount--;
     if (link.prevInSource) {
         link.prevInSource.nextInSource = link.nextInSource;
     }
@@ -120,28 +130,107 @@ export function cleanupSubscriber(subscriber) {
         unlinkDependency(link);
         link = next;
     }
-    subscriber.pending = false;
+    subscriber.depsHead = null;
+    subscriber.depsTail = null;
+    subscriber.flags = DISPOSED;
 }
-// ─── Batch scheduling ────────────────────────────────────────────────────────
+// ─── Push phase ──────────────────────────────────────────────────────────────
+// Walks the subscriber list and lets each node decide how to invalidate:
+// computeds mark themselves dirty and keep propagating synchronously, while
+// effects only queue themselves. No effect runs during this phase, which is
+// what makes diamond graphs glitch-free.
+export function invalidateSource(source) {
+    let link = source.subsHead;
+    while (link) {
+        const next = link.nextInSource;
+        link.subscriber.invalidate();
+        link = next;
+    }
+}
+// ─── Pull phase / scheduling ─────────────────────────────────────────────────
 let _batchDepth = 0;
-const _pendingNotifications = [];
-function queueSubscriber(subscriber) {
-    if (_batchDepth > 0) {
-        if (!subscriber.pending) {
-            subscriber.pending = true;
-            _pendingNotifications.push(subscriber);
-        }
+let _flushDepth = 0;
+let _pendingHead = null;
+let _pendingTail = null;
+function enqueueSubscriber(subscriber) {
+    subscriber.flags |= PENDING;
+    subscriber.pendingNext = null;
+    if (_pendingTail === null) {
+        _pendingHead = subscriber;
     }
     else {
-        subscriber.notify();
+        _pendingTail.pendingNext = subscriber;
+    }
+    _pendingTail = subscriber;
+}
+function clearPendingQueue() {
+    let subscriber = _pendingHead;
+    while (subscriber !== null) {
+        const next = subscriber.pendingNext;
+        subscriber.flags &= ~PENDING;
+        subscriber.pendingNext = null;
+        subscriber = next;
+    }
+    _pendingHead = null;
+    _pendingTail = null;
+}
+function flushPendingNotifications() {
+    if (_flushDepth > 0)
+        return;
+    _flushDepth++;
+    let failed = false;
+    try {
+        while (_pendingHead !== null) {
+            const subscriber = _pendingHead;
+            _pendingHead = subscriber.pendingNext;
+            subscriber.pendingNext = null;
+            if (_pendingHead === null)
+                _pendingTail = null;
+            if (!(subscriber.flags & PENDING))
+                continue;
+            subscriber.flags &= ~PENDING;
+            subscriber.notify();
+        }
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        // On failure, do not leave subscribers permanently stuck with PENDING set.
+        if (failed)
+            clearPendingQueue();
+        _flushDepth--;
     }
 }
+// Every signal write is an implicit batch: versions are bumped, invalidations
+// are pushed through the whole graph, and only then are effects notified.
 export function scheduleSource(source) {
-    let link = source.subsHead;
-    while (link) {
-        const next = link.nextInSource;
-        queueSubscriber(link.subscriber);
-        link = next;
+    source.version++;
+    if (_batchDepth !== 0) {
+        invalidateSource(source);
+        return;
+    }
+    // Fast path: without computed subscribers there is no derived state that
+    // could be observed mid-write, so effects can run right away (glitches are
+    // impossible).
+    if (source.computedCount === 0) {
+        let link = source.subsHead;
+        while (link) {
+            const next = link.nextInSource;
+            link.subscriber.notify();
+            link = next;
+        }
+        return;
+    }
+    _batchDepth = 1;
+    try {
+        invalidateSource(source);
+    }
+    finally {
+        _batchDepth = 0;
+        if (_pendingHead !== null)
+            flushPendingNotifications();
     }
 }
 export function batch(fn) {
@@ -151,14 +240,8 @@ export function batch(fn) {
     }
     finally {
         _batchDepth--;
-        if (_batchDepth === 0) {
-            const pending = _pendingNotifications.splice(0);
-            for (const sub of pending) {
-                if (!sub.pending)
-                    continue;
-                sub.pending = false;
-                sub.notify();
-            }
+        if (_batchDepth === 0 && _pendingHead !== null) {
+            flushPendingNotifications();
         }
     }
 }
@@ -175,39 +258,120 @@ export function untracked(fn) {
 }
 // ─── Effect ──────────────────────────────────────────────────────────────────
 const MAX_EFFECT_ITERATIONS = 100;
+function dependenciesChanged(subscriber) {
+    if (!subscriber.initialized)
+        return true;
+    let link = subscriber.depsHead;
+    while (link) {
+        const source = link.source;
+        // Pull derived values before comparing: a dirty computed may still end up
+        // producing the same value, which lets us skip the re-run entirely.
+        if (source.refresh !== null)
+            source.refresh();
+        if (source.version !== link.seenVersion)
+            return true;
+        link = link.nextInSubscriber;
+    }
+    return false;
+}
 /**
  * Creates an effect that runs immediately and tracks dependencies.
+ *
+ * The callback may return a cleanup function. It is invoked before every
+ * re-run and when the effect is stopped.
+ *
  * @param fn The function to execute.
  * @returns An unsubscribe function.
  */
 export function effect(fn) {
-    const effectObj = {};
-    effectObj.notify = () => {
-        if (effectObj.isRunning) {
-            effectObj.needsRerun = true;
+    const instance = new EffectImpl(fn);
+    instance.notify();
+    return () => instance.stop();
+}
+// Class-based so every effect shares the same hidden class and prototype
+// methods. This keeps subscription lists monomorphic for V8 and avoids
+// allocating a pair of closures per effect instance.
+class EffectImpl {
+    depsHead = null;
+    depsTail = null;
+    trackId = 0;
+    flags = 0;
+    initialized = false;
+    isComputed = false;
+    pendingNext = null;
+    _fn;
+    _cleanup = null;
+    constructor(fn) {
+        this._fn = fn;
+    }
+    notify() {
+        if (this.flags & DISPOSED)
+            return;
+        if (this.flags & RUNNING) {
+            this.flags |= NEEDS_RERUN;
+            return;
+        }
+        if (!dependenciesChanged(this))
+            return;
+        this._run();
+    }
+    invalidate() {
+        if (this.flags & DISPOSED)
             return;
+        if (_batchDepth !== 0) {
+            if (!(this.flags & PENDING))
+                enqueueSubscriber(this);
         }
-        effectObj.isRunning = true;
+        else {
+            this.notify();
+        }
+    }
+    stop() {
+        if (this.flags & DISPOSED)
+            return;
+        try {
+            if (this._cleanup !== null) {
+                const previousCleanup = this._cleanup;
+                this._cleanup = null;
+                previousCleanup();
+            }
+        }
+        finally {
+            cleanupSubscriber(this);
+        }
+    }
+    _run() {
+        this.flags |= RUNNING;
         let iterations = 0;
         try {
             do {
                 if (++iterations > MAX_EFFECT_ITERATIONS) {
                     throw new Error('Circular dependency detected: effect exceeded maximum re-run limit');
                 }
-                effectObj.needsRerun = false;
-                trackSubscriber(effectObj, fn);
-            } while (effectObj.needsRerun);
+                this.flags &= ~NEEDS_RERUN;
+                if (this._cleanup !== null) {
+                    const previousCleanup = this._cleanup;
+                    this._cleanup = null;
+                    previousCleanup();
+                }
+                const result = trackSubscriber(this, this._fn);
+                this._cleanup = typeof result === 'function' ? result : null;
+                this.initialized = true;
+                if (this.flags & DISPOSED) {
+                    if (this._cleanup !== null) {
+                        const finalCleanup = this._cleanup;
+                        this._cleanup = null;
+                        finalCleanup();
+                    }
+                    // Dependencies read after stop() was called during this run were
+                    // linked again; remove them so a disposed effect holds no references.
+                    cleanupSubscriber(this);
+                    break;
+                }
+            } while (this.flags & NEEDS_RERUN);
         }
         finally {
-            effectObj.isRunning = false;
+            this.flags &= ~RUNNING;
         }
-    };
-    effectObj.depsHead = null;
-    effectObj.depsTail = null;
-    effectObj.trackId = 0;
-    effectObj.pending = false;
-    effectObj.isRunning = false;
-    effectObj.needsRerun = false;
-    effectObj.notify();
-    return () => cleanupSubscriber(effectObj);
+    }
 }

package/dist/signal.d.ts

@@ -1,5 +1,10 @@
 export interface ReadonlySignal<T> {
     readonly value: T;
+    /**
+     * Reads the current value without subscribing the active effect/computed.
+     * Unlike `untracked(() => sig.value)` this avoids allocating a closure.
+     */
+    peek(): T;
 }
 export interface Signal<T> extends ReadonlySignal<T> {
     value: T;

package/dist/signal.js

@@ -19,9 +19,15 @@ class SignalImpl {
     set value(newValue) {
         if (this._value !== newValue) {
             this._value = newValue;
-            scheduleSource(this._source);
+            // Writes with no subscribers are a pure property assignment: skip the
+            // scheduling machinery entirely.
+            if (this._source.subsHead !== null)
+                scheduleSource(this._source);
         }
     }
+    peek() {
+        return this._value;
+    }
 }
 /**
  * Creates a reactive signal.

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@hoosk/minisignals",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Minimal agnostic signals library",
+  "type": "module",
+  "sideEffects": false,
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +14,6 @@
       "default": "./dist/index.js"
     }
   },
-  "type": "module",
   "files": [
     "dist"
   ],
@@ -22,7 +23,22 @@
     "test": "vitest run",
     "bench": "npm run build && node ./bench/core.bench.mjs"
   },
-  "keywords": [],
+  "keywords": [
+    "signals",
+    "reactive",
+    "reactivity",
+    "state",
+    "computed",
+    "effect",
+    "signal",
+    "observable",
+    "framework-agnostic"
+  ],
   "author": "Hoosk",
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hoosk/minisignals.git",
+    "directory": "packages/core"
+  }
 }