@pikku/core 0.11.0 → 0.11.2

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

@@ -0,0 +1,95 @@
+/**
+ * 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[];
+}
+import type { WorkflowWires } from '../workflow.types.js';
+export type { WorkflowWires };
+/**
+ * Workflow graph definition (internal use)
+ */
+export interface WorkflowGraphDefinition<Nodes extends Record<string, GraphNodeConfig<string>> = Record<string, GraphNodeConfig>> {
+    /** Unique workflow name */
+    name: string;
+    /** Wire configuration */
+    wires: WorkflowWires;
+    /** Graph nodes */
+    graph: Nodes;
+}
+/**
+ * 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,6 +1,10 @@
 /**
  * Workflow module exports
  */
-export type { CoreWorkflow, WorkflowStepOptions, WorkflowStepMeta, PikkuWorkflowInteraction, PikkuWorkflow, WorkflowsMeta, WorkflowRun, StepState, WorkflowStatus, StepStatus, } from './workflow.types.js';
-export { PikkuWorkflowService } from './pikku-workflow-service.js';
-export { wireWorkflow } from './workflow-runner.js';
+export { PikkuWorkflowService, WorkflowCancelledException, } from './pikku-workflow-service.js';
+export { addWorkflow } from './dsl/workflow-runner.js';
+export { addWorkflowGraph } from './graph/graph-runner.js';
+export { wireWorkflow } from './wire-workflow.js';
+export type { WorkflowDefinition, WorkflowDefinitionFunc, WorkflowDefinitionGraph, } from './wire-workflow.js';
+export type { WorkflowService, WorkflowServiceConfig, WorkflowHTTPWire, WorkflowWires, WorkflowStatus, StepStatus, WorkflowRun, StepState, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, 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,6 +1,9 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService } from './pikku-workflow-service.js';
-// Functions
-export { wireWorkflow } from './workflow-runner.js';
+export { PikkuWorkflowService, WorkflowCancelledException, } from './pikku-workflow-service.js';
+// Internal registration functions (used by generated code)
+export { addWorkflow } from './dsl/workflow-runner.js';
+export { addWorkflowGraph } from './graph/graph-runner.js';
+// Unified wireWorkflow function
+export { wireWorkflow } from './wire-workflow.js';

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

@@ -1,5 +1,35 @@
-import { CoreConfig, CoreSingletonServices, CreateSessionServices, SerializedError } from '../../types/core.types.js';
-import type { StepState, WorkflowRun, WorkflowStatus, WorkflowService, WorkflowStepOptions } from './workflow.types.js';
+import { CoreConfig, CoreSingletonServices, CreateWireServices, SerializedError } from '../../types/core.types.js';
+import type { StepState, WorkflowRun, 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);
+}
+/**
+ * Error class for workflow not found
+ */
+export declare class WorkflowNotFoundError extends PikkuError {
+    constructor(name: string);
+}
+/**
+ * Error class for workflow not found
+ */
+export declare class WorkflowRunNotFound extends PikkuError {
+    constructor(runId: string);
+}
 export declare class WorkflowServiceNotInitialized extends Error {
 }
 export declare class WorkflowStepNameNotString extends Error {
@@ -13,16 +43,29 @@ export declare class WorkflowStepNameNotString extends Error {
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private config;
     private singletonServices;
-    private createSessionServices;
+    private createWireServices;
+    private inlineRuns;
     constructor();
-    setServices(singletonServices: CoreSingletonServices, createSessionServices: CreateSessionServices, { workflow }: CoreConfig): void;
+    /**
+     * Check if a run is executing inline (without queues)
+     */
+    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, { workflow }: CoreConfig): void;
     /**
      * Create a new workflow run
      * @param name - Workflow name
      * @param input - Input data for the workflow
      * @returns Run ID
      */
-    abstract createRun(workflowName: string, input: any): Promise<string>;
+    abstract createRun(workflowName: string, input: any, inline?: boolean): Promise<string>;
     /**
      * Get a workflow run by ID
      * @param id - Run ID
@@ -103,10 +146,60 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @returns Function result
      */
     abstract withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute function within a step lock to prevent concurrent step execution
+     * @param runId - Run ID
+     * @param stepName - Step name
+     * @param fn - Function to execute
+     * @returns Function result
+     */
+    abstract withStepLock<T>(runId: string, stepName: string, fn: () => Promise<T>): Promise<T>;
     /**
      * 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[];
+        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>>;
     /**
      * Resume a paused workflow by triggering the orchestrator
      * @param runId - Run ID
@@ -117,7 +210,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * 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
@@ -126,8 +219,14 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     protected scheduleOrchestratorRetry(runId: string, retryDelay?: number | string): Promise<void>;
     /**
      * Start a new workflow run
-     */
-    startWorkflow<I>(name: string, input: I, rpcService: any): Promise<{
+     * 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, options?: {
+        inline?: boolean;
+        startNode?: string;
+    }): Promise<{
         runId: string;
     }>;
     runWorkflowJob(runId: string, rpcService: any): Promise<void>;
@@ -145,8 +244,7 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private rpcStep;
     private inlineStep;
     private sleepStep;
-    private cancelWorkflow;
-    private createWorkflowInteraction;
+    private createWorkflowWire;
     private verifyStepName;
     private getConfig;
 }