@nodetool-ai/node-sdk 0.7.0-rc.11

package/dist/validation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Node-level validation.
+ *
+ * Validates that a node descriptor has all of its required properties set
+ * before a workflow is executed. Properties supplied via incoming edges are
+ * skipped (the value will be produced at runtime by an upstream node).
+ *
+ * Three checks are run for each declared property:
+ *
+ *   1. `required: true` — the value must be present and non-empty.
+ *   2. Model fields (`type` ending in `_model`) — if the value carries a
+ *      `provider`, it must not be the sentinel `"empty"` and `id` must be
+ *      a non-empty string. This catches the very common "user forgot to
+ *      pick a model" case for LLM/agent nodes.
+ *   3. Required asset fields (`audio`, `image`, `video`, `document`,
+ *      `dataframe`, `model_3d`, `folder`, `font`, `text`, `asset`) — when
+ *      `required: true`, the value must carry a `uri`, `asset_id`,
+ *      `temp_id`, or inline `data`. The default placeholder
+ *      (`{ type: "audio", uri: "", asset_id: null, data: null }`) otherwise
+ *      looks "non-empty" to the generic emptiness check, so without this
+ *      branch a `required: true` audio/image input would slip through.
+ *
+ * The validator works against the @prop metadata on a node class, so any
+ * node that uses `@prop({ required: true, ... })`, a model-typed field, or
+ * an asset-typed field gets validation for free with no per-node code.
+ */
+import type { DeclaredPropertyMetadata } from "./decorators.js";
+/** A single validation issue tied to a node property. */
+export interface NodePropertyValidationIssue {
+    /** Node id, when known. */
+    nodeId?: string;
+    /** Node type, when known. */
+    nodeType?: string;
+    /** Property name that failed validation. */
+    property: string;
+    /** Human-readable message describing the failure. */
+    message: string;
+}
+export interface ValidateNodePropertiesOptions {
+    /**
+     * Set of property names that are connected to incoming data edges. These
+     * properties are produced at runtime, so their default value (often empty)
+     * should not be flagged as missing.
+     */
+    connectedHandles?: ReadonlySet<string> | ReadonlyArray<string>;
+    /** Node id to attach to issues. */
+    nodeId?: string;
+    /** Node type to attach to issues. */
+    nodeType?: string;
+}
+/**
+ * Validate property values against declared @prop metadata.
+ *
+ * Properties whose name appears in `connectedHandles` are skipped because
+ * they will receive a value from an upstream node at runtime.
+ */
+export declare function validateNodeProperties(declared: ReadonlyArray<DeclaredPropertyMetadata>, properties: Record<string, unknown>, options?: ValidateNodePropertiesOptions): NodePropertyValidationIssue[];
+/**
+ * Format a list of validation issues into a single human-readable message.
+ * Used by GraphValidationError when validation fails.
+ */
+export declare function formatValidationIssues(issues: ReadonlyArray<NodePropertyValidationIssue>): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAEhE,yDAAyD;AACzD,MAAM,WAAW,2BAA2B;IAC1C,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/D,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA4ED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,aAAa,CAAC,wBAAwB,CAAC,EACjD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,GAAE,6BAAkC,GAC1C,2BAA2B,EAAE,CAsC/B;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,CAAC,2BAA2B,CAAC,GACjD,MAAM,CAWR"}

package/dist/validation.js

@@ -0,0 +1,138 @@
+const MODEL_TYPE_SUFFIX = "_model";
+const EMPTY_PROVIDER = "empty";
+const ASSET_TYPES = new Set([
+    "asset",
+    "audio",
+    "image",
+    "video",
+    "text",
+    "document",
+    "dataframe",
+    "model_3d",
+    "folder",
+    "font"
+]);
+function isModelType(typeStr) {
+    if (!typeStr)
+        return false;
+    return typeStr.endsWith(MODEL_TYPE_SUFFIX);
+}
+function isAssetType(typeStr) {
+    if (!typeStr)
+        return false;
+    return ASSET_TYPES.has(typeStr);
+}
+function isUnsetAsset(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value !== "object")
+        return false;
+    const v = value;
+    const uri = v.uri;
+    const assetId = v.asset_id;
+    const tempId = v.temp_id;
+    const data = v.data;
+    const hasUri = typeof uri === "string" && uri.length > 0;
+    const hasAssetId = typeof assetId === "string" && assetId.length > 0;
+    const hasTempId = typeof tempId === "string" && tempId.length > 0;
+    const hasData = data != null &&
+        !(typeof data === "string" && data.length === 0) &&
+        !(Array.isArray(data) && data.length === 0);
+    return !hasUri && !hasAssetId && !hasTempId && !hasData;
+}
+function isEmptyValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === "string")
+        return value.length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+function isUnsetModel(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value !== "object")
+        return false;
+    const v = value;
+    const provider = v.provider;
+    const id = v.id;
+    // A bare placeholder like `{ type: "language_model" }` (no provider, no id)
+    // is exactly the unselected default we want to flag.
+    if (provider == null)
+        return true;
+    if (typeof provider === "string" && provider === EMPTY_PROVIDER)
+        return true;
+    if (id == null)
+        return true;
+    if (typeof id === "string" && id.length === 0)
+        return true;
+    return false;
+}
+function toSet(handles) {
+    if (!handles)
+        return new Set();
+    if (handles instanceof Set)
+        return handles;
+    return new Set(handles);
+}
+/**
+ * Validate property values against declared @prop metadata.
+ *
+ * Properties whose name appears in `connectedHandles` are skipped because
+ * they will receive a value from an upstream node at runtime.
+ */
+export function validateNodeProperties(declared, properties, options = {}) {
+    const connected = toSet(options.connectedHandles);
+    const issues = [];
+    for (const { name, options: meta } of declared) {
+        if (connected.has(name))
+            continue;
+        const value = properties[name];
+        const typeStr = meta.type;
+        if (meta.required) {
+            // Asset-typed fields hold object placeholders that pass the generic
+            // emptiness check, so route them through the asset-specific check.
+            const isAsset = isAssetType(typeStr);
+            const empty = isAsset ? isUnsetAsset(value) : isEmptyValue(value);
+            if (empty) {
+                issues.push({
+                    nodeId: options.nodeId,
+                    nodeType: options.nodeType,
+                    property: name,
+                    message: isAsset
+                        ? `Property "${name}" requires a ${typeStr} (asset, uri, or inline data)`
+                        : `Required property "${name}" is not set`
+                });
+                continue;
+            }
+        }
+        if (isModelType(typeStr) && isUnsetModel(value)) {
+            issues.push({
+                nodeId: options.nodeId,
+                nodeType: options.nodeType,
+                property: name,
+                message: `Property "${name}" requires a ${typeStr} to be selected (provider and model id)`
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Format a list of validation issues into a single human-readable message.
+ * Used by GraphValidationError when validation fails.
+ */
+export function formatValidationIssues(issues) {
+    if (issues.length === 0)
+        return "";
+    const lines = issues.map((issue) => {
+        const where = issue.nodeId
+            ? ` on node "${issue.nodeId}"${issue.nodeType ? ` (${issue.nodeType})` : ""}`
+            : issue.nodeType
+                ? ` on ${issue.nodeType}`
+                : "";
+        return `  - ${issue.message}${where}`;
+    });
+    return `Graph validation failed with ${issues.length} issue(s):\n${lines.join("\n")}`;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nodetool-ai/node-sdk",
+  "type": "module",
+  "version": "0.7.0-rc.11",
+  "description": "Node SDK: BaseNode, NodeRegistry, and example nodes",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "node ../../scripts/build-typescript-workspace.mjs",
+    "test": "vitest run",
+    "test:metadata": "vitest run tests/metadata.test.ts",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@nodetool-ai/kernel": "^0.7.0-rc.11",
+    "@nodetool-ai/protocol": "^0.7.0-rc.11",
+    "@nodetool-ai/runtime": "^0.7.0-rc.11"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/node-sdk"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}