@pikku/core 0.11.1 → 0.12.0

package/dist/wirings/workflow/graph/workflow-graph.types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Ref value - internal representation after input callback is evaluated
+ */
+export interface RefValue {
+    __isRef: true;
+    nodeId: string;
+    path?: string;
+}
+/**
+ * Helper to create a ref value
+ */
+export declare const createRef: (nodeId: string, path?: string) => RefValue;
+/**
+ * Check if a value is a ref
+ */
+export declare const isRef: (value: unknown) => value is RefValue;
+/**
+ * Input reference for fetching step results
+ */
+export interface InputRef {
+    nodeId: string;
+    path?: string;
+}
+/**
+ * Ref function type - provides type-safe references to other nodes' outputs
+ * The actual typing is done at the pikkuWorkflowGraph level
+ */
+export type RefFn<NodeIds extends string = string> = (nodeId: NodeIds, path?: string) => RefValue;
+/**
+ * Next node configuration - fully serializable
+ * - string: single next node
+ * - string[]: parallel execution (all run concurrently)
+ * - Record<string, string | string[]>: branching (function calls graph.branch('key'))
+ */
+export type NextConfig<NodeIds extends string = string> = NodeIds | NodeIds[] | Record<string, NodeIds | NodeIds[]>;
+/**
+ * Graph node configuration - references functions by RPC name
+ */
+export interface GraphNodeConfig<NodeIds extends string = string> {
+    /** RPC function name */
+    func: string;
+    /** Input mapping callback - receives ref function, returns input object */
+    input?: (ref: RefFn<NodeIds>) => Record<string, unknown>;
+    /** Next nodes - string, array, or record for branching */
+    next?: NextConfig<NodeIds>;
+    /** Error routing - node(s) to execute on error */
+    onError?: NodeIds | NodeIds[];
+}
+/**
+ * Graph wire context - available to functions running in a workflow graph
+ */
+export interface PikkuGraphWire {
+    /** Workflow run ID */
+    runId: string;
+    /** Graph name */
+    graphName: string;
+    /** Current node ID */
+    nodeId: string;
+    /**
+     * Select which branch to take for Record-based next config.
+     * Must be called if the node has a Record `next` configuration.
+     * @param key - The branch key to take (must match a key in the next Record)
+     */
+    branch: (key: string) => void;
+    /**
+     * Set a state variable value.
+     * @param name - Variable name
+     * @param value - Value to store
+     */
+    setState: (name: string, value: unknown) => Promise<void>;
+    /**
+     * Get the entire state object.
+     * @returns The state object with all variables
+     */
+    getState: () => Promise<Record<string, unknown>>;
+}
+/**
+ * Internal mutable state for graph wire (used by runner to capture branch)
+ */
+export interface GraphWireState {
+    branchKey?: string;
+}

package/dist/wirings/workflow/graph/workflow-graph.types.js

@@ -0,0 +1,15 @@
+/**
+ * Helper to create a ref value
+ */
+export const createRef = (nodeId, path) => ({
+    __isRef: true,
+    nodeId,
+    path,
+});
+/**
+ * Check if a value is a ref
+ */
+export const isRef = (value) => typeof value === 'object' &&
+    value !== null &&
+    '__isRef' in value &&
+    value.__isRef === true;

package/dist/wirings/workflow/index.d.ts

@@ -1,15 +1,10 @@
 /**
  * Workflow module exports
  */
-export type { CoreWorkflow, WorkflowStepOptions, WorkflowStepMeta, RpcStepMeta, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, InputSource, OutputBinding, PikkuWorkflowWire, PikkuWorkflow, WorkflowsMeta, WorkflowRun, StepState, WorkflowStatus, StepStatus, } from './workflow.types.js';
-export { PikkuWorkflowService } from './pikku-workflow-service.js';
-export { addWorkflow } from './workflow-runner.js';
-/**
- * @deprecated This function is no longer used and will be removed in a future release.
- * It exists only for backwards compatibility with generated code.
- * TODO: Remove this export in a future release after updating code generation
- */
-export declare const wireWorkflow: <T extends {
-    name: string;
-    func: any;
-}>(workflow: T) => void;
+export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowNotFoundError, WorkflowRunNotFoundError, } from './pikku-workflow-service.js';
+export { addWorkflow } from './dsl/workflow-runner.js';
+export { template, type TemplateString } from './graph/template.js';
+export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
+export { workflow, workflowStart, workflowStatus, graphStart, } from './workflow-helpers.js';
+export type { WorkflowService, WorkflowServiceConfig, WorkflowRunWire, WorkflowStatus, StepStatus, WorkflowRun, StepState, WorkflowRunService, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';

package/dist/wirings/workflow/index.js

@@ -1,14 +1,11 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService } from './pikku-workflow-service.js';
-// Internal registration function (used by generated code)
-export { addWorkflow } from './workflow-runner.js';
-/**
- * @deprecated This function is no longer used and will be removed in a future release.
- * It exists only for backwards compatibility with generated code.
- * TODO: Remove this export in a future release after updating code generation
- */
-export const wireWorkflow = (workflow) => {
-    // Empty function - no longer used, kept for backwards compatibility
-};
+export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowNotFoundError, WorkflowRunNotFoundError, } from './pikku-workflow-service.js';
+// Internal registration functions (used by generated code)
+export { addWorkflow } from './dsl/workflow-runner.js';
+// Graph helpers (template, pikkuWorkflowGraph)
+export { template } from './graph/template.js';
+export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
+// Workflow helpers (runtime factories for HTTP handlers)
+export { workflow, workflowStart, workflowStatus, graphStart, } from './workflow-helpers.js';

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,5 +1,40 @@
 import { CoreConfig, CoreSingletonServices, CreateWireServices, SerializedError } from '../../types/core.types.js';
-import type { StepState, WorkflowRun, WorkflowStatus, WorkflowService, WorkflowStepOptions } from './workflow.types.js';
+import type { StepState, WorkflowRun, WorkflowRunWire, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
+import { WorkflowService } from '../../services/workflow-service.js';
+import { PikkuError } from '../../errors/error-handler.js';
+/**
+ * Exception thrown when workflow needs to pause for async step
+ */
+export declare class WorkflowAsyncException extends Error {
+    readonly runId: string;
+    readonly stepName: string;
+    constructor(runId: string, stepName: string);
+}
+/**
+ * Exception thrown when workflow is cancelled
+ */
+export declare class WorkflowCancelledException extends Error {
+    readonly runId: string;
+    readonly reason?: string | undefined;
+    constructor(runId: string, reason?: string | undefined);
+}
+/**
+ * Exception thrown when workflow is suspended
+ */
+export declare class WorkflowSuspendedException extends Error {
+    readonly runId: string;
+    readonly reason: string;
+    constructor(runId: string, reason: string);
+}
+/**
+ * Error class for workflow not found
+ */
+export declare class WorkflowNotFoundError extends PikkuError {
+    constructor(name: string);
+}
+export declare class WorkflowRunNotFoundError extends PikkuError {
+    constructor(runId: string);
+}
 export declare class WorkflowServiceNotInitialized extends Error {
 }
 export declare class WorkflowStepNameNotString extends Error {
@@ -14,15 +49,23 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private config;
     private singletonServices;
     private createWireServices;
+    private inlineRuns;
     constructor();
-    setServices(singletonServices: CoreSingletonServices, createWireServices: CreateWireServices, { workflow }: CoreConfig): void;
     /**
-     * Create a new workflow run
-     * @param name - Workflow name
-     * @param input - Input data for the workflow
-     * @returns Run ID
+     * Check if a run is executing inline (without queues)
      */
-    abstract createRun(workflowName: string, input: any): Promise<string>;
+    protected isInline(runId: string): boolean;
+    /**
+     * Register a run as inline (for graph-runner to use)
+     */
+    registerInlineRun(runId: string): void;
+    /**
+     * Unregister a run from inline tracking
+     */
+    unregisterInlineRun(runId: string): void;
+    setServices(singletonServices: CoreSingletonServices, createWireServices: CreateWireServices | undefined, { workflow }: CoreConfig): void;
+    registerWorkflowVersions(): Promise<void>;
+    abstract createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire): Promise<string>;
     /**
      * Get a workflow run by ID
      * @param id - Run ID
@@ -115,17 +158,66 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * Close any open connections
      */
     abstract close(): Promise<void>;
+    /**
+     * Get completed graph state (lightweight - no results)
+     * @param runId - Run ID
+     * @returns Completed node IDs and their branch keys
+     */
+    abstract getCompletedGraphState(runId: string): Promise<{
+        completedNodeIds: string[];
+        failedNodeIds: string[];
+        branchKeys: Record<string, string>;
+    }>;
+    /**
+     * Filter candidate nodes to only those without existing steps
+     * @param runId - Run ID
+     * @param nodeIds - Candidate node IDs to check
+     * @returns Node IDs that don't have a step yet
+     */
+    abstract getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
+    /**
+     * Get results for specific nodes
+     * @param runId - Run ID
+     * @param nodeIds - Node IDs to fetch results for
+     * @returns Map of nodeId to result
+     */
+    abstract getNodeResults(runId: string, nodeIds: string[]): Promise<Record<string, any>>;
+    /**
+     * Set the branch key for a graph node step
+     * @param stepId - Step ID
+     * @param branchKey - Branch key selected by graph.branch()
+     */
+    abstract setBranchTaken(stepId: string, branchKey: string): Promise<void>;
+    /**
+     * Update a state variable in the workflow run's state
+     * @param runId - Run ID
+     * @param name - Variable name
+     * @param value - Value to store
+     */
+    abstract updateRunState(runId: string, name: string, value: unknown): Promise<void>;
+    /**
+     * Get the entire state object for a workflow run
+     * @param runId - Run ID
+     * @returns The state object with all variables
+     */
+    abstract getRunState(runId: string): Promise<Record<string, unknown>>;
+    abstract upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string): Promise<void>;
+    abstract getWorkflowVersion(name: string, graphHash: string): Promise<{
+        graph: any;
+        source: string;
+    } | null>;
     /**
      * Resume a paused workflow by triggering the orchestrator
      * @param runId - Run ID
      */
     resumeWorkflow(runId: string): Promise<void>;
+    queueStepWorker(runId: string, stepName: string, rpcName: string, data: any): Promise<void>;
     /**
      * Execute a workflow sleep step completion
      * Sets the step result to null and resumes the workflow
      * @param data - Sleeper input data
      */
-    executeWorkflowSleep(runId: string, stepId: string): Promise<void>;
+    executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>;
     /**
      * Schedule orchestrator retry with delay
      * @param runId - Run ID
@@ -134,11 +226,22 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     protected scheduleOrchestratorRetry(runId: string, retryDelay?: number | string): Promise<void>;
     /**
      * Start a new workflow run
+     * Automatically detects workflow type (DSL or graph) from meta and executes accordingly
+     * @param options.inline - If true, execute workflow directly without queue service
+     * @param options.startNode - Starting node ID for graph workflows (from wire config)
      */
-    startWorkflow<I>(name: string, input: I, rpcService: any): Promise<{
+    startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
+        inline?: boolean;
+        startNode?: string;
+    }): Promise<{
         runId: string;
     }>;
+    runToCompletion<I>(name: string, input: I, rpcService: any, options?: {
+        pollIntervalMs?: number;
+        wire?: WorkflowRunWire;
+    }): Promise<any>;
     runWorkflowJob(runId: string, rpcService: any): Promise<void>;
+    private runVersionMismatchFallback;
     /**
      * Execute a single workflow step (called by worker)
      * Handles idempotency, RPC execution, result storage, retry logic, and orchestrator triggering
@@ -153,7 +256,8 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private rpcStep;
     private inlineStep;
     private sleepStep;
-    private cancelWorkflow;
+    private getSuspendStepName;
+    private suspendStep;
     private createWorkflowWire;
     private verifyStepName;
     private getConfig;