flint-reactivity 4.0.0

package/dist/signals.js

@@ -0,0 +1,757 @@
+// Flint Reactivity — Core signals implementation v4
+// Version-based dirty tracking with automatic dependency tracking
+import { SIGNAL_BRAND, COMPUTED_BRAND, EFFECT_BRAND, } from './types.js';
+// ─── Global State ───────────────────────────────────────────────
+let currentSubscriber = null;
+let currentScope = null;
+let writeVersion = 0;
+let readVersion = 0;
+let batchDepth = 0;
+let pendingEffects = new Set();
+let pendingComputeds = new Set();
+let flushScheduled = false;
+// ─── Equality ───────────────────────────────────────────────────
+function defaultEquals(a, b) {
+    return Object.is(a, b);
+}
+// ─── Dependency Tracking ────────────────────────────────────────
+function track(signal) {
+    if (currentSubscriber) {
+        signal.observers.add(currentSubscriber);
+        currentSubscriber.dependencies.add(signal);
+    }
+}
+function untrackAll(subscriber) {
+    for (const dep of subscriber.dependencies) {
+        dep.observers.delete(subscriber);
+    }
+    subscriber.dependencies.clear();
+}
+// ─── Dirty Marking ──────────────────────────────────────────────
+const updatingComputeds = new WeakSet();
+function markDirty(signal) {
+    signal.version = writeVersion;
+    for (const observer of signal.observers) {
+        if (observer.kind === 'computed') {
+            if (!observer.dirty) {
+                if (updatingComputeds.has(observer)) {
+                    console.warn('[Flint] Circular computed dependency detected:', observer);
+                    continue;
+                }
+                observer.dirty = true;
+                markDirty(observer);
+            }
+        }
+        else if (observer.kind === 'effect') {
+            scheduleEffect(observer);
+        }
+    }
+}
+function isDirty(computed) {
+    for (const dep of computed.dependencies) {
+        if (dep.version > computed.version) {
+            return true;
+        }
+    }
+    return false;
+}
+function refreshComputedDeps(deps) {
+    for (const dep of deps) {
+        if (dep.kind === 'computed' && !dep.disposed) {
+            refreshComputedDeps(dep.dependencies);
+            if (dep.dirty || isDirty(dep)) {
+                updateComputed(dep);
+            }
+        }
+    }
+}
+function isEffectStale(effectState) {
+    refreshComputedDeps(effectState.dependencies);
+    for (const dep of effectState.dependencies) {
+        if (dep.changeVersion > effectState.version) {
+            return true;
+        }
+    }
+    return false;
+}
+// ─── Effect Scheduling ──────────────────────────────────────────
+function scheduleEffect(effect) {
+    if (!effect.disposed) {
+        pendingEffects.add(effect);
+    }
+    scheduleFlush();
+}
+function scheduleFlush() {
+    if (!flushScheduled && batchDepth === 0) {
+        flushScheduled = true;
+        queueMicrotask(flush);
+    }
+}
+function flush() {
+    flushScheduled = false;
+    while (pendingComputeds.size > 0) {
+        const computeds = [...pendingComputeds];
+        pendingComputeds.clear();
+        for (const computed of computeds) {
+            if (computed.dirty && !computed.disposed) {
+                updateComputed(computed);
+            }
+        }
+    }
+    const effects = [...pendingEffects];
+    pendingEffects.clear();
+    for (const effectState of effects) {
+        if (!effectState.disposed && isEffectStale(effectState)) {
+            runEffect(effectState);
+        }
+    }
+}
+// ─── Core Primitives ────────────────────────────────────────────
+function updateComputed(computed) {
+    updateComputedWithEquals(computed, computed.equals ?? defaultEquals);
+}
+function updateComputedWithEquals(computed, comparator) {
+    if (updatingComputeds.has(computed)) {
+        console.warn('[Flint] Circular computed dependency detected during update:', computed);
+        return;
+    }
+    updatingComputeds.add(computed);
+    untrackAll(computed);
+    const prevSubscriber = currentSubscriber;
+    currentSubscriber = computed;
+    computed.tracking = true;
+    readVersion++;
+    try {
+        const prevValue = computed.value;
+        const newValue = computed.fn();
+        const unchanged = comparator(prevValue, newValue);
+        if (!unchanged) {
+            computed.value = newValue;
+            computed.version = writeVersion;
+            computed.changeVersion = writeVersion;
+            for (const observer of computed.observers) {
+                if (observer.kind === 'computed') {
+                    if (!observer.dirty) {
+                        observer.dirty = true;
+                        pendingComputeds.add(observer);
+                    }
+                }
+                else if (observer.kind === 'effect') {
+                    scheduleEffect(observer);
+                }
+            }
+        }
+        computed.dirty = false;
+    }
+    finally {
+        computed.tracking = false;
+        currentSubscriber = prevSubscriber;
+        updatingComputeds.delete(computed);
+    }
+}
+function runEffect(effect) {
+    if (effect.disposed)
+        return;
+    if (effect.cleanup) {
+        effect.cleanup();
+        effect.cleanup = null;
+    }
+    untrackAll(effect);
+    const prevSubscriber = currentSubscriber;
+    currentSubscriber = effect;
+    effect.tracking = true;
+    readVersion++;
+    try {
+        const result = effect.fn();
+        if (typeof result === 'function') {
+            effect.cleanup = result;
+        }
+        effect.version = writeVersion;
+    }
+    finally {
+        effect.tracking = false;
+        currentSubscriber = prevSubscriber;
+    }
+}
+// ─── Public API ─────────────────────────────────────────────────
+/**
+ * Create a reactive state signal.
+ *
+ * @example
+ * const count = state(0)
+ * count()      // read: 0
+ * count.set(5) // write: 5
+ * count.set(c => c + 1) // write: 6
+ */
+export function state(initial) {
+    const signalState = {
+        kind: 'signal',
+        value: initial,
+        version: 0,
+        changeVersion: 0,
+        observers: new Set(),
+        comparator: defaultEquals,
+    };
+    const read = (() => {
+        track(signalState);
+        return signalState.value;
+    });
+    Object.defineProperty(read, SIGNAL_BRAND, { value: true });
+    read.set = (value) => {
+        const newValue = typeof value === 'function'
+            ? value(signalState.value)
+            : value;
+        if (!signalState.comparator(signalState.value, newValue)) {
+            signalState.value = newValue;
+            writeVersion++;
+            signalState.changeVersion = writeVersion;
+            markDirty(signalState);
+            scheduleFlush();
+        }
+    };
+    read.peek = () => signalState.value;
+    read.subscribe = (fn) => {
+        const eff = effect(() => fn(signalState.value));
+        return () => eff.dispose();
+    };
+    read.map = (fn) => {
+        return computed(() => fn(signalState.value));
+    };
+    read.pipe = (fn1) => {
+        return computed(() => fn1(signalState.value));
+    };
+    return read;
+}
+/**
+ * Create a computed (derived) value.
+ * Lazily evaluated and cached. Only recomputes when dependencies change.
+ */
+export function computed(fn, options) {
+    const comparator = options?.equals ?? defaultEquals;
+    const computedState = {
+        kind: 'computed',
+        value: undefined,
+        version: 0,
+        changeVersion: 0,
+        dirty: true,
+        disposed: false,
+        fn,
+        observers: new Set(),
+        dependencies: new Set(),
+        tracking: false,
+    };
+    const read = (() => {
+        track(computedState);
+        if (computedState.dirty || isDirty(computedState)) {
+            updateComputedWithEquals(computedState, comparator);
+        }
+        return computedState.value;
+    });
+    Object.defineProperty(read, COMPUTED_BRAND, { value: true });
+    computedState.equals = comparator;
+    updateComputedWithEquals(computedState, comparator);
+    return read;
+}
+/**
+ * Create a writable computed value.
+ * Like computed, but can be set directly.
+ *
+ * @example
+ * const count = state(0)
+ * const doubled = computedSet({
+ *   get: () => count() * 2,
+ *   set: (value) => count.set(value / 2)
+ * })
+ *
+ * doubled()      // read: 0
+ * doubled.set(10) // write: sets count to 5
+ */
+export function computedSet(options) {
+    const comparator = options.equals ?? defaultEquals;
+    const computedState = {
+        kind: 'computed',
+        value: undefined,
+        version: 0,
+        changeVersion: 0,
+        dirty: true,
+        disposed: false,
+        fn: options.get,
+        observers: new Set(),
+        dependencies: new Set(),
+        tracking: false,
+    };
+    const read = (() => {
+        track(computedState);
+        if (computedState.dirty || isDirty(computedState)) {
+            updateComputedWithEquals(computedState, comparator);
+        }
+        return computedState.value;
+    });
+    Object.defineProperty(read, COMPUTED_BRAND, { value: true });
+    computedState.equals = comparator;
+    updateComputedWithEquals(computedState, comparator);
+    // Add set method
+    read.set = (value) => {
+        const newValue = typeof value === 'function'
+            ? value(computedState.value)
+            : value;
+        options.set(newValue);
+    };
+    read.peek = () => computedState.value;
+    return read;
+}
+/**
+ * Create a side effect that auto-tracks dependencies.
+ */
+export function effect(fn) {
+    const effectState = {
+        kind: 'effect',
+        fn,
+        cleanup: null,
+        dependencies: new Set(),
+        tracking: false,
+        disposed: false,
+        version: 0,
+    };
+    runEffect(effectState);
+    return {
+        [EFFECT_BRAND]: true,
+        dispose() {
+            effectState.disposed = true;
+            if (effectState.cleanup) {
+                effectState.cleanup();
+                effectState.cleanup = null;
+            }
+            untrackAll(effectState);
+        },
+    };
+}
+/**
+ * Watch a source function and call callback when value changes.
+ */
+export function watch(source, callback) {
+    let lastValue = undefined;
+    let initialized = false;
+    const eff = effect(() => {
+        const value = source();
+        if (initialized) {
+            callback(value, lastValue);
+        }
+        lastValue = value;
+        initialized = true;
+    });
+    return {
+        dispose() {
+            eff.dispose();
+        },
+    };
+}
+/**
+ * Batch multiple signal updates into a single flush.
+ */
+export function batch(fn) {
+    batchDepth++;
+    try {
+        fn();
+    }
+    finally {
+        batchDepth--;
+        if (batchDepth === 0) {
+            scheduleFlush();
+        }
+    }
+}
+/**
+ * Run queued effects/computeds immediately.
+ */
+export function flushSync() {
+    flush();
+}
+// ─── captureScope ─────────────────────────────────────────────
+export function captureScope(fn) {
+    const probe = {
+        kind: 'effect',
+        fn: () => undefined,
+        cleanup: null,
+        dependencies: new Set(),
+        tracking: true,
+        disposed: true,
+        version: 0,
+    };
+    const prevSubscriber = currentSubscriber;
+    currentSubscriber = probe;
+    let value;
+    try {
+        value = fn();
+    }
+    finally {
+        currentSubscriber = prevSubscriber;
+        for (const dep of probe.dependencies) {
+            dep.observers.delete(probe);
+        }
+    }
+    return { value, dependencies: probe.dependencies };
+}
+// ─── untrack ────────────────────────────────────────────────────
+export function untrack(fn) {
+    const prevSubscriber = currentSubscriber;
+    currentSubscriber = null;
+    try {
+        return fn();
+    }
+    finally {
+        currentSubscriber = prevSubscriber;
+    }
+}
+// ─── createRoot / Scope ─────────────────────────────────────────
+export function createRoot(fn) {
+    const scopeState = {
+        kind: 'scope',
+        disposables: [],
+        disposed: false,
+        parent: currentScope,
+    };
+    const prevScope = currentScope;
+    currentScope = scopeState;
+    function dispose() {
+        if (scopeState.disposed)
+            return;
+        scopeState.disposed = true;
+        for (let i = scopeState.disposables.length - 1; i >= 0; i--) {
+            try {
+                scopeState.disposables[i]();
+            }
+            catch (e) {
+                console.warn('[Flint] Disposable cleanup failed:', e);
+            }
+        }
+        scopeState.disposables.length = 0;
+        currentScope = prevScope;
+    }
+    try {
+        const result = fn(dispose);
+        const scope = {
+            dispose,
+            onCleanup(fn) {
+                if (!scopeState.disposed) {
+                    scopeState.disposables.push(fn);
+                }
+            },
+            get disposed() {
+                return scopeState.disposed;
+            },
+        };
+        return Object.assign(result, scope);
+    }
+    finally {
+        currentScope = prevScope;
+    }
+}
+export function onCleanup(fn) {
+    if (currentScope) {
+        currentScope.disposables.push(fn);
+    }
+    if (currentSubscriber && currentSubscriber.kind === 'effect') {
+        const effectState = currentSubscriber;
+        const prevCleanup = effectState.cleanup;
+        effectState.cleanup = () => {
+            if (prevCleanup)
+                prevCleanup();
+            fn();
+        };
+    }
+}
+// ─── createSelector ─────────────────────────────────────────────
+export function createSelector(source) {
+    const sourceFn = typeof source === 'function' ? source : () => source();
+    let currentValue;
+    const effectsByValue = new Map();
+    const eff = effect(() => {
+        currentValue = sourceFn();
+    });
+    function select(key) {
+        if (currentSubscriber) {
+            if (!effectsByValue.has(key)) {
+                effectsByValue.set(key, new Set());
+            }
+            effectsByValue.get(key).add(currentSubscriber);
+        }
+        return key === currentValue;
+    }
+    return Object.assign(select, {
+        setSelected(keyOrSet) {
+            if (keyOrSet instanceof Set) {
+                batch(() => {
+                    for (const key of keyOrSet) {
+                        const subs = effectsByValue.get(key);
+                        if (subs) {
+                            for (const sub of subs) {
+                                scheduleEffect(sub);
+                            }
+                        }
+                    }
+                });
+            }
+            else {
+                if (typeof source === 'function' && 'set' in source) {
+                    source.set(keyOrSet);
+                }
+                else if (typeof source !== 'function' && 'set' in source) {
+                    source.set(keyOrSet);
+                }
+            }
+        },
+        getSelected() {
+            return new Set([currentValue]);
+        },
+        isSelected(key) {
+            return key === currentValue;
+        },
+        dispose() {
+            eff.dispose();
+            effectsByValue.clear();
+        },
+    });
+}
+export { onCleanup as onDispose };
+// ─── NEW: Simplified APIs for Maximum DX ───────────────────────
+/**
+ * Create a reactive object with Proxy. Reads auto-track, writes auto-trigger.
+ *
+ * @example
+ * const user = reactive({ name: 'John', age: 30 })
+ * user.name  // tracked
+ * user.age = 31  // triggers effects
+ */
+export function reactive(obj) {
+    const signalMap = new Map();
+    for (const key of Object.keys(obj)) {
+        signalMap.set(key, state(obj[key]));
+    }
+    return new Proxy(obj, {
+        get(target, key) {
+            const sig = signalMap.get(key);
+            if (sig)
+                return sig();
+            return target[key];
+        },
+        set(target, key, value) {
+            const sig = signalMap.get(key);
+            if (sig) {
+                sig.set(value);
+            }
+            else {
+                signalMap.set(key, state(value));
+                target[key] = value;
+            }
+            return true;
+        },
+        has(target, key) {
+            return key in target;
+        },
+        ownKeys(target) {
+            return Reflect.ownKeys(target);
+        },
+        getOwnPropertyDescriptor(target, key) {
+            return Reflect.getOwnPropertyDescriptor(target, key);
+        },
+    });
+}
+/**
+ * Create a model — a reactive container with actions.
+ * Combines state + computed + actions in one clean API.
+ *
+ * @example
+ * const counter = model({
+ *   state: { count: 0, step: 1 },
+ *   computed: {
+ *     doubled: (s) => s.count * 2,
+ *     isPositive: (s) => s.count > 0,
+ *   },
+ *   actions: {
+ *     increment(s) { s.count += s.step },
+ *     decrement(s) { s.count -= s.step },
+ *     reset(s) { s.count = 0 },
+ *   },
+ * })
+ *
+ * counter.count()       // 0
+ * counter.doubled()     // 0
+ * counter.increment()   // s.count = 1
+ */
+export function model(config) {
+    const signals = {};
+    const result = {};
+    // Create signals for state
+    for (const [key, value] of Object.entries(config.state)) {
+        signals[key] = state(value);
+        result[key] = signals[key];
+    }
+    // Create computeds
+    if (config.computed) {
+        for (const [key, fn] of Object.entries(config.computed)) {
+            result[key] = computed(() => {
+                const currentState = {};
+                for (const [k, sig] of Object.entries(signals)) {
+                    ;
+                    currentState[k] = sig();
+                }
+                return fn(currentState);
+            });
+        }
+    }
+    // Create actions
+    if (config.actions) {
+        for (const [key, fn] of Object.entries(config.actions)) {
+            result[key] = (...args) => {
+                const mutableState = {};
+                for (const [k, sig] of Object.entries(signals)) {
+                    ;
+                    mutableState[k] = sig.peek();
+                }
+                ;
+                fn(mutableState, ...args);
+                for (const [k, sig] of Object.entries(signals)) {
+                    if (mutableState[k] !== sig.peek()) {
+                        sig.set(mutableState[k]);
+                    }
+                }
+            };
+        }
+    }
+    return result;
+}
+/**
+ * Create a two-way binding between a signal and a DOM element property.
+ * Simplifies form handling dramatically.
+ *
+ * @example
+ * const name = state('')
+ * <input {...bind(name, 'value')} onInput={(e) => name.set(e.target.value)} />
+ */
+export function bind(signal, prop) {
+    return {
+        [prop]: () => signal(),
+    };
+}
+/**
+ * Create a mutable ref (like React's useRef).
+ */
+export function createRef(initial) {
+    return { current: initial };
+}
+/**
+ * Create a shallow ref — only triggers on reference change, not deep mutation.
+ */
+export function shallowRef(value) {
+    const sig = state(value);
+    const ref = Object.assign((() => sig()), {
+        get current() { return sig(); },
+        set current(v) { sig.set(v); },
+        set: sig.set.bind(sig),
+        peek: sig.peek.bind(sig),
+    });
+    return ref;
+}
+/**
+ * Group multiple signals into a single derived signal.
+ *
+ * @example
+ * const [doubled, tripled] = derive(
+ *   [count],
+ *   (c) => [c * 2, c * 3]
+ * )
+ */
+export function derive(sources, fn) {
+    return computed(() => {
+        const values = sources.map(s => s());
+        return fn(...values);
+    });
+}
+/**
+ * Batch create multiple signals from an object.
+ *
+ * @example
+ * const [count, name, items] = signals(0, 'hello', [])
+ */
+export function signals(...initials) {
+    return initials.map(init => state(init));
+}
+/**
+ * Create an effect that runs on a specific interval.
+ *
+ * @example
+ * poll(() => fetchData(), 5000) // poll every 5 seconds
+ */
+export function poll(fn, ms) {
+    const id = setInterval(() => fn(), ms);
+    return {
+        [EFFECT_BRAND]: true,
+        dispose() {
+            clearInterval(id);
+        },
+    };
+}
+/**
+ * Create an effect that runs when a signal changes (debounced).
+ *
+ * @example
+ * watchDebounced(searchQuery, (q) => fetchResults(q), 300)
+ */
+export function watchDebounced(source, callback, ms) {
+    let timeoutId;
+    let lastValue;
+    let initialized = false;
+    const eff = effect(() => {
+        const value = source();
+        if (initialized) {
+            clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => callback(value, lastValue), ms);
+        }
+        lastValue = value;
+        initialized = true;
+    });
+    return {
+        dispose() {
+            clearTimeout(timeoutId);
+            eff.dispose();
+        },
+    };
+}
+/**
+ * Create an effect that runs when a signal changes (throttled).
+ */
+export function watchThrottled(source, callback, ms) {
+    let lastRun = 0;
+    let lastValue;
+    let initialized = false;
+    let pendingValue = false;
+    const eff = effect(() => {
+        const value = source();
+        if (initialized) {
+            const now = Date.now();
+            if (now - lastRun >= ms) {
+                lastRun = now;
+                callback(value, lastValue);
+            }
+            else {
+                pendingValue = value;
+                setTimeout(() => {
+                    if (pendingValue !== undefined) {
+                        callback(pendingValue, lastValue);
+                        pendingValue = undefined;
+                        lastRun = Date.now();
+                    }
+                }, ms - (now - lastRun));
+            }
+        }
+        lastValue = value;
+        initialized = true;
+    });
+    return {
+        dispose() {
+            eff.dispose();
+        },
+    };
+}
+//# sourceMappingURL=signals.js.map