@ersbeth/picoflow 2.3.1 → 3.0.0

package/dist/shared2.d.ts

@@ -0,0 +1,93 @@
+import { r as FlowObservable } from "./shared.js";
+//#region src/core/api/base/flowPrimitiveOptions.d.ts
+/**
+ * Compares the value a primitive currently holds against the one being written, and returns `true`
+ * when the two count as the same — in which case nothing is notified.
+ *
+ * Defaults to `===` (see {@link FlowPrimitiveOptions.equals}). Called only on the `resolved` path,
+ * where `previous` is the live value rather than a stale cache.
+ *
+ * A comparator that throws does not throw back at whoever wrote: it fails the node with that error,
+ * the write is not applied, and the error surfaces on the next read and in `subscribe`'s `onError`
+ * — the same contract a throwing `update()` updater follows. A comparator that throws on every call
+ * therefore fails every write, the recovering `set()` included; that is a comparator to fix.
+ *
+ * @public
+ */
+type FlowEquals<T> = (previous: T, next: T) => boolean;
+/**
+ * Optional per-instance settings accepted by the primitive factories (`state`, `derivation`,
+ * `array`, `map`, `signal`, …).
+ *
+ * @public
+ */
+interface FlowPrimitiveOptions<T = unknown> {
+  /**
+   * Identifies this primitive in error messages, e.g. `"[PicoFlow] Primitive \"$count\" is disposed"`
+   * instead of the unnamed `"[PicoFlow] Primitive is disposed"`. Purely diagnostic — has no effect
+   * on reactive behavior.
+   */
+  name?: string;
+  /**
+   * Decides whether a write counts as a change. Defaults to `===`, which means `NaN` written over
+   * `NaN` re-notifies, `-0` is indistinguishable from `0`, and an object mutated in place and
+   * written back under the same reference is a silent no-op (A2-SEM-4). Pass `Object.is` for the
+   * first two, or a structural comparator for the third.
+   *
+   * Honoured by the value primitives only — `array()`, `map()` and `signal()` ignore it, having no
+   * single value to compare.
+   *
+   * A comparator that throws fails the node rather than the write call — see {@link FlowEquals}.
+   */
+  equals?: FlowEquals<T>;
+  /**
+   * Recomputes this primitive as soon as it becomes dirty — at the next flush, whether or not
+   * anything reads it — instead of lazily at the next read (#118). An eager primitive computes
+   * for the first time at the first flush after creation. Defaults to `false`, the documented
+   * lazy model: no reader, no work.
+   *
+   * Honoured by the derivation factories only (`derivation`, `writableDerivation`,
+   * `derivationAsync`, `writableDerivationAsync`) — `state`, `constant`, the collections and
+   * `signal` ignore it, having no dependency-driven recomputation to hasten.
+   */
+  eager?: boolean;
+}
+//#endregion
+//#region src/core/api/nodes/flowSignal.d.ts
+/**
+ * Manual trigger that notifies subscribers without carrying data.
+ *
+ * Unlike reactive state or derivations, signals don't hold values. They serve as event emitters
+ * that notify dependents when explicitly triggered. Use signals for side effects that should run
+ * in response to manual actions rather than data changes.
+ *
+ * @public
+ */
+interface FlowSignal extends FlowObservable<void> {
+  /**
+   * Notifies every dependent that the event occurred.
+   *
+   * A signal carries no value, so this is its only emission: dependents are queued for the next
+   * flush whether or not anything else changed. Two triggers in the same synchronous turn coalesce
+   * into one run, like any other batched notification.
+   *
+   * Declared here rather than on {@link FlowObservable} because forcing dependents to re-run is a
+   * write, not a read: a `constant()` or a `derivation()` must not offer it (A3-ARCH-1, #132).
+   */
+  trigger(): void;
+}
+/**
+ * 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
+ */
+declare function signal(options?: FlowPrimitiveOptions): FlowSignal;
+//#endregion
+export { FlowPrimitiveOptions as i, signal as n, FlowEquals as r, FlowSignal as t };

package/dist/shared2.js

@@ -0,0 +1,59 @@
+import { a as ReadableNode, o as EffectNode, r as syncCore } from "./shared.js";
+
+//#region src/core/nodes/derivationNode.ts
+/**
+* The primitive behind `derivation()` and `derivationAsync()`: readable, and recomputable on demand
+* through `refresh()`. No `set`, no `update` (#26, A2-SEM-3).
+* @internal
+*/
+var DerivationNode = class extends ReadableNode {
+	refresh() {
+		this._core.refresh();
+	}
+};
+
+//#endregion
+//#region src/core/api/nodes/flowEffect.ts
+/**
+* Creates a reactive effect that runs immediately and automatically re-runs when dependencies change.
+*
+* The effect function tracks any reactive values accessed and subscribes to their changes.
+* When any tracked value changes, the effect re-executes with the new values.
+* Optional callbacks handle errors and pending async states.
+*
+* @param data - Function that accesses reactive dependencies and returns data
+* @param onData - Callback invoked with the computed data on each execution
+* @param onError - Optional callback for handling errors during execution
+* @param onPending - Optional callback invoked when async dependencies are pending
+* @param options - Optional settings; `name` identifies the effect in errors and inspection dumps
+* @returns A FlowEffect handle with a `dispose()` method to stop the effect
+*
+* @public
+*/
+function subscribe(data, onData, onError, onPending, options) {
+	return new EffectNode(data, onData, onError, onPending, options?.name);
+}
+
+//#endregion
+//#region src/core/api/nodes/sync/flowDerivation.ts
+/**
+* Creates a derived reactive value that automatically recomputes when dependencies change.
+*
+* The compute function runs when any tracked dependency changes, and the result is cached until the next change.
+* Access reactive values within the compute function to establish dependencies automatically. The derivation
+* computes lazily on first access and then reactively thereafter. Use for derived data that should stay
+* synchronized with source state.
+*
+* @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 FlowDerivation that provides read-only access to the computed value
+*
+* @public
+*/
+function derivation(compute, options) {
+	return new DerivationNode(syncCore(compute, options, true), "derivation");
+}
+
+//#endregion
+export { subscribe as n, DerivationNode as r, derivation as t };

package/dist/shared3.d.ts

@@ -0,0 +1,54 @@
+import { n as FlowValue } from "./shared.js";
+//#region src/core/api/nodes/utils.d.ts
+/**
+ * The type `NotPromise<T>` resolves to when `T` is a promise.
+ *
+ * A string literal rather than `never`, so the compiler diagnostic spells out the mistake and its fix
+ * ("… is not assignable to parameter of type '[PicoFlow] A Promise cannot be held …'") instead of the
+ * opaque "not assignable to type 'never'". Being a literal, a plain string equal to this exact text
+ * would technically be accepted where a promise is refused — a hole too narrow to matter in practice.
+ *
+ * @public
+ */
+type PromiseNotAllowed = "[PicoFlow] A Promise cannot be held by a synchronous primitive; use stateAsync, derivationAsync or constantAsync";
+/**
+ * Type that excludes Promise values from a type.
+ *
+ * This utility type ensures that synchronous reactive primitives (like `state`, `constant`, `derivation`)
+ * only accept non-Promise values. Use this to prevent accidental mixing of sync and async values, which
+ * would cause runtime errors. For async values, use the async variants (like `stateAsync`, `constantAsync`).
+ *
+ * A promise resolves to {@link PromiseNotAllowed}, so the compiler error names the problem; a union that
+ * includes a promise member is rejected rather than silently narrowed to its other members.
+ *
+ * The check is **one level deep**, by design: a promise nested inside an object or an array
+ * (`state({ inner: fetchUser() })`) is not detected. Deep detection would be costly and would reject
+ * legitimate models that hold promises as data.
+ *
+ * @public
+ */
+type NotPromise<T> = T extends Promise<unknown> ? PromiseNotAllowed : T;
+/**
+ * Type that narrows a reactive value to its read side.
+ *
+ * In practice it removes nothing: all four names live on the writable interfaces (`FlowState`,
+ * `FlowWritableDerivation`) rather than on `FlowValue` — `set`, `update` and `refresh` since #114,
+ * `trigger` since #132 (A3-ARCH-1), which moved it off the read side for the same reason. They stay
+ * named in the `Omit` as the statement of intent, and so that a mutator ever added to `FlowValue`
+ * is stripped here without a second edit.
+ *
+ * Use it to hand a reactive value to code that should observe it but not write to it — a child
+ * component, a module that only renders — while keeping write access where the value was created.
+ *
+ * This is a **compile-time narrowing only**: it removes the methods from the *type*, not from the
+ * object, which keeps whatever its factory gave it. A `FlowState` passed as `FlowReadonly` still has
+ * `set` at runtime, reachable through a cast or from JavaScript. For a value that must be read-only
+ * everywhere, create it with `constant()` or `derivation()` (or their async forms): since #114 those
+ * carry no mutator at all, so a `FlowReadonly` backed by one of them is read-only at runtime too
+ * (#32, A2-ARCH-3).
+ *
+ * @public
+ */
+type FlowReadonly<T> = Omit<FlowValue<T>, "set" | "update" | "refresh" | "trigger">;
+//#endregion
+export { NotPromise as n, PromiseNotAllowed as r, FlowReadonly as t };

package/dist/shared3.js

@@ -0,0 +1,17 @@
+import { c as Observable, o as EffectNode } from "./shared.js";
+
+//#region src/core/nodes/signalNode.ts
+/**
+* Manual trigger that notifies subscribers without carrying data.
+* @internal
+*/
+var SignalNode = class extends Observable {
+	_kind = "signal";
+	subscribe(onTrigger, onError, onPending, options) {
+		if (this._disposed) throw this._disposedError();
+		return new EffectNode((t) => this.watch(t), onTrigger, onError, onPending, options?.name);
+	}
+};
+
+//#endregion
+export { SignalNode as t };

package/dist/{types/converters/solid.d.ts → solid.d.ts}

@@ -1,5 +1,8 @@
-import { Resource } from 'solid-js';
-import { FlowTracker, FlowValue, NotPromise } from '../api/index.js';
+/// <reference lib="esnext.disposable" preserve="true" />
+import { l as FlowTracker, n as FlowValue } from "./shared.js";
+import { n as NotPromise } from "./shared3.js";
+import { Resource } from "solid-js";
+//#region src/converters/solid.d.ts
 /**
  * Converts a PicoFlow value or getter function into a SolidJS resource.
  *
@@ -24,9 +27,9 @@ import { FlowTracker, FlowValue, NotPromise } from '../api/index.js';
  * to `from()` are not disposed.
  *
  * @example
- * ```typescript
- * import { from } from 'picoflow/solid';
- * import { state, derivation } from 'picoflow';
+ * ```tsx
+ * import { state } from '@ersbeth/picoflow';
+ * import { from } from '@ersbeth/picoflow/solid';
  *
  * // Convert a PicoFlow state to a Solid resource
  * const $count = state(0);
@@ -38,12 +41,11 @@ import { FlowTracker, FlowValue, NotPromise } from '../api/index.js';
  * }
  *
  * // Or convert a computation function
- * const solidDerived = from((t) => {
- *   return $count.get(t) * 2;
- * });
+ * const solidDerived = from((t) => $count.get(t) * 2);
  * ```
  *
  * @public
  */
 export declare function from<T>(flow: FlowValue<T>): Resource<T>;
 export declare function from<T>(flow: (t: FlowTracker) => NotPromise<T>): Resource<T>;
+//#endregion

package/dist/solid.js

@@ -0,0 +1,63 @@
+import { _ as PicoFlowPreconditionError, i as PICOFLOW_VALUE_NODE } from "./shared.js";
+import { n as subscribe, t as derivation } from "./shared2.js";
+import { createEffect, createResource, onCleanup, onMount, resetErrorBoundaries } from "solid-js";
+
+//#region src/converters/solid.ts
+function describeFlowInput(value) {
+	if (value === null) return "null";
+	if (typeof value === "object") {
+		const name = value.constructor?.name;
+		return name ? `object (${name})` : "object";
+	}
+	return typeof value;
+}
+/**
+* Tests for the `picoflow.node` brand rather than `instanceof`: two copies of picoflow in one
+* dependency tree produce two distinct `ReadableNode` class objects, and a node
+* built by one copy fails `instanceof` in the other. `Symbol.for()` resolves to the same value
+* across module copies, so the brand survives that split (A2-RT-1).
+*/
+function isValueNode(flow) {
+	return typeof flow === "object" && flow !== null && PICOFLOW_VALUE_NODE in flow;
+}
+/**
+* Internal helper that converts a PicoFlow node into a SolidJS resource.
+* @internal
+*/
+function fromNode(node, options) {
+	const [resource, { refetch }] = createResource(() => node.pick());
+	let fx;
+	onMount(() => {
+		fx = subscribe((t) => node.get(t), () => {
+			refetch();
+		}, () => {
+			refetch();
+		}, () => {
+			refetch();
+		});
+	});
+	createEffect(() => {
+		resource.error ?? resource();
+		resetErrorBoundaries();
+	});
+	onCleanup(() => {
+		fx.dispose();
+		if (options?.disposeNode) node.dispose();
+	});
+	return resource;
+}
+/**
+* Internal helper that wraps a getter function in a PicoFlow node and converts it to a SolidJS resource.
+* @internal
+*/
+function fromGetter(getter) {
+	return fromNode(derivation(getter), { disposeNode: true });
+}
+function from(flow) {
+	if (isValueNode(flow)) return fromNode(flow);
+	if (typeof flow === "function") return fromGetter(flow);
+	throw new PicoFlowPreconditionError(`[PicoFlow] from(): expected a FlowValue or getter function, received ${describeFlowInput(flow)}`);
+}
+
+//#endregion
+export { from };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ersbeth/picoflow",
-    "version": "2.3.1",
+    "version": "3.0.0",
     "description": "Minimal Dataflow library for TypeScript",
     "type": "module",
     "packageManager": "pnpm@11.9.0",
@@ -12,48 +12,52 @@
         "SKILL.md"
     ],
     "exports": {
-        "types": "./dist/types/index.d.ts",
-        "default": "./dist/picoflow.js"
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./solid": {
+            "types": "./dist/solid.d.ts",
+            "default": "./dist/solid.js"
+        },
+        "./inspect": {
+            "types": "./dist/inspect.d.ts",
+            "default": "./dist/inspect.js"
+        }
     },
     "scripts": {
-        "check": "pnpm exec tsc --noEmit",
-        "lint": "pnpm exec biome check --fix",
-        "build": "pnpm exec vite build --config vite.config.ts",
-        "test": "pnpm exec vitest",
-        "test:coverage": "pnpm exec vitest run --coverage",
-        "test:browser": "pnpm exec vitest --config=vitest.browser.config.ts",
-        "test:browser:coverage": "pnpm exec vitest run --config=vitest.browser.config.ts --coverage",
-        "test:browser:matrix": "pnpm exec vitest run --config=vitest.browser.matrix.config.ts",
-        "test:coverage:merge": "rm -rf .vitest-reports && pnpm exec vitest run --coverage --reporter=blob --outputFile=.vitest-reports/node.json && pnpm exec vitest run --config=vitest.browser.config.ts --coverage --reporter=blob --outputFile=.vitest-reports/browser.json && pnpm exec vitest --mergeReports=.vitest-reports --coverage",
-        "ci:check": "pnpm exec tsc --noEmit",
-        "ci:lint": "pnpm exec biome check .",
-        "ci:test": "pnpm exec vitest run --coverage",
-        "ci:test:browser": "pnpm exec vitest run --config=vitest.browser.config.ts --coverage",
-        "ci:test:browser:matrix": "pnpm exec vitest run --config=vitest.browser.matrix.config.ts",
-        "ci:pack:smoke": "node tools/release/smoke-tarball.mjs",
-        "ci:release:check": "node tools/release/check-release.mjs",
-        "playwright:install": "playwright install --with-deps chromium firefox webkit",
-        "quality:diff": "node tools/quality/differential-graph.mjs 400",
-        "quality:bench": "node tools/quality/bench-core.mjs",
-        "quality:snippets": "node tools/quality/check-doc-snippets.mjs",
-        "quality:mutation": "bash tools/quality/mutation-test.sh"
+        "check": "pnpm exec vp check src test",
+        "lint": "pnpm exec vp check --fix src test",
+        "build": "pnpm exec vp pack",
+        "build:ci": "pnpm exec vp pack && git diff --exit-code dist/",
+        "test:install": "playwright install --with-deps chromium",
+        "test:core": "pnpm exec vp test --project core",
+        "test:core:ci": "pnpm exec vp test run --project core --coverage --coverage.include='src/core/**/*'",
+        "test:converters": "pnpm exec vp test --project converters",
+        "test:converters:ci": "pnpm exec vp test run --project converters --coverage --coverage.include='src/converters/**/*' --coverage.include='src/solid.ts'",
+        "verify:pre-commit": "pnpm check && pnpm build && pnpm test:core:ci",
+        "verify:ci": "pnpm check && pnpm build:ci && pnpm test:core:ci",
+        "verify:pre-push": "pnpm check && pnpm build:ci && pnpm test:core:ci && pnpm test:converters:ci"
     },
     "peerDependencies": {
-        "solid-js": "^1.9.7"
+        "solid-js": "^1.9.14"
+    },
+    "peerDependenciesMeta": {
+        "solid-js": {
+            "optional": true
+        }
     },
     "devDependencies": {
-        "@biomejs/biome": "2.3.8",
         "@solidjs/testing-library": "^0.8.10",
-        "@vitest/browser-playwright": "^4.1.10",
-        "@vitest/coverage-v8": "4.1.10",
-        "jsdom": "^27.3.0",
+        "@vitest/browser-playwright": "^4.1.11",
+        "@vitest/coverage-v8": "4.1.11",
+        "jsdom": "^27.4.0",
         "playwright": "1.62.1",
+        "solid-js": "^1.9.15",
         "typescript": "^5.9.3",
-        "vite": "^7.3.0",
-        "vite-plugin-dts": "^4.5.4",
-        "vite-plugin-solid": "^2.11.10",
-        "vite-tsconfig-paths": "^6.0.3",
-        "vitest": "^4.1.10"
+        "vite-plugin-solid": "^2.11.14",
+        "vite-plus": "0.3.1",
+        "vitest": "^4.1.11"
     },
     "repository": {
         "type": "git",