@rlabs-inc/signals 1.8.2 → 1.10.0

package/README.md

@@ -2,16 +2,29 @@
 
 **Production-grade fine-grained reactivity for TypeScript.**
 
-A complete standalone mirror of Svelte 5's reactivity system, enhanced with Angular's linkedSignal, Solid's createSelector, and Vue's effectScope. No compiler needed, no DOM, works anywhere - Bun, Node, Deno, or browser.
+A complete standalone implementation of modern reactivity patterns, combining the best of Svelte 5, Angular, Solid, and Vue. No compiler needed, no DOM dependencies - works anywhere: Bun, Node, Deno, or browser.
 
-## Why This Library?
+## Features
 
-- **True Fine-Grained Reactivity** - Changes to deeply nested properties only trigger effects that read that exact path
-- **Per-Property Tracking** - Proxy-based deep reactivity with lazy signal creation per property
-- **Framework-Agnostic** - Use the best patterns from Svelte, Angular, Solid, and Vue in any environment
-- **Zero Dependencies** - Pure TypeScript, no runtime dependencies
-- **Automatic Memory Cleanup** - FinalizationRegistry ensures signals are garbage collected properly
-- **Battle-Tested Patterns** - Based on proven reactivity systems from major frameworks
+- **Fine-Grained Reactivity** - Changes only trigger effects that depend on them
+- **Deep Reactivity** - Proxy-based tracking at any nesting depth
+- **Zero Dependencies** - Pure TypeScript, ~8KB minified
+- **Framework Patterns** - linkedSignal (Angular), createSelector (Solid), effectScope (Vue)
+- **Sync & Async Effects** - Choose predictable timing or automatic batching
+- **Automatic Cleanup** - FinalizationRegistry ensures proper garbage collection
+
+## Performance
+
+Benchmarked against Preact Signals (the fastest mainstream implementation):
+
+| Operation | @rlabs-inc/signals | Preact Signals |
+|-----------|-------------------|----------------|
+| Signal read | **2ns** | 3ns |
+| Signal write | 15ns | 12ns |
+| Effect run | **20ns** | 25ns |
+| Derived read | 5ns | 5ns |
+
+Performance is competitive while offering significantly more features.
 
 ## Installation
 
@@ -26,18 +39,18 @@ npm install @rlabs-inc/signals
 ```typescript
 import { signal, derived, effect, flushSync } from '@rlabs-inc/signals'
 
-// Create a signal
+// Create a signal (reactive value)
 const count = signal(0)
 
-// Create a derived value
+// Create a derived (computed value)
 const doubled = derived(() => count.value * 2)
 
-// Create an effect
+// Create an effect (side effect)
 effect(() => {
   console.log(`Count: ${count.value}, Doubled: ${doubled.value}`)
 })
 
-// Flush to run effects synchronously
+// Flush to run effects synchronously (for testing/demos)
 flushSync()  // Logs: "Count: 0, Doubled: 0"
 
 // Update the signal
@@ -47,6 +60,37 @@ flushSync()  // Logs: "Count: 5, Doubled: 10"
 
 ---
 
+## Table of Contents
+
+- [Core Primitives](#core-primitives)
+  - [signal](#signal)
+  - [signals](#signals)
+  - [derived](#derived)
+  - [state](#state)
+  - [stateRaw](#stateraw)
+- [Effects](#effects)
+  - [effect()](#effect-async)
+  - [effect.sync()](#effectsync)
+  - [effect.root()](#effectroot)
+  - [effect.tracking()](#effecttracking)
+- [Advanced Primitives](#advanced-primitives)
+  - [linkedSignal](#linkedsignal-angulars-killer-feature)
+  - [createSelector](#createselector-solids-on-to-o2-optimization)
+  - [effectScope](#effectscope-vues-lifecycle-management)
+- [Bindings & Slots](#bindings--slots)
+  - [bind](#bind)
+  - [slot](#slot)
+  - [slotArray](#slotarray)
+  - [trackedSlotArray](#trackedslotarray)
+  - [reactiveProps](#reactiveprops)
+- [Deep Reactivity](#deep-reactivity)
+- [Utilities](#utilities)
+- [Reactive Collections](#reactive-collections)
+- [Equality Functions](#equality-functions)
+- [Error Handling](#error-handling)
+
+---
+
 ## Core Primitives
 
 ### signal
@@ -60,7 +104,10 @@ signal<T>(initialValue: T, options?: { equals?: (a: T, b: T) => boolean }): Writ
 ```typescript
 const name = signal('John')
 console.log(name.value)  // 'John'
-name.value = 'Jane'      // Triggers effects
+name.value = 'Jane'      // Triggers effects that depend on it
+
+// With custom equality (skip updates when structurally equal)
+const user = signal({ name: 'John' }, { equals: deepEquals })
 ```
 
 ### signals
@@ -83,6 +130,30 @@ ui.content.value = 'updated'
 ui.width.value = 60
 ```
 
+### derived
+
+Create a computed value that automatically updates when dependencies change.
+
+```typescript
+derived<T>(fn: () => T, options?: { equals?: Equals<T> }): DerivedSignal<T>
+```
+
+```typescript
+const firstName = signal('John')
+const lastName = signal('Doe')
+
+const fullName = derived(() => `${firstName.value} ${lastName.value}`)
+console.log(fullName.value)  // 'John Doe'
+
+firstName.value = 'Jane'
+console.log(fullName.value)  // 'Jane Doe'
+```
+
+Deriveds are:
+- **Lazy** - Only computed when read
+- **Cached** - Value is memoized until dependencies change
+- **Pure** - Cannot write to signals inside (throws error)
+
 ### state
 
 Create a deeply reactive object. No `.value` needed - access properties directly.
@@ -94,10 +165,13 @@ state<T extends object>(initialValue: T): T
 ```typescript
 const user = state({
   name: 'John',
-  address: { city: 'NYC' }
+  address: { city: 'NYC', zip: '10001' }
 })
-user.name = 'Jane'           // Reactive
-user.address.city = 'LA'     // Also reactive, deeply
+
+// All property access is reactive
+user.name = 'Jane'           // Triggers effects reading user.name
+user.address.city = 'LA'     // Triggers effects reading user.address.city
+// Effects reading user.name are NOT triggered by city change (fine-grained!)
 ```
 
 ### stateRaw
@@ -119,34 +193,15 @@ Use `stateRaw` for:
 - Class instances
 - Large objects where you only care about replacement
 
-### derived
-
-Create a computed value that automatically updates when dependencies change.
-
-```typescript
-derived<T>(fn: () => T, options?: { equals?: Equals<T> }): DerivedSignal<T>
-```
-
-```typescript
-const firstName = signal('John')
-const lastName = signal('Doe')
-
-const fullName = derived(() => `${firstName.value} ${lastName.value}`)
-console.log(fullName.value)  // 'John Doe'
-```
-
-Deriveds are:
-- **Lazy** - Only computed when read
-- **Cached** - Value is memoized until dependencies change
-- **Pure** - Cannot write to signals inside (throws error)
-
 ---
 
 ## Effects
 
-### effect
+Effects are the bridge between reactive state and the outside world. They re-run when their dependencies change.
 
-Create a side effect that re-runs when dependencies change.
+### effect() (async)
+
+Create an effect that runs asynchronously via microtask. Multiple signal changes are automatically batched.
 
 ```typescript
 effect(fn: () => void | CleanupFn): DisposeFn
@@ -158,41 +213,75 @@ const count = signal(0)
 const dispose = effect(() => {
   console.log('Count is:', count.value)
 
-  // Optional cleanup function
-  return () => {
-    console.log('Cleaning up...')
-  }
+  // Optional cleanup function - runs before next execution
+  return () => console.log('Cleaning up...')
 })
 
+count.value = 1
+count.value = 2
+count.value = 3
+// Effect runs ONCE with final value (3) on next microtask
+
 // Stop the effect
 dispose()
 ```
 
-### effect.pre
+**When to use:** Most UI work, general reactivity. The automatic batching provides better throughput.
+
+### effect.sync()
 
-Create an effect that runs synchronously (like `$effect.pre` in Svelte).
+Create a synchronous effect that runs immediately when dependencies change. Combine with `batch()` for best performance.
 
 ```typescript
-effect.pre(() => {
-  // Runs immediately, not on microtask
+effect.sync(fn: () => void | CleanupFn): DisposeFn
+```
+
+```typescript
+const count = signal(0)
+
+effect.sync(() => {
+  console.log('Count:', count.value)
 })
+// Logs: "Count: 0" (runs immediately)
+
+count.value = 1  // Logs: "Count: 1" (runs immediately)
+count.value = 2  // Logs: "Count: 2" (runs immediately)
+
+// For better performance with multiple writes, use batch():
+batch(() => {
+  count.value = 10
+  count.value = 20
+  count.value = 30
+})
+// Logs: "Count: 30" (runs once at end of batch)
 ```
 
-### effect.root
+**When to use:**
+- Debugging (predictable execution order)
+- Testing (synchronous assertions)
+- Sequential logic where timing matters
+- When you need immediate side effects
 
-Create an effect scope that can contain nested effects.
+### effect.root()
+
+Create a root effect scope that can contain nested effects.
+
+```typescript
+effect.root(fn: () => void): DisposeFn
+```
 
 ```typescript
 const dispose = effect.root(() => {
-  effect(() => { /* ... */ })
-  effect(() => { /* ... */ })
+  effect(() => console.log('Effect A'))
+  effect(() => console.log('Effect B'))
+  effect.sync(() => console.log('Sync Effect C'))
 })
 
-// Disposes all nested effects
+// Later, clean up ALL nested effects at once
 dispose()
 ```
 
-### effect.tracking
+### effect.tracking()
 
 Check if currently inside a reactive tracking context.
 
@@ -202,86 +291,195 @@ if (effect.tracking()) {
 }
 ```
 
----
+### effect.pre (deprecated)
 
-## Bindings
+Alias for `effect.sync()`. Use `effect.sync()` instead for clarity.
 
-Two-way reactive pointers that forward reads and writes to a source signal.
+---
 
-### bind
+## Advanced Primitives
 
-Create a reactive binding.
+### linkedSignal (Angular's killer feature)
+
+Create a writable signal that derives from a source but can be manually overridden. When the source changes, the linked signal resets to the computed value.
 
 ```typescript
-bind<T>(source: WritableSignal<T> | Binding<T> | T | (() => T)): Binding<T>
+linkedSignal<D>(fn: () => D): WritableSignal<D>
+linkedSignal<S, D>(options: LinkedSignalOptions<S, D>): WritableSignal<D>
 ```
 
+**Simple form - dropdown selection:**
+
 ```typescript
-const source = signal(0)
-const binding = bind(source)
+const options = signal(['a', 'b', 'c'])
+const selected = linkedSignal(() => options.value[0])
 
-// Reading through binding reads from source
-console.log(binding.value)  // 0
+console.log(selected.value)  // 'a'
+selected.value = 'b'         // Manual override
+console.log(selected.value)  // 'b'
 
-// Writing through binding writes to source
-binding.value = 42
-console.log(source.value)  // 42
+options.value = ['x', 'y']   // Source changes
+flushSync()
+console.log(selected.value)  // 'x' (reset to first item)
 ```
 
-**Overloads:**
-- `bind(signal)` - Creates writable binding to signal
-- `bind(binding)` - Chains bindings (both point to same source)
-- `bind(value)` - Wraps raw value in a signal
-- `bind(() => expr)` - Creates read-only binding from getter
+**Advanced form - keep valid selection:**
 
-**Use cases:**
-- Two-way binding for form inputs
-- Connecting parent state to child components
-- Creating reactive links between signals
+```typescript
+const items = signal([1, 2, 3])
+const selectedItem = linkedSignal({
+  source: () => items.value,
+  computation: (newItems, prev) => {
+    // Keep selection if still valid
+    if (prev && newItems.includes(prev.value)) {
+      return prev.value
+    }
+    return newItems[0]
+  }
+})
+```
+
+**Form input that resets when data reloads:**
+
+```typescript
+const user = signal({ name: 'Alice' })
+const editName = linkedSignal(() => user.value.name)
+
+// User types in input
+editName.value = 'Bob'
+console.log(editName.value)  // 'Bob'
 
-### bindReadonly
+// When user data reloads from server
+user.value = { name: 'Charlie' }
+flushSync()
+console.log(editName.value)  // 'Charlie' (reset!)
+```
 
-Create a read-only binding.
+### createSelector (Solid's O(n) to O(2) optimization)
+
+Create a selector function for efficient list selection tracking. Instead of O(n) effects re-running, only affected items run = O(2).
 
 ```typescript
-const source = signal(0)
-const readonly = bindReadonly(source)
+createSelector<T, U = T>(
+  source: () => T,
+  fn?: (key: U, value: T) => boolean
+): SelectorFn<T, U>
+```
+
+```typescript
+const selectedId = signal(1)
+const isSelected = createSelector(() => selectedId.value)
 
-console.log(readonly.value)  // 0
-// readonly.value = 42       // TypeScript error + runtime error
+// In a list of 1000 items:
+items.forEach(item => {
+  effect(() => {
+    // Only runs when THIS item's selection state changes!
+    if (isSelected(item.id)) {
+      highlight(item)
+    } else {
+      unhighlight(item)
+    }
+  })
+})
+
+// When selectedId changes from 1 to 2:
+// - Only item 1's effect runs (was selected, now not)
+// - Only item 2's effect runs (was not selected, now is)
+// - Other 998 items' effects DON'T run!
 ```
 
-### isBinding / unwrap
+### effectScope (Vue's lifecycle management)
+
+Create an effect scope to group effects for batch disposal with pause/resume support.
 
 ```typescript
-// Check if a value is a binding
-isBinding(maybeBinding)  // true or false
+effectScope(detached?: boolean): EffectScope
 
-// Get value from binding, signal, derived, or return plain value directly
-// Works with ALL reactive types for unified value access
-const count = signal(42)
-const doubled = derived(() => count.value * 2)
-const bound = bind(count)
+interface EffectScope {
+  readonly active: boolean
+  readonly paused: boolean
+  run<R>(fn: () => R): R | undefined
+  stop(): void
+  pause(): void
+  resume(): void
+}
+```
+
+```typescript
+const scope = effectScope()
+
+scope.run(() => {
+  effect(() => console.log(count.value))
+  effect(() => console.log(name.value))
 
-unwrap(count)     // 42 (extracts .value from signal)
-unwrap(doubled)   // 84 (extracts .value from derived)
-unwrap(bound)     // 42 (extracts .value from binding)
-unwrap('static')  // 'static' (returns plain values as-is)
+  // Register cleanup to run when scope stops
+  onScopeDispose(() => {
+    console.log('Cleaning up...')
+  })
+})
+
+// Pause execution temporarily
+scope.pause()
+count.value = 5  // Effect doesn't run
+
+// Resume and run pending updates
+scope.resume()  // Now effect runs with value 5
+
+// Later, dispose all effects at once
+scope.stop()  // Runs onScopeDispose callbacks
+```
+
+**Related utilities:**
 
-// Great for mapping mixed arrays
-const arr: (string | Binding<string>)[] = ['static', bind(signal('dynamic'))]
-arr.map(unwrap)  // ['static', 'dynamic']
+```typescript
+// Register cleanup on current scope
+onScopeDispose(() => clearInterval(timer))
+
+// Get the currently active scope
+const scope = getCurrentScope()
 ```
 
 ---
 
-## Slots (bind() on steroids)
+## Bindings & Slots
+
+### bind
+
+Create a reactive binding - a two-way pointer that forwards reads and writes to a source signal.
+
+```typescript
+bind<T>(source: WritableSignal<T> | Binding<T> | T | (() => T)): Binding<T>
+```
 
-Slots are stable reactive cells that can point to different sources. Unlike `bind()`, a Slot is never replaced - you mutate its source. This ensures deriveds ALWAYS track changes correctly.
+```typescript
+const source = signal(0)
+const binding = bind(source)
+
+// Reading through binding reads from source
+console.log(binding.value)  // 0
+
+// Writing through binding writes to source
+binding.value = 42
+console.log(source.value)  // 42
+```
+
+**Overloads:**
+- `bind(signal)` - Creates writable binding to signal
+- `bind(binding)` - Chains bindings (both point to same source)
+- `bind(value)` - Wraps raw value in a signal
+- `bind(() => expr)` - Creates read-only binding from getter
+
+```typescript
+// Read-only binding from getter
+const count = signal(5)
+const doubled = bind(() => count.value * 2)
+console.log(doubled.value)  // 10
+// doubled.value = 20  // Would throw!
+```
 
 ### slot
 
-Create a single reactive slot.
+Create a stable reactive cell that can point to different sources. Unlike `bind()`, a Slot is never replaced - you mutate its source.
 
 ```typescript
 slot<T>(initial?: T): Slot<T>
@@ -295,16 +493,12 @@ console.log(mySlot.value)  // 'hello'
 mySlot.source = 'world'
 console.log(mySlot.value)  // 'world'
 
-// Point to a signal
+// Point to a signal (two-way binding!)
 const name = signal('Alice')
 mySlot.source = name
 console.log(mySlot.value)  // 'Alice'
-name.value = 'Bob'
-console.log(mySlot.value)  // 'Bob'
-
-// Write through to signal (two-way binding!)
-mySlot.set('Charlie')
-console.log(name.value)    // 'Charlie'
+mySlot.set('Bob')          // Writes through to signal!
+console.log(name.value)    // 'Bob'
 
 // Point to a getter (read-only, auto-tracks)
 const count = signal(5)
@@ -320,7 +514,7 @@ console.log(mySlot.value)  // 'Count: 10'
 
 ### slotArray
 
-Create an array of slots for efficient reactive arrays.
+Create an array of slots for efficient reactive arrays (parallel array / ECS pattern).
 
 ```typescript
 slotArray<T>(defaultValue?: T): SlotArray<T>
@@ -343,6 +537,7 @@ const rawSlot = textContent.slot(0)
 ```
 
 **SlotArray methods:**
+
 | Method | Description |
 |--------|-------------|
 | `arr[i]` | Read value at index (auto-unwraps, auto-tracks) |
@@ -352,46 +547,77 @@ const rawSlot = textContent.slot(0)
 | `arr.ensureCapacity(n)` | Expand to at least n slots |
 | `arr.clear(i)` | Reset slot i to default |
 
-### TUI-style use case
+### trackedSlotArray
 
-Slots are designed for frameworks like TUI where:
-1. Components write sources to arrays
-2. Pipelines read from arrays reactively
-3. Two-way binding enables inputs
+Create an array of slots with automatic dirty tracking - perfect for incremental computation and ECS-style architectures.
 
 ```typescript
-// Component setup
-const count = signal(0)
-textContent.setSource(index, () => `Count: ${count.value}`)
+trackedSlotArray<T>(defaultValue?: T, dirtySet: ReactiveSet<number>): SlotArray<T>
+```
 
-// Pipeline (derived) reads automatically
-// When count changes, pipeline re-renders!
+```typescript
+const dirty = new ReactiveSet<number>()
+const positions = trackedSlotArray({ x: 0, y: 0 }, dirty)
+
+// Set source - automatically marks index as dirty
+positions.setSource(0, signal({ x: 10, y: 20 }))  // dirty.has(0) === true
+
+// setValue also marks dirty
+positions.setValue(5, { x: 100, y: 200 })  // dirty.has(5) === true
 
-// For inputs - two-way binding
-const username = signal('')
-textContent.setSource(inputIndex, username)
-// User types:
-textContent.setValue(inputIndex, 'alice')
-// username.value is now 'alice'!
+// Use dirty tracking for O(1) skips
+const layout = derived(() => {
+  if (dirty.size === 0) return cachedLayout  // Nothing changed!
+  
+  // Process only dirty indices
+  for (const index of dirty) {
+    updateLayout(index, positions[index])
+  }
+  
+  dirty.clear()
+  return computedLayout
+})
 ```
 
+**Three-level reactivity:**
+
+1. **Per-index tracking** - `dirty.has(5)` only subscribes to index 5
+2. **Size tracking** - `dirty.size` tracks count of dirty indices (perfect for "anything changed?" checks)
+3. **Version tracking** - Iterating `for (const i of dirty)` tracks structural changes
+
+**Use cases:**
+
+- **ECS systems** - Track which entities changed, skip unchanged ones
+- **Layout engines** - Recompute only components with changed properties
+- **Incremental compilation** - Track which modules changed
+- **Dirty checking** - Skip expensive computations when nothing changed
+
+**Comparison with slotArray:**
+
+| Feature | slotArray | trackedSlotArray |
+|---------|-----------|------------------|
+| Basic functionality | ✅ | ✅ |
+| Automatic dirty tracking | ❌ | ✅ |
+| O(1) skip optimization | ❌ | ✅ |
+| Drop-in replacement | - | ✅ (just add dirtySet param) |
+
 ### reactiveProps
 
 Normalize component props to a consistent reactive interface. Accepts static values, getter functions, or signals - returns an object where every property is a DerivedSignal.
 
 ```typescript
-reactiveProps<T>(rawProps: PropsInput<T>): ReactiveProps<T>
+reactiveProps<T>(rawProps: T): ReactiveProps<UnwrapPropInputs<T>>
 ```
 
 ```typescript
 interface MyComponentProps {
-  name: string
-  count: number
-  active: boolean
+  name: PropInput<string>
+  count: PropInput<number>
+  active: PropInput<boolean>
 }
 
-function MyComponent(rawProps: PropsInput<MyComponentProps>) {
-  // Convert any mix of static/getter/signal props to consistent reactive interface
+function MyComponent(rawProps: MyComponentProps) {
+  // Convert any mix of static/getter/signal props to consistent interface
   const props = reactiveProps(rawProps)
 
   // Everything is now a DerivedSignal - consistent .value access
@@ -412,147 +638,104 @@ MyComponent({ name: nameSignal, count: () => getCount(), active: activeSignal })
 | Consumer must know which props need getters | Consumer just passes values |
 | Component must handle multiple input types | Component always gets DerivedSignal |
 | Easy to forget `() =>` and get stale values | Props are always reactive |
-| Inconsistent patterns across components | One pattern everywhere |
 
 ---
 
-## Advanced Features
-
-### linkedSignal (Angular's killer feature)
+## Deep Reactivity
 
-Create a writable signal that derives from a source but can be manually overridden. When the source changes, the linked signal resets to the computed value.
+### proxy
 
-```typescript
-linkedSignal<D>(fn: () => D): WritableSignal<D>
-linkedSignal<S, D>(options: LinkedSignalOptions<S, D>): WritableSignal<D>
-```
+Create a deeply reactive proxy (used internally by `state()`).
 
 ```typescript
-// Simple form - dropdown selection
-const options = signal(['a', 'b', 'c'])
-const selected = linkedSignal(() => options.value[0])
+const obj = proxy({ a: { b: { c: 1 } } })
 
-console.log(selected.value)  // 'a'
-selected.value = 'b'         // Manual override
-console.log(selected.value)  // 'b'
+effect(() => console.log('c changed:', obj.a.b.c))
+effect(() => console.log('a changed:', obj.a))
 
-options.value = ['x', 'y']   // Source changes
-flushSync()
-console.log(selected.value)  // 'x' (reset to computed value)
+obj.a.b.c = 2  // Only triggers first effect (fine-grained!)
 ```
 
+### toRaw
+
+Get the original object from a proxy.
+
 ```typescript
-// Advanced form - keep valid selection
-const items = signal([1, 2, 3])
-const selectedItem = linkedSignal({
-  source: () => items.value,
-  computation: (newItems, prev) => {
-    // Keep selection if still valid
-    if (prev && newItems.includes(prev.value)) {
-      return prev.value
-    }
-    return newItems[0]
-  }
-})
+const raw = toRaw(user)  // Original non-reactive object
 ```
 
-**Use cases:**
-- Form inputs that reset when parent data changes
-- Selection state that persists within valid options
-- Derived values that can be temporarily overridden
-
-### createSelector (Solid's O(n) to O(2) optimization)
+### isReactive
 
-Create a selector function for efficient list selection tracking. Instead of O(n) effects re-running, only affected items run = O(2).
+Check if a value is a reactive proxy.
 
 ```typescript
-createSelector<T, U = T>(
-  source: () => T,
-  fn?: (key: U, value: T) => boolean
-): SelectorFn<T, U>
+if (isReactive(value)) {
+  console.log('This is a proxy')
+}
 ```
 
-```typescript
-const selectedId = signal(1)
-const isSelected = createSelector(() => selectedId.value)
+---
 
-// In a list of 1000 items:
-items.forEach(item => {
-  effect(() => {
-    // Only runs when THIS item's selection state changes!
-    // When selectedId changes from 1 to 2:
-    // - Only item 1's effect runs (was selected, now not)
-    // - Only item 2's effect runs (was not selected, now is)
-    // - Other 998 items' effects DON'T run
-    if (isSelected(item.id)) {
-      highlight(item)
-    } else {
-      unhighlight(item)
-    }
-  })
-})
-```
+## Utilities
 
-### effectScope (Vue's lifecycle management)
+### batch
 
-Create an effect scope to group effects for batch disposal with pause/resume support.
+Batch multiple signal updates into a single effect run. Essential for performance when doing multiple writes.
 
 ```typescript
-effectScope(detached?: boolean): EffectScope
-
-interface EffectScope {
-  readonly active: boolean
-  readonly paused: boolean
-  run<R>(fn: () => R): R | undefined
-  stop(): void
-  pause(): void
-  resume(): void
-}
-```
+const a = signal(1)
+const b = signal(2)
 
-```typescript
-const scope = effectScope()
+effect.sync(() => console.log(a.value + b.value))
 
-scope.run(() => {
-  effect(() => console.log(count.value))
-  effect(() => console.log(name.value))
+// Without batch: effect runs twice
+a.value = 10  // Effect runs
+b.value = 20  // Effect runs again
 
-  onScopeDispose(() => {
-    console.log('Cleaning up...')
-  })
+// With batch: effect runs once with final values
+batch(() => {
+  a.value = 100
+  b.value = 200
 })
+// Effect runs once: 300
+```
 
-// Pause execution temporarily
-scope.pause()
-count.value = 5  // Effect doesn't run
+### untrack / peek
 
-// Resume and run pending updates
-scope.resume()
+Read signals without creating dependencies.
 
-// Later, dispose all effects at once
-scope.stop()
+```typescript
+effect(() => {
+  const a = count.value                    // Creates dependency
+  const b = untrack(() => other.value)     // No dependency
+})
+
+// peek is an alias for untrack
+const value = peek(() => signal.value)
 ```
 
-### onScopeDispose
+### flushSync
 
-Register a cleanup function on the current scope.
+Synchronously flush all pending effects. Useful for testing and ensuring effects have run.
 
 ```typescript
-scope.run(() => {
-  const timer = setInterval(() => log('tick'), 1000)
-  onScopeDispose(() => clearInterval(timer))
+count.value = 5
+flushSync()  // Effects run NOW, not on next microtask
+
+// Can also wrap a function
+flushSync(() => {
+  count.value = 10
+  // Effects for this change run before flushSync returns
 })
 ```
 
-### getCurrentScope
+### tick
 
-Get the currently active effect scope.
+Wait for the next update cycle (async). Returns a promise that resolves after all pending effects have run.
 
 ```typescript
-const scope = getCurrentScope()
-if (scope) {
-  // Inside a scope
-}
+count.value = 5
+await tick()  // Effects have run
 ```
 
 ---
@@ -597,7 +780,7 @@ A Date with reactive getters/setters.
 const date = new ReactiveDate()
 
 effect(() => {
-  console.log(date.getHours())  // Re-runs when time changes
+  console.log(date.getHours())  // Re-runs when hours change
 })
 
 date.setHours(12)  // Triggers effect
@@ -605,128 +788,38 @@ date.setHours(12)  // Triggers effect
 
 ---
 
-## Utilities
-
-### batch
-
-Batch multiple signal updates into a single effect run.
-
-```typescript
-const a = signal(1)
-const b = signal(2)
-
-effect(() => console.log(a.value + b.value))
-
-batch(() => {
-  a.value = 10
-  b.value = 20
-})
-// Effect runs once with final values, not twice
-```
-
-### untrack / peek
-
-Read signals without creating dependencies.
-
-```typescript
-effect(() => {
-  const a = count.value                    // Creates dependency
-  const b = untrack(() => other.value)     // No dependency
-})
-
-// peek is an alias for untrack
-const value = peek(() => signal.value)
-```
-
-### flushSync
-
-Synchronously flush all pending effects.
-
-```typescript
-count.value = 5
-flushSync()  // Effects run NOW, not on next microtask
-```
-
-### tick
-
-Wait for the next update cycle (async).
-
-```typescript
-count.value = 5
-await tick()  // Effects have run
-```
-
----
-
-## Deep Reactivity
-
-### proxy
-
-Create a deeply reactive proxy (used internally by `state()`).
-
-```typescript
-const obj = proxy({ a: { b: { c: 1 } } })
-
-effect(() => console.log('c changed:', obj.a.b.c))
-effect(() => console.log('a changed:', obj.a))
-
-obj.a.b.c = 2  // Only triggers first effect (fine-grained!)
-```
-
-### toRaw
-
-Get the original object from a proxy.
-
-```typescript
-const raw = toRaw(user)  // Original non-reactive object
-```
-
-### isReactive
-
-Check if a value is a reactive proxy.
-
-```typescript
-if (isReactive(value)) {
-  console.log('This is a proxy')
-}
-```
-
----
-
 ## Equality Functions
 
 Control when signals trigger updates:
 
 ```typescript
-import { signal, derived, equals, deepEquals, safeEquals, shallowEquals, neverEquals, alwaysEquals, createEquals } from '@rlabs-inc/signals'
+import {
+  signal, derived,
+  equals,        // Object.is (default for signals)
+  deepEquals,    // Bun.deepEquals (default for derived)
+  safeEquals,    // Handles NaN correctly
+  shallowEquals, // One level deep comparison
+  neverEquals,   // Always trigger
+  alwaysEquals,  // Never trigger
+  createEquals   // Custom equality
+} from '@rlabs-inc/signals'
 
-// signal() - uses Object.is (reference equality)
+// signal() uses Object.is (reference equality)
 const a = signal(0)
 
-// derived() - uses Bun.deepEquals (structural equality) by default
-// This prevents unnecessary propagation when computed values are structurally identical
+// derived() uses Bun.deepEquals (structural equality)
+// Prevents unnecessary propagation when computed values are structurally identical
 const items = signal([1, 2, 3])
 const doubled = derived(() => items.value.map(x => x * 2))
-// If doubled produces [2, 4, 6] again, downstream effects won't re-run
 
-// Deep equality - uses Bun.deepEquals (36ns for small objects!)
+// Deep equality for signals
 const c = signal({ a: 1 }, { equals: deepEquals })
 c.value = { a: 1 }  // Won't trigger - deeply equal
 
-// Safe equality - handles NaN correctly
-const d = signal(NaN, { equals: safeEquals })
-
-// Shallow comparison - compares one level deep
-const e = signal({ a: 1 }, { equals: shallowEquals })
-
 // Always trigger updates
 const f = signal(0, { equals: neverEquals })
 f.value = 0  // Still triggers!
 
-// Never trigger updates
-const g = signal(0, { equals: alwaysEquals })
-g.value = 100  // Doesn't trigger
-
 // Custom equality
 const customEquals = createEquals((a, b) =>
   JSON.stringify(a) === JSON.stringify(b)
@@ -735,11 +828,12 @@ const h = signal([], { equals: customEquals })
 ```
 
 **Default equality by primitive:**
+
 | Primitive | Default | Reason |
 |-----------|---------|--------|
 | `signal()` | `Object.is` | User-controlled input - reference equality |
-| `derived()` | `Bun.deepEquals` | Computed output - structural equality prevents unnecessary work |
-| `linkedSignal()` | `Bun.deepEquals` | Computed output - structural equality |
+| `derived()` | `deepEquals` | Computed output - structural equality prevents unnecessary work |
+| `linkedSignal()` | `deepEquals` | Computed output - structural equality |
 
 ---
 
@@ -774,7 +868,7 @@ effect(() => {
   count.value = count.value + 1  // Always triggers itself
 })
 
-// GOOD - add a guard
+// GOOD - add a guard or use untrack
 effect(() => {
   if (count.value < 100) {
     count.value++
@@ -784,30 +878,6 @@ effect(() => {
 
 ---
 
-## Performance
-
-This library is designed for performance:
-
-| Operation | Complexity | Notes |
-|-----------|------------|-------|
-| Signal read/write | O(1) | Direct property access |
-| Derived read | O(1) | Cached after first computation |
-| Effect trigger | O(deps) | Only runs if dependencies change |
-| `batch()` | O(1) cycle | Multiple updates, single flush |
-| `createSelector()` | O(2) | Only changed items' effects run |
-| Proxy property access | O(1) | Per-property signal lookup |
-| `ReactiveMap.get()` | O(1) | Per-key tracking |
-
-**Key optimizations:**
-- **Lazy evaluation** - Deriveds only compute when read
-- **Version-based deduplication** - No duplicate dependency tracking
-- **Linked list effect tree** - O(1) effect insertion/removal
-- **Microtask batching** - Updates coalesce automatically
-- **Per-property signals** - Fine-grained updates at any depth
-- **FinalizationRegistry cleanup** - Automatic memory management
-
----
-
 ## Framework Comparison
 
 | Feature | @rlabs-inc/signals | Svelte 5 | Vue 3 | Angular | Solid.js |
@@ -815,11 +885,13 @@ This library is designed for performance:
 | `signal()` | `signal()` | `$state` | `ref()` | `signal()` | `createSignal()` |
 | `derived()` | `derived()` | `$derived` | `computed()` | `computed()` | `createMemo()` |
 | `effect()` | `effect()` | `$effect` | `watchEffect()` | `effect()` | `createEffect()` |
+| `effect.sync()` | `effect.sync()` | `$effect.pre` | - | - | - |
 | Deep reactivity | `state()` | `$state` | `reactive()` | - | - |
 | `linkedSignal()` | Yes | - | - | Yes | - |
 | `createSelector()` | Yes | - | - | - | Yes |
 | `effectScope()` | Yes | - | Yes | - | - |
 | `slot()` / `slotArray()` | Yes | - | - | - | - |
+| `reactiveProps()` | Yes | - | - | - | - |
 | Compiler required | No | Yes | No | No | No |
 | DOM integration | No | Yes | Yes | Yes | Yes |
 
@@ -851,6 +923,49 @@ set(src, 10)
 
 ---
 
+## Type Exports
+
+```typescript
+import type {
+  // Core types
+  Signal,
+  Source,
+  Reaction,
+  Derived,
+  Effect,
+  Value,
+
+  // Public API types
+  ReadableSignal,
+  WritableSignal,
+  DerivedSignal,
+  DisposeFn,
+  CleanupFn,
+  EffectFn,
+
+  // Binding types
+  Binding,
+  ReadonlyBinding,
+
+  // Slot types
+  Slot,
+  SlotArray,
+
+  // Props types
+  PropInput,
+  PropsInput,
+  ReactiveProps,
+
+  // Advanced types
+  LinkedSignalOptions,
+  SelectorFn,
+  EffectScope,
+  Equals,
+} from '@rlabs-inc/signals'
+```
+
+---
+
 ## License
 
 MIT