@zeix/cause-effect 0.18.0 → 0.18.2

package/types/src/nodes/list.d.ts

@@ -8,7 +8,7 @@ type DiffResult = {
     change: UnknownRecord;
     remove: UnknownRecord;
 };
-type KeyConfig<T> = string | ((item: T) => string);
+type KeyConfig<T> = string | ((item: T) => string | undefined);
 type ListOptions<T extends {}> = {
     keyConfig?: KeyConfig<T>;
     watched?: () => Cleanup;
@@ -19,8 +19,8 @@ type List<T extends {}> = {
     [Symbol.iterator](): IterableIterator<State<T>>;
     readonly length: number;
     get(): T[];
-    set(newValue: T[]): void;
-    update(fn: (oldValue: T[]) => T[]): void;
+    set(next: T[]): void;
+    update(fn: (prev: T[]) => T[]): void;
     at(index: number): State<T> | undefined;
     keys(): IterableIterator<string>;
     byKey(key: string): State<T> | undefined;
@@ -37,23 +37,24 @@ type List<T extends {}> = {
  * Checks if two values are equal with cycle detection
  *
  * @since 0.15.0
- * @param {T} a - First value to compare
- * @param {T} b - Second value to compare
- * @param {WeakSet<object>} visited - Set to track visited objects for cycle detection
- * @returns {boolean} Whether the two values are equal
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @param visited - Set to track visited objects for cycle detection
+ * @returns Whether the two values are equal
  */
+declare function isEqual<T>(a: T, b: T, visited?: WeakSet<object>): boolean;
 /** Shallow equality check for string arrays */
 declare function keysEqual(a: string[], b: string[]): boolean;
-declare function isEqual<T>(a: T, b: T, visited?: WeakSet<object>): boolean;
+declare function getKeyGenerator<T extends {}>(keyConfig?: KeyConfig<T>): [(item: T) => string, boolean];
 /**
  * Creates a reactive list with stable keys and per-item reactivity.
  *
  * @since 0.18.0
- * @param initialValue - Initial array of items
+ * @param value - Initial array of items
  * @param options - Optional configuration for key generation and watch lifecycle
  * @returns A List signal
  */
-declare function createList<T extends {}>(initialValue: T[], options?: ListOptions<T>): List<T>;
+declare function createList<T extends {}>(value: T[], options?: ListOptions<T>): List<T>;
 /**
  * Checks if a value is a List signal.
  *
@@ -62,4 +63,4 @@ declare function createList<T extends {}>(initialValue: T[], options?: ListOptio
  * @returns True if the value is a List
  */
 declare function isList<T extends {}>(value: unknown): value is List<T>;
-export { type DiffResult, type KeyConfig, type List, type ListOptions, type UnknownRecord, createList, isEqual, isList, keysEqual, TYPE_LIST, };
+export { type DiffResult, type KeyConfig, type List, type ListOptions, type UnknownRecord, createList, isEqual, isList, getKeyGenerator, keysEqual, TYPE_LIST, };

package/types/src/nodes/memo.d.ts

@@ -25,6 +25,12 @@ type Memo<T extends {}> = {
  * @template T - The type of value computed by the memo
  * @param fn - The computation function that receives the previous value
  * @param options - Optional configuration for the memo
+ * @param options.value - Optional initial value for reducer patterns
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`)
+ * @param options.guard - Optional type guard to validate values
+ * @param options.watched - Optional callback invoked when the memo is first watched by an effect.
+ *   Receives an `invalidate` function to mark the memo dirty and trigger recomputation.
+ *   Must return a cleanup function called when no effects are watching.
  * @returns A Memo object with a get() method
  *
  * @example

package/types/src/nodes/sensor.d.ts

@@ -1,4 +1,4 @@
-import { type Cleanup, type ComputedOptions } from '../graph';
+import { type Cleanup, type SignalOptions } from '../graph';
 /**
  * A read-only signal that tracks external input and updates a state value as long as it is active.
  *
@@ -8,7 +8,6 @@ type Sensor<T extends {}> = {
     readonly [Symbol.toStringTag]: 'Sensor';
     /**
      * Gets the current value of the sensor.
-     * Updates its state value if the sensor is active.
      * When called inside another reactive context, creates a dependency.
      * @returns The sensor value
      * @throws UnsetSignalValueError If the sensor value is still unset when read.
@@ -22,6 +21,13 @@ type Sensor<T extends {}> = {
  * @param set - A function to set the observed value
  * @returns A cleanup function when the sensor stops being watched
  */
+type SensorOptions<T extends {}> = SignalOptions<T> & {
+    /**
+     * Optional initial value. Avoids `UnsetSignalValueError` on first read
+     * before the watched callback fires.
+     */
+    value?: T;
+};
 type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
 /**
  * Creates a sensor that tracks external input and updates a state value as long as it is active.
@@ -29,12 +35,12 @@ type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
  * no longer watched. This lazy activation pattern ensures resources are only consumed when needed.
  *
  * @since 0.18.0
- * @template T - The type of value stored in the state
- * @param start - The callback function that starts the sensor and returns a cleanup function.
- * @param options - Optional options for the sensor.
+ * @template T - The type of value produced by the sensor
+ * @param watched - The callback invoked when the sensor starts being watched, receives a `set` function and returns a cleanup function.
+ * @param options - Optional configuration for the sensor.
  * @param options.value - Optional initial value. Avoids `UnsetSignalValueError` on first read
- *   before the start callback fires. Essential for the mutable-object observation pattern.
- * @param options.equals - Optional equality function. Defaults to `Object.is`. Use `SKIP_EQUALITY`
+ *   before the watched callback fires. Essential for the mutable-object observation pattern.
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`). Use `SKIP_EQUALITY`
  *   for mutable objects where the reference stays the same but internal state changes.
  * @param options.guard - Optional type guard to validate values.
  * @returns A read-only sensor signal.
@@ -63,7 +69,7 @@ type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
  * }, { value: node, equals: SKIP_EQUALITY });
  * ```
  */
-declare function createSensor<T extends {}>(start: SensorCallback<T>, options?: ComputedOptions<T>): Sensor<T>;
+declare function createSensor<T extends {}>(watched: SensorCallback<T>, options?: SensorOptions<T>): Sensor<T>;
 /**
  * Checks if a value is a Sensor signal.
  *
@@ -72,4 +78,4 @@ declare function createSensor<T extends {}>(start: SensorCallback<T>, options?:
  * @returns True if the value is a Sensor
  */
 declare function isSensor<T extends {} = unknown & {}>(value: unknown): value is Sensor<T>;
-export { createSensor, isSensor, type Sensor, type SensorCallback };
+export { createSensor, isSensor, type Sensor, type SensorCallback, type SensorOptions, };

package/types/src/nodes/store.d.ts

@@ -14,8 +14,8 @@ type BaseStore<T extends UnknownRecord> = {
     keys(): IterableIterator<string>;
     byKey<K extends keyof T & string>(key: K): T[K] extends readonly (infer U extends {})[] ? List<U> : T[K] extends UnknownRecord ? Store<T[K]> : T[K] extends unknown & {} ? State<T[K] & {}> : State<T[K] & {}> | undefined;
     get(): T;
-    set(newValue: T): void;
-    update(fn: (oldValue: T) => T): void;
+    set(next: T): void;
+    update(fn: (prev: T) => T): void;
     add<K extends keyof T & string>(key: K, value: T[K]): K;
     remove(key: string): void;
 };
@@ -28,7 +28,7 @@ type Store<T extends UnknownRecord> = BaseStore<T> & {
  * Properties are accessible directly via proxy.
  *
  * @since 0.15.0
- * @param initialValue - Initial object value of the store
+ * @param value - Initial object value of the store
  * @param options - Optional configuration for watch lifecycle
  * @returns A Store with reactive properties
  *
@@ -39,7 +39,7 @@ type Store<T extends UnknownRecord> = BaseStore<T> & {
  * console.log(user.get()); // { name: 'Bob', age: 30 }
  * ```
  */
-declare function createStore<T extends UnknownRecord>(initialValue: T, options?: StoreOptions): Store<T>;
+declare function createStore<T extends UnknownRecord>(value: T, options?: StoreOptions): Store<T>;
 /**
  * Checks if a value is a Store signal.
  *

package/types/src/nodes/task.d.ts

@@ -36,6 +36,12 @@ type Task<T extends {}> = {
  * @template T - The type of value resolved by the task
  * @param fn - The async computation function that receives the previous value and an AbortSignal
  * @param options - Optional configuration for the task
+ * @param options.value - Optional initial value for reducer patterns
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`)
+ * @param options.guard - Optional type guard to validate values
+ * @param options.watched - Optional callback invoked when the task is first watched by an effect.
+ *   Receives an `invalidate` function to mark the task dirty and trigger re-execution.
+ *   Must return a cleanup function called when no effects are watching.
  * @returns A Task object with get(), isPending(), and abort() methods
  *
  * @example

package/COLLECTION_REFACTORING.md

@@ -1,161 +0,0 @@
-# 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