# Cause & Effect - Reactive State Management Primitives

## Project Type
TypeScript reactive state management primitives library using a unified signal graph

## Core Concepts
- Signals: Reactive primitives with .get() method for dependency tracking
- State: createState() for mutable source values
- Sensor: createSensor() for external input with lazy lifecycle
- Memo: createMemo() for synchronous memoized derivations
- Task: createTask() for asynchronous derivations with cancellation
- Store: createStore() for reactive objects with per-property signals
- List: createList() for reactive arrays with stable keys
- Collection: createCollection() for reactive collections (external source or derived, item-level memoization)
- Effect: createEffect() for side-effect sinks

## Code Style
- Use const for immutable values
- Generic constraints: T extends {} (excludes null/undefined)
- Factory functions: create* prefix
- Type predicates: is* prefix
- Constants: TYPE_* or UPPER_CASE
- Pure functions marked with /*#__PURE__*/ comment

## Key Patterns
- All signals have .get() method
- Mutable signals have .set(value) and .update(fn)
- Store properties auto-become reactive signals via Proxy
- Memo callbacks receive previous value as first parameter for reducer patterns
- Task callbacks receive (next, AbortSignal)
- Sensor and Collection use start callbacks for lazy resource management
- Store and List support optional watched callbacks
- batch() for grouping multiple updates
- untrack() for reading signals without creating edges

## File Structure
- src/graph.ts - Core reactive engine (nodes, edges, propagation, flush)
- src/nodes/state.ts - Mutable state signals
- src/nodes/sensor.ts - External input tracking
- src/nodes/memo.ts - Synchronous derived signals
- src/nodes/task.ts - Asynchronous derived signals
- src/nodes/effect.ts - Side-effect system
- src/nodes/store.ts - Reactive objects
- src/nodes/list.ts - Reactive arrays with stable keys
- src/nodes/collection.ts - Externally-driven and derived collections
- next.ts - Public API exports

## Error Handling
- Custom error classes in src/errors.ts
- Validate inputs with validateSignalValue() and validateCallback()
- AbortSignal integration for async cancellation in Task and Collection

## Performance
- Linked-list edges for O(1) dependency tracking
- Flag-based dirty checking (CLEAN, CHECK, DIRTY)
- Tree-shaking friendly, zero dependencies
- Minimize effect re-runs via equality checks

## Testing
- bun:test with describe/test/expect
- Test files: test/*.test.ts

## Build
- Bun build tool and runtime
- ES modules only
- TypeScript with declaration files