@pikku/core 0.12.4 → 0.12.5

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -0,0 +1,320 @@
+/**
+ * DSL (Domain Specific Language) workflow types
+ * These types define the step-based workflow format extracted by the inspector
+ */
+
+import type { WorkflowRun } from '../workflow.types.js'
+
+/**
+ * Workflow step options
+ */
+export interface WorkflowStepOptions {
+  /** Display name for logs/UI (optional, doesn't affect execution) */
+  description?: string
+  /** Number of retry attempts for failed steps (only applies to local execution) */
+  retries?: number
+  /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
+  retryDelay?: string | number
+  // Future: timeout, failFast, priority
+}
+
+/**
+ * Type signature for workflow.do() RPC form - used by inspector
+ */
+export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(
+  stepName: string,
+  rpcName: string,
+  data: TInput,
+  options?: WorkflowStepOptions
+) => Promise<TOutput>
+
+/**
+ * Type signature for workflow.do() inline form - used by inspector
+ */
+export type WorkflowWireDoInline = <T>(
+  stepName: string,
+  fn: () => Promise<T> | T,
+  options?: WorkflowStepOptions
+) => Promise<T>
+
+/**
+ * Type signature for workflow.sleep() - used by inspector
+ */
+export type WorkflowWireSleep = (
+  stepName: string,
+  duration: string
+) => Promise<void>
+
+/**
+ * Type signature for workflow.suspend() - used by inspector
+ */
+export type WorkflowWireSuspend = (reason: string) => Promise<void>
+
+/**
+ * Input source for step arguments in DSL workflows
+ */
+export type InputSource =
+  | { from: 'input'; path: string }
+  | { from: 'outputVar'; name: string; path?: string }
+  | { from: 'item'; path: string }
+  | { from: 'literal'; value: unknown }
+  | { from: 'template'; parts: string[]; expressions: InputSource[] }
+
+/**
+ * Output binding for return statements in DSL workflows
+ */
+export type OutputBinding =
+  | { from: 'outputVar'; name: string; path?: string }
+  | { from: 'stateVar'; name: string; path?: string }
+  | { from: 'input'; path: string }
+  | { from: 'literal'; value: unknown }
+  | { from: 'expression'; expression: string }
+
+/**
+ * RPC step metadata (base form)
+ */
+export interface RpcStepMeta {
+  /** RPC form - generates queue worker */
+  type: 'rpc'
+  /** Cache key (stepName from workflow.do) */
+  stepName: string
+  /** RPC to invoke */
+  rpcName: string
+  /** Output variable name (if assigned) */
+  outputVar?: string
+  /** Input source mappings, or 'passthrough' when entire data is passed */
+  inputs?: Record<string, InputSource> | 'passthrough'
+  /** Step options */
+  options?: WorkflowStepOptions
+}
+
+/**
+ * Simple condition expression (leaf node)
+ */
+export interface SimpleCondition {
+  type: 'simple'
+  expression: string
+}
+
+/**
+ * Nested condition structure supporting AND/OR operations
+ */
+export type Condition =
+  | SimpleCondition
+  | { type: 'and'; conditions: Condition[] }
+  | { type: 'or'; conditions: Condition[] }
+
+/**
+ * A single branch in an if/else-if chain
+ */
+export interface BranchCase {
+  /** Condition for this branch */
+  condition: Condition
+  /** Steps to execute when condition is true */
+  steps: WorkflowStepMeta[]
+}
+
+/**
+ * Branch step metadata (if/else-if/else control flow)
+ */
+export interface BranchStepMeta {
+  type: 'branch'
+  /** Branches in order: first is "if", rest are "else if" */
+  branches: BranchCase[]
+  /** Else branch steps (when no conditions match) */
+  elseSteps?: WorkflowStepMeta[]
+}
+
+/**
+ * Parallel group step metadata (Promise.all with multiple steps)
+ */
+export interface ParallelGroupStepMeta {
+  type: 'parallel'
+  /** Child steps to execute in parallel */
+  children: RpcStepMeta[]
+}
+
+/**
+ * Fanout step metadata (parallel or sequential iteration)
+ */
+export interface FanoutStepMeta {
+  type: 'fanout'
+  /** Step name for this fanout */
+  stepName: string
+  /** Source array variable name */
+  sourceVar: string
+  /** Iterator variable name */
+  itemVar: string
+  /** Execution mode */
+  mode: 'parallel' | 'sequential'
+  /** Child step to execute per iteration */
+  child: RpcStepMeta
+  /** Time between iterations (sequential mode only) */
+  timeBetween?: string
+}
+
+/**
+ * Return step metadata (workflow output)
+ */
+export interface ReturnStepMeta {
+  type: 'return'
+  /** Output bindings */
+  outputs: Record<string, OutputBinding>
+}
+
+/**
+ * Inline step metadata (legacy support)
+ */
+export interface InlineStepMeta {
+  /** Inline form - local execution */
+  type: 'inline'
+  /** Cache key (stepName from workflow.do) */
+  stepName: string
+  /** Display name */
+  description?: string
+  /** Step options */
+  options?: WorkflowStepOptions
+}
+
+/**
+ * Sleep step metadata
+ */
+export interface SleepStepMeta {
+  /** Sleep step */
+  type: 'sleep'
+  /** Cache key (stepName from workflow.sleep) */
+  stepName: string
+  /** Sleep duration */
+  duration: string | number
+}
+
+/**
+ * Cancel step metadata
+ */
+export interface CancelStepMeta {
+  /** Cancel step */
+  type: 'cancel'
+  /** Optional cancellation reason */
+  reason?: string
+}
+
+/**
+ * Set step metadata (context variable assignment)
+ */
+export interface SetStepMeta {
+  /** Set step */
+  type: 'set'
+  /** Variable name to set (must be in context) */
+  variable: string
+  /** Value to assign (literal or expression) */
+  value: unknown
+}
+
+/**
+ * Switch case metadata
+ */
+export interface SwitchCaseMeta {
+  /** Case value (literal) or expression */
+  value?: string | number | boolean | null
+  /** Case expression (for complex cases) */
+  expression?: string
+  /** Steps to execute for this case */
+  steps: WorkflowStepMeta[]
+}
+
+/**
+ * Switch step metadata (switch/case control flow)
+ */
+export interface SwitchStepMeta {
+  type: 'switch'
+  /** Expression being switched on */
+  expression: string
+  /** Case branches */
+  cases: SwitchCaseMeta[]
+  /** Default case steps (optional) */
+  defaultSteps?: WorkflowStepMeta[]
+}
+
+/**
+ * Filter step metadata (array.filter)
+ */
+export interface FilterStepMeta {
+  type: 'filter'
+  /** Source array variable name */
+  sourceVar: string
+  /** Iterator variable name */
+  itemVar: string
+  /** Filter condition */
+  condition: Condition
+  /** Output variable name (if assigned) */
+  outputVar?: string
+}
+
+/**
+ * Array predicate step metadata (array.some, array.every)
+ */
+export interface ArrayPredicateStepMeta {
+  type: 'arrayPredicate'
+  /** Predicate mode */
+  mode: 'some' | 'every'
+  /** Source array variable name */
+  sourceVar: string
+  /** Iterator variable name */
+  itemVar: string
+  /** Predicate condition */
+  condition: Condition
+  /** Output variable name (if assigned) */
+  outputVar?: string
+}
+
+/**
+ * Workflow step metadata (extracted by inspector)
+ */
+export type WorkflowStepMeta =
+  | RpcStepMeta
+  | BranchStepMeta
+  | ParallelGroupStepMeta
+  | FanoutStepMeta
+  | ReturnStepMeta
+  | InlineStepMeta
+  | SleepStepMeta
+  | CancelStepMeta
+  | SwitchStepMeta
+  | FilterStepMeta
+  | ArrayPredicateStepMeta
+  | SetStepMeta
+
+/**
+ * Workflow step wire context for RPC functions
+ * Provides step-level metadata including retry attempt tracking
+ */
+export interface WorkflowStepWire {
+  /** The workflow run ID */
+  runId: string
+  /** The unique step ID */
+  stepId: string
+  /** Current attempt number (1-indexed, increments on retry) */
+  attemptCount: number
+}
+
+/**
+ * Workflow wire object for DSL workflows
+ * Provides workflow-specific capabilities to function execution
+ */
+export interface PikkuWorkflowWire {
+  /** The workflow name */
+  name: string
+  /** The current run ID */
+  runId: string
+  /** Get the current workflow run */
+  getRun: () => Promise<WorkflowRun>
+
+  /** Execute a workflow step (overloaded - RPC or inline form) */
+  do: WorkflowWireDoRPC & WorkflowWireDoInline
+
+  /** Sleep for a duration */
+  sleep: WorkflowWireSleep
+
+  /** Suspend workflow until explicitly resumed */
+  suspend: WorkflowWireSuspend
+}

package/src/wirings/workflow/dsl/workflow-runner.ts

@@ -0,0 +1,28 @@
+import { pikkuState } from '../../../pikku-state.js'
+import { addFunction } from '../../../function/function-runner.js'
+import { PikkuMissingMetaError } from '../../../errors/errors.js'
+
+/**
+ * Add a workflow to the system
+ * This is called by the generated workflow wirings
+ */
+export const addWorkflow = (workflowName: string, workflowFunc: any) => {
+  // Get workflow metadata from inspector
+  const meta = pikkuState(null, 'workflows', 'meta')
+  const workflowMeta = meta[workflowName]
+  if (!workflowMeta) {
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for workflow '${workflowName}'`
+    )
+  }
+
+  // Store workflow definition in state
+  const registrations = pikkuState(null, 'workflows', 'registrations')
+  registrations.set(workflowName, {
+    name: workflowName,
+    func: workflowFunc,
+  })
+
+  // Register the function with pikku
+  addFunction(workflowMeta.pikkuFuncId, workflowFunc)
+}

package/src/wirings/workflow/graph/graph-node.ts

@@ -0,0 +1,222 @@
+import type {
+  GraphNodeConfig,
+  NextConfig,
+  RefValue,
+} from './workflow-graph.types.js'
+
+/**
+ * Standard RPC handler interface (matches generated FlattenedRPCMap entries)
+ */
+export interface RPCHandler<I = any, O = any> {
+  input: I
+  output: O
+}
+
+/**
+ * Compute output types for all nodes based on their func (RPC name)
+ */
+export type NodeOutputMap<
+  Nodes extends Record<string, { func: string }>,
+  RPCMap extends Record<string, RPCHandler>,
+> = {
+  [K in keyof Nodes]: Nodes[K]['func'] extends keyof RPCMap
+    ? RPCMap[Nodes[K]['func']]['output']
+    : unknown
+}
+
+/**
+ * Node definition with RPC name reference
+ */
+export interface GraphNodeDef<
+  RPCMap extends Record<string, RPCHandler>,
+  NodeIds extends string = string,
+  NodeOutputs extends Record<string, any> = Record<string, any>,
+> {
+  /** RPC function name (must be a key in RPCMap) */
+  func: keyof RPCMap & string
+  /** Input mapping - reference outputs from other nodes with autocomplete */
+  input?: (
+    ref: <N extends keyof NodeOutputs & string>(
+      nodeId: N,
+      path: keyof NodeOutputs[N] & string
+    ) => RefValue
+  ) => Record<string, unknown>
+  /** Next node(s) to execute */
+  next?: NextConfig<NodeIds>
+  /** Error handling - node(s) to execute on error */
+  onError?: NodeIds | NodeIds[]
+}
+
+/**
+ * Helper to create a type-safe graph definition with RPC autocomplete.
+ * Pass node IDs as first type parameter for type-safe next/ref/output key completion.
+ *
+ * @example
+ * ```typescript
+ * // Import the typed graph from generated types
+ * import { pikkuWorkflowGraph } from './.pikku/workflow/pikku-workflow-types.gen.js'
+ *
+ * export const myGraph = pikkuWorkflowGraph({
+ *   name: 'myWorkflow',
+ *   nodes: {
+ *     entry: 'createUserProfile',  // autocompletes RPC names
+ *     sendWelcome: 'sendEmail',
+ *   },
+ *   config: {
+ *     entry: { next: 'sendWelcome' },
+ *     sendWelcome: {
+ *       input: (ref) => ({
+ *         to: ref('entry', 'email'),  // 'entry' and 'email' both autocomplete
+ *       }),
+ *     },
+ *   },
+ * })
+ * ```
+ */
+/**
+ * Type to compute output types for all nodes based on their func mapping
+ */
+type ComputeNodeOutputs<
+  FuncMap extends Record<string, string>,
+  RPCMap extends Record<string, RPCHandler>,
+> = {
+  [K in keyof FuncMap]: FuncMap[K] extends keyof RPCMap
+    ? RPCMap[FuncMap[K]]['output']
+    : unknown
+}
+
+/**
+ * Type to compute input types for all nodes based on their func mapping
+ */
+type ComputeNodeInputs<
+  FuncMap extends Record<string, string>,
+  RPCMap extends Record<string, RPCHandler>,
+> = {
+  [K in keyof FuncMap]: FuncMap[K] extends keyof RPCMap
+    ? RPCMap[FuncMap[K]]['input']
+    : unknown
+}
+
+/**
+ * Typed ref value - carries the type of the referenced field as a phantom type.
+ * At runtime this is just RefValue, but TypeScript tracks the type T.
+ */
+export type TypedRef<T> = RefValue & { __phantomType?: T }
+
+/**
+ * Map input type fields to allow TypedRef of matching type as an alternative
+ */
+type InputWithRefs<T> = {
+  [K in keyof T]: T[K] | TypedRef<T[K]>
+}
+
+export function createGraph<RPCMap extends Record<string, RPCHandler>>() {
+  return <const FuncMap extends Record<string, keyof RPCMap & string>>(
+    funcMap: FuncMap,
+    nodesOrBuilder?:
+      | GraphNodeConfigMap<FuncMap, RPCMap>
+      | ((nodes: FuncMap) => GraphNodeConfigMap<FuncMap, RPCMap>)
+  ): Record<
+    Extract<keyof FuncMap, string>,
+    GraphNodeConfig<Extract<keyof FuncMap, string>>
+  > => {
+    type NodeIds = Extract<keyof FuncMap, string>
+
+    // If no nodes provided, return just the funcMap converted to graph nodes
+    if (!nodesOrBuilder) {
+      const result: Record<string, GraphNodeConfig<string>> = {}
+      for (const [nodeId, rpcName] of Object.entries(funcMap)) {
+        result[nodeId] = {
+          func: rpcName as string,
+        }
+      }
+      return result as Record<NodeIds, GraphNodeConfig<NodeIds>>
+    }
+
+    const nodes =
+      typeof nodesOrBuilder === 'function'
+        ? nodesOrBuilder(funcMap)
+        : nodesOrBuilder
+
+    const result: Record<string, GraphNodeConfig<string>> = {}
+
+    for (const [nodeId, def] of Object.entries(nodes) as [string, any][]) {
+      result[nodeId] = {
+        func: funcMap[nodeId] as string,
+        input: def?.input as any,
+        next: def?.next,
+        onError: def?.onError,
+      }
+    }
+
+    return result as Record<NodeIds, GraphNodeConfig<NodeIds>>
+  }
+}
+
+/**
+ * Type helper for node configuration map
+ */
+type GraphNodeConfigMap<
+  FuncMap extends Record<string, string>,
+  RPCMap extends Record<string, RPCHandler>,
+> = {
+  [K in Extract<keyof FuncMap, string>]?: {
+    next?: NextConfig<Extract<keyof FuncMap, string>>
+    input?: (
+      ref: <
+        N extends Extract<keyof FuncMap, string>,
+        P extends keyof ComputeNodeOutputs<FuncMap, RPCMap>[N] & string,
+      >(
+        nodeId: N,
+        path: P
+      ) => TypedRef<ComputeNodeOutputs<FuncMap, RPCMap>[N][P]>
+    ) => InputWithRefs<ComputeNodeInputs<FuncMap, RPCMap>[K]>
+    onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[]
+  }
+}
+
+/**
+ * Untyped graph for use without RPC map.
+ * Pass node IDs as type parameter for type-safe next/ref, or omit for untyped usage.
+ *
+ * @example
+ * ```typescript
+ * // Typed usage - next and ref are type-checked
+ * graph<'entry' | 'sendWelcome'>({
+ *   entry: { func: 'createUserProfile', next: 'sendWelcome' },
+ *   sendWelcome: { func: 'sendEmail', input: (ref) => ({ to: ref('entry', 'email') }) },
+ * })
+ *
+ * // Untyped usage - no type checking on next/ref
+ * graph({
+ *   entry: { func: 'createUserProfile', next: 'sendWelcome' },
+ *   sendWelcome: { func: 'sendEmail' },
+ * })
+ * ```
+ */
+export function graph<NodeIds extends string = string>(
+  nodes: Record<
+    NodeIds,
+    {
+      func: string
+      next?: NextConfig<NodeIds>
+      input?: (
+        ref: (nodeId: NodeIds, path: string) => RefValue
+      ) => Record<string, unknown>
+      onError?: NodeIds | NodeIds[]
+    }
+  >
+): Record<NodeIds, GraphNodeConfig<NodeIds>> {
+  const result: Record<string, GraphNodeConfig<string>> = {}
+
+  for (const [nodeId, def] of Object.entries(nodes) as [string, any][]) {
+    result[nodeId] = {
+      func: def.func,
+      input: def.input as any,
+      next: def.next,
+      onError: def.onError,
+    }
+  }
+
+  return result as Record<NodeIds, GraphNodeConfig<NodeIds>>
+}