@decaf-ts/integrations 0.3.0 → 0.3.2

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

@@ -0,0 +1,20 @@
+/**
+ * @module integrations/graph/store/GraphCachedValue
+ * @summary A cached graph value with pinning metadata.
+ * @description Represents a node's output that has been cached (and optionally pinned) in the value store.
+ */
+import type { GraphExecutionValues } from "../types.d.mts";
+import type { GraphValueKey } from "./GraphValueKey.d.mts";
+/**
+ * A value stored in the cache, including the outputs, pinning state, and
+ * timestamps for TTL-based expiry.
+ */
+export interface GraphCachedValue {
+    key: GraphValueKey;
+    outputs: GraphExecutionValues;
+    pinned: boolean;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @module integrations/graph/store/GraphValueKey
+ * @summary Stable key for cached graph values.
+ * @description Identifies a cached value in the store by workflow, node, fingerprint, and optional namespace/version.
+ */
+/**
+ * Key used to read/write cached values in a {@link GraphValueStoreAdapter}.
+ *
+ * The `fingerprint` must change when meaningful inputs or dependencies change
+ * so stale values are never accidentally reused.
+ */
+export interface GraphValueKey {
+    workflowId: string;
+    nodeId: string;
+    fingerprint: string;
+    namespace?: string;
+    version?: string;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @module integrations/graph/store/GraphValueKey
+ * @summary Stable key for cached graph values.
+ * @description Identifies a cached value in the store by workflow, node, fingerprint, and optional namespace/version.
+ */
+/**
+ * Key used to read/write cached values in a {@link GraphValueStoreAdapter}.
+ *
+ * The `fingerprint` must change when meaningful inputs or dependencies change
+ * so stale values are never accidentally reused.
+ */
+export interface GraphValueKey {
+    workflowId: string;
+    nodeId: string;
+    fingerprint: string;
+    namespace?: string;
+    version?: string;
+}

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

@@ -0,0 +1,41 @@
+import type { GraphExecutionValues } from "../types.d.cts";
+import type { GraphValueStoreAdapter } from "./GraphValueStoreAdapter.d.cts";
+import type { GraphValueKey } from "./GraphValueKey.d.cts";
+import type { GraphCachedValue } from "./GraphCachedValue.d.cts";
+/**
+ * Manages values during a single graph execution.
+ *
+ * Runtime values (workflow inputs, node outputs, workflow outputs) are kept in
+ * an in-memory map. Persistent cache and pinning operations are delegated to
+ * the configured {@link GraphValueStoreAdapter}.
+ */
+export declare class GraphValueStore {
+    private readonly adapter;
+    private readonly runtimeValues;
+    /**
+     * @param adapter - The persistent adapter for cached/pinned values.
+     */
+    constructor(adapter: GraphValueStoreAdapter);
+    /** Seeds the workflow input values. */
+    seedWorkflowInputs(inputs: GraphExecutionValues): void;
+    /** Stores the outputs produced by a node. */
+    setNodeOutputs(nodeId: string, outputs: GraphExecutionValues): void;
+    /** Reads a single port value from a node's stored outputs. */
+    getPort(nodeId: string, port: string): unknown;
+    /** Returns whether a node has a value for the given port. */
+    hasPort(nodeId: string, port: string): boolean;
+    /** Sets a single workflow output port value. */
+    setWorkflowOutput(port: string, value: unknown): void;
+    /** Returns all workflow-level values (inputs merged with outputs). */
+    getWorkflowValues(): GraphExecutionValues;
+    /** Reads a cached value from the adapter. */
+    readCached(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
+    /** Writes a cached value through the adapter. */
+    writeCached(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
+    /** Deletes a cached value through the adapter. */
+    deleteCached(key: GraphValueKey): Promise<void>;
+    /** Returns a snapshot of all runtime values. */
+    snapshot(): Record<string, GraphExecutionValues>;
+    /** Returns the underlying adapter (used by the pinning service). */
+    getAdapter(): GraphValueStoreAdapter;
+}

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

@@ -0,0 +1,41 @@
+import type { GraphExecutionValues } from "../types.d.mts";
+import type { GraphValueStoreAdapter } from "./GraphValueStoreAdapter.d.mts";
+import type { GraphValueKey } from "./GraphValueKey.d.mts";
+import type { GraphCachedValue } from "./GraphCachedValue.d.mts";
+/**
+ * Manages values during a single graph execution.
+ *
+ * Runtime values (workflow inputs, node outputs, workflow outputs) are kept in
+ * an in-memory map. Persistent cache and pinning operations are delegated to
+ * the configured {@link GraphValueStoreAdapter}.
+ */
+export declare class GraphValueStore {
+    private readonly adapter;
+    private readonly runtimeValues;
+    /**
+     * @param adapter - The persistent adapter for cached/pinned values.
+     */
+    constructor(adapter: GraphValueStoreAdapter);
+    /** Seeds the workflow input values. */
+    seedWorkflowInputs(inputs: GraphExecutionValues): void;
+    /** Stores the outputs produced by a node. */
+    setNodeOutputs(nodeId: string, outputs: GraphExecutionValues): void;
+    /** Reads a single port value from a node's stored outputs. */
+    getPort(nodeId: string, port: string): unknown;
+    /** Returns whether a node has a value for the given port. */
+    hasPort(nodeId: string, port: string): boolean;
+    /** Sets a single workflow output port value. */
+    setWorkflowOutput(port: string, value: unknown): void;
+    /** Returns all workflow-level values (inputs merged with outputs). */
+    getWorkflowValues(): GraphExecutionValues;
+    /** Reads a cached value from the adapter. */
+    readCached(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
+    /** Writes a cached value through the adapter. */
+    writeCached(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
+    /** Deletes a cached value through the adapter. */
+    deleteCached(key: GraphValueKey): Promise<void>;
+    /** Returns a snapshot of all runtime values. */
+    snapshot(): Record<string, GraphExecutionValues>;
+    /** Returns the underlying adapter (used by the pinning service). */
+    getAdapter(): GraphValueStoreAdapter;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * @module integrations/graph/store/GraphValueStoreAdapter
+ * @summary Adapter interface for persistent graph value storage.
+ * @description Users provide implementations of this interface to control where cached/pinned values live (in-memory, database, Redis, file, etc.).
+ */
+import type { GraphExecutionValues } from "../types.d.cts";
+import type { GraphValueKey } from "./GraphValueKey.d.cts";
+import type { GraphCachedValue } from "./GraphCachedValue.d.cts";
+/**
+ * Adapter that persists cached and pinned graph values.
+ *
+ * The engine never assumes a specific storage backend; it always delegates to
+ * an adapter. The {@link InMemoryGraphValueStoreAdapter} is the default.
+ */
+export interface GraphValueStoreAdapter {
+    /** Reads a cached value for the given key. */
+    read(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
+    /** Writes a cached value for the given key. */
+    write(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
+    /** Deletes a cached value for the given key. */
+    delete(key: GraphValueKey): Promise<void>;
+    /** Returns whether a cached value exists for the given key. */
+    has(key: GraphValueKey): Promise<boolean>;
+    /** Lists cached values matching a prefix of the key. */
+    list?(prefix: Partial<GraphValueKey>): Promise<GraphCachedValue[]>;
+    /** Clears all cached values for a run. */
+    clearRun?(runId: string): Promise<void>;
+    /** Reads the runtime values for a node in a run. */
+    readRuntimeValues?(runId: string, nodeId: string): Promise<GraphExecutionValues | undefined>;
+    /** Writes the runtime values for a node in a run. */
+    writeRuntimeValues?(runId: string, nodeId: string, values: GraphExecutionValues): Promise<void>;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * @module integrations/graph/store/GraphValueStoreAdapter
+ * @summary Adapter interface for persistent graph value storage.
+ * @description Users provide implementations of this interface to control where cached/pinned values live (in-memory, database, Redis, file, etc.).
+ */
+import type { GraphExecutionValues } from "../types.d.mts";
+import type { GraphValueKey } from "./GraphValueKey.d.mts";
+import type { GraphCachedValue } from "./GraphCachedValue.d.mts";
+/**
+ * Adapter that persists cached and pinned graph values.
+ *
+ * The engine never assumes a specific storage backend; it always delegates to
+ * an adapter. The {@link InMemoryGraphValueStoreAdapter} is the default.
+ */
+export interface GraphValueStoreAdapter {
+    /** Reads a cached value for the given key. */
+    read(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
+    /** Writes a cached value for the given key. */
+    write(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
+    /** Deletes a cached value for the given key. */
+    delete(key: GraphValueKey): Promise<void>;
+    /** Returns whether a cached value exists for the given key. */
+    has(key: GraphValueKey): Promise<boolean>;
+    /** Lists cached values matching a prefix of the key. */
+    list?(prefix: Partial<GraphValueKey>): Promise<GraphCachedValue[]>;
+    /** Clears all cached values for a run. */
+    clearRun?(runId: string): Promise<void>;
+    /** Reads the runtime values for a node in a run. */
+    readRuntimeValues?(runId: string, nodeId: string): Promise<GraphExecutionValues | undefined>;
+    /** Writes the runtime values for a node in a run. */
+    writeRuntimeValues?(runId: string, nodeId: string, values: GraphExecutionValues): Promise<void>;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * @module integrations/graph/store/InMemoryGraphValueStoreAdapter
+ * @summary Default in-memory value store adapter.
+ * @description Stores all cached values in a Map. Suitable for testing and single-process execution.
+ */
+import type { GraphValueStoreAdapter } from "./GraphValueStoreAdapter.d.cts";
+import type { GraphValueKey } from "./GraphValueKey.d.cts";
+import type { GraphCachedValue } from "./GraphCachedValue.d.cts";
+/**
+ * In-memory implementation of {@link GraphValueStoreAdapter}.
+ *
+ * Values are keyed by a serialized string combining namespace, workflowId,
+ * nodeId, version, and fingerprint.
+ */
+export declare class InMemoryGraphValueStoreAdapter implements GraphValueStoreAdapter {
+    private readonly values;
+    /** @inheritDoc */
+    read(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
+    /** @inheritDoc */
+    write(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
+    /** @inheritDoc */
+    delete(key: GraphValueKey): Promise<void>;
+    /** @inheritDoc */
+    has(key: GraphValueKey): Promise<boolean>;
+    /** @inheritDoc */
+    list(prefix: Partial<GraphValueKey>): Promise<GraphCachedValue[]>;
+    /** @inheritDoc */
+    clearRun(runId: string): Promise<void>;
+    /**
+     * Serializes a key into a stable string used as the Map key.
+     */
+    private serializeKey;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * @module integrations/graph/store/InMemoryGraphValueStoreAdapter
+ * @summary Default in-memory value store adapter.
+ * @description Stores all cached values in a Map. Suitable for testing and single-process execution.
+ */
+import type { GraphValueStoreAdapter } from "./GraphValueStoreAdapter.d.mts";
+import type { GraphValueKey } from "./GraphValueKey.d.mts";
+import type { GraphCachedValue } from "./GraphCachedValue.d.mts";
+/**
+ * In-memory implementation of {@link GraphValueStoreAdapter}.
+ *
+ * Values are keyed by a serialized string combining namespace, workflowId,
+ * nodeId, version, and fingerprint.
+ */
+export declare class InMemoryGraphValueStoreAdapter implements GraphValueStoreAdapter {
+    private readonly values;
+    /** @inheritDoc */
+    read(key: GraphValueKey): Promise<GraphCachedValue | undefined>;
+    /** @inheritDoc */
+    write(key: GraphValueKey, value: GraphCachedValue): Promise<void>;
+    /** @inheritDoc */
+    delete(key: GraphValueKey): Promise<void>;
+    /** @inheritDoc */
+    has(key: GraphValueKey): Promise<boolean>;
+    /** @inheritDoc */
+    list(prefix: Partial<GraphValueKey>): Promise<GraphCachedValue[]>;
+    /** @inheritDoc */
+    clearRun(runId: string): Promise<void>;
+    /**
+     * Serializes a key into a stable string used as the Map key.
+     */
+    private serializeKey;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/store
+ * @summary Graph value store, adapter, and key types.
+ * @description Re-exports the value store adapter interface, in-memory default, key/cached-value types, and the runtime store wrapper.
+ */
+export * from "./GraphValueKey.d.cts";
+export * from "./GraphCachedValue.d.cts";
+export * from "./GraphValueStoreAdapter.d.cts";
+export * from "./InMemoryGraphValueStoreAdapter.d.cts";
+export * from "./GraphValueStore.d.cts";

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

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/store
+ * @summary Graph value store, adapter, and key types.
+ * @description Re-exports the value store adapter interface, in-memory default, key/cached-value types, and the runtime store wrapper.
+ */
+export * from "./GraphValueKey.d.mts";
+export * from "./GraphCachedValue.d.mts";
+export * from "./GraphValueStoreAdapter.d.mts";
+export * from "./InMemoryGraphValueStoreAdapter.d.mts";
+export * from "./GraphValueStore.d.mts";

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[];
+}