@nerdalytics/beacon 1000.0.0 → 1000.1.1

package/README.md

@@ -13,6 +13,7 @@ A lightweight reactive state library for Node.js backends. Enables reactive stat
   - [effect](#effectfn---void---void)
   - [batch](#batchtfn---t-t)
   - [select](#selectt-rsource-readonlystatet-selectorfn-state-t--r-equalityfn-a-r-b-r--boolean-readonlystater)
+  - [lens](#lenst-ksource-statet-accessor-state-t--k-statek)
   - [readonlyState](#readonlystatetstate-statet-readonlystatet)
   - [protectedState](#protectedstatetinitialvalue-t-readonlystatet-writeablestatet)
 - [Development](#development)
@@ -94,6 +95,29 @@ user.update(u => ({ ...u, name: "Bob" }));
 // Updates to other properties won't trigger the effect
 user.update(u => ({ ...u, age: 31 })); // No effect triggered
 
+// Using lens for two-way binding with nested properties
+const nested = state({
+  user: {
+    profile: {
+      settings: {
+        theme: "dark",
+        notifications: true
+      }
+    }
+  }
+});
+
+// Create a lens focused on a deeply nested property
+const themeLens = lens(nested, n => n.user.profile.settings.theme);
+
+// Read the focused value
+console.log(themeLens()); // => "dark"
+
+// Update the focused value directly (maintains referential integrity)
+themeLens.set("light");
+console.log(themeLens()); // => "light"
+console.log(nested().user.profile.settings.theme); // => "light"
+
 // Unsubscribe the effect to stop it from running on future updates
 // and clean up all its internal subscriptions
 unsubscribe();
@@ -148,6 +172,10 @@ Batches multiple updates to only trigger effects once at the end.
 
 Creates an efficient subscription to a subset of a state value. The selector will only notify its subscribers when the selected value actually changes according to the provided equality function (defaults to `Object.is`).
 
+### `lens<T, K>(source: State<T>, accessor: (state: T) => K): State<K>`
+
+Creates a lens for direct updates to nested properties of a state. A lens combines the functionality of `select` (for reading) with the ability to update the nested property while maintaining referential integrity throughout the object tree.
+
 ### `readonlyState<T>(state: State<T>): ReadOnlyState<T>`
 
 Creates a read-only view of a state, hiding mutation methods. Useful when you want to expose a state to other parts of your application without allowing direct mutations.
@@ -175,6 +203,7 @@ npm run test:unit:effect
 npm run test:unit:derive
 npm run test:unit:batch
 npm run test:unit:select
+npm run test:unit:lens
 npm run test:unit:readonly
 npm run test:unit:protected
 

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,28 +1,27 @@
 {
 	"name": "@nerdalytics/beacon",
-	"version": "1000.0.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",
-		"src/",
+		"dist/src/index.js",
+		"dist/src/index.d.ts",
+		"src/index.ts",
 		"LICENSE"
 	],
 	"repository": {
-		"url": "github:nerdalytics/beacon",
+		"url": "git+https://github.com/nerdalytics/beacon.git",
 		"type": "git"
 	},
 	"scripts": {
 		"lint": "npx @biomejs/biome lint --config-path=./biome.json",
 		"lint:fix": "npx @biomejs/biome lint --fix --config-path=./biome.json",
 		"lint:fix:unsafe": "npx @biomejs/biome lint --fix --unsafe --config-path=./biome.json",
-		"format": "npx @biomejs/biome format src --write --config-path=./biome.json",
-		"check": "npx @biomejs/biome check src --config-path=./biome.json",
-		"check:fix": "npx @biomejs/biome format src --fix --config-path=./biome.json",
-
+		"format": "npx @biomejs/biome format --write --config-path=./biome.json",
+		"check": "npx @biomejs/biome check --config-path=./biome.json",
+		"check:fix": "npx @biomejs/biome format --fix --config-path=./biome.json",
 		"test": "node --test --test-skip-pattern=\"COMPONENT NAME\" tests/**/*.ts",
 		"test:coverage": "node --test --experimental-config-file=node.config.json --test-skip-pattern=\"[COMPONENT NAME]\" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info tests/**/*.ts",
 		"test:unit:state": "node --test tests/state.test.ts",
@@ -30,21 +29,19 @@
 		"test:unit:batch": "node --test tests/batch.test.ts",
 		"test:unit:derive": "node --test tests/derive.test.ts",
 		"test:unit:select": "node --test tests/select.test.ts",
+		"test:unit:lens": "node --test tests/lens.test.ts",
 		"test:unit:cleanup": "node --test tests/cleanup.test.ts",
 		"test:unit:cyclic-dependency": "node --test tests/cyclic-dependency.test.ts",
 		"test:unit:deep-chain": "node --test tests/deep-chain.test.ts",
 		"test:unit:infinite-loop": "node --test tests/infinite-loop.test.ts",
-
 		"benchmark": "node scripts/benchmark.ts",
-
 		"build": "npm run build:lts",
 		"prebuild:lts": "rm -rf dist/",
 		"build:lts": "tsc -p tsconfig.lts.json",
 		"prepublishOnly": "npm run build:lts",
-
-		"pretest:lts": "npm run build:lts",
-		"test:lts": "node scripts/run-lts-tests.js",
-
+		"pretest:lts": "node scripts/run-lts-tests.js",
+		"test:lts:20": "node --test dist/tests/**.js",
+		"test:lts:22": "node --test --test-skip-pattern=\"COMPONENT NAME\" dist/tests/**/*.js",
 		"update-performance-docs": "node --experimental-config-file=node.config.json scripts/update-performance-docs.ts"
 	},
 	"keywords": [

package/src/index.ts

@@ -66,6 +66,12 @@ export const protectedState = <T>(initialValue: T): [ReadOnlyState<T>, Writeable
 	]
 }
 
+/**
+ * Creates a lens for direct updates to nested properties of a state.
+ */
+export const lens = <T, K>(source: State<T>, accessor: (state: T) => K): State<K> =>
+	StateImpl.createLens(source, accessor)
+
 class StateImpl<T> {
 	// Static fields track global reactivity state - this centralized approach allows
 	// for coordinated updates while maintaining individual state isolation
@@ -92,8 +98,10 @@ class StateImpl<T> {
 		this.value = initialValue
 	}
 
-	// Creates a callable function that both reads and writes state -
-	// this design maintains JavaScript idioms while adding reactivity
+	/**
+	 * Creates a reactive state container with the provided initial value.
+	 * Implementation of the public 'state' function.
+	 */
 	static createState = <T>(initialValue: T): State<T> => {
 		const instance = new StateImpl<T>(initialValue)
 		const get = (): T => instance.get()
@@ -172,7 +180,10 @@ class StateImpl<T> {
 		this.set(fn(this.value))
 	}
 
-	// Creates an effect that automatically tracks and responds to state changes
+	/**
+	 * Registers a function to run whenever its reactive dependencies change.
+	 * Implementation of the public 'effect' function.
+	 */
 	static createEffect = (fn: () => void): Unsubscribe => {
 		const runEffect = (): void => {
 			// Prevent re-entrance to avoid cascade updates during effect execution
@@ -265,7 +276,10 @@ class StateImpl<T> {
 		}
 	}
 
-	// Batches state updates to improve performance by reducing redundant effect runs
+	/**
+	 * Groups multiple state updates to trigger effects only once at the end.
+	 * Implementation of the public 'batch' function.
+	 */
 	static executeBatch = <T>(fn: () => T): T => {
 		// Increment depth counter to handle nested batches correctly
 		StateImpl.batchDepth++
@@ -302,7 +316,10 @@ class StateImpl<T> {
 		}
 	}
 
-	// Creates a derived state that memoizes computations and updates only when dependencies change
+	/**
+	 * Creates a read-only computed value that updates when its dependencies change.
+	 * Implementation of the public 'derive' function.
+	 */
 	static createDerive = <T>(computeFn: () => T): ReadOnlyState<T> => {
 		const valueState = StateImpl.createState<T | undefined>(undefined)
 		let initialized = false
@@ -334,7 +351,10 @@ class StateImpl<T> {
 		}
 	}
 
-	// Creates a selector that monitors a slice of state with performance optimizations
+	/**
+	 * Creates an efficient subscription to a subset of a state value.
+	 * Implementation of the public 'select' function.
+	 */
 	static createSelect = <T, R>(
 		source: ReadOnlyState<T>,
 		selectorFn: (state: T) => R,
@@ -381,6 +401,85 @@ class StateImpl<T> {
 		}
 	}
 
+	/**
+	 * Creates a lens for direct updates to nested properties of a state.
+	 * Implementation of the public 'lens' function.
+	 */
+	static createLens = <T, K>(source: State<T>, accessor: (state: T) => K): State<K> => {
+		// Extract the property path once during lens creation
+		const extractPath = (): (string | number)[] => {
+			const path: (string | number)[] = []
+			const proxy = new Proxy(
+				{},
+				{
+					get: (_: object, prop: string | symbol): unknown => {
+						if (typeof prop === 'string' || typeof prop === 'number') {
+							path.push(prop)
+						}
+						return proxy
+					},
+				}
+			)
+
+			try {
+				accessor(proxy as unknown as T)
+			} 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<K>(accessor(source()))
+
+		// Prevent circular updates
+		let isUpdating = false
+
+		// Set up an effect to sync from source to lens
+		StateImpl.createEffect((): void => {
+			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: K): void => {
+			if (isUpdating) {
+				return
+			}
+
+			isUpdating = true
+			try {
+				// Update lens state
+				originalSet(value)
+
+				// Update source by modifying the value at path
+				source.update((current: T): T => setValueAtPath(current, path, value))
+			} finally {
+				isUpdating = false
+			}
+		}
+
+		// Add update method for completeness
+		lensState.update = (fn: (value: K) => K): void => {
+			lensState.set(fn(lensState()))
+		}
+
+		return lensState
+	}
+
 	// Processes queued subscriber notifications in a controlled, non-reentrant way
 	private static notifySubscribers = (): void => {
 		// Prevent reentrance to avoid cascading notification loops when
@@ -425,3 +524,110 @@ class StateImpl<T> {
 		}
 	}
 }
+// Helper for array updates
+const updateArrayItem = <V>(arr: unknown[], index: number, value: V): unknown[] => {
+	const copy = [...arr]
+	copy[index] = value
+	return copy
+}
+
+// Helper for single-level updates (optimization)
+const updateShallowProperty = <V>(
+	obj: Record<string | number, unknown>,
+	key: string | number,
+	value: V
+): Record<string | number, unknown> => {
+	const result = { ...obj }
+	result[key] = value
+	return result
+}
+
+// Helper to create the appropriate container type
+const createContainer = (key: string | number): Record<string | number, unknown> | unknown[] => {
+	const isArrayKey = typeof key === 'number' || !Number.isNaN(Number(key))
+	return isArrayKey ? [] : {}
+}
+
+// Helper for handling array path updates
+const updateArrayPath = <V>(array: unknown[], pathSegments: (string | number)[], value: V): unknown[] => {
+	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 = <V>(
+	obj: Record<string | number, unknown>,
+	pathSegments: (string | number)[],
+	value: V
+): Record<string | number, unknown> => {
+	// 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 = <V, O>(obj: O, pathSegments: (string | number)[], value: V): O => {
+	// Handle base cases
+	if (pathSegments.length === 0) {
+		return value as unknown as O
+	}
+
+	if (obj === undefined || obj === null) {
+		return setValueAtPath({} as O, 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) as unknown as O
+	}
+
+	return updateObjectPath(obj as Record<string | number, unknown>, pathSegments, value) as unknown as O
+}