@nerdalytics/beacon 1000.1.0 → 1000.1.1

package/dist/src/index.d.ts

@@ -0,0 +1,43 @@
+type Unsubscribe = () => void;
+export type ReadOnlyState<T> = () => T;
+export interface WriteableState<T> {
+    set(value: T): void;
+    update(fn: (value: T) => T): void;
+}
+declare const STATE_ID: unique symbol;
+export type State<T> = ReadOnlyState<T> & WriteableState<T> & {
+    [STATE_ID]?: symbol;
+};
+/**
+ * Creates a reactive state container with the provided initial value.
+ */
+export declare const state: <T>(initialValue: T) => State<T>;
+/**
+ * Registers a function to run whenever its reactive dependencies change.
+ */
+export declare const effect: (fn: () => void) => Unsubscribe;
+/**
+ * Groups multiple state updates to trigger effects only once at the end.
+ */
+export declare const batch: <T>(fn: () => T) => T;
+/**
+ * Creates a read-only computed value that updates when its dependencies change.
+ */
+export declare const derive: <T>(computeFn: () => T) => ReadOnlyState<T>;
+/**
+ * Creates an efficient subscription to a subset of a state value.
+ */
+export declare const select: <T, R>(source: ReadOnlyState<T>, selectorFn: (state: T) => R, equalityFn?: (a: R, b: R) => boolean) => ReadOnlyState<R>;
+/**
+ * Creates a read-only view of a state, hiding mutation methods.
+ */
+export declare const readonlyState: <T>(state: State<T>) => ReadOnlyState<T>;
+/**
+ * Creates a state with access control, returning a tuple of reader and writer.
+ */
+export declare const protectedState: <T>(initialValue: T) => [ReadOnlyState<T>, WriteableState<T>];
+/**
+ * Creates a lens for direct updates to nested properties of a state.
+ */
+export declare const lens: <T, K>(source: State<T>, accessor: (state: T) => K) => State<K>;
+export {};

package/dist/src/index.js

@@ -0,0 +1,520 @@
+// Special symbol used for internal tracking
+const STATE_ID = Symbol();
+/**
+ * Creates a reactive state container with the provided initial value.
+ */
+export const state = (initialValue) => StateImpl.createState(initialValue);
+/**
+ * Registers a function to run whenever its reactive dependencies change.
+ */
+export const effect = (fn) => StateImpl.createEffect(fn);
+/**
+ * Groups multiple state updates to trigger effects only once at the end.
+ */
+export const batch = (fn) => StateImpl.executeBatch(fn);
+/**
+ * Creates a read-only computed value that updates when its dependencies change.
+ */
+export const derive = (computeFn) => StateImpl.createDerive(computeFn);
+/**
+ * Creates an efficient subscription to a subset of a state value.
+ */
+export const select = (source, selectorFn, equalityFn = Object.is) => StateImpl.createSelect(source, selectorFn, equalityFn);
+/**
+ * Creates a read-only view of a state, hiding mutation methods.
+ */
+export const readonlyState = (state) => () => state();
+/**
+ * Creates a state with access control, returning a tuple of reader and writer.
+ */
+export const protectedState = (initialValue) => {
+    const fullState = state(initialValue);
+    return [
+        () => readonlyState(fullState)(),
+        {
+            set: (value) => fullState.set(value),
+            update: (fn) => fullState.update(fn),
+        },
+    ];
+};
+/**
+ * Creates a lens for direct updates to nested properties of a state.
+ */
+export const lens = (source, accessor) => StateImpl.createLens(source, accessor);
+class StateImpl {
+    // Static fields track global reactivity state - this centralized approach allows
+    // for coordinated updates while maintaining individual state isolation
+    static currentSubscriber = null;
+    static pendingSubscribers = new Set();
+    static isNotifying = false;
+    static batchDepth = 0;
+    static deferredEffectCreations = [];
+    static activeSubscribers = new Set();
+    // WeakMaps enable automatic garbage collection when subscribers are no
+    // longer referenced, preventing memory leaks in long-running applications
+    static stateTracking = new WeakMap();
+    static subscriberDependencies = new WeakMap();
+    static parentSubscriber = new WeakMap();
+    static childSubscribers = new WeakMap();
+    // Instance state - each state has unique subscribers and ID
+    value;
+    subscribers = new Set();
+    stateId = Symbol();
+    constructor(initialValue) {
+        this.value = initialValue;
+    }
+    /**
+     * Creates a reactive state container with the provided initial value.
+     * Implementation of the public 'state' function.
+     */
+    static createState = (initialValue) => {
+        const instance = new StateImpl(initialValue);
+        const get = () => instance.get();
+        get.set = (value) => instance.set(value);
+        get.update = (fn) => instance.update(fn);
+        get[STATE_ID] = instance.stateId;
+        return get;
+    };
+    // Auto-tracks dependencies when called within effects, creating a fine-grained
+    // reactivity graph that only updates affected components
+    get = () => {
+        const currentEffect = StateImpl.currentSubscriber;
+        if (currentEffect) {
+            // Add this effect to subscribers for future notification
+            this.subscribers.add(currentEffect);
+            // Maintain bidirectional dependency tracking to enable precise cleanup
+            // when effects are unsubscribed, preventing memory leaks
+            let dependencies = StateImpl.subscriberDependencies.get(currentEffect);
+            if (!dependencies) {
+                dependencies = new Set();
+                StateImpl.subscriberDependencies.set(currentEffect, dependencies);
+            }
+            dependencies.add(this.subscribers);
+            // Track read states to detect direct cyclical dependencies that
+            // could cause infinite loops
+            let readStates = StateImpl.stateTracking.get(currentEffect);
+            if (!readStates) {
+                readStates = new Set();
+                StateImpl.stateTracking.set(currentEffect, readStates);
+            }
+            readStates.add(this.stateId);
+        }
+        return this.value;
+    };
+    // Handles value updates with built-in optimizations and safeguards
+    set = (newValue) => {
+        // Skip updates for unchanged values to prevent redundant effect executions
+        if (Object.is(this.value, newValue)) {
+            return;
+        }
+        // Infinite loop detection prevents direct self-mutation within effects,
+        // while allowing nested effect patterns that would otherwise appear cyclical
+        const effect = StateImpl.currentSubscriber;
+        if (effect) {
+            const states = StateImpl.stateTracking.get(effect);
+            if (states?.has(this.stateId) && !StateImpl.parentSubscriber.get(effect)) {
+                throw new Error('Infinite loop detected: effect() cannot update a state() it depends on!');
+            }
+        }
+        this.value = newValue;
+        // Skip updates when there are no subscribers, avoiding unnecessary processing
+        if (this.subscribers.size === 0) {
+            return;
+        }
+        // Queue notifications instead of executing immediately to support batch operations
+        // and prevent redundant effect runs
+        for (const sub of this.subscribers) {
+            StateImpl.pendingSubscribers.add(sub);
+        }
+        // Immediate execution outside of batches, deferred execution inside batches
+        if (StateImpl.batchDepth === 0 && !StateImpl.isNotifying) {
+            StateImpl.notifySubscribers();
+        }
+    };
+    update = (fn) => {
+        this.set(fn(this.value));
+    };
+    /**
+     * Registers a function to run whenever its reactive dependencies change.
+     * Implementation of the public 'effect' function.
+     */
+    static createEffect = (fn) => {
+        const runEffect = () => {
+            // Prevent re-entrance to avoid cascade updates during effect execution
+            if (StateImpl.activeSubscribers.has(runEffect)) {
+                return;
+            }
+            StateImpl.activeSubscribers.add(runEffect);
+            const parentEffect = StateImpl.currentSubscriber;
+            try {
+                // Clean existing subscriptions before running to ensure only
+                // currently accessed states are tracked as dependencies
+                StateImpl.cleanupEffect(runEffect);
+                // Set current context for automatic dependency tracking
+                StateImpl.currentSubscriber = runEffect;
+                StateImpl.stateTracking.set(runEffect, new Set());
+                // Track parent-child relationships to handle nested effects correctly
+                // and enable hierarchical cleanup later
+                if (parentEffect) {
+                    StateImpl.parentSubscriber.set(runEffect, parentEffect);
+                    let children = StateImpl.childSubscribers.get(parentEffect);
+                    if (!children) {
+                        children = new Set();
+                        StateImpl.childSubscribers.set(parentEffect, children);
+                    }
+                    children.add(runEffect);
+                }
+                // Execute the effect function, which will auto-track dependencies
+                fn();
+            }
+            finally {
+                // Restore previous context when done
+                StateImpl.currentSubscriber = parentEffect;
+                StateImpl.activeSubscribers.delete(runEffect);
+            }
+        };
+        // Run immediately unless we're in a batch operation
+        if (StateImpl.batchDepth === 0) {
+            runEffect();
+        }
+        else {
+            // Still track parent-child relationship even when deferred,
+            // ensuring proper hierarchical cleanup later
+            if (StateImpl.currentSubscriber) {
+                const parent = StateImpl.currentSubscriber;
+                StateImpl.parentSubscriber.set(runEffect, parent);
+                let children = StateImpl.childSubscribers.get(parent);
+                if (!children) {
+                    children = new Set();
+                    StateImpl.childSubscribers.set(parent, children);
+                }
+                children.add(runEffect);
+            }
+            // Queue for execution when batch completes
+            StateImpl.deferredEffectCreations.push(runEffect);
+        }
+        // Return cleanup function to properly disconnect from reactivity graph
+        return () => {
+            // Remove from dependency tracking to stop future notifications
+            StateImpl.cleanupEffect(runEffect);
+            StateImpl.pendingSubscribers.delete(runEffect);
+            StateImpl.activeSubscribers.delete(runEffect);
+            StateImpl.stateTracking.delete(runEffect);
+            // Clean up parent-child relationship bidirectionally
+            const parent = StateImpl.parentSubscriber.get(runEffect);
+            if (parent) {
+                const siblings = StateImpl.childSubscribers.get(parent);
+                if (siblings) {
+                    siblings.delete(runEffect);
+                }
+            }
+            StateImpl.parentSubscriber.delete(runEffect);
+            // Recursively clean up child effects to prevent memory leaks in
+            // nested effect scenarios
+            const children = StateImpl.childSubscribers.get(runEffect);
+            if (children) {
+                for (const child of children) {
+                    StateImpl.cleanupEffect(child);
+                }
+                children.clear();
+                StateImpl.childSubscribers.delete(runEffect);
+            }
+        };
+    };
+    /**
+     * Groups multiple state updates to trigger effects only once at the end.
+     * Implementation of the public 'batch' function.
+     */
+    static executeBatch = (fn) => {
+        // Increment depth counter to handle nested batches correctly
+        StateImpl.batchDepth++;
+        try {
+            return fn();
+        }
+        catch (error) {
+            // Clean up on error to prevent stale subscribers from executing
+            // and potentially causing cascading errors
+            if (StateImpl.batchDepth === 1) {
+                StateImpl.pendingSubscribers.clear();
+                StateImpl.deferredEffectCreations.length = 0;
+            }
+            throw error;
+        }
+        finally {
+            StateImpl.batchDepth--;
+            // Only process effects when exiting the outermost batch,
+            // maintaining proper execution order while avoiding redundant runs
+            if (StateImpl.batchDepth === 0) {
+                // Process effects created during the batch
+                if (StateImpl.deferredEffectCreations.length > 0) {
+                    const effectsToRun = [...StateImpl.deferredEffectCreations];
+                    StateImpl.deferredEffectCreations.length = 0;
+                    for (const effect of effectsToRun) {
+                        effect();
+                    }
+                }
+                // Process state updates that occurred during the batch
+                if (StateImpl.pendingSubscribers.size > 0 && !StateImpl.isNotifying) {
+                    StateImpl.notifySubscribers();
+                }
+            }
+        }
+    };
+    /**
+     * Creates a read-only computed value that updates when its dependencies change.
+     * Implementation of the public 'derive' function.
+     */
+    static createDerive = (computeFn) => {
+        const valueState = StateImpl.createState(undefined);
+        let initialized = false;
+        let cachedValue;
+        // Internal effect automatically tracks dependencies and updates the derived value
+        StateImpl.createEffect(() => {
+            const newValue = computeFn();
+            // Only update if the value actually changed to preserve referential equality
+            // and prevent unnecessary downstream updates
+            if (!(initialized && Object.is(cachedValue, newValue))) {
+                cachedValue = newValue;
+                valueState.set(newValue);
+            }
+            initialized = true;
+        });
+        // Return function with lazy initialization - ensures value is available
+        // even when accessed before its dependencies have had a chance to update
+        return () => {
+            if (!initialized) {
+                cachedValue = computeFn();
+                initialized = true;
+                valueState.set(cachedValue);
+            }
+            return valueState();
+        };
+    };
+    /**
+     * Creates an efficient subscription to a subset of a state value.
+     * Implementation of the public 'select' function.
+     */
+    static createSelect = (source, selectorFn, equalityFn = Object.is) => {
+        let lastSourceValue;
+        let lastSelectedValue;
+        let initialized = false;
+        const valueState = StateImpl.createState(undefined);
+        // Internal effect to track the source and update only when needed
+        StateImpl.createEffect(() => {
+            const sourceValue = source();
+            // Skip computation if source reference hasn't changed
+            if (initialized && Object.is(lastSourceValue, sourceValue)) {
+                return;
+            }
+            lastSourceValue = sourceValue;
+            const newSelectedValue = selectorFn(sourceValue);
+            // Use custom equality function to determine if value semantically changed,
+            // allowing for deep equality comparisons with complex objects
+            if (initialized && lastSelectedValue !== undefined && equalityFn(lastSelectedValue, newSelectedValue)) {
+                return;
+            }
+            // Update cache and notify subscribers due the value has changed
+            lastSelectedValue = newSelectedValue;
+            valueState.set(newSelectedValue);
+            initialized = true;
+        });
+        // Return function with eager initialization capability
+        return () => {
+            if (!initialized) {
+                lastSourceValue = source();
+                lastSelectedValue = selectorFn(lastSourceValue);
+                valueState.set(lastSelectedValue);
+                initialized = true;
+            }
+            return valueState();
+        };
+    };
+    /**
+     * Creates a lens for direct updates to nested properties of a state.
+     * Implementation of the public 'lens' function.
+     */
+    static createLens = (source, accessor) => {
+        // Extract the property path once during lens creation
+        const extractPath = () => {
+            const path = [];
+            const proxy = new Proxy({}, {
+                get: (_, prop) => {
+                    if (typeof prop === 'string' || typeof prop === 'number') {
+                        path.push(prop);
+                    }
+                    return proxy;
+                },
+            });
+            try {
+                accessor(proxy);
+            }
+            catch {
+                // Ignore errors, we're just collecting the path
+            }
+            return path;
+        };
+        // Capture the path once
+        const path = extractPath();
+        // Create a state with the initial value from the source
+        const lensState = StateImpl.createState(accessor(source()));
+        // Prevent circular updates
+        let isUpdating = false;
+        // Set up an effect to sync from source to lens
+        StateImpl.createEffect(() => {
+            if (isUpdating) {
+                return;
+            }
+            isUpdating = true;
+            try {
+                lensState.set(accessor(source()));
+            }
+            finally {
+                isUpdating = false;
+            }
+        });
+        // Override the lens state's set method to update the source
+        const originalSet = lensState.set;
+        lensState.set = (value) => {
+            if (isUpdating) {
+                return;
+            }
+            isUpdating = true;
+            try {
+                // Update lens state
+                originalSet(value);
+                // Update source by modifying the value at path
+                source.update((current) => setValueAtPath(current, path, value));
+            }
+            finally {
+                isUpdating = false;
+            }
+        };
+        // Add update method for completeness
+        lensState.update = (fn) => {
+            lensState.set(fn(lensState()));
+        };
+        return lensState;
+    };
+    // Processes queued subscriber notifications in a controlled, non-reentrant way
+    static notifySubscribers = () => {
+        // Prevent reentrance to avoid cascading notification loops when
+        // effects trigger further state changes
+        if (StateImpl.isNotifying) {
+            return;
+        }
+        StateImpl.isNotifying = true;
+        try {
+            // Process all pending effects in batches for better perf,
+            // ensuring topological execution order is maintained
+            while (StateImpl.pendingSubscribers.size > 0) {
+                // Process in snapshot batches to prevent infinite loops
+                // when effects trigger further state changes
+                const subscribers = Array.from(StateImpl.pendingSubscribers);
+                StateImpl.pendingSubscribers.clear();
+                for (const effect of subscribers) {
+                    effect();
+                }
+            }
+        }
+        finally {
+            StateImpl.isNotifying = false;
+        }
+    };
+    // Removes effect from dependency tracking to prevent memory leaks
+    static cleanupEffect = (effect) => {
+        // Remove from execution queue to prevent stale updates
+        StateImpl.pendingSubscribers.delete(effect);
+        // Remove bidirectional dependency references to prevent memory leaks
+        const deps = StateImpl.subscriberDependencies.get(effect);
+        if (deps) {
+            for (const subscribers of deps) {
+                subscribers.delete(effect);
+            }
+            deps.clear();
+            StateImpl.subscriberDependencies.delete(effect);
+        }
+    };
+}
+// Helper for array updates
+const updateArrayItem = (arr, index, value) => {
+    const copy = [...arr];
+    copy[index] = value;
+    return copy;
+};
+// Helper for single-level updates (optimization)
+const updateShallowProperty = (obj, key, value) => {
+    const result = { ...obj };
+    result[key] = value;
+    return result;
+};
+// Helper to create the appropriate container type
+const createContainer = (key) => {
+    const isArrayKey = typeof key === 'number' || !Number.isNaN(Number(key));
+    return isArrayKey ? [] : {};
+};
+// Helper for handling array path updates
+const updateArrayPath = (array, pathSegments, value) => {
+    const index = Number(pathSegments[0]);
+    if (pathSegments.length === 1) {
+        // Simple array item update
+        return updateArrayItem(array, index, value);
+    }
+    // Nested path in array
+    const copy = [...array];
+    const nextPathSegments = pathSegments.slice(1);
+    const nextKey = nextPathSegments[0];
+    // For null/undefined values in arrays, create appropriate containers
+    let nextValue = array[index];
+    if (nextValue === undefined || nextValue === null) {
+        // Use empty object as default if nextKey is undefined
+        nextValue = nextKey !== undefined ? createContainer(nextKey) : {};
+    }
+    copy[index] = setValueAtPath(nextValue, nextPathSegments, value);
+    return copy;
+};
+// Helper for handling object path updates
+const updateObjectPath = (obj, pathSegments, value) => {
+    // Ensure we have a valid key
+    const currentKey = pathSegments[0];
+    if (currentKey === undefined) {
+        // This shouldn't happen given our checks in the main function
+        return obj;
+    }
+    if (pathSegments.length === 1) {
+        // Simple object property update
+        return updateShallowProperty(obj, currentKey, value);
+    }
+    // Nested path in object
+    const nextPathSegments = pathSegments.slice(1);
+    const nextKey = nextPathSegments[0];
+    // For null/undefined values, create appropriate containers
+    let currentValue = obj[currentKey];
+    if (currentValue === undefined || currentValue === null) {
+        // Use empty object as default if nextKey is undefined
+        currentValue = nextKey !== undefined ? createContainer(nextKey) : {};
+    }
+    // Create new object with updated property
+    const result = { ...obj };
+    result[currentKey] = setValueAtPath(currentValue, nextPathSegments, value);
+    return result;
+};
+// Simplified function to update a nested value at a path
+const setValueAtPath = (obj, pathSegments, value) => {
+    // Handle base cases
+    if (pathSegments.length === 0) {
+        return value;
+    }
+    if (obj === undefined || obj === null) {
+        return setValueAtPath({}, pathSegments, value);
+    }
+    const currentKey = pathSegments[0];
+    if (currentKey === undefined) {
+        return obj;
+    }
+    // Delegate to specialized handlers based on data type
+    if (Array.isArray(obj)) {
+        return updateArrayPath(obj, pathSegments, value);
+    }
+    return updateObjectPath(obj, pathSegments, value);
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "@nerdalytics/beacon",
-	"version": "1000.1.0",
+	"version": "1000.1.1",
 	"description": "A lightweight reactive state library for Node.js backends. Enables reactive state management with automatic dependency tracking and efficient updates for server-side applications.",
 	"type": "module",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
+	"main": "dist/src/index.js",
+	"types": "dist/src/index.d.ts",
 	"files": [
-		"dist/index.js",
-		"dist/index.d.ts",
+		"dist/src/index.js",
+		"dist/src/index.d.ts",
 		"src/index.ts",
 		"LICENSE"
 	],