@nodish/core 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,519 @@
+import { Component } from 'vue';
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { DefineComponent } from 'vue';
+import { PublicProps } from 'vue';
+
+declare type __VLS_Props = {
+    map: NodeMap;
+    ioWidgets?: boolean;
+};
+
+/**
+ * Replace the map's graph and interface from a document.
+ * @returns Errors from extension checks before apply, then validation errors after apply.
+ */
+export declare function applyDocument(map: NodeMap, doc: GraphDocument): string[];
+
+/**
+ * Return the single Input and Output nodes on the graph.
+ * @throws When the graph does not contain exactly one of each.
+ */
+export declare function boundaryNodes(map: NodeMap): {
+    input: DefiniteNode;
+    output: DefiniteNode;
+};
+
+/** Serializable nested graph owned by a composite instance. */
+declare interface CompositeState {
+    graph: NodeGraph;
+    interface: GraphInterface;
+}
+
+/**
+ * Directed wire from an output port to an input port. Stored centrally on the
+ * graph so either endpoint can be looked up uniformly.
+ */
+export declare interface Connection {
+    id: ConnectionId;
+    /** Must reference an output port. */
+    from: PortRef;
+    /** Must reference an input port. */
+    to: PortRef;
+}
+
+export declare type ConnectionId = string;
+
+/**
+ * Create an in-memory graph workspace with registries, boundary nodes, and
+ * {@link NodeMap.loadPack} wired for widget setup.
+ *
+ * Registers built-in `number`/`string` widgets on first call (for packs that
+ * use those conventional type ids).
+ */
+export declare function createNodeMap(init?: CreateNodeMapInit): NodeMap;
+
+/** Options for the vue entry `createNodeMap()`. */
+export declare interface CreateNodeMapInit {
+    /** Initial graph contents. Defaults to empty nodes and connections. */
+    graph?: NodeGraph;
+    /** Pre-loaded pack ids (usually leave empty and use {@link NodeMap.loadPack}). */
+    extensions?: string[];
+    /** Graph boundary ports; defaults to no inputs and no outputs. */
+    graphInterface?: GraphInterface;
+    /** Extra types to merge into the registry at creation time. */
+    types?: TypeRegistry;
+    /** Extra node types to merge into the registry at creation time (authoring form). */
+    nodeTypes?: NodeSpecRegistry;
+    /** Packs to load immediately after creation (via {@link NodeMap.loadPack}). */
+    packs?: NodePack[];
+}
+
+/**
+ * Turn a {@link TypeSpec} into a complete {@link PortTypeDefinition}.
+ */
+export declare function defineType(spec: TypeSpec): PortTypeDefinition;
+
+/**
+ * A node placed on the workspace. Serializable data only — behaviour lives on
+ * the {@link IndefiniteNode} referenced by {@link DefiniteNode.typeId}.
+ */
+export declare interface DefiniteNode {
+    id: NodeId;
+    /** {@link IndefiniteNode} this instance was created from. */
+    typeId: NodeTypeId;
+    location: NodeLocation;
+    inputs: NodeIO;
+    outputs: NodeIO;
+    label?: string;
+    color?: string;
+    /** Node width in px. Falls back to layout default when undefined. */
+    width?: number;
+    /**
+     * Stacking order — higher paints on top. Stored for save/load. Undefined until
+     * first assigned.
+     */
+    z?: number;
+    /** Nested graph for composite/group instances. Serializable with the node. */
+    composite?: CompositeState;
+}
+
+/**
+ * Authoring form of {@link IndefiniteNode.resolvePorts}. Returns ports in
+ * {@link IOSpec} shape; normalized when registered via {@link registerNodeTypes}.
+ */
+export declare type DynamicPortsSpec = (params: Record<string, unknown>) => {
+    inputs?: IOSpec;
+    outputs?: IOSpec;
+};
+
+/** Serialize the current workspace to a {@link GraphDocument}. */
+export declare function exportGraph(map: NodeMap): GraphDocument;
+
+/**
+ * Serializable graph snapshot. Contains no `execute()` implementations or type
+ * definitions — custom nodes are resolved at runtime from loaded {@link NodePack}s.
+ */
+export declare interface GraphDocument {
+    graph: NodeGraph;
+    interface: GraphInterface;
+    /** Pack ids required to interpret this document. See {@link NodeMap.extensions}. */
+    extensions?: string[];
+}
+
+/**
+ * External signature of a graph. Parameters become the Input node's output ports;
+ * returns become the Output node's input ports.
+ */
+export declare interface GraphInterface {
+    /** Graph inputs (function parameters). Key = port name. */
+    parameters?: Record<string, GraphPortSpec>;
+    /** Graph outputs (return values). Key = port name. */
+    returns?: Record<string, GraphPortSpec>;
+}
+
+/** Serializable port template for boundary definitions (object key = port name). */
+export declare type GraphPortSpec = Omit<PortDefinition, "name">;
+
+export declare interface GraphRunResult {
+    /** Output port values from the graph's Output node, keyed by port name. */
+    values: Values;
+    /** First error per node encountered during evaluation. */
+    errors: NodeErrors;
+}
+
+/** Replace the map's graph from a document. Alias of {@link applyDocument}. */
+export declare function importGraph(map: NodeMap, doc: GraphDocument): string[];
+
+/**
+ * Node type template that {@link DefiniteNode} instances are created from. Lives
+ * in the runtime registry only (never in a saved graph). Authors ship types via
+ * {@link NodePack}.
+ *
+ * - **Primitive:** implements {@link IndefiniteNode.execute}.
+ * - **Composite:** supplies a nested {@link IndefiniteNode.graph} instead of `execute`.
+ */
+export declare interface IndefiniteNode {
+    /** Unique node type id (e.g. `"my-pack/add"`). */
+    typeId: NodeTypeId;
+    displayName: string;
+    color: string;
+    description: string;
+    /**
+     * Hierarchical menu category, broadest first, e.g. `["Math", "Basic Operations"]`.
+     * Empty or omitted places the node at the menu root.
+     */
+    group?: string[];
+    inputs: NodeIODefinition;
+    outputs: NodeIODefinition;
+    /**
+     * Runtime evaluation, keyed by port name (not id). Omit for composite types.
+     * @returns Output values keyed by port name.
+     */
+    execute?: (inputs: Record<string, unknown>) => Record<string, unknown>;
+    /** Nested subgraph for composite types (registry-only, not evaluated standalone). */
+    graph?: NodeGraph;
+    /**
+     * Dynamic port count driven by user-only inputs. When present, static
+     * `inputs`/`outputs` are initial defaults; reconciliation re-materializes
+     * ports by name so existing ids and connections survive a recount.
+     */
+    resolvePorts?: (params: Record<string, unknown>) => {
+        inputs: NodeIODefinition;
+        outputs: NodeIODefinition;
+    };
+}
+
+/** {@link IndefiniteNode.typeId} for the graph Input (Group Input) boundary node. */
+export declare const INPUT_TYPE = "io/input";
+
+/**
+ * Create a placed {@link DefiniteNode} from a node type, generating fresh port ids.
+ * For dynamic nodes, the initial port set comes from {@link IndefiniteNode.resolvePorts}
+ * seeded with the definition's default parameter values.
+ */
+export declare function instantiate(def: IndefiniteNode, location: NodeLocation): DefiniteNode;
+
+/** Input or output port templates keyed by port name. */
+export declare type IOSpec = Record<string, PortSpec>;
+
+/** Evaluation errors keyed by {@link NodeId}. */
+declare type NodeErrors = Record<NodeId, string>;
+
+/**
+ * Placed nodes and connections. Every graph must contain exactly one Input node
+ * and one Output node.
+ */
+export declare interface NodeGraph {
+    nodes: DefiniteNode[];
+    connections: Connection[];
+}
+
+export declare type NodeId = string;
+
+/** Materialized ports on an instance, keyed by id (connection/DOM-friendly). */
+declare type NodeIO = Record<PortId, Port>;
+
+/** Port templates on a definition, keyed by name (authoring-friendly). */
+declare type NodeIODefinition = Record<string, PortDefinition>;
+
+export declare type NodeLocation = {
+    x: number;
+    y: number;
+};
+
+/** In-memory workspace: serializable graph plus runtime type and node registries. */
+export declare interface NodeMap {
+    graph: NodeGraph;
+    types: TypeRegistry;
+    nodeTypes: NodeRegistry;
+    /** Ids of packs loaded via {@link NodeMap.loadPack}. */
+    extensions: string[];
+    graphInterface: GraphInterface;
+    /**
+     * Register types, nodes, and optional widget setup from a pack.
+     * @returns Registration errors (empty array on success).
+     */
+    loadPack(pack: NodePack): string[];
+}
+
+/**
+ * A publishable bundle of custom types and/or node types (npm package contents).
+ * Load onto a {@link NodeMap} with {@link NodeMap.loadPack}.
+ */
+export declare interface NodePack {
+    /** Unique pack id (e.g. `"@my-org/my-pack"`). Recorded in {@link GraphDocument.extensions}. */
+    id: string;
+    /** Custom {@link PortTypeDefinition}s to register. */
+    types?: TypeRegistry;
+    /** Custom node definitions to register (authoring form). */
+    nodeTypes?: NodeSpecRegistry;
+    /**
+     * Optional hook to register Vue widgets after types and nodes are merged.
+     * Runs once per pack load.
+     */
+    setup?: (ctx: PackSetupContext) => void;
+}
+
+/** Library of available node types, keyed by {@link NodeTypeId}. */
+export declare type NodeRegistry = Record<NodeTypeId, IndefiniteNode>;
+
+/**
+ * Authoring format for a node type. Normalized into a full {@link IndefiniteNode}
+ * when registered on a {@link NodeMap} (via {@link NodePack} or
+ * {@link registerNodeTypes}).
+ */
+export declare interface NodeSpec {
+    /** Unique node type id (e.g. `"my-pack/add"`). */
+    typeId: NodeTypeId;
+    displayName: string;
+    color?: string;
+    description?: string;
+    /**
+     * Hierarchical menu category, broadest first. See {@link IndefiniteNode.group}.
+     */
+    group?: string[];
+    inputs?: IOSpec;
+    outputs?: IOSpec;
+    /**
+     * Runtime evaluation, keyed by port name. Omit for composite node packs.
+     * @returns Output values keyed by port name.
+     */
+    execute?: (inputs: Record<string, unknown>) => Record<string, unknown>;
+    /** Nested subgraph for composite types in a published pack. Not evaluated yet. */
+    graph?: NodeGraph;
+    /**
+     * Dynamic port count driven by user-only inputs. Static `inputs`/`outputs`
+     * act as initial defaults when present.
+     */
+    resolvePorts?: DynamicPortsSpec;
+}
+
+/** Node types in authoring form, keyed by {@link NodeTypeId}. */
+export declare type NodeSpecRegistry = Record<NodeTypeId, NodeSpec>;
+
+declare type NodeTypeId = string;
+
+export declare const NodeViewer: DefineComponent<__VLS_Props, {
+resetView: typeof resetView;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+ioWidgets: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {
+viewerEl: HTMLDivElement;
+}, HTMLDivElement>;
+
+/** {@link IndefiniteNode.typeId} for the graph Output (Group Output) boundary node. */
+export declare const OUTPUT_TYPE = "io/output";
+
+/** Context passed to {@link NodePack.setup} for widget registration. */
+export declare interface PackSetupContext {
+    /**
+     * Bind a Vue component to all editable ports of a type id.
+     * Overrides the generic widget for that type.
+     */
+    registerTypeWidget: (typeId: string, component: Component) => void;
+    /**
+     * Bind a Vue component to a custom widget id
+     * ({@link TypeWidgetSpec} `kind: "custom"`).
+     */
+    registerComponentWidget: (componentId: string, component: Component) => void;
+}
+
+/**
+ * Parse a JSON string into a {@link GraphDocument}.
+ * @throws When JSON is invalid or required fields are missing.
+ */
+export declare function parseGraphDocument(json: string): GraphDocument;
+
+/**
+ * Materialized port on a placed node ({@link DefiniteNode}). Has a unique id so
+ * connections and the DOM can reference it directly.
+ */
+export declare type Port = {
+    id: PortId;
+    /** Matches the {@link PortDefinition.name} it came from. */
+    name: string;
+    type: PortType;
+    direction: PortDirection;
+    /** Input: value when disconnected. Output: optional cache of last computed value. */
+    value?: unknown;
+    userOnly?: boolean;
+    multi?: boolean;
+    customProps?: Record<string, unknown>;
+};
+
+/**
+ * Port template declared by a node type ({@link IndefiniteNode}). Has no id and
+ * no live value — only describes ports that instances will receive.
+ */
+export declare type PortDefinition = {
+    /** Stable, human-authored key; referenced inside `execute()`. */
+    name: string;
+    type: PortType;
+    /** Used by an input when nothing is connected to it. */
+    defaultValue?: unknown;
+    description?: string;
+    /**
+     * Input-only. Never accepts a connection — no socket, always shows its widget.
+     * Also feeds parameters into {@link IndefiniteNode.resolvePorts}.
+     */
+    userOnly?: boolean;
+    /**
+     * Input-only. Accepts any number of incoming connections; `execute()` receives
+     * values as an unordered array of `type`.
+     */
+    multi?: boolean;
+    /**
+     * Widget-specific configuration merged on top of the type's widget spec.
+     * Recognized keys: `options`, `min`, `max`, `step`, `rows`, `rowHeight`.
+     */
+    customProps?: Record<string, unknown>;
+};
+
+declare type PortDirection = "input" | "output";
+
+declare type PortId = string;
+
+/** Reference to one port on one node. */
+export declare type PortRef = {
+    node: NodeId;
+    port: PortId;
+};
+
+/**
+ * Port in a node spec — same as {@link GraphPortSpec}; the name comes from the
+ * object key so authors do not repeat it.
+ */
+export declare type PortSpec = GraphPortSpec;
+
+declare type PortType = PortTypeId;
+
+/**
+ * A registered data type. Carries validation, connection compatibility, and
+ * optional value lifecycle hooks. Registered at startup — only {@link PortTypeId}
+ * keys on ports are serialized in documents.
+ */
+export declare interface PortTypeDefinition {
+    id: PortTypeId;
+    label: string;
+    color: string;
+    validate: (value: unknown) => boolean;
+    /**
+     * Whether an output of type `from` may connect into an input of this type.
+     * Decided by the destination type. Omitted means strict identity (`from === id`).
+     */
+    accepts?: (from: PortTypeId) => boolean;
+    /** Fallback when a port of this type omits its own default. */
+    defaultValue?: unknown;
+    /** Display/edit descriptor for the viewer (no functions). */
+    widget?: TypeWidgetSpec;
+    /** Parse a raw string (e.g. from an input field) into a value. */
+    parse?: (raw: string) => unknown;
+    /** Format a value for display in the viewer. */
+    format?: (value: unknown) => string;
+    /** Normalize or clamp a value after edit or connection. */
+    coerce?: (value: unknown) => unknown;
+}
+
+/** Key into the {@link TypeRegistry} (e.g. `"number"`). */
+export declare type PortTypeId = string;
+
+/**
+ * Bind a Vue component to a custom widget id
+ * ({@link TypeWidgetSpec} `kind: "custom"`).
+ */
+export declare function registerComponentWidget(componentId: string, component: Component): void;
+
+/**
+ * Register built-in Vue widgets for conventional `number` and `string` type ids.
+ * Call once at app startup before loading packs that rely on those widgets.
+ */
+export declare function registerDefaultTypeWidgets(): void;
+
+/**
+ * Bind a Vue component to all editable ports of a type id.
+ * Overrides the generic widget for that type.
+ */
+export declare function registerTypeWidget(typeId: string, component: Component): void;
+
+declare function resetView(): void;
+
+/**
+ * Evaluate the graph as a function: supply values for the Input node's output
+ * ports (keyed by port name) and receive the Output node's input port values.
+ *
+ * Uses pull-based recursive evaluation with per-node memoization and cycle detection.
+ */
+export declare function runGraph(map: NodeMap, inputs?: Values): GraphRunResult;
+
+/**
+ * Serialize the current workspace to a {@link GraphDocument}.
+ * Alias of {@link exportGraph}.
+ */
+export declare function serializeDocument(map: NodeMap): GraphDocument;
+
+/** Library of available data types, keyed by id. */
+export declare type TypeRegistry = Record<PortTypeId, PortTypeDefinition>;
+
+/**
+ * Authoring format for a data type. {@link defineType} expands this into a full
+ * {@link PortTypeDefinition} (default label, color, and widget lifecycle hooks).
+ */
+export declare interface TypeSpec {
+    /** Unique type id (e.g. `"number"`, `"my-pack/label"`). */
+    id: PortTypeId;
+    label?: string;
+    color?: string;
+    validate: (value: unknown) => boolean;
+    /**
+     * Whether an output of type `from` may connect into ports of this type.
+     * Omitted means strict identity.
+     */
+    accepts?: (from: PortTypeId) => boolean;
+    /** Fallback when a port of this type omits its own default. */
+    defaultValue?: unknown;
+    /** Viewer widget descriptor for ports of this type. */
+    widget?: TypeWidgetSpec;
+    /** Override default parse behaviour for this type's widget. */
+    parse?: (raw: string) => unknown;
+    /** Override default format behaviour for this type's widget. */
+    format?: (value: unknown) => string;
+    /** Override default coerce behaviour for this type's widget. */
+    coerce?: (value: unknown) => unknown;
+}
+
+/**
+ * Serializable widget descriptor for port value editing and display. Lives on the
+ * type definition; the Vue viewer resolves it to a concrete component.
+ */
+export declare type TypeWidgetSpec = {
+    kind: "number";
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Port row height in px; defaults to one line (20px). */
+    rowHeight?: number;
+} | {
+    kind: "text";
+    /** Multiline row count; height is `rows × 20px` unless `rowHeight` is set. */
+    rows?: number;
+    /** Port row height in px; overrides `rows`. */
+    rowHeight?: number;
+} | {
+    kind: "custom";
+    /** Id passed to `registerComponentWidget` in a pack's `setup` hook. */
+    componentId: string;
+    /** Port row height in px; defaults to one line (20px). */
+    rowHeight?: number;
+};
+
+/**
+ * Validate a document against the current map without applying it.
+ * @returns Human-readable error messages (empty when valid).
+ */
+export declare function validateDocument(map: NodeMap, doc: GraphDocument): string[];
+
+/** Port values keyed by port name. */
+export declare type Values = Record<string, unknown>;
+
+export { }