@nerdalytics/beacon 1000.1.1 → 1000.2.1

package/README.md

@@ -1,28 +1,50 @@
 # Beacon <img align="right" src="https://raw.githubusercontent.com/nerdalytics/beacon/refs/heads/trunk/assets/beacon-logo.svg" width="128px" alt="A stylized lighthouse beacon with golden light against a dark blue background, representing the reactive state library"/>
 
+> Lightweight reactive state management for Node.js backends
+
+[![license:mit](https://flat.badgen.net/static/license/MIT/blue)](https://github.com/nerdalytics/beacon/blob/trunk/LICENSE)
+[![registry:npm:version](https://img.shields.io/npm/v/@nerdalytics/beacon.svg)](https://www.npmjs.com/package/@nerdalytics/beacon)
+
+[![tech:nodejs](https://img.shields.io/badge/Node%20js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![language:typescript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://typescriptlang.org/)
+[![linter:biome](https://img.shields.io/badge/biome-60a5fa?style=for-the-badge&logo=biome&logoColor=white)](https://biomejs.dev/)
+
 A lightweight reactive state library for Node.js backends. Enables reactive state management with automatic dependency tracking and efficient updates for server-side applications.
 
-## Table of Contents
+<details>
+<summary><Strong>Table of Contents</Strong></summary>
 
 - [Features](#features)
-- [Installation](#installation)
-- [Usage](#usage)
-- [API](#api)
-  - [state](#statetinitialvalue-t-statet)
-  - [derive](#derivetfn---t-readonlystatet)
-  - [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)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [API Reference](#api-reference)
+   - [Core Primitives](#core-primitives)
+      - [state](#statetinitialvalue-t-equalityfn-a-t-b-t--boolean-statet)
+      - [derive](#derivetfn---t-readonlystatet)
+      - [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)
+   - [Access Control](#access-control)
+      - [readonlyState](#readonlystatetstate-statet-readonlystatet)
+      - [protectedState](#protectedstatetinitialvalue-t-equalityfn-a-t-b-t--boolean-readonlystatet-writeablestatet)
+- [Advanced Features](#advanced-features)
+   - [Infinite Loop Protection](#infinite-loop-protection)
+   - [Automatic Cleanup](#automatic-cleanup)
+   - [Custom Equality Functions](#custom-equality-functions)
+- [Design Philosophy](#design-philosophy)
+- [Architecture](#architecture)
 - [Development](#development)
-  - [Node.js LTS Compatibility](#nodejs-lts-compatibility)
-- [Key Differences vs TC39 Proposal](#key-differences-between-my-library-and-the-tc39-proposal)
-- [Implementation Details](#implementation-details)
+- [Key Differences vs TC39 Proposal](#key-differences-vs-tc39-proposal)
 - [FAQ](#faq)
+   - [Why "Beacon" Instead of "Signal"?](#why-beacon-instead-of-signal)
+   - [How does Beacon handle memory management?](#how-does-beacon-handle-memory-management)
+   - [Can I use Beacon with Express or other frameworks?](#can-i-use-beacon-with-express-or-other-frameworks)
+   - [Can Beacon be used in browser applications?](#can-beacon-be-used-in-browser-applications)
 - [License](#license)
 
+</details>
+
 ## Features
 
 - 📶 **Reactive state** - Create reactive values that automatically track dependencies
@@ -35,67 +57,209 @@ A lightweight reactive state library for Node.js backends. Enables reactive stat
 - ♻️ **Cycle handling** - Safely manages cyclic dependencies without crashing
 - 🚨 **Infinite loop detection** - Automatically detects and prevents infinite update loops
 - 🛠️ **TypeScript-first** - Full TypeScript support with generics
-- 🪶 **Lightweight** - Zero dependencies, < 200 LOC
+- 🪶 **Lightweight** - Zero dependencies
 - ✅ **Node.js compatibility** - Works with Node.js LTS v20+ and v22+
 
-## Installation
+## Quick Start
 
-```sh
-npm install @nerdalytics/beacon
+```other
+npm install @nerdalytics/beacon --save-exact
 ```
 
-## Usage
-
 ```typescript
-import { state, derive, effect, batch, select, readonlyState, protectedState } from "@nerdalytics/beacon";
+import { state, derive, effect } from '@nerdalytics/beacon';
 
 // Create reactive state
 const count = state(0);
-const doubled = derive(() => count() * 2);
 
-// Read values
-console.log(count()); // => 0
-console.log(doubled()); // => 0
+// Create a derived value
+const doubled = derive(() => count() * 2);
 
-// Setup an effect that automatically runs when dependencies change
-// effect() returns a cleanup function that removes all subscriptions when called
-const unsubscribe = effect(() => {
-  console.log(`Count is ${count()}, doubled is ${doubled()}`);
+// Set up an effect
+effect(() => {
+  console.log(`Count: ${count()}, Doubled: ${doubled()}`);
 });
-// => "Count is 0, doubled is 0" (effect runs immediately when created)
+// => "Count: 0, Doubled: 0"
 
-// Update values - effect automatically runs after each change
+// Update the state - effect runs automatically
 count.set(5);
-// => "Count is 5, doubled is 10"
+// => "Count: 5, Doubled: 10"
+```
+
+## Core Concepts
+
+Beacon is built around three core primitives:
+
+1. **States**: Mutable, reactive values
+2. **Derived States**: Read-only computed values that update automatically
+3. **Effects**: Side effects that run automatically when dependencies change
+
+The library handles all the dependency tracking and updates automatically, so you can focus on your business logic.
+
+## API Reference
+
+### Version Compatibility
+
+The table below tracks when features were introduced and when function signatures were changed.
+
+| API | Introduced | Last Updated | Notes |
+|-----|------------|--------------|-------|
+| `state` | v1.0.0 | v1000.2.0 | Added `equalityFn` parameter |
+| `derive` | v1.0.0 | v1000.0.0 | Renamed `derived` → `derive` |
+| `effect` | v1.0.0 | - | - |
+| `batch` | v1.0.0 | - | - |
+| `select` | v1000.0.0 | - | - |
+| `lens` | v1000.1.0 | - | - |
+| `readonlyState` | v1000.0.0 | - | - |
+| `protectedState` | v1000.0.0 | v1000.2.0 | Added `equalityFn` parameter |
+
+### Core Primitives
+
+#### `state<T>(initialValue: T, equalityFn?: (a: T, b: T) => boolean): State<T>`
+> *Since v1.0.0*
+
+The foundation of Beacon's reactivity system. Create with `state()` and use like a function.
+
+```typescript
+import { state } from '@nerdalytics/beacon';
+
+const counter = state(0);
+
+// Read current value
+console.log(counter()); // => 0
+
+// Update value
+counter.set(5);
+console.log(counter()); // => 5
 
 // Update with a function
-count.update((n) => n + 1);
-// => "Count is 6, doubled is 12"
+counter.update(n => n + 1);
+console.log(counter()); // => 6
+
+// With custom equality function
+const deepCounter = state({ value: 0 }, (a, b) => {
+  // Deep equality check
+  return a.value === b.value;
+});
+
+// This won't trigger effects because values are deeply equal
+deepCounter.set({ value: 0 });
+```
+
+#### `derive<T>(fn: () => T): ReadOnlyState<T>`
+> *Since v1.0.0*
+
+Calculate values based on other states. Updates automatically when dependencies change.
+
+```typescript
+import { state, derive } from '@nerdalytics/beacon';
+
+const firstName = state('John');
+const lastName = state('Doe');
+
+const fullName = derive(() => `${firstName()} ${lastName()}`);
+
+console.log(fullName()); // => "John Doe"
+
+firstName.set('Jane');
+console.log(fullName()); // => "Jane Doe"
+```
+
+#### `effect(fn: () => void): () => void`
+> *Since v1.0.0*
+
+Run side effects when reactive values change.
+
+```typescript
+import { state, effect } from '@nerdalytics/beacon';
+
+const user = state({ name: 'Alice', loggedIn: false });
+
+const cleanup = effect(() => {
+  console.log(`User ${user().name} is ${user().loggedIn ? 'online' : 'offline'}`);
+});
+// => "User Alice is offline" (effect runs immediately when created)
+
+user.update(u => ({ ...u, loggedIn: true }));
+// => "User Alice is online"
+
+// Stop the effect and clean up all subscriptions
+cleanup();
+```
+
+#### `batch<T>(fn: () => T): T`
+> *Since v1.0.0*
+
+Group multiple updates to trigger effects only once.
+
+```typescript
+import { state, effect, batch } from "@nerdalytics/beacon";
+
+const count = state(0);
+
+effect(() => {
+  console.log(`Count is ${count()}`);
+});
+// => "Count is 0" (effect runs immediately)
+
+// Without batching, effects run after each update
+count.set(1);
+// => "Count is 1"
+count.set(2);
+// => "Count is 2"
 
 // Batch updates (only triggers effects once at the end)
 batch(() => {
   count.set(10);
   count.set(20);
+  count.set(30);
 });
-// => "Count is 20, doubled is 40" (only once)
+// => "Count is 30" (only once)
+```
+
+#### `select<T, R>(source: ReadOnlyState<T>, selectorFn: (state: T) => R, equalityFn?: (a: R, b: R) => boolean): ReadOnlyState<R>`
+> *Since v1000.0.0*
 
-// Using select to subscribe to specific parts of state
-const user = state({ name: "Alice", age: 30, email: "alice@example.com" });
-const nameSelector = select(user, u => u.name);
+Subscribe to specific parts of a state object.
+
+```typescript
+import { state, select, effect } from '@nerdalytics/beacon';
+
+const user = state({
+  profile: { name: 'Alice' },
+  preferences: { theme: 'dark' }
+});
+
+// Only triggers when name changes
+const nameState = select(user, u => u.profile.name);
 
 effect(() => {
-  console.log(`Name changed: ${nameSelector()}`);
+  console.log(`Name: ${nameState()}`);
 });
-// => "Name changed: Alice"
+// => "Name: Alice"
+
+// This triggers the effect
+user.update(u => ({
+  ...u,
+  profile: { ...u.profile, name: 'Bob' }
+}));
+// => "Name: Bob"
+
+// This doesn't trigger the effect (theme changed, not name)
+user.update(u => ({
+  ...u,
+  preferences: { ...u.preferences, theme: 'light' }
+}));
+```
 
-// Updates to the selected property will trigger the effect
-user.update(u => ({ ...u, name: "Bob" }));
-// => "Name changed: Bob"
+#### `lens<T, K>(source: State<T>, accessor: (state: T) => K): State<K>`
+> *Since v1000.1.0*
 
-// Updates to other properties won't trigger the effect
-user.update(u => ({ ...u, age: 31 })); // No effect triggered
+Two-way binding to deeply nested properties.
+
+```typescript
+import { state, lens, effect } from "@nerdalytics/beacon";
 
-// Using lens for two-way binding with nested properties
 const nested = state({
   user: {
     profile: {
@@ -118,165 +282,255 @@ 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();
+// The entire object is updated with proper referential integrity
+// This makes it easy to detect changes throughout the object tree
+```
+
+### Access Control
+
+Control who can read vs. write to your state.
+
+#### `readonlyState<T>(state: State<T>): ReadOnlyState<T>`
+> *Since v1000.0.0*
+
+Creates a read-only view of a state, hiding mutation methods. Useful when you want to expose state to other parts of your application without allowing direct mutations.
+
+```typescript
+import { state, readonlyState } from "@nerdalytics/beacon";
 
-// Using readonlyState to create a read-only view
 const counter = state(0);
 const readonlyCounter = readonlyState(counter);
-// readonlyCounter() works, but readonlyCounter.set() is not available
 
-// Using protectedState to separate read and write capabilities
+// Reading works
+console.log(readonlyCounter()); // => 0
+
+// Updating the original state reflects in the readonly view
+counter.set(5);
+console.log(readonlyCounter()); // => 5
+
+// This would cause a TypeScript error since readonlyCounter has no set method
+// readonlyCounter.set(10); // Error: Property 'set' does not exist
+```
+
+#### `protectedState<T>(initialValue: T, equalityFn?: (a: T, b: T) => boolean): [ReadOnlyState<T>, WriteableState<T>]`
+> *Since v1000.0.0*
+
+Creates a state with separated read and write capabilities, returning a tuple of reader and writer. This pattern allows you to expose only the reading capability to consuming code while keeping the writing capability private.
+
+```typescript
+import { protectedState } from "@nerdalytics/beacon";
+
+// Create a state with separated read and write capabilities
 const [getUser, setUser] = protectedState({ name: 'Alice' });
-// getUser() works to read the state
-// setUser.set() and setUser.update() work to modify the state
-// but getUser has no mutation methods
-
-// Infinite loop detection example (would throw an error)
-try {
-  effect(() => {
-    const value = counter();
-    // The following would throw an error because it attempts to
-    // update a state that the effect depends on:
-    // "Infinite loop detected: effect() cannot update a state() it depends on!"
-    // counter.set(value + 1);
-
-    // Instead, use a safe pattern with proper dependencies:
-    console.log(`Current counter value: ${value}`);
-  });
-} catch (error) {
-  console.error('Prevented infinite loop:', error.message);
+
+// Read the state
+console.log(getUser()); // => { name: 'Alice' }
+
+// Update the state
+setUser.set({ name: 'Bob' });
+console.log(getUser()); // => { name: 'Bob' }
+
+// This is useful for exposing only read access to outside consumers
+function createProtectedCounter() {
+  const [getCount, setCount] = protectedState(0);
+
+  return {
+    value: getCount,
+    increment: () => setCount.update(n => n + 1),
+    decrement: () => setCount.update(n => n - 1)
+  };
 }
+
+const counter = createProtectedCounter();
+console.log(counter.value()); // => 0
+counter.increment();
+console.log(counter.value()); // => 1
 ```
 
-## API
+## Advanced Features
 
-### `state<T>(initialValue: T): State<T>`
+Beacon includes several advanced capabilities that help you build robust applications.
 
-Creates a new reactive state container with the provided initial value.
+### Infinite Loop Protection
 
-### `derive<T>(fn: () => T): ReadOnlyState<T>`
+Beacon prevents common mistakes that could cause infinite loops:
 
-Creates a read-only computed value that updates when its dependencies change.
+```typescript
+import { state, effect } from '@nerdalytics/beacon';
 
-### `effect(fn: () => void): () => void`
+const counter = state(0);
 
-Creates an effect that runs the given function immediately and whenever its dependencies change. Returns an unsubscribe function that stops the effect and cleans up all subscriptions when called.
+// This would throw an error
+effect(() => {
+  const value = counter();
+  counter.set(value + 1); // Error: Infinite loop detected!
+});
 
-### `batch<T>(fn: () => T): T`
+// Instead, use proper patterns like:
+const increment = () => counter.update(n => n + 1);
+```
 
-Batches multiple updates to only trigger effects once at the end.
+### Automatic Cleanup
 
-### `select<T, R>(source: ReadOnlyState<T>, selectorFn: (state: T) => R, equalityFn?: (a: R, b: R) => boolean): ReadOnlyState<R>`
+All subscriptions are automatically cleaned up when effects are unsubscribed:
 
-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`).
+```typescript
+import { state, effect } from '@nerdalytics/beacon';
+
+const data = state({ loading: true, items: [] });
+
+// Effect with nested effect
+const cleanup = effect(() => {
+  if (data().loading) {
+    console.log('Loading...');
+  } else {
+    // This nested effect is automatically cleaned up when the parent is
+    effect(() => {
+      console.log(`${data().items.length} items loaded`);
+    });
+  }
+});
 
-### `lens<T, K>(source: State<T>, accessor: (state: T) => K): State<K>`
+// Unsubscribe cleans up everything, including nested effects
+cleanup();
+```
 
-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.
+### Custom Equality Functions
 
-### `readonlyState<T>(state: State<T>): ReadOnlyState<T>`
+Control when subscribers are notified with custom equality checks. You can provide custom equality functions to `state`, `select`, and `protectedState`:
 
-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.
+```typescript
+import { state, select, effect, protectedState } from '@nerdalytics/beacon';
 
-### `protectedState<T>(initialValue: T): [ReadOnlyState<T>, WriteableState<T>]`
+// Custom equality function for state
+// Only trigger updates when references are different (useful for logging)
+const logMessages = state([], (a, b) => a === b); // Reference equality
 
-Creates a state with access control, returning a tuple of reader and writer. This pattern separates read and write capabilities, allowing you to expose only the reading capability to consuming code while keeping the writing capability private.
+// Add logs - each call triggers effects even with identical content
+logMessages.set(['System started']); // Triggers effects
+logMessages.set(['System started']); // Triggers effects again
 
-## Development
+// Protected state with custom equality function
+const [getConfig, setConfig] = protectedState({ theme: 'dark' }, (a, b) => {
+  // Only consider configs equal if all properties match
+  return a.theme === b.theme;
+});
 
-```sh
-# Install dependencies
-npm install
+// Custom equality with select
+const list = state([1, 2, 3]);
 
-# Run all tests
-npm test
+// Only notify when array length changes, not on content changes
+const listLengthState = select(
+  list,
+  arr => arr.length,
+  (a, b) => a === b
+);
 
-# Run all tests with coverage
-npm run test:coverage
-
-# Run specific test suites
-# Core functionality
-npm run test:unit:state
-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
-
-# Advanced patterns
-npm run test:unit:cleanup              # Tests for effect cleanup behavior
-npm run test:unit:cyclic-dependency    # Tests for cyclic dependency handling
-npm run test:unit:deep-chain           # Tests for deep chain handling
-npm run test:unit:infinite-loop        # Tests for infinite loop detection
-
-# Benchmarking
-npm run benchmark    # Tests for infinite loop detection
-
-# Format code
-npm run format
-npm run lint
-npm run check    # Runs Bioms lint + format
+effect(() => {
+  console.log(`List has ${listLengthState()} items`);
+});
 ```
 
-### Node.js LTS Compatibility
+## Design Philosophy
+
+Beacon follows these key principles:
+
+1. **Simplicity**: Minimal API surface with powerful primitives
+2. **Fine-grained reactivity**: Track dependencies at exactly the right level
+3. **Predictability**: State changes flow predictably through the system
+4. **Performance**: Optimize for server workloads and memory efficiency
+5. **Type safety**: Full TypeScript support with generics
+
+## Architecture
+
+Beacon is built around a centralized reactivity system with fine-grained dependency tracking. Here's how it works:
+
+- **Automatic Dependency Collection**: When a state is read inside an effect, Beacon automatically records this dependency
+- **WeakMap-based Tracking**: Uses WeakMaps for automatic garbage collection
+- **Topological Updates**: Updates flow through the dependency graph in the correct order
+- **Memory-Efficient**: Designed for long-running Node.js processes
+
+### Dependency Tracking
+
+When a state is read inside an effect, Beacon automatically records this dependency relationship and sets up a subscription.
+
+### Infinite Loop Prevention
 
-Beacon supports the two most recent Node.js LTS versions (currently v20 and v22). When the package is published to npm, it includes transpiled code compatible with these LTS versions.
+Beacon actively detects when an effect tries to update a state it depends on, preventing common infinite update cycles:
 
-## Key Differences Between My Library and the [TC39 Proposal][1]
+```typescript
+// This would throw: "Infinite loop detected"
+effect(() => {
+  const value = counter();
+  counter.set(value + 1); // Error! Updating a state the effect depends on
+});
+```
 
-| Aspect | @nerdalytics/beacon | TC39 Proposal |
-|--------|---------------------|---------------|
-| **API Style** | Functional approach (`state()`, `derive()`) | Class-based design (`Signal.State`, `Signal.Computed`) |
-| **Reading/Writing Pattern** | Function call for reading (`count()`), methods for writing (`count.set(5)`) | Method-based access (`get()`/`set()`) |
-| **Framework Support** | High-level abstractions like `effect()` and `batch()` | Lower-level primitives (`Signal.subtle.Watcher`) that frameworks build upon |
-| **Advanced Features** | Focused on core reactivity | Includes introspection capabilities, watched/unwatched callbacks, and Signal.subtle namespace |
-| **Scope and Purpose** | Practical Node.js use cases with minimal API surface | Standardization with robust interoperability between frameworks |
+### Cyclic Dependencies
 
-## Implementation Details
+Beacon employs two complementary strategies for handling cyclical updates:
 
-Beacon is designed with a focus on simplicity, performance, and robust handling of complex dependency scenarios.
+1. **Active Detection**: The system tracks which states an effect reads from and writes to. If an effect attempts to directly update a state it depends on, Beacon throws a clear error.
+2. **Safe Cycles**: For indirect cycles and safe update patterns, Beacon uses a queue-based update system that won't crash even with cyclical dependencies. When states form a cycle where values eventually stabilize, the system handles these updates efficiently without stack overflows.
 
-### Key Implementation Concepts
+## Development
 
-- **Fine-grained reactivity**: Dependencies are tracked automatically at the state level
-- **Efficient updates**: Changes only propagate to affected parts of the dependency graph
-- **Cyclical dependency handling**: Robust handling of circular references without crashing
-- **Infinite loop detection**: Safeguards against direct self-mutation within effects
-- **Memory management**: Automatic cleanup of subscriptions when effects are disposed
-- **Optimized batching**: Smart scheduling of updates to minimize redundant computations
+```other
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+```
+
+## Key Differences vs [TC39 Proposal][1]
+
+| **Aspect**                  | **@nerdalytics/beacon**                                                     | **TC39 Proposal**                                                                             |
+| --------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| **API Style**               | Functional approach (`state()`, `derive()`)                                 | Class-based design (`Signal.State`, `Signal.Computed`)                                        |
+| **Reading/Writing Pattern** | Function call for reading (`count()`), methods for writing (`count.set(5)`) | Method-based access (`get()`/`set()`)                                                         |
+| **Framework Support**       | High-level abstractions like `effect()` and `batch()`                       | Lower-level primitives (`Signal.subtle.Watcher`) that frameworks build upon                   |
+| **Advanced Features**       | Focused on core reactivity                                                  | Includes introspection capabilities, watched/unwatched callbacks, and Signal.subtle namespace |
+| **Scope and Purpose**       | Practical Node.js use cases with minimal API surface                        | Standardization with robust interoperability between frameworks                               |
 
 ## FAQ
 
-<details>
+#### Why "Beacon" Instead of "Signal"?
 
-<summary>Why "Beacon" Instead of "Signal"?</summary>
-I chose "Beacon" because it clearly represents how the library broadcasts notifications when state changes—just like a lighthouse guides ships. While my library draws inspiration from Preact Signals, Angular Signals, and aspects of Svelte, I wanted to create something lighter and specifically designed for Node.js backends. Using "Beacon" instead of the term "Signal" helps avoid confusion with the TC39 proposal and similar libraries while still accurately describing the core functionality.
+Beacon represents how the library broadcasts notifications when state changes—just like a lighthouse guides ships. The name avoids confusion with the TC39 proposal and similar libraries while accurately describing the core functionality.
 
-</details>
+#### How does Beacon handle memory management?
 
-<details>
+Beacon uses WeakMaps for dependency tracking, ensuring that unused states and effects can be garbage collected. When you unsubscribe an effect, all its internal subscriptions are automatically cleaned up.
 
-<summary>How does Beacon handle infinite update cycles?</summary>
-Beacon employs two complementary strategies for handling cyclical updates:
+#### Can I use Beacon with Express or other frameworks?
 
-1. **Infinite Loop Detection**: Beacon actively detects direct infinite loops in effects by tracking which states an effect reads and writes to. If an effect attempts to update a state it depends on (directly modifying its own dependency), Beacon throws an error with a clear message: "Infinite loop detected: effect() cannot update a state() it depends on!"
+Yes! Beacon works well as a state management solution in any Node.js application:
 
-2. **Safe Cyclic Dependencies**: For indirect cycles and safe update patterns, Beacon uses a queue-based update system that won't crash even with cyclical dependencies. When states form a cycle where values eventually stabilize, the system handles these updates efficiently without stack overflows.
+```typescript
+import express from 'express';
+import { state, effect } from '@nerdalytics/beacon';
 
-This dual approach prevents accidental infinite loops while still supporting legitimate cyclic update patterns that eventually stabilize.
+const app = express();
+const stats = state({ requests: 0, errors: 0 });
 
-</details>
+// Update stats on each request
+app.use((req, res, next) => {
+  stats.update(s => ({ ...s, requests: s.requests + 1 }));
+  next();
+});
 
-<details>
+// Log stats every minute
+effect(() => {
+  console.log(`Stats: ${stats().requests} requests, ${stats().errors} errors`);
+});
+
+app.listen(3000);
+```
 
-<summary>How performant is Beacon?</summary>
-Beacon is designed with performance in mind for server-side Node.js environments. It achieves millions of operations per second for core operations like reading and writing states.
+#### Can Beacon be used in browser applications?
 
-</details>
+While Beacon is optimized for Node.js server-side applications, its core principles would work in browser environments. However, the library is specifically designed for backend use cases and hasn't been optimized for browser bundle sizes or DOM integration patterns.
 
 ## License
 

package/dist/src/index.d.ts

@@ -8,36 +8,12 @@ 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 state: <T>(initialValue: T, equalityFn?: (a: T, b: T) => boolean) => State<T>;
 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 protectedState: <T>(initialValue: T, equalityFn?: (a: T, b: T) => boolean) => [ReadOnlyState<T>, WriteableState<T>];
 export declare const lens: <T, K>(source: State<T>, accessor: (state: T) => K) => State<K>;
 export {};

package/dist/src/index.js

@@ -1,34 +1,12 @@
-// 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 state = (initialValue, equalityFn = Object.is) => StateImpl.createState(initialValue, equalityFn);
 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);
+export const protectedState = (initialValue, equalityFn = Object.is) => {
+    const fullState = state(initialValue, equalityFn);
     return [
         () => readonlyState(fullState)(),
         {
@@ -37,61 +15,44 @@ export const protectedState = (initialValue) => {
         },
     ];
 };
-/**
- * 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) {
+    equalityFn;
+    constructor(initialValue, equalityFn = Object.is) {
         this.value = initialValue;
+        this.equalityFn = equalityFn;
     }
-    /**
-     * Creates a reactive state container with the provided initial value.
-     * Implementation of the public 'state' function.
-     */
-    static createState = (initialValue) => {
-        const instance = new StateImpl(initialValue);
+    static createState = (initialValue, equalityFn = Object.is) => {
+        const instance = new StateImpl(initialValue, equalityFn);
         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();
@@ -101,14 +62,10 @@ class StateImpl {
         }
         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)) {
+        if (this.equalityFn(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);
@@ -117,16 +74,12 @@ class StateImpl {
             }
         }
         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();
         }
@@ -134,27 +87,17 @@ class StateImpl {
     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);
@@ -164,22 +107,17 @@ class StateImpl {
                     }
                     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);
@@ -190,17 +128,13 @@ class StateImpl {
                 }
                 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);
@@ -209,8 +143,6 @@ class StateImpl {
                 }
             }
             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) {
@@ -221,19 +153,12 @@ class StateImpl {
             }
         };
     };
-    /**
-     * 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;
@@ -242,10 +167,7 @@ class StateImpl {
         }
         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;
@@ -253,34 +175,24 @@ class StateImpl {
                         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();
@@ -290,35 +202,25 @@ class StateImpl {
             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();
@@ -329,12 +231,7 @@ class StateImpl {
             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({}, {
@@ -349,17 +246,12 @@ class StateImpl {
                 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;
@@ -372,7 +264,6 @@ class StateImpl {
                 isUpdating = false;
             }
         });
-        // Override the lens state's set method to update the source
         const originalSet = lensState.set;
         lensState.set = (value) => {
             if (isUpdating) {
@@ -380,35 +271,25 @@ class StateImpl {
             }
             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) {
@@ -420,11 +301,8 @@ class StateImpl {
             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) {
@@ -435,72 +313,54 @@ class StateImpl {
         }
     };
 }
-// 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;
     }
@@ -511,7 +371,6 @@ const setValueAtPath = (obj, pathSegments, value) => {
     if (currentKey === undefined) {
         return obj;
     }
-    // Delegate to specialized handlers based on data type
     if (Array.isArray(obj)) {
         return updateArrayPath(obj, pathSegments, value);
     }

package/dist/src/index.min.js

@@ -0,0 +1 @@
+let s=Symbol(),i=(e,t=Object.is)=>u.createState(e,t);var e=e=>u.createEffect(e),t=e=>u.executeBatch(e),r=e=>u.createDerive(e),c=(e,t,r=Object.is)=>u.createSelect(e,t,r);let a=e=>()=>e();var n=(e,t=Object.is)=>{let r=i(e,t);return[()=>a(r)(),{set:e=>r.set(e),update:e=>r.update(e)}]},b=(e,t)=>u.createLens(e,t);class u{static currentSubscriber=null;static pendingSubscribers=new Set;static isNotifying=!1;static batchDepth=0;static deferredEffectCreations=[];static activeSubscribers=new Set;static stateTracking=new WeakMap;static subscriberDependencies=new WeakMap;static parentSubscriber=new WeakMap;static childSubscribers=new WeakMap;value;subscribers=new Set;stateId=Symbol();equalityFn;constructor(e,t=Object.is){this.value=e,this.equalityFn=t}static createState=(e,t=Object.is)=>{let r=new u(e,t);e=()=>r.get();return e.set=e=>r.set(e),e.update=e=>r.update(e),e[s]=r.stateId,e};get=()=>{var r=u.currentSubscriber;if(r){this.subscribers.add(r);let e=u.subscriberDependencies.get(r),t=(e||(e=new Set,u.subscriberDependencies.set(r,e)),e.add(this.subscribers),u.stateTracking.get(r));t||(t=new Set,u.stateTracking.set(r,t)),t.add(this.stateId)}return this.value};set=e=>{if(!this.equalityFn(this.value,e)){var t=u.currentSubscriber;if(t)if(u.stateTracking.get(t)?.has(this.stateId)&&!u.parentSubscriber.get(t))throw new Error("Infinite loop detected: effect() cannot update a state() it depends on!");if(this.value=e,0!==this.subscribers.size){for(var r of this.subscribers)u.pendingSubscribers.add(r);0!==u.batchDepth||u.isNotifying||u.notifySubscribers()}}};update=e=>{this.set(e(this.value))};static createEffect=e=>{let r=()=>{if(!u.activeSubscribers.has(r)){u.activeSubscribers.add(r);var t=u.currentSubscriber;try{if(u.cleanupEffect(r),u.currentSubscriber=r,u.stateTracking.set(r,new Set),t){u.parentSubscriber.set(r,t);let e=u.childSubscribers.get(t);e||(e=new Set,u.childSubscribers.set(t,e)),e.add(r)}e()}finally{u.currentSubscriber=t,u.activeSubscribers.delete(r)}}};if(0===u.batchDepth)r();else{if(u.currentSubscriber){var t=u.currentSubscriber;u.parentSubscriber.set(r,t);let e=u.childSubscribers.get(t);e||(e=new Set,u.childSubscribers.set(t,e)),e.add(r)}u.deferredEffectCreations.push(r)}return()=>{u.cleanupEffect(r),u.pendingSubscribers.delete(r),u.activeSubscribers.delete(r),u.stateTracking.delete(r);var e=u.parentSubscriber.get(r),e=(e&&(e=u.childSubscribers.get(e))&&e.delete(r),u.parentSubscriber.delete(r),u.childSubscribers.get(r));if(e){for(var t of e)u.cleanupEffect(t);e.clear(),u.childSubscribers.delete(r)}}};static executeBatch=e=>{u.batchDepth++;try{return e()}catch(e){throw 1===u.batchDepth&&(u.pendingSubscribers.clear(),u.deferredEffectCreations.length=0),e}finally{if(u.batchDepth--,0===u.batchDepth){if(0<u.deferredEffectCreations.length){var t,e=[...u.deferredEffectCreations];u.deferredEffectCreations.length=0;for(t of e)t()}0<u.pendingSubscribers.size&&!u.isNotifying&&u.notifySubscribers()}}};static createDerive=t=>{let r=u.createState(void 0),s=!1,i;return u.createEffect(()=>{var e=t();s&&Object.is(i,e)||(i=e,r.set(e)),s=!0}),()=>(s||(i=t(),s=!0,r.set(i)),r())};static createSelect=(t,r,s=Object.is)=>{let i,c,a=!1,n=u.createState(void 0);return u.createEffect(()=>{var e=t();a&&Object.is(i,e)||(i=e,e=r(e),a&&void 0!==c&&s(c,e))||(c=e,n.set(e),a=!0)}),()=>(a||(i=t(),c=r(i),n.set(c),a=!0),n())};static createLens=(e,t)=>{let r=(()=>{let r=[],s=new Proxy({},{get:(e,t)=>("string"!=typeof t&&"number"!=typeof t||r.push(t),s)});try{t(s)}catch{}return r})(),s=u.createState(t(e())),i=!1,c=(u.createEffect(()=>{if(!i){i=!0;try{s.set(t(e()))}finally{i=!1}}}),s.set);return s.set=t=>{if(!i){i=!0;try{c(t),e.update(e=>p(e,r,t))}finally{i=!1}}},s.update=e=>{s.set(e(s()))},s};static notifySubscribers=()=>{if(!u.isNotifying){u.isNotifying=!0;try{for(;0<u.pendingSubscribers.size;){var e,t=Array.from(u.pendingSubscribers);u.pendingSubscribers.clear();for(e of t)e()}}finally{u.isNotifying=!1}}};static cleanupEffect=e=>{u.pendingSubscribers.delete(e);var t=u.subscriberDependencies.get(e);if(t){for(var r of t)r.delete(e);t.clear(),u.subscriberDependencies.delete(e)}}}let f=(e,t,r)=>{e=[...e];return e[t]=r,e},l=(e,t,r)=>{e={...e};return e[t]=r,e},d=e=>"number"==typeof e||!Number.isNaN(Number(e))?[]:{},S=(e,t,r)=>{var s=Number(t[0]);if(1===t.length)return f(e,s,r);var i=[...e],t=t.slice(1),c=t[0];let a=e[s];return null==a&&(a=void 0!==c?d(c):{}),i[s]=p(a,t,r),i},h=(e,t,r)=>{var s=t[0];if(void 0===s)return e;if(1===t.length)return l(e,s,r);var t=t.slice(1),i=t[0];let c=e[s];null==c&&(c=void 0!==i?d(i):{});i={...e};return i[s]=p(c,t,r),i},p=(e,t,r)=>0===t.length?r:null==e?p({},t,r):void 0===t[0]?e:(Array.isArray(e)?S:h)(e,t,r);export{i as state,e as effect,t as batch,r as derive,c as select,a as readonlyState,n as protectedState,b as lens};

package/package.json

@@ -1,16 +1,17 @@
 {
 	"name": "@nerdalytics/beacon",
-	"version": "1000.1.1",
+	"version": "1000.2.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/src/index.js",
+	"main": "dist/src/index.min.js",
 	"types": "dist/src/index.d.ts",
-	"files": [
-		"dist/src/index.js",
-		"dist/src/index.d.ts",
-		"src/index.ts",
-		"LICENSE"
-	],
+	"files": ["dist/src/index.js", "dist/src/index.d.ts", "src/index.ts", "LICENSE"],
+	"exports": {
+		".": {
+			"typescript": "./src/index.ts",
+			"default": "./dist/src/index.js"
+		}
+	},
 	"repository": {
 		"url": "git+https://github.com/nerdalytics/beacon.git",
 		"type": "git"
@@ -34,10 +35,12 @@
 		"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",
+		"test:unit:custom-equality": "node --test tests/custom-equality.test.ts",
 		"benchmark": "node scripts/benchmark.ts",
 		"build": "npm run build:lts",
 		"prebuild:lts": "rm -rf dist/",
 		"build:lts": "tsc -p tsconfig.lts.json",
+		"postbuild:lts": "npx uglify-js --compress --mangle --module --toplevel --v8 --warn --source-map \"content='dist/src/index.js.map'\" --output dist/src/index.min.js dist/src/index.js",
 		"prepublishOnly": "npm run build:lts",
 		"pretest:lts": "node scripts/run-lts-tests.js",
 		"test:lts:20": "node --test dist/tests/**.js",
@@ -66,11 +69,12 @@
 	"license": "MIT",
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
-		"@types/node": "22.14.0",
-		"typescript": "5.8.3"
+		"@types/node": "22.14.1",
+		"typescript": "5.8.3",
+		"uglify-js": "3.19.3"
 	},
 	"engines": {
 		"node": ">=20.0.0"
 	},
-	"packageManager": "npm@11.2.0"
+	"packageManager": "npm@11.3.0"
 }

package/src/index.ts

@@ -18,7 +18,8 @@ export type State<T> = ReadOnlyState<T> &
 /**
  * Creates a reactive state container with the provided initial value.
  */
-export const state = <T>(initialValue: T): State<T> => StateImpl.createState(initialValue)
+export const state = <T>(initialValue: T, equalityFn: (a: T, b: T) => boolean = Object.is): State<T> =>
+	StateImpl.createState(initialValue, equalityFn)
 
 /**
  * Registers a function to run whenever its reactive dependencies change.
@@ -55,8 +56,11 @@ export const readonlyState =
 /**
  * Creates a state with access control, returning a tuple of reader and writer.
  */
-export const protectedState = <T>(initialValue: T): [ReadOnlyState<T>, WriteableState<T>] => {
-	const fullState = state(initialValue)
+export const protectedState = <T>(
+	initialValue: T,
+	equalityFn: (a: T, b: T) => boolean = Object.is
+): [ReadOnlyState<T>, WriteableState<T>] => {
+	const fullState = state(initialValue, equalityFn)
 	return [
 		(): T => readonlyState(fullState)(),
 		{
@@ -93,17 +97,19 @@ class StateImpl<T> {
 	private value: T
 	private subscribers = new Set<Subscriber>()
 	private stateId = Symbol()
+	private equalityFn: (a: T, b: T) => boolean
 
-	constructor(initialValue: T) {
+	constructor(initialValue: T, equalityFn: (a: T, b: T) => boolean = Object.is) {
 		this.value = initialValue
+		this.equalityFn = equalityFn
 	}
 
 	/**
 	 * 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)
+	static createState = <T>(initialValue: T, equalityFn: (a: T, b: T) => boolean = Object.is): State<T> => {
+		const instance = new StateImpl<T>(initialValue, equalityFn)
 		const get = (): T => instance.get()
 		get.set = (value: T): void => instance.set(value)
 		get.update = (fn: (currentValue: T) => T): void => instance.update(fn)
@@ -143,7 +149,7 @@ class StateImpl<T> {
 	// Handles value updates with built-in optimizations and safeguards
 	set = (newValue: T): void => {
 		// Skip updates for unchanged values to prevent redundant effect executions
-		if (Object.is(this.value, newValue)) {
+		if (this.equalityFn(this.value, newValue)) {
 			return
 		}