@pikku/core 0.12.2 → 0.12.4

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

@@ -1,320 +0,0 @@
-/**
- * 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

@@ -1,28 +0,0 @@
-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

@@ -1,222 +0,0 @@
-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>>
-}