@decaf-ts/integrations 0.3.1 → 0.3.2

package/lib/types/graph/types.d.cts

@@ -0,0 +1,197 @@
+/**
+ * @module integrations/graph/types
+ * @summary Graph execution engine core types.
+ * @description Type aliases and interfaces shared across the graph execution engine.
+ */
+import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEventType, GraphExecutionStatus } from "./constants.d.cts";
+/**
+ * Unique identifier for a single graph execution run.
+ */
+export type GraphRunId = string;
+/**
+ * Identifier for a workflow definition.
+ */
+export type GraphWorkflowId = string;
+/**
+ * Identifier for a node within a workflow.
+ */
+export type GraphNodeId = string;
+/**
+ * Name of a port on a node or workflow boundary.
+ */
+export type GraphPortName = string;
+/**
+ * A bag of named values exchanged between nodes and the workflow boundary.
+ */
+export type GraphExecutionValues = Record<string, unknown>;
+/**
+ * Options that influence a single execution of a workflow.
+ */
+export interface GraphExecutionOptions {
+    runId?: GraphRunId;
+    parentRunId?: GraphRunId;
+    workflowId?: GraphWorkflowId;
+    path?: string[];
+    concurrency?: number;
+    failFast?: boolean;
+    validateInputs?: boolean;
+    validateOutputs?: boolean;
+    maxLoopIterations?: number;
+    maxForeachIterations?: number;
+    usePinnedValues?: boolean;
+    writeThroughCache?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Serialized error payload included in execution events and results.
+ */
+export interface GraphExecutionErrorPayload {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * A single event emitted during graph execution.
+ */
+export interface GraphExecutionEvent {
+    id: string;
+    sequence: number;
+    runId: GraphRunId;
+    parentRunId?: GraphRunId;
+    workflowId: GraphWorkflowId;
+    type: GraphExecutionEventType;
+    timestamp: Date;
+    nodeId?: GraphNodeId;
+    edgeId?: string;
+    port?: GraphPortName;
+    iteration?: number;
+    path: string[];
+    status?: GraphExecutionStatus;
+    payload?: unknown;
+    error?: GraphExecutionErrorPayload;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of executing a single node.
+ */
+export interface GraphNodeExecutionResult {
+    nodeId: GraphNodeId;
+    status: GraphExecutionStatus;
+    inputs: GraphExecutionValues;
+    outputs?: GraphExecutionValues;
+    error?: GraphExecutionErrorPayload;
+    startedAt: Date;
+    finishedAt?: Date;
+    fromCache?: boolean;
+    pinned?: boolean;
+    events: GraphExecutionEvent[];
+}
+/**
+ * Result of executing an entire workflow.
+ */
+export interface GraphExecutionResult {
+    runId: GraphRunId;
+    parentRunId?: GraphRunId;
+    workflowId: GraphWorkflowId;
+    status: GraphExecutionStatus;
+    workflow: GraphWorkflowDefinition;
+    inputs: GraphExecutionValues;
+    outputs: GraphExecutionValues;
+    nodeResults: Record<GraphNodeId, GraphNodeExecutionResult>;
+    events: GraphExecutionEvent[];
+    startedAt: Date;
+    finishedAt?: Date;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options used to construct a {@link GraphExecutionContext}.
+ */
+export interface GraphExecutionContextOptions {
+    runId: GraphRunId;
+    parentRunId?: GraphRunId;
+    workflow: GraphWorkflowDefinition;
+    node: GraphNodeDefinition;
+    path: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Metadata describing a loop node's behaviour.
+ */
+export interface GraphLoopMetadata {
+    body: GraphWorkflowDefinition | unknown;
+    maxIterations?: number;
+    timeoutMs?: number;
+    condition?: GraphConditionDefinition;
+    concurrency?: number;
+    inputPort?: string;
+    outputPort?: string;
+    itemPort?: string;
+    resultPort?: string;
+    statePort?: string;
+}
+/**
+ * Definition of a condition evaluated by the loop condition evaluator.
+ */
+export interface GraphConditionDefinition {
+    type: "truthy" | "falsy" | "equals" | "notEquals" | "greaterThan" | "greaterThanOrEqual" | "lessThan" | "lessThanOrEqual" | "exists" | "custom";
+    left?: string;
+    right?: unknown;
+    evaluator?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Pinning metadata attached to a node via `@pinnable()`.
+ */
+export interface GraphPinningMetadata {
+    enabled: boolean;
+    ttlMs?: number;
+    strategy: "manual" | "automatic" | "disabled";
+    includeDependencies: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for pinning a node after a completed run.
+ */
+export interface GraphPinNodeOptions {
+    workflow: GraphWorkflowDefinition;
+    plan: unknown;
+    result: GraphExecutionResult;
+    nodeId: string;
+    includeDependencies?: boolean;
+    namespace?: string;
+}
+/**
+ * Options for unpinning a node.
+ */
+export interface GraphUnpinNodeOptions {
+    workflow: GraphWorkflowDefinition;
+    nodeId: string;
+    fingerprint: string;
+    namespace?: string;
+}
+/**
+ * A patch applied to a graph workflow snapshot after execution.
+ */
+export interface GraphExecutionSnapshotPatch {
+    runId: string;
+    status: GraphExecutionStatus;
+    nodes: Record<string, {
+        status: GraphExecutionStatus;
+        startedAt?: string;
+        finishedAt?: string;
+        error?: GraphExecutionErrorPayload;
+        outputs?: Record<string, unknown>;
+        fromCache?: boolean;
+        pinned?: boolean;
+    }>;
+    edges: Record<string, {
+        status: GraphExecutionStatus;
+        lastValue?: unknown;
+        updatedAt: string;
+    }>;
+    outputs: Record<string, unknown>;
+    events: GraphExecutionEvent[];
+}

package/lib/types/graph/types.d.mts

@@ -0,0 +1,197 @@
+/**
+ * @module integrations/graph/types
+ * @summary Graph execution engine core types.
+ * @description Type aliases and interfaces shared across the graph execution engine.
+ */
+import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEventType, GraphExecutionStatus } from "./constants.d.mts";
+/**
+ * Unique identifier for a single graph execution run.
+ */
+export type GraphRunId = string;
+/**
+ * Identifier for a workflow definition.
+ */
+export type GraphWorkflowId = string;
+/**
+ * Identifier for a node within a workflow.
+ */
+export type GraphNodeId = string;
+/**
+ * Name of a port on a node or workflow boundary.
+ */
+export type GraphPortName = string;
+/**
+ * A bag of named values exchanged between nodes and the workflow boundary.
+ */
+export type GraphExecutionValues = Record<string, unknown>;
+/**
+ * Options that influence a single execution of a workflow.
+ */
+export interface GraphExecutionOptions {
+    runId?: GraphRunId;
+    parentRunId?: GraphRunId;
+    workflowId?: GraphWorkflowId;
+    path?: string[];
+    concurrency?: number;
+    failFast?: boolean;
+    validateInputs?: boolean;
+    validateOutputs?: boolean;
+    maxLoopIterations?: number;
+    maxForeachIterations?: number;
+    usePinnedValues?: boolean;
+    writeThroughCache?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Serialized error payload included in execution events and results.
+ */
+export interface GraphExecutionErrorPayload {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * A single event emitted during graph execution.
+ */
+export interface GraphExecutionEvent {
+    id: string;
+    sequence: number;
+    runId: GraphRunId;
+    parentRunId?: GraphRunId;
+    workflowId: GraphWorkflowId;
+    type: GraphExecutionEventType;
+    timestamp: Date;
+    nodeId?: GraphNodeId;
+    edgeId?: string;
+    port?: GraphPortName;
+    iteration?: number;
+    path: string[];
+    status?: GraphExecutionStatus;
+    payload?: unknown;
+    error?: GraphExecutionErrorPayload;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of executing a single node.
+ */
+export interface GraphNodeExecutionResult {
+    nodeId: GraphNodeId;
+    status: GraphExecutionStatus;
+    inputs: GraphExecutionValues;
+    outputs?: GraphExecutionValues;
+    error?: GraphExecutionErrorPayload;
+    startedAt: Date;
+    finishedAt?: Date;
+    fromCache?: boolean;
+    pinned?: boolean;
+    events: GraphExecutionEvent[];
+}
+/**
+ * Result of executing an entire workflow.
+ */
+export interface GraphExecutionResult {
+    runId: GraphRunId;
+    parentRunId?: GraphRunId;
+    workflowId: GraphWorkflowId;
+    status: GraphExecutionStatus;
+    workflow: GraphWorkflowDefinition;
+    inputs: GraphExecutionValues;
+    outputs: GraphExecutionValues;
+    nodeResults: Record<GraphNodeId, GraphNodeExecutionResult>;
+    events: GraphExecutionEvent[];
+    startedAt: Date;
+    finishedAt?: Date;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options used to construct a {@link GraphExecutionContext}.
+ */
+export interface GraphExecutionContextOptions {
+    runId: GraphRunId;
+    parentRunId?: GraphRunId;
+    workflow: GraphWorkflowDefinition;
+    node: GraphNodeDefinition;
+    path: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Metadata describing a loop node's behaviour.
+ */
+export interface GraphLoopMetadata {
+    body: GraphWorkflowDefinition | unknown;
+    maxIterations?: number;
+    timeoutMs?: number;
+    condition?: GraphConditionDefinition;
+    concurrency?: number;
+    inputPort?: string;
+    outputPort?: string;
+    itemPort?: string;
+    resultPort?: string;
+    statePort?: string;
+}
+/**
+ * Definition of a condition evaluated by the loop condition evaluator.
+ */
+export interface GraphConditionDefinition {
+    type: "truthy" | "falsy" | "equals" | "notEquals" | "greaterThan" | "greaterThanOrEqual" | "lessThan" | "lessThanOrEqual" | "exists" | "custom";
+    left?: string;
+    right?: unknown;
+    evaluator?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Pinning metadata attached to a node via `@pinnable()`.
+ */
+export interface GraphPinningMetadata {
+    enabled: boolean;
+    ttlMs?: number;
+    strategy: "manual" | "automatic" | "disabled";
+    includeDependencies: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for pinning a node after a completed run.
+ */
+export interface GraphPinNodeOptions {
+    workflow: GraphWorkflowDefinition;
+    plan: unknown;
+    result: GraphExecutionResult;
+    nodeId: string;
+    includeDependencies?: boolean;
+    namespace?: string;
+}
+/**
+ * Options for unpinning a node.
+ */
+export interface GraphUnpinNodeOptions {
+    workflow: GraphWorkflowDefinition;
+    nodeId: string;
+    fingerprint: string;
+    namespace?: string;
+}
+/**
+ * A patch applied to a graph workflow snapshot after execution.
+ */
+export interface GraphExecutionSnapshotPatch {
+    runId: string;
+    status: GraphExecutionStatus;
+    nodes: Record<string, {
+        status: GraphExecutionStatus;
+        startedAt?: string;
+        finishedAt?: string;
+        error?: GraphExecutionErrorPayload;
+        outputs?: Record<string, unknown>;
+        fromCache?: boolean;
+        pinned?: boolean;
+    }>;
+    edges: Record<string, {
+        status: GraphExecutionStatus;
+        lastValue?: unknown;
+        updatedAt: string;
+    }>;
+    outputs: Record<string, unknown>;
+    events: GraphExecutionEvent[];
+}

package/lib/types/graph/validation/GraphDefinitionValidator.d.cts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/validation/GraphDefinitionValidator
+ * @summary Validates graph workflow definitions before execution.
+ * @description Checks workflow structure, node IDs, relation endpoints/ports, required port sources, cycles, and loop metadata.
+ */
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import { GraphExecutionPlanner } from "../planning/GraphExecutionPlanner.d.cts";
+/**
+ * Validates a {@link GraphWorkflowDefinition} before execution.
+ */
+export declare class GraphDefinitionValidator {
+    private readonly planner;
+    constructor(planner?: GraphExecutionPlanner);
+    /**
+     * Validates the workflow definition.
+     *
+     * @throws {GraphInputError} when the workflow has no name or invalid structure.
+     * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
+     */
+    validate(workflow: GraphWorkflowDefinition): void;
+}

package/lib/types/graph/validation/GraphDefinitionValidator.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/validation/GraphDefinitionValidator
+ * @summary Validates graph workflow definitions before execution.
+ * @description Checks workflow structure, node IDs, relation endpoints/ports, required port sources, cycles, and loop metadata.
+ */
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import { GraphExecutionPlanner } from "../planning/GraphExecutionPlanner.d.mts";
+/**
+ * Validates a {@link GraphWorkflowDefinition} before execution.
+ */
+export declare class GraphDefinitionValidator {
+    private readonly planner;
+    constructor(planner?: GraphExecutionPlanner);
+    /**
+     * Validates the workflow definition.
+     *
+     * @throws {GraphInputError} when the workflow has no name or invalid structure.
+     * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
+     */
+    validate(workflow: GraphWorkflowDefinition): void;
+}

package/lib/types/graph/validation/GraphPortSchemaResolver.d.cts

@@ -0,0 +1,39 @@
+/**
+ * @module integrations/graph/validation/GraphPortSchemaResolver
+ * @summary Resolves graph port definitions to Zod schemas.
+ * @description Prefers `@decaf-ts/as-zod` for model-backed ports and falls back to primitive type mapping.
+ */
+import type { GraphPortDefinition } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Resolves a {@link GraphPortDefinition} to a Zod schema (or a lightweight
+ * validation function when Zod is not available).
+ *
+ * This implementation uses primitive type mapping. When the port's `model`
+ * field or underlying Decaf metadata references a `Model` class, consumers
+ * should use `modelToZod` from `@decaf-ts/as-zod` to build the schema.
+ */
+export declare class GraphPortSchemaResolver {
+    /**
+     * Resolves a single port to a schema descriptor.
+     *
+     * @returns A descriptor with the port name, a `validate` function, and
+     * optional Zod schema reference.
+     */
+    resolve(port: GraphPortDefinition): {
+        name: string;
+        required: boolean;
+        validate: (value: unknown) => boolean;
+    };
+    /**
+     * Resolves multiple ports into a map of name -> descriptor.
+     */
+    resolveAll(ports: GraphPortDefinition[]): Record<string, {
+        name: string;
+        required: boolean;
+        validate: (value: unknown) => boolean;
+    }>;
+    /**
+     * Creates a validation function based on the port's type.
+     */
+    private createValidator;
+}

package/lib/types/graph/validation/GraphPortSchemaResolver.d.mts

@@ -0,0 +1,39 @@
+/**
+ * @module integrations/graph/validation/GraphPortSchemaResolver
+ * @summary Resolves graph port definitions to Zod schemas.
+ * @description Prefers `@decaf-ts/as-zod` for model-backed ports and falls back to primitive type mapping.
+ */
+import type { GraphPortDefinition } from "@decaf-ts/ui-decorators/graph";
+/**
+ * Resolves a {@link GraphPortDefinition} to a Zod schema (or a lightweight
+ * validation function when Zod is not available).
+ *
+ * This implementation uses primitive type mapping. When the port's `model`
+ * field or underlying Decaf metadata references a `Model` class, consumers
+ * should use `modelToZod` from `@decaf-ts/as-zod` to build the schema.
+ */
+export declare class GraphPortSchemaResolver {
+    /**
+     * Resolves a single port to a schema descriptor.
+     *
+     * @returns A descriptor with the port name, a `validate` function, and
+     * optional Zod schema reference.
+     */
+    resolve(port: GraphPortDefinition): {
+        name: string;
+        required: boolean;
+        validate: (value: unknown) => boolean;
+    };
+    /**
+     * Resolves multiple ports into a map of name -> descriptor.
+     */
+    resolveAll(ports: GraphPortDefinition[]): Record<string, {
+        name: string;
+        required: boolean;
+        validate: (value: unknown) => boolean;
+    }>;
+    /**
+     * Creates a validation function based on the port's type.
+     */
+    private createValidator;
+}

package/lib/types/graph/validation/GraphValueValidator.d.cts

@@ -0,0 +1,27 @@
+/**
+ * @module integrations/graph/validation/GraphValueValidator
+ * @summary Validates runtime values against graph port definitions.
+ * @description Validates workflow inputs/outputs and node inputs/outputs using the schema resolver.
+ */
+import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphPortSchemaResolver } from "./GraphPortSchemaResolver.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Validates runtime values against port definitions.
+ */
+export declare class GraphValueValidator {
+    private readonly resolver;
+    constructor(resolver: GraphPortSchemaResolver);
+    /** Validates workflow-level input values. */
+    validateWorkflowInputs(workflow: GraphWorkflowDefinition, values: GraphExecutionValues): void;
+    /** Validates workflow-level output values. */
+    validateWorkflowOutputs(workflow: GraphWorkflowDefinition, values: GraphExecutionValues): void;
+    /** Validates a node's input values. */
+    validateNodeInputs(node: GraphNodeDefinition, values: GraphExecutionValues): void;
+    /** Validates a node's output values. */
+    validateNodeOutputs(node: GraphNodeDefinition, values: GraphExecutionValues): void;
+    /**
+     * Validates values against a set of port definitions.
+     */
+    private validatePorts;
+}

package/lib/types/graph/validation/GraphValueValidator.d.mts

@@ -0,0 +1,27 @@
+/**
+ * @module integrations/graph/validation/GraphValueValidator
+ * @summary Validates runtime values against graph port definitions.
+ * @description Validates workflow inputs/outputs and node inputs/outputs using the schema resolver.
+ */
+import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphPortSchemaResolver } from "./GraphPortSchemaResolver.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Validates runtime values against port definitions.
+ */
+export declare class GraphValueValidator {
+    private readonly resolver;
+    constructor(resolver: GraphPortSchemaResolver);
+    /** Validates workflow-level input values. */
+    validateWorkflowInputs(workflow: GraphWorkflowDefinition, values: GraphExecutionValues): void;
+    /** Validates workflow-level output values. */
+    validateWorkflowOutputs(workflow: GraphWorkflowDefinition, values: GraphExecutionValues): void;
+    /** Validates a node's input values. */
+    validateNodeInputs(node: GraphNodeDefinition, values: GraphExecutionValues): void;
+    /** Validates a node's output values. */
+    validateNodeOutputs(node: GraphNodeDefinition, values: GraphExecutionValues): void;
+    /**
+     * Validates values against a set of port definitions.
+     */
+    private validatePorts;
+}

package/lib/types/graph/validation/index.d.cts

@@ -0,0 +1,8 @@
+/**
+ * @module integrations/graph/validation
+ * @summary Graph validation utilities.
+ * @description Re-exports the definition validator, port schema resolver, and value validator.
+ */
+export * from "./GraphDefinitionValidator.d.cts";
+export * from "./GraphPortSchemaResolver.d.cts";
+export * from "./GraphValueValidator.d.cts";

package/lib/types/graph/validation/index.d.mts

@@ -0,0 +1,8 @@
+/**
+ * @module integrations/graph/validation
+ * @summary Graph validation utilities.
+ * @description Re-exports the definition validator, port schema resolver, and value validator.
+ */
+export * from "./GraphDefinitionValidator.d.mts";
+export * from "./GraphPortSchemaResolver.d.mts";
+export * from "./GraphValueValidator.d.mts";

package/lib/types/index.d.cts

@@ -5,6 +5,6 @@
  */
 export * from "./utils.d.cts";
 export declare const VERSION: string;
-export declare const COMMIT = "bf16ce1";
-export declare const FULL_VERSION = "0.3.0-bf16ce1";
+export declare const COMMIT = "538f19e";
+export declare const FULL_VERSION = "0.3.1-538f19e";
 export declare const PACKAGE_NAME: string;

package/lib/types/index.d.mts

@@ -5,6 +5,6 @@
  */
 export * from "./utils.d.mts";
 export declare const VERSION: string;
-export declare const COMMIT = "bf16ce1";
-export declare const FULL_VERSION = "0.3.0-bf16ce1";
+export declare const COMMIT = "538f19e";
+export declare const FULL_VERSION = "0.3.1-538f19e";
 export declare const PACKAGE_NAME: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/integrations",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.mts",
@@ -202,6 +202,17 @@
         "default": "./lib/cjs/blob/memory/index.cjs"
       },
       "default": "./lib/esm/blob/memory/index.js"
+    },
+    "./graph": {
+      "import": {
+        "types": "./lib/types/graph/index.d.mts",
+        "default": "./lib/esm/graph/index.js"
+      },
+      "require": {
+        "types": "./lib/types/graph/index.d.cts",
+        "default": "./lib/cjs/graph/index.cjs"
+      },
+      "default": "./lib/esm/graph/index.js"
     }
   },
   "scripts": {
@@ -248,6 +259,7 @@
     "@decaf-ts/injectable-decorators": "latest",
     "@decaf-ts/logging": "latest",
     "@decaf-ts/transactional-decorators": "latest",
+    "@decaf-ts/ui-decorators": "latest",
     "axios": "^1.7.9",
     "node-fetch": "^3.3.2",
     "tslib": "^2.8.1",
@@ -257,7 +269,8 @@
     "@decaf-ts/cli": "latest",
     "@decaf-ts/for-http": "latest",
     "@decaf-ts/for-nano": "latest",
-    "@decaf-ts/for-nest": "0.11.2-refactor.5",
+    "@decaf-ts/as-zod": "latest",
+    "@decaf-ts/for-nest": "0.11.2-refactor.7",
     "@decaf-ts/utils": "latest",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
@@ -272,7 +285,8 @@
   },
   "peerDependencies": {
     "@decaf-ts/for-http": "latest",
-    "@decaf-ts/for-nest": "0.11.2-refactor.5",
+    "@decaf-ts/as-zod": "latest",
+    "@decaf-ts/for-nest": "0.11.2-refactor.7",
     "jose": ">=5.0.0"
   },
   "peerDependenciesMeta": {