@nerdalytics/beacon 1.0.0 → 1000.0.0

package/README.md

@@ -1,6 +1,6 @@
-# Beacon
+# 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"/>
 
-A lightweight reactive signal library for Node.js backends. Enables reactive state management with automatic dependency tracking and efficient updates for server-side applications.
+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
 
@@ -8,10 +8,13 @@ A lightweight reactive signal library for Node.js backends. Enables reactive sta
 - [Installation](#installation)
 - [Usage](#usage)
 - [API](#api)
-  - [state](#statetinitialvalue-t-signalt)
-  - [derived](#derivedfn--t-signalt)
-  - [effect](#effectfn--void--void)
-  - [batch](#batchfn--t-t)
+  - [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)
+  - [readonlyState](#readonlystatetstate-statet-readonlystatet)
+  - [protectedState](#protectedstatetinitialvalue-t-readonlystatet-writeablestatet)
 - [Development](#development)
   - [Node.js LTS Compatibility](#nodejs-lts-compatibility)
 - [Key Differences vs TC39 Proposal](#key-differences-between-my-library-and-the-tc39-proposal)
@@ -21,31 +24,33 @@ A lightweight reactive signal library for Node.js backends. Enables reactive sta
 
 ## Features
 
-- 🔄 **Reactive signals** - Create reactive values that automatically track dependencies
-- 🧮 **Computed values** - Derive values from other signals with automatic updates
-- 🔍 **Fine-grained reactivity** - Dependencies are tracked precisely at the signal level
+- 📶 **Reactive state** - Create reactive values that automatically track dependencies
+- 🧮 **Computed values** - Derive values from other states with automatic updates
+- 🔍 **Fine-grained reactivity** - Dependencies are tracked precisely at the state level
 - 🏎️ **Efficient updates** - Only recompute values when dependencies change
 - 📦 **Batched updates** - Group multiple updates for performance
+- 🎯 **Targeted subscriptions** - Select and subscribe to specific parts of state objects
 - 🧹 **Automatic cleanup** - Effects and computations automatically clean up dependencies
-- 🔁 **Cycle handling** - Safely manages cyclic dependencies without crashing
+- ♻️ **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
 - ✅ **Node.js compatibility** - Works with Node.js LTS v20+ and v22+
 
 ## Installation
 
-```bash
+```sh
 npm install @nerdalytics/beacon
 ```
 
 ## Usage
 
 ```typescript
-import { state, derived, effect, batch } from "@nerdalytics/beacon";
+import { state, derive, effect, batch, select, readonlyState, protectedState } from "@nerdalytics/beacon";
 
 // Create reactive state
 const count = state(0);
-const doubled = derived(() => count() * 2);
+const doubled = derive(() => count() * 2);
 
 // Read values
 console.log(count()); // => 0
@@ -73,20 +78,63 @@ batch(() => {
 });
 // => "Count is 20, doubled is 40" (only once)
 
+// 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);
+
+effect(() => {
+  console.log(`Name changed: ${nameSelector()}`);
+});
+// => "Name changed: Alice"
+
+// Updates to the selected property will trigger the effect
+user.update(u => ({ ...u, name: "Bob" }));
+// => "Name changed: Bob"
+
+// Updates to other properties won't trigger the effect
+user.update(u => ({ ...u, age: 31 })); // No effect triggered
+
 // Unsubscribe the effect to stop it from running on future updates
 // and clean up all its internal subscriptions
 unsubscribe();
+
+// 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
+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);
+}
 ```
 
 ## API
 
-### `state<T>(initialValue: T): Signal<T>`
+### `state<T>(initialValue: T): State<T>`
 
-Creates a new reactive signal with the given initial value.
+Creates a new reactive state container with the provided initial value.
 
-### `derived<T>(fn: () => T): Signal<T>`
+### `derive<T>(fn: () => T): ReadOnlyState<T>`
 
-Creates a derived signal that updates when its dependencies change.
+Creates a read-only computed value that updates when its dependencies change.
 
 ### `effect(fn: () => void): () => void`
 
@@ -96,9 +144,21 @@ Creates an effect that runs the given function immediately and whenever its depe
 
 Batches multiple updates to only trigger effects once at the end.
 
+### `select<T, R>(source: ReadOnlyState<T>, selectorFn: (state: T) => R, equalityFn?: (a: R, b: R) => boolean): ReadOnlyState<R>`
+
+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`).
+
+### `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.
+
+### `protectedState<T>(initialValue: T): [ReadOnlyState<T>, WriteableState<T>]`
+
+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.
+
 ## Development
 
-```bash
+```sh
 # Install dependencies
 npm install
 
@@ -111,19 +171,26 @@ npm run test:coverage
 # Run specific test suites
 # Core functionality
 npm run test:unit:state
-npm run test:unit:derived
 npm run test:unit:effect
+npm run test:unit:derive
 npm run test:unit:batch
+npm run test:unit:select
+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     # Tests for cyclic dependency handling
+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
-
-# Build for Node.js LTS compatibility (v20+)
-npm run build:lts
+npm run lint
+npm run check    # Runs Bioms lint + format
 ```
 
 ### Node.js LTS Compatibility
@@ -134,7 +201,7 @@ Beacon supports the two most recent Node.js LTS versions (currently v20 and v22)
 
 | Aspect | @nerdalytics/beacon | TC39 Proposal |
 |--------|---------------------|---------------|
-| **API Style** | Functional approach (`state()`, `derived()`) | Class-based design (`Signal.State`, `Signal.Computed`) |
+| **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 |
@@ -146,42 +213,51 @@ Beacon is designed with a focus on simplicity, performance, and robust handling
 
 ### Key Implementation Concepts
 
-- **Fine-grained reactivity**: Dependencies are tracked automatically at the signal level
+- **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
-
-For an in-depth explanation of Beacon's internal architecture, advanced features, and best practices for handling complex scenarios like cyclical dependencies, see the [TECHNICAL_DETAILS.md][2] document.
+- **Optimized batching**: Smart scheduling of updates to minimize redundant computations
 
 ## FAQ
 
 <details>
 
 <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 "Signal" helps avoid confusion with the TC39 proposal and similar libraries while still accurately describing the core functionality.
+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.
 
 </details>
 
 <details>
 
 <summary>How does Beacon handle infinite update cycles?</summary>
-Beacon uses a queue-based update system that won't crash even with cyclical dependencies. If signals form a cycle where values constantly change (A updates B updates A...), the system will continue processing these updates without stack overflows. However, this could potentially affect performance if updates never stabilize. See the [TECHNICAL_DETAILS.md][4] document for best practices on handling cyclical dependencies.
+Beacon employs two complementary strategies for handling cyclical updates:
+
+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!"
+
+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.
+
+This dual approach prevents accidental infinite loops while still supporting legitimate cyclic update patterns that eventually stabilize.
 
 </details>
 
 <details>
 
 <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 signals.
+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.
 
 </details>
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE][3] file for details.
+This project is licensed under the MIT License. See the [LICENSE][2] file for details.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/nerdalytics/nerdalytics/refs/heads/main/nerdalytics-logo-gray-transparent.svg" width="128px">
+</div>
 
 <!-- Links collection -->
 
 [1]: https://github.com/tc39/proposal-signals
-[2]: ./TECHNICAL_DETAILS.md
-[3]: ./LICENSE
+[2]: ./LICENSE

package/package.json

@@ -1,58 +1,79 @@
 {
 	"name": "@nerdalytics/beacon",
-	"version": "1.0.0",
-	"description": "A lightweight reactive signal library for Node.js backends. Enables reactive state management with automatic dependency tracking and efficient updates for server-side applications.",
+	"version": "1000.0.0",
+	"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",
 	"files": [
-		"dist/",
+		"dist/index.js",
+		"dist/index.d.ts",
 		"src/",
 		"LICENSE"
 	],
+	"repository": {
+		"url": "github:nerdalytics/beacon",
+		"type": "git"
+	},
 	"scripts": {
-		"test": "node --test --experimental-config-file=node.config.json \"test/**/*.test.ts\"",
-		"test:coverage": "node --test --experimental-config-file=node.config.json --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info \"test/**/*.test.ts\"",
-		"test:unit": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^(State|Derived|Effect|Batch|Cleanup|Cyclic Dependencies)$/\"",
-		"test:unit:state": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^State$/\"",
-		"test:unit:derived": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^Derived$/\"",
-		"test:unit:effect": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^Effect$/\"",
-		"test:unit:batch": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^Batch$/\"",
-		"test:unit:cleanup": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^Cleanup$/\"",
-		"test:unit:cyclic": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^Cyclic Dependencies$/\"",
-		"test:integration": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^Deep Dependency Chains$/\"",
-		"test:perf": "node --test --experimental-config-file=node.config.json --test-name-pattern=\"/^Performance$/\"",
-		"test:perf:update-docs": "node scripts/update-performance-docs.ts",
-		"format": "biome format --write .",
-		"prebuild": "rm -rf dist/",
+		"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",
+
+		"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",
+		"test:unit:effect": "node --test tests/effect.test.ts",
+		"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: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",
-		"build:lts": "tsc -p tsconfig.build.json",
-		"prepublishOnly": "npm run build"
+		"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",
+
+		"update-performance-docs": "node --experimental-config-file=node.config.json scripts/update-performance-docs.ts"
 	},
 	"keywords": [
-		"reactive",
-		"signals",
 		"state-management",
-		"nodejs",
-		"typescript",
-		"reactive-programming",
+		"effects",
+		"fine-grained",
+		"computed-values",
+		"batching",
+		"signals",
+		"reactive",
+		"lightweight",
+		"performance",
 		"dependency-tracking",
-		"esm",
-		"observable",
-		"backend",
+		"memoization",
+		"memory-management",
+		"nodejs",
 		"server-side",
-		"computed-values",
-		"effects",
-		"batching"
+		"backend",
+		"typescript"
 	],
-	"author": "Denny Trebbin",
+	"author": "Denny Trebbin (nerdalytics)",
 	"license": "MIT",
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
-		"@types/node": "22.13.16",
-		"typescript": "5.8.2"
+		"@types/node": "22.14.0",
+		"typescript": "5.8.3"
 	},
 	"engines": {
 		"node": ">=20.0.0"
-	}
+	},
+	"packageManager": "npm@11.2.0"
 }

package/src/index.ts

@@ -1,175 +1,427 @@
-// Types
+// Core types for reactive primitives
 type Subscriber = () => void
-
 type Unsubscribe = () => void
-
-export interface Signal<T> {
-	(): T // get value
-	set(value: T): void // set value directly
-	update(fn: (currentValue: T) => T): void // update value with a function
+export type ReadOnlyState<T> = () => T
+export interface WriteableState<T> {
+	set(value: T): void
+	update(fn: (value: T) => T): void
 }
 
-// Global state for tracking
-let currentEffect: Subscriber | null = null
+// Special symbol used for internal tracking
+const STATE_ID = Symbol()
 
-let batchDepth = 0
+export type State<T> = ReadOnlyState<T> &
+	WriteableState<T> & {
+		[STATE_ID]?: symbol
+	}
 
-const pendingEffects = new Set<Subscriber>()
+/**
+ * Creates a reactive state container with the provided initial value.
+ */
+export const state = <T>(initialValue: T): State<T> => StateImpl.createState(initialValue)
 
-const subscriberDependencies = new WeakMap<Subscriber, Set<Set<Subscriber>>>()
+/**
+ * Registers a function to run whenever its reactive dependencies change.
+ */
+export const effect = (fn: () => void): Unsubscribe => StateImpl.createEffect(fn)
 
-// Use a flag to prevent multiple updates from running the effects
-let updateInProgress = false
+/**
+ * Groups multiple state updates to trigger effects only once at the end.
+ */
+export const batch = <T>(fn: () => T): T => StateImpl.executeBatch(fn)
 
 /**
- * Creates a new reactive state with the provided initial value
+ * Creates a read-only computed value that updates when its dependencies change.
  */
-export const state = <T>(initialValue: T): Signal<T> => {
-	let value = initialValue
+export const derive = <T>(computeFn: () => T): ReadOnlyState<T> => StateImpl.createDerive(computeFn)
 
-	const subscribers = new Set<Subscriber>()
+/**
+ * Creates an efficient subscription to a subset of a state value.
+ */
+export const select = <T, R>(
+	source: ReadOnlyState<T>,
+	selectorFn: (state: T) => R,
+	equalityFn: (a: R, b: R) => boolean = Object.is
+): ReadOnlyState<R> => StateImpl.createSelect(source, selectorFn, equalityFn)
 
-	const read = (): T => {
-		if (currentEffect) {
-			subscribers.add(currentEffect)
+/**
+ * Creates a read-only view of a state, hiding mutation methods.
+ */
+export const readonlyState =
+	<T>(state: State<T>): ReadOnlyState<T> =>
+	(): T =>
+		state()
+
+/**
+ * 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)
+	return [
+		(): T => readonlyState(fullState)(),
+		{
+			set: (value: T): void => fullState.set(value),
+			update: (fn: (value: T) => T): void => fullState.update(fn),
+		},
+	]
+}
 
-			let dependencies = subscriberDependencies.get(currentEffect)
+class StateImpl<T> {
+	// Static fields track global reactivity state - this centralized approach allows
+	// for coordinated updates while maintaining individual state isolation
+	private static currentSubscriber: Subscriber | null = null
+	private static pendingSubscribers = new Set<Subscriber>()
+	private static isNotifying = false
+	private static batchDepth = 0
+	private static deferredEffectCreations: Subscriber[] = []
+	private static activeSubscribers = new Set<Subscriber>()
+
+	// WeakMaps enable automatic garbage collection when subscribers are no
+	// longer referenced, preventing memory leaks in long-running applications
+	private static stateTracking = new WeakMap<Subscriber, Set<symbol>>()
+	private static subscriberDependencies = new WeakMap<Subscriber, Set<Set<Subscriber>>>()
+	private static parentSubscriber = new WeakMap<Subscriber, Subscriber>()
+	private static childSubscribers = new WeakMap<Subscriber, Set<Subscriber>>()
+
+	// Instance state - each state has unique subscribers and ID
+	private value: T
+	private subscribers = new Set<Subscriber>()
+	private stateId = Symbol()
+
+	constructor(initialValue: T) {
+		this.value = initialValue
+	}
+
+	// Creates a callable function that both reads and writes state -
+	// this design maintains JavaScript idioms while adding reactivity
+	static createState = <T>(initialValue: T): State<T> => {
+		const instance = new StateImpl<T>(initialValue)
+		const get = (): T => instance.get()
+		get.set = (value: T): void => instance.set(value)
+		get.update = (fn: (currentValue: T) => T): void => instance.update(fn)
+		get[STATE_ID] = instance.stateId
+		return get as State<T>
+	}
 
+	// Auto-tracks dependencies when called within effects, creating a fine-grained
+	// reactivity graph that only updates affected components
+	get = (): T => {
+		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()
-
-				subscriberDependencies.set(currentEffect, dependencies)
+				StateImpl.subscriberDependencies.set(currentEffect, dependencies)
 			}
-
-			dependencies.add(subscribers)
+			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 value
+		return this.value
 	}
 
-	const write = (newValue: T): void => {
-		if (Object.is(value, newValue)) {
-			return // No change
+	// 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)) {
+			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!')
+			}
 		}
-		value = newValue
 
-		if (subscribers.size === 0) {
+		this.value = newValue
+
+		// Skip updates when there are no subscribers, avoiding unnecessary processing
+		if (this.subscribers.size === 0) {
 			return
 		}
 
-		// Add subscribers to pendingEffects - always use loop for better performance
-		for (const sub of subscribers) {
-			pendingEffects.add(sub)
+		// 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)
 		}
 
-		if (batchDepth === 0 && !updateInProgress) {
-			processEffects()
+		// Immediate execution outside of batches, deferred execution inside batches
+		if (StateImpl.batchDepth === 0 && !StateImpl.isNotifying) {
+			StateImpl.notifySubscribers()
 		}
 	}
 
-	const update = (fn: (currentValue: T) => T): void => {
-		write(fn(value))
+	update = (fn: (currentValue: T) => T): void => {
+		this.set(fn(this.value))
 	}
 
-	return Object.assign(read, { set: write, update })
-}
+	// Creates an effect that automatically tracks and responds to state changes
+	static createEffect = (fn: () => void): Unsubscribe => {
+		const runEffect = (): void => {
+			// Prevent re-entrance to avoid cascade updates during effect execution
+			if (StateImpl.activeSubscribers.has(runEffect)) {
+				return
+			}
 
-/**
- * Process all pending effects, ensuring full propagation through the dependency chain
- */
-const processEffects = (): void => {
-	if (pendingEffects.size === 0 || updateInProgress) {
-		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)
+			}
+		}
 
-	updateInProgress = true
+		// 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)
+			}
 
-	while (pendingEffects.size > 0) {
-		const currentEffects = [...pendingEffects]
-		pendingEffects.clear()
+			// Queue for execution when batch completes
+			StateImpl.deferredEffectCreations.push(runEffect)
+		}
 
-		for (const effect of currentEffects) {
-			effect()
+		// Return cleanup function to properly disconnect from reactivity graph
+		return (): void => {
+			// 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)
+			}
 		}
 	}
 
-	updateInProgress = false
-}
-
-/**
- * Helper to clean up effect subscriptions
- */
-const cleanupEffect = (effect: Subscriber): void => {
-	const deps = subscriberDependencies.get(effect)
-
-	if (deps) {
-		for (const subscribers of deps) {
-			subscribers.delete(effect)
+	// Batches state updates to improve performance by reducing redundant effect runs
+	static executeBatch = <T>(fn: () => T): T => {
+		// Increment depth counter to handle nested batches correctly
+		StateImpl.batchDepth++
+		try {
+			return fn()
+		} catch (error: unknown) {
+			// 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()
+				}
+			}
 		}
-
-		deps.clear()
 	}
-}
-
-/**
- * Creates an effect that runs when its dependencies change
- */
-export const effect = (fn: () => void): Unsubscribe => {
-	const runEffect = (): void => {
-		cleanupEffect(runEffect)
 
-		const prevEffect = currentEffect
+	// Creates a derived state that memoizes computations and updates only when dependencies change
+	static createDerive = <T>(computeFn: () => T): ReadOnlyState<T> => {
+		const valueState = StateImpl.createState<T | undefined>(undefined)
+		let initialized = false
+		let cachedValue: T
+
+		// Internal effect automatically tracks dependencies and updates the derived value
+		StateImpl.createEffect((): void => {
+			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)
+			}
 
-		currentEffect = runEffect
+			initialized = true
+		})
 
-		try {
-			fn()
-		} finally {
-			currentEffect = prevEffect
+		// Return function with lazy initialization - ensures value is available
+		// even when accessed before its dependencies have had a chance to update
+		return (): T => {
+			if (!initialized) {
+				cachedValue = computeFn()
+				initialized = true
+				valueState.set(cachedValue)
+			}
+			return valueState() as T
 		}
 	}
 
-	runEffect()
+	// Creates a selector that monitors a slice of state with performance optimizations
+	static createSelect = <T, R>(
+		source: ReadOnlyState<T>,
+		selectorFn: (state: T) => R,
+		equalityFn: (a: R, b: R) => boolean = Object.is
+	): ReadOnlyState<R> => {
+		let lastSourceValue: T | undefined
+		let lastSelectedValue: R | undefined
+		let initialized = false
+		const valueState = StateImpl.createState<R | undefined>(undefined)
+
+		// Internal effect to track the source and update only when needed
+		StateImpl.createEffect((): void => {
+			const sourceValue = source()
+
+			// Skip computation if source reference hasn't changed
+			if (initialized && Object.is(lastSourceValue, sourceValue)) {
+				return
+			}
 
-	return (): void => {
-		cleanupEffect(runEffect)
-	}
-}
+			lastSourceValue = sourceValue
+			const newSelectedValue = selectorFn(sourceValue)
 
-/**
- * Creates a derived signal that computes its value from other signals
- */
-export const derived = <T>(fn: () => T): Signal<T> => {
-	// Initialize signal with the computed value
-	const signal = state<T>(fn())
+			// 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
+			}
 
-	// Only run fn() again when dependencies change
-	effect((): void => {
-		signal.set(fn())
-	})
+			// Update cache and notify subscribers due the value has changed
+			lastSelectedValue = newSelectedValue
+			valueState.set(newSelectedValue)
+			initialized = true
+		})
+
+		// Return function with eager initialization capability
+		return (): R => {
+			if (!initialized) {
+				lastSourceValue = source()
+				lastSelectedValue = selectorFn(lastSourceValue)
+				valueState.set(lastSelectedValue)
+				initialized = true
+			}
+			return valueState() as R
+		}
+	}
 
-	return signal
-}
+	// Processes queued subscriber notifications in a controlled, non-reentrant way
+	private static notifySubscribers = (): void => {
+		// Prevent reentrance to avoid cascading notification loops when
+		// effects trigger further state changes
+		if (StateImpl.isNotifying) {
+			return
+		}
 
-/**
- * Batches multiple updates to run effects only once at the end
- */
-export const batch = <T>(fn: () => T): T => {
-	batchDepth++
-
-	try {
-		return fn()
-	} catch (error) {
-		if (batchDepth === 1) {
-			pendingEffects.clear()
+		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
 		}
+	}
 
-		throw error
-	} finally {
-		batchDepth--
+	// Removes effect from dependency tracking to prevent memory leaks
+	private static cleanupEffect = (effect: Subscriber): void => {
+		// Remove from execution queue to prevent stale updates
+		StateImpl.pendingSubscribers.delete(effect)
 
-		if (batchDepth === 0 && pendingEffects.size > 0) {
-			processEffects()
+		// 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)
 		}
 	}
 }

package/dist/index.d.ts

@@ -1,23 +0,0 @@
-type Unsubscribe = () => void;
-export interface Signal<T> {
-    (): T;
-    set(value: T): void;
-    update(fn: (currentValue: T) => T): void;
-}
-/**
- * Creates a new reactive state with the provided initial value
- */
-export declare const state: <T>(initialValue: T) => Signal<T>;
-/**
- * Creates an effect that runs when its dependencies change
- */
-export declare const effect: (fn: () => void) => Unsubscribe;
-/**
- * Creates a derived signal that computes its value from other signals
- */
-export declare const derived: <T>(fn: () => T) => Signal<T>;
-/**
- * Batches multiple updates to run effects only once at the end
- */
-export declare const batch: <T>(fn: () => T) => T;
-export {};

package/dist/index.js

@@ -1,129 +0,0 @@
-// Global state for tracking
-let currentEffect = null;
-let batchDepth = 0;
-const pendingEffects = new Set();
-const subscriberDependencies = new WeakMap();
-// Use a flag to prevent multiple updates from running the effects
-let updateInProgress = false;
-/**
- * Creates a new reactive state with the provided initial value
- */
-export const state = (initialValue) => {
-    let value = initialValue;
-    const subscribers = new Set();
-    const read = () => {
-        if (currentEffect) {
-            subscribers.add(currentEffect);
-            let dependencies = subscriberDependencies.get(currentEffect);
-            if (!dependencies) {
-                dependencies = new Set();
-                subscriberDependencies.set(currentEffect, dependencies);
-            }
-            dependencies.add(subscribers);
-        }
-        return value;
-    };
-    const write = (newValue) => {
-        if (Object.is(value, newValue)) {
-            return; // No change
-        }
-        value = newValue;
-        if (subscribers.size === 0) {
-            return;
-        }
-        // Add subscribers to pendingEffects - always use loop for better performance
-        for (const sub of subscribers) {
-            pendingEffects.add(sub);
-        }
-        if (batchDepth === 0 && !updateInProgress) {
-            processEffects();
-        }
-    };
-    const update = (fn) => {
-        write(fn(value));
-    };
-    return Object.assign(read, { set: write, update });
-};
-/**
- * Process all pending effects, ensuring full propagation through the dependency chain
- */
-const processEffects = () => {
-    if (pendingEffects.size === 0 || updateInProgress) {
-        return;
-    }
-    updateInProgress = true;
-    while (pendingEffects.size > 0) {
-        const currentEffects = [...pendingEffects];
-        pendingEffects.clear();
-        for (const effect of currentEffects) {
-            effect();
-        }
-    }
-    updateInProgress = false;
-};
-/**
- * Helper to clean up effect subscriptions
- */
-const cleanupEffect = (effect) => {
-    const deps = subscriberDependencies.get(effect);
-    if (deps) {
-        for (const subscribers of deps) {
-            subscribers.delete(effect);
-        }
-        deps.clear();
-    }
-};
-/**
- * Creates an effect that runs when its dependencies change
- */
-export const effect = (fn) => {
-    const runEffect = () => {
-        cleanupEffect(runEffect);
-        const prevEffect = currentEffect;
-        currentEffect = runEffect;
-        try {
-            fn();
-        }
-        finally {
-            currentEffect = prevEffect;
-        }
-    };
-    runEffect();
-    return () => {
-        cleanupEffect(runEffect);
-    };
-};
-/**
- * Creates a derived signal that computes its value from other signals
- */
-export const derived = (fn) => {
-    // Initialize signal with the computed value
-    const signal = state(fn());
-    // Only run fn() again when dependencies change
-    effect(() => {
-        signal.set(fn());
-    });
-    return signal;
-};
-/**
- * Batches multiple updates to run effects only once at the end
- */
-export const batch = (fn) => {
-    batchDepth++;
-    try {
-        return fn();
-    }
-    catch (error) {
-        if (batchDepth === 1) {
-            pendingEffects.clear();
-        }
-        throw error;
-    }
-    finally {
-        batchDepth--;
-        if (batchDepth === 0 && pendingEffects.size > 0) {
-            processEffects();
-        }
-    }
-};
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,4BAA4B;AAC5B,IAAI,aAAa,GAAsB,IAAI,CAAA;AAE3C,IAAI,UAAU,GAAG,CAAC,CAAA;AAElB,MAAM,cAAc,GAAG,IAAI,GAAG,EAAc,CAAA;AAE5C,MAAM,sBAAsB,GAAG,IAAI,OAAO,EAAoC,CAAA;AAE9E,kEAAkE;AAClE,IAAI,gBAAgB,GAAG,KAAK,CAAA;AAE5B;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAI,YAAe,EAAa,EAAE;IACtD,IAAI,KAAK,GAAG,YAAY,CAAA;IAExB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAc,CAAA;IAEzC,MAAM,IAAI,GAAG,GAAM,EAAE;QACpB,IAAI,aAAa,EAAE,CAAC;YACnB,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;YAE9B,IAAI,YAAY,GAAG,sBAAsB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;YAE5D,IAAI,CAAC,YAAY,EAAE,CAAC;gBACnB,YAAY,GAAG,IAAI,GAAG,EAAE,CAAA;gBAExB,sBAAsB,CAAC,GAAG,CAAC,aAAa,EAAE,YAAY,CAAC,CAAA;YACxD,CAAC;YAED,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QAC9B,CAAC;QAED,OAAO,KAAK,CAAA;IACb,CAAC,CAAA;IAED,MAAM,KAAK,GAAG,CAAC,QAAW,EAAQ,EAAE;QACnC,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;YAChC,OAAM,CAAC,YAAY;QACpB,CAAC;QACD,KAAK,GAAG,QAAQ,CAAA;QAEhB,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAM;QACP,CAAC;QAED,6EAA6E;QAC7E,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC/B,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACxB,CAAC;QAED,IAAI,UAAU,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3C,cAAc,EAAE,CAAA;QACjB,CAAC;IACF,CAAC,CAAA;IAED,MAAM,MAAM,GAAG,CAAC,EAA0B,EAAQ,EAAE;QACnD,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IACjB,CAAC,CAAA;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AACnD,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,cAAc,GAAG,GAAS,EAAE;IACjC,IAAI,cAAc,CAAC,IAAI,KAAK,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACnD,OAAM;IACP,CAAC;IAED,gBAAgB,GAAG,IAAI,CAAA;IAEvB,OAAO,cAAc,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,cAAc,GAAG,CAAC,GAAG,cAAc,CAAC,CAAA;QAC1C,cAAc,CAAC,KAAK,EAAE,CAAA;QAEtB,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;YACrC,MAAM,EAAE,CAAA;QACT,CAAC;IACF,CAAC;IAED,gBAAgB,GAAG,KAAK,CAAA;AACzB,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,aAAa,GAAG,CAAC,MAAkB,EAAQ,EAAE;IAClD,MAAM,IAAI,GAAG,sBAAsB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAE/C,IAAI,IAAI,EAAE,CAAC;QACV,KAAK,MAAM,WAAW,IAAI,IAAI,EAAE,CAAC;YAChC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3B,CAAC;QAED,IAAI,CAAC,KAAK,EAAE,CAAA;IACb,CAAC;AACF,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,EAAc,EAAe,EAAE;IACrD,MAAM,SAAS,GAAG,GAAS,EAAE;QAC5B,aAAa,CAAC,SAAS,CAAC,CAAA;QAExB,MAAM,UAAU,GAAG,aAAa,CAAA;QAEhC,aAAa,GAAG,SAAS,CAAA;QAEzB,IAAI,CAAC;YACJ,EAAE,EAAE,CAAA;QACL,CAAC;gBAAS,CAAC;YACV,aAAa,GAAG,UAAU,CAAA;QAC3B,CAAC;IACF,CAAC,CAAA;IAED,SAAS,EAAE,CAAA;IAEX,OAAO,GAAS,EAAE;QACjB,aAAa,CAAC,SAAS,CAAC,CAAA;IACzB,CAAC,CAAA;AACF,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAI,EAAW,EAAa,EAAE;IACpD,4CAA4C;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAI,EAAE,EAAE,CAAC,CAAA;IAE7B,+CAA+C;IAC/C,MAAM,CAAC,GAAS,EAAE;QACjB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAA;IACjB,CAAC,CAAC,CAAA;IAEF,OAAO,MAAM,CAAA;AACd,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAI,EAAW,EAAK,EAAE;IAC1C,UAAU,EAAE,CAAA;IAEZ,IAAI,CAAC;QACJ,OAAO,EAAE,EAAE,CAAA;IACZ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;YACtB,cAAc,CAAC,KAAK,EAAE,CAAA;QACvB,CAAC;QAED,MAAM,KAAK,CAAA;IACZ,CAAC;YAAS,CAAC;QACV,UAAU,EAAE,CAAA;QAEZ,IAAI,UAAU,KAAK,CAAC,IAAI,cAAc,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACjD,cAAc,EAAE,CAAA;QACjB,CAAC;IACF,CAAC;AACF,CAAC,CAAA"}