@sonamu-kit/tasks 0.0.1

package/src/client.test.ts

@@ -0,0 +1,297 @@
+import { randomUUID } from "node:crypto";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { BackendPostgres } from ".";
+import { declareWorkflow, OpenWorkflow } from "./client";
+import { KNEX_GLOBAL_CONFIG } from "./testing/connection";
+
+describe("OpenWorkflow", () => {
+  let backend: BackendPostgres;
+
+  beforeEach(async () => {
+    backend = await BackendPostgres.connect(KNEX_GLOBAL_CONFIG, {
+      namespaceId: randomUUID(),
+      runMigrations: false,
+    });
+  });
+
+  afterEach(async () => {
+    await backend.stop();
+  });
+
+  test("enqueues workflow runs via backend", async () => {
+    const client = new OpenWorkflow({ backend });
+
+    const workflow = client.defineWorkflow({ name: "enqueue-test" }, noopFn);
+    await workflow.run({ docUrl: "https://example.com" });
+
+    const workerId = "enqueue-worker";
+    const claimed = await backend.claimWorkflowRun({
+      workerId,
+      leaseDurationMs: 1000,
+    });
+
+    expect(claimed?.workflowName).toBe("enqueue-test");
+    expect(claimed?.workerId).toBe(workerId);
+    expect(claimed?.input).toEqual({ docUrl: "https://example.com" });
+  });
+
+  describe("schema validation", () => {
+    describe("Zod schema", () => {
+      const schema = z.object({
+        userId: z.uuid(),
+        count: z.number().int().positive(),
+      });
+
+      test("accepts valid input", async () => {
+        const client = new OpenWorkflow({ backend });
+        const workflow = client.defineWorkflow({ name: "schema-zod-valid", schema }, noopFn);
+
+        const handle = await workflow.run({
+          userId: randomUUID(),
+          count: 3,
+        });
+
+        await handle.cancel();
+      });
+
+      test("rejects invalid input", async () => {
+        const client = new OpenWorkflow({ backend });
+        const workflow = client.defineWorkflow({ name: "schema-zod-invalid", schema }, noopFn);
+
+        await expect(workflow.run({ userId: "not-a-uuid", count: 0 } as never)).rejects.toThrow();
+      });
+    });
+  });
+
+  test("result resolves when workflow succeeds", async () => {
+    const client = new OpenWorkflow({ backend });
+
+    const workflow = client.defineWorkflow({ name: "result-success" }, noopFn);
+    const handle = await workflow.run({ value: 1 });
+
+    const workerId = "test-worker";
+    const claimed = await backend.claimWorkflowRun({
+      workerId,
+      leaseDurationMs: 1000,
+    });
+    expect(claimed).not.toBeNull();
+    if (!claimed) throw new Error("workflow run was not claimed");
+
+    await backend.completeWorkflowRun({
+      workflowRunId: claimed.id,
+      workerId,
+      output: { ok: true },
+    });
+
+    // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+    const result = await handle.result();
+    expect(result).toEqual({ ok: true });
+  });
+
+  test("result rejects when workflow fails", async () => {
+    const client = new OpenWorkflow({ backend });
+
+    const workflow = client.defineWorkflow({ name: "result-failure" }, noopFn);
+    await workflow.run({ value: 1 });
+
+    const workerId = "test-worker";
+    const claimed = await backend.claimWorkflowRun({
+      workerId,
+      leaseDurationMs: 1000,
+    });
+    expect(claimed).not.toBeNull();
+    if (!claimed) throw new Error("workflow run was not claimed");
+
+    // mark as failed (should reschedule))
+    await backend.failWorkflowRun({
+      workflowRunId: claimed.id,
+      workerId,
+      error: { message: "boom" },
+    });
+
+    const rescheduled = await backend.getWorkflowRun({
+      workflowRunId: claimed.id,
+    });
+    expect(rescheduled?.status).toBe("pending");
+    expect(rescheduled?.error).toEqual({ message: "boom" });
+  });
+
+  test("creates workflow run with deadline", async () => {
+    const client = new OpenWorkflow({ backend });
+
+    const workflow = client.defineWorkflow({ name: "deadline-test" }, noopFn);
+    const deadline = new Date(Date.now() + 60_000); // in 1 minute
+    const handle = await workflow.run({ value: 1 }, { deadlineAt: deadline });
+
+    expect(handle.workflowRun.deadlineAt).not.toBeNull();
+    expect(handle.workflowRun.deadlineAt?.getTime()).toBe(deadline.getTime());
+  });
+
+  test("creates workflow run with version", async () => {
+    const client = new OpenWorkflow({ backend });
+
+    const workflow = client.defineWorkflow({ name: "versioned-test", version: "v2.0" }, noopFn);
+    const handle = await workflow.run({ value: 1 });
+
+    expect(handle.workflowRun.version).toBe("v2.0");
+  });
+
+  test("creates workflow run without version", async () => {
+    const client = new OpenWorkflow({ backend });
+
+    const workflow = client.defineWorkflow({ name: "unversioned-test" }, noopFn);
+    const handle = await workflow.run({ value: 1 });
+
+    expect(handle.workflowRun.version).toBeNull();
+  });
+
+  test("cancels workflow run via handle", async () => {
+    const client = new OpenWorkflow({ backend });
+
+    const workflow = client.defineWorkflow({ name: "cancel-test" }, noopFn);
+    const handle = await workflow.run({ value: 1 });
+
+    await handle.cancel();
+
+    const workflowRun = await backend.getWorkflowRun({
+      workflowRunId: handle.workflowRun.id,
+    });
+    expect(workflowRun?.status).toBe("canceled");
+    expect(workflowRun?.finishedAt).not.toBeNull();
+  });
+
+  describe("declareWorkflow / implementWorkflow API", () => {
+    test("declareWorkflow returns a spec that can be used to schedule runs", async () => {
+      const client = new OpenWorkflow({ backend });
+
+      const spec = declareWorkflow({ name: "declare-test" });
+
+      const handle = await client.runWorkflow(spec, { message: "hello" });
+      expect(handle.workflowRun.workflowName).toBe("declare-test");
+
+      await handle.cancel();
+    });
+
+    test("implementWorkflow registers the workflow for worker execution", async () => {
+      const client = new OpenWorkflow({ backend });
+
+      const spec = declareWorkflow({ name: "implement-test" });
+      client.implementWorkflow(spec, ({ input }) => {
+        return { received: input };
+      });
+
+      const handle = await client.runWorkflow(spec, { data: 42 });
+      const worker = client.newWorker();
+      await worker.tick();
+      await sleep(100); // wait for background execution
+
+      const result = await handle.result();
+      expect(result).toEqual({ received: { data: 42 } });
+    });
+
+    test("implementWorkflow throws when workflow is already registered", async () => {
+      const client = new OpenWorkflow({ backend });
+
+      const spec = declareWorkflow({ name: "duplicate-test" });
+      client.implementWorkflow(spec, noopFn);
+
+      expect(() => {
+        client.implementWorkflow(spec, noopFn);
+      }).toThrow('Workflow "duplicate-test" is already registered');
+    });
+
+    test("implementWorkflow allows registering different versions of the same workflow", async () => {
+      const client = new OpenWorkflow({ backend });
+
+      const specV1 = declareWorkflow({
+        name: "multi-version",
+        version: "v1",
+      });
+      const specV2 = declareWorkflow({
+        name: "multi-version",
+        version: "v2",
+      });
+
+      // no throwing...
+      client.implementWorkflow(specV1, noopFn);
+      client.implementWorkflow(specV2, noopFn);
+    });
+
+    test("implementWorkflow throws for same name+version combination", async () => {
+      const client = new OpenWorkflow({ backend });
+
+      const spec1 = declareWorkflow({
+        name: "version-duplicate",
+        version: "v1",
+      });
+      const spec2 = declareWorkflow({
+        name: "version-duplicate",
+        version: "v1",
+      });
+
+      client.implementWorkflow(spec1, noopFn);
+
+      expect(() => {
+        client.implementWorkflow(spec2, noopFn);
+      }).toThrow('Workflow "version-duplicate" (version: v1) is already registered');
+    });
+
+    test("declareWorkflow with schema validates input on runWorkflow", async () => {
+      const client = new OpenWorkflow({ backend });
+
+      const schema = z.object({
+        email: z.email(),
+      });
+      const spec = declareWorkflow({
+        name: "declare-schema-test",
+        schema,
+      });
+
+      const handle = await client.runWorkflow(spec, {
+        email: "test@example.com",
+      });
+      await handle.cancel();
+
+      await expect(client.runWorkflow(spec, { email: "not-an-email" })).rejects.toThrow();
+    });
+
+    test("declareWorkflow with version sets version on workflow run", async () => {
+      const client = new OpenWorkflow({ backend });
+
+      const spec = declareWorkflow({
+        name: "declare-version-test",
+        version: "v1.2.3",
+      });
+
+      const handle = await client.runWorkflow(spec);
+      expect(handle.workflowRun.version).toBe("v1.2.3");
+
+      await handle.cancel();
+    });
+
+    test("defineWorkflow wraps declareWorkflow and implementWorkflow", async () => {
+      const client = new OpenWorkflow({ backend });
+
+      const workflow = client.defineWorkflow({ name: "define-wrap-test" }, ({ input }) => ({
+        doubled: (input as { n: number }).n * 2,
+      }));
+
+      const handle = await workflow.run({ n: 21 });
+      const worker = client.newWorker();
+      await worker.tick();
+      await sleep(100); // wait for background execution
+
+      const result = await handle.result();
+      expect(result).toEqual({ doubled: 42 });
+    });
+  });
+});
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function noopFn() {
+  // no-op
+}

package/src/client.ts

@@ -0,0 +1,331 @@
+import type { Backend } from "./backend";
+import type { StandardSchemaV1 } from "./core/schema";
+import type { SchemaInput, SchemaOutput, WorkflowRun } from "./core/workflow";
+import { validateInput } from "./core/workflow";
+import type { WorkflowFunction } from "./execution";
+import { WorkflowRegistry } from "./registry";
+import { Worker, type WorkerOptions } from "./worker";
+import { defineWorkflow, defineWorkflowSpec, type Workflow, type WorkflowSpec } from "./workflow";
+
+const DEFAULT_RESULT_POLL_INTERVAL_MS = 1000; // 1s
+const DEFAULT_RESULT_TIMEOUT_MS = 5 * 60 * 1000; // 5m
+
+/* The data the worker function receives (after transformation). */
+type WorkflowHandlerInput<TSchema, Input> = SchemaOutput<TSchema, Input>;
+
+/* The data the client sends (before transformation) */
+type WorkflowRunInput<TSchema, Input> = SchemaInput<TSchema, Input>;
+
+/**
+ * Options for the OpenWorkflow client.
+ */
+export interface OpenWorkflowOptions {
+  backend: Backend;
+}
+
+/**
+ * Client used to register workflows and start runs.
+ */
+export class OpenWorkflow {
+  private backend: Backend;
+  private registry = new WorkflowRegistry();
+
+  constructor(options: OpenWorkflowOptions) {
+    this.backend = options.backend;
+  }
+
+  /**
+   * Create a new Worker with this client's backend and workflows.
+   * @param options - Worker options
+   * @param options.concurrency - Max concurrent workflow runs
+   * @returns Worker instance
+   */
+  newWorker(options?: {
+    concurrency?: number | undefined;
+    usePubSub?: boolean;
+    listenDelay?: number;
+  }): Worker {
+    return new Worker({
+      backend: this.backend,
+      registry: this.registry,
+      concurrency: options?.concurrency,
+      usePubSub: options?.usePubSub,
+      listenDelay: options?.listenDelay,
+    } satisfies WorkerOptions);
+  }
+
+  /**
+   * Provide the implementation for a declared workflow. This links the workflow
+   * specification to its execution logic and registers it with this
+   * OpenWorkflow instance for worker execution.
+   * @param spec - Workflow spec
+   * @param fn - Workflow implementation
+   */
+  implementWorkflow<Input, Output, RunInput = Input>(
+    spec: WorkflowSpec<Input, Output, RunInput>,
+    fn: WorkflowFunction<Input, Output>,
+  ): void {
+    const workflow: Workflow<Input, Output, RunInput> = { spec, fn };
+    this.registry.register(workflow as Workflow<unknown, unknown, unknown>);
+  }
+
+  /**
+   * Run a workflow from its specification. This is the primary way to schedule
+   * a workflow using only its WorkflowSpec.
+   * @param spec - Workflow spec
+   * @param input - Workflow input
+   * @param options - Run options
+   * @returns Handle for awaiting the result
+   * @example
+   * ```ts
+   * const handle = await ow.runWorkflow(emailWorkflow, { to: 'user@example.com' });
+   * const result = await handle.result();
+   * ```
+   */
+  async runWorkflow<Input, Output, RunInput = Input>(
+    spec: WorkflowSpec<Input, Output, RunInput>,
+    input?: RunInput,
+    options?: WorkflowRunOptions,
+  ): Promise<WorkflowRunHandle<Output>> {
+    const validationResult = await validateInput(spec.schema, input);
+    if (!validationResult.success) {
+      throw new Error(validationResult.error);
+    }
+    const parsedInput = validationResult.value;
+    const workflowRun = await this.backend.createWorkflowRun({
+      workflowName: spec.name,
+      version: spec.version ?? null,
+      idempotencyKey: null,
+      config: {},
+      context: null,
+      input: parsedInput ?? null,
+      availableAt: null,
+      deadlineAt: options?.deadlineAt ?? null,
+    });
+
+    if (options?.publishToChannel) {
+      await this.backend.publish(workflowRun.id);
+    }
+
+    return new WorkflowRunHandle<Output>({
+      backend: this.backend,
+      workflowRun: workflowRun,
+      resultPollIntervalMs: DEFAULT_RESULT_POLL_INTERVAL_MS,
+      resultTimeoutMs: DEFAULT_RESULT_TIMEOUT_MS,
+    });
+  }
+
+  /**
+   * Define and register a new workflow.
+   *
+   * This is a convenience method that combines `declareWorkflow` and
+   * `implementWorkflow` into a single call. For better code splitting and to
+   * separate declaration from implementation, consider using those methods
+   * separately.
+   * @param config - Workflow config
+   * @param fn - Workflow implementation
+   * @returns Runnable workflow
+   * @example
+   * ```ts
+   * const workflow = ow.defineWorkflow(
+   *   { name: 'my-workflow' },
+   *   async ({ input, step }) => {
+   *     // workflow implementation
+   *   },
+   * );
+   * ```
+   */
+  defineWorkflow<Input, Output, TSchema extends StandardSchemaV1 | undefined = undefined>(
+    spec: WorkflowSpec<
+      WorkflowHandlerInput<TSchema, Input>,
+      Output,
+      WorkflowRunInput<TSchema, Input>
+    >,
+    fn: WorkflowFunction<WorkflowHandlerInput<TSchema, Input>, Output>,
+  ): RunnableWorkflow<
+    WorkflowHandlerInput<TSchema, Input>,
+    Output,
+    WorkflowRunInput<TSchema, Input>
+  > {
+    const workflow = defineWorkflow(spec, fn);
+    this.registry.register(workflow as Workflow<unknown, unknown, unknown>);
+    return new RunnableWorkflow(this, workflow);
+  }
+
+  /**
+   * Unregister a workflow from the registry.
+   * @param name - The workflow name
+   * @param version - The workflow version (null for unversioned)
+   * @example
+   * ```ts
+   * ow.unregisterWorkflow("my-workflow", "v1");
+   * ```
+   */
+  unregisterWorkflow(name: string, version: string | null): void {
+    this.registry.remove(name, version);
+  }
+
+  /**
+   * Check if a workflow is registered in the registry.
+   * @param name - The workflow name
+   * @param version - The workflow version (null for unversioned)
+   * @returns True if the workflow is registered, false otherwise
+   * @example
+   * ```ts
+   * ow.isWorkflowRegistered("my-workflow", "v1");
+   * ```
+   */
+  isWorkflowRegistered(name: string, version: string | null): boolean {
+    return this.registry.has(name, version);
+  }
+}
+
+/**
+ * Declare a workflow without providing its implementation (which is provided
+ * separately via `implementWorkflow`). Returns a lightweight WorkflowSpec
+ * that can be used to schedule workflow runs.
+ * @param config - Workflow config
+ * @param spec - Workflow spec
+ * @returns Workflow spec
+ * @example
+ * ```ts
+ * export const emailWorkflow = declareWorkflow({
+ *   name: 'send-email',
+ *   schema: z.object({ to: z.string().email() }),
+ * });
+ * ```
+ */
+// kept for backwards compatibility, to be deprecated
+// eslint-disable-next-line unicorn/prefer-export-from
+export const declareWorkflow = defineWorkflowSpec;
+
+//
+// --- Workflow Definition
+//
+
+/**
+ * A fully defined workflow with its implementation. This class is returned by
+ * `defineWorkflow` and provides the `.run()` method for scheduling workflow
+ * runs.
+ */
+export class RunnableWorkflow<Input, Output, RunInput = Input> {
+  private readonly ow: OpenWorkflow;
+  readonly workflow: Workflow<Input, Output, RunInput>;
+
+  constructor(ow: OpenWorkflow, workflow: Workflow<Input, Output, RunInput>) {
+    this.ow = ow;
+    this.workflow = workflow;
+  }
+
+  /**
+   * Starts a new workflow run.
+   * @param input - Workflow input
+   * @param options - Run options
+   * @returns Workflow run handle
+   */
+  async run(input?: RunInput, options?: WorkflowRunOptions): Promise<WorkflowRunHandle<Output>> {
+    return this.ow.runWorkflow(this.workflow.spec, input, options);
+  }
+}
+
+//
+// --- Workflow Run
+//
+
+/**
+ * Options for creating a new workflow run from a runnable workflow when calling
+ * `workflow.run()`.
+ */
+export interface WorkflowRunOptions {
+  /**
+   * Set a deadline for the workflow run. If the workflow exceeds this deadline,
+   * it will be marked as failed.
+   */
+  deadlineAt?: Date;
+
+  /**
+   * Publish when the workflow run is created to the channel.
+   * Default: true
+   */
+  publishToChannel?: boolean;
+}
+
+/**
+ * Options for WorkflowHandle.
+ */
+export interface WorkflowHandleOptions {
+  backend: Backend;
+  workflowRun: WorkflowRun;
+  resultPollIntervalMs: number;
+  resultTimeoutMs: number;
+}
+
+/**
+ * Represents a started workflow run and provides methods to await its result.
+ * Returned from `workflowDef.run()`.
+ */
+export class WorkflowRunHandle<Output> {
+  private backend: Backend;
+  readonly workflowRun: WorkflowRun;
+  private resultPollIntervalMs: number;
+  private resultTimeoutMs: number;
+
+  constructor(options: WorkflowHandleOptions) {
+    this.backend = options.backend;
+    this.workflowRun = options.workflowRun;
+    this.resultPollIntervalMs = options.resultPollIntervalMs;
+    this.resultTimeoutMs = options.resultTimeoutMs;
+  }
+
+  /**
+   * Waits for the workflow run to complete and returns the result.
+   * @returns Workflow output
+   */
+  async result(): Promise<Output> {
+    const start = Date.now();
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+      const latest = await this.backend.getWorkflowRun({
+        workflowRunId: this.workflowRun.id,
+      });
+
+      if (!latest) {
+        throw new Error(`Workflow run ${this.workflowRun.id} no longer exists`);
+      }
+
+      // 'succeeded' status is deprecated
+      if (latest.status === "succeeded" || latest.status === "completed") {
+        return latest.output as Output;
+      }
+
+      if (latest.status === "failed") {
+        throw new Error(
+          `Workflow ${this.workflowRun.workflowName} failed: ${JSON.stringify(latest.error)}`,
+        );
+      }
+
+      if (latest.status === "canceled") {
+        throw new Error(`Workflow ${this.workflowRun.workflowName} was canceled`);
+      }
+
+      if (Date.now() - start > this.resultTimeoutMs) {
+        throw new Error(`Timed out waiting for workflow run ${this.workflowRun.id} to finish`);
+      }
+
+      await new Promise((resolve) => {
+        setTimeout(resolve, this.resultPollIntervalMs);
+      });
+    }
+  }
+
+  /**
+   * Cancels the workflow run. Only workflows in pending, running, or sleeping
+   * status can be canceled.
+   */
+  async cancel(): Promise<void> {
+    await this.backend.cancelWorkflowRun({
+      workflowRunId: this.workflowRun.id,
+    });
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "vitest";
+import { defineConfig } from "./config";
+import { createBackend } from "./testing/connection";
+
+describe("defineConfig", async () => {
+  const backend = await createBackend();
+
+  test("returns the same config", () => {
+    const config = { backend };
+    const result = defineConfig(config);
+    expect(result).toBe(config);
+  });
+});
+
+describe("loadConfig", () => {
+  test("loads config file in the specified directory", async () => {
+    const { loadConfig } = await import("./config");
+    const { config, configFile } = await loadConfig("./templates");
+    expect(config).toBeDefined();
+    expect(config.backend).toBeDefined();
+    expect(configFile).toContain("/templates/openworkflow.config.ts");
+  });
+});

package/src/config.ts

@@ -0,0 +1,35 @@
+import { loadConfig as loadC12Config } from "c12";
+import type { Backend } from "./backend";
+import type { WorkerOptions } from "./worker";
+
+export interface OpenWorkflowConfig {
+  backend: Backend;
+  worker?: WorkerConfig;
+}
+
+export type WorkerConfig = Pick<WorkerOptions, "concurrency">;
+
+/**
+ * Create a typed OpenWorkflow configuration.
+ * @param config - the config
+ * @returns the config
+ */
+export function defineConfig(config: OpenWorkflowConfig): OpenWorkflowConfig {
+  return config;
+}
+
+/**
+ * Load the OpenWorkflow config at openworkflow.config.ts (or other extension;
+ * see https://github.com/unjs/c12)
+ * @param rootDir - Optional root directory to search from (defaults to
+ * process.cwd())
+ * @returns The loaded configuration and metadata
+ */
+export async function loadConfig(rootDir?: string) {
+  const cwd = rootDir ?? process.cwd();
+
+  return await loadC12Config<OpenWorkflowConfig>({
+    cwd,
+    name: "openworkflow",
+  });
+}