@ersbeth/picoflow 0.2.4 → 1.0.0

package/dist/types/advanced/array.d.ts

@@ -50,12 +50,6 @@ export declare class FlowArray<T> extends FlowObservable<T[]> {
      * @public
      */
     get length(): number;
-    /**
-     * Returns a copy of the internal array.
-     * @returns A copy of the array.
-     * @public
-     */
-    get(): T[];
     /**
      * Replaces the entire array with new items.
      * @param items - The new array of items.

package/dist/types/advanced/array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/advanced/array.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAI1D;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IACvB;IACI,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,CAAC,EAAE,CAAC;CACd,GACD;IACI,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACX,GACD;IACI,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,CAAC;CACX,GACD;IACI,IAAI,EAAE,KAAK,CAAC;CACf,GACD;IACI,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,CAAC,CAAC;CACX,GACD;IACI,IAAI,EAAE,OAAO,CAAC;CACjB,GACD;IACI,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,EAAE,CAAC;CACd,GACD;IACI,IAAI,EAAE,OAAO,CAAC;CACjB,CAAC;AAER;;;GAGG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,EAAE,CAAC;IACjD;;;OAGG;IACH,WAAW,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3C;;;;OAIG;gBACS,KAAK,GAAE,CAAC,EAAO;IAS3B;;;;OAIG;IACH,IAAI,MAAM,IAAI,MAAM,CAGnB;IAED;;;;OAIG;IACH,GAAG,IAAI,CAAC,EAAE;IAKV;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAUrB;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IAUrC;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAOnB;;;OAGG;IACH,GAAG,IAAI,IAAI;IAUX;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAOtB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAUb;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,EAAE,GAAG,IAAI;IAelE;;;OAGG;IACH,KAAK,IAAI,IAAI;IAWb;;;;OAIG;IACM,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CAWtD"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/advanced/array.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,SAAS,EAAgB,MAAM,UAAU,CAAC;AAGxE;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAC1B;IACA,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,CAAC,EAAE,CAAC;CACV,GACD;IACA,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACP,GACD;IACA,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,CAAC;CACP,GACD;IACA,IAAI,EAAE,KAAK,CAAC;CACX,GACD;IACA,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,CAAC,CAAC;CACP,GACD;IACA,IAAI,EAAE,OAAO,CAAC;CACb,GACD;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,EAAE,CAAC;CACV,GACD;IACA,IAAI,EAAE,OAAO,CAAC;CACb,CAAC;AAEL;;;GAGG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,EAAE,CAAC;IACpD;;;OAGG;IACH,WAAW,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3C;;;;OAIG;gBACS,KAAK,GAAE,CAAC,EAAO;IAS3B;;;;OAIG;IACH,IAAI,MAAM,IAAI,MAAM,CAGnB;IAWD;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAUrB;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IAUrC;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAOnB;;;OAGG;IACH,GAAG,IAAI,IAAI;IAUX;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAOtB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAUb;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,EAAE,GAAG,IAAI;IAelE;;;OAGG;IACH,KAAK,IAAI,IAAI;IAWb;;;;OAIG;IACM,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CAWnD"}

package/dist/types/advanced/index.d.ts

@@ -1,9 +1,9 @@
+export type { FlowArrayAction } from './array';
+export { FlowArray } from './array';
 export { FlowMap } from './map';
-export { FlowStream } from './stream';
-export { FlowStreamAsync } from './streamAsync';
 export { FlowResource } from './resource';
 export { FlowResourceAsync } from './resourceAsync';
-export type { FlowStreamUpdater, FlowStreamDisposer, FlowStreamSetter, } from './stream';
-export { FlowArray } from './array';
-export type { FlowArrayAction } from './array';
+export type { FlowStreamDisposer, FlowStreamSetter, FlowStreamUpdater, } from './stream';
+export { FlowStream } from './stream';
+export { FlowStreamAsync } from './streamAsync';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/advanced/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/advanced/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EACR,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/advanced/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EACX,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/types/advanced/map.d.ts

@@ -1,36 +1,103 @@
 import { FlowState } from '../basic/';
 /**
- * Represents a reactive map of states extending {@link FlowState} for a Map of key/value pairs.
+ * Represents a reactive map that extends {@link FlowState} for tracking key-value pairs.
  *
  * @remarks
- * FlowMap wraps a native Map and provides reactive signals for fine-grained tracking
- * of updates to the map. In addition to the reactive capabilities inherited from FlowState,
- * it exposes two reactive signals:
+ * FlowMap wraps a native JavaScript Map and provides reactive tracking at multiple granularity levels.
+ * Unlike plain reactive state, FlowMap offers fine-grained reactivity that lets you track:
  *
- * • $lastSet: Holds the most recent key-value pair that was set.
- * • $lastDeleted: Holds the most recent key-value pair that was deleted.
+ * 1. **Whole map changes**: Via `get(t)` or `pick()` on the FlowMap itself
+ * 2. **Last add operation**: Via the `$lastAdded` signal, track which key-value pair was most recently added
+ * 3. **Last update operation**: Via the `$lastUpdated` signal, track which key-value pair was most recently updated
+ * 4. **Last delete operation**: Via the `$lastDeleted` signal, track which key-value pair was most recently removed
  *
- * Use {@link FlowMap.setAt} to add or update a key-value pair and {@link FlowMap.delete} to remove a key.
+ * **Reactive Signals:**
+ * - **$lastAdded**: A FlowState containing `{ key?: K, value?: V }` updated on each `add()` call
+ * - **$lastUpdated**: A FlowState containing `{ key?: K, value?: V }` updated on each `update()` call
+ * - **$lastDeleted**: A FlowState containing `{ key?: K, value?: V }` updated on each `delete()` call
  *
- * @typeparam K - The type of the map keys.
- * @typeparam V - The type of the map values.
+ * These signals enable fine-grained reactivity patterns where effects can respond to specific
+ * map operations without re-processing the entire map.
+ *
+ * **Use Cases:**
+ * - Entity stores where you want to track additions/removals separately
+ * - Cache implementations with granular invalidation
+ * - Collections where operations on individual keys matter
+ * - UI state where you want to animate specific additions or removals
+ *
+ * @example
+ * ```typescript
+ * const $users = map<string, User>();
+ *
+ * // Track the whole map
+ * effect((t) => {
+ *   const users = $users.get(t);
+ *   console.log(`Total users: ${users.size}`);
+ * });
+ *
+ * // Track only additions
+ * effect((t) => {
+ *   const { key, value } = $users.$lastAdded.get(t);
+ *   if (key && value) {
+ *     console.log(`User ${key} was added:`, value);
+ *   }
+ * });
+ *
+ * // Track only updates
+ * effect((t) => {
+ *   const { key, value } = $users.$lastUpdated.get(t);
+ *   if (key && value) {
+ *     console.log(`User ${key} was updated:`, value);
+ *   }
+ * });
+ *
+ * // Track only deletions
+ * effect((t) => {
+ *   const { key, value } = $users.$lastDeleted.get(t);
+ *   if (key && value) {
+ *     console.log(`User ${key} was deleted:`, value);
+ *   }
+ * });
+ *
+ * // Modify the map
+ * $users.add('user1', { name: 'John', age: 30 });
+ * $users.add('user2', { name: 'Jane', age: 25 });
+ * $users.update('user1', { name: 'John', age: 31 });
+ * $users.delete('user1');
+ * ```
+ *
+ * @typeParam K - The type of the map keys.
+ * @typeParam V - The type of the map values.
  *
  * @public
  */
 export declare class FlowMap<K, V> extends FlowState<Map<K, V>> {
     /**
-     * A reactive state that holds the most recent key and value that were set.
+     * A reactive state that holds the most recent key and value that were added.
      *
      * @remarks
-     * When a key is set via {@link FlowMap.setAt}, this state is updated with
+     * When a key is added via {@link FlowMap.add}, this state is updated with
      * the corresponding key and value.
      *
      * @public
      */
-    $lastSet: FlowState<{
-        key?: K;
-        value?: V;
-    }>;
+    $lastAdded: FlowState<{
+        key: K;
+        value: V;
+    } | null>;
+    /**
+     * A reactive state that holds the most recent key and value that were updated.
+     *
+     * @remarks
+     * When a key is updated via {@link FlowMap.update}, this state is updated with
+     * the corresponding key and value.
+     *
+     * @public
+     */
+    $lastUpdated: FlowState<{
+        key: K;
+        value: V;
+    } | null>;
     /**
      * A reactive state that holds the most recent key and value that were deleted.
      *
@@ -41,23 +108,39 @@ export declare class FlowMap<K, V> extends FlowState<Map<K, V>> {
      * @public
      */
     $lastDeleted: FlowState<{
-        key?: K;
-        value?: V;
-    }>;
+        key: K;
+        value: V;
+    } | null>;
     /**
-     * Sets a value at the specified key in the underlying map.
+     * Adds a new key-value pair to the map.
      *
-     * @param key - The key at which to set the value.
-     * @param value - The value to set.
+     * @param key - The key to add.
+     * @param value - The value to associate with the key.
      * @throws If the FlowMap instance is disposed.
+     * @throws If the key already exists in the map.
      *
      * @remarks
-     * Updates the internal map, emits the key-value pair via {@link FlowMap.$lastSet},
+     * Adds a new entry to the internal map, emits the key-value pair via {@link FlowMap.$lastAdded},
      * and notifies all subscribers of the change.
      *
      * @public
      */
-    setAt(key: K, value: V): void;
+    add(key: K, value: V): void;
+    /**
+     * Updates an existing key-value pair in the map.
+     *
+     * @param key - The key to update.
+     * @param value - The new value to associate with the key.
+     * @throws If the FlowMap instance is disposed.
+     * @throws If the key does not exist in the map.
+     *
+     * @remarks
+     * Updates an existing entry in the internal map, emits the key-value pair via {@link FlowMap.$lastUpdated},
+     * and notifies all subscribers of the change.
+     *
+     * @public
+     */
+    update(key: K, value: V): void;
     /**
      * Deletes the value at the specified key from the underlying map.
      *
@@ -71,5 +154,13 @@ export declare class FlowMap<K, V> extends FlowState<Map<K, V>> {
      * @public
      */
     delete(key: K): void;
+    /**
+     * Disposes the FlowMap and its values.
+     * @param options - Disposal options.
+     * @public
+     */
+    dispose(options?: {
+        self: boolean;
+    }): void;
 }
 //# sourceMappingURL=map.d.ts.map

package/dist/types/advanced/map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/advanced/map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,OAAO,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnD;;;;;;;;OAQG;IACI,QAAQ,EAAE,SAAS,CAAC;QAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC,CAAqB;IAEvE;;;;;;;;OAQG;IACI,YAAY,EAAE,SAAS,CAAC;QAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC,CAAqB;IAE3E;;;;;;;;;;;;OAYG;IACI,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAOpC;;;;;;;;;;;OAWG;IACI,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;CAO9B"}
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/advanced/map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,MAAM,WAAW,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,qBAAa,OAAO,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD;;;;;;;;OAQG;IACI,UAAU;aAAwB,CAAC;eAAS,CAAC;cAAiB;IAErE;;;;;;;;OAQG;IACI,YAAY;aAAwB,CAAC;eAAS,CAAC;cAAiB;IAEvE;;;;;;;;OAQG;IACI,YAAY;aAAwB,CAAC;eAAS,CAAC;cAAiB;IAEvE;;;;;;;;;;;;;OAaG;IACI,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAUlC;;;;;;;;;;;;;OAaG;IACI,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAUrC;;;;;;;;;;;OAWG;IACI,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAS3B;;;;OAIG;IACM,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CAUnD"}

package/dist/types/advanced/resource.d.ts

@@ -1,29 +1,68 @@
 import { FlowObservable } from '../basic';
 /**
- * Represents a reactive resource that asynchronously fetches its value.
+ * Represents a reactive resource that asynchronously fetches its value and returns `T | undefined`.
  *
- * @remarks A FlowResource extends FlowObservable and encapsulates an asynchronous fetch function.
- * It is used to retrieve and update its value asynchronously. When the fetch is executed,
- * if the new value differs from the current value, the resource is updated and its subscribers
- * are notified.
+ * @remarks
+ * FlowResource extends FlowObservable to manage asynchronous data fetching with reactive updates.
+ * Unlike {@link FlowResourceAsync} which always returns a Promise, FlowResource returns the resolved
+ * value directly (or `undefined` if not yet fetched), making it more convenient for synchronous access
+ * patterns in effects and derivations.
+ *
+ * **Key Characteristics:**
+ * - The value is `undefined` initially, before the first fetch
+ * - Call `fetch()` to trigger the asynchronous fetch operation
+ * - When fetched, the value is compared to the current value; only different values trigger updates
+ * - Reading via `get(t)` or `pick()` returns the current value (possibly `undefined`) without triggering a fetch
+ *
+ * **Fetch Behavior:**
+ * The fetch function is NOT called automatically on construction. You must explicitly call the
+ * `fetch()` method to retrieve the resource. This gives you control over when network requests
+ * or expensive async operations occur.
+ *
+ * **Use Cases:**
+ * - API data fetching where you want synchronous access to the cached value
+ * - Lazy-loaded data that shouldn't fetch on construction
+ * - Resources that need manual refresh control
+ * - Data that may or may not be available (hence `T | undefined`)
+ *
+ * @example
+ * ```typescript
+ * const $user = resource(() => fetchUserFromAPI());
+ *
+ * // Initially undefined
+ * console.log($user.pick()); // undefined
+ *
+ * // Trigger the fetch
+ * await $user.fetch();
+ * console.log($user.pick()); // { id: 1, name: 'John' }
+ *
+ * // Use in an effect
+ * effect((t) => {
+ *   const user = $user.get(t);
+ *   if (user) {
+ *     console.log(`Hello, ${user.name}`);
+ *   }
+ * });
+ *
+ * // Refetch to update
+ * await $user.fetch();
+ * ```
+ *
+ * @typeParam T - The type of the resource value (not including the undefined case).
  *
  * @public
  */
 export declare class FlowResource<T> extends FlowObservable<T | undefined> {
     /**
      * Creates a new FlowResource.
+     *
      * @param fetch - An asynchronous function that retrieves the resource's value.
+     * This function is not invoked on construction; you must call the `fetch()` method
+     * to execute it.
      *
      * @public
      */
     constructor(fetch: () => Promise<T>);
-    /**
-     * Retrieves the current resource value.
-     * @returns The current value, or undefined if the resource has not been fetched yet.
-     * @throws Error if the resource is disposed.
-     * @public
-     */
-    get(): T | undefined;
     /**
      * Asynchronously fetches a new value for the resource.
      * @remarks

package/dist/types/advanced/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../../src/advanced/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;;;;GASG;AACH,qBAAa,YAAY,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,GAAG,SAAS,CAAC;IAC9D;;;;;OAKG;gBACS,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAKnC;;;;;OAKG;IACI,GAAG,IAAI,CAAC,GAAG,SAAS;IAK3B;;;;;;;;OAQG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUnC,OAAO,CAAC,MAAM,CAAmB;CACpC"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../../src/advanced/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,qBAAa,YAAY,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE;;;;;;;;OAQG;gBACS,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAcnC;;;;;;;;OAQG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUnC,OAAO,CAAC,MAAM,CAAmB;CACjC"}

package/dist/types/advanced/resourceAsync.d.ts

@@ -1,14 +1,36 @@
 import { FlowObservable } from '../basic/';
 /**
- * Represents a reactive resource that asynchronously fetches its value.
+ * Represents a reactive resource that asynchronously fetches its value and always returns a Promise.
  *
  * @remarks
- * A FlowResource extends FlowObservable and encapsulates an asynchronous fetch function.
- * It is used to retrieve and update its value asynchronously. When the fetch is executed,
- * if the new value differs from the current value, the resource is updated and its subscribers
- * are notified.
+ * FlowResourceAsync extends FlowObservable and encapsulates an asynchronous fetch function.
+ * Unlike {@link FlowResource} which returns `T | undefined`, FlowResourceAsync always returns
+ * a `Promise<T>`, making it suitable for async/await patterns.
  *
- * @typeparam T - The type of the resource value.
+ * **Key Characteristics:**
+ * - The first call to `get()` or `pick()` creates and caches a Promise
+ * - Subsequent calls return the same Promise until `fetch()` is called
+ * - Calling `fetch()` creates a new Promise and notifies subscribers
+ * - The Promise resolves to the fetched value of type T
+ *
+ * **Lazy Promise Creation:**
+ * The fetch function doesn't execute until the resource's value is first accessed.
+ * This allows you to define resources without immediately triggering network requests.
+ *
+ * @example
+ * ```typescript
+ * const $user = resourceAsync(() => fetchUserFromAPI());
+ *
+ * effect(async (t) => {
+ *   const user = await $user.get(t);  // Tracked, effect re-runs on fetch()
+ *   console.log(user.name);
+ * });
+ *
+ * // Trigger a refetch
+ * await $user.fetch();
+ * ```
+ *
+ * @typeParam T - The type of the resource value (not the Promise itself).
  *
  * @public
  */
@@ -19,13 +41,6 @@ export declare class FlowResourceAsync<T> extends FlowObservable<Promise<T>> {
      * @public
      */
     constructor(fetch: () => Promise<T>);
-    /**
-     * Retrieves the current resource value.
-     * @returns The current value, or undefined if the resource has not been fetched yet.
-     * @throws Error if the resource is disposed.
-     * @public
-     */
-    get(): Promise<T>;
     /**
      * Asynchronously fetches a new value for the resource.
      * @remarks

package/dist/types/advanced/resourceAsync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resourceAsync.d.ts","sourceRoot":"","sources":["../../../src/advanced/resourceAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAChE;;;;OAIG;gBACS,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAKnC;;;;;OAKG;IACI,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IAMxB;;;;;;;;OAQG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQnC,OAAO,CAAC,MAAM,CAAmB;CACpC"}
+{"version":3,"file":"resourceAsync.d.ts","sourceRoot":"","sources":["../../../src/advanced/resourceAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,iBAAiB,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE;;;;OAIG;gBACS,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAenC;;;;;;;;OAQG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQnC,OAAO,CAAC,MAAM,CAAmB;CACjC"}

package/dist/types/advanced/stream.d.ts

@@ -1,7 +1,7 @@
 import { FlowObservable } from '../basic/';
 /**
  * A function type that sets a new value for the reactive stream.
- * @typeparam T - The type of the value.
+ * @typeParam T - The type of the value.
  * @public
  */
 export type FlowStreamSetter<T> = (value: T) => void;
@@ -15,36 +15,94 @@ export type FlowStreamDisposer = () => void;
  * @remarks
  * The updater receives a setter function to update the stream's value.
  * It should return a disposer function to release any resources or subscriptions.
- * @typeparam T - The type of the stream value.
+ * @typeParam T - The type of the stream value.
  * @public
  */
 export type FlowStreamUpdater<T> = (set: FlowStreamSetter<T>) => FlowStreamDisposer;
 /**
- * Represents a reactive stream that updates its value based on an updater function.
+ * Represents a reactive stream that updates its value based on an external updater function.
  *
  * @remarks
- * FlowStream extends FlowObservable to encapsulate an update mechanism provided by an external updater function.
- * The updater is invoked during construction with a setter, and it returns a disposer to be called upon disposal.
- * Note: The stream's current value may be undefined until explicitly set.
+ * FlowStream extends FlowObservable to bridge external event sources with PicoFlow's reactive
+ * system. It's designed for integrating with event emitters, WebSocket connections, timers,
+ * or any push-based data source that sends updates over time.
  *
- * @typeparam T - The type of the stream's value.
+ * **How It Works:**
+ * 1. You provide an updater function that receives a setter callback
+ * 2. The updater sets up subscriptions to external events and calls the setter with new values
+ * 3. When the setter is called, the stream notifies all dependent effects and derivations
+ * 4. The updater returns a disposer function for cleanup
+ *
+ * **Initial Value:**
+ * The stream's value is `undefined` until the first time the setter is called. This allows
+ * you to check if any data has been received yet.
+ *
+ * **Change Detection:**
+ * The stream only notifies subscribers when the new value differs from the current value
+ * (using strict equality `===`). This prevents unnecessary updates for duplicate values.
+ *
+ * **Resource Management:**
+ * The disposer function returned by your updater is automatically called when the stream
+ * is disposed. Use it to clean up subscriptions, close connections, or clear timers.
+ *
+ * **Use Cases:**
+ * - WebSocket message streams
+ * - DOM event listeners
+ * - setInterval/setTimeout timers
+ * - Server-sent events (SSE)
+ * - Observable subscriptions from other libraries
+ * - Any push-based data source
+ *
+ * @example
+ * ```typescript
+ * // WebSocket stream
+ * const $messages = stream<string>((set) => {
+ *   const ws = new WebSocket('ws://example.com');
+ *   ws.onmessage = (event) => set(event.data);
+ *   return () => ws.close();
+ * });
+ *
+ * // Timer stream
+ * const $tick = stream<number>((set) => {
+ *   let count = 0;
+ *   const id = setInterval(() => set(count++), 1000);
+ *   return () => clearInterval(id);
+ * });
+ *
+ * // DOM event stream
+ * const $clicks = stream<MouseEvent>((set) => {
+ *   const handler = (e: MouseEvent) => set(e);
+ *   document.addEventListener('click', handler);
+ *   return () => document.removeEventListener('click', handler);
+ * });
+ *
+ * // Use in an effect
+ * effect((t) => {
+ *   const message = $messages.get(t);
+ *   if (message) {
+ *     console.log('Received:', message);
+ *   }
+ * });
+ * ```
+ *
+ * @typeParam T - The type of the values emitted by the stream.
  * @public
  */
 export declare class FlowStream<T> extends FlowObservable<T | undefined> {
     /**
      * Creates a new FlowStream.
-     * @param updater - A function that receives a setter to update the stream's value.
-     * It should return a disposer function that will be called upon disposal.
+     *
+     * @param updater - A function that receives a setter callback and returns a disposer.
+     * The setter should be called whenever new data is available. The disposer will be
+     * invoked when the stream is disposed to clean up resources.
+     *
+     * @remarks
+     * The updater is invoked immediately during construction. Make sure to return a proper
+     * cleanup function to avoid resource leaks.
+     *
      * @public
      */
     constructor(updater: FlowStreamUpdater<T>);
-    /**
-     * Retrieves the current value of the stream.
-     * @returns The current value, or undefined if no value has been set yet.
-     * @throws Error if the stream is disposed.
-     * @public
-     */
-    get(): T | undefined;
     /**
      * Disposes the stream, releasing all resources.
      * @remarks

package/dist/types/advanced/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/advanced/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,IAAI,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAC/B,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,KACvB,kBAAkB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,GAAG,SAAS,CAAC;IAC5D;;;;;OAKG;gBACS,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAOzC;;;;;OAKG;IACI,GAAG,IAAI,CAAC,GAAG,SAAS;IAK3B;;;;;;OAMG;IACa,OAAO,IAAI,IAAI;IAO/B,OAAO,CAAC,SAAS,CAAqB;IAEtC,OAAO,CAAC,IAAI;CAOf"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/advanced/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,IAAI,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAClC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,KACpB,kBAAkB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,GAAG,SAAS,CAAC;IAC/D;;;;;;;;;;;;OAYG;gBACS,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAgBzC;;;;;;OAMG;IACa,OAAO,IAAI,IAAI;IAO/B,OAAO,CAAC,SAAS,CAAqB;IAEtC,OAAO,CAAC,IAAI;CAOZ"}

package/dist/types/advanced/streamAsync.d.ts

@@ -1,32 +1,86 @@
 import { FlowObservable } from '../basic';
 import { FlowStreamUpdater } from './stream';
 /**
- * Represents an asynchronous reactive stream that updates its value based on an updater function.
+ * Represents an asynchronous reactive stream that always returns a Promise and updates based on an updater function.
  *
  * @remarks
- * A FlowStreamAsync extends FlowObservable and encapsulates a mechanism for asynchronously updating its value.
- * The updater is invoked during construction with a setter, and its returned disposer is called upon disposal.
- * Note: The stream's current value may be undefined until it is set.
+ * FlowStreamAsync extends FlowObservable to bridge external async event sources with PicoFlow's
+ * reactive system. Unlike {@link FlowStream} which returns `T | undefined`, FlowStreamAsync always
+ * returns a `Promise<T>`, making it suitable for use with async/await patterns.
  *
- * @typeparam T - The type of the stream's value.
+ * **How It Works:**
+ * 1. On construction, creates an initial Promise that resolves when the first value arrives
+ * 2. Your updater function receives a setter callback and sets up event subscriptions
+ * 3. When the setter is called with a value, the Promise resolves (first call) or a new Promise is created (subsequent calls)
+ * 4. The updater returns a disposer function for cleanup
+ *
+ * **Promise Behavior:**
+ * - **First call to setter**: Resolves the initial Promise created at construction
+ * - **Subsequent calls**: Creates a new `Promise.resolve(value)` for immediate resolution
+ * - **Reading the value**: Always returns a Promise, either pending (initial) or resolved
+ *
+ * **Change Detection:**
+ * After the first value is set, the stream only notifies subscribers when the new value
+ * differs from the previous value (using strict equality `===`). This prevents unnecessary
+ * updates for duplicate values.
+ *
+ * **Resource Management:**
+ * The disposer function returned by your updater is automatically called when the stream
+ * is disposed. Use it to clean up subscriptions, close connections, or clear timers.
+ *
+ * **Use Cases:**
+ * - Async WebSocket message streams
+ * - Server-sent events that you want to await
+ * - Async event handlers
+ * - Integration with async iterators
+ * - Any push-based async data source
+ *
+ * @example
+ * ```typescript
+ * // Async WebSocket stream
+ * const $messages = streamAsync<string>((set) => {
+ *   const ws = new WebSocket('ws://example.com');
+ *   ws.onmessage = (event) => set(event.data);
+ *   return () => ws.close();
+ * });
+ *
+ * // Use with async/await
+ * effect(async (t) => {
+ *   const message = await $messages.get(t);
+ *   console.log('Received:', message);
+ * });
+ *
+ * // Wait for the first message
+ * const firstMessage = await $messages.pick();
+ * console.log('First message:', firstMessage);
+ *
+ * // Async timer stream
+ * const $asyncTick = streamAsync<number>((set) => {
+ *   let count = 0;
+ *   const id = setInterval(() => set(count++), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ *
+ * @typeParam T - The type of the values emitted by the stream (not the Promise itself).
  * @public
  */
 export declare class FlowStreamAsync<T> extends FlowObservable<Promise<T>> {
     /**
      * Creates a new asynchronous FlowStream.
-     * @param updater - A function that receives a setter to update the stream's value.
-     * It should return a disposer function that will be called upon disposal.
-     * @remarks The updater function can invoke the setter asynchronously to update the stream.
+     *
+     * @param updater - A function that receives a setter callback and returns a disposer.
+     * The setter should be called whenever new data is available (can be called asynchronously).
+     * The disposer will be invoked when the stream is disposed to clean up resources.
+     *
+     * @remarks
+     * The updater is invoked immediately during construction. An initial Promise is created
+     * that will resolve when the setter is first called. Make sure to return a proper cleanup
+     * function to avoid resource leaks.
+     *
      * @public
      */
     constructor(updater: FlowStreamUpdater<T>);
-    /**
-     * Retrieves the current value of the stream as a Promise.
-     * @returns A Promise that resolves to the current value.
-     * @throws Error if the stream is disposed.
-     * @public
-     */
-    get(): Promise<T>;
     /**
      * Disposes the stream, releasing all resources.
      * @remarks In addition to disposing the underlying observable, this method calls the disposer

package/dist/types/advanced/streamAsync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streamAsync.d.ts","sourceRoot":"","sources":["../../../src/advanced/streamAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9D;;;;;;OAMG;gBACS,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAWzC;;;;;OAKG;IACI,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IAKxB;;;;;OAKG;IACa,OAAO,IAAI,IAAI;IAO/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAC,CAAI;IAE1B,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,SAAS,CAAqB;IAEtC,OAAO,CAAC,IAAI;CAkBf"}
+{"version":3,"file":"streamAsync.d.ts","sourceRoot":"","sources":["../../../src/advanced/streamAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACjE;;;;;;;;;;;;;OAaG;gBACS,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAoBzC;;;;;OAKG;IACa,OAAO,IAAI,IAAI;IAO/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAC,CAAI;IAE1B,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,SAAS,CAAqB;IAEtC,OAAO,CAAC,IAAI;CAkBZ"}