@ersbeth/picoflow 0.2.3 → 1.0.0

package/src/advanced/map.ts

@@ -1,83 +1,193 @@
-import { FlowState } from "../basic/";
+import { FlowState, isDisposable } 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 class FlowMap<K, V> extends FlowState<Map<K, V>> {
-    /**
-     * A reactive state that holds the most recent key and value that were set.
-     *
-     * @remarks
-     * When a key is set via {@link FlowMap.setAt}, this state is updated with
-     * the corresponding key and value.
-     *
-     * @public
-     */
-    public $lastSet: FlowState<{ key?: K; value?: V }> = new FlowState({});
+	/**
+	 * A reactive state that holds the most recent key and value that were added.
+	 *
+	 * @remarks
+	 * When a key is added via {@link FlowMap.add}, this state is updated with
+	 * the corresponding key and value.
+	 *
+	 * @public
+	 */
+	public $lastAdded = new FlowState<{ key: K; value: V } | null>(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
+	 */
+	public $lastUpdated = new FlowState<{ key: K; value: V } | null>(null);
+
+	/**
+	 * A reactive state that holds the most recent key and value that were deleted.
+	 *
+	 * @remarks
+	 * When a key is deleted via {@link FlowMap.delete}, this state is updated with
+	 * the corresponding key and its last known value.
+	 *
+	 * @public
+	 */
+	public $lastDeleted = new FlowState<{ key: K; value: V } | null>(null);
+
+	/**
+	 * Adds a new key-value pair to the map.
+	 *
+	 * @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
+	 * 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
+	 */
+	public add(key: K, value: V): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		if (this._value.has(key)) {
+			throw new Error("[PicoFlow] Key already exists");
+		}
+		this._value.set(key, value);
+		this.$lastAdded.set({ key, value });
+		this._notify();
+	}
 
-    /**
-     * A reactive state that holds the most recent key and value that were deleted.
-     *
-     * @remarks
-     * When a key is deleted via {@link FlowMap.delete}, this state is updated with
-     * the corresponding key and its last known value.
-     *
-     * @public
-     */
-    public $lastDeleted: FlowState<{ key?: K; value?: V }> = new FlowState({});
+	/**
+	 * 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
+	 */
+	public update(key: K, value: V): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		if (!this._value.has(key)) {
+			throw new Error("[PicoFlow] Key does not exist");
+		}
+		this._value.set(key, value);
+		this.$lastUpdated.set({ key, value });
+		this._notify();
+	}
 
-    /**
-     * Sets a value at the specified key in the underlying map.
-     *
-     * @param key - The key at which to set the value.
-     * @param value - The value to set.
-     * @throws If the FlowMap instance is disposed.
-     *
-     * @remarks
-     * Updates the internal map, emits the key-value pair via {@link FlowMap.$lastSet},
-     * and notifies all subscribers of the change.
-     *
-     * @public
-     */
-    public setAt(key: K, value: V): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._value.set(key, value);
-        this.$lastSet.set({ key, value });
-        this._notify();
-    }
+	/**
+	 * Deletes the value at the specified key from the underlying map.
+	 *
+	 * @param key - The key to delete.
+	 * @throws If the FlowMap instance is disposed.
+	 *
+	 * @remarks
+	 * Removes the key from the internal map, emits the deleted key and its value via {@link FlowMap.$lastDeleted},
+	 * and notifies all subscribers of the change.
+	 *
+	 * @public
+	 */
+	public delete(key: K): void {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const value = this._value.get(key);
+		if (!value) throw new Error("[PicoFlow] Key does not exist");
+		this._value.delete(key);
+		this.$lastDeleted.set({ key, value });
+		this._notify();
+	}
 
-    /**
-     * Deletes the value at the specified key from the underlying map.
-     *
-     * @param key - The key to delete.
-     * @throws If the FlowMap instance is disposed.
-     *
-     * @remarks
-     * Removes the key from the internal map, emits the deleted key and its value via {@link FlowMap.$lastDeleted},
-     * and notifies all subscribers of the change.
-     *
-     * @public
-     */
-    public delete(key: K): void {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        const value = this._value.get(key);
-        this._value.delete(key);
-        this.$lastDeleted.set({ key, value });
-        this._notify();
-    }
+	/**
+	 * Disposes the FlowMap and its values.
+	 * @param options - Disposal options.
+	 * @public
+	 */
+	override dispose(options?: { self: boolean }): void {
+		super.dispose(options);
+		this._value.forEach((item) => {
+			if (isDisposable(item)) item.dispose(options);
+		});
+		this._value.clear();
+		this.$lastAdded.dispose(options);
+		this.$lastUpdated.dispose(options);
+		this.$lastDeleted.dispose(options);
+	}
 }

package/src/advanced/resource.ts

@@ -1,56 +1,100 @@
 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 class FlowResource<T> extends FlowObservable<T | undefined> {
-    /**
-     * Creates a new FlowResource.
-     * @param fetch - An asynchronous function that retrieves the resource's value.
-     *
-     * @public
-     */
-    constructor(fetch: () => Promise<T>) {
-        super();
-        this._fetch = fetch;
-    }
+	/**
+	 * 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>) {
+		super();
+		this._fetch = fetch;
+	}
 
-    /**
-     * 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
-     */
-    public get(): T | undefined {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        return this._value;
-    }
+	/**
+	 * Internal method to get the raw value.
+	 * @internal
+	 */
+	protected _getRaw(): T | undefined {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		return this._value;
+	}
 
-    /**
-     * Asynchronously fetches a new value for the resource.
-     * @remarks
-     * Executes the internal fetch function. If the fetched value differs from the current one,
-     * updates the resource's value and notifies subscribers.
-     * @returns A Promise that resolves when the fetch operation is complete.
-     * @throws Error if the resource is disposed.
-     * @public
-     */
-    public async fetch(): Promise<void> {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        const value = await this._fetch();
-        if (value === this._value) return;
-        this._value = value;
-        this._notify();
-    }
+	/**
+	 * Asynchronously fetches a new value for the resource.
+	 * @remarks
+	 * Executes the internal fetch function. If the fetched value differs from the current one,
+	 * updates the resource's value and notifies subscribers.
+	 * @returns A Promise that resolves when the fetch operation is complete.
+	 * @throws Error if the resource is disposed.
+	 * @public
+	 */
+	public async fetch(): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		const value = await this._fetch();
+		if (value === this._value) return;
+		this._value = value;
+		this._notify();
+	}
 
-    /* INTERNAL ------------------------------------------------ */
+	/* INTERNAL ------------------------------------------------ */
 
-    private _fetch: () => Promise<T>;
+	private _fetch: () => Promise<T>;
 }

package/src/advanced/resourceAsync.ts

@@ -1,57 +1,77 @@
 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
  */
 export class FlowResourceAsync<T> extends FlowObservable<Promise<T>> {
-    /**
-     * Creates a new FlowResource.
-     * @param fetch - An asynchronous function that retrieves the resource's value.
-     * @public
-     */
-    constructor(fetch: () => Promise<T>) {
-        super();
-        this._fetch = fetch;
-    }
+	/**
+	 * Creates a new FlowResource.
+	 * @param fetch - An asynchronous function that retrieves the resource's value.
+	 * @public
+	 */
+	constructor(fetch: () => Promise<T>) {
+		super();
+		this._fetch = fetch;
+	}
 
-    /**
-     * 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
-     */
-    public get(): Promise<T> {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        if (!this._value) this._value = this._fetch();
-        return this._value;
-    }
+	/**
+	 * Internal method to get the raw value.
+	 * @internal
+	 */
+	protected _getRaw(): Promise<T> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		if (!this._value) this._value = this._fetch();
+		return this._value;
+	}
 
-    /**
-     * Asynchronously fetches a new value for the resource.
-     * @remarks
-     * Executes the internal fetch function. If the fetched value differs from the current one,
-     * updates the resource's value and notifies subscribers.
-     * @returns A Promise that resolves when the fetch operation is complete.
-     * @throws Error if the resource is disposed.
-     * @public
-     */
-    public async fetch(): Promise<void> {
-        if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-        this._value = this._fetch();
-        this._notify();
-    }
+	/**
+	 * Asynchronously fetches a new value for the resource.
+	 * @remarks
+	 * Executes the internal fetch function. If the fetched value differs from the current one,
+	 * updates the resource's value and notifies subscribers.
+	 * @returns A Promise that resolves when the fetch operation is complete.
+	 * @throws Error if the resource is disposed.
+	 * @public
+	 */
+	public async fetch(): Promise<void> {
+		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+		this._value = this._fetch();
+		this._notify();
+	}
 
-    /* INTERNAL ------------------------------------------------ */
+	/* INTERNAL ------------------------------------------------ */
 
-    private _fetch: () => Promise<T>;
+	private _fetch: () => Promise<T>;
 }