@ersbeth/picoflow 2.3.2 → 3.0.0

package/dist/index.js

@@ -0,0 +1,544 @@
+import { _ as PicoFlowPreconditionError, a as ReadableNode, g as PicoFlowInternalError, h as PicoFlowError, m as PicoFlowDisposedError, n as asyncCore, o as EffectNode, p as PicoFlowCycleError, r as syncCore, u as ExecutionStack } from "./shared.js";
+import { n as subscribe, r as DerivationNode, t as derivation } from "./shared2.js";
+import { t as SignalNode } from "./shared3.js";
+
+//#region src/core/api/base/flowConfig.ts
+/**
+* Installs a global handler for errors that escape the reactive flush.
+*
+* All reactive work — recomputing derivations, running effects — happens inside an
+* asynchronous flush. Without this hook, an error escaping the flush (an effect callback
+* that throws with no `onError`, or a feedback loop between two effects) becomes an
+* uncaught exception, which terminates a Node process. Installing a handler here makes
+* that error catchable instead.
+*
+* Defaults to `console.error`. The handler replaces any previously installed handler —
+* it is not additive.
+*
+* @param handler - Called with the error that escaped the flush.
+*
+* @public
+*/
+function onFlushError(handler) {
+	ExecutionStack.setFlushErrorHandler(handler);
+}
+/**
+* Returns the scheduler to its just-started state: both queues emptied, any scheduled flush
+* cancelled, and the flush error handler back to its `console.error` default.
+*
+* Scheduling is process-global, so reactive work left over from one test can still be waiting when
+* the next one starts, and a handler installed with {@link onFlushError} stays installed. Calling
+* this from an `afterEach` gives each test a clean scheduler. It is the supported alternative to
+* reaching into internals, and applications testing their own code need it for the same reason
+* PicoFlow's own suite does.
+*
+* Queued work is **discarded, not run** — this cancels pending reactivity rather than flushing it.
+* Primitives created before the call stay usable, but any recomputation that was waiting is lost:
+* those nodes only recompute once something notifies them again. To let pending work complete
+* instead, `await` a value with `pick()`.
+*
+* @public
+*/
+function reset() {
+	ExecutionStack.reset();
+}
+
+//#endregion
+//#region src/core/api/base/flowDisposable.ts
+/**
+* Type guard to check if an object implements the FlowDisposable interface.
+*
+* Useful for conditionally disposing objects that may or may not be disposable,
+* such as when cleaning up mixed collections of values. Returns true if the object
+* has a `dispose` method, providing type-safe access to disposal functionality.
+*
+* @param obj - The object to check
+* @returns True if the object implements FlowDisposable, false otherwise
+*
+* @public
+*/
+function isDisposable(obj) {
+	return obj !== null && obj !== void 0 && typeof obj.dispose === "function";
+}
+
+//#endregion
+//#region src/core/nodes/constantNode.ts
+/**
+* The primitive behind `constant()` and `constantAsync()`: a {@link ReadableNode} and nothing more.
+* It computes once, lazily, and carries no mutator on its prototype chain (#26, A2-SEM-3).
+* @internal
+*/
+var ConstantNode = class extends ReadableNode {};
+
+//#endregion
+//#region src/core/api/nodes/async/flowConstantAsync.ts
+function constantAsync(valueOrInitializer, options) {
+	return new ConstantNode(asyncCore(valueOrInitializer, options), "constantAsync");
+}
+
+//#endregion
+//#region src/core/api/nodes/async/flowDerivationAsync.ts
+/**
+* Creates an async derived value that automatically recomputes when dependencies change.
+*
+* The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
+* the function runs again and returns a new promise. The resolved value is cached until the next change.
+* While the promise is pending, reactive computations that access this value receive PendingError and automatically
+* retry once resolved. Use for derived data from async sources like filtered API results or computed database queries.
+*
+* @param compute - Async function that accesses dependencies and returns a promise of the derived value
+* @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the
+*   default `===` change detection, `eager` recomputes on dirty instead of on read (#118)
+* @returns A FlowDerivationAsync that provides read-only access to the resolved computed value
+*
+* @public
+*/
+function derivationAsync(compute, options) {
+	return new DerivationNode(asyncCore(compute, options, true), "derivationAsync");
+}
+
+//#endregion
+//#region src/core/nodes/stateNode.ts
+/**
+* The primitive behind `state()` and `stateAsync()`: readable and writable. `set` replaces, `update`
+* derives the next value from the stabilised current one (A2-TYPE-1, #43). `I` is the core's input
+* type — the value for a sync state, a promise of it for an async one. No `refresh`: a state has
+* nothing to recompute, and re-running its initializer would undo every write since.
+* @internal
+*/
+var StateNode = class extends ReadableNode {
+	get _core() {
+		return super._core;
+	}
+	set(input) {
+		this._core.overwrite(input);
+	}
+	update(updater) {
+		this._core.update(updater);
+	}
+	/** Notifies dependents without changing the value — a write, hence its place here (#132). */
+	trigger() {
+		this._core.trigger();
+	}
+};
+
+//#endregion
+//#region src/core/api/nodes/async/flowStateAsync.ts
+function stateAsync(valueOrInitializer, options) {
+	return new StateNode(asyncCore(valueOrInitializer, options), "stateAsync");
+}
+
+//#endregion
+//#region src/core/nodes/writableDerivationNode.ts
+/**
+* The primitive behind `writableDerivation()` and `writableDerivationAsync()`: a {@link StateNode}
+* that also recomputes from its dependencies, hence `refresh()` on top of `set` / `update`. Each
+* mutator is a one-line delegation to the core, so declaring all three here duplicates nothing —
+* which is what lets the sync/async × state/derivation diamond go (#114, step 4 of #110).
+* @internal
+*/
+var WritableDerivationNode = class extends StateNode {
+	refresh() {
+		this._core.refresh();
+	}
+};
+
+//#endregion
+//#region src/core/api/nodes/async/flowWritableDerivationAsync.ts
+/**
+* Creates an async derived value that recomputes automatically but can also be manually overridden.
+*
+* The async compute function tracks dependencies and returns a promise. When any tracked dependency changes,
+* the function runs again and returns a new promise. However, you can also call `set()` to override the computed
+* value with a new promise. Use for async values that are normally derived but need occasional manual adjustments,
+* such as editable async calculated fields or user-correctable async totals.
+*
+* @param compute - Async function that accesses dependencies and returns a promise of the derived value
+* @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the
+*   default `===` change detection, `eager` recomputes on dirty instead of on read (#118)
+* @returns A FlowWritableDerivationAsync that provides both reactive async computation and manual control
+*
+* @public
+*/
+function writableDerivationAsync(compute, options) {
+	return new WritableDerivationNode(asyncCore(compute, options, true), "writableDerivationAsync");
+}
+
+//#endregion
+//#region src/core/nodes/actionNode.ts
+/**
+* Reactive state that tracks the latest action while delivering every emitted action
+* to `.subscribe()` callbacks, including multiple mutations within the same batch.
+*
+* Two read models:
+* - get() / pick(): last-write-wins snapshot (current action value).
+* - subscribe(): event stream — one onData call per emitted action, even when several
+*   mutations happen before the next flush. Each subscriber owns its own queue so
+*   delivery is not shared or stolen between subscribers.
+*
+* @internal
+*/
+var ActionNode = class extends StateNode {
+	#slots = /* @__PURE__ */ new Set();
+	constructor(value, name) {
+		super(syncCore(value, { name }), "action");
+	}
+	/** The engine's cached value — an action node is built with a value and is always resolved. */
+	get _value() {
+		return this._core.current;
+	}
+	_enqueueForSubscribers(action) {
+		for (const slot of this.#slots) slot.queue.push(action);
+	}
+	set(value) {
+		this._core.assertAlive();
+		if (this.status === "resolved" && value === this._value) return;
+		this._enqueueForSubscribers(value);
+		super.set(value);
+	}
+	update(updater) {
+		this._core.assertAlive();
+		let action;
+		try {
+			action = updater(this._value);
+		} catch (error) {
+			this._core.fail(error);
+			return;
+		}
+		this.set(action);
+	}
+	subscribe(onValue, onError, onPending, options) {
+		this._core.assertAlive();
+		const slot = { queue: [] };
+		this.#slots.add(slot);
+		const effect = new EffectNode((tracker) => {
+			this.watch(tracker);
+			if (slot.queue.length === 0) return [this.get(tracker)];
+			return slot.queue.splice(0);
+		}, (actions) => {
+			for (const action of actions) onValue(action);
+		}, onError, onPending, options?.name);
+		effect.onDispose(() => {
+			this.#slots.delete(slot);
+		});
+		return effect;
+	}
+	dispose() {
+		super.dispose();
+		this.#slots.clear();
+	}
+};
+
+//#endregion
+//#region src/core/nodes/arrayNode.ts
+/**
+* Internal implementation of reactive array with mutation tracking.
+* @internal
+*/
+var ArrayNode = class extends ReadableNode {
+	$lastAction;
+	get _core() {
+		return super._core;
+	}
+	/** The live backing store, owned by the engine and mutated in place here. */
+	get _value() {
+		return this._core.current;
+	}
+	set _value(value) {
+		this._core.current = value;
+	}
+	constructor(value = [], name) {
+		super(syncCore(value, { name }), "array");
+		this.$lastAction = new ActionNode({
+			type: "set",
+			setItems: value,
+			clearedItems: []
+		}, name && `${name}.$lastAction`);
+	}
+	/** Notifies dependents without changing the contents. */
+	trigger() {
+		this._core.trigger();
+	}
+	set(items) {
+		this._core.assertAlive();
+		const previousValue = this._value;
+		if (!this._core.overwrite(items)) return;
+		this.$lastAction.set({
+			type: "set",
+			setItems: this._value,
+			clearedItems: previousValue
+		});
+	}
+	setAt(index, item) {
+		this._core.assertAlive();
+		if (index < 0 || index >= this._value.length || !Number.isInteger(index)) throw new PicoFlowPreconditionError("[PicoFlow] Index out of bounds");
+		const previousValue = this._value[index];
+		this._value[index] = item;
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "setAt",
+			index,
+			setItem: item,
+			clearedItem: previousValue
+		});
+	}
+	push(item) {
+		this._core.assertAlive();
+		this._value.push(item);
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "push",
+			addedItem: item
+		});
+	}
+	pop() {
+		this._core.assertAlive();
+		if (this._value.length === 0) return void 0;
+		const item = this._value.pop();
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "pop",
+			removedItem: item
+		});
+		return item;
+	}
+	unshift(item) {
+		this._core.assertAlive();
+		this._value.unshift(item);
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "unshift",
+			addedItem: item
+		});
+	}
+	shift() {
+		this._core.assertAlive();
+		if (this._value.length === 0) return void 0;
+		const item = this._value.shift();
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "shift",
+			removedItem: item
+		});
+		return item;
+	}
+	splice(start, deleteCount, ...newItems) {
+		this._core.assertAlive();
+		const length = this._value.length;
+		if (!Number.isInteger(start) || start < 0 || start > length) throw new PicoFlowPreconditionError("[PicoFlow] Index out of bounds");
+		if (!Number.isInteger(deleteCount) || deleteCount < 0 || deleteCount > length - start) throw new PicoFlowPreconditionError("[PicoFlow] Delete count out of bounds");
+		const items = this._value.splice(start, deleteCount, ...newItems);
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "splice",
+			start,
+			deleteCount,
+			addedItems: newItems,
+			removedItems: items
+		});
+		return items;
+	}
+	clear() {
+		this._core.assertAlive();
+		const previousValue = [...this._value];
+		this._value = [];
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "clear",
+			clearedItems: previousValue
+		});
+		return previousValue;
+	}
+	dispose() {
+		super.dispose();
+		this.$lastAction.dispose();
+	}
+};
+
+//#endregion
+//#region src/core/api/nodes/collections/flowArray.ts
+/**
+* Creates a reactive array with mutation methods and fine-grained action tracking.
+*
+* The array starts with the provided initial items (or empty if none provided). All mutation methods
+* (push, pop, splice, etc.) notify dependents and emit detailed action information to `$lastAction`.
+* Use the array itself for coarse-grained reactivity, or subscribe to `$lastAction` for fine-grained
+* reactivity to specific mutation types. Useful for reactive lists, collections, or any data that
+* needs array-like operations with automatic change propagation.
+*
+* @param initial - Optional initial array of items
+* @param options - Optional settings; `name` identifies this primitive in error messages
+* @returns A FlowArray with reactive mutation methods
+*
+* @public
+*/
+function array(initial, options) {
+	return new ArrayNode(initial, options?.name);
+}
+
+//#endregion
+//#region src/core/nodes/mapNode.ts
+/**
+* Internal implementation of reactive map with mutation tracking.
+* @internal
+*/
+var MapNode = class extends ReadableNode {
+	$lastAction;
+	get _core() {
+		return super._core;
+	}
+	/** The live backing store, owned by the engine and mutated in place here. */
+	get _value() {
+		return this._core.current;
+	}
+	set _value(value) {
+		this._core.current = value;
+	}
+	constructor(value = /* @__PURE__ */ new Map(), name) {
+		super(syncCore(value, { name }), "map");
+		this.$lastAction = new ActionNode({
+			type: "set",
+			setMap: value,
+			clearedMap: /* @__PURE__ */ new Map()
+		}, name && `${name}.$lastAction`);
+	}
+	add(key, value) {
+		this._core.assertAlive();
+		if (this._value.has(key)) throw new PicoFlowPreconditionError("[PicoFlow] Key already exists");
+		this._value.set(key, value);
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "add",
+			key,
+			addedValue: value
+		});
+	}
+	setAt(key, value) {
+		this._core.assertAlive();
+		if (!this._value.has(key)) throw new PicoFlowPreconditionError("[PicoFlow] Key does not exist");
+		const previousValue = this._value.get(key);
+		this._value.set(key, value);
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "setAt",
+			key,
+			setValue: value,
+			clearedValue: previousValue
+		});
+	}
+	delete(key) {
+		this._core.assertAlive();
+		if (!this._value.has(key)) throw new PicoFlowPreconditionError("[PicoFlow] Key does not exist");
+		const value = this._value.get(key);
+		this._value.delete(key);
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "delete",
+			key,
+			removedValue: value
+		});
+		return value;
+	}
+	/** Notifies dependents without changing the contents. */
+	trigger() {
+		this._core.trigger();
+	}
+	set(map) {
+		this._core.assertAlive();
+		const previousValue = this._value;
+		if (!this._core.overwrite(map)) return;
+		this.$lastAction.set({
+			type: "set",
+			setMap: this._value,
+			clearedMap: previousValue
+		});
+	}
+	clear() {
+		this._core.assertAlive();
+		const previousValue = this._value;
+		this._value = /* @__PURE__ */ new Map();
+		this._core.notifyDependents();
+		this.$lastAction.set({
+			type: "clear",
+			clearedMap: previousValue
+		});
+		return previousValue;
+	}
+	dispose() {
+		super.dispose();
+		this.$lastAction.dispose();
+	}
+};
+
+//#endregion
+//#region src/core/api/nodes/collections/flowMap.ts
+function map(initial, options) {
+	if (initial instanceof Map) return new MapNode(initial, options?.name);
+	return new MapNode(new Map(initial ? Object.entries(initial) : []), options?.name);
+}
+
+//#endregion
+//#region src/core/api/nodes/flowSignal.ts
+/**
+* Creates a signal that can be manually triggered to notify dependents.
+*
+* Signals act as event emitters in the reactive graph. Call `trigger()` to notify all subscribers
+* and reactive computations that depend on the signal. Unlike state or derivations, signals don't
+* carry data values - they simply represent that an event occurred.
+*
+* @param options - Optional settings; `name` identifies this primitive in error messages
+* @returns A FlowSignal that can be triggered manually and subscribed to
+*
+* @public
+*/
+function signal(options) {
+	return new SignalNode(options?.name);
+}
+
+//#endregion
+//#region src/core/api/nodes/sync/flowConstant.ts
+/**
+* Creates a constant reactive value that initializes lazily and never recomputes.
+*
+* The initializer function runs once on first access, and the result is cached permanently.
+* Unlike state or derivations, constants never react to changes - they represent immutable values
+* in the reactive graph. Useful for expensive one-time computations or static configuration.
+*
+* @param initializer - Function that computes the constant value on first access
+* @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the default `===` change detection
+* @returns A FlowConstant that provides read-only access to the cached value
+*
+* @public
+*/
+function constant(initializer, options) {
+	return new ConstantNode(syncCore(initializer, options), "constant");
+}
+
+//#endregion
+//#region src/core/api/nodes/sync/flowState.ts
+function state(valueOrInitializer, options) {
+	return new StateNode(syncCore(valueOrInitializer, options), "state");
+}
+
+//#endregion
+//#region src/core/api/nodes/sync/flowWritableDerivation.ts
+/**
+* Creates a derived value that recomputes automatically but can also be manually overridden.
+*
+* The compute function tracks dependencies and recomputes when they change, just like a regular derivation.
+* However, you can also call `set()` to override the computed value. Use this for values that are normally
+* derived but need occasional manual adjustments, such as editable calculated fields or user-correctable totals.
+*
+* @param compute - Function that accesses dependencies and computes the derived value
+* @param options - Optional settings; `name` identifies this primitive in error messages, `equals` overrides the
+*   default `===` change detection, `eager` recomputes on dirty instead of on read (#118)
+* @returns A FlowWritableDerivation that provides both reactive computation and manual control
+*
+* @public
+*/
+function writableDerivation(compute, options) {
+	return new WritableDerivationNode(syncCore(compute, options, true), "writableDerivation");
+}
+
+//#endregion
+export { PicoFlowCycleError, PicoFlowDisposedError, PicoFlowError, PicoFlowInternalError, PicoFlowPreconditionError, array, constant, constantAsync, derivation, derivationAsync, isDisposable, map, onFlushError, reset, signal, state, stateAsync, subscribe, writableDerivation, writableDerivationAsync };