@ersbeth/picoflow 1.0.1 → 1.1.1

package/dist/types/creators.d.ts

@@ -1,340 +0,0 @@
-import { FlowMap, FlowResource, FlowResourceAsync, FlowStream, FlowStreamAsync } from './advanced/';
-import { FlowArray } from './advanced/array';
-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.
- *
- * @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 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, 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 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 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 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 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: (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 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: (t: TrackingContext) => void): FlowEffect;
-/**
- * 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 declare function map<K extends string | number | symbol, V>(initial?: Record<K, V>): FlowMap<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 declare function array<T>(initial?: T[]): FlowArray<T>;
-//# sourceMappingURL=creators.d.ts.map

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

@@ -1 +0,0 @@
-{"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/src/advanced/array.ts

@@ -1,222 +0,0 @@
-import { FlowObservable, type FlowState, isDisposable } from "../basic";
-import { state } from "../creators";
-
-/**
- * Represents the actions that can be performed on a FlowArray.
- * @public
- */
-export type FlowArrayAction<T> =
-	| {
-			type: "set";
-			items: T[];
-	  }
-	| {
-			type: "setItem";
-			index: number;
-			item: T;
-	  }
-	| {
-			type: "push";
-			item: T;
-	  }
-	| {
-			type: "pop";
-	  }
-	| {
-			type: "unshift";
-			item: T;
-	  }
-	| {
-			type: "shift";
-	  }
-	| {
-			type: "splice";
-			start: number;
-			deleteCount: number;
-			items: T[];
-	  }
-	| {
-			type: "clear";
-	  };
-
-/**
- * Represents a reactive array.
- * @public
- */
-export class FlowArray<T> extends FlowObservable<T[]> {
-	/**
-	 * Last action performed on the FlowArray.
-	 * @public
-	 */
-	$lastAction: FlowState<FlowArrayAction<T>>;
-
-	/**
-	 * Creates an instance of FlowArray.
-	 * @param value - Initial array value.
-	 * @public
-	 */
-	constructor(value: T[] = []) {
-		super();
-		this._value = value;
-		this.$lastAction = state<FlowArrayAction<T>>({
-			type: "set",
-			items: value,
-		});
-	}
-
-	/**
-	 * Gets the current length of the array.
-	 * @returns The length of the array.
-	 * @public
-	 */
-	get length(): number {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		return this._value.length;
-	}
-
-	/**
-	 * Internal method to get the raw value.
-	 * @internal
-	 */
-	protected _getRaw(): T[] {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		return [...this._value]; // Ensure nobody can modify the original array
-	}
-
-	/**
-	 * Replaces the entire array with new items.
-	 * @param items - The new array of items.
-	 * @public
-	 */
-	set(items: T[]): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		this._value.forEach((item) => {
-			if (isDisposable(item)) item.dispose({ self: true });
-		});
-		this._value = items;
-		this._notify();
-		this.$lastAction.set({ type: "set", items: items });
-	}
-
-	/**
-	 * Replaces an item at a specific index.
-	 * @param index - The index of the item to replace.
-	 * @param item - The new item.
-	 * @public
-	 */
-	setItem(index: number, item: T): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		if (index < 0 || index >= this._value.length) {
-			throw new Error("[PicoFlow] Index out of bounds");
-		}
-		this._value[index] = item;
-		this._notify();
-		this.$lastAction.set({ type: "setItem", index: index, item: item });
-	}
-
-	/**
-	 * Appends an item to the end of the array.
-	 * @param item - The item to append.
-	 * @public
-	 */
-	push(item: T): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		this._value.push(item);
-		this._notify();
-		this.$lastAction.set({ type: "push", item: item });
-	}
-
-	/**
-	 * Removes the last item from the array.
-	 * @public
-	 */
-	pop(): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const item = this._value.pop();
-		if (isDisposable(item)) {
-			item.dispose({ self: true });
-		}
-		this._notify();
-		this.$lastAction.set({ type: "pop" });
-	}
-
-	/**
-	 * Inserts an item at the beginning of the array.
-	 * @param item - The item to insert.
-	 * @public
-	 */
-	unshift(item: T): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		this._value.unshift(item);
-		this._notify();
-		this.$lastAction.set({ type: "unshift", item: item });
-	}
-
-	/**
-	 * Removes the first item from the array.
-	 * @public
-	 */
-	shift(): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const item = this._value.shift();
-		if (isDisposable(item)) {
-			item.dispose({ self: true });
-		}
-		this._notify();
-		this.$lastAction.set({ type: "shift" });
-	}
-
-	/**
-	 * Changes the content of the array.
-	 * @param start - The starting index.
-	 * @param deleteCount - Number of items to remove.
-	 * @param newItems - New items to add.
-	 * @public
-	 */
-	splice(start: number, deleteCount: number, ...newItems: T[]): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const items = this._value.splice(start, deleteCount, ...newItems);
-		items.forEach((item) => {
-			if (isDisposable(item)) item.dispose({ self: true });
-		});
-		this._notify();
-		this.$lastAction.set({
-			type: "splice",
-			start: start,
-			deleteCount: deleteCount,
-			items: newItems,
-		});
-	}
-
-	/**
-	 * Clears all items from the array.
-	 * @public
-	 */
-	clear(): void {
-		if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
-		const items = [...this._value];
-		items.forEach((item) => {
-			if (isDisposable(item)) item.dispose({ self: true });
-		});
-		this._value = [];
-		this._notify();
-		this.$lastAction.set({ type: "clear" });
-	}
-
-	/**
-	 * Disposes the FlowArray and its items.
-	 * @param options - Disposal options.
-	 * @public
-	 */
-	override dispose(options?: { self: boolean }): void {
-		super.dispose(options);
-		this._value.forEach((item) => {
-			if (isDisposable(item)) item.dispose(options);
-		});
-		this._value = [];
-	}
-
-	/* INTERNAL */
-
-	/** @internal */ protected override _value: T[] = [];
-}

package/src/advanced/index.ts

@@ -1,12 +0,0 @@
-export type { FlowArrayAction } from "./array";
-export { FlowArray } from "./array";
-export { FlowMap } from "./map";
-export { FlowResource } from "./resource";
-export { FlowResourceAsync } from "./resourceAsync";
-export type {
-	FlowStreamDisposer,
-	FlowStreamSetter,
-	FlowStreamUpdater,
-} from "./stream";
-export { FlowStream } from "./stream";
-export { FlowStreamAsync } from "./streamAsync";