@ersbeth/picoflow 1.0.0 → 1.1.0

package/src/solid/converters.ts

@@ -1,63 +1,34 @@
 import { onCleanup, onMount } from "solid-js";
-import {
-	FlowDerivation,
-	FlowEffect,
-	FlowObservable,
-	type TrackingContext,
-} from "../basic";
-import { type SolidDerivation, SolidResource, SolidState } from "./primitives";
+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";
 
 /**
- * Converts a synchronous FlowObservable into a SolidJS signal.
+ * Converts an asynchronous FlowNodeAsync (Promise-based) into a SolidJS resource.
  *
- * @param state - The FlowObservable to convert.
- * @returns A SolidDerivation that mirrors the FlowObservable's value.
+ * @param node - The FlowNodeAsync to convert.
+ * @returns A SolidResource that wraps the FlowNodeAsync'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
+ * 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 fromSync<T>(state: FlowObservable<T>): SolidDerivation<T> {
-	const solidState = new SolidState<T>(state.pick());
+function fromNode<T>(node: FlowNodeAsync<T> | FlowNode<T>): SolidResource<T> {
+	let initialized = false;
 
-	let fx: FlowEffect;
-
-	onMount(() => {
-		fx = new FlowEffect((t) => {
-			const value = state.get(t);
-			solidState.set(() => value);
-		});
-	});
-
-	onCleanup(() => fx.dispose());
-
-	return solidState;
-}
-
-/**
- * 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();
+		let value: T;
+		if (initialized) {
+			value = await node.get(null); // don't request graph read
+		} else {
+			value = await node.pick();
+			initialized = true;
+		}
 		return value;
 	});
 
@@ -65,7 +36,7 @@ function fromAsync<T>(
 
 	onMount(() => {
 		fx = new FlowEffect(async (t) => {
-			await derivation.get(t);
+			node.watch(t);
 			solidResource.refetch();
 		});
 	});
@@ -76,68 +47,27 @@ function fromAsync<T>(
 }
 
 /**
- * Converts a FlowObservable directly into a Solid primitive (signal or resource).
+ * Converts a getter function into a SolidResource.
  *
- * @param flow - The FlowObservable to convert (can be sync or async).
- * @returns A SolidDerivation for sync values or SolidResource for async values.
+ * @param getter - A function that computes a value using a FlowTracker.
+ * @returns A SolidResource that wraps the computed value.
  *
  * @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).
+ * 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 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.pick();
-	const isAsync = initialValue instanceof Promise;
-	if (isAsync) {
-		return fromAsync(flow as FlowObservable<Promise<T>>);
-	}
-	return fromSync(flow as FlowObservable<T>);
-}
-
-/**
- * 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) => {
+function fromGetter<T>(
+	getter: (t: FlowTracker) => T | Promise<T>,
+): SolidResource<T> {
+	const derivation = new FlowNodeAsync<T>(async (t) => {
 		return getter(t);
 	});
 
-	const initialValue = derivation.pick();
-	const isAsync = initialValue instanceof Promise;
-
-	if (isAsync) {
-		return fromAsync(derivation as FlowObservable<Promise<T>>);
-	}
-
-	return fromSync(derivation as FlowObservable<T>);
+	return fromNode(derivation);
 }
 
 /**
@@ -149,91 +79,23 @@ function deepFrom<T>(
 export type NotPromise<T> = T extends Promise<unknown> ? never : T;
 
 /**
- * Converts a FlowObservable of a Promise value into a SolidResource.
+ * Converts a FlowNode, FlowNodeAsync, or getter function into a SolidResource.
  *
- * @param flow - The FlowObservable to convert.
- * @returns A SolidResource wrapping the observable.
- *
- * @public
- */
-export function from<T>(
-	flow: FlowObservable<Promise<NotPromise<T>>>,
-): SolidResource<NotPromise<T>>;
-/**
- * Converts a FlowObservable of a non-Promise value into a SolidDerivation.
- *
- * @param flow - The FlowObservable to convert.
- * @returns A SolidDerivation wrapping the observable.
- *
- * @public
- */
-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.
- *
- * @param flow - The FlowObservable to convert.
- * @returns A SolidDerivation or SolidResource, depending on the input type.
- *
- * @public
- */
-export function from<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.
- *
- * @param flow - The getter function to convert.
- * @returns A SolidDerivation wrapping the getter.
- *
- * @public
- */
-export function from<T>(
-	flow: (t: TrackingContext) => NotPromise<T>,
-): SolidDerivation<NotPromise<T>>;
-/**
- * Converts a getter function returning a Promise into a SolidResource.
- *
- * @param flow - The getter function to convert.
- * @returns A SolidResource wrapping the getter.
- *
- * @public
- */
-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.
- *
- * @param flow - The getter function to convert.
- * @returns A SolidDerivation or SolidResource, depending on the input type.
- *
- * @public
- */
-export function from<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.
- *
- * @param flow - The FlowObservable or getter function to convert.
- * @returns A SolidDerivation or SolidResource, depending on the input type.
+ * @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 observables within Solid components. The conversion is automatic based on
- * whether the value is a Promise or not:
+ * PicoFlow nodes and computations within Solid components. All conversions return a
+ * `SolidResource`, which can handle both synchronous and asynchronous values seamlessly.
  *
- * - **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 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 Solid primitives automatically subscribe to the PicoFlow observables and
- * update when changes occur. The subscription is properly cleaned up when the Solid
+ * 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
@@ -241,19 +103,18 @@ export function from<T>(
  * import { from } from 'picoflow/solid';
  * import { state } from 'picoflow';
  *
- * // Convert a PicoFlow state to a Solid signal
+ * // Convert a PicoFlow state to a Solid resource
  * 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>;
+ *   return <div>Count: {solidCount.get()}</div>;
  * }
  *
  * // Or convert a computation function
  * const solidDerived = from((t) => {
- *   return $count.get(t) * 2;
+ *   return solidCount.get(t) * 2;
  * });
  * ```
  *
@@ -261,18 +122,18 @@ export function from<T>(
  */
 export function from<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>;
+		| FlowReadonlyAsync<T>
+		| FlowReadonly<T>
+		| ((t: FlowTracker) => T)
+		| ((t: FlowTracker) => Promise<T>),
+): SolidResource<T> {
+	if (flow instanceof FlowNodeAsync || flow instanceof FlowNode) {
+		return fromNode(flow);
+	}
+
+	if (typeof flow === "function") {
+		return fromGetter(flow);
 	}
 
-	return deepFrom(flow as (t: TrackingContext) => T | Promise<T>) as
-		| SolidDerivation<T>
-		| SolidResource<T>;
+	throw new Error("Invalid flow type");
 }

package/src/solid/primitives.ts

@@ -197,6 +197,8 @@ export class SolidResource<T> implements SolidObservable<T | undefined> {
 	 */
 	readonly refetch: () => void;
 
+	readonly set: (param: SolidGetter<T>) => void;
+
 	/**
 	 * Creates a new SolidResource from a fetcher function.
 	 * @param fetcher - The async fetcher function.
@@ -207,5 +209,7 @@ export class SolidResource<T> implements SolidObservable<T | undefined> {
 		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

@@ -0,0 +1,108 @@
+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");
+		});
+	});
+});