@zeix/cause-effect 0.15.2 → 0.16.1

package/.ai-context.md

@@ -0,0 +1,254 @@
+# 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
+
+### Signal Types
+- **Signal**: Base interface with `.get()` method for value access
+- **State**: Mutable signals for primitive values (numbers, strings, booleans)
+- **Store**: Mutable signals for objects with individually reactive properties
+- **Computed**: Read-only derived signals with automatic memoization, reducer-like capabilities and asyc handling
+- **Effect**: Side effect handlers that react to signal changes
+
+### Key Principles
+1. **Functional Programming**: Immutable by default, pure functions
+2. **Type Safety**: Full TypeScript support with strict type constraints
+3. **Performance**: Minimal re-computations through dependency tracking
+4. **Async Support**: Built-in cancellation with AbortSignal
+5. **Tree-shaking**: Optimized for minimal bundle size
+
+## Project Structure
+
+```
+cause-effect/
+├── src/
+│   ├── signal.ts      # Base signal types and utilities
+│   ├── state.ts       # Mutable state signals (createState)
+│   ├── store.ts       # Object stores with reactive properties
+│   ├── computed.ts    # Computed/derived signals (createComputed)
+│   ├── effect.ts      # Effect system (createEffect)
+│   ├── system.ts      # Core reactivity (watchers, batching, subscriptions)
+│   ├── resolve.ts     # Helper for extracting signal values
+│   ├── match.ts       # Pattern matching utility
+│   ├── diff.ts        # Object comparison utilities
+│   ├── errors.ts      # Custom error classes
+│   └── util.ts        # Utilities and constants
+├── index.ts           # Main export file
+├── types/index.d.ts   # TypeScript declarations
+└── package.json       # NPM package configuration
+```
+
+## API Patterns
+
+### Signal Creation
+```typescript
+// State signals for primitives
+const count = createState(42)
+const name = createState('Alice')
+const actions = createState<'increment' | 'decrement' | 'reset'>('reset')
+
+// Store signals for objects  
+const user = createStore({ name: 'Alice', age: 30 })
+
+// Computed signals for derived values
+const doubled = createComputed(() => count.get() * 2)
+
+// Computed with reducer-like capabilities (access to previous value)
+const counter = createComputed((prev) => {
+  const action = actions.get()
+  switch (action) {
+    case 'increment': return prev + 1
+    case 'decrement': return prev - 1
+    case 'reset': return 0
+    default: return prev
+  }
+}, 0) // Initial value
+
+// Async computed with access to previous value
+const userData = createComputed(async (prev, abort) => {
+  const id = userId.get()
+  if (!id) return prev // Keep previous data if no user ID
+  const response = await fetch(`/users/${id}`, { signal: abort })
+  return response.json()
+})
+```
+
+### Reactivity
+```typescript
+// Effects react to signal changes
+createEffect(() => {
+  console.log(`Count: ${count.get()}`)
+})
+
+// Async effects with automatic cancellation
+createEffect(async (abort) => {
+  const response = await fetch('/api', { signal: abort })
+  return response.json()
+})
+```
+
+### Value Access Patterns
+```typescript
+// All signals use .get() for value access
+const value = signal.get()
+
+// Mutable signals have .set() and .update()
+state.set(newValue)
+state.update(current => current + 1)
+
+// Store properties are individually reactive
+user.name.set("Bob")          // Only name watchers trigger
+user.age.update(age => age + 1)  // Only age watchers trigger
+```
+
+## Coding Conventions
+
+### TypeScript Style
+- Generic constraints: `T extends {}` to exclude null/undefined
+- Use `const` for immutable values
+- Function overloads for complex type scenarios
+- JSDoc comments on all public APIs
+- Pure function annotations: `/*#__PURE__*/` for tree-shaking
+
+### Naming Conventions
+- Factory functions: `create*` prefix (createState, createStore, createComputed)
+- Type predicates: `is*` prefix (isSignal, isState, isComputed)
+- Type constants: `TYPE_*` format (TYPE_STATE, TYPE_STORE, TYPE_COMPUTED)
+- Utility constants: UPPER_CASE (UNSET)
+
+### Error Handling
+- Custom error classes in `src/errors.ts`
+- Descriptive error messages with context
+- Input validation at public API boundaries
+- Use `UNSET` symbol for uninitialized/pending states
+
+## Performance Considerations
+
+### Optimization Patterns
+- Dependency tracking with `Set<Watcher>` for O(1) operations
+- Batched updates to minimize effect re-runs
+- Shallow equality checks with `isEqual()` utility
+- Memoization in computed signals prevents unnecessary recalculations
+- Tree-shaking friendly with pure function annotations
+
+### Memory Management
+- Automatic cleanup of watchers when effects are disposed
+- WeakMap usage for object-to-signal mappings where appropriate
+- AbortSignal integration for canceling async operations
+
+## Common Implementation Patterns
+
+### State Management
+```typescript
+// Simple state
+const loading = createState(false)
+const error = createState('') // Empty string means no error
+
+// Complex state with stores
+const appState = createStore({
+  user: { id: 1, name: "Alice" },
+  settings: { theme: "dark", notifications: true }
+})
+```
+
+### Derived State
+```typescript
+// Reducer-like pattern for state machines
+const appState = createComputed((currentState) => {
+  const event = events.get()
+  switch (currentState) {
+    case 'idle':
+      return event === 'start' ? 'loading' : 'idle'
+    case 'loading':
+      return event === 'success' ? 'loaded' : event === 'error' ? 'error' : 'loading'
+    case 'loaded':
+      return event === 'refresh' ? 'loading' : 'loaded'
+    case 'error':
+      return event === 'retry' ? 'loading' : 'error'
+    default:
+      return 'idle'
+  }
+}, 'idle') // Initial state
+```
+
+### Async Operations
+```typescript
+// Computed with async data fetching
+const userData = createComputed(async (oldValue, abort) => {
+  const id = userId.get()
+  if (!id) return oldValue // Retain previous data when no ID
+  const response = await fetch(`/users/${id}`, { signal: abort })
+  if (!response.ok) throw new Error('Failed to fetch user')
+  return response.json()
+})
+```
+
+### Error Handling
+```typescript
+// Handle loading/error states
+createEffect(() => {
+  match(resolve({ userData }), {
+    ok: ({ userData }) => console.log('User:', userData),
+    nil: () => console.log('Loading...'),
+    err: (errors) => console.error('Error:', errors[0])
+  })
+})
+```
+
+### Helper Functions Usage
+```typescript
+// Extract values from multiple signals
+const result = resolve({ name, age, email })
+
+// Pattern matching for discriminated unions
+match(result, {
+  ok: (values) => console.log('Success:', values),
+  nil: () => console.log('Some values pending'),
+  err: (errors) => console.error('Errors:', errors)
+})
+
+// Object diffing
+const changes = diff(oldUser, newUser)
+console.log('Changed:', changes.change)
+console.log('Added:', changes.add)
+console.log('Removed:', changes.remove)
+```
+
+## Build and Development
+
+### Tools
+- **Runtime**: Bun (also works with Node.js)
+- **Build**: Bun build with TypeScript compilation
+- **Testing**: Bun test runner
+- **Linting**: Biome for code formatting and linting
+
+### Package Configuration
+- ES modules only (`"type": "module"`)
+- Dual exports: TypeScript source and compiled JavaScript
+- Tree-shaking friendly with proper sideEffects configuration
+- TypeScript declarations generated automatically
+
+## Key Design Decisions
+
+### Why Signals?
+- Fine-grained reactivity (update only what changed)
+- Explicit dependency tracking (no hidden dependencies)
+- Composable and testable
+- Framework agnostic
+
+### Why TypeScript-First?
+- Better developer experience with autocomplete
+- Compile-time error catching
+- Self-documenting APIs
+- Better refactoring support
+
+### Why Functional Approach?
+- Predictable behavior
+- Easier testing
+- Better composition
+- Minimal API surface
+
+When working with this codebase, focus on maintaining the established patterns, ensuring type safety, and optimizing for performance while keeping the API simple and predictable.

package/.cursorrules

@@ -0,0 +1,54 @@
+# Cause & Effect - Reactive State Management Library
+
+## Project Type
+TypeScript/JavaScript reactive state management library using signals pattern
+
+## Core Concepts
+- Signals: Base reactive primitives with .get() method
+- State: createState() for primitives/simple values  
+- Store: createStore() for objects with reactive properties
+- Computed: createComputed() for derived/memoized values
+- Effects: createEffect() for side effects
+
+## 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
+- Computed callbacks receive oldValue as first parameter for reducer patterns
+- Async computed and effect callbacks receive AbortSignal for async cancellation
+- Use UNSET symbol for uninitialized states
+- Batch updates for performance
+- JSDoc comments on all public APIs
+
+## File Structure
+- src/signal.ts - Base signal types
+- src/state.ts - Mutable state signals  
+- src/store.ts - Object stores
+- src/computed.ts - Computed signals
+- src/effect.ts - Effect system
+- src/system.ts - Core reactivity (watchers, batching)
+- index.ts - Main exports
+
+## Error Handling  
+- Custom error classes in src/errors.ts
+- Validate inputs, throw descriptive errors
+- Support AbortSignal in async operations
+
+## Performance
+- Use Set<Watcher> for subscriptions
+- Shallow equality with isEqual() utility
+- Tree-shaking friendly code
+- Minimize effect re-runs
+
+## Build
+- Bun build tool and runtime
+- ES modules only
+- TypeScript with declaration files

package/.github/copilot-instructions.md

@@ -0,0 +1,132 @@
+# Copilot Instructions for Cause & Effect
+
+## Project Overview
+
+Cause & Effect is a reactive state management library for JavaScript/TypeScript that provides signals-based reactivity. The library is built with modern JavaScript/TypeScript and follows functional programming principles with a focus on performance and type safety.
+
+## Core Architecture
+
+- **Signals**: Base reactive primitives with `.get()` method
+- **State**: Mutable signals for primitive values (`createState()`)
+- **Store**: Mutable signals for objects with reactive properties (`createStore()`)
+- **Computed**: Derived read-only signals with memoization, reducer-like capabilities and async support (`createComputed()`)
+- **Effects**: Side effect handlers that react to signal changes (`createEffect()`)
+
+## Key Files Structure
+
+- `src/signal.ts` - Base signal types and utilities
+- `src/state.ts` - Mutable state signals
+- `src/store.ts` - Object stores with reactive properties
+- `src/computed.ts` - Computed/derived signals
+- `src/effect.ts` - Effect system
+- `src/system.ts` - Core reactivity system (watchers, batching)
+- `src/util.ts` - Utility functions and constants
+- `index.ts` - Main export file
+
+## Coding Conventions
+
+### TypeScript Style
+- Use `const` for immutable values, prefer immutability
+- Generic constraints: `T extends {}` to exclude nullish values
+- Function overloads for complex type inference
+- Pure functions marked with `/*#__PURE__*/` for tree-shaking
+- JSDoc comments for all public APIs
+
+### Naming Conventions
+- Factory functions: `create*` (e.g., `createState`, `createStore`)
+- Type predicates: `is*` (e.g., `isSignal`, `isState`)
+- Constants: `TYPE_*` for type tags, `UPPER_CASE` for values
+- Private variables: use descriptive names, no underscore prefix
+
+### Error Handling
+- Custom error classes in `src/errors.ts`
+- Validate inputs and throw descriptive errors
+- Use `UNSET` symbol for uninitialized/pending states
+- Support AbortSignal for cancellation in async operations
+
+### Performance Patterns
+- Use `Set<Watcher>` for efficient subscription management
+- Batch updates to minimize effect re-runs
+- Memoization in computed signals
+- Shallow equality checks with `isEqual()` utility
+- Tree-shaking friendly with pure function annotations
+
+### API Design Principles
+- All signals have `.get()` method for value access
+- Mutable signals have `.set(value)` and `.update(fn)` methods
+- Store properties are automatically reactive signals
+- Effects receive AbortSignal for async cancellation
+- Helper functions like `resolve()`, `match()`, `diff()` for ergonomics
+
+### Testing Patterns
+- Use Bun test runner
+- Test reactivity chains and dependency tracking
+- Test async cancellation behavior
+- Test error conditions and edge cases
+
+## Common Code Patterns
+
+### Creating Signals
+```typescript
+// State for primitives
+const count = createState(42)
+const name = createState('Alice')
+const actions = createState<'increment' | 'decrement'>('increment')
+
+// Store for objects
+const user = createStore({ name: 'Alice', age: 30 })
+
+// Computed for derived values
+const doubled = createComputed(() => count.get() * 2)
+
+// Computed with reducer-like capabilities
+const counter = createComputed((prev) => {
+  const action = actions.get()
+  return action === 'increment' ? prev + 1 : prev - 1
+}, 0) // Initial value
+```
+
+### Reactivity
+```typescript
+// Effects run when dependencies change
+createEffect(() => {
+  console.log(`Count is ${count.get()}`)
+})
+
+// Async effects with cancellation
+createEffect(async (abort) => {
+  const response = await fetch('/api', { signal: abort })
+  return response.json()
+})
+
+// Async computed with old value access
+const userData = createComputed(async (prev, abort) => {
+  if (!userId.get()) return prev // Keep previous data if no user
+  const response = await fetch(`/users/${userId.get()}`, { signal: abort })
+  return response.json()
+})
+```
+
+### Type Safety
+```typescript
+// Use proper generic constraints
+function createSignal<T extends {}>(value: T): Signal<T>
+
+// Type predicates for runtime checks
+function isSignal<T extends {}>(value: unknown): value is Signal<T>
+```
+
+## Build System
+- Uses Bun as build tool and runtime
+- TypeScript compilation with declaration files
+- Minified production build
+- ES modules only (`"type": "module"`)
+
+## When suggesting code:
+1. Follow the established patterns for signal creation and usage
+2. Use proper TypeScript types and generics
+3. Include JSDoc for public APIs
+4. Consider performance implications
+5. Handle errors appropriately
+6. Support async operations with AbortSignal when relevant
+7. Use the established utility functions (`UNSET`, `isEqual`, etc.)