@ersbeth/picoflow 1.1.2 → 2.0.0

package/src/solid/converters.ts

@@ -1,148 +0,0 @@
-import { onCleanup, onMount } from "solid-js";
-import { FlowNode, type FlowReadonly, type FlowReadonlyAsync } from "../flow";
-import { FlowEffect } from "../flow/base";
-import type { FlowTracker } from "../flow/base/flowTracker";
-import { FlowNodeAsync } from "../flow/nodes/async/flowNodeAsync";
-import { SolidResource } from "./primitives";
-import type { NotPromise } from "../flow/base";
-/**
- * Converts an asynchronous FlowNodeAsync (Promise-based) into a SolidJS resource.
- *
- * @param node - The FlowNodeAsync to convert.
- * @returns A SolidResource that wraps the FlowNodeAsync's value.
- *
- * @remarks
- * This internal helper bridges PicoFlow's async reactive system with SolidJS by creating
- * a SolidResource that automatically tracks the FlowNodeAsync and updates when its value changes.
- * The resource is properly cleaned up when the Solid component unmounts.
- *
- * @internal
- */
-function fromNode<T>(node: FlowNodeAsync<T> | FlowNode<T>): SolidResource<T> {
-	let initialized = false;
-
-	const solidResource = new SolidResource<T>(async () => {
-		let value: T;
-		if (initialized) {
-			value = await node.get(null); // don't request graph read
-		} else {
-			value = await node.pick();
-			initialized = true;
-		}
-		return value;
-	});
-
-	let fx: FlowEffect;
-
-	onMount(() => {
-		fx = new FlowEffect(async (t) => {
-			const watched = node.watch(t);
-			if (watched instanceof Promise) {
-				await watched;
-			}
-			solidResource.refetch();
-		});
-	});
-
-	onCleanup(() => fx.dispose());
-
-	return solidResource;
-}
-
-/**
- * Converts a getter function into a SolidResource.
- *
- * @param getter - A function that computes a value using a FlowTracker.
- * @returns A SolidResource that wraps the computed value.
- *
- * @remarks
- * This internal helper performs "deep" conversion by creating a FlowNodeAsync from
- * the getter function and then converting it to a SolidResource. This allows users
- * to pass computation functions directly to `from()` without manually creating a
- * FlowNodeAsync first.
- *
- * @internal
- */
-function fromGetter<T>(
-	getter: (t: FlowTracker) => T | Promise<T>,
-): SolidResource<T> {
-	const derivation = new FlowNodeAsync<T>(async (t) => {
-		return getter(t);
-	});
-
-	return fromNode(derivation);
-}
-
-/**
- * Utility type that excludes Promise types from T.
- * Used to ensure type safety for synchronous derivations/resources.
- *
- * @public
- */
-// export type NotPromise<T> = T extends Promise<unknown> ? never : T;
-
-/**
- * Converts a FlowNode, FlowNodeAsync, or getter function into a SolidResource.
- *
- * @param flow - The FlowNode, FlowNodeAsync, or getter function to convert.
- * @returns A SolidResource that wraps the value or computation.
- *
- * @remarks
- * This function bridges PicoFlow's reactive system with SolidJS, allowing you to use
- * PicoFlow nodes and computations within Solid components. All conversions return a
- * `SolidResource`, which can handle both synchronous and asynchronous values seamlessly.
- *
- * The conversion works with:
- * - **FlowNode**: Synchronous reactive nodes (e.g., from `state()` or `derivation()`)
- * - **FlowNodeAsync**: Asynchronous reactive nodes (e.g., from `resourceAsync()`)
- * - **Getter functions**: Computation functions that use a FlowTracker to access reactive values
- *
- * The created SolidResource automatically subscribes to the PicoFlow nodes and updates
- * when their values change. 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 resource
- * const $count = state(0);
- * const solidCount = from($count);
- *
- * // Use in a Solid component
- * function Counter() {
- *   return <div>Count: {solidCount.get()}</div>;
- * }
- *
- * // Or convert a computation function
- * const solidDerived = from((t) => {
- *   return solidCount.get(t) * 2;
- * });
- * ```
- *
- * @public
- */
-export function from<T>(flow: FlowReadonlyAsync<T>): SolidResource<T>;
-export function from<T>(flow: FlowReadonly<T>): SolidResource<T>;
-export function from<T>(flow: (t: FlowTracker) => Promise<T>): SolidResource<T>;
-export function from<T>(
-	flow: (t: FlowTracker) => NotPromise<T>,
-): SolidResource<T>;
-export function from<T>(
-	flow:
-		| FlowReadonlyAsync<T>
-		| FlowReadonly<T>
-		| ((t: FlowTracker) => NotPromise<T>)
-		| ((t: FlowTracker) => Promise<T>),
-): SolidResource<T> {
-	if (flow instanceof FlowNodeAsync || flow instanceof FlowNode) {
-		return fromNode(flow);
-	}
-
-	if (typeof flow === "function") {
-		return fromGetter(flow);
-	}
-
-	throw new Error("Invalid flow type");
-}

package/src/solid/index.ts

@@ -1,2 +0,0 @@
-export * from "./converters";
-export * from "./primitives";

package/src/solid/primitives.ts

@@ -1,215 +0,0 @@
-import {
-	createMemo,
-	createResource,
-	createSignal,
-	type ResourceFetcher,
-} from "solid-js";
-
-/**
- * A getter function or value for Solid state/derivation.
- *
- * @typeParam T - The value type.
- * @public
- */
-export type SolidGetter<T> = ((previous: T) => T) | T;
-
-/**
- * Interface for a Solid-style observable value.
- *
- * @typeParam T - The value type.
- * @public
- */
-export interface SolidObservable<T> {
-	/**
-	 * Returns the current value.
-	 */
-	get: () => T;
-}
-
-/**
- * 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;
-
-	/**
-	 * 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 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;
-
-	/**
-	 * 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 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;
-
-	readonly set: (param: SolidGetter<T>) => 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();
-		//@ts-expect-error - SolidGetter is not assignable to parameter of type 'Exclude<T, Function> | ((prev: T | undefined) => T)'
-		this.set = (value: SolidGetter<T>) => set.mutate(value);
-	}
-}

package/test/base/flowEffect.test.ts

@@ -1,108 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { effect } from "#package";
-
-describe("FlowEffect", () => {
-	describe("disposal", () => {
-		it("should have disposed property set to false initially and true after disposal", () => {
-			const effectFn = vi.fn();
-			const $effect = effect(() => {
-				effectFn();
-			});
-
-			expect($effect.disposed).toBe(false);
-			$effect.dispose();
-			expect($effect.disposed).toBe(true);
-		});
-
-		it("should throw error when disposed twice", () => {
-			const effectFn = vi.fn();
-			const $effect = effect(() => {
-				effectFn();
-			});
-
-			$effect.dispose();
-			expect(() => $effect.dispose()).toThrow("Effect is disposed");
-		});
-	});
-
-	describe("execution", () => {
-		it("should execute immediately upon creation", async () => {
-			const effectFn = vi.fn();
-			effect(() => {
-				effectFn();
-			});
-
-			await vi.waitFor(() => expect(effectFn).toHaveBeenCalledTimes(1));
-		});
-
-		it("should execute callback with tracking context as parameter", async () => {
-			const effectFn = vi.fn();
-			let receivedContext: unknown = null;
-
-			const $effect = effect((t) => {
-				receivedContext = t;
-				effectFn();
-			});
-
-			await vi.waitFor(() => expect(effectFn).toHaveBeenCalledTimes(1));
-			expect(receivedContext).toBe($effect);
-		});
-	});
-
-	describe("async support", () => {
-		it("should support async callback functions", async () => {
-			const effectFn = vi.fn();
-			let asyncCompleted = false;
-
-			effect(async () => {
-				await new Promise((resolve) => setTimeout(resolve, 10));
-				asyncCompleted = true;
-				effectFn();
-			});
-
-			await vi.waitFor(() => expect(effectFn).toHaveBeenCalledTimes(1));
-			expect(asyncCompleted).toBe(true);
-		});
-
-		it("should await async callback before completing", async () => {
-			const executionOrder: string[] = [];
-			const effectFn = vi.fn();
-
-			effect(async () => {
-				executionOrder.push("start");
-				await new Promise((resolve) => setTimeout(resolve, 10));
-				executionOrder.push("async-complete");
-				effectFn();
-			});
-
-			executionOrder.push("after-effect-creation");
-
-			await vi.waitFor(() => expect(effectFn).toHaveBeenCalledTimes(1));
-			expect(executionOrder).toEqual([
-				"start",
-				"after-effect-creation",
-				"async-complete",
-			]);
-		});
-	});
-
-	describe("error handling", () => {
-		it("should throw error when trying to execute after disposal", async () => {
-			const effectFn = vi.fn();
-			const $effect = effect(() => {
-				effectFn();
-			});
-
-			await vi.waitFor(() => expect(effectFn).toHaveBeenCalledTimes(1));
-
-			$effect.dispose();
-
-			// The internal _exec method should throw when called after disposal
-			// This is tested indirectly - if we try to trigger execution after disposal,
-			// it should fail. However, since we're testing in isolation without dependencies,
-			// we verify that the disposed state prevents further execution
-			expect($effect.disposed).toBe(true);
-			expect(() => $effect.dispose()).toThrow("Effect is disposed");
-		});
-	});
-});