@ersbeth/picoflow 0.2.3 → 1.0.0

package/src/creators.ts

@@ -1,152 +1,395 @@
 import {
-    FlowMap,
-    FlowResource,
-    FlowResourceAsync,
-    FlowStream,
-    FlowStreamAsync,
+	FlowMap,
+	FlowResource,
+	FlowResourceAsync,
+	FlowStream,
+	FlowStreamAsync,
 } from "./advanced/";
 import { FlowArray } from "./advanced/array";
+import type { TrackingContext } from "./basic/";
 import {
-    FlowConstant,
-    FlowDerivation,
-    FlowEffect,
-    FlowSignal,
-    FlowState,
+	FlowConstant,
+	FlowDerivation,
+	FlowEffect,
+	FlowSignal,
+	FlowState,
 } from "./basic/";
-import type { FlowGetter, FlowWatcher } from "./basic/";
 
 /**
  * Creates a new reactive signal.
+ *
  * @returns A new instance of {@link FlowSignal}.
+ *
+ * @remarks
+ * A signal is the simplest reactive primitive - it doesn't hold a value, but can be triggered
+ * to notify dependent effects and derivations. Use signals when you need event-like notifications
+ * without associated data.
+ *
+ * @example
+ * ```typescript
+ * const $refresh = signal();
+ *
+ * effect((t) => {
+ *   $refresh.watch(t);
+ *   console.log('Refreshing...');
+ * });
+ *
+ * $refresh.trigger(); // Logs: "Refreshing..."
+ * ```
+ *
  * @public
  */
 export function signal(): FlowSignal {
-    return new FlowSignal();
+	return new FlowSignal();
 }
 
 /**
  * Creates a new reactive constant.
- * @param value - The value or a function that returns the value.
+ *
+ * @typeParam T - The type of the constant value.
+ * @param value - The value or a function that returns the value (for lazy initialization).
  * @returns A new instance of {@link FlowConstant}.
+ *
+ * @remarks
+ * A constant is an immutable reactive value that never changes after initialization.
+ * It can be initialized eagerly (direct value) or lazily (function). Use constants for
+ * configuration, computed-once values, or expensive initialization that should only run once.
+ *
+ * @example
+ * ```typescript
+ * // Eager initialization
+ * const $config = constant({ apiUrl: 'https://api.example.com' });
+ *
+ * // Lazy initialization
+ * const $computed = constant(() => expensiveCalculation());
+ * ```
+ *
  * @public
  */
 export function constant<T>(value: T | (() => T)): FlowConstant<T> {
-    return new FlowConstant<T>(value);
+	return new FlowConstant<T>(value);
 }
 
 /**
- * Creates a new reactive state holding a value.
- * @typeparam T - The type of the state value.
- * @param value - The initial value for the state.
+ * Creates a new reactive state holding a mutable value.
+ *
+ * @typeParam T - The type of the state value.
+ * @param value - The initial value for the state, or a function returning the initial value.
  * @returns A new instance of {@link FlowState}.
+ *
+ * @remarks
+ * State is the most common reactive primitive - a mutable container that notifies dependents
+ * when its value changes. Use `set()` to update the value and `get(t)` or `pick()` to read it.
+ *
+ * @example
+ * ```typescript
+ * const $count = state(0);
+ *
+ * effect((t) => {
+ *   console.log($count.get(t));
+ * });
+ *
+ * $count.set(1); // Logs: 1
+ * $count.set(n => n + 1); // Logs: 2
+ * ```
+ *
  * @public
  */
 export function state<T>(value: T | (() => T)): FlowState<T> {
-    return new FlowState(value);
+	return new FlowState(value);
 }
 
 /**
- * Creates a new reactive resource that asynchronously fetches its value.
- * @typeparam T - The type of the resource value.
+ * Creates a new reactive resource that asynchronously fetches its value, returning `T | undefined`.
+ *
+ * @typeParam T - The type of the resource value.
  * @param fn - An asynchronous function that fetches the resource value.
  * @returns A new instance of {@link FlowResource}.
+ *
+ * @remarks
+ * A resource manages async data fetching with reactive updates. Unlike {@link resourceAsync},
+ * this returns the resolved value directly (or `undefined` if not fetched yet), making it
+ * easier to work with in synchronous contexts. Call `fetch()` to trigger the async operation.
+ *
+ * @example
+ * ```typescript
+ * const $user = resource(() => fetch('/api/user').then(r => r.json()));
+ *
+ * // Trigger fetch
+ * await $user.fetch();
+ *
+ * // Use in effect
+ * effect((t) => {
+ *   const user = $user.get(t);
+ *   if (user) {
+ *     console.log(user.name);
+ *   }
+ * });
+ * ```
+ *
  * @public
  */
 export function resource<T>(fn: () => Promise<T>): FlowResource<T> {
-    return new FlowResource(fn);
+	return new FlowResource(fn);
 }
 
 /**
- * Creates a new reactive asynchronous resource that fetches its value.
- * @typeparam T - The type of the resource value.
+ * Creates a new reactive asynchronous resource that always returns a Promise.
+ *
+ * @typeParam T - The type of the resource value.
  * @param fn - An asynchronous function that fetches the resource value.
  * @returns A new instance of {@link FlowResourceAsync}.
+ *
+ * @remarks
+ * An async resource manages async data fetching and always returns a Promise, making it
+ * ideal for async/await patterns. Unlike {@link resource}, the Promise is created lazily
+ * on first access and cached. Call `fetch()` to create a new Promise and trigger a refetch.
+ *
+ * @example
+ * ```typescript
+ * const $data = resourceAsync(() => fetch('/api/data').then(r => r.json()));
+ *
+ * // Use with async/await
+ * effect(async (t) => {
+ *   const data = await $data.get(t);
+ *   console.log(data);
+ * });
+ *
+ * // Refetch
+ * await $data.fetch();
+ * ```
+ *
  * @public
  */
 export function resourceAsync<T>(fn: () => Promise<T>): FlowResourceAsync<T> {
-    return new FlowResourceAsync(fn);
+	return new FlowResourceAsync(fn);
 }
 
 /**
- * Creates a new reactive stream.
- * @typeparam T - The type of the stream value.
+ * Creates a new reactive stream that bridges external event sources with PicoFlow's reactive system.
+ *
+ * @typeParam T - The type of the stream value.
  * @param updater - A function that receives a setter to update the stream's value.
  * It should return a disposer function to clean up resources.
  * @returns A new instance of {@link FlowStream}.
+ *
+ * @remarks
+ * Streams are ideal for integrating push-based data sources like WebSockets, DOM events,
+ * timers, or any event emitter. The updater sets up subscriptions and calls the setter
+ * when new data arrives. The returned disposer is called on cleanup.
+ *
+ * @example
+ * ```typescript
+ * // WebSocket stream
+ * const $messages = stream<string>((set) => {
+ *   const ws = new WebSocket('ws://example.com');
+ *   ws.onmessage = (e) => set(e.data);
+ *   return () => ws.close();
+ * });
+ *
+ * // Timer stream
+ * const $tick = stream<number>((set) => {
+ *   let count = 0;
+ *   const id = setInterval(() => set(count++), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ *
  * @public
  */
 export function stream<T>(
-    updater: (set: (value: T) => void) => () => void,
+	updater: (set: (value: T) => void) => () => void,
 ): FlowStream<T> {
-    return new FlowStream(updater);
+	return new FlowStream(updater);
 }
 
 /**
- * Creates a new reactive asynchronous stream.
- * @typeparam T - The type of the stream value.
+ * Creates a new reactive asynchronous stream that always returns a Promise.
+ *
+ * @typeParam T - The type of the stream value.
  * @param updater - A function that receives a setter to update the stream's value.
  * It should return a disposer function to clean up resources.
  * @returns A new instance of {@link FlowStreamAsync}.
+ *
+ * @remarks
+ * Async streams are ideal for push-based async data sources where you want to use async/await.
+ * Unlike {@link stream}, this always returns a Promise that resolves to the value. The initial
+ * Promise is created on construction and resolves when the setter is first called.
+ *
+ * @example
+ * ```typescript
+ * const $asyncMessages = streamAsync<string>((set) => {
+ *   const ws = new WebSocket('ws://example.com');
+ *   ws.onmessage = (e) => set(e.data);
+ *   return () => ws.close();
+ * });
+ *
+ * effect(async (t) => {
+ *   const message = await $asyncMessages.get(t);
+ *   console.log('Received:', message);
+ * });
+ * ```
+ *
  * @public
  */
 export function streamAsync<T>(
-    updater: (set: (value: T) => void) => () => void,
+	updater: (set: (value: T) => void) => () => void,
 ): FlowStreamAsync<T> {
-    return new FlowStreamAsync(updater);
+	return new FlowStreamAsync(updater);
 }
 
 /**
  * Creates a new reactive derivation whose value is computed based on other reactive signals.
- * @typeparam T - The type of the derived value.
- * @param fn - A function that computes the derived value. It receives a getter and a watcher
- * function to access and register dependencies.
+ *
+ * @typeParam T - The type of the derived value.
+ * @param fn - A function that computes the derived value using a tracking context.
  * @returns A new instance of {@link FlowDerivation}.
+ *
+ * @remarks
+ * A derivation is a computed reactive value that automatically tracks its dependencies and
+ * recomputes when they change. The computation is lazy - it runs only when the value is
+ * accessed, not on construction. Use derivations to create derived state without manual
+ * dependency management.
+ *
+ * @example
+ * ```typescript
+ * const $firstName = state('John');
+ * const $lastName = state('Doe');
+ *
+ * const $fullName = derivation((t) => {
+ *   return `${$firstName.get(t)} ${$lastName.get(t)}`;
+ * });
+ *
+ * effect((t) => {
+ *   console.log($fullName.get(t)); // Logs: "John Doe"
+ * });
+ *
+ * $firstName.set('Jane'); // Logs: "Jane Doe"
+ * ```
+ *
  * @public
  */
 export function derivation<T>(
-    fn: (get: FlowGetter, watch: FlowWatcher) => T,
+	fn: (t: TrackingContext) => T,
 ): FlowDerivation<T> {
-    return new FlowDerivation(fn);
+	return new FlowDerivation(fn);
 }
 
 /**
  * Creates a new reactive effect that executes a side-effect function based on its dependencies.
- * @param fn - A function that performs side effects. It receives a getter and a watcher
- * function for tracking reactive dependencies.
+ *
+ * @param fn - A function that performs side effects using a tracking context.
  * @returns A new instance of {@link FlowEffect}.
+ *
+ * @remarks
+ * An effect is a reactive computation that runs immediately and re-runs whenever its tracked
+ * dependencies change. Use effects for side effects like logging, DOM updates, network requests,
+ * or any operation that should respond to reactive state changes.
+ *
+ * The effect executes immediately upon creation and provides a tracking context (`t`) that you
+ * use to explicitly mark dependencies via `observable.get(t)`. Use `observable.pick()` for
+ * reads that shouldn't trigger re-runs.
+ *
+ * @example
+ * ```typescript
+ * const $count = state(0);
+ *
+ * const fx = effect((t) => {
+ *   console.log('Count is:', $count.get(t));
+ * });
+ *
+ * $count.set(1); // Logs: "Count is: 1"
+ * $count.set(2); // Logs: "Count is: 2"
+ *
+ * // Clean up when done
+ * fx.dispose();
+ * ```
+ *
  * @public
  */
-export function effect(
-    fn: (get: FlowGetter, watch: FlowWatcher) => void,
-): FlowEffect {
-    return new FlowEffect(fn);
+export function effect(fn: (t: TrackingContext) => void): FlowEffect {
+	return new FlowEffect(fn);
 }
 
 /**
- * Creates a new reactive map state.
- * @typeparam K - The type of the keys.
- * @typeparam V - The type of the values.
+ * Creates a new reactive map state with fine-grained tracking of operations.
+ *
+ * @typeParam K - The type of the keys.
+ * @typeParam V - The type of the values.
  * @param initial - An optional record of key-value pairs to initialize the map.
  * @returns A new instance of {@link FlowMap}.
+ *
  * @remarks
- * The initial record is converted to a native Map before being used.
+ * A reactive map wraps a native JavaScript Map and provides multiple levels of reactivity:
+ * tracking the entire map, tracking individual set operations, and tracking individual
+ * delete operations. The initial record (if provided) is converted to a native Map.
+ *
+ * @example
+ * ```typescript
+ * const $users = map<string, User>({
+ *   'user1': { name: 'John', age: 30 }
+ * });
+ *
+ * // Track the whole map
+ * effect((t) => {
+ *   console.log('Users:', $users.get(t).size);
+ * });
+ *
+ * // Track additions
+ * effect((t) => {
+ *   const { key, value } = $users.$lastSet.get(t);
+ *   if (key) console.log(`Added: ${key}`);
+ * });
+ *
+ * $users.setAt('user2', { name: 'Jane', age: 25 });
+ * ```
+ *
  * @public
  */
 export function map<K extends string | number | symbol, V>(
-    initial?: Record<K, V>,
+	initial?: Record<K, V>,
 ): FlowMap<K, V> {
-    return new FlowMap<K, V>(
-        new Map<K, V>(initial ? (Object.entries(initial) as [K, V][]) : []),
-    );
+	return new FlowMap<K, V>(
+		new Map<K, V>(initial ? (Object.entries(initial) as [K, V][]) : []),
+	);
 }
 
 /**
- * Creates a new reactive array.
- * @typeparam T - The type of the array elements.
+ * Creates a new reactive array with mutation methods and fine-grained action tracking.
+ *
+ * @typeParam T - The type of the array elements.
  * @param initial - An optional array of initial values.
  * @returns A new instance of {@link FlowArray}.
+ *
+ * @remarks
+ * A reactive array provides array-like mutation methods (push, pop, shift, unshift, splice)
+ * and tracks the last operation performed via `$lastAction`. This enables both whole-array
+ * reactivity and fine-grained tracking of specific mutations.
+ *
+ * The array automatically disposes disposable items when they are removed (if they implement
+ * the FlowDisposable interface).
+ *
+ * @example
+ * ```typescript
+ * const $items = array([1, 2, 3]);
+ *
+ * // Track the whole array
+ * effect((t) => {
+ *   console.log('Items:', $items.get(t));
+ * });
+ *
+ * // Track the last action
+ * effect((t) => {
+ *   const action = $items.$lastAction.get(t);
+ *   console.log('Action:', action.type);
+ * });
+ *
+ * $items.push(4); // Logs action: "push"
+ * $items.pop();   // Logs action: "pop"
+ * ```
+ *
  * @public
  */
 export function array<T>(initial?: T[]): FlowArray<T> {
-    return new FlowArray<T>(initial);
+	return new FlowArray<T>(initial);
 }

package/src/index.ts

@@ -1,56 +1,109 @@
 /**
  * @packageDocumentation
  *
- * PicoFlow is a lightweight reactive dataflow library that provides a set of
- * reactive primitives such as signals, state, resources, streams, derivations,
- * effects, and reactive maps.
+ * # PicoFlow
  *
+ * PicoFlow is a lightweight reactive dataflow library that provides a comprehensive set of
+ * reactive primitives for building reactive applications with explicit dependency tracking.
+ *
+ * ## Core Concepts
+ *
+ * **Reactive Primitives:**
+ * - {@link FlowSignal}: Event-like notifications without values
+ * - {@link FlowState}: Mutable reactive values
+ * - {@link FlowConstant}: Immutable reactive values (computed once)
+ * - {@link FlowDerivation}: Computed values that track dependencies
+ * - {@link FlowEffect}: Side effects that run when dependencies change
+ *
+ * **Advanced Primitives:**
+ * - {@link FlowArray}: Reactive arrays with mutation tracking
+ * - {@link FlowMap}: Reactive maps with operation tracking
+ * - {@link FlowResource}: Async data fetching returning `T | undefined`
+ * - {@link FlowResourceAsync}: Async data fetching returning `Promise<T>`
+ * - {@link FlowStream}: Event streams from external sources
+ * - {@link FlowStreamAsync}: Async event streams returning Promises
+ *
+ * **Tracking Context:**
+ * - {@link TrackingContext}: The core mechanism for explicit dependency tracking
+ * - Use `observable.get(t)` to read with tracking
+ * - Use `observable.pick()` to read without tracking
+ * - Use `signal.watch(t)` to track signals without values
+ *
+ * ## Key Features
+ *
+ * - **Explicit tracking**: Full control over what triggers re-execution via TrackingContext
+ * - **Lazy evaluation**: Derivations compute only when accessed
+ * - **Fine-grained reactivity**: Track specific operations on collections
+ * - **Resource management**: Automatic cleanup with dispose patterns
+ * - **SolidJS integration**: Seamless bridge to SolidJS primitives
+ *
+ * ## Basic Usage
+ *
+ * ```typescript
+ * import { state, effect, derivation } from 'picoflow';
+ *
+ * // Create reactive state
+ * const $count = state(0);
+ *
+ * // Create derived value
+ * const $double = derivation((t) => $count.get(t) * 2);
+ *
+ * // Create effect
+ * effect((t) => {
+ *   console.log('Count:', $count.get(t), 'Double:', $double.get(t));
+ * });
+ *
+ * // Update state
+ * $count.set(1); // Logs: "Count: 1 Double: 2"
+ * ```
+ *
+ * @see {@link https://github.com/yourusername/picoflow | GitHub Repository}
  */
+
 export {
-    signal,
-    state,
-    constant,
-    resource,
-    stream,
-    derivation,
-    effect,
-    map,
-    array,
-    streamAsync,
-    resourceAsync,
-} from "./creators";
+	FlowArray,
+	type FlowArrayAction,
+	FlowMap,
+	FlowResource,
+	FlowResourceAsync,
+	FlowStream,
+	FlowStreamAsync,
+	type FlowStreamDisposer,
+	type FlowStreamSetter,
+	type FlowStreamUpdater,
+} from "./advanced/";
 
 export {
-    isDisposable,
-    FlowDerivation,
-    FlowEffect,
-    FlowObservable,
-    FlowSignal,
-    FlowState,
-    FlowConstant,
-    type FlowGetter,
-    type FlowWatcher,
-    type FlowDisposable,
+	FlowConstant,
+	FlowDerivation,
+	type FlowDisposable,
+	FlowEffect,
+	FlowObservable,
+	FlowSignal,
+	FlowState,
+	isDisposable,
+	TrackingContext,
 } from "./basic/";
-
 export {
-    FlowResource,
-    FlowMap,
-    FlowResourceAsync,
-    FlowStreamAsync,
-    FlowStream,
-    FlowArray,
-    type FlowStreamDisposer,
-    type FlowStreamSetter,
-    type FlowStreamUpdater,
-    type FlowArrayAction,
-} from "./advanced/";
+	array,
+	constant,
+	derivation,
+	effect,
+	map,
+	resource,
+	resourceAsync,
+	signal,
+	state,
+	stream,
+	streamAsync,
+} from "./creators";
 
 export {
-    from,
-    SolidState,
-    SolidResource,
-    SolidDerivation,
-    type SolidObservable,
-    type SolidGetter,
+	from,
+	type NotPromise,
+	SolidDerivation,
+	type SolidGetter,
+	type SolidObservable,
+	SolidResource,
+	SolidState,
 } from "./solid/";