@pond-ts/process 0.54.0

package/dist/node.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Nodes: units of computation with typed ports, and the pull-based
+ * evaluation that drives them.
+ *
+ * ## Evaluation model
+ *
+ * Two mechanisms, doing two different jobs:
+ *
+ * - **Dirty marking (push)** tells a node "something upstream moved,
+ *   revalidate before answering." It propagates from the changed node
+ *   through every downstream edge, cutting off at nodes already marked,
+ *   so a change costs O(affected nodes) regardless of graph size. A
+ *   clean node answers `get()` from cache without walking anything.
+ *
+ * - **Version stamps (pull)** tell a node whether the change was real.
+ *   Each outlet's version increments only when a recomputed value
+ *   actually differs, and each node records the input versions it last
+ *   computed against. A dirty node whose input versions all match skips
+ *   `compute` entirely and stays cached.
+ *
+ * The second is what makes the layer worth having over plain function
+ * calls: setting a source that happens to produce an identical
+ * downstream value stops the cascade there, so expensive transforms
+ * further down never run. Dirty marking alone (as in a naive dataflow
+ * graph) would recompute the whole subtree on every touch.
+ */
+import { Inlet, Outlet } from './port.js';
+import type { PortSpec, PortSpecMap, PortValue, PortValues } from './types.js';
+/** The inlet map exposed as `node.in`. */
+export type InletsFor<In extends PortSpecMap> = {
+    readonly [K in keyof In]: Inlet<PortValue<In[K]>>;
+};
+/** The outlet map exposed as `node.out`. */
+export type OutletsFor<Out extends PortSpecMap> = {
+    readonly [K in keyof Out]: Outlet<PortValue<Out[K]>>;
+};
+/** Declares a reusable node type. Passed to {@link defineNode}. */
+export interface NodeSpec<In extends PortSpecMap, Out extends PortSpecMap> {
+    /** Stable identifier for this node type, used in errors and `toJSON()`. */
+    readonly kind: string;
+    readonly inputs: In;
+    readonly outputs: Out;
+    /**
+     * Produces every declared output from the current input values.
+     *
+     * Called only when an input version actually changed. Must be a pure
+     * function of its inputs — the engine caches the result and will not
+     * call it again until something upstream moves.
+     */
+    compute(inputs: PortValues<In>): PortValues<Out>;
+}
+/**
+ * A unit of computation with typed input and output ports.
+ *
+ * Construct via {@link defineNode} or {@link derive} rather than
+ * directly — both wire the port maps up from the spec.
+ */
+export declare class Node<In extends PortSpecMap = PortSpecMap, Out extends PortSpecMap = PortSpecMap> {
+    #private;
+    /** Unique within the process. Stable across a graph's lifetime. */
+    readonly id: string;
+    /** The node type's name, from its spec. */
+    readonly kind: string;
+    /** Typed input ports, keyed as declared. */
+    readonly in: InletsFor<In>;
+    /** Typed output ports, keyed as declared. */
+    readonly out: OutletsFor<Out>;
+    constructor(spec: NodeSpec<In, Out>);
+    /** Whether this node will revalidate on the next pull. */
+    get dirty(): boolean;
+    /**
+     * The error thrown by the most recent `compute`, or `undefined` if the
+     * last evaluation succeeded (or none has run). Cached alongside the
+     * value: an errored node rethrows without re-running `compute` until
+     * an input changes, so a broken node stays cheap to poll — useful when
+     * rendering a graph where one node is misconfigured.
+     */
+    get error(): unknown;
+    /**
+     * Forces this node to recompute on the next pull, even if no input
+     * version changed, and marks everything downstream dirty.
+     *
+     * Needed when a node's output depends on something the graph can't
+     * see — a settable source value, an external mutable resource.
+     */
+    invalidate(): void;
+}
+/** Creates instances of a declared node type. */
+export interface NodeFactory<In extends PortSpecMap, Out extends PortSpecMap> {
+    (): Node<In, Out>;
+    /** The `kind` of the nodes this factory produces. */
+    readonly kind: string;
+}
+/**
+ * Declares a reusable node type and returns a factory for it.
+ *
+ * ```ts
+ * const Stats = defineNode({
+ *   kind: 'stats',
+ *   inputs: { series: port<TimeSeries<Schema>>() },
+ *   outputs: { mean: port<number>(), max: port<number>() },
+ *   compute: ({ series }) => ({
+ *     mean: series.column('cpu').mean(),
+ *     max: series.column('cpu').max(),
+ *   }),
+ * });
+ *
+ * const stats = Stats();
+ * raw.out.value.connect(stats.in.series);
+ * stats.out.mean.get();
+ * ```
+ *
+ * For a node type that needs per-instance configuration, close over it:
+ * `const smoother = (span: number) => defineNode({ ... })();`
+ */
+export declare function defineNode<In extends PortSpecMap, Out extends PortSpecMap>(spec: NodeSpec<In, Out>): NodeFactory<In, Out>;
+/** Extracts the value type carried by an {@link Outlet}. */
+export type OutletValue<O> = O extends Outlet<infer T> ? T : never;
+/** The spec map implied by a record of source outlets. */
+export type SpecsForOutlets<M> = {
+    [K in keyof M]: PortSpec<OutletValue<M[K]>>;
+};
+/** The single-output spec map produced by {@link derive}. */
+export type DerivedOutput<R> = {
+    readonly value: PortSpec<R>;
+};
+/**
+ * Builds a single-output node and wires it to its sources in one step —
+ * the shape most graph edges take.
+ *
+ * ```ts
+ * const smoothed = derive({ series: raw.out.value }, ({ series }) =>
+ *   series.smooth('cpu', { method: 'ema', alpha: 0.3 }),
+ * );
+ * smoothed.out.value.get();
+ * ```
+ *
+ * Equivalent to {@link defineNode} with one output named `value`, an
+ * input per source key, and the connections already made. Reach for
+ * `defineNode` when a node has several outputs, or when the node type is
+ * reused across graphs and deserves a name.
+ */
+export declare function derive<Sources extends Readonly<Record<string, Outlet<any>>>, R>(sources: Sources, compute: (inputs: {
+    [K in keyof Sources]: OutletValue<Sources[K]>;
+}) => R, options?: {
+    /** Node type name for errors and `toJSON()`. Defaults to `'derive'`. */
+    readonly kind?: string;
+    /** Change test for the output. Defaults to `Object.is`. */
+    readonly equals?: (a: R, b: R) => boolean;
+}): Node<SpecsForOutlets<Sources>, DerivedOutput<R>>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.js

@@ -0,0 +1,268 @@
+/**
+ * Nodes: units of computation with typed ports, and the pull-based
+ * evaluation that drives them.
+ *
+ * ## Evaluation model
+ *
+ * Two mechanisms, doing two different jobs:
+ *
+ * - **Dirty marking (push)** tells a node "something upstream moved,
+ *   revalidate before answering." It propagates from the changed node
+ *   through every downstream edge, cutting off at nodes already marked,
+ *   so a change costs O(affected nodes) regardless of graph size. A
+ *   clean node answers `get()` from cache without walking anything.
+ *
+ * - **Version stamps (pull)** tell a node whether the change was real.
+ *   Each outlet's version increments only when a recomputed value
+ *   actually differs, and each node records the input versions it last
+ *   computed against. A dirty node whose input versions all match skips
+ *   `compute` entirely and stays cached.
+ *
+ * The second is what makes the layer worth having over plain function
+ * calls: setting a source that happens to produce an identical
+ * downstream value stops the cascade there, so expensive transforms
+ * further down never run. Dirty marking alone (as in a naive dataflow
+ * graph) would recompute the whole subtree on every touch.
+ */
+import { CycleError, MissingOutputError, ProcessError } from './errors.js';
+import { Inlet, Outlet } from './port.js';
+let nextNodeId = 1;
+/**
+ * A unit of computation with typed input and output ports.
+ *
+ * Construct via {@link defineNode} or {@link derive} rather than
+ * directly — both wire the port maps up from the spec.
+ */
+export class Node {
+    /** Unique within the process. Stable across a graph's lifetime. */
+    id;
+    /** The node type's name, from its spec. */
+    kind;
+    /** Typed input ports, keyed as declared. */
+    in;
+    /** Typed output ports, keyed as declared. */
+    out;
+    #compute;
+    #inlets;
+    #outlets;
+    #dirty = true;
+    #computed = false;
+    #evaluating = false;
+    #inputVersions = new Map();
+    #error = undefined;
+    #hasError = false;
+    constructor(spec) {
+        this.id = `n${nextNodeId++}`;
+        this.kind = spec.kind;
+        this.#compute = (inputs) => spec.compute(inputs);
+        // Null-prototype maps: a port legitimately named `__proto__` would
+        // otherwise hit the prototype setter instead of defining a key,
+        // leaving the node with no ports at all and a hijacked `node.in`.
+        const inlets = Object.create(null);
+        for (const [name, portSpec] of Object.entries(spec.inputs)) {
+            inlets[name] = new Inlet(this, name, portSpec.defaultValue);
+        }
+        const outlets = Object.create(null);
+        for (const [name, portSpec] of Object.entries(spec.outputs)) {
+            outlets[name] = new Outlet(this, name, portSpec.equals);
+        }
+        this.in = Object.freeze(inlets);
+        this.out = Object.freeze(outlets);
+        this.#inlets = Object.values(inlets);
+        this.#outlets = Object.values(outlets);
+    }
+    /** Whether this node will revalidate on the next pull. */
+    get dirty() {
+        return this.#dirty;
+    }
+    /**
+     * The error thrown by the most recent `compute`, or `undefined` if the
+     * last evaluation succeeded (or none has run). Cached alongside the
+     * value: an errored node rethrows without re-running `compute` until
+     * an input changes, so a broken node stays cheap to poll — useful when
+     * rendering a graph where one node is misconfigured.
+     */
+    get error() {
+        return this.#error;
+    }
+    /**
+     * Forces this node to recompute on the next pull, even if no input
+     * version changed, and marks everything downstream dirty.
+     *
+     * Needed when a node's output depends on something the graph can't
+     * see — a settable source value, an external mutable resource.
+     */
+    invalidate() {
+        this.#computed = false;
+        this.markDirty();
+    }
+    /** @internal Marks stale and propagates downstream, cutting off at nodes already dirty. */
+    markDirty() {
+        if (this.#dirty)
+            return;
+        this.#dirty = true;
+        for (const outlet of this.#outlets)
+            outlet.invalidateDownstream();
+    }
+    /** @internal */
+    inletList() {
+        return this.#inlets;
+    }
+    /** @internal */
+    outletList() {
+        return this.#outlets;
+    }
+    /** @internal Brings this node's outlets up to date. See the module docstring. */
+    ensureFresh() {
+        // The re-entrancy check must precede the clean-node early return.
+        // `#dirty` is cleared before `compute` runs, so a compute that pulls
+        // its own node would otherwise take the early return and be handed
+        // the *previous* cached value — a silently stale result instead of
+        // the cycle it actually is.
+        if (this.#evaluating) {
+            throw new CycleError(`Node '${this.kind}' was pulled while it was still evaluating — its compute re-entered the graph`);
+        }
+        if (!this.#dirty) {
+            if (this.#hasError)
+                throw this.#error;
+            return;
+        }
+        this.#evaluating = true;
+        try {
+            // Refresh upstream first, then compare versions: a dirty mark says
+            // "maybe stale", the versions say whether anything really moved.
+            const versions = new Map();
+            let changed = !this.#computed;
+            for (const inlet of this.#inlets) {
+                try {
+                    inlet.source?.node.ensureFresh();
+                }
+                catch (error) {
+                    // Upstream failed. Drop any error cached from this node's own
+                    // last compute: it is no longer why this node can't produce a
+                    // value, and leaving it would point a graph inspector at the
+                    // wrong node. The failing upstream keeps its own `error`.
+                    this.#error = undefined;
+                    this.#hasError = false;
+                    throw error;
+                }
+                const version = inlet.sourceVersion();
+                versions.set(inlet.name, version);
+                if (this.#inputVersions.get(inlet.name) !== version)
+                    changed = true;
+            }
+            this.#dirty = false;
+            if (!changed) {
+                if (this.#hasError)
+                    throw this.#error;
+                return;
+            }
+            this.#inputVersions = versions;
+            this.#computed = true;
+            // Reading inputs, computing, and storing outputs share one catch:
+            // all three can fail, and a node that fails any of them must end
+            // up in the same state — error cached, rethrown on every pull
+            // until an input changes. Catching only around `compute` left a
+            // node that threw while reading an unconnected input marked clean
+            // with no value and no error, so the second pull reported a
+            // misleading "produced no value" instead of the real cause.
+            try {
+                const inputs = {};
+                for (const inlet of this.#inlets)
+                    inputs[inlet.name] = inlet.get();
+                const produced = this.#compute(inputs);
+                if (produced === null || typeof produced !== 'object') {
+                    throw new MissingOutputError(`Node '${this.kind}' compute must return an object of output values`);
+                }
+                const values = produced;
+                for (const outlet of this.#outlets) {
+                    // `hasOwn`, not `in`: `in` walks the prototype chain, so an
+                    // output named `toString` or `valueOf` would silently pass the
+                    // guard and publish an `Object.prototype` member as its value.
+                    if (!Object.hasOwn(values, outlet.name)) {
+                        throw new MissingOutputError(`Node '${this.kind}' compute did not return output '${outlet.name}'`);
+                    }
+                    outlet.produce(values[outlet.name]);
+                }
+                this.#error = undefined;
+                this.#hasError = false;
+            }
+            catch (error) {
+                this.#error = error;
+                this.#hasError = true;
+                throw error;
+            }
+        }
+        finally {
+            this.#evaluating = false;
+        }
+    }
+}
+/**
+ * Declares a reusable node type and returns a factory for it.
+ *
+ * ```ts
+ * const Stats = defineNode({
+ *   kind: 'stats',
+ *   inputs: { series: port<TimeSeries<Schema>>() },
+ *   outputs: { mean: port<number>(), max: port<number>() },
+ *   compute: ({ series }) => ({
+ *     mean: series.column('cpu').mean(),
+ *     max: series.column('cpu').max(),
+ *   }),
+ * });
+ *
+ * const stats = Stats();
+ * raw.out.value.connect(stats.in.series);
+ * stats.out.mean.get();
+ * ```
+ *
+ * For a node type that needs per-instance configuration, close over it:
+ * `const smoother = (span: number) => defineNode({ ... })();`
+ */
+export function defineNode(spec) {
+    const factory = () => new Node(spec);
+    return Object.assign(factory, { kind: spec.kind });
+}
+/**
+ * Builds a single-output node and wires it to its sources in one step —
+ * the shape most graph edges take.
+ *
+ * ```ts
+ * const smoothed = derive({ series: raw.out.value }, ({ series }) =>
+ *   series.smooth('cpu', { method: 'ema', alpha: 0.3 }),
+ * );
+ * smoothed.out.value.get();
+ * ```
+ *
+ * Equivalent to {@link defineNode} with one output named `value`, an
+ * input per source key, and the connections already made. Reach for
+ * `defineNode` when a node has several outputs, or when the node type is
+ * reused across graphs and deserves a name.
+ */
+export function derive(sources, compute, options = {}) {
+    const inputs = {};
+    for (const name of Object.keys(sources))
+        inputs[name] = {};
+    const outputValue = options.equals
+        ? { equals: options.equals }
+        : {};
+    const node = new Node({
+        kind: options.kind ?? 'derive',
+        inputs: inputs,
+        outputs: { value: outputValue },
+        compute: (values) => ({
+            value: compute(values),
+        }),
+    });
+    for (const [name, outlet] of Object.entries(sources)) {
+        const inlet = node.in[name];
+        if (inlet === undefined) {
+            // Unreachable: the inputs above are built from these same keys.
+            throw new ProcessError(`Node '${node.kind}' has no input named '${name}'`);
+        }
+        outlet.connect(inlet);
+    }
+    return node;
+}
+//# sourceMappingURL=node.js.map

package/dist/plan/builder.d.ts

@@ -0,0 +1,138 @@
+/**
+ * A programmable API that **emits** a plan — [PND-PROCBUILD].
+ *
+ * Plans-as-data is right for a wire format and required for a cache key,
+ * but it is not how an application wants to *author* a graph. A consumer
+ * building studies over its own metrics should not be assembling nested
+ * JSON by hand.
+ *
+ * ```ts
+ * const g = plan('ACME_5m').as('bands_and_stretch');
+ * const bb = g.add('bb', 'bollinger', { period: 20 }, ['px']);
+ * const z = g.add('z', 'zscore', { period: 20 }, ['px']);
+ *
+ * g.expose('upper_band', bb.last({ output: 'Upper' }));
+ * g.expose('stretch', z.percentileRank());
+ * g.expose('band_series', bb.columns());
+ *
+ * host.run(g.toJSON());
+ * ```
+ *
+ * **Slots are what make this possible**, which is why this depends on
+ * [PND-PROCSLOT] rather than standing alone: a builder needs a stable
+ * handle to refer back to, and a content-addressed id cannot be one — it
+ * changes the moment a param does. A slot is exactly a handle, and
+ * passing `bb` rather than the string `'bb'` is what turns a typo into a
+ * compile error.
+ *
+ * **The builder emits a plan; it does not replace one.** `toJSON()`
+ * produces the same envelope a model would compose, so there is one
+ * resolution path, one cache, and one thing to test — a graph built in
+ * code and one composed by a model land on the same nodes.
+ *
+ * It deliberately knows nothing about the registry: no op-name checking,
+ * no param typing. That keeps it a pure authoring layer with no
+ * dependency on the op corpus, and leaves the resolver as the single
+ * place a bad plan is diagnosed. Typing params off `ParamDef` is the
+ * open question in the ticket, not a gap this file is hiding.
+ */
+import { ProcessError } from '../errors.js';
+import type { Select } from './run.js';
+import type { SourceRef } from './source.js';
+import type { Slots } from './slots.js';
+import type { ParamValue } from './types.js';
+/** Thrown when a graph is built wrong — before it is ever sent. */
+export declare class BuilderError extends ProcessError {
+}
+/**
+ * The derived slot for a fold over `on` — a function of the node, the
+ * fold, **and its params**. Params used to be omitted, so
+ * `shape({points: 20})` followed by `shape({points: 100})` landed on one
+ * slot and the second call silently kept 20. Sorted by key so two
+ * spellings of one param set collide deliberately, the same rule
+ * `specId` applies one layer down.
+ *
+ * One asymmetry is inherent: this builder holds no registry, so it
+ * cannot resolve defaults — `shape()` and `shape({points: 40})` derive
+ * two slots here even though `specId` resolves them to one computation.
+ * That is safe: resolution collapses them to one node, and the response
+ * labels it with the first slot that named it. The registry-bound
+ * fluent layer canonicalizes params before calling this, so it does not
+ * split.
+ */
+export declare function foldSlot(on: string, op: string, params?: Readonly<Record<string, ParamValue>>): string;
+/** One named output of a multi-output node. */
+export interface OutputHandle {
+    readonly slot: string;
+    readonly output: string;
+}
+/** What a node's inputs may be: a source column, a node, or one named output. */
+export type InputRef = string | NodeHandle | OutputHandle;
+/**
+ * A reference to a node in the graph under construction.
+ *
+ * The fold methods **add a node** and hand back a handle to it, rather
+ * than producing a selector as they used to. That is the whole shape of
+ * [PND-PROCFOLD] at the authoring layer: `z.percentileRank()` always
+ * read like an op call, and now it is one.
+ *
+ * The derived slot is `<slot>:<fold>` — with the fold's params folded in
+ * when it has any, e.g. `<slot>:shape(points=100)`. Deterministic in all
+ * three, so calling `.last()` twice on the same node returns the same
+ * node rather than colliding, while `shape({points: 20})` and
+ * `shape({points: 100})` are two nodes rather than the second silently
+ * answering with the first's 20. Safe against a source column name,
+ * which cannot contain a colon.
+ */
+export interface NodeHandle {
+    readonly slot: string;
+    /** Latest defined value, with when. */
+    last(): NodeHandle;
+    /** Minimum and maximum, each with when. */
+    extremes(): NodeHandle;
+    /** Where the latest value sits in its own history. */
+    percentileRank(): NodeHandle;
+    /** A bounded sample of the whole series. */
+    shape(options?: {
+        points?: number;
+    }): NodeHandle;
+}
+/** The envelope a builder produces — what `Host.run` takes. */
+export interface BuiltRequest<From extends string | SourceRef = string> {
+    readonly from: From;
+    readonly as?: string;
+    readonly nodes: Slots;
+    readonly outputs: Readonly<Record<string, Select>>;
+}
+export declare class PlanBuilder<From extends string | SourceRef = string> {
+    #private;
+    constructor(from: From);
+    /** Names the result, so a later request can refer back to it. */
+    as(name: string): this;
+    /**
+     * Adds a node under a caller-chosen slot name.
+     *
+     * The name is required rather than derived, because it *is* the stable
+     * identity — deriving `sma2` from a counter would renumber the moment
+     * a node is inserted above it, which is the property slots exist to
+     * provide.
+     *
+     * @throws {BuilderError} if the slot is already taken.
+     */
+    add(slot: string, op: string, params: Readonly<Record<string, ParamValue>> | undefined, inputs: readonly InputRef[]): NodeHandle;
+    /**
+     * Surfaces a node under the caller's own name.
+     *
+     * Takes a handle, because a selector's only remaining job is to point
+     * at a node — what comes back is whatever that node produces.
+     *
+     * @throws {BuilderError} if the name is already used.
+     */
+    expose(name: string, node: NodeHandle, options?: {
+        output?: string;
+    }): this;
+    /** The envelope. Plain JSON — nothing here survives into the request. */
+    toJSON(): BuiltRequest<From>;
+}
+export declare function plan<const From extends string | SourceRef>(from: From): PlanBuilder<From>;
+//# sourceMappingURL=builder.d.ts.map