@ersbeth/picoflow 1.0.1 → 1.1.1

package/src/creators.ts

@@ -1,395 +0,0 @@
-import {
-	FlowMap,
-	FlowResource,
-	FlowResourceAsync,
-	FlowStream,
-	FlowStreamAsync,
-} from "./advanced/";
-import { FlowArray } from "./advanced/array";
-import type { TrackingContext } from "./basic/";
-import {
-	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 function signal(): FlowSignal {
-	return new FlowSignal();
-}
-
-/**
- * Creates a new reactive constant.
- *
- * @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);
-}
-
-/**
- * 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);
-}
-
-/**
- * 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);
-}
-
-/**
- * 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);
-}
-
-/**
- * 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,
-): FlowStream<T> {
-	return new FlowStream(updater);
-}
-
-/**
- * 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,
-): FlowStreamAsync<T> {
-	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 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: (t: TrackingContext) => T,
-): FlowDerivation<T> {
-	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 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: (t: TrackingContext) => void): FlowEffect {
-	return new FlowEffect(fn);
-}
-
-/**
- * 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
- * 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>,
-): FlowMap<K, V> {
-	return new FlowMap<K, V>(
-		new Map<K, V>(initial ? (Object.entries(initial) as [K, V][]) : []),
-	);
-}
-
-/**
- * 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);
-}