@pikku/core 0.11.1 → 0.11.2

package/dist/wirings/trigger/trigger.types.d.ts

@@ -0,0 +1,42 @@
+import type { CorePikkuTriggerFunctionConfig } from '../../function/functions.types.js';
+/**
+ * The trigger interaction object passed to trigger functions via the wire.
+ * Call trigger() to fire the trigger and start a new workflow/execution.
+ */
+export interface PikkuTrigger<TOutput = unknown> {
+    trigger: (data: TOutput) => void;
+}
+/**
+ * Metadata for registered triggers stored in state.
+ */
+export type TriggerMeta = Record<string, {
+    pikkuFuncName: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+}>;
+/**
+ * Core trigger definition for registration.
+ *
+ * @template TConfig - Configuration type
+ * @template TOutput - Output type
+ */
+export interface CoreTrigger<TConfig = unknown, TOutput = unknown, TriggerFunctionConfig extends CorePikkuTriggerFunctionConfig<TConfig, TOutput> = CorePikkuTriggerFunctionConfig<TConfig, TOutput>> {
+    /** Unique name for this trigger */
+    name: string;
+    /** The trigger function configuration */
+    func: TriggerFunctionConfig;
+    /** Configuration to pass to the trigger function */
+    config: TConfig;
+    /** Optional description */
+    description?: string;
+    /** Optional tags for categorization */
+    tags?: string[];
+}
+/**
+ * Represents a trigger instance with teardown capability
+ */
+export interface TriggerInstance {
+    name: string;
+    teardown: () => void | Promise<void>;
+}

package/dist/wirings/trigger/trigger.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * DSL (Domain Specific Language) workflow exports
+ */
+export { addWorkflow } from './workflow-runner.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';

package/dist/wirings/workflow/dsl/index.js

@@ -0,0 +1,4 @@
+/**
+ * DSL (Domain Specific Language) workflow exports
+ */
+export { addWorkflow } from './workflow-runner.js';

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

@@ -0,0 +1,286 @@
+/**
+ * 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;
+}
+/**
+ * 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>;
+/**
+ * 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 */
+    workflowName: 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;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * DSL (Domain Specific Language) workflow types
+ * These types define the step-based workflow format extracted by the inspector
+ */
+export {};

package/dist/wirings/workflow/dsl/workflow-runner.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Add a workflow to the system
+ * This is called by the generated workflow wirings
+ */
+export declare const addWorkflow: (workflowName: string, workflowFunc: any) => void;

package/dist/wirings/workflow/dsl/workflow-runner.js

@@ -0,0 +1,22 @@
+import { pikkuState } from '../../../pikku-state.js';
+import { addFunction } from '../../../function/function-runner.js';
+/**
+ * Add a workflow to the system
+ * This is called by the generated workflow wirings
+ */
+export const addWorkflow = (workflowName, workflowFunc) => {
+    // Get workflow metadata from inspector
+    const meta = pikkuState(null, 'workflows', 'meta');
+    const workflowMeta = meta[workflowName];
+    if (!workflowMeta) {
+        throw new Error(`Workflow metadata not found for '${workflowName}'. Make sure to run the CLI to generate metadata.`);
+    }
+    // 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.pikkuFuncName, workflowFunc);
+};

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

@@ -0,0 +1,122 @@
+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, wireWorkflow } 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
+ *       }),
+ *     },
+ *   },
+ * })
+ *
+ * wireWorkflow({
+ *   wires: { http: { route: '/start', method: 'post' } },
+ *   graph: myGraph,
+ * })
+ * ```
+ */
+/**
+ * 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 declare function createGraph<RPCMap extends Record<string, RPCHandler>>(): <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 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 declare 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>>;
+export {};

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

@@ -0,0 +1,58 @@
+export function createGraph() {
+    return (funcMap, nodesOrBuilder) => {
+        // If no nodes provided, return just the funcMap converted to graph nodes
+        if (!nodesOrBuilder) {
+            const result = {};
+            for (const [nodeId, rpcName] of Object.entries(funcMap)) {
+                result[nodeId] = {
+                    func: rpcName,
+                };
+            }
+            return result;
+        }
+        const nodes = typeof nodesOrBuilder === 'function'
+            ? nodesOrBuilder(funcMap)
+            : nodesOrBuilder;
+        const result = {};
+        for (const [nodeId, def] of Object.entries(nodes)) {
+            result[nodeId] = {
+                func: funcMap[nodeId],
+                input: def?.input,
+                next: def?.next,
+                onError: def?.onError,
+            };
+        }
+        return result;
+    };
+}
+/**
+ * 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(nodes) {
+    const result = {};
+    for (const [nodeId, def] of Object.entries(nodes)) {
+        result[nodeId] = {
+            func: def.func,
+            input: def.input,
+            next: def.next,
+            onError: def.onError,
+        };
+    }
+    return result;
+}

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

@@ -0,0 +1,35 @@
+import type { PikkuWorkflowService } from '../pikku-workflow-service.js';
+import type { GraphNodeConfig, WorkflowGraphDefinition } from './workflow-graph.types.js';
+/**
+ * Add a workflow graph to the system
+ * This is called by the generated workflow wirings
+ */
+export declare const addWorkflowGraph: (workflowName: string, graphResult: {
+    graph: Record<string, GraphNodeConfig<string>>;
+    wires?: any;
+}) => void;
+/**
+ * Get a registered workflow graph by name
+ */
+export declare function getWorkflowGraph(name: string): WorkflowGraphDefinition<any> | undefined;
+/**
+ * Continue graph execution
+ * Non-blocking - finds pending nodes, resolves inputs, queues them for execution
+ */
+export declare function continueGraph(workflowService: PikkuWorkflowService, runId: string, graphName: string): Promise<void>;
+/**
+ * Execute a graph step with wire context.
+ * Called by the step worker when executing graph nodes.
+ */
+export declare function executeGraphStep(workflowService: PikkuWorkflowService, rpcService: any, runId: string, stepId: string, stepName: string, rpcName: string, data: any, graphName: string): Promise<any>;
+/**
+ * Handle node completion - re-triggers graph continuation
+ */
+export declare function onGraphNodeComplete(workflowService: PikkuWorkflowService, runId: string, graphName: string): Promise<void>;
+/**
+ * Start a workflow graph execution
+ * @param startNode - Optional starting node ID (from wire config). If not provided, uses wires.api from graph definition.
+ */
+export declare function runWorkflowGraph(workflowService: PikkuWorkflowService, graphName: string, triggerInput: any, rpcService?: any, inline?: boolean, startNode?: string): Promise<{
+    runId: string;
+}>;