@hoosk/minisignals 1.0.7 → 1.1.1

package/README.md

@@ -31,4 +31,36 @@ batch(() => {
 }); // Logs once: Count: 20, Double: 40
 ```
 
-For full documentation and advanced features, please refer to the [main repository README](../../README.md).
+## 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.
+
+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
+
+── 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
+
+── 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
+```
+
+Run `npm run bench` to reproduce locally.
+
+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,7 +1,7 @@
 import { ReadonlySignal } from './signal.js';
 export interface Computed<T> extends ReadonlySignal<T> {
     /**
-     * Stops the internal effect from observing dependencies.
+     * Stops the computed signal from observing dependencies.
      * Call this when the computed signal is no longer needed to prevent memory leaks.
      */
     dispose: () => void;

package/dist/computed.js

@@ -1,5 +1,4 @@
-import { signal } from './signal.js';
-import { effect } from './effect.js';
+import { cleanupSubscriber, createDependencySource, getActiveSubscriber, PENDING, scheduleSource, trackDependency, trackSubscriber, } from './effect.js';
 /**
  * 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.
@@ -8,39 +7,53 @@ import { effect } from './effect.js';
  * @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,
+        flags: 0,
+    };
     let initialized = false;
-    let internalSignal = null;
-    let unsubscribe = null;
     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.flags &= ~PENDING;
+        cachedValue = trackSubscriber(observer, fn);
+        initialized = true;
+        dirty = false;
+    }
     return {
         get value() {
+            if (getActiveSubscriber())
+                trackDependency(source);
             if (isDisposed) {
                 if (!initialized) {
-                    internalSignal = signal(fn());
+                    cachedValue = fn();
                     initialized = true;
+                    dirty = false;
                 }
-                return internalSignal.value;
-            }
-            if (!initialized) {
-                unsubscribe = effect(() => {
-                    const newValue = fn();
-                    if (!initialized) {
-                        internalSignal = signal(newValue);
-                        initialized = true;
-                    }
-                    else {
-                        internalSignal.value = newValue;
-                    }
-                });
+                return cachedValue;
             }
-            return internalSignal.value;
+            if (!initialized || dirty)
+                refreshValue();
+            return cachedValue;
         },
         dispose() {
             isDisposed = true;
-            if (unsubscribe) {
-                unsubscribe();
-                unsubscribe = null;
-            }
-        }
+            dirty = false;
+            cleanupSubscriber(observer);
+        },
     };
 }

package/dist/effect.d.ts

@@ -1,13 +1,40 @@
-export type SubscriberSet = Set<() => void>;
-interface ActiveEffect {
-    run: () => void;
-    deps: Set<SubscriberSet>;
-    isRunning: boolean;
-    needsRerun: boolean;
+export declare const PENDING: number;
+export declare const RUNNING: number;
+export declare const NEEDS_RERUN: number;
+export interface DependencySource {
+    subsHead: DependencyLink | null;
+    currentLink: DependencyLink | null;
 }
-export declare function getActiveEffect(): ActiveEffect | null;
-export declare function scheduleSubs(subscribers: SubscriberSet): void;
+interface DependencyLink {
+    source: DependencySource;
+    subscriber: Subscriber;
+    trackId: number;
+    rollbackCurrentLink: DependencyLink | null;
+    nextInSource: DependencyLink | null;
+    prevInSource: DependencyLink | null;
+    nextInSubscriber: DependencyLink | null;
+    prevInSubscriber: DependencyLink | null;
+}
+export interface Subscriber {
+    notify: () => void;
+    depsHead: DependencyLink | null;
+    depsTail: DependencyLink | null;
+    trackId: number;
+    flags: number;
+}
+declare let _activeSubscriber: Subscriber | null;
+export { _activeSubscriber };
+export declare function createDependencySource(): DependencySource;
+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 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.
+ * @param fn The function to execute.
+ * @returns An unsubscribe function.
+ */
 export declare function effect(fn: () => void): () => void;
-export {};

package/dist/effect.js

@@ -1,20 +1,150 @@
-let _activeEffect = null;
-export function getActiveEffect() {
-    return _activeEffect;
+// ─── Subscriber flags ───────────────────────────────────────────────────────
+export const PENDING = 1 << 0; // queued in _pendingNotifications
+export const RUNNING = 1 << 1; // effect is currently executing
+export const NEEDS_RERUN = 1 << 2; // dependency changed while RUNNING
+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.
+export { _activeSubscriber };
+export function createDependencySource() {
+    return { subsHead: null, currentLink: null };
 }
-// --- Batch scheduling ---
+export function getActiveSubscriber() {
+    return _activeSubscriber;
+}
+// ─── Link management ─────────────────────────────────────────────────────────
+// Before running a subscriber, stamp each of its existing dep links onto
+// source.currentLink (saving whatever was there as rollbackCurrentLink).
+// This lets linkDependency find the reusable link with a single pointer read.
+function prepareSources(subscriber) {
+    let link = subscriber.depsHead;
+    while (link) {
+        link.rollbackCurrentLink = link.source.currentLink;
+        link.source.currentLink = link;
+        link = link.nextInSubscriber;
+    }
+}
+function linkDependency(source, subscriber) {
+    const existing = source.currentLink;
+    if (existing !== null && existing.subscriber === subscriber) {
+        // Stable dep: just mark as seen in this run.
+        existing.trackId = subscriber.trackId;
+        return;
+    }
+    // New dep: create a link and install it. Save whatever was in currentLink
+    // so it can be restored when the tracking pass finishes (rollback chain).
+    const link = {
+        source,
+        subscriber,
+        trackId: subscriber.trackId,
+        rollbackCurrentLink: existing,
+        nextInSource: source.subsHead,
+        prevInSource: null,
+        nextInSubscriber: null,
+        prevInSubscriber: subscriber.depsTail,
+    };
+    if (source.subsHead)
+        source.subsHead.prevInSource = link;
+    source.subsHead = link;
+    if (subscriber.depsTail) {
+        subscriber.depsTail.nextInSubscriber = link;
+    }
+    else {
+        subscriber.depsHead = link;
+    }
+    subscriber.depsTail = link;
+    source.currentLink = link;
+}
+function unlinkDependency(link) {
+    const { source, subscriber } = link;
+    if (link.prevInSource) {
+        link.prevInSource.nextInSource = link.nextInSource;
+    }
+    else {
+        source.subsHead = link.nextInSource;
+    }
+    if (link.nextInSource)
+        link.nextInSource.prevInSource = link.prevInSource;
+    if (link.prevInSubscriber) {
+        link.prevInSubscriber.nextInSubscriber = link.nextInSubscriber;
+    }
+    else {
+        subscriber.depsHead = link.nextInSubscriber;
+    }
+    if (link.nextInSubscriber) {
+        link.nextInSubscriber.prevInSubscriber = link.prevInSubscriber;
+    }
+    else {
+        subscriber.depsTail = link.prevInSubscriber;
+    }
+    link.nextInSource = link.prevInSource = null;
+    link.nextInSubscriber = link.prevInSubscriber = null;
+}
+// After the fn runs: prune stale links and restore source.currentLink for all
+// links we touched (both kept and removed) so outer contexts are unaffected.
+function pruneStaleDependencies(subscriber) {
+    let link = subscriber.depsHead;
+    while (link) {
+        const next = link.nextInSubscriber;
+        // Restore regardless of whether we keep or prune the link.
+        link.source.currentLink = link.rollbackCurrentLink;
+        link.rollbackCurrentLink = null;
+        if (link.trackId !== subscriber.trackId)
+            unlinkDependency(link);
+        link = next;
+    }
+}
+export function trackDependency(source) {
+    if (_activeSubscriber)
+        linkDependency(source, _activeSubscriber);
+}
+export function trackSubscriber(subscriber, fn) {
+    const previous = _activeSubscriber;
+    subscriber.trackId++;
+    prepareSources(subscriber);
+    _activeSubscriber = subscriber;
+    try {
+        return fn();
+    }
+    finally {
+        _activeSubscriber = previous;
+        pruneStaleDependencies(subscriber);
+    }
+}
+export function cleanupSubscriber(subscriber) {
+    let link = subscriber.depsHead;
+    while (link) {
+        const next = link.nextInSubscriber;
+        // Restore currentLink if it still points to this link.
+        if (link.source.currentLink === link) {
+            link.source.currentLink = link.rollbackCurrentLink;
+        }
+        link.rollbackCurrentLink = null;
+        unlinkDependency(link);
+        link = next;
+    }
+    subscriber.flags &= ~PENDING;
+}
+// ─── Batch scheduling ────────────────────────────────────────────────────────
 let _batchDepth = 0;
-const _pendingNotifications = new Set();
-export function scheduleSubs(subscribers) {
+const _pendingNotifications = [];
+function queueSubscriber(subscriber) {
     if (_batchDepth > 0) {
-        for (const sub of subscribers) {
-            _pendingNotifications.add(sub);
+        if (!(subscriber.flags & PENDING)) {
+            subscriber.flags |= PENDING;
+            _pendingNotifications.push(subscriber);
         }
     }
     else {
-        for (const sub of [...subscribers]) {
-            sub();
-        }
+        subscriber.notify();
+    }
+}
+export function scheduleSource(source) {
+    let link = source.subsHead;
+    while (link) {
+        const next = link.nextInSource;
+        queueSubscriber(link.subscriber);
+        link = next;
     }
 }
 export function batch(fn) {
@@ -25,73 +155,60 @@ export function batch(fn) {
     finally {
         _batchDepth--;
         if (_batchDepth === 0) {
-            const pending = [..._pendingNotifications];
-            _pendingNotifications.clear();
+            const pending = _pendingNotifications.splice(0);
             for (const sub of pending) {
-                sub();
+                if (!(sub.flags & PENDING))
+                    continue;
+                sub.flags &= ~PENDING;
+                sub.notify();
             }
         }
     }
 }
-// --- Untracked read ---
+// ─── Untracked read ───────────────────────────────────────────────────────────
 export function untracked(fn) {
-    const previous = _activeEffect;
-    _activeEffect = null;
+    const previous = _activeSubscriber;
+    _activeSubscriber = null;
     try {
         return fn();
     }
     finally {
-        _activeEffect = previous;
+        _activeSubscriber = previous;
     }
 }
-// --- Effect ---
+// ─── Effect ──────────────────────────────────────────────────────────────────
+const MAX_EFFECT_ITERATIONS = 100;
 /**
  * Creates an effect that runs immediately and tracks dependencies.
  * @param fn The function to execute.
  * @returns An unsubscribe function.
  */
-const MAX_EFFECT_ITERATIONS = 100;
 export function effect(fn) {
-    const effectObj = {
-        run() {
-            if (effectObj.isRunning) {
-                effectObj.needsRerun = true;
-                return;
-            }
-            effectObj.isRunning = true;
-            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;
-                    cleanup(effectObj);
-                    const previousEffect = _activeEffect;
-                    _activeEffect = effectObj;
-                    try {
-                        fn();
-                    }
-                    finally {
-                        _activeEffect = previousEffect;
-                    }
-                } while (effectObj.needsRerun);
-            }
-            finally {
-                effectObj.isRunning = false;
-            }
-        },
-        deps: new Set(),
-        isRunning: false,
-        needsRerun: false,
-    };
-    function cleanup(eff) {
-        for (const depSet of eff.deps) {
-            depSet.delete(eff.run);
+    const effectObj = {};
+    effectObj.notify = () => {
+        if (effectObj.flags & RUNNING) {
+            effectObj.flags |= NEEDS_RERUN;
+            return;
         }
-        eff.deps.clear();
-        _pendingNotifications.delete(eff.run);
-    }
-    effectObj.run();
-    return () => cleanup(effectObj);
+        effectObj.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.flags &= ~NEEDS_RERUN;
+                trackSubscriber(effectObj, fn);
+            } while (effectObj.flags & NEEDS_RERUN);
+        }
+        finally {
+            effectObj.flags &= ~RUNNING;
+        }
+    };
+    effectObj.depsHead = null;
+    effectObj.depsTail = null;
+    effectObj.trackId = 0;
+    effectObj.flags = 0;
+    effectObj.notify();
+    return () => cleanupSubscriber(effectObj);
 }

package/dist/signal.js

@@ -1,26 +1,33 @@
-import { getActiveEffect, scheduleSubs } from './effect.js';
+import { _activeSubscriber, createDependencySource, scheduleSource, trackDependency } from './effect.js';
+// Class-based implementation so all signal instances share the same prototype
+// getter/setter. V8 can monomorphize and inline the accessors instead of
+// treating every signal as a unique object with closure-based functions.
+class SignalImpl {
+    /** @internal */ _source;
+    /** @internal */ _value;
+    constructor(initialValue) {
+        this._source = createDependencySource();
+        this._value = initialValue;
+    }
+    get value() {
+        // Inline null-check to avoid the trackDependency() function call entirely
+        // when there is no active subscriber — the common case outside effects.
+        if (_activeSubscriber !== null)
+            trackDependency(this._source);
+        return this._value;
+    }
+    set value(newValue) {
+        if (this._value !== newValue) {
+            this._value = newValue;
+            scheduleSource(this._source);
+        }
+    }
+}
 /**
  * Creates a reactive signal.
  * @param initialValue The starting value.
  * @returns An object with a reactive .value property.
  */
 export function signal(initialValue) {
-    const subscribers = new Set();
-    let _value = initialValue;
-    return {
-        get value() {
-            const active = getActiveEffect();
-            if (active) {
-                subscribers.add(active.run);
-                active.deps.add(subscribers);
-            }
-            return _value;
-        },
-        set value(newValue) {
-            if (_value !== newValue) {
-                _value = newValue;
-                scheduleSubs(subscribers);
-            }
-        }
-    };
+    return new SignalImpl(initialValue);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoosk/minisignals",
-  "version": "1.0.7",
+  "version": "1.1.1",
   "description": "Minimal agnostic signals library",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -19,9 +19,10 @@
   "scripts": {
     "build": "tsc",
     "prepare": "npm run build",
-    "test": "vitest run"
+    "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"
 }