@ersbeth/picoflow 0.2.4 → 1.0.0

package/dist/types/creators.d.ts

@@ -1,94 +1,339 @@
 import { FlowMap, FlowResource, FlowResourceAsync, FlowStream, FlowStreamAsync } from './advanced/';
 import { FlowArray } from './advanced/array';
-import { FlowConstant, FlowDerivation, FlowEffect, FlowSignal, FlowState, FlowGetter, FlowWatcher } from './basic/';
+import { TrackingContext, FlowConstant, FlowDerivation, FlowEffect, FlowSignal, FlowState } 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 declare function signal(): 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 declare function constant<T>(value: T | (() => T)): FlowConstant<T>;
 /**
- * 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 declare function state<T>(value: T | (() => T)): FlowState<T>;
 /**
- * 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 declare function resource<T>(fn: () => Promise<T>): FlowResource<T>;
 /**
- * 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 declare function resourceAsync<T>(fn: () => Promise<T>): FlowResourceAsync<T>;
 /**
- * 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 declare function stream<T>(updater: (set: (value: T) => void) => () => void): FlowStream<T>;
 /**
- * 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 declare function streamAsync<T>(updater: (set: (value: T) => void) => () => void): FlowStreamAsync<T>;
 /**
  * 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 declare function derivation<T>(fn: (get: FlowGetter, watch: FlowWatcher) => T): FlowDerivation<T>;
+export declare function derivation<T>(fn: (t: TrackingContext) => T): FlowDerivation<T>;
 /**
  * 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 declare function effect(fn: (get: FlowGetter, watch: FlowWatcher) => void): FlowEffect;
+export declare function effect(fn: (t: TrackingContext) => void): FlowEffect;
 /**
- * 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 declare function map<K extends string | number | symbol, V>(initial?: Record<K, V>): FlowMap<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 declare function array<T>(initial?: T[]): FlowArray<T>;

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

@@ -1 +1 @@
-{"version":3,"file":"creators.d.ts","sourceRoot":"","sources":["../../src/creators.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,eAAe,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EACH,YAAY,EACZ,cAAc,EACd,UAAU,EACV,UAAU,EACV,SAAS,EACZ,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,UAAU,CAEnC;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACpB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,GACjD,UAAU,CAAC,CAAC,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,GACjD,eAAe,CAAC,CAAC,CAAC,CAEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EACxB,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,CAAC,GAC/C,cAAc,CAAC,CAAC,CAAC,CAEnB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAClB,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI,GAClD,UAAU,CAEZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,EACrD,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAEpD"}
+{"version":3,"file":"creators.d.ts","sourceRoot":"","sources":["../../src/creators.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EACN,YAAY,EACZ,cAAc,EACd,UAAU,EACV,UAAU,EACV,SAAS,EACT,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,MAAM,IAAI,UAAU,CAEnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAEjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAE3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAEjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAE3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACvB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,GAC9C,UAAU,CAAC,CAAC,CAAC,CAEf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,GAC9C,eAAe,CAAC,CAAC,CAAC,CAEpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC3B,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,CAAC,GAC3B,cAAc,CAAC,CAAC,CAAC,CAEnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,UAAU,CAEnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,EACxD,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAIf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAEpD"}

package/dist/types/index.d.ts

@@ -1,13 +1,66 @@
 /**
  * @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';
-export { isDisposable, FlowDerivation, FlowEffect, FlowObservable, FlowSignal, FlowState, FlowConstant, type FlowGetter, type FlowWatcher, type FlowDisposable, } from './basic/';
-export { FlowResource, FlowMap, FlowResourceAsync, FlowStreamAsync, FlowStream, FlowArray, type FlowStreamDisposer, type FlowStreamSetter, type FlowStreamUpdater, type FlowArrayAction, } from './advanced/';
-export { from, SolidState, SolidResource, SolidDerivation, type SolidObservable, type SolidGetter, } from './solid/';
+export { FlowArray, type FlowArrayAction, FlowMap, FlowResource, FlowResourceAsync, FlowStream, FlowStreamAsync, type FlowStreamDisposer, type FlowStreamSetter, type FlowStreamUpdater, } from './advanced/';
+export { FlowConstant, FlowDerivation, type FlowDisposable, FlowEffect, FlowObservable, FlowSignal, FlowState, isDisposable, TrackingContext, } from './basic/';
+export { array, constant, derivation, effect, map, resource, resourceAsync, signal, state, stream, streamAsync, } from './creators';
+export { from, type NotPromise, SolidDerivation, type SolidGetter, type SolidObservable, SolidResource, SolidState, } from './solid/';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACH,MAAM,EACN,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,UAAU,EACV,MAAM,EACN,GAAG,EACH,KAAK,EACL,WAAW,EACX,aAAa,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACH,YAAY,EACZ,cAAc,EACd,UAAU,EACV,cAAc,EACd,UAAU,EACV,SAAS,EACT,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,GACtB,MAAM,UAAU,CAAC;AAElB,OAAO,EACH,YAAY,EACZ,OAAO,EACP,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACvB,MAAM,aAAa,CAAC;AAErB,OAAO,EACH,IAAI,EACJ,UAAU,EACV,aAAa,EACb,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,WAAW,GACnB,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,EACN,SAAS,EACT,KAAK,eAAe,EACpB,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACtB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,YAAY,EACZ,cAAc,EACd,KAAK,cAAc,EACnB,UAAU,EACV,cAAc,EACd,UAAU,EACV,SAAS,EACT,YAAY,EACZ,eAAe,GACf,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,KAAK,EACL,QAAQ,EACR,UAAU,EACV,MAAM,EACN,GAAG,EACH,QAAQ,EACR,aAAa,EACb,MAAM,EACN,KAAK,EACL,MAAM,EACN,WAAW,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACN,IAAI,EACJ,KAAK,UAAU,EACf,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,aAAa,EACb,UAAU,GACV,MAAM,UAAU,CAAC"}

package/dist/types/solid/converters.d.ts

@@ -1,5 +1,5 @@
-import { SolidResource, SolidDerivation } from './primitives';
-import { FlowObservable, FlowGetter } from '../basic';
+import { FlowObservable, TrackingContext } from '../basic';
+import { SolidDerivation, SolidResource } from './primitives';
 /**
  * Utility type that excludes Promise types from T.
  * Used to ensure type safety for synchronous derivations/resources.
@@ -42,7 +42,7 @@ export declare function from<T>(flow: FlowObservable<Promise<NotPromise<T>>> | F
  *
  * @public
  */
-export declare function from<T>(flow: (get: FlowGetter) => NotPromise<T>): SolidDerivation<NotPromise<T>>;
+export declare function from<T>(flow: (t: TrackingContext) => NotPromise<T>): SolidDerivation<NotPromise<T>>;
 /**
  * Converts a getter function returning a Promise into a SolidResource.
  *
@@ -51,7 +51,7 @@ export declare function from<T>(flow: (get: FlowGetter) => NotPromise<T>): Solid
  *
  * @public
  */
-export declare function from<T>(flow: (get: FlowGetter) => Promise<NotPromise<T>>): SolidResource<NotPromise<T>>;
+export declare function from<T>(flow: (t: TrackingContext) => Promise<NotPromise<T>>): SolidResource<NotPromise<T>>;
 /**
  * Converts a getter function into a Solid derivation or resource, depending on whether the returned value is synchronous or asynchronous.
  *
@@ -60,5 +60,5 @@ export declare function from<T>(flow: (get: FlowGetter) => Promise<NotPromise<T>
  *
  * @public
  */
-export declare function from<T>(flow: ((get: FlowGetter) => NotPromise<T>) | ((get: FlowGetter) => Promise<NotPromise<T>>)): SolidDerivation<T> | SolidResource<T>;
+export declare function from<T>(flow: ((t: TrackingContext) => NotPromise<T>) | ((t: TrackingContext) => Promise<NotPromise<T>>)): SolidDerivation<T> | SolidResource<T>;
 //# sourceMappingURL=converters.d.ts.map

package/dist/types/solid/converters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/solid/converters.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAc,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAc,cAAc,EAAE,KAAK,UAAU,EAAkB,MAAM,UAAU,CAAC;AAsEvF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAEnE;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACpG;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7F;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAClB,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAC7E,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAClG;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACzG;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAClB,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAC3F,eAAe,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../../../src/solid/converters.ts"],"names":[],"mappings":"AACA,OAAO,EAGN,cAAc,EACd,KAAK,eAAe,EACpB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAc,MAAM,cAAc,CAAC;AAuI/E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAEnE;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1C,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAChC;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GACjC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAC1E,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,UAAU,CAAC,CAAC,CAAC,GACzC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAClD,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAChC;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACrB,IAAI,EACD,CAAC,CAAC,CAAC,EAAE,eAAe,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,GACvC,CAAC,CAAC,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GACjD,eAAe,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC"}

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

@@ -1,3 +1,3 @@
-export { from } from './converters';
-export { SolidState, SolidResource, SolidDerivation, type SolidObservable, type SolidGetter } from './primitives';
+export { from, type NotPromise } from './converters';
+export { SolidDerivation, type SolidGetter, type SolidObservable, SolidResource, SolidState, } from './primitives';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/solid/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/solid/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EACN,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,aAAa,EACb,UAAU,GACV,MAAM,cAAc,CAAC"}

package/dist/types/solid/primitives.d.ts

@@ -19,7 +19,30 @@ export interface SolidObservable<T> {
     get: () => T;
 }
 /**
- * Solid-style state container, similar to a writable signal.
+ * Solid-style state container wrapping SolidJS's createSignal, providing a writable reactive signal.
+ *
+ * @remarks
+ * SolidState is a thin wrapper around SolidJS's `createSignal` that provides a class-based
+ * interface consistent with PicoFlow's API style. It's used internally by PicoFlow's Solid
+ * integration but can also be used directly in Solid components.
+ *
+ * Unlike PicoFlow's {@link FlowState} which uses explicit tracking context, SolidState
+ * relies on SolidJS's automatic dependency tracking within reactive contexts like
+ * `createEffect` or component render functions.
+ *
+ * @example
+ * ```typescript
+ * const count = new SolidState(0);
+ *
+ * // In a Solid component
+ * function Counter() {
+ *   return <div>{count.get()}</div>; // Automatically reactive
+ * }
+ *
+ * // Update the value
+ * count.set(1);
+ * count.set(prev => prev + 1);
+ * ```
  *
  * @typeParam T - The value type.
  * @public
@@ -40,7 +63,35 @@ export declare class SolidState<T> implements SolidObservable<T> {
     constructor(initialValue: T);
 }
 /**
- * Solid-style derivation, similar to a computed/memoized value.
+ * Solid-style derivation wrapping SolidJS's createMemo, providing a computed reactive value.
+ *
+ * @remarks
+ * SolidDerivation is a thin wrapper around SolidJS's `createMemo` that provides a class-based
+ * interface consistent with PicoFlow's API style. It creates a memoized computation that
+ * automatically tracks its dependencies and recomputes only when they change.
+ *
+ * Unlike PicoFlow's {@link FlowDerivation} which uses explicit tracking context, SolidDerivation
+ * relies on SolidJS's automatic dependency tracking. The computation function runs within
+ * SolidJS's reactive scope and automatically subscribes to any signals accessed during execution.
+ *
+ * **Memoization:**
+ * The computed value is cached and only recomputed when tracked dependencies change,
+ * providing efficient derived state management.
+ *
+ * @example
+ * ```typescript
+ * const firstName = new SolidState('John');
+ * const lastName = new SolidState('Doe');
+ *
+ * const fullName = new SolidDerivation(() => {
+ *   return `${firstName.get()} ${lastName.get()}`;
+ * });
+ *
+ * // In a Solid component
+ * function Display() {
+ *   return <div>{fullName.get()}</div>; // Automatically updates
+ * }
+ * ```
  *
  * @typeParam T - The value type.
  * @public
@@ -57,7 +108,48 @@ export declare class SolidDerivation<T> implements SolidObservable<T> {
     constructor(calculator: SolidGetter<T>);
 }
 /**
- * Solid-style resource, similar to an async resource or data loader.
+ * Solid-style resource wrapping SolidJS's createResource, providing async data loading with reactive state.
+ *
+ * @remarks
+ * SolidResource is a thin wrapper around SolidJS's `createResource` that provides a class-based
+ * interface consistent with PicoFlow's API style. It manages asynchronous data fetching with
+ * built-in loading states, error handling, and automatic reactivity.
+ *
+ * Unlike PicoFlow's {@link FlowResource} or {@link FlowResourceAsync}, SolidResource integrates
+ * directly with SolidJS's Suspense and ErrorBoundary mechanisms, providing a first-class async
+ * data loading experience in Solid applications.
+ *
+ * **Resource States:**
+ * - `unresolved`: Initial state before first fetch
+ * - `pending`: Fetch is in progress
+ * - `ready`: Data has been successfully loaded
+ * - `refreshing`: Refetching while previous data is still available
+ * - `errored`: Fetch failed with an error
+ *
+ * **Properties:**
+ * - `get()`: Returns the current value (or undefined if not ready)
+ * - `state()`: Returns the current loading state
+ * - `latest()`: Returns the most recent successfully loaded value
+ * - `refetch()`: Triggers a new fetch operation
+ *
+ * @example
+ * ```typescript
+ * const user = new SolidResource(async () => {
+ *   const res = await fetch('/api/user');
+ *   return res.json();
+ * });
+ *
+ * // In a Solid component
+ * function UserProfile() {
+ *   return (
+ *     <div>
+ *       {user.state() === 'pending' && <p>Loading...</p>}
+ *       {user.state() === 'ready' && <p>Name: {user.get()?.name}</p>}
+ *       <button onClick={() => user.refetch()}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  *
  * @typeParam T - The value type.
  * @public
@@ -70,7 +162,7 @@ export declare class SolidResource<T> implements SolidObservable<T | undefined>
     /**
      * Returns the current resource state.
      */
-    readonly state: () => 'unresolved' | 'pending' | 'errored' | 'ready' | 'refreshing';
+    readonly state: () => "unresolved" | "pending" | "errored" | "ready" | "refreshing";
     /**
      * Returns the latest successfully loaded value (or undefined).
      */

package/dist/types/solid/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/solid/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,eAAe,EAAG,MAAM,UAAU,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAC9B;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IACpD;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAE9C;;;OAGG;gBACS,YAAY,EAAE,CAAC;CAK9B;AAGD;;;;;GAKG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IACzD;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEtB;;;OAGG;gBACS,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;CAIzC;AAED;;;;;GAKG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,GAAG,SAAS,CAAC;IACnE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,CAAC;IACpF;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACrC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAE7B;;;OAGG;gBACS,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC;CAOzD"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/solid/primitives.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,KAAK,eAAe,EACpB,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IACvD;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAE9C;;;OAGG;gBACS,YAAY,EAAE,CAAC;CAK3B;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAC5D;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEtB;;;OAGG;gBACS,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;CAItC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,GAAG,SAAS,CAAC;IACtE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MACb,YAAY,GACZ,SAAS,GACT,SAAS,GACT,OAAO,GACP,YAAY,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACrC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAE7B;;;OAGG;gBACS,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC;CAOtD"}