@vector-nodes/core 0.1.0

package/dist/schema.js

@@ -0,0 +1,163 @@
+/**
+ * The `.vnodes` JSON Schema (draft 2020-12), embedded so the package is
+ * self-contained when published.
+ *
+ * This is a verbatim copy of the canonical `docs/vnodes.schema.json`. The two
+ * are kept in sync by `schema.test.ts`, which fails if they diverge.
+ */
+export const VNODES_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://vector-nodes.dev/schema/vnodes.schema.json',
+    title: 'Vector Nodes network (.vnodes)',
+    description: 'Skeleton schema for the Vector Nodes JSON network definition format. Refined during Phase 1.',
+    type: 'object',
+    required: ['format', 'version', 'nodes', 'links'],
+    additionalProperties: false,
+    properties: {
+        format: {
+            const: 'vector-nodes',
+            description: 'Format discriminator.',
+        },
+        version: {
+            type: 'string',
+            pattern: '^\\d+\\.\\d+$',
+            description: 'Format version, e.g. "1.0".',
+        },
+        metadata: {
+            type: 'object',
+            description: 'Human-facing info. `name` seeds the generated function name.',
+            properties: {
+                name: { type: 'string' },
+                author: { type: 'string' },
+                description: { type: 'string' },
+                created: { type: 'string' },
+            },
+            additionalProperties: true,
+        },
+        parameters: {
+            type: 'array',
+            description: "External, typed inputs exposed as the generated function's arguments.",
+            items: { $ref: '#/$defs/parameter' },
+        },
+        nodes: {
+            type: 'array',
+            description: 'The nodes in the network. Exactly one OutputGeometry node is expected.',
+            items: { $ref: '#/$defs/node' },
+        },
+        links: {
+            type: 'array',
+            description: 'Edges connecting an output socket to an input socket.',
+            items: { $ref: '#/$defs/link' },
+        },
+        metaNodes: {
+            type: 'object',
+            description: 'Reusable meta-node (function) definitions, keyed by name.',
+            additionalProperties: { $ref: '#/$defs/metaNode' },
+        },
+    },
+    $defs: {
+        socketType: {
+            type: 'string',
+            enum: ['Float', 'Integer', 'Boolean', 'Vector', 'Color', 'String', 'Geometry', 'Matrix'],
+            description: 'Socket data type. Drives color-coding and link type-checking.',
+        },
+        parameter: {
+            type: 'object',
+            required: ['id', 'type'],
+            additionalProperties: false,
+            properties: {
+                id: { type: 'string' },
+                type: { $ref: '#/$defs/socketType' },
+                isArray: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'True if this carries a field/array of the type.',
+                },
+                default: {
+                    description: 'Default value; shape depends on `type`.',
+                },
+                min: { type: 'number' },
+                max: { type: 'number' },
+            },
+        },
+        node: {
+            type: 'object',
+            required: ['id', 'type'],
+            additionalProperties: false,
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Stable unique id used by links.',
+                },
+                type: {
+                    type: 'string',
+                    description: 'Node type from the node library (e.g. "PointCircle", "OutputGeometry").',
+                },
+                position: {
+                    type: 'array',
+                    description: 'Editor canvas position [x, y].',
+                    items: { type: 'number' },
+                    minItems: 2,
+                    maxItems: 2,
+                },
+                params: {
+                    type: 'object',
+                    description: 'Static parameter values baked into the node.',
+                    additionalProperties: true,
+                },
+                label: { type: 'string' },
+            },
+        },
+        endpoint: {
+            type: 'array',
+            description: 'A [nodeId, socketName] reference.',
+            items: { type: 'string' },
+            minItems: 2,
+            maxItems: 2,
+        },
+        link: {
+            type: 'object',
+            required: ['from', 'to'],
+            additionalProperties: false,
+            properties: {
+                from: {
+                    $ref: '#/$defs/endpoint',
+                    description: 'Source output socket [nodeId, outputSocketName].',
+                },
+                to: {
+                    $ref: '#/$defs/endpoint',
+                    description: 'Target input socket [nodeId, inputSocketName].',
+                },
+            },
+        },
+        metaNode: {
+            type: 'object',
+            required: ['interface', 'nodes', 'links'],
+            additionalProperties: false,
+            properties: {
+                interface: {
+                    type: 'object',
+                    required: ['inputs', 'outputs'],
+                    additionalProperties: false,
+                    properties: {
+                        inputs: { type: 'array', items: { $ref: '#/$defs/interfaceSocket' } },
+                        outputs: { type: 'array', items: { $ref: '#/$defs/interfaceSocket' } },
+                    },
+                },
+                nodes: { type: 'array', items: { $ref: '#/$defs/node' } },
+                links: { type: 'array', items: { $ref: '#/$defs/link' } },
+            },
+        },
+        interfaceSocket: {
+            type: 'object',
+            required: ['name', 'type'],
+            additionalProperties: false,
+            properties: {
+                name: { type: 'string' },
+                type: { $ref: '#/$defs/socketType' },
+                isArray: { type: 'boolean', default: false },
+            },
+        },
+    },
+};
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/socket-types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The eight socket types of the Vector Nodes type system.
+ *
+ * A single internal `Vector` type represents both points and directions (2D is a
+ * `Vector` with `z = 0`); there is no separate `Point` type. See the README's
+ * "type system" section for the full rationale.
+ */
+export declare const SOCKET_TYPES: readonly ["Float", "Integer", "Boolean", "Vector", "Color", "String", "Geometry", "Matrix"];
+/** Union of every valid socket type. */
+export type SocketType = (typeof SOCKET_TYPES)[number];
+/** Narrow an arbitrary string to a {@link SocketType}. */
+export declare function isSocketType(value: string): value is SocketType;
+/**
+ * A socket's full type: its base {@link SocketType} plus whether it carries a
+ * single value or an array ("field" in Blender terms). Any socket may be a
+ * field, so this flag is orthogonal to the base type.
+ */
+export interface SocketTypeDescriptor {
+    readonly type: SocketType;
+    /** When `true`, the socket carries an array/field of `type` rather than one value. */
+    readonly isArray: boolean;
+}
+/** Convenience constructor for a {@link SocketTypeDescriptor}. */
+export declare function socketTypeDescriptor(type: SocketType, isArray?: boolean): SocketTypeDescriptor;
+//# sourceMappingURL=socket-types.d.ts.map

package/dist/socket-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-types.d.ts","sourceRoot":"","sources":["../src/socket-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,6FASf,CAAC;AAEX,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,UAAQ,GAAG,oBAAoB,CAE5F"}

package/dist/socket-types.js

@@ -0,0 +1,26 @@
+/**
+ * The eight socket types of the Vector Nodes type system.
+ *
+ * A single internal `Vector` type represents both points and directions (2D is a
+ * `Vector` with `z = 0`); there is no separate `Point` type. See the README's
+ * "type system" section for the full rationale.
+ */
+export const SOCKET_TYPES = [
+    'Float',
+    'Integer',
+    'Boolean',
+    'Vector',
+    'Color',
+    'String',
+    'Geometry',
+    'Matrix',
+];
+/** Narrow an arbitrary string to a {@link SocketType}. */
+export function isSocketType(value) {
+    return SOCKET_TYPES.includes(value);
+}
+/** Convenience constructor for a {@link SocketTypeDescriptor}. */
+export function socketTypeDescriptor(type, isArray = false) {
+    return { type, isArray };
+}
+//# sourceMappingURL=socket-types.js.map

package/dist/socket-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-types.js","sourceRoot":"","sources":["../src/socket-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO;IACP,SAAS;IACT,SAAS;IACT,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,UAAU;IACV,QAAQ;CACA,CAAC;AAKX,0DAA0D;AAC1D,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAQ,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAaD,kEAAkE;AAClE,MAAM,UAAU,oBAAoB,CAAC,IAAgB,EAAE,OAAO,GAAG,KAAK;IACpE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC"}

package/dist/validate-graph.d.ts

@@ -0,0 +1,37 @@
+import { type Graph } from './graph';
+import type { NodeRegistry } from './registry';
+/** The kinds of static-validation problems a graph can have. */
+export type GraphValidationCode = 'duplicate-node-id' | 'unknown-node-type' | 'missing-output' | 'multiple-outputs' | 'dangling-link-node' | 'dangling-link-socket' | 'duplicate-input-link' | 'type-mismatch' | 'field-mismatch' | 'cycle';
+/** A single static-validation problem with enough context to locate it. */
+export interface GraphValidationIssue {
+    code: GraphValidationCode;
+    message: string;
+    /** Relevant node id, when the issue concerns a node. */
+    nodeId?: string;
+    /** Index into `graph.links`, when the issue concerns a link. */
+    linkIndex?: number;
+}
+/** The outcome of {@link validateGraph}. */
+export interface GraphValidationResult {
+    valid: boolean;
+    issues: GraphValidationIssue[];
+}
+/** Error thrown by {@link assertValidGraph} carrying the structured issues. */
+export declare class GraphValidationError extends Error {
+    readonly issues: GraphValidationIssue[];
+    constructor(issues: GraphValidationIssue[]);
+}
+/**
+ * Statically validate a {@link Graph} against the node definitions in
+ * `registry`. Checks, in order: duplicate node ids, unknown node types, the
+ * single-output rule, dangling links (to a missing node or socket), duplicate
+ * links into one input, link type/field compatibility (honoring implicit
+ * conversions), and dependency cycles.
+ *
+ * Returns every issue found; an empty `issues` array means the graph is valid.
+ * Validation of embedded meta-node definitions is deferred to Phase 5.
+ */
+export declare function validateGraph(graph: Graph, registry: NodeRegistry): GraphValidationResult;
+/** Assert a graph is valid against `registry`, throwing on any issue. */
+export declare function assertValidGraph(graph: Graph, registry: NodeRegistry): void;
+//# sourceMappingURL=validate-graph.d.ts.map

package/dist/validate-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-graph.d.ts","sourceRoot":"","sources":["../src/validate-graph.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,KAAK,EAEX,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,mBAAmB,GACnB,gBAAgB,GAChB,kBAAkB,GAClB,oBAAoB,GACpB,sBAAsB,GACtB,sBAAsB,GACtB,eAAe,GACf,gBAAgB,GAChB,OAAO,CAAC;AAEZ,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED,+EAA+E;AAC/E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC;gBAE5B,MAAM,EAAE,oBAAoB,EAAE;CAO3C;AAaD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,GAAG,qBAAqB,CAkIzF;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAK3E"}

package/dist/validate-graph.js

@@ -0,0 +1,201 @@
+import { canConvertImplicitly } from './conversions';
+import { endpointNode, endpointSocket, OUTPUT_NODE_TYPE, } from './graph';
+/** Error thrown by {@link assertValidGraph} carrying the structured issues. */
+export class GraphValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid graph:\n${issues.map((issue) => `  - [${issue.code}] ${issue.message}`).join('\n')}`);
+        this.name = 'GraphValidationError';
+        this.issues = issues;
+    }
+}
+function endpointLabel(endpoint) {
+    return `${endpointNode(endpoint)}.${endpointSocket(endpoint)}`;
+}
+function findSocket(sockets, name) {
+    return sockets.find((socket) => socket.name === name);
+}
+/**
+ * Statically validate a {@link Graph} against the node definitions in
+ * `registry`. Checks, in order: duplicate node ids, unknown node types, the
+ * single-output rule, dangling links (to a missing node or socket), duplicate
+ * links into one input, link type/field compatibility (honoring implicit
+ * conversions), and dependency cycles.
+ *
+ * Returns every issue found; an empty `issues` array means the graph is valid.
+ * Validation of embedded meta-node definitions is deferred to Phase 5.
+ */
+export function validateGraph(graph, registry) {
+    const issues = [];
+    // Resolve each node's definition once; track known node ids.
+    const definitions = new Map();
+    const knownNodeIds = new Set();
+    for (const node of graph.nodes) {
+        if (knownNodeIds.has(node.id)) {
+            issues.push({
+                code: 'duplicate-node-id',
+                nodeId: node.id,
+                message: `Duplicate node id "${node.id}".`,
+            });
+            continue;
+        }
+        knownNodeIds.add(node.id);
+        const def = registry.get(node.type);
+        if (def === undefined) {
+            issues.push({
+                code: 'unknown-node-type',
+                nodeId: node.id,
+                message: `Node "${node.id}" has unknown type "${node.type}".`,
+            });
+        }
+        else {
+            definitions.set(node.id, def);
+        }
+    }
+    // Single-output rule.
+    const outputs = graph.nodes.filter((node) => node.type === OUTPUT_NODE_TYPE);
+    if (outputs.length === 0) {
+        issues.push({
+            code: 'missing-output',
+            message: `Graph has no ${OUTPUT_NODE_TYPE} node; exactly one is required.`,
+        });
+    }
+    else if (outputs.length > 1) {
+        issues.push({
+            code: 'multiple-outputs',
+            message: `Graph has ${outputs.length} ${OUTPUT_NODE_TYPE} nodes; exactly one is allowed.`,
+        });
+    }
+    // Per-link checks: dangling references, fan-in, type/field compatibility.
+    const inputSeen = new Set();
+    graph.links.forEach((link, linkIndex) => {
+        /** Report a dangling node reference; returns the node's definition if usable. */
+        const checkEndpointNode = (endpoint, side) => {
+            const id = endpointNode(endpoint);
+            if (!knownNodeIds.has(id)) {
+                issues.push({
+                    code: 'dangling-link-node',
+                    linkIndex,
+                    message: `Link ${side} references unknown node "${id}".`,
+                });
+                return undefined;
+            }
+            return definitions.get(id);
+        };
+        const fromDef = checkEndpointNode(link.from, 'from');
+        const toDef = checkEndpointNode(link.to, 'to');
+        // Detect more than one link into the same input socket.
+        const toKey = endpointLabel(link.to);
+        if (inputSeen.has(toKey)) {
+            issues.push({
+                code: 'duplicate-input-link',
+                linkIndex,
+                message: `Input ${toKey} receives more than one link.`,
+            });
+        }
+        inputSeen.add(toKey);
+        if (fromDef === undefined || toDef === undefined)
+            return;
+        const fromSocket = findSocket(fromDef.outputs, endpointSocket(link.from));
+        const toSocket = findSocket(toDef.inputs, endpointSocket(link.to));
+        if (fromSocket === undefined) {
+            issues.push({
+                code: 'dangling-link-socket',
+                linkIndex,
+                message: `No output socket "${endpointSocket(link.from)}" on node "${endpointNode(link.from)}".`,
+            });
+        }
+        if (toSocket === undefined) {
+            issues.push({
+                code: 'dangling-link-socket',
+                linkIndex,
+                message: `No input socket "${endpointSocket(link.to)}" on node "${endpointNode(link.to)}".`,
+            });
+        }
+        if (fromSocket === undefined || toSocket === undefined)
+            return;
+        if ((fromSocket.isArray ?? false) !== (toSocket.isArray ?? false)) {
+            issues.push({
+                code: 'field-mismatch',
+                linkIndex,
+                message: `Link ${endpointLabel(link.from)} → ${endpointLabel(link.to)} connects a ${fromSocket.isArray ? 'field' : 'single value'} to a ${toSocket.isArray ? 'field' : 'single value'}.`,
+            });
+        }
+        else if (!canConvertImplicitly(fromSocket.type, toSocket.type)) {
+            issues.push({
+                code: 'type-mismatch',
+                linkIndex,
+                message: `Link ${endpointLabel(link.from)} → ${endpointLabel(link.to)} connects ${fromSocket.type} to ${toSocket.type}, with no implicit conversion.`,
+            });
+        }
+    });
+    // Dependency cycle detection over links between known nodes.
+    const cycle = detectCycle(graph.links, knownNodeIds);
+    if (cycle.length > 0) {
+        issues.push({
+            code: 'cycle',
+            message: `Graph contains a cycle: ${cycle.join(' → ')}.`,
+        });
+    }
+    return { valid: issues.length === 0, issues };
+}
+/** Assert a graph is valid against `registry`, throwing on any issue. */
+export function assertValidGraph(graph, registry) {
+    const { issues } = validateGraph(graph, registry);
+    if (issues.length > 0) {
+        throw new GraphValidationError(issues);
+    }
+}
+/**
+ * Find one dependency cycle among `links` (treating each link as a directed
+ * edge `from → to`), restricted to nodes in `knownNodeIds`. Returns the cycle
+ * as a list of node ids (closing back on the first), or an empty array if the
+ * graph is acyclic.
+ */
+function detectCycle(links, knownNodeIds) {
+    const adjacency = new Map();
+    for (const link of links) {
+        const from = endpointNode(link.from);
+        const to = endpointNode(link.to);
+        if (!knownNodeIds.has(from) || !knownNodeIds.has(to))
+            continue;
+        const targets = adjacency.get(from);
+        if (targets)
+            targets.push(to);
+        else
+            adjacency.set(from, [to]);
+    }
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const color = new Map();
+    const stack = [];
+    function visit(node) {
+        color.set(node, GRAY);
+        stack.push(node);
+        for (const next of adjacency.get(node) ?? []) {
+            const state = color.get(next) ?? WHITE;
+            if (state === GRAY) {
+                const start = stack.indexOf(next);
+                return [...stack.slice(start), next];
+            }
+            if (state === WHITE) {
+                const found = visit(next);
+                if (found)
+                    return found;
+            }
+        }
+        stack.pop();
+        color.set(node, BLACK);
+        return null;
+    }
+    for (const node of knownNodeIds) {
+        if ((color.get(node) ?? WHITE) === WHITE) {
+            const found = visit(node);
+            if (found)
+                return found;
+        }
+    }
+    return [];
+}
+//# sourceMappingURL=validate-graph.js.map

package/dist/validate-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-graph.js","sourceRoot":"","sources":["../src/validate-graph.ts"],"names":[],"mappings":"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"}

package/dist/vnodes.d.ts

@@ -0,0 +1,37 @@
+import type { Graph } from './graph';
+/** A single schema-validation problem, derived from an ajv error. */
+export interface VnodesValidationIssue {
+    /** JSON Pointer to the offending value (ajv `instancePath`). */
+    path: string;
+    /** Human-readable description. */
+    message: string;
+    /** The schema keyword that failed (e.g. `"required"`, `"enum"`). */
+    keyword: string;
+}
+/** Error thrown when a value fails `.vnodes` schema validation. */
+export declare class VnodesValidationError extends Error {
+    readonly issues: VnodesValidationIssue[];
+    constructor(issues: VnodesValidationIssue[]);
+}
+/**
+ * Validate an arbitrary value against the `.vnodes` schema. Returns the list of
+ * issues; an empty array means the value is valid.
+ */
+export declare function validateVnodes(value: unknown): VnodesValidationIssue[];
+/** Type guard: whether a value is a schema-valid {@link Graph}. */
+export declare function isValidVnodes(value: unknown): value is Graph;
+/** Assert a value is a schema-valid {@link Graph}, throwing otherwise. */
+export declare function assertValidVnodes(value: unknown): asserts value is Graph;
+/**
+ * Parse `.vnodes` JSON text into a validated {@link Graph}.
+ *
+ * @throws SyntaxError if the text is not valid JSON.
+ * @throws VnodesValidationError if the document does not match the schema.
+ */
+export declare function parseVnodes(text: string): Graph;
+/**
+ * Serialize a {@link Graph} to `.vnodes` JSON text. Indents with `space` spaces
+ * (default 2) and appends a trailing newline.
+ */
+export declare function serializeVnodes(graph: Graph, space?: number): string;
+//# sourceMappingURL=vnodes.d.ts.map

package/dist/vnodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vnodes.d.ts","sourceRoot":"","sources":["../src/vnodes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGrC,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,qBAAqB,EAAE,CAAC;gBAE7B,MAAM,EAAE,qBAAqB,EAAE;CAS5C;AAaD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,EAAE,CAEtE;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAE5D;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAKxE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAI/C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,SAAI,GAAG,MAAM,CAE/D"}

package/dist/vnodes.js

@@ -0,0 +1,59 @@
+import Ajv2020, {} from 'ajv/dist/2020';
+import { VNODES_SCHEMA } from './schema';
+/** Error thrown when a value fails `.vnodes` schema validation. */
+export class VnodesValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid .vnodes document:\n${issues
+            .map((issue) => `  - ${issue.path || '/'} ${issue.message}`)
+            .join('\n')}`);
+        this.name = 'VnodesValidationError';
+        this.issues = issues;
+    }
+}
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const validateFn = ajv.compile(VNODES_SCHEMA);
+function toIssues(errors) {
+    return (errors ?? []).map((error) => ({
+        path: error.instancePath,
+        message: error.message ?? 'is invalid',
+        keyword: error.keyword,
+    }));
+}
+/**
+ * Validate an arbitrary value against the `.vnodes` schema. Returns the list of
+ * issues; an empty array means the value is valid.
+ */
+export function validateVnodes(value) {
+    return validateFn(value) ? [] : toIssues(validateFn.errors);
+}
+/** Type guard: whether a value is a schema-valid {@link Graph}. */
+export function isValidVnodes(value) {
+    return validateFn(value);
+}
+/** Assert a value is a schema-valid {@link Graph}, throwing otherwise. */
+export function assertValidVnodes(value) {
+    const issues = validateVnodes(value);
+    if (issues.length > 0) {
+        throw new VnodesValidationError(issues);
+    }
+}
+/**
+ * Parse `.vnodes` JSON text into a validated {@link Graph}.
+ *
+ * @throws SyntaxError if the text is not valid JSON.
+ * @throws VnodesValidationError if the document does not match the schema.
+ */
+export function parseVnodes(text) {
+    const value = JSON.parse(text);
+    assertValidVnodes(value);
+    return value;
+}
+/**
+ * Serialize a {@link Graph} to `.vnodes` JSON text. Indents with `space` spaces
+ * (default 2) and appends a trailing newline.
+ */
+export function serializeVnodes(graph, space = 2) {
+    return `${JSON.stringify(graph, null, space)}\n`;
+}
+//# sourceMappingURL=vnodes.js.map

package/dist/vnodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vnodes.js","sourceRoot":"","sources":["../src/vnodes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAA2C,MAAM,eAAe,CAAC;AAGjF,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAYzC,mEAAmE;AACnE,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,MAAM,CAA0B;IAEzC,YAAY,MAA+B;QACzC,KAAK,CACH,8BAA8B,MAAM;aACjC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,IAAI,IAAI,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;aAC3D,IAAI,CAAC,IAAI,CAAC,EAAE,CAChB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;AAC5D,MAAM,UAAU,GAAqB,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;AAEhE,SAAS,QAAQ,CAAC,MAAwC;IACxD,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACpC,IAAI,EAAE,KAAK,CAAC,YAAY;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,YAAY;QACtC,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC9D,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,UAAU,CAAC,KAAK,CAAY,CAAC;AACtC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACzB,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAY,EAAE,KAAK,GAAG,CAAC;IACrD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;AACnD,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vector-nodes/core",
+  "version": "0.1.0",
+  "description": "Types, graph model, and .vnodes schema for Vector Nodes.",
+  "license": "Apache-2.0",
+  "author": "Sergey Chernyshev <sergey.chernyshev@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sergeychernyshev/vector-nodes.git",
+    "directory": "packages/core"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "prepack": "tsc -b"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
+  }
+}