@donkeylabs/server 0.4.8 → 0.5.0

package/docs/workflows.md

@@ -1,6 +1,6 @@
 # Workflows
 
-Workflows provide step function / state machine orchestration for complex multi-step processes. Built on top of the Jobs service, workflows support sequential tasks, parallel execution, conditional branching, retries, and real-time progress via SSE.
+Workflows provide step function / state machine orchestration for complex multi-step processes. Workflows support sequential tasks with inline handlers, parallel execution, conditional branching, retries, and real-time progress via SSE.
 
 ## Overview
 
@@ -17,11 +17,17 @@ Use workflows when you need to:
 
 ```typescript
 import { workflow } from "@donkeylabs/server";
+import { z } from "zod";
 
 const orderWorkflow = workflow("process-order")
+  // First task: inputSchema validates workflow input
   .task("validate", {
-    job: "validate-order",
-    input: (ctx) => ({ orderId: ctx.input.orderId }),
+    inputSchema: z.object({ orderId: z.string() }),
+    outputSchema: z.object({ valid: z.boolean(), inStock: z.boolean(), total: z.number() }),
+    handler: async (input, ctx) => {
+      const order = await ctx.plugins.orders.validate(input.orderId);
+      return { valid: true, inStock: order.inStock, total: order.total };
+    },
   })
   .choice("check-inventory", {
     choices: [
@@ -35,16 +41,35 @@ const orderWorkflow = workflow("process-order")
   .parallel("fulfill", {
     branches: [
       workflow.branch("shipping")
-        .task("ship", { job: "create-shipment" })
+        .task("ship", {
+          // inputSchema as function: maps previous step output to this step's input
+          inputSchema: (prev) => ({ orderId: prev.orderId }),
+          handler: async (input, ctx) => {
+            return await ctx.plugins.shipping.createShipment(input.orderId);
+          },
+        })
         .build(),
       workflow.branch("notification")
-        .task("notify", { job: "send-confirmation" })
+        .task("notify", {
+          inputSchema: (prev, workflowInput) => ({
+            orderId: workflowInput.orderId,
+            total: prev.total,
+          }),
+          handler: async (input, ctx) => {
+            await ctx.plugins.email.sendConfirmation(input);
+            return { sent: true };
+          },
+        })
         .build(),
     ],
     next: "complete",
   })
+  // Subsequent tasks: inputSchema as function receives prev step output
   .task("backorder", {
-    job: "create-backorder",
+    inputSchema: (prev) => ({ orderId: prev.orderId, total: prev.total }),
+    handler: async (input, ctx) => {
+      return await ctx.plugins.orders.createBackorder(input);
+    },
     next: "complete",
   })
   .pass("complete", { end: true })
@@ -82,25 +107,26 @@ ctx.core.events.on("workflow.progress", (data) => {
 
 ### Task
 
-Executes a job (in-process or external) and waits for completion.
+Executes an inline handler function with typed input/output.
 
 ```typescript
 workflow("example")
   .task("step-name", {
-    // Required: job to execute
-    job: "my-job-name",
-
-    // Optional: transform workflow context to job input
-    input: (ctx) => ({
-      orderId: ctx.input.orderId,
-      previousResult: ctx.steps.previousStep,
-    }),
-
-    // Optional: transform job result to step output
-    output: (result, ctx) => ({
-      processed: true,
-      data: result.data,
-    }),
+    // Input: Zod schema (for first step) OR mapper function (for subsequent steps)
+    // First step - validates workflow input:
+    inputSchema: z.object({ orderId: z.string() }),
+    // Subsequent steps - maps previous output to this step's input:
+    // inputSchema: (prev, workflowInput) => ({ orderId: prev.orderId }),
+
+    // Optional: Zod schema for output validation
+    outputSchema: z.object({ success: z.boolean(), data: z.any() }),
+
+    // Required: inline handler function
+    handler: async (input, ctx) => {
+      // input is typed from inputSchema
+      // ctx provides access to plugins, prev, steps, etc.
+      return { success: true, data: await processOrder(input.orderId) };
+    },
 
     // Optional: retry configuration
     retry: {
@@ -119,6 +145,58 @@ workflow("example")
   })
 ```
 
+#### Input Schema Options
+
+**Option 1: Zod Schema (first step or when validating workflow input)**
+```typescript
+.task("validate", {
+  inputSchema: z.object({ orderId: z.string(), userId: z.string() }),
+  handler: async (input, ctx) => {
+    // input: { orderId: string, userId: string } - validated from workflow input
+    return { valid: true };
+  },
+})
+```
+
+**Option 2: Mapper Function (subsequent steps)**
+```typescript
+.task("charge", {
+  // prev = output from previous step, workflowInput = original workflow input
+  inputSchema: (prev, workflowInput) => ({
+    amount: prev.total,
+    userId: workflowInput.userId,
+  }),
+  handler: async (input, ctx) => {
+    // input: { amount: number, userId: string } - inferred from mapper return
+    return { chargeId: "ch_123" };
+  },
+})
+```
+
+#### Legacy API (Job-based)
+
+For backward compatibility, you can still use job references:
+
+```typescript
+workflow("example")
+  .task("step-name", {
+    // Job name to execute
+    job: "my-job-name",
+
+    // Optional: transform workflow context to job input
+    input: (ctx) => ({
+      orderId: ctx.input.orderId,
+      previousResult: ctx.steps.previousStep,
+    }),
+
+    // Optional: transform job result to step output
+    output: (result, ctx) => ({
+      processed: true,
+      data: result.data,
+    }),
+  })
+```
+
 ### Parallel
 
 Runs multiple workflow branches concurrently.
@@ -219,6 +297,9 @@ interface WorkflowContext {
   /** Results from completed steps (keyed by step name) */
   steps: Record<string, any>;
 
+  /** Output from the previous step (undefined for first step) */
+  prev?: any;
+
   /** Current workflow instance */
   instance: WorkflowInstance;
 
@@ -230,18 +311,17 @@ interface WorkflowContext {
 Example usage in step configuration:
 
 ```typescript
+// Using inputSchema mapper function (recommended)
 .task("process", {
-  job: "process-data",
-  input: (ctx) => ({
-    // Access original input
-    orderId: ctx.input.orderId,
-
-    // Access previous step output
-    validationResult: ctx.steps.validate,
-
-    // Type-safe access
-    amount: ctx.getStepResult<{ amount: number }>("calculate")?.amount,
+  inputSchema: (prev, workflowInput) => ({
+    orderId: workflowInput.orderId,
+    validationResult: prev,  // prev = output from previous step
   }),
+  handler: async (input, ctx) => {
+    // Access any step's output
+    const calcResult = ctx.getStepResult<{ amount: number }>("calculate");
+    return { processed: true, amount: calcResult?.amount };
+  },
 })
 ```
 
@@ -421,24 +501,41 @@ For this to work properly:
 
 ```typescript
 import { AppServer, workflow, createDatabase } from "@donkeylabs/server";
+import { z } from "zod";
 
-// Define workflow
+// Define workflow with inline handlers
 const onboardingWorkflow = workflow("user-onboarding")
   .timeout(86400000) // 24 hour max
   .defaultRetry({ maxAttempts: 3 })
 
+  // First step: inputSchema validates workflow input
   .task("create-account", {
-    job: "create-user-account",
-    input: (ctx) => ctx.input,
+    inputSchema: z.object({
+      email: z.string().email(),
+      name: z.string(),
+      plan: z.enum(["free", "pro", "enterprise"]),
+    }),
+    outputSchema: z.object({ userId: z.string() }),
+    handler: async (input, ctx) => {
+      const user = await ctx.plugins.users.create({
+        email: input.email,
+        name: input.name,
+      });
+      return { userId: user.id };
+    },
   })
 
+  // Subsequent steps: inputSchema maps previous output
   .task("send-welcome-email", {
-    job: "send-email",
-    input: (ctx) => ({
-      to: ctx.input.email,
-      template: "welcome",
-      userId: ctx.steps["create-account"].userId,
+    inputSchema: (prev, workflowInput) => ({
+      to: workflowInput.email,
+      template: "welcome" as const,
+      userId: prev.userId,
     }),
+    handler: async (input, ctx) => {
+      await ctx.plugins.email.send(input);
+      return { sent: true };
+    },
   })
 
   .choice("check-plan", {
@@ -452,14 +549,24 @@ const onboardingWorkflow = workflow("user-onboarding")
   })
 
   .task("enterprise-setup", {
-    job: "setup-enterprise",
-    input: (ctx) => ({ userId: ctx.steps["create-account"].userId }),
+    // After a choice step, use handler to access specific step outputs
+    handler: async (input, ctx) => {
+      const userId = ctx.steps["create-account"].userId;
+      await ctx.plugins.accounts.setupEnterprise({
+        userId,
+        features: ["sso", "audit-logs", "dedicated-support"],
+      });
+      return { setup: "enterprise", userId };
+    },
     next: "complete",
   })
 
   .task("standard-setup", {
-    job: "setup-standard",
-    input: (ctx) => ({ userId: ctx.steps["create-account"].userId }),
+    handler: async (input, ctx) => {
+      const userId = ctx.steps["create-account"].userId;
+      await ctx.plugins.accounts.setupStandard({ userId });
+      return { setup: "standard", userId };
+    },
     next: "complete",
   })
 
@@ -476,19 +583,6 @@ const onboardingWorkflow = workflow("user-onboarding")
 // Setup server
 const server = new AppServer({ db: createDatabase() });
 
-// Register jobs that workflows use
-server.getCore().jobs.register("create-user-account", async (data) => {
-  // ... create user
-  return { userId: "user-123" };
-});
-
-server.getCore().jobs.register("send-email", async (data) => {
-  // ... send email
-  return { sent: true };
-});
-
-// ... register other jobs
-
 // Register workflow
 server.getCore().workflows.register(onboardingWorkflow);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/core/workflows.ts

@@ -2,7 +2,7 @@
 // Step function / state machine orchestration built on Jobs
 //
 // Supports:
-// - task: Execute a job (sync or async)
+// - task: Execute inline handler or job (sync or async)
 // - parallel: Run multiple branches concurrently
 // - choice: Conditional branching
 // - pass: Transform data / no-op
@@ -10,6 +10,11 @@
 import type { Events } from "./events";
 import type { Jobs } from "./jobs";
 import type { SSE } from "./sse";
+import type { z } from "zod";
+
+// Type helper for Zod schema inference
+type ZodSchema = z.ZodTypeAny;
+type InferZodOutput<T extends ZodSchema> = z.infer<T>;
 
 // ============================================
 // Step Types
@@ -40,14 +45,31 @@ export interface RetryConfig {
   retryOn?: string[];
 }
 
-// Task Step: Execute a job
-export interface TaskStepDefinition extends BaseStepDefinition {
+// Task Step: Execute inline handler or job
+export interface TaskStepDefinition<
+  TInput extends ZodSchema = ZodSchema,
+  TOutput extends ZodSchema = ZodSchema,
+> extends BaseStepDefinition {
   type: "task";
-  /** Job name to execute */
-  job: string;
-  /** Transform workflow context to job input */
+
+  // === NEW API: Inline handler with Zod schemas ===
+  /**
+   * Input schema (Zod) OR function that maps previous step output to input.
+   * - First task: Use Zod schema, input comes from workflow input
+   * - Subsequent tasks: Use function (prev, workflowInput) => inputShape
+   */
+  inputSchema?: TInput | ((prev: any, workflowInput: any) => InferZodOutput<TInput>);
+  /** Output schema (Zod) for runtime validation and typing */
+  outputSchema?: TOutput;
+  /** Inline handler function - receives validated input, returns output */
+  handler?: (input: InferZodOutput<TInput>, ctx: WorkflowContext) => Promise<InferZodOutput<TOutput>> | InferZodOutput<TOutput>;
+
+  // === LEGACY API: Job-based execution ===
+  /** Job name to execute (legacy - use handler instead) */
+  job?: string;
+  /** Transform workflow context to job input (legacy) */
   input?: (ctx: WorkflowContext) => any;
-  /** Transform job result to step output */
+  /** Transform job result to step output (legacy) */
   output?: (result: any, ctx: WorkflowContext) => any;
 }
 
@@ -164,6 +186,8 @@ export interface WorkflowContext {
   input: any;
   /** Results from completed steps */
   steps: Record<string, any>;
+  /** Output from the previous step (undefined for first step) */
+  prev?: any;
   /** Current workflow instance */
   instance: WorkflowInstance;
   /** Get a step result with type safety */
@@ -270,29 +294,76 @@ export class WorkflowBuilder {
     return this;
   }
 
-  /** Add a task step that executes a job */
-  task(
+  /**
+   * Add a task step with inline handler (recommended) or job reference.
+   *
+   * @example
+   * // New API with inline handler and Zod schemas
+   * .task("validate", {
+   *   inputSchema: z.object({ orderId: z.string() }),
+   *   outputSchema: z.object({ valid: z.boolean(), total: z.number() }),
+   *   handler: async (input, ctx) => {
+   *     return { valid: true, total: 99.99 };
+   *   },
+   * })
+   *
+   * // Using input mapper from previous step
+   * .task("charge", {
+   *   inputSchema: (prev) => ({ amount: prev.total }),
+   *   outputSchema: z.object({ chargeId: z.string() }),
+   *   handler: async (input, ctx) => {
+   *     return { chargeId: "ch_123" };
+   *   },
+   * })
+   *
+   * // Legacy API (still supported)
+   * .task("process", { job: "process-order" })
+   */
+  task<TInput extends ZodSchema = ZodSchema, TOutput extends ZodSchema = ZodSchema>(
     name: string,
-    config: {
-      job: string;
-      input?: (ctx: WorkflowContext) => any;
-      output?: (result: any, ctx: WorkflowContext) => any;
-      retry?: RetryConfig;
-      timeout?: number;
-      next?: string;
-      end?: boolean;
-    }
+    config:
+      | {
+          // New API: Inline handler with typed schemas
+          inputSchema?: TInput | ((prev: any, workflowInput: any) => InferZodOutput<TInput>);
+          outputSchema?: TOutput;
+          handler: (
+            input: InferZodOutput<TInput>,
+            ctx: WorkflowContext
+          ) => Promise<InferZodOutput<TOutput>> | InferZodOutput<TOutput>;
+          retry?: RetryConfig;
+          timeout?: number;
+          next?: string;
+          end?: boolean;
+        }
+      | {
+          // Legacy API: Job reference
+          job: string;
+          input?: (ctx: WorkflowContext) => any;
+          output?: (result: any, ctx: WorkflowContext) => any;
+          retry?: RetryConfig;
+          timeout?: number;
+          next?: string;
+          end?: boolean;
+        }
   ): this {
-    const step: TaskStepDefinition = {
+    // Determine which API is being used
+    const isNewApi = "handler" in config;
+
+    const step: TaskStepDefinition<TInput, TOutput> = {
       name,
       type: "task",
-      job: config.job,
-      input: config.input,
-      output: config.output,
       retry: config.retry,
       timeout: config.timeout,
       next: config.next,
       end: config.end,
+      // New API fields
+      inputSchema: isNewApi ? (config as any).inputSchema : undefined,
+      outputSchema: isNewApi ? (config as any).outputSchema : undefined,
+      handler: isNewApi ? (config as any).handler : undefined,
+      // Legacy API fields
+      job: !isNewApi ? (config as any).job : undefined,
+      input: !isNewApi ? (config as any).input : undefined,
+      output: !isNewApi ? (config as any).output : undefined,
     };
 
     this.addStep(step);
@@ -623,7 +694,7 @@ class WorkflowsImpl implements Workflows {
     }
 
     // Build context
-    const ctx = this.buildContext(instance);
+    const ctx = this.buildContext(instance, definition);
 
     // Emit step started event
     await this.emitEvent("workflow.step.started", {
@@ -676,37 +747,93 @@ class WorkflowsImpl implements Workflows {
     ctx: WorkflowContext,
     definition: WorkflowDefinition
   ): Promise<any> {
-    if (!this.jobs) {
-      throw new Error("Jobs service not configured");
-    }
+    // Determine which API is being used
+    const useInlineHandler = !!step.handler;
 
-    // Prepare job input
-    const jobInput = step.input ? step.input(ctx) : ctx.input;
+    if (useInlineHandler) {
+      // === NEW API: Inline handler with Zod schemas ===
+      let input: any;
 
-    // Update step with input
-    const instance = await this.adapter.getInstance(instanceId);
-    if (instance) {
-      const stepResult = instance.stepResults[step.name];
-      if (stepResult) {
-        stepResult.input = jobInput;
-        await this.adapter.updateInstance(instanceId, {
-          stepResults: { ...instance.stepResults, [step.name]: stepResult },
-        });
+      if (step.inputSchema) {
+        if (typeof step.inputSchema === "function") {
+          // inputSchema is a mapper function: (prev, workflowInput) => input
+          input = step.inputSchema(ctx.prev, ctx.input);
+        } else {
+          // inputSchema is a Zod schema - validate workflow input
+          const parseResult = step.inputSchema.safeParse(ctx.input);
+          if (!parseResult.success) {
+            throw new Error(`Input validation failed: ${parseResult.error.message}`);
+          }
+          input = parseResult.data;
+        }
+      } else {
+        // No input schema, use workflow input directly
+        input = ctx.input;
       }
-    }
 
-    // Enqueue the job
-    const jobId = await this.jobs.enqueue(step.job, {
-      ...jobInput,
-      _workflowInstanceId: instanceId,
-      _workflowStepName: step.name,
-    });
+      // Update step with input
+      const instance = await this.adapter.getInstance(instanceId);
+      if (instance) {
+        const stepResult = instance.stepResults[step.name];
+        if (stepResult) {
+          stepResult.input = input;
+          await this.adapter.updateInstance(instanceId, {
+            stepResults: { ...instance.stepResults, [step.name]: stepResult },
+          });
+        }
+      }
+
+      // Execute the inline handler
+      let result = await step.handler!(input, ctx);
 
-    // Wait for job completion
-    const result = await this.waitForJob(jobId, step.timeout);
+      // Validate output if schema provided
+      if (step.outputSchema) {
+        const parseResult = step.outputSchema.safeParse(result);
+        if (!parseResult.success) {
+          throw new Error(`Output validation failed: ${parseResult.error.message}`);
+        }
+        result = parseResult.data;
+      }
+
+      return result;
+    } else {
+      // === LEGACY API: Job-based execution ===
+      if (!this.jobs) {
+        throw new Error("Jobs service not configured");
+      }
+
+      if (!step.job) {
+        throw new Error("Task step requires either 'handler' or 'job'");
+      }
+
+      // Prepare job input
+      const jobInput = step.input ? step.input(ctx) : ctx.input;
+
+      // Update step with input
+      const instance = await this.adapter.getInstance(instanceId);
+      if (instance) {
+        const stepResult = instance.stepResults[step.name];
+        if (stepResult) {
+          stepResult.input = jobInput;
+          await this.adapter.updateInstance(instanceId, {
+            stepResults: { ...instance.stepResults, [step.name]: stepResult },
+          });
+        }
+      }
+
+      // Enqueue the job
+      const jobId = await this.jobs.enqueue(step.job, {
+        ...jobInput,
+        _workflowInstanceId: instanceId,
+        _workflowStepName: step.name,
+      });
+
+      // Wait for job completion
+      const result = await this.waitForJob(jobId, step.timeout);
 
-    // Transform output if needed
-    return step.output ? step.output(result, ctx) : result;
+      // Transform output if needed
+      return step.output ? step.output(result, ctx) : result;
+    }
   }
 
   private async waitForJob(jobId: string, timeout?: number): Promise<any> {
@@ -930,7 +1057,7 @@ class WorkflowsImpl implements Workflows {
     return ctx.input;
   }
 
-  private buildContext(instance: WorkflowInstance): WorkflowContext {
+  private buildContext(instance: WorkflowInstance, definition: WorkflowDefinition): WorkflowContext {
     // Build steps object with outputs
     const steps: Record<string, any> = {};
     for (const [name, result] of Object.entries(instance.stepResults)) {
@@ -939,9 +1066,35 @@ class WorkflowsImpl implements Workflows {
       }
     }
 
+    // Find the previous step's output by tracing the workflow path
+    let prev: any = undefined;
+    if (instance.currentStep) {
+      // Find which step comes before current step
+      for (const [stepName, stepDef] of definition.steps) {
+        if (stepDef.next === instance.currentStep && steps[stepName] !== undefined) {
+          prev = steps[stepName];
+          break;
+        }
+      }
+      // If no explicit next found, use most recent completed step output
+      if (prev === undefined) {
+        const completedSteps = Object.entries(instance.stepResults)
+          .filter(([, r]) => r.status === "completed" && r.output !== undefined)
+          .sort((a, b) => {
+            const aTime = a[1].completedAt?.getTime() ?? 0;
+            const bTime = b[1].completedAt?.getTime() ?? 0;
+            return bTime - aTime;
+          });
+        if (completedSteps.length > 0) {
+          prev = completedSteps[0][1].output;
+        }
+      }
+    }
+
     return {
       input: instance.input,
       steps,
+      prev,
       instance,
       getStepResult: <T = any>(stepName: string): T | undefined => {
         return steps[stepName] as T | undefined;