@zeix/cause-effect 0.17.3 → 0.18.0

package/COLLECTION_REFACTORING.md

@@ -0,0 +1,161 @@
+# Collection Refactoring Plan
+
+## Goal
+
+Unify `createCollection()` and `createSourceCollection()` into a single `createCollection()` primitive whose primary form mirrors `createSensor()`: an externally-driven signal with a watched lifecycle. The derived-from-List/Collection form becomes an internal helper used by `.deriveCollection()`.
+
+## Motivation
+
+- **Sensor ↔ Collection parallel**: Both are externally-driven, lazily activated, and auto-cleaned. Making their signatures parallel sharpens this mental model.
+- **One primitive, one name**: Users learn `createCollection(start, options)` the same way they learn `createSensor(start, options)`.
+- **Derived collections are a method, not a standalone call**: `list.deriveCollection(fn)` and `collection.deriveCollection(fn)` already exist and are the natural way to create derived collections.
+
+## New API Surface
+
+```typescript
+// Primary form — externally driven (replaces createSourceCollection)
+function createCollection<T extends {}>(
+  start: CollectionCallback<T>,
+  options?: CollectionOptions<T>,
+): Collection<T>
+
+// CollectionCallback mirrors SensorCallback but receives applyChanges
+type CollectionCallback<T extends {}> = (
+  applyChanges: (changes: DiffResult) => void,
+) => Cleanup
+
+// CollectionOptions — initial value hidden in options (like Memo, Task, Sensor)
+type CollectionOptions<T extends {}> = {
+  value?: T[]                                      // initial items (default: [])
+  keyConfig?: KeyConfig<T>                         // key generation strategy
+  createItem?: (key: string, value: T) => Signal<T> // custom item factory
+}
+
+// Derive method — unchanged on List and Collection
+collection.deriveCollection(callback)
+list.deriveCollection(callback)
+```
+
+## Refactoring Steps
+
+Order matters: the existing `createCollection` and `CollectionCallback` names must be freed up before they can be reused for the new concept. The refactoring proceeds in two phases.
+
+### Phase 1 — Rename existing symbols (free the names)
+
+#### 1.1. Rename `createCollection` → `deriveCollection`
+
+In `src/nodes/collection.ts`:
+
+- Rename the function `createCollection(source, callback)` → `deriveCollection(source, callback)`.
+- Update both overload signatures and the implementation signature.
+- Update the internal `deriveCollection()` call inside the `Collection.deriveCollection` method body (both in the derived-collection object and the source-collection object).
+
+#### 1.2. Rename `CollectionCallback<T, U>` → `DeriveCollectionCallback<T, U>`
+
+- Rename the type alias in `src/nodes/collection.ts`.
+- Update all references: the `deriveCollection` parameter types, and the `Collection.deriveCollection` method parameter type annotations.
+
+#### 1.3. Update `list.ts`
+
+- Change the import from `createCollection` to `deriveCollection`.
+- Update `List.deriveCollection()` body to call `deriveCollection(list, cb)`.
+
+#### 1.4. Update exports in `index.ts`
+
+- Replace `createCollection` → `deriveCollection` in the export list.
+- Replace `CollectionCallback` → `DeriveCollectionCallback`.
+- Keep or drop `CollectionSource` from public exports (internal detail of `deriveCollection`).
+
+#### 1.5. Update tests
+
+- In `test/collection.test.ts` (or `test/collection.next.test.ts`): replace all direct `createCollection(source, cb)` calls with either `deriveCollection(source, cb)` or the equivalent `.deriveCollection(cb)` method.
+- Update imports accordingly.
+
+#### 1.6. Verify
+
+- `bun run check` and `bun test` pass.
+- Commit: "Rename createCollection → deriveCollection, CollectionCallback → DeriveCollectionCallback"
+
+### Phase 2 — Reshape `createSourceCollection` → `createCollection`
+
+#### 2.1. Rename and reshape function
+
+In `src/nodes/collection.ts`:
+
+- Rename `createSourceCollection` → `createCollection`.
+- Move `initialValue` from first positional arg into `options.value` (default `[]`).
+- New signature: `createCollection<T>(start: CollectionCallback<T>, options?: CollectionOptions<T>)`.
+
+#### 2.2. Rename types
+
+- `SourceCollectionCallback` → `CollectionCallback<T>` (generic over `T` for type coherence with `CollectionOptions<T>`, even though the callback itself doesn't use `T` directly).
+- `SourceCollectionOptions<T>` → `CollectionOptions<T>`, adding the `value?: T[]` field.
+
+#### 2.3. Update exports in `index.ts`
+
+```typescript
+// Remove
+export { createSourceCollection, SourceCollectionCallback, SourceCollectionOptions, CollectionSource }
+
+// Add / rename
+export { createCollection, CollectionCallback, CollectionOptions }
+
+// Keep
+export { Collection, DiffResult, isCollection }
+
+// Optional (if deriveCollection is exported)
+export { deriveCollection, DeriveCollectionCallback }
+```
+
+#### 2.4. Update tests
+
+- `test/source-collection.test.ts` → rename to `test/collection.next.test.ts` (or merge into existing collection test file).
+- Update all `createSourceCollection(initialValue, start, options)` calls to `createCollection(start, { value: initialValue, ...options })`.
+- Update type imports: `CollectionCallback` instead of `SourceCollectionCallback`, etc.
+
+#### 2.5. Update CLAUDE.md and docs
+
+- Update the Collection section to present `createCollection(start, options)` as the primary form.
+- Show `.deriveCollection()` as the way to transform Lists/Collections.
+- Emphasize Sensor ↔ Collection parallel in the mental model section.
+
+#### 2.6. Verify
+
+- `bun run check` and `bun test` pass.
+- Commit: "Reshape createSourceCollection → createCollection(start, options)"
+
+## Type Summary
+
+```
+Before                              After
+─────────────────────────────────   ─────────────────────────────────
+createSourceCollection(init, start, opts)  →  createCollection(start, opts)
+  SourceCollectionCallback          →  CollectionCallback<T>
+  SourceCollectionOptions<T>        →  CollectionOptions<T>
+
+createCollection(source, callback)  →  deriveCollection(source, callback)  [internal]
+  CollectionCallback<T, U>          →  DeriveCollectionCallback<T, U>      [internal or optional export]
+  CollectionSource<T>               →  CollectionSource<T>                 [internal]
+```
+
+## Migration Checklist
+
+### Phase 1 — Free the names
+- [ ] Rename `createCollection(source, cb)` → `deriveCollection(source, cb)`
+- [ ] Rename type `CollectionCallback<T, U>` → `DeriveCollectionCallback<T, U>`
+- [ ] Update `List.deriveCollection()` and `Collection.deriveCollection()` to call `deriveCollection()`
+- [ ] Update `index.ts` exports (phase 1)
+- [ ] Update tests (phase 1)
+- [ ] Verify: `bun run check` and `bun test` pass
+- [ ] Commit phase 1
+
+### Phase 2 — Reclaim the names
+- [ ] Rename `createSourceCollection` → `createCollection(start, options)` with `options.value`
+- [ ] Rename type `SourceCollectionCallback` → `CollectionCallback<T>`
+- [ ] Rename type `SourceCollectionOptions` → `CollectionOptions` (add `value?: T[]`)
+- [ ] Drop `CollectionSource` from public exports
+- [ ] Update `index.ts` exports (phase 2)
+- [ ] Update tests (phase 2)
+- [ ] Update CLAUDE.md Collection sections
+- [ ] Verify: `bun run check` and `bun test` pass
+- [ ] Commit phase 2

package/GUIDE.md

@@ -0,0 +1,298 @@
+# Guide for Framework Developers
+
+If you've used React, Vue, or Angular, you already understand the core idea behind Cause & Effect: state changes should automatically propagate to derived values and side effects. This guide maps what you know to how this library works, explains where the mental model diverges, and introduces capabilities that go beyond what most reactive libraries provide.
+
+## The Familiar Core
+
+The three building blocks map directly to what you already use:
+
+| Concept | React | Vue | Angular | Cause & Effect |
+|---------|-------|-----|---------|----------------|
+| Mutable state | `useState` | `ref()` | `signal()` | `createState()` |
+| Derived value | `useMemo` | `computed()` | `computed()` | `createMemo()` |
+| Side effect | `useEffect` | `watchEffect()` | `effect()` | `createEffect()` |
+
+Here is how they work together:
+
+```ts
+import { createState, createMemo, createEffect } from '@zeix/cause-effect'
+
+const count = createState(0)
+const doubled = createMemo(() => count.get() * 2)
+
+createEffect(() => {
+  console.log(`${count.get()} doubled is ${doubled.get()}`)
+})
+
+count.set(5) // logs: "5 doubled is 10"
+```
+
+If you've written a `computed` in Vue or a `useMemo` in React, this should feel immediately familiar. The difference is that there is no component, no template, no JSX — just reactive primitives composing directly.
+
+## What Works Differently
+
+### Dependencies are tracked, not declared
+
+In React, you declare dependencies manually:
+
+```ts
+// React
+useEffect(() => {
+  console.log(count)
+}, [count]) // ← you must list dependencies
+```
+
+In Cause & Effect, calling `.get()` *is* the dependency declaration. If you read a signal inside an effect or memo, it becomes a dependency automatically. If you don't read it, it doesn't.
+
+```ts
+// Cause & Effect
+createEffect(() => {
+  console.log(count.get()) // ← this IS the dependency
+})
+```
+
+There are no dependency arrays to maintain, no lint rules to enforce them, and no stale closure bugs from forgetting a dependency. Vue and Angular developers will find this familiar — it works like `watchEffect()` and Angular's `effect()`.
+
+### Effects run synchronously
+
+In React, effects run after the browser paints. In Vue, reactive updates are batched until the next microtask. In Cause & Effect, effects run synchronously right after a state change:
+
+```ts
+const name = createState('Alice')
+
+createEffect(() => {
+  console.log(name.get()) // runs immediately with "Alice"
+})
+
+name.set('Bob') // runs the effect again, right here, synchronously
+```
+
+When you need to update multiple signals without triggering intermediate effects, wrap updates in `batch()`:
+
+```ts
+import { batch } from '@zeix/cause-effect'
+
+batch(() => {
+  firstName.set('Bob')
+  lastName.set('Smith')
+}) // effect runs once, after both updates
+```
+
+### Non-nullable signals
+
+All signals enforce `T extends {}` — `null` and `undefined` are excluded at the type level. This means you can trust that `.get()` always returns a real value without null checks.
+
+```ts
+const count = createState(0)
+count.get() // type is number, guaranteed non-null
+
+// This won't compile:
+// const maybeUser = createState<User | null>(null)
+```
+
+This is a deliberate design decision. In frameworks, nullable state leads to defensive checks scattered across templates and hooks. Here, the type system prevents it.
+
+**What to do instead:**
+
+- For async results: use `createTask()` — a Task without reactive dependencies works like a Promise that resolves into the graph. Use `match()` to handle the pending state.
+- For external input that starts undefined: use `createSensor()` with its lazy start callback.
+- For optional state: use a discriminated union, an empty string, an empty array, `0`, or `false` — whatever the zero value for your type is:
+
+```ts
+type AuthState = { status: 'anonymous' } | { status: 'authenticated', user: User }
+const auth = createState<AuthState>({ status: 'anonymous' })
+```
+
+### Scopes replace the component tree
+
+In React, Vue, and Angular, reactivity is tied to components. Effects clean up when components unmount. Components form a tree that manages lifetimes.
+
+Cause & Effect has no components — but it has `createScope()`, which serves the same structural purpose. A scope captures child effects, manages their cleanup, and can be nested inside other scopes or effects:
+
+```ts
+import { createState, createEffect, createScope } from '@zeix/cause-effect'
+
+const dispose = createScope(() => {
+  const count = createState(0)
+
+  createEffect(() => {
+    console.log(count.get())
+  })
+
+  return () => console.log('scope disposed')
+})
+
+// Later: dispose everything created inside
+dispose()
+```
+
+Think of scopes as **components without rendering**. They are the building block for breaking the signal graph into smaller, manageable pieces — often driven by what needs to be looped or dynamically created. A UI framework built on this library would typically create a scope per component.
+
+**Automatic vs. manual cleanup:**
+
+- Inside a scope or parent effect, child effects are disposed automatically when the parent is disposed.
+- Outside any owner, you must call the cleanup function returned by `createEffect()` yourself.
+
+```ts
+// Automatic: effect is disposed when the scope is disposed
+const dispose = createScope(() => {
+  createEffect(() => console.log(count.get()))
+})
+dispose() // cleans up the effect
+
+// Manual: no parent scope, you manage the lifetime
+const cleanup = createEffect(() => console.log(count.get()))
+cleanup() // you must call this yourself
+```
+
+### Explicit equality, not reference identity
+
+By default, signals use `===` for equality. But unlike frameworks where this is buried in internals, you can override it per signal:
+
+```ts
+const point = createState({ x: 0, y: 0 }, {
+  equals: (a, b) => a.x === b.x && a.y === b.y
+})
+
+point.set({ x: 0, y: 0 }) // no update — values are equal
+```
+
+## Beyond the Basics
+
+The primitives above cover what most reactive libraries provide. The following signal types address patterns that frameworks handle with ad-hoc solutions or external libraries.
+
+### Task: async derivations with cancellation
+
+In React, async data fetching requires `useEffect` + cleanup + state management (or a library like React Query). In Angular, you'd use RxJS with `switchMap`. In Cause & Effect, `createTask()` is a signal that happens to be async:
+
+```ts
+import { createState, createTask, createEffect, match } from '@zeix/cause-effect'
+
+const userId = createState(1)
+
+const user = createTask(async (prev, abort) => {
+  const res = await fetch(`/api/users/${userId.get()}`, { signal: abort })
+  return res.json()
+})
+
+userId.set(2) // cancels the in-flight request, starts a new one
+```
+
+The `abort` signal is managed automatically — when dependencies change, the previous computation is cancelled. No cleanup functions to write, no race conditions to handle.
+
+Use `match()` inside effects to handle all states declaratively:
+
+```ts
+createEffect(() => {
+  match([user], {
+    ok: ([data]) => console.log('User:', data),
+    nil: () => console.log('Loading...'),
+    err: (errors) => console.error(errors[0])
+  })
+})
+```
+
+### Store: per-property reactivity
+
+In React, updating one property of an object re-renders everything that reads the object. In Vue, `reactive()` gives you per-property tracking — `createStore()` works the same way:
+
+```ts
+import { createStore, createEffect } from '@zeix/cause-effect'
+
+const user = createStore({ name: 'Alice', age: 30, email: 'alice@example.com' })
+
+// This effect only re-runs when name changes
+createEffect(() => {
+  console.log(user.name.get())
+})
+
+user.age.set(31)  // does NOT trigger the effect above
+user.name.set('Bob') // triggers it
+```
+
+Each property becomes its own signal. Nested objects become nested stores. This is more granular than `createState({ ... })`, which would treat the whole object as a single value.
+
+### List: reactive arrays with stable keys
+
+Frameworks use `key` props (React), `:key` bindings (Vue), or `track` expressions (Angular) to maintain item identity during re-renders. In Cause & Effect, `createList()` bakes stable keys into the data structure itself:
+
+```ts
+import { createList, createEffect } from '@zeix/cause-effect'
+
+const todos = createList([
+  { id: 't1', text: 'Learn signals', done: false },
+  { id: 't2', text: 'Build app', done: false }
+], { keyConfig: todo => todo.id })
+
+// Get a stable reference to a specific item
+const first = todos.byKey('t1')
+
+todos.sort((a, b) => a.text.localeCompare(b.text))
+// first still points to "Learn signals", regardless of position
+
+// Update a single item without replacing the array
+first?.set({ id: 't1', text: 'Learn signals', done: true })
+```
+
+Each item is its own signal. Sorting reorders keys without destroying signals or their downstream dependencies. Adding and removing items is granular — unaffected items and their effects don't re-run.
+
+### Collection: derived arrays with item-level memoization
+
+Collections provide reactive transformations over arrays with automatic per-item memoization. They come in two forms: **derived collections** (transformations of Lists or other Collections) and **externally-driven collections** (fed by external sources like WebSockets or Server-Sent Events).
+
+**Derived collections** are created via `.deriveCollection()` on a List or Collection:
+
+```ts
+const display = todos.deriveCollection(todo => ({
+  label: todo.done ? `[x] ${todo.text}` : `[ ] ${todo.text}`
+}))
+
+// Async transformations with automatic cancellation
+const enriched = todos.deriveCollection(async (todo, abort) => {
+  const res = await fetch(`/api/details/${todo.id}`, { signal: abort })
+  return { ...todo, details: await res.json() }
+})
+
+// Chain collections for data pipelines
+const pipeline = todos
+  .deriveCollection(todo => ({ ...todo, urgent: todo.priority > 8 }))
+  .deriveCollection(todo => todo.urgent ? `URGENT: ${todo.text}` : todo.text)
+```
+
+When one item changes, only its derived signal recomputes. Structural changes (additions, removals) are tracked separately from value changes.
+
+**Externally-driven collections** are created with `createCollection()` and a start callback for keyed data arriving from external sources:
+
+```ts
+import { createCollection, createEffect } from '@zeix/cause-effect'
+
+const messages = createCollection((applyChanges) => {
+  const ws = new WebSocket('/messages')
+  ws.onmessage = (e) => applyChanges({ changed: true, add: JSON.parse(e.data) })
+  return () => ws.close()
+}, { keyConfig: msg => msg.id })
+
+// Same Collection interface — .get(), .byKey(), .deriveCollection()
+createEffect(() => {
+  console.log('Messages:', messages.get().length)
+})
+```
+
+The WebSocket connects when the first effect reads the collection and disconnects when no effects are watching. Incoming data is applied as granular add/change/remove operations, not wholesale array replacement.
+
+### Sensor: lazy external input
+
+Frameworks typically manage event listeners inside component lifecycle hooks (`useEffect`, `onMounted`, `ngOnInit`). In Cause & Effect, `createSensor()` encapsulates external input with automatic resource management:
+
+```ts
+import { createSensor, createEffect } from '@zeix/cause-effect'
+
+const windowSize = createSensor((set) => {
+  const update = () => set({ w: innerWidth, h: innerHeight })
+  update()
+  window.addEventListener('resize', update)
+  return () => window.removeEventListener('resize', update)
+})
+```
+
+The start callback runs lazily — only when an effect first reads the sensor. When no effects are watching, the cleanup runs automatically. When an effect reads it again, the start callback runs again. No manual setup/teardown.