@donkeylabs/server 0.4.8 → 0.5.1

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;

package/src/core.ts

@@ -1,4 +1,4 @@
-import type { Kysely } from "kysely";
+import { sql, type Kysely } from "kysely";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import type { z } from "zod";
@@ -355,8 +355,53 @@ export class PluginManager {
     this.plugins.set(plugin.name, plugin);
   }
 
+  /**
+   * Ensures the migrations tracking table exists.
+   * This table tracks which migrations have been applied for each plugin.
+   */
+  private async ensureMigrationsTable(): Promise<void> {
+    await this.core.db.schema
+      .createTable("__donkeylabs_migrations__")
+      .ifNotExists()
+      .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+      .addColumn("plugin_name", "text", (col) => col.notNull())
+      .addColumn("migration_name", "text", (col) => col.notNull())
+      .addColumn("executed_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`))
+      .execute();
+
+    // Create unique index for plugin_name + migration_name (if not exists)
+    // Using raw SQL since Kysely doesn't have ifNotExists for indexes
+    await sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_migrations_unique
+              ON __donkeylabs_migrations__(plugin_name, migration_name)`.execute(this.core.db);
+  }
+
+  /**
+   * Checks if a migration has already been applied for a specific plugin.
+   */
+  private async isMigrationApplied(pluginName: string, migrationName: string): Promise<boolean> {
+    const result = await sql<{ count: number }>`
+      SELECT COUNT(*) as count FROM __donkeylabs_migrations__
+      WHERE plugin_name = ${pluginName} AND migration_name = ${migrationName}
+    `.execute(this.core.db);
+    return (result.rows[0]?.count ?? 0) > 0;
+  }
+
+  /**
+   * Records that a migration has been applied for a specific plugin.
+   */
+  private async recordMigration(pluginName: string, migrationName: string): Promise<void> {
+    await sql`
+      INSERT INTO __donkeylabs_migrations__ (plugin_name, migration_name)
+      VALUES (${pluginName}, ${migrationName})
+    `.execute(this.core.db);
+  }
+
   async migrate(): Promise<void> {
     console.log("Running migrations (File-System Based)...");
+
+    // Ensure the migrations tracking table exists
+    await this.ensureMigrationsTable();
+
     const sortedPlugins = this.resolveOrder();
 
     for (const plugin of sortedPlugins) {
@@ -392,22 +437,46 @@ export class PluginManager {
                  console.log(`[Migration] checking plugin: ${pluginName} at ${migrationDir}`);
 
                  for (const file of migrationFiles.sort()) {
+                     // Check if this migration has already been applied
+                     const isApplied = await this.isMigrationApplied(pluginName, file);
+                     if (isApplied) {
+                         console.log(`  - Skipping (already applied): ${file}`);
+                         continue;
+                     }
+
                      console.log(`  - Executing migration: ${file}`);
                      const migrationPath = join(migrationDir, file);
-                     const migration = await import(migrationPath);
+
+                     let migration;
+                     try {
+                         migration = await import(migrationPath);
+                     } catch (importError) {
+                         const err = importError instanceof Error ? importError : new Error(String(importError));
+                         throw new Error(`Failed to import migration ${file}: ${err.message}`);
+                     }
 
                      if (migration.up) {
                          try {
                               await migration.up(this.core.db);
+                              // Record successful migration
+                              await this.recordMigration(pluginName, file);
                               console.log(`    Success`);
                          } catch (e) {
                              console.error(`    Failed to run ${file}:`, e);
+                             throw e; // Stop on migration failure - don't continue with inconsistent state
                          }
                      }
                  }
              }
-        } catch {
-            // Migration directory doesn't exist, skip
+        } catch (e) {
+            // Re-throw migration execution errors (they've already been logged)
+            // Only silently catch directory read errors (ENOENT)
+            const isDirectoryError = e instanceof Error &&
+              ((e as NodeJS.ErrnoException).code === 'ENOENT' ||
+               (e as NodeJS.ErrnoException).code === 'ENOTDIR');
+            if (!isDirectoryError) {
+                throw e;
+            }
         }
     }
   }

package/src/index.ts

@@ -45,6 +45,7 @@ export {
   type InferHandlers,
   type InferMiddleware,
   type InferDependencies,
+  type EventSchemas,
 } from "./core";
 
 // Middleware
@@ -72,3 +73,14 @@ export function defineConfig(config: DonkeylabsConfig): DonkeylabsConfig {
 
 // Re-export HttpError for custom error creation
 export { HttpError } from "./core/errors";
+
+// Workflows (step functions)
+export {
+  workflow,
+  WorkflowBuilder,
+  type WorkflowDefinition,
+  type WorkflowInstance,
+  type WorkflowStatus,
+  type WorkflowContext,
+  type Workflows,
+} from "./core/workflows";