@zeix/cause-effect 1.0.0 → 1.0.2

package/skills/cause-effect/references/api-facts.md

@@ -0,0 +1,179 @@
+<overview>
+Key API constraints, defaults, and callback patterns for @zeix/cause-effect. All knowledge is
+self-contained — no library source files required. Read this when writing or reviewing any
+code that uses the public API.
+</overview>
+
+<type_constraint>
+**`T extends {}`** — all signal generics exclude `null` and `undefined` at the type level.
+This is intentional: signals always have a value; absence must be modelled explicitly.
+
+```typescript
+// Wrong — TypeScript will reject this
+const count = createState<number | null>(null)
+
+// Correct — use a sentinel or a wrapper type
+const count = createState<number>(0)
+const selected = createState<{ id: string } | { id: never }>({ id: '' })
+```
+</type_constraint>
+
+<core_functions>
+**`createScope(fn)`**
+- Returns a single `Cleanup` function
+- `fn` receives no arguments and may return an optional cleanup
+- Use to group effects and control their shared lifetime
+
+```typescript
+const dispose = createScope(() => {
+  createEffect(() => console.log(count.get()))
+  // all effects inside are disposed when dispose() is called
+})
+dispose() // cleans up everything inside
+```
+
+**`createEffect(fn)`**
+- Returns a `Cleanup` function
+- **Must be called inside an owner** (a `createScope` callback or another `createEffect` callback)
+- Throws `RequiredOwnerError` if called without an active owner
+- Runs `fn` immediately, then re-runs whenever tracked dependencies change
+
+**`batch(fn)`**
+- Defers the reactive flush until `fn` returns
+- Multiple state writes inside `fn` coalesce into a single propagation pass
+- Use when updating several signals that feed the same downstream computation
+
+```typescript
+batch(() => {
+  x.set(1)
+  y.set(2)
+  z.set(3)
+  // only one propagation pass runs after all three writes
+})
+```
+
+**`untrack(fn)`**
+- Runs `fn` without recording dependency edges
+- Reads inside `fn` do not subscribe the current computation to those signals
+- Use to read a signal's current value without creating a reactive dependency
+
+```typescript
+createEffect(() => {
+  const a = reactive.get()           // tracked — effect re-runs when reactive changes
+  const b = untrack(() => other.get()) // untracked — no dependency on other
+  render(a, b)
+})
+```
+
+**`unown(fn)`**
+- Runs `fn` without registering cleanups in the current owner
+- Use in `connectedCallback` and similar DOM lifecycle methods where the DOM —
+  not the reactive graph — manages the element's lifetime
+
+```typescript
+connectedCallback() {
+  // cleanup is tied to disconnectedCallback, not to a reactive owner
+  this.#cleanup = unown(() => createEffect(() => this.render()))
+}
+disconnectedCallback() {
+  this.#cleanup?.()
+}
+```
+</core_functions>
+
+<options>
+**`equals`**
+- Available on `createState`, `createSensor`, `createMemo`, `createTask`
+- Default: strict equality (`===`)
+- When a new value is considered equal to the previous one, propagation stops —
+  downstream nodes are not re-run
+- **`SKIP_EQUALITY`** — special sentinel value for `equals`; forces propagation on every
+  update regardless of value. Use with mutable-reference sensors where the object
+  reference never changes but the contents do:
+
+```typescript
+import { createSensor, SKIP_EQUALITY } from '@zeix/cause-effect'
+
+const mouse = 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)
+  },
+  { equals: SKIP_EQUALITY } // new object every time, so skip reference equality
+)
+```
+
+**`guard`**
+- Available on `createState`, `createSensor`
+- A predicate `(value: unknown) => value is T`
+- Throws `InvalidSignalValueError` if a set value fails the predicate
+- Use to enforce runtime type safety at signal boundaries
+
+```typescript
+const age = createState(0, {
+  guard: (v): v is number => typeof v === 'number' && v >= 0,
+})
+```
+</options>
+
+<callback_patterns>
+**Memo and Task callbacks receive `prev`**
+- Signature: `(prev: T) => T` for Memo; `(prev: T, signal: AbortSignal) => Promise<T>` for Task
+- `prev` is the previous computed value, enabling reducer-style patterns without external state:
+
+```typescript
+const runningTotal = createMemo((prev: number) => prev + newValue.get())
+```
+
+**Task carries an `AbortSignal`**
+- The second argument to the Task callback is an `AbortSignal`
+- The signal is aborted when dependencies change before the previous async run completes
+- Always forward it to any `fetch` or cancellable async operation:
+
+```typescript
+const results = createTask(async (prev, signal) => {
+  const res = await fetch(`/api/search?q=${query.get()}`, { signal })
+  return res.json()
+})
+```
+
+**`Slot` is a property descriptor**
+- Has `get`, `set`, `configurable`, `enumerable` fields
+- Can be passed directly to `Object.defineProperty()`:
+
+```typescript
+const nameSlot = createSlot(store, 'name')
+Object.defineProperty(element, 'name', nameSlot)
+```
+</callback_patterns>
+
+<match_helper>
+`match` reads one or more Sensor/Task signals and routes to `ok` or `nil` based on whether
+all signals have a value. Use it to safely handle the unset state without try/catch:
+
+```typescript
+import { match } from '@zeix/cause-effect'
+
+createEffect(() => {
+  match([task, sensor], {
+    ok:  ([taskResult, sensorValue]) => render(taskResult, sensorValue),
+    nil: () => showSpinner(),
+  })
+})
+```
+
+Read signals you care about eagerly inside `match`'s array — not inside individual branches.
+See `non-obvious-behaviors.md → conditional-reads-delay-watched` for why.
+</match_helper>
+
+<lifecycle_summary>
+| Function | Requires owner? | Returns | Reactive? |
+|---|---|---|---|
+| `createScope(fn)` | No | `Cleanup` | No (fn runs once) |
+| `createEffect(fn)` | **Yes** | `Cleanup` | Yes — re-runs on dependency change |
+| `createMemo(fn)` | No | `Memo<T>` | Lazy — recomputes on read if stale |
+| `createTask(fn)` | No | `Task<T>` | Yes — re-runs async on dependency change |
+| `createState(value)` | No | `State<T>` | Source — never recomputes |
+| `createSensor(setup)` | No | `Sensor<T>` | Source — set by external callback |
+</lifecycle_summary>

package/skills/cause-effect/references/error-classes.md

@@ -0,0 +1,153 @@
+<overview>
+Error classes thrown by @zeix/cause-effect and the conditions that trigger them. All knowledge
+is self-contained — no library source files required. Read this when writing error-handling
+code, testing error conditions, or diagnosing an unexpected throw.
+</overview>
+
+<import>
+All error classes are exported from the package root:
+
+```typescript
+import {
+  NullishSignalValueError,
+  InvalidSignalValueError,
+  InvalidCallbackError,
+  DuplicateKeyError,
+  UnsetSignalValueError,
+  ReadonlySignalError,
+  RequiredOwnerError,
+  CircularDependencyError,
+} from '@zeix/cause-effect'
+```
+</import>
+
+<error_table>
+| Class | When thrown |
+|---|---|
+| `NullishSignalValueError` | Signal value is `null` or `undefined` |
+| `InvalidSignalValueError` | Value fails the `guard` predicate |
+| `InvalidCallbackError` | A required callback argument is not a function |
+| `DuplicateKeyError` | List/Collection key collision on insert |
+| `UnsetSignalValueError` | Reading a Sensor or Task before it has produced its first value |
+| `ReadonlySignalError` | Attempting to write to a read-only signal |
+| `RequiredOwnerError` | `createEffect` called outside an owner (scope or parent effect) |
+| `CircularDependencyError` | A cycle is detected in the reactive graph |
+</error_table>
+
+<error_details>
+
+<NullishSignalValueError>
+Thrown when a signal's value is `null` or `undefined`. Because all signal generics use
+`T extends {}`, nullish values are excluded by design — this error surfaces the constraint
+at runtime if type safety is bypassed (e.g. via a type assertion or untyped interop).
+
+**Prevention:** model absence explicitly with a sentinel value or wrapper type instead of `null`.
+</NullishSignalValueError>
+
+<InvalidSignalValueError>
+Thrown when a value passed to `.set()` fails the `guard` predicate supplied in the signal's
+options. This is the runtime enforcement of custom type narrowing at signal boundaries.
+
+```typescript
+import { createState, InvalidSignalValueError } from '@zeix/cause-effect'
+
+const age = createState(0, {
+  guard: (v): v is number => typeof v === 'number' && v >= 0,
+})
+
+age.set(-1) // throws InvalidSignalValueError
+```
+</InvalidSignalValueError>
+
+<InvalidCallbackError>
+Thrown when a required callback argument — such as the computation function passed to
+`createMemo`, `createTask`, or `createEffect` — is not a function. Catches programming
+errors like passing `undefined` or a non-function value by mistake.
+</InvalidCallbackError>
+
+<DuplicateKeyError>
+Thrown when inserting an item into a List or Collection whose key already exists. Keys must
+be unique within a given List or Collection.
+
+**Fix:** use the collection's update or set method to change an existing entry rather than
+inserting a new one with the same key.
+</DuplicateKeyError>
+
+<UnsetSignalValueError>
+Thrown when `.get()` is called on a Sensor or Task before it has emitted its first value.
+Unlike State, Sensor and Task start in an explicitly unset state with no initial value.
+
+**Fix:** use `match` to handle the unset state (`nil` branch) instead of calling `.get()`
+directly:
+
+```typescript
+import { match } from '@zeix/cause-effect'
+
+createEffect(() => {
+  match([sensor, task], {
+    ok:  ([s, t]) => render(s, t),
+    nil: () => showSpinner(),
+  })
+})
+```
+</UnsetSignalValueError>
+
+<ReadonlySignalError>
+Thrown when code attempts to call `.set()` on a read-only signal. Derived signals (Memo,
+Task) are inherently read-only. Certain factory options may also produce read-only State
+or Sensor instances.
+
+**Fix:** only write to signals you own (State, Sensor via the internal setter callback).
+</ReadonlySignalError>
+
+<RequiredOwnerError>
+Thrown when `createEffect` is called without an active owner in the current execution context.
+Effects must be created inside a `createScope` callback or inside another `createEffect`
+callback so their cleanup can be registered and managed.
+
+```typescript
+import { createEffect, createScope } from '@zeix/cause-effect'
+
+// Wrong — no active owner
+createEffect(() => console.log('runs'))  // throws RequiredOwnerError
+
+// Correct — wrapped in a scope
+const dispose = createScope(() => {
+  createEffect(() => console.log('runs'))
+})
+```
+
+**Exception:** use `unown` when the DOM manages the element's lifetime (e.g. inside
+`connectedCallback`/`disconnectedCallback`) and you intentionally want to bypass owner
+registration.
+</RequiredOwnerError>
+
+<CircularDependencyError>
+Thrown when the graph engine detects a cycle during propagation — a signal that, directly
+or transitively, depends on itself. Cycles make it impossible to determine a stable
+evaluation order and are always a programming error.
+
+**Common causes:**
+- A Memo or Task that writes to a State it also reads
+- Two Memos that read each other
+
+**Fix:** restructure the data flow so that values move in one direction only.
+</CircularDependencyError>
+
+</error_details>
+
+<testing_error_conditions>
+Use `expect(() => ...).toThrow(ErrorClass)` to assert that a specific error is thrown.
+Import the error class from the package root:
+
+```typescript
+import { createState, InvalidSignalValueError } from '@zeix/cause-effect'
+
+test('rejects negative age', () => {
+  const age = createState(0, {
+    guard: (v): v is number => typeof v === 'number' && v >= 0,
+  })
+  expect(() => age.set(-1)).toThrow(InvalidSignalValueError)
+})
+```
+</testing_error_conditions>

package/skills/cause-effect/references/non-obvious-behaviors.md

@@ -0,0 +1,195 @@
+<overview>
+Counterintuitive behaviors in @zeix/cause-effect that commonly cause bugs or confusion.
+All knowledge is self-contained — no library source files required. Read this when debugging
+unexpected reactive behavior, or when writing code that involves collections, conditional
+reads, async operations, or ownership.
+</overview>
+
+<direct_lookups_do_not_track>
+**`byKey()`, `at()`, `keyAt()`, and `indexOfKey()` do not create graph edges.** They are
+direct lookups into the internal map/array — calling them inside an effect or memo does not
+subscribe to structural changes.
+
+To react to structural changes (key added, key removed, order changed), read a tracking
+accessor instead:
+
+| You want to react to | Read this |
+|---|---|
+| Any structural change | `collection.get()` or `list.get()` |
+| Key set membership | `collection.keys()` |
+| Length / item count | `collection.length` |
+| A specific item's value | `collection.get()` then access the item |
+
+```typescript
+// Wrong — effect does not re-run when keys are added or removed
+createEffect(() => {
+  const item = collection.byKey('id-123')
+  render(item)
+})
+
+// Correct — reading keys() creates a dependency on structural changes
+createEffect(() => {
+  const keys = collection.keys()           // tracks structure
+  const item = collection.byKey('id-123') // safe after establishing the edge
+  render(item)
+})
+```
+</direct_lookups_do_not_track>
+
+<bykey_set_does_not_propagate_to_structural_subscribers>
+**`byKey(key).set(value)` does not propagate to effects that subscribed via `list.keys()`,
+`list.length`, or the iterator.** Those effects subscribe to the list's structural node but
+do not establish item-level edges, so a direct item signal mutation reaches them only if
+`list.get()` has previously been called to link the item signal to the list node.
+
+Use `list.replace(key, value)` for imperative item updates. It propagates through both paths
+— item-level edges and the structural node — regardless of how subscribers are attached.
+
+```typescript
+// Wrong — silently does nothing for effects that subscribed via list.keys()
+list.byKey(key)?.set(newValue)
+
+// Correct — guaranteed propagation to all subscribers
+list.replace(key, newValue)
+```
+
+`byKey(key).set(value)` is safe only when the consuming effect directly calls
+`byKey(key).get()` inside its body — that creates a direct edge from the item signal to the
+effect, bypassing the list node entirely.
+</bykey_set_does_not_propagate_to_structural_subscribers>
+
+<conditional_reads_delay_watched>
+**Conditional signal reads delay `watched` activation.** The `watched` callback on a State
+or Sensor fires when the first downstream effect subscribes. If a signal is only read inside
+a branch that hasn't executed yet, `watched` does not fire until that branch runs.
+
+Read all signals you care about eagerly — before any conditional logic — to ensure `watched`
+fires on the first effect run:
+
+```typescript
+// Bad — `derived` is only read after `task` resolves to `ok`
+// `derived.watched` does not fire until the task has a value
+createEffect(() => {
+  match([task], {
+    ok: ([result]) => render(derived.get(), result),
+    nil: () => showSpinner(),
+  })
+})
+
+// Good — both signals are read on every run, regardless of task state
+// Both `watched` callbacks fire immediately when the effect is created
+createEffect(() => {
+  match([task, derived], {
+    ok: ([result, value]) => render(value, result),
+    nil: () => showSpinner(),
+  })
+})
+```
+
+This also applies to plain `if` / ternary / `&&` patterns — any signal read gated behind a
+condition may not establish its dependency edge until the condition is true.
+</conditional_reads_delay_watched>
+
+<equals_suppresses_subtrees>
+**`equals` suppresses entire downstream subgraphs, not just the node it is set on.** When a
+Memo or State recomputes to a value considered equal to the previous one, all downstream
+nodes skip recomputation entirely without running their callbacks.
+
+This is a powerful optimisation, but it has a non-obvious consequence: a custom `equals` on
+an intermediate Memo can silently prevent large parts of the graph from updating, even if
+upstream sources changed.
+
+```typescript
+const source = createState({ x: 1, y: 2 })
+
+// This memo compares by x only
+const xOnly = createMemo(
+  () => source.get().x,
+  { equals: (a, b) => a === b }
+)
+
+// This effect depends on xOnly.
+// It will NOT re-run if source changes but x stays the same,
+// even if y changed dramatically.
+createEffect(() => {
+  console.log('x is', xOnly.get())
+})
+```
+
+When debugging "why did my effect not re-run", check for custom `equals` on intermediate
+memos in the dependency chain.
+</equals_suppresses_subtrees>
+
+<watched_stable_through_mutations>
+**`watched` stays active through structural mutations.** The `watched` callback on a List or
+Collection source is called once when the first downstream effect subscribes, and `unwatched`
+is called when the last downstream effect unsubscribes. Structural mutations (adding items,
+removing items, updating values) do not call `unwatched` then `watched` again — the callback
+remains active for the lifetime of the subscription.
+
+```typescript
+const list = createList(
+  () => startPolling(),   // watched:   called once when first effect subscribes
+  () => stopPolling(),    // unwatched: called once when last effect unsubscribes
+)
+
+// These mutations do NOT restart the watched/unwatched cycle.
+// The data source stays open as long as at least one effect is subscribed.
+list.push({ id: '1', name: 'Item 1' })  // watched is NOT called again
+list.delete('1')                         // watched is NOT called again
+```
+</watched_stable_through_mutations>
+
+<task_abort_on_dependency_change>
+**A Task's `AbortSignal` is aborted when dependencies change before the async operation
+completes.** If a Task's sources update while the previous `Promise` is still pending, a new
+run is scheduled and the previous `AbortController` is aborted. Not forwarding the signal to
+cancellable async operations will cause stale results to overwrite fresh ones.
+
+```typescript
+// Wrong — fetch is not cancellable; a stale response may arrive after a newer one
+const results = createTask(async () => {
+  return fetch(`/api/search?q=${query.get()}`).then(r => r.json())
+})
+
+// Correct — abort signal forwarded; stale in-flight requests are cancelled
+const results = createTask(async (prev, signal) => {
+  return fetch(`/api/search?q=${query.get()}`, { signal }).then(r => r.json())
+})
+```
+</task_abort_on_dependency_change>
+
+<sensor_unset_before_first_value>
+**Reading a Sensor or Task before it has produced a value throws `UnsetSignalValueError`.**
+Unlike State, these signals have no initial value — they are explicitly "unset" until the
+first value arrives.
+
+Guard against this with `match`, which provides a `nil` branch for the unset case:
+
+```typescript
+const tick = createSensor<number>(set => {
+  const id = setInterval(() => set(Date.now()), 1000)
+  return () => clearInterval(id)
+})
+
+// Wrong — throws UnsetSignalValueError on first run, before the interval fires
+createEffect(() => {
+  console.log(tick.get())
+})
+
+// Correct — match handles the nil (unset) case explicitly
+createEffect(() => {
+  match([tick], {
+    ok:  ([timestamp]) => console.log('tick:', timestamp),
+    nil: () => console.log('waiting for first tick…'),
+  })
+})
+```
+</sensor_unset_before_first_value>
+
+<scope_cleanup_is_synchronous>
+**Scope and Effect cleanup runs synchronously when the returned `Cleanup` function is
+called.** It does not wait for the current flush to complete. Calling cleanup during a batch
+(e.g. inside a `batch` callback) is safe but will immediately dispose the owner and all its
+children.
+</scope_cleanup_is_synchronous>