@zeix/cause-effect 1.0.0 → 1.0.1

package/skills/tech-writer/workflows/update-requirements.md

@@ -0,0 +1,80 @@
+<required_reading>
+1. references/document-map.md — REQUIREMENTS.md section
+2. references/tone-guide.md — requirements tone rules
+</required_reading>
+
+<process>
+## Step 1: Confirm the update is warranted
+
+REQUIREMENTS.md captures the library's vision, audience, design principles, constraints,
+and non-goals. It is intentionally written to survive version bumps. Do NOT update it for:
+
+- Bug fixes or internal refactors
+- New options on existing signal types
+- Changed implementation details
+- Documentation or tooling changes
+
+Only update REQUIREMENTS.md when one of these applies:
+
+| Trigger | Section affected |
+|---|---|
+| A new signal type is added to the library | "Design Principles → Minimal Surface, Maximum Coverage" table |
+| A signal type is removed | Same table + "Non-Goals" if it was previously out of scope |
+| A runtime environment is added or dropped | "Runtime Environments" |
+| A bundle size target changes | "Size and Performance Constraints" |
+| A design principle is added, changed, or removed | "Design Principles" |
+| The primary or secondary audience shifts | "Audience" |
+| A non-goal is resolved or a new one is added | "Non-Goals" |
+| Stability guarantees change | "Stability" |
+
+If the change does not meet any of these criteria, stop and explain why REQUIREMENTS.md
+does not need updating. Do not edit it speculatively.
+
+## Step 2: Read the full document
+
+Read `REQUIREMENTS.md` in full before touching anything. Identify the single section
+(or at most two) that the change affects. Changes to REQUIREMENTS.md are almost always
+one table row, one list item, or one short paragraph — rarely more.
+
+## Step 3: Make the minimal edit
+
+Make only the change the trigger warrants:
+
+**Signal type table (most common):**
+Add or remove a row. The row format is:
+`| **Type** | Role description | Data structure |`
+Keep the role description to one short phrase. The table reflects the final state
+of the type set — it is not a changelog.
+
+**Runtime environments:**
+Add or remove the environment name from the prose list. One line.
+
+**Bundle size targets:**
+Update the number in the table. If the target changed for a reason that future readers
+should understand, add one sentence of rationale — no more.
+
+**Non-goals:**
+Each non-goal is a bold heading followed by one sentence. Do not expand them into
+paragraphs. If adding a new non-goal, follow the same pattern. If resolving one,
+remove it entirely — do not mark it as resolved inline.
+
+**Stability section:**
+Update only the factual claims (version number, breaking change expectations). Preserve
+the formal register of the surrounding text.
+
+## Step 4: Verify internal consistency
+
+After editing, confirm:
+- The signal type table count matches the count stated in the prose ("9 signal types").
+- The "Non-Goals" section does not contradict anything now present in the codebase.
+- The "Stability" section accurately describes the current version and compatibility stance.
+</process>
+
+<success_criteria>
+- Update was warranted by one of the listed triggers
+- Only the affected section was changed — no rewrites of accurate content
+- Signal type table count consistent with prose and with `index.ts`
+- Formal, strategic tone preserved throughout per references/tone-guide.md
+- No changelog-style language ("previously", "now", "we changed") — state the current
+  truth only
+</success_criteria>

package/src/graph.ts

@@ -590,6 +590,8 @@ function createScope(fn: () => MaybeCleanup): Cleanup {
  * reactive graph.
  *
  * @since 0.18.5
+ * @param fn - The function to execute without an active owner
+ * @returns The return value of `fn`
  */
 function unown<T>(fn: () => T): T {
 	const prev = activeOwner

package/src/nodes/collection.ts

@@ -36,10 +36,24 @@ import { createTask } from './task'
 
 type CollectionSource<T extends {}> = List<T> | Collection<T>
 
+/**
+ * Transformation callback for `deriveCollection` — sync or async.
+ * Sync callbacks produce a `Memo<T>` per item; async callbacks produce a `Task<T>`
+ * with automatic cancellation when the source item changes.
+ *
+ * @template T - The type of derived items
+ * @template U - The type of source items
+ */
 type DeriveCollectionCallback<T extends {}, U extends {}> =
 	| ((sourceValue: U) => T)
 	| ((sourceValue: U, abort: AbortSignal) => Promise<T>)
 
+/**
+ * A read-only reactive keyed collection with per-item reactivity.
+ * Created by `createCollection` (externally driven) or via `.deriveCollection()` on a `List` or `Collection`.
+ *
+ * @template T - The type of items in the collection
+ */
 type Collection<T extends {}> = {
 	readonly [Symbol.toStringTag]: 'Collection'
 	readonly [Symbol.isConcatSpreadable]: true
@@ -59,18 +73,42 @@ type Collection<T extends {}> = {
 	readonly length: number
 }
 
+/**
+ * Granular mutation descriptor passed to the `applyChanges` callback inside a `CollectionCallback`.
+ *
+ * @template T - The type of items in the collection
+ */
 type CollectionChanges<T> = {
+	/** Items to add. Each item is assigned a new key via the configured `keyConfig`. */
 	add?: T[]
+	/** Items whose values have changed. Matched to existing entries by key. */
 	change?: T[]
+	/** Items to remove. Matched to existing entries by key. */
 	remove?: T[]
 }
 
+/**
+ * Configuration options for `createCollection`.
+ *
+ * @template T - The type of items in the collection
+ */
 type CollectionOptions<T extends {}> = {
+	/** Initial items. Defaults to `[]`. */
 	value?: T[]
+	/** Key generation strategy. See `KeyConfig`. Defaults to auto-increment. */
 	keyConfig?: KeyConfig<T>
+	/** Factory for per-item signals. Defaults to `createState`. */
 	createItem?: (value: T) => Signal<T>
 }
 
+/**
+ * Setup callback for `createCollection`. Invoked when the collection gains its first downstream
+ * subscriber; receives an `applyChanges` function to push granular mutations into the graph.
+ *
+ * @template T - The type of items in the collection
+ * @param apply - Call with a `CollectionChanges` object to add, update, or remove items
+ * @returns A cleanup function invoked when the collection loses all subscribers
+ */
 type CollectionCallback<T extends {}> = (
 	apply: (changes: CollectionChanges<T>) => void,
 ) => Cleanup

package/src/nodes/effect.ts

@@ -20,13 +20,22 @@ import {
 
 /* === Types === */
 
+/** A value that is either synchronous or a `Promise` — used for handler return types in `match()`. */
 type MaybePromise<T> = T | Promise<T>
 
+/**
+ * Handlers for all states of one or more signals passed to `match()`.
+ *
+ * @template T - Tuple of `Signal` types being matched
+ */
 type MatchHandlers<T extends readonly Signal<unknown & {}>[]> = {
+	/** Called when all signals have a value. Receives a tuple of resolved values. */
 	ok: (values: {
 		[K in keyof T]: T[K] extends Signal<infer V> ? V : never
 	}) => MaybePromise<MaybeCleanup>
+	/** Called when one or more signals hold an error. Defaults to `console.error`. */
 	err?: (errors: readonly Error[]) => MaybePromise<MaybeCleanup>
+	/** Called when one or more signals are unset (pending). */
 	nil?: () => MaybePromise<MaybeCleanup>
 }
 
@@ -88,10 +97,13 @@ function createEffect(fn: EffectCallback): Cleanup {
 }
 
 /**
- * Runs handlers based on the current values of signals.
+ * Reads one or more signals and dispatches to the appropriate handler based on their state.
  * Must be called within an active owner (effect or scope) so async cleanup can be registered.
  *
  * @since 0.15.0
+ * @param signals - Tuple of signals to read; all must have a value for `ok` to run.
+ * @param handlers - Object with an `ok` branch and optional `err` and `nil` branches.
+ * @returns An optional cleanup function if the active handler returns one.
  * @throws RequiredOwnerError If called without an active owner.
  */
 function match<T extends readonly Signal<unknown & {}>[]>(

package/src/nodes/list.ts

@@ -40,13 +40,33 @@ type DiffResult = {
 	remove: UnknownRecord
 }
 
+/**
+ * Key generation strategy for `createList` items.
+ * A string value is used as a prefix for auto-incremented keys (`prefix0`, `prefix1`, …).
+ * A function receives each item and returns a stable string key, or `undefined` to fall back to auto-increment.
+ *
+ * @template T - The type of items in the list
+ */
 type KeyConfig<T> = string | ((item: T) => string | undefined)
 
+/**
+ * Configuration options for `createList`.
+ *
+ * @template T - The type of items in the list
+ */
 type ListOptions<T extends {}> = {
+	/** Key generation strategy. A string prefix or a function `(item) => string | undefined`. Defaults to auto-increment. */
 	keyConfig?: KeyConfig<T>
+	/** Lifecycle callback invoked when the list gains its first downstream subscriber. Must return a cleanup function. */
 	watched?: () => Cleanup
 }
 
+/**
+ * A reactive ordered array with stable keys and per-item reactivity.
+ * Each item is a `State<T>` signal; structural changes (add/remove/sort) propagate reactively.
+ *
+ * @template T - The type of items in the list
+ */
 type List<T extends {}> = {
 	readonly [Symbol.toStringTag]: 'List'
 	readonly [Symbol.isConcatSpreadable]: true
@@ -240,8 +260,9 @@ function diffArrays<T>(
  *
  * @since 0.18.0
  * @param value - Initial array of items
- * @param options - Optional configuration for key generation and watch lifecycle
- * @returns A List signal
+ * @param options.keyConfig - Key generation strategy: string prefix or `(item) => string | undefined`. Defaults to auto-increment.
+ * @param options.watched - Lifecycle callback invoked on first subscriber; must return a cleanup function called on last unsubscribe.
+ * @returns A `List` signal with reactive per-item `State` signals
  */
 function createList<T extends {}>(
 	value: T[],

package/src/nodes/memo.ts

@@ -36,7 +36,6 @@ type Memo<T extends {}> = {
 	 * Recomputes if dependencies have changed since last access.
 	 * When called inside another reactive context, creates a dependency.
 	 * @returns The computed value
-	 * @throws UnsetSignalValueError If the memo value is still unset when read.
 	 */
 	get(): T
 }

package/src/nodes/sensor.ts

@@ -35,11 +35,9 @@ type Sensor<T extends {}> = {
 }
 
 /**
- * A callback function for sensors when the sensor starts being watched.
+ * Configuration options for `createSensor`.
  *
- * @template T - The type of value observed
- * @param set - A function to set the observed value
- * @returns A cleanup function when the sensor stops being watched
+ * @template T - The type of value produced by the sensor
  */
 type SensorOptions<T extends {}> = SignalOptions<T> & {
 	/**
@@ -49,6 +47,14 @@ type SensorOptions<T extends {}> = SignalOptions<T> & {
 	value?: T
 }
 
+/**
+ * Setup callback for `createSensor`. Invoked when the sensor gains its first downstream
+ * subscriber; receives a `set` function to push new values into the graph.
+ *
+ * @template T - The type of value produced by the sensor
+ * @param set - Updates the sensor value and propagates the change to subscribers
+ * @returns A cleanup function invoked when the sensor loses all subscribers
+ */
 type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup
 
 /* === Exported Functions === */

package/src/nodes/store.ts

@@ -28,7 +28,11 @@ import { createState, type State } from './state'
 
 /* === Types === */
 
+/**
+ * Configuration options for `createStore`.
+ */
 type StoreOptions = {
+	/** Invoked when the store gains its first downstream subscriber; returns a cleanup called when the last one unsubscribes. */
 	watched?: () => Cleanup
 }
 
@@ -58,6 +62,13 @@ type BaseStore<T extends UnknownRecord> = {
 	remove(key: string): void
 }
 
+/**
+ * A reactive object with per-property reactivity.
+ * Each property is wrapped as a `State`, nested `Store`, or `List` signal, accessible directly via proxy.
+ * Updating one property only re-runs effects that read that property.
+ *
+ * @template T - The plain-object type whose properties become reactive signals
+ */
 type Store<T extends UnknownRecord> = BaseStore<T> & {
 	[K in keyof T]: T[K] extends readonly (infer U extends {})[]
 		? List<U>

package/src/signal.ts

@@ -22,6 +22,12 @@ import { isAsyncFunction, isFunction, isRecord, isUniformArray } from './util'
 
 /* === Types === */
 
+/**
+ * A readable and writable signal — the type union of `State`, `Store`, and `List`.
+ * Use as a parameter type for generic code that accepts any writable signal.
+ *
+ * @template T - The type of value held by the signal
+ */
 type MutableSignal<T extends {}> = {
 	get(): T
 	set(value: T): void

package/tsconfig.json

@@ -12,6 +12,10 @@
 		"moduleResolution": "bundler",
 		"allowImportingTsExtensions": true,
 		"verbatimModuleSyntax": true,
+		"erasableSyntaxOnly": true,
+		"isolatedModules": true,
+		"resolveJsonModule": true,
+		"types": ["bun-types"],
 
 		// Editor-only mode - no emit
 		"noEmit": true,
@@ -24,11 +28,16 @@
 		"useUnknownInCatchVariables": true,
 		"noUncheckedSideEffectImports": true,
 		"noFallthroughCasesInSwitch": true,
+		"forceConsistentCasingInFileNames": true,
 
 		// Some stricter flags (disabled by default)
 		"noUnusedLocals": false,
 		"noUnusedParameters": false,
 		"noPropertyAccessFromIndexSignature": false,
+
+		/* Performance */
+		"incremental": true,
+		"tsBuildInfoFile": "./.tsbuildinfo",
 	},
 	"include": ["./**/*.ts"],
 	"exclude": ["node_modules", "types", "index.js"],