@zeix/cause-effect 0.18.4 → 1.0.0

package/test/unown.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, test } from 'bun:test'
+import {
+	createEffect,
+	createScope,
+	createState,
+	unown,
+} from '../index.ts'
+
+describe('unown', () => {
+
+	test('should return the value of the callback', () => {
+		const result = unown(() => 42)
+		expect(result).toBe(42)
+	})
+
+	test('should run the callback immediately and synchronously', () => {
+		let ran = false
+		unown(() => { ran = true })
+		expect(ran).toBe(true)
+	})
+
+	test('scope created inside unown is not registered on the enclosing scope', () => {
+		let innerCleanupRan = false
+		const outerDispose = createScope(() => {
+			unown(() => {
+				createScope(() => {
+					return () => { innerCleanupRan = true }
+				})
+			})
+		})
+		outerDispose()
+		expect(innerCleanupRan).toBe(false)
+	})
+
+	test('scope created inside unown is not registered on the enclosing effect', () => {
+		const trigger = createState(0)
+		let innerCleanupRuns = 0
+
+		const outerDispose = createScope(() => {
+			createEffect((): undefined => {
+				trigger.get()
+				unown(() => {
+					createScope(() => {
+						return () => { innerCleanupRuns++ }
+					})
+				})
+			})
+		})
+
+		expect(innerCleanupRuns).toBe(0)
+		trigger.set(1)
+		expect(innerCleanupRuns).toBe(0)
+		trigger.set(2)
+		expect(innerCleanupRuns).toBe(0)
+
+		outerDispose()
+	})
+
+	test('effects inside an unowned scope survive effect re-runs (ownership bug regression)', () => {
+		const listChange = createState(0)
+		let componentEffectRuns = 0
+		let componentCleanupRuns = 0
+
+		const connectComponent = () => unown(() =>
+			createScope(() => {
+				createEffect((): undefined => {
+					componentEffectRuns++
+				})
+				return () => { componentCleanupRuns++ }
+			})
+		)
+
+		const outerDispose = createScope(() => {
+			createEffect((): undefined => {
+				listChange.get()
+				if (listChange.get() === 0) connectComponent()
+			})
+		})
+
+		expect(componentEffectRuns).toBe(1)
+		expect(componentCleanupRuns).toBe(0)
+
+		listChange.set(1)
+		expect(componentEffectRuns).toBe(1)
+		expect(componentCleanupRuns).toBe(0)
+
+		outerDispose()
+	})
+
+	test('effects inside an unowned scope still run reactively', () => {
+		const source = createState('a')
+		let effectRuns = 0
+
+		const dispose = unown(() =>
+			createScope(() => {
+				createEffect((): undefined => {
+					source.get()
+					effectRuns++
+				})
+			})
+		)
+
+		expect(effectRuns).toBe(1)
+		source.set('b')
+		expect(effectRuns).toBe(2)
+
+		dispose()
+		source.set('c')
+		expect(effectRuns).toBe(2)
+	})
+
+	test('dispose returned from an unowned scope still works', () => {
+		let cleanupRan = false
+		const dispose = unown(() =>
+			createScope(() => {
+				return () => { cleanupRan = true }
+			})
+		)
+		expect(cleanupRan).toBe(false)
+		dispose()
+		expect(cleanupRan).toBe(true)
+	})
+
+	test('nested unown calls work correctly', () => {
+		let innerCleanupRan = false
+		const outerDispose = createScope(() => {
+			unown(() => {
+				unown(() => {
+					createScope(() => {
+						return () => { innerCleanupRan = true }
+					})
+				})
+			})
+		})
+		outerDispose()
+		expect(innerCleanupRan).toBe(false)
+	})
+
+	test('restores the active owner after the callback completes', () => {
+		let postCleanupRan = false
+		const outerDispose = createScope(() => {
+			unown(() => { /* some unowned work */ })
+			createScope(() => {
+				return () => { postCleanupRan = true }
+			})
+		})
+		outerDispose()
+		expect(postCleanupRan).toBe(true)
+	})
+
+	test('restores the active owner even if the callback throws', () => {
+		let postCleanupRan = false
+		const outerDispose = createScope(() => {
+			try {
+				unown(() => { throw new Error('boom') })
+			} catch {
+				// swallow
+			}
+			createScope(() => {
+				return () => { postCleanupRan = true }
+			})
+		})
+		outerDispose()
+		expect(postCleanupRan).toBe(true)
+	})
+
+	test('works correctly when called outside any scope or effect', () => {
+		let ran = false
+		const dispose = unown(() => {
+			ran = true
+			return createScope(() => {
+				return () => {}
+			})
+		})
+		expect(ran).toBe(true)
+		expect(typeof dispose).toBe('function')
+	})
+
+})

package/test/util/dependency-graph.ts

@@ -53,7 +53,8 @@ export function runGraph(
 ): number {
 	const rand = new Random('seed')
 	const { sources, layers } = graph
-	const leaves = layers[layers.length - 1]
+	// biome-ignore lint/style/noNonNullAssertion: test
+	const leaves = layers[layers.length - 1]!
 	const skipCount = Math.round(leaves.length * (1 - readFraction))
 	const readLeaves = removeElems(leaves, skipCount, rand)
 	const frameworkName = framework.name.toLowerCase()
@@ -65,7 +66,8 @@ export function runGraph(
 		for (let i = 0; i < iterations; i++) {
 			framework.withBatch(() => {
 				const sourceDex = i % sources.length
-				sources[sourceDex].write(i + sourceDex)
+				// biome-ignore lint/style/noNonNullAssertion: test
+				sources[sourceDex]!.write(i + sourceDex)
 			})
 
 			for (const leaf of readLeaves) {
@@ -87,7 +89,8 @@ export function runGraph(
         } */
 
 				const sourceDex = i % sources.length
-				sources[sourceDex].write(i + sourceDex)
+				// biome-ignore lint/style/noNonNullAssertion: test
+				sources[sourceDex]!.write(i + sourceDex)
 
 				for (const leaf of readLeaves) {
 					leaf.read()
@@ -153,7 +156,8 @@ function makeRow(
 	return sources.map((_, myDex) => {
 		const mySources: Computed<number>[] = []
 		for (let sourceDex = 0; sourceDex < nSources; sourceDex++) {
-			mySources.push(sources[(myDex + sourceDex) % sources.length])
+			// biome-ignore lint/style/noNonNullAssertion: test
+			mySources.push(sources[(myDex + sourceDex) % sources.length]!)
 		}
 
 		const staticNode = random.float() < staticFraction
@@ -170,7 +174,8 @@ function makeRow(
 			})
 		} else {
 			// dynamic node, drops one of the sources depending on the value of the first element
-			const first = mySources[0]
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const first = mySources[0]!
 			const tail = mySources.slice(1)
 			const node = framework.computed(() => {
 				counter.count++
@@ -180,7 +185,8 @@ function makeRow(
 
 				for (let i = 0; i < tail.length; i++) {
 					if (shouldDrop && i === dropDex) continue
-					sum += tail[i].read()
+					// biome-ignore lint/style/noNonNullAssertion: test
+					sum += tail[i]!.read()
 				}
 
 				return sum

package/tsconfig.json

@@ -19,6 +19,10 @@
 		// Best practices
 		"strict": true,
 		"skipLibCheck": true,
+		"noUncheckedIndexedAccess": true,
+		"exactOptionalPropertyTypes": true,
+		"useUnknownInCatchVariables": true,
+		"noUncheckedSideEffectImports": true,
 		"noFallthroughCasesInSwitch": true,
 
 		// Some stricter flags (disabled by default)
@@ -27,5 +31,5 @@
 		"noPropertyAccessFromIndexSignature": false,
 	},
 	"include": ["./**/*.ts"],
-	"exclude": ["node_modules", "types"],
+	"exclude": ["node_modules", "types", "index.js"],
 }

package/types/index.d.ts

@@ -1,10 +1,10 @@
 /**
  * @name Cause & Effect
- * @version 0.18.3
+ * @version 1.0.0
  * @author Esther Brunner
  */
 export { CircularDependencyError, type Guard, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, RequiredOwnerError, UnsetSignalValueError, } from './src/errors';
-export { batch, type Cleanup, type ComputedOptions, createScope, type EffectCallback, type MaybeCleanup, type MemoCallback, type Signal, type SignalOptions, SKIP_EQUALITY, type TaskCallback, untrack, } from './src/graph';
+export { batch, type Cleanup, type ComputedOptions, createScope, type EffectCallback, type MaybeCleanup, type MemoCallback, type Signal, type SignalOptions, SKIP_EQUALITY, type TaskCallback, unown, untrack, } from './src/graph';
 export { type Collection, type CollectionCallback, type CollectionChanges, type CollectionOptions, createCollection, type DeriveCollectionCallback, isCollection, } from './src/nodes/collection';
 export { createEffect, type MatchHandlers, type MaybePromise, match, } from './src/nodes/effect';
 export { createList, isEqual, isList, type KeyConfig, type List, type ListOptions, } from './src/nodes/list';

package/types/src/graph.d.ts

@@ -3,11 +3,11 @@ type SourceFields<T extends {}> = {
     value: T;
     sinks: Edge | null;
     sinksTail: Edge | null;
-    stop?: Cleanup;
+    stop?: Cleanup | undefined;
 };
 type OptionsFields<T extends {}> = {
     equals: (a: T, b: T) => boolean;
-    guard?: Guard<T>;
+    guard?: Guard<T> | undefined;
 };
 type SinkFields = {
     fn: unknown;
@@ -218,4 +218,14 @@ declare function untrack<T>(fn: () => T): T;
  * ```
  */
 declare function createScope(fn: () => MaybeCleanup): Cleanup;
-export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY, SKIP_EQUALITY, FLAG_CHECK, FLAG_CLEAN, FLAG_DIRTY, FLAG_RELINK, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_SLOT, TYPE_STORE, TYPE_TASK, unlink, untrack, };
+/**
+ * Runs a callback without any active owner.
+ * Any scopes or effects created inside the callback will not be registered as
+ * children of the current active owner (e.g. a re-runnable effect). Use this
+ * when a component or resource manages its own lifecycle independently of the
+ * reactive graph.
+ *
+ * @since 0.18.5
+ */
+declare function unown<T>(fn: () => T): T;
+export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY, SKIP_EQUALITY, FLAG_CHECK, FLAG_CLEAN, FLAG_DIRTY, FLAG_RELINK, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_SLOT, TYPE_STORE, TYPE_TASK, unlink, unown, untrack, };

package/.ai-context.md

@@ -1,281 +0,0 @@
-# AI Context for Cause & Effect
-
-## What is Cause & Effect?
-
-Cause & Effect is a modern reactive state management library for JavaScript/TypeScript that implements the signals pattern. It provides fine-grained reactivity with automatic dependency tracking, making it easy to build responsive applications with predictable state updates.
-
-## Core Architecture
-
-### Graph-Based Reactivity (`src/graph.ts`)
-
-The reactive engine is a linked graph of source and sink nodes connected by `Edge` entries:
-- **Sources** (StateNode) maintain a linked list of sink edges
-- **Sinks** (MemoNode, TaskNode, EffectNode) maintain a linked list of source edges
-- `link()` creates edges between sources and sinks during `.get()` calls
-- `propagate()` flags sinks as dirty when sources change
-- `flush()` processes queued effects after propagation
-- `trimSources()` removes stale edges after recomputation
-
-### Node Types
-```
-StateNode<T>  — source-only with equality + guard (State, Sensor)
-MemoNode<T>   — source + sink (Memo, Slot, Store, List, Collection)
-TaskNode<T>   — source + sink + async (Task)
-EffectNode    — sink + owner (Effect)
-Scope         — owner-only (createScope)
-```
-
-### Signal Types
-- **State** (`createState`): Mutable signals for primitive values and objects
-- **Sensor** (`createSensor`): Read-only signals for external input streams with automatic state updates. Use `SKIP_EQUALITY` for mutable object observation.
-- **Memo** (`createMemo`): Synchronous derived computations with memoization, reducer capabilities, and optional `watched(invalidate)` for external invalidation
-- **Task** (`createTask`): Async derived computations with automatic abort/cancellation and optional `watched(invalidate)` for external invalidation
-- **Store** (`createStore`): Mutable object signals with individually reactive properties via Proxy
-- **List** (`createList`): Mutable array signals with stable keys and reactive items
-- **Collection** (`createCollection`): Reactive collections — either externally-driven with watched lifecycle, or derived from List/Collection with item-level memoization
-- **Slot** (`createSlot`): Stable delegation signal with swappable backing signal, designed for integration layers (property descriptors, custom elements)
-- **Effect** (`createEffect`): Side effect handlers that react to signal changes
-
-### Key Principles
-1. **Functional API**: All signals created via `create*()` factory functions (no classes)
-2. **Type Safety**: Full TypeScript support with strict type constraints (`T extends {}`)
-3. **Performance**: Flag-based dirty checking, linked-list edge traversal, batched flushing
-4. **Async Support**: Built-in cancellation with AbortSignal in Tasks
-5. **Tree-shaking**: Optimized for minimal bundle size with `/*#__PURE__*/` annotations
-
-## Project Structure
-
-```
-cause-effect/
-├── src/
-│   ├── graph.ts           # Core reactive engine (nodes, edges, link, propagate, flush, batch)
-│   ├── nodes/
-│   │   ├── state.ts       # createState — mutable state signals
-│   │   ├── sensor.ts      # createSensor — external input tracking (also covers mutable object observation)
-│   │   ├── memo.ts        # createMemo — synchronous derived computations
-│   │   ├── task.ts        # createTask — async derived computations
-│   │   ├── effect.ts      # createEffect, match — side effects
-│   │   ├── store.ts       # createStore — reactive object stores
-│   │   ├── list.ts        # createList — reactive arrays with stable keys
-│   │   ├── collection.ts  # createCollection — externally-driven and derived collections
-│   │   └── slot.ts        # createSlot — stable delegation with swappable backing signal
-│   ├── util.ts            # Utility functions and type checks
-│   └── ...
-├── index.ts           # Entry point / main export file
-├── test/
-│   ├── state.test.ts
-│   ├── memo.test.ts
-│   ├── task.test.ts
-│   ├── effect.test.ts
-│   ├── store.test.ts
-│   ├── list.test.ts
-│   └── collection.test.ts
-└── package.json
-```
-
-## API Patterns
-
-### Signal Creation
-```typescript
-// State for primitives and objects
-const count = createState(42)
-const name = createState('Alice')
-
-// Sensor for external input
-const mousePos = createSensor<{ x: number; y: number }>((set) => {
-  const handler = (e: MouseEvent) => set({ x: e.clientX, y: e.clientY })
-  window.addEventListener('mousemove', handler)
-  return () => window.removeEventListener('mousemove', handler)
-})
-
-// Sensor for mutable object observation (SKIP_EQUALITY)
-const element = createSensor<HTMLElement>((set) => {
-  const node = document.getElementById('box')!
-  set(node)
-  const obs = new MutationObserver(() => set(node))
-  obs.observe(node, { attributes: true })
-  return () => obs.disconnect()
-}, { value: node, equals: SKIP_EQUALITY })
-
-// Store for objects with reactive properties
-const user = createStore({ name: 'Alice', age: 30 })
-
-// List with stable keys for arrays
-const items = createList(['apple', 'banana', 'cherry'])
-const users = createList(
-  [{ id: 'alice', name: 'Alice' }],
-  { keyConfig: user => user.id }
-)
-
-// Memo for synchronous derived values
-const doubled = createMemo(() => count.get() * 2)
-
-// Memo with reducer capabilities (access to previous value)
-const counter = createMemo(prev => {
-  const action = actions.get()
-  return action === 'increment' ? prev + 1 : prev - 1
-}, { value: 0 })
-
-// Task for async derived values with cancellation
-const userData = createTask(async (prev, abort) => {
-  const id = userId.get()
-  if (!id) return prev
-  const response = await fetch(`/users/${id}`, { signal: abort })
-  return response.json()
-})
-
-// Collection for derived transformations
-const doubled = numbers.deriveCollection((value: number) => value * 2)
-const enriched = users.deriveCollection(async (user, abort) => {
-  const res = await fetch(`/api/${user.id}`, { signal: abort })
-  return { ...user, details: await res.json() }
-})
-
-// Collection for externally-driven data
-const feed = createCollection<{ id: string; text: string }>((applyChanges) => {
-  const ws = new WebSocket('/feed')
-  ws.onmessage = (e) => applyChanges(JSON.parse(e.data))
-  return () => ws.close()
-}, { keyConfig: item => item.id })
-
-// Slot for stable property delegation
-const local = createState('default')
-const slot = createSlot(local)
-Object.defineProperty(element, 'label', slot)
-slot.replace(createMemo(() => parentState.get())) // swap backing signal
-```
-
-### Reactivity
-```typescript
-// Effects run when dependencies change
-const dispose = createEffect(() => {
-  console.log(`Count: ${count.get()}`)
-})
-
-// Effects can return cleanup functions
-createEffect(() => {
-  const timer = setInterval(() => console.log(count.get()), 1000)
-  return () => clearInterval(timer)
-})
-
-// match() for ergonomic signal value extraction inside effects
-createEffect(() => {
-  match([userData], {
-    ok: ([data]) => updateUI(data),
-    nil: () => showLoading(),
-    err: errors => showError(errors[0].message)
-  })
-})
-```
-
-### Value Access Patterns
-```typescript
-// All signals use .get() for value access
-const value = signal.get()
-
-// State has .set() and .update()
-state.set(newValue)
-state.update(current => current + 1)
-
-// Store properties are individually reactive via Proxy
-user.name.set('Bob')             // Only name watchers trigger
-user.age.update(age => age + 1)  // Only age watchers trigger
-
-// List with stable keys
-const items = createList(['apple', 'banana'], { keyConfig: 'fruit' })
-const appleSignal = items.byKey('fruit0')
-const firstKey = items.keyAt(0)
-const appleIndex = items.indexOfKey('fruit0')
-items.splice(1, 0, 'cherry')
-items.sort()
-
-// Collections via deriveCollection
-const processed = items.deriveCollection(item => item.toUpperCase())
-```
-
-## Coding Conventions
-
-### TypeScript Style
-- Generic constraints: `T extends {}` to exclude null/undefined
-- Use `const` for immutable values
-- Function overloads for complex type scenarios (e.g., `createCollection`, `deriveCollection`)
-- JSDoc comments on all public APIs
-- Pure function annotations: `/*#__PURE__*/` for tree-shaking
-
-### Naming Conventions
-- Factory functions: `create*` prefix (createState, createMemo, createEffect, createStore, createList, createCollection, createSensor, createSlot)
-- Type predicates: `is*` prefix (isState, isMemo, isTask, isStore, isList, isCollection, isSensor, isSlot)
-- Type constants: `TYPE_*` format (TYPE_STATE, TYPE_STORE, TYPE_SENSOR, TYPE_COLLECTION)
-- Callback types: `*Callback` suffix (MemoCallback, TaskCallback, EffectCallback, SensorCallback, CollectionCallback, DeriveCollectionCallback)
-
-### Error Handling
-- Custom error classes in `src/errors.ts`: CircularDependencyError, NullishSignalValueError, InvalidSignalValueError, InvalidCallbackError, RequiredOwnerError, UnsetSignalValueError
-- Descriptive error messages with `[TypeName]` prefix
-- Input validation via `validateSignalValue()` and `validateCallback()`
-- Optional type guards via `guard` option in SignalOptions
-
-## Performance Considerations
-
-### Optimization Patterns
-- Linked-list edges for O(1) link/unlink operations
-- Flag-based dirty checking: FLAG_CLEAN, FLAG_CHECK, FLAG_DIRTY, FLAG_RUNNING
-- Batched updates via `batch()` to minimize effect re-runs
-- Lazy evaluation: Memos only recompute when accessed and dirty
-- Automatic abort of in-flight Tasks when sources change
-
-### Memory Management
-- `trimSources()` removes stale edges after each recomputation
-- `unlink()` calls `source.stop()` when last sink disconnects (auto-cleanup for Sensor/Collection/Store/List)
-- AbortSignal integration for canceling async operations
-- `createScope()` for hierarchical cleanup of nested effects
-
-## Resource Management
-
-**Sensor and Collection** use a watched callback that returns a Cleanup function:
-```typescript
-const sensor = createSensor<T>((set) => {
-  // setup input tracking, call set(value) to update
-  return () => { /* cleanup */ }
-})
-
-const feed = createCollection<T>((applyChanges) => {
-  // setup external data source, call applyChanges(diffResult) on changes
-  return () => { /* cleanup */ }
-}, { keyConfig: item => item.id })
-```
-
-**Memo and Task** use an optional `watched` callback in options that receives an `invalidate` function:
-```typescript
-const derived = createMemo(() => element.get().textContent ?? '', {
-  watched: (invalidate) => {
-    const obs = new MutationObserver(() => invalidate())
-    obs.observe(element.get(), { childList: true })
-    return () => obs.disconnect()
-  }
-})
-```
-
-**Store and List** use an optional `watched` callback in options:
-```typescript
-const store = createStore(initialValue, {
-  watched: () => {
-    // setup resources
-    return () => { /* cleanup */ }
-  }
-})
-```
-
-Resources activate on first sink link and cleanup when last sink unlinks.
-
-## Build and Development
-
-### Tools
-- **Runtime**: Bun (also works with Node.js)
-- **Build**: Bun build with TypeScript compilation
-- **Testing**: Bun test runner (`bun test`)
-- **Linting**: Biome for code formatting and linting
-
-### Package Configuration
-- ES modules only (`"type": "module"`)
-- TypeScript declarations generated automatically
-- Tree-shaking friendly with proper sideEffects configuration