@ersbeth/picoflow 0.2.3 → 1.0.0

package/src/solid/converters.ts

@@ -1,73 +1,143 @@
-import { FlowDerivation, FlowEffect, FlowObservable, type FlowGetter } from '@ersbeth/picoflow';
-import { onCleanup, onMount } from 'solid-js';
-import { SolidResource, SolidState, type SolidDerivation } from './primitives';
-
+import { onCleanup, onMount } from "solid-js";
+import {
+	FlowDerivation,
+	FlowEffect,
+	FlowObservable,
+	type TrackingContext,
+} from "../basic";
+import { type SolidDerivation, SolidResource, SolidState } from "./primitives";
 
+/**
+ * Converts a synchronous FlowObservable into a SolidJS signal.
+ *
+ * @param state - The FlowObservable to convert.
+ * @returns A SolidDerivation that mirrors the FlowObservable's value.
+ *
+ * @remarks
+ * This internal helper bridges PicoFlow's reactive system with SolidJS by:
+ * 1. Reading the initial value without tracking (using `pick()`)
+ * 2. Creating a FlowEffect that tracks the observable and updates the Solid signal
+ * 3. Properly disposing the effect when the Solid component unmounts
+ *
+ * @internal
+ */
 function fromSync<T>(state: FlowObservable<T>): SolidDerivation<T> {
+	const solidState = new SolidState<T>(state.pick());
 
-    const solidState = new SolidState<T>(state.get());
+	let fx: FlowEffect;
 
-    let fx: FlowEffect;
+	onMount(() => {
+		fx = new FlowEffect((t) => {
+			const value = state.get(t);
+			solidState.set(() => value);
+		});
+	});
 
-    onMount(() => {
-        fx = new FlowEffect((get) => {
-            const value = get(state);
-            solidState.set(() => value);
-        });
-    });
+	onCleanup(() => fx.dispose());
 
-    onCleanup(() => fx.dispose());
-
-    return solidState
+	return solidState;
 }
 
-function fromAsync<T>(derivation: FlowObservable<Promise<T>>): SolidResource<T> {
-
-    const solidResource = new SolidResource<T>(async () => {
-        const value = await derivation.get();
-        return value;
-    });
+/**
+ * Converts an asynchronous FlowObservable (Promise-based) into a SolidJS resource.
+ *
+ * @param derivation - The FlowObservable that resolves to a Promise.
+ * @returns A SolidResource that mirrors the FlowObservable's async value.
+ *
+ * @remarks
+ * This internal helper bridges PicoFlow's async reactive system with SolidJS by:
+ * 1. Creating a SolidResource with an initial fetch using `pick()` (untracked)
+ * 2. Setting up a FlowEffect that tracks the Promise observable
+ * 3. Refetching the SolidResource whenever the Promise observable changes
+ * 4. Properly disposing the effect when the Solid component unmounts
+ *
+ * @internal
+ */
+function fromAsync<T>(
+	derivation: FlowObservable<Promise<T>>,
+): SolidResource<T> {
+	const solidResource = new SolidResource<T>(async () => {
+		const value = await derivation.pick();
+		return value;
+	});
 
-    let fx: FlowEffect;
+	let fx: FlowEffect;
 
-    onMount(() => {
-        fx = new FlowEffect(async (get) => {
-            await get(derivation);
-            solidResource.refetch();
-        });
-    });
+	onMount(() => {
+		fx = new FlowEffect(async (t) => {
+			await derivation.get(t);
+			solidResource.refetch();
+		});
+	});
 
-    onCleanup(() => fx.dispose());
+	onCleanup(() => fx.dispose());
 
-    return solidResource;
+	return solidResource;
 }
 
+/**
+ * Converts a FlowObservable directly into a Solid primitive (signal or resource).
+ *
+ * @param flow - The FlowObservable to convert (can be sync or async).
+ * @returns A SolidDerivation for sync values or SolidResource for async values.
+ *
+ * @remarks
+ * This internal helper performs "shallow" conversion, meaning it converts the
+ * observable itself without creating an intermediate FlowDerivation. It inspects
+ * the initial value to determine if it's a Promise, then delegates to the
+ * appropriate converter (fromSync or fromAsync).
+ *
+ * @internal
+ */
 function shallowFrom<T>(flow: FlowObservable<Promise<T>>): SolidResource<T>;
 function shallowFrom<T>(flow: FlowObservable<T>): SolidDerivation<T>;
-function shallowFrom<T>(flow: FlowObservable<Promise<T>> | FlowObservable<T>): SolidDerivation<T> | SolidResource<T> {
-    const initialValue = flow.get();
-    const isAsync = initialValue instanceof Promise;
-    if (isAsync) {
-        return fromAsync(flow as FlowObservable<Promise<T>>);
-    }
-    return fromSync(flow as FlowObservable<T>);
+function shallowFrom<T>(
+	flow: FlowObservable<Promise<T>> | FlowObservable<T>,
+): SolidDerivation<T> | SolidResource<T> {
+	const initialValue = flow.pick();
+	const isAsync = initialValue instanceof Promise;
+	if (isAsync) {
+		return fromAsync(flow as FlowObservable<Promise<T>>);
+	}
+	return fromSync(flow as FlowObservable<T>);
 }
 
-function deepFrom<T>(getter: (get: FlowGetter) => T): SolidDerivation<T>;
-function deepFrom<T>(getter: (get: FlowGetter) => Promise<T>): SolidResource<T>;
-function deepFrom<T>(getter: (get: FlowGetter) => T | Promise<T>): SolidDerivation<T> | SolidResource<T> {
-    const derivation = new FlowDerivation((get) => {
-        return getter(get);
-    });
+/**
+ * Converts a getter function with TrackingContext into a Solid primitive (signal or resource).
+ *
+ * @param getter - A function that computes a value using a TrackingContext.
+ * @returns A SolidDerivation for sync values or SolidResource for async values.
+ *
+ * @remarks
+ * This internal helper performs "deep" conversion by:
+ * 1. Creating a FlowDerivation from the getter function
+ * 2. Inspecting the initial computed value to determine if it's a Promise
+ * 3. Delegating to the appropriate converter (fromSync or fromAsync)
+ *
+ * This allows users to pass computation functions directly to `from()` without
+ * manually creating a FlowDerivation first.
+ *
+ * @internal
+ */
+function deepFrom<T>(getter: (t: TrackingContext) => T): SolidDerivation<T>;
+function deepFrom<T>(
+	getter: (t: TrackingContext) => Promise<T>,
+): SolidResource<T>;
+function deepFrom<T>(
+	getter: (t: TrackingContext) => T | Promise<T>,
+): SolidDerivation<T> | SolidResource<T> {
+	const derivation = new FlowDerivation((t) => {
+		return getter(t);
+	});
 
-    const initialValue = derivation.get();
-    const isAsync = initialValue instanceof Promise;
+	const initialValue = derivation.pick();
+	const isAsync = initialValue instanceof Promise;
 
-    if (isAsync) {
-        return fromAsync(derivation as FlowObservable<Promise<T>>);
-    }
+	if (isAsync) {
+		return fromAsync(derivation as FlowObservable<Promise<T>>);
+	}
 
-    return fromSync(derivation as FlowObservable<T>);
+	return fromSync(derivation as FlowObservable<T>);
 }
 
 /**
@@ -86,7 +156,9 @@ export type NotPromise<T> = T extends Promise<unknown> ? never : T;
  *
  * @public
  */
-export function from<T>(flow: FlowObservable<Promise<NotPromise<T>>>): SolidResource<NotPromise<T>>;
+export function from<T>(
+	flow: FlowObservable<Promise<NotPromise<T>>>,
+): SolidResource<NotPromise<T>>;
 /**
  * Converts a FlowObservable of a non-Promise value into a SolidDerivation.
  *
@@ -95,7 +167,9 @@ export function from<T>(flow: FlowObservable<Promise<NotPromise<T>>>): SolidReso
  *
  * @public
  */
-export function from<T>(flow: FlowObservable<NotPromise<T>>): SolidDerivation<NotPromise<T>>;
+export function from<T>(
+	flow: FlowObservable<NotPromise<T>>,
+): SolidDerivation<NotPromise<T>>;
 /**
  * Converts a FlowObservable into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous.
  *
@@ -105,7 +179,7 @@ export function from<T>(flow: FlowObservable<NotPromise<T>>): SolidDerivation<No
  * @public
  */
 export function from<T>(
-    flow: FlowObservable<Promise<NotPromise<T>>> | FlowObservable<NotPromise<T>>,
+	flow: FlowObservable<Promise<NotPromise<T>>> | FlowObservable<NotPromise<T>>,
 ): SolidDerivation<NotPromise<T>> | SolidResource<NotPromise<T>>;
 /**
  * Converts a getter function returning a non-Promise value into a SolidDerivation.
@@ -115,7 +189,9 @@ export function from<T>(
  *
  * @public
  */
-export function from<T>(flow: (get: FlowGetter) => NotPromise<T>): SolidDerivation<NotPromise<T>>;
+export function from<T>(
+	flow: (t: TrackingContext) => NotPromise<T>,
+): SolidDerivation<NotPromise<T>>;
 /**
  * Converts a getter function returning a Promise into a SolidResource.
  *
@@ -124,7 +200,9 @@ export function from<T>(flow: (get: FlowGetter) => NotPromise<T>): SolidDerivati
  *
  * @public
  */
-export function from<T>(flow: (get: FlowGetter) => Promise<NotPromise<T>>): SolidResource<NotPromise<T>>;
+export 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.
  *
@@ -134,26 +212,67 @@ export function from<T>(flow: (get: FlowGetter) => Promise<NotPromise<T>>): Soli
  * @public
  */
 export function from<T>(
-    flow: ((get: FlowGetter) => NotPromise<T>) | ((get: FlowGetter) => Promise<NotPromise<T>>),
+	flow:
+		| ((t: TrackingContext) => NotPromise<T>)
+		| ((t: TrackingContext) => Promise<NotPromise<T>>),
 ): SolidDerivation<T> | SolidResource<T>;
 /**
  * Converts a FlowObservable or getter function into a Solid derivation or resource, depending on whether the value is synchronous or asynchronous.
  *
- * - If passed a FlowObservable of a non-Promise value, returns a SolidDerivation.
- * - If passed a FlowObservable of a Promise, returns a SolidResource.
- * - If passed a getter function returning a non-Promise value, returns a SolidDerivation.
- * - If passed a getter function returning a Promise, returns a SolidResource.
- *
  * @param flow - The FlowObservable or getter function to convert.
- * @returns A SolidDerivation or SolidResource, depending on the input type. 
+ * @returns A SolidDerivation or SolidResource, depending on the input type.
+ *
+ * @remarks
+ * This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
+ * PicoFlow observables within Solid components. The conversion is automatic based on
+ * whether the value is a Promise or not:
+ *
+ * - **FlowObservable of non-Promise value** → SolidDerivation (reactive signal)
+ * - **FlowObservable of Promise** → SolidResource (async resource)
+ * - **Getter function returning non-Promise** → SolidDerivation (computed signal)
+ * - **Getter function returning Promise** → SolidResource (async computed resource)
+ *
+ * The created Solid primitives automatically subscribe to the PicoFlow observables and
+ * update when changes occur. The subscription is properly cleaned up when the Solid
+ * component unmounts.
+ *
+ * @example
+ * ```typescript
+ * import { from } from 'picoflow/solid';
+ * import { state } from 'picoflow';
+ *
+ * // Convert a PicoFlow state to a Solid signal
+ * const $count = state(0);
+ * const solidCount = from($count);
+ *
+ * // Use in a Solid component
+ * function Counter() {
+ *   const count = solidCount.get(); // Solid's reactive get
+ *   return <div>Count: {count}</div>;
+ * }
+ *
+ * // Or convert a computation function
+ * const solidDerived = from((t) => {
+ *   return $count.get(t) * 2;
+ * });
+ * ```
+ *
  * @public
  */
 export function from<T>(
-    flow: FlowObservable<Promise<T>> | FlowObservable<T> | ((get: FlowGetter) => T) | ((get: FlowGetter) => Promise<T>),
+	flow:
+		| FlowObservable<Promise<T>>
+		| FlowObservable<T>
+		| ((t: TrackingContext) => T)
+		| ((t: TrackingContext) => Promise<T>),
 ): SolidDerivation<T> | SolidResource<T> {
-    if (flow instanceof FlowObservable) {
-        return shallowFrom(flow as FlowObservable<T | Promise<T>>) as SolidDerivation<T> | SolidResource<T>;
-    }
+	if (flow instanceof FlowObservable) {
+		return shallowFrom(flow as FlowObservable<T | Promise<T>>) as
+			| SolidDerivation<T>
+			| SolidResource<T>;
+	}
 
-    return deepFrom(flow as (get: FlowGetter) => T | Promise<T>) as SolidDerivation<T> | SolidResource<T>;
-}
+	return deepFrom(flow as (t: TrackingContext) => T | Promise<T>) as
+		| SolidDerivation<T>
+		| SolidResource<T>;
+}

package/src/solid/index.ts

@@ -1,2 +1,8 @@
-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";

package/src/solid/primitives.ts

@@ -1,4 +1,9 @@
-import { createMemo, createResource, createSignal, type ResourceFetcher, } from "solid-js";
+import {
+	createMemo,
+	createResource,
+	createSignal,
+	type ResourceFetcher,
+} from "solid-js";
 
 /**
  * A getter function or value for Solid state/derivation.
@@ -15,95 +20,192 @@ export type SolidGetter<T> = ((previous: T) => T) | T;
  * @public
  */
 export interface SolidObservable<T> {
-    /**
-     * Returns the current value.
-     */
-    get: () => T;
+	/**
+	 * Returns the current value.
+	 */
+	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
  */
 export class SolidState<T> implements SolidObservable<T> {
-    /**
-     * Returns the current value.
-     */
-    readonly get: () => T;
-    /**
-     * Sets the value or updates it using a getter function.
-     */
-    readonly set: (param: SolidGetter<T>) => void;
+	/**
+	 * Returns the current value.
+	 */
+	readonly get: () => T;
+	/**
+	 * Sets the value or updates it using a getter function.
+	 */
+	readonly set: (param: SolidGetter<T>) => void;
 
-    /**
-     * Creates a new SolidState with the given initial value.
-     * @param initialValue - The initial value.
-     */
-    constructor(initialValue: T) {
-        const [get, set] = createSignal<T>(initialValue);
-        this.get = get;
-        this.set = set;
-    }
+	/**
+	 * Creates a new SolidState with the given initial value.
+	 * @param initialValue - The initial value.
+	 */
+	constructor(initialValue: T) {
+		const [get, set] = createSignal<T>(initialValue);
+		this.get = get;
+		this.set = set;
+	}
 }
 
 type EffectFunction<Prev, Next extends Prev = Prev> = (v: Prev) => Next;
 /**
- * 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
  */
 export class SolidDerivation<T> implements SolidObservable<T> {
-    /**
-     * Returns the current derived value.
-     */
-    readonly get: () => T;
+	/**
+	 * Returns the current derived value.
+	 */
+	readonly get: () => T;
 
-    /**
-     * Creates a new SolidDerivation from a getter function or value.
-     * @param calculator - The getter function or value.
-     */
-    constructor(calculator: SolidGetter<T>) {
-        const get = createMemo<T>(calculator as EffectFunction<T | undefined, T>);
-        this.get = get;
-    }
+	/**
+	 * Creates a new SolidDerivation from a getter function or value.
+	 * @param calculator - The getter function or value.
+	 */
+	constructor(calculator: SolidGetter<T>) {
+		const get = createMemo<T>(calculator as EffectFunction<T | undefined, T>);
+		this.get = get;
+	}
 }
 
 /**
- * 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
  */
 export class SolidResource<T> implements SolidObservable<T | undefined> {
-    /**
-     * Returns the current value (or undefined if not yet loaded).
-     */
-    readonly get: () => T | undefined;
-    /**
-     * Returns the current resource state.
-     */
-    readonly state: () => 'unresolved' | 'pending' | 'errored' | 'ready' | 'refreshing';
-    /**
-     * Returns the latest successfully loaded value (or undefined).
-     */
-    readonly latest: () => T | undefined;
-    /**
-     * Triggers a refetch of the resource.
-     */
-    readonly refetch: () => void;
+	/**
+	 * Returns the current value (or undefined if not yet loaded).
+	 */
+	readonly get: () => T | undefined;
+	/**
+	 * Returns the current resource state.
+	 */
+	readonly state: () =>
+		| "unresolved"
+		| "pending"
+		| "errored"
+		| "ready"
+		| "refreshing";
+	/**
+	 * Returns the latest successfully loaded value (or undefined).
+	 */
+	readonly latest: () => T | undefined;
+	/**
+	 * Triggers a refetch of the resource.
+	 */
+	readonly refetch: () => void;
 
-    /**
-     * Creates a new SolidResource from a fetcher function.
-     * @param fetcher - The async fetcher function.
-     */
-    constructor(fetcher: ResourceFetcher<true, T, unknown>) {
-        const [get, set] = createResource<T>(fetcher);
-        this.get = get;
-        this.state = () => get.state;
-        this.latest = () => get.latest;
-        this.refetch = () => set.refetch();
-    }
-}
+	/**
+	 * Creates a new SolidResource from a fetcher function.
+	 * @param fetcher - The async fetcher function.
+	 */
+	constructor(fetcher: ResourceFetcher<true, T, unknown>) {
+		const [get, set] = createResource<T>(fetcher);
+		this.get = get;
+		this.state = () => get.state;
+		this.latest = () => get.latest;
+		this.refetch = () => set.refetch();
+	}
+}