@sonamu-kit/tasks 0.0.1

package/.swcrc

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://swc.rs/schema.json",
+  "module": {
+    "type": "es6", // import/export 쓰는 esm으로 가겠습니다.
+    "resolveFully": true // esm이 요구하는 대로, 임포트 경로를 실제 파일 경로(확장자 포함)로 풀어줍니다.
+  },
+  "jsc": {
+    "parser": {
+      "syntax": "typescript",
+      "decorators": true
+    },
+    "baseUrl": ".", // 위 resolveFully 옵션이 작동하려면 이게 필요합니다. 이 파일이 있는 로컬에서 쉘에 직접 실행할 때에는 baseUrl에 이 파일이 위치한 경로 기준으로 절대경로가 resolve되어 들어갑니다. 그러나 만약 swc를 코드 상에서 import해서 쓰거나, 아니면 설정 파일(.swcrc) 대신 -C로 설정을 명령줄에 직접 넘기는 경우, baseUrl에 직접 올바른 절대경로를 넣어주어야 합니다.
+    "target": "esnext" // 타겟은 그냥 최신 문법으로.
+  },
+  "minify": false, // 어차피 용량 10%정도 차이밖에 안 남. minify를 끄면 혹시 혹시 정말 혹시나 나중에 소스맵 없이 코드를 봐야 하는 끔찍한 상황에 조금이나마 도움이 될 수 있지 않을까 해서 끔.
+  "sourceMaps": true // 소스맵 생성. 선언맵은 밖에서 tsc로 따로 만들거예요.
+}

package/README.md

@@ -0,0 +1,7 @@
+# Sonamu Task Queue
+
+## Q&A
+
+1. 패키지 설치 중에 에러가 납니다.
+   - `@sonamu-kit/tasks`는 성능 상의 이슈로 인해 optional dependency로 `pg-native` 패키지를 사용합니다.
+   - [`pg-native` 문서](https://github.com/brianc/node-postgres/tree/master/packages/pg-native#install)에서는 설치 전 필요한 작업에 대해 안내해주고 있습니다.

package/dist/backend.d.ts

@@ -0,0 +1,107 @@
+import type { SerializedError } from "./core/error";
+import type { JsonValue } from "./core/json";
+import type { StepAttempt, StepAttemptContext, StepKind } from "./core/step";
+import type { WorkflowRun } from "./core/workflow";
+import type { OnSubscribed } from "./database/pubsub";
+export declare const DEFAULT_NAMESPACE_ID = "default";
+/**
+ * Backend is the interface for backend providers to implement.
+ */
+export interface Backend {
+    subscribe(callback: OnSubscribed): Promise<void>;
+    publish(payload?: string): Promise<void>;
+    createWorkflowRun(params: Readonly<CreateWorkflowRunParams>): Promise<WorkflowRun>;
+    getWorkflowRun(params: Readonly<GetWorkflowRunParams>): Promise<WorkflowRun | null>;
+    listWorkflowRuns(params: Readonly<ListWorkflowRunsParams>): Promise<PaginatedResponse<WorkflowRun>>;
+    claimWorkflowRun(params: Readonly<ClaimWorkflowRunParams>): Promise<WorkflowRun | null>;
+    extendWorkflowRunLease(params: Readonly<ExtendWorkflowRunLeaseParams>): Promise<WorkflowRun>;
+    sleepWorkflowRun(params: Readonly<SleepWorkflowRunParams>): Promise<WorkflowRun>;
+    completeWorkflowRun(params: Readonly<CompleteWorkflowRunParams>): Promise<WorkflowRun>;
+    failWorkflowRun(params: Readonly<FailWorkflowRunParams>): Promise<WorkflowRun>;
+    cancelWorkflowRun(params: Readonly<CancelWorkflowRunParams>): Promise<WorkflowRun>;
+    createStepAttempt(params: Readonly<CreateStepAttemptParams>): Promise<StepAttempt>;
+    getStepAttempt(params: Readonly<GetStepAttemptParams>): Promise<StepAttempt | null>;
+    listStepAttempts(params: Readonly<ListStepAttemptsParams>): Promise<PaginatedResponse<StepAttempt>>;
+    completeStepAttempt(params: Readonly<CompleteStepAttemptParams>): Promise<StepAttempt>;
+    failStepAttempt(params: Readonly<FailStepAttemptParams>): Promise<StepAttempt>;
+}
+export interface CreateWorkflowRunParams {
+    workflowName: string;
+    version: string | null;
+    idempotencyKey: string | null;
+    config: JsonValue;
+    context: JsonValue | null;
+    input: JsonValue | null;
+    availableAt: Date | null;
+    deadlineAt: Date | null;
+}
+export interface GetWorkflowRunParams {
+    workflowRunId: string;
+}
+export type ListWorkflowRunsParams = PaginationOptions;
+export interface ClaimWorkflowRunParams {
+    workerId: string;
+    leaseDurationMs: number;
+}
+export interface ExtendWorkflowRunLeaseParams {
+    workflowRunId: string;
+    workerId: string;
+    leaseDurationMs: number;
+}
+export interface SleepWorkflowRunParams {
+    workflowRunId: string;
+    workerId: string;
+    availableAt: Date;
+}
+export interface CompleteWorkflowRunParams {
+    workflowRunId: string;
+    workerId: string;
+    output: JsonValue | null;
+}
+export interface FailWorkflowRunParams {
+    workflowRunId: string;
+    workerId: string;
+    error: SerializedError;
+}
+export interface CancelWorkflowRunParams {
+    workflowRunId: string;
+}
+export interface CreateStepAttemptParams {
+    workflowRunId: string;
+    workerId: string;
+    stepName: string;
+    kind: StepKind;
+    config: JsonValue;
+    context: StepAttemptContext | null;
+}
+export interface GetStepAttemptParams {
+    stepAttemptId: string;
+}
+export interface ListStepAttemptsParams extends PaginationOptions {
+    workflowRunId: string;
+}
+export interface CompleteStepAttemptParams {
+    workflowRunId: string;
+    stepAttemptId: string;
+    workerId: string;
+    output: JsonValue | null;
+}
+export interface FailStepAttemptParams {
+    workflowRunId: string;
+    stepAttemptId: string;
+    workerId: string;
+    error: SerializedError;
+}
+export interface PaginationOptions {
+    limit?: number;
+    after?: string;
+    before?: string;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        next: string | null;
+        prev: string | null;
+    };
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,OAAO;IAEtB,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGzC,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,uBAAuB,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACnF,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACpF,gBAAgB,CACd,MAAM,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GACvC,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3C,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACxF,sBAAsB,CAAC,MAAM,EAAE,QAAQ,CAAC,4BAA4B,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7F,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACjF,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,yBAAyB,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACvF,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,uBAAuB,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAGnF,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,uBAAuB,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACnF,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACpF,gBAAgB,CACd,MAAM,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GACvC,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3C,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,yBAAyB,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACvF,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AAEvD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,UAAU,EAAE;QACV,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;CACH"}

package/dist/backend.js

@@ -0,0 +1,3 @@
+export const DEFAULT_NAMESPACE_ID = "default";
+
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/backend.ts"],"sourcesContent":["import type { SerializedError } from \"./core/error\";\nimport type { JsonValue } from \"./core/json\";\nimport type { StepAttempt, StepAttemptContext, StepKind } from \"./core/step\";\nimport type { WorkflowRun } from \"./core/workflow\";\nimport type { OnSubscribed } from \"./database/pubsub\";\n\nexport const DEFAULT_NAMESPACE_ID = \"default\";\n\n/**\n * Backend is the interface for backend providers to implement.\n */\nexport interface Backend {\n  // Listen for events on a channel\n  subscribe(callback: OnSubscribed): Promise<void>;\n  publish(payload?: string): Promise<void>;\n\n  // Workflow Runs\n  createWorkflowRun(params: Readonly<CreateWorkflowRunParams>): Promise<WorkflowRun>;\n  getWorkflowRun(params: Readonly<GetWorkflowRunParams>): Promise<WorkflowRun | null>;\n  listWorkflowRuns(\n    params: Readonly<ListWorkflowRunsParams>,\n  ): Promise<PaginatedResponse<WorkflowRun>>;\n  claimWorkflowRun(params: Readonly<ClaimWorkflowRunParams>): Promise<WorkflowRun | null>;\n  extendWorkflowRunLease(params: Readonly<ExtendWorkflowRunLeaseParams>): Promise<WorkflowRun>;\n  sleepWorkflowRun(params: Readonly<SleepWorkflowRunParams>): Promise<WorkflowRun>;\n  completeWorkflowRun(params: Readonly<CompleteWorkflowRunParams>): Promise<WorkflowRun>;\n  failWorkflowRun(params: Readonly<FailWorkflowRunParams>): Promise<WorkflowRun>;\n  cancelWorkflowRun(params: Readonly<CancelWorkflowRunParams>): Promise<WorkflowRun>;\n\n  // Step Attempts\n  createStepAttempt(params: Readonly<CreateStepAttemptParams>): Promise<StepAttempt>;\n  getStepAttempt(params: Readonly<GetStepAttemptParams>): Promise<StepAttempt | null>;\n  listStepAttempts(\n    params: Readonly<ListStepAttemptsParams>,\n  ): Promise<PaginatedResponse<StepAttempt>>;\n  completeStepAttempt(params: Readonly<CompleteStepAttemptParams>): Promise<StepAttempt>;\n  failStepAttempt(params: Readonly<FailStepAttemptParams>): Promise<StepAttempt>;\n}\n\nexport interface CreateWorkflowRunParams {\n  workflowName: string;\n  version: string | null;\n  idempotencyKey: string | null;\n  config: JsonValue;\n  context: JsonValue | null;\n  input: JsonValue | null;\n  availableAt: Date | null; // null = immediately\n  deadlineAt: Date | null; // null = no deadline\n}\n\nexport interface GetWorkflowRunParams {\n  workflowRunId: string;\n}\n\nexport type ListWorkflowRunsParams = PaginationOptions;\n\nexport interface ClaimWorkflowRunParams {\n  workerId: string;\n  leaseDurationMs: number;\n}\n\nexport interface ExtendWorkflowRunLeaseParams {\n  workflowRunId: string;\n  workerId: string;\n  leaseDurationMs: number;\n}\n\nexport interface SleepWorkflowRunParams {\n  workflowRunId: string;\n  workerId: string;\n  availableAt: Date;\n}\n\nexport interface CompleteWorkflowRunParams {\n  workflowRunId: string;\n  workerId: string;\n  output: JsonValue | null;\n}\n\nexport interface FailWorkflowRunParams {\n  workflowRunId: string;\n  workerId: string;\n  error: SerializedError;\n}\n\nexport interface CancelWorkflowRunParams {\n  workflowRunId: string;\n}\n\nexport interface CreateStepAttemptParams {\n  workflowRunId: string;\n  workerId: string;\n  stepName: string;\n  kind: StepKind;\n  config: JsonValue;\n  context: StepAttemptContext | null;\n}\n\nexport interface GetStepAttemptParams {\n  stepAttemptId: string;\n}\n\nexport interface ListStepAttemptsParams extends PaginationOptions {\n  workflowRunId: string;\n}\n\nexport interface CompleteStepAttemptParams {\n  workflowRunId: string;\n  stepAttemptId: string;\n  workerId: string;\n  output: JsonValue | null;\n}\n\nexport interface FailStepAttemptParams {\n  workflowRunId: string;\n  stepAttemptId: string;\n  workerId: string;\n  error: SerializedError;\n}\n\nexport interface PaginationOptions {\n  limit?: number;\n  after?: string;\n  before?: string;\n}\n\nexport interface PaginatedResponse<T> {\n  data: T[];\n  pagination: {\n    next: string | null;\n    prev: string | null;\n  };\n}\n"],"names":["DEFAULT_NAMESPACE_ID"],"mappings":"AAMA,OAAO,MAAMA,uBAAuB,UAAU"}

package/dist/chaos.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chaos.test.d.ts.map

package/dist/chaos.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chaos.test.d.ts","sourceRoot":"","sources":["../src/chaos.test.ts"],"names":[],"mappings":""}

package/dist/chaos.test.js

@@ -0,0 +1,92 @@
+import { randomInt } from "node:crypto";
+import { describe, expect, test } from "vitest";
+import { OpenWorkflow } from "./client.js";
+import { createBackend } from "./testing/connection.js";
+const TOTAL_STEPS = 50;
+const WORKER_COUNT = 3;
+const WORKER_CONCURRENCY = 2;
+const STEP_DURATION_MS = 25;
+const CHAOS_DURATION_MS = 5000;
+const CHAOS_INTERVAL_MS = 200;
+const TEST_TIMEOUT_MS = 30_000;
+describe("chaos test", ()=>{
+    test("workflow completes despite random worker deaths (known slow test)", async ()=>{
+        const backend = await createBackend();
+        const client = new OpenWorkflow({
+            backend
+        });
+        const workflow = client.defineWorkflow({
+            name: "chaos-workflow"
+        }, async ({ step })=>{
+            const results = [];
+            for(let i = 0; i < TOTAL_STEPS; i++){
+                const stepName = `step-${i.toString()}`;
+                const result = await step.run({
+                    name: stepName
+                }, async ()=>{
+                    await sleep(STEP_DURATION_MS); // fake work
+                    return i;
+                });
+                results.push(result);
+            }
+            return results;
+        });
+        const workers = await Promise.all(Array.from({
+            length: WORKER_COUNT
+        }, ()=>createAndStartWorker(client)));
+        const handle = await workflow.run();
+        let workflowCompleted = false;
+        let chaosTask = null;
+        try {
+            chaosTask = runChaosTest({
+                client,
+                workers,
+                durationMs: CHAOS_DURATION_MS,
+                intervalMs: CHAOS_INTERVAL_MS,
+                shouldStop: ()=>workflowCompleted
+            });
+            const result = await handle.result();
+            workflowCompleted = true;
+            const restarts = await chaosTask;
+            expect(result).toHaveLength(TOTAL_STEPS);
+            expect(result[TOTAL_STEPS - 1]).toBe(TOTAL_STEPS - 1);
+            expect(restarts).toBeGreaterThan(0);
+        } finally{
+            workflowCompleted = true;
+            if (chaosTask) await chaosTask;
+            await Promise.all(workers.map((worker)=>worker.stop()));
+            await backend.stop();
+        }
+    }, TEST_TIMEOUT_MS);
+});
+async function runChaosTest(params) {
+    const { client, workers, durationMs, intervalMs, shouldStop } = params;
+    const chaosEndsAt = Date.now() + durationMs;
+    let restartCount = 0;
+    while(Date.now() < chaosEndsAt && !shouldStop()){
+        await sleep(intervalMs);
+        if (workers.length === 0) {
+            workers.push(await createAndStartWorker(client));
+            continue;
+        }
+        const index = randomInt(workers.length);
+        const victim = workers.splice(index, 1)[0];
+        await victim?.stop();
+        const replacement = await createAndStartWorker(client);
+        workers.push(replacement);
+        restartCount++;
+    }
+    return restartCount;
+}
+async function createAndStartWorker(client) {
+    const worker = client.newWorker({
+        concurrency: WORKER_CONCURRENCY
+    });
+    await worker.start();
+    return worker;
+}
+function sleep(ms) {
+    return new Promise((resolve)=>setTimeout(resolve, ms));
+}
+
+//# sourceMappingURL=chaos.test.js.map

package/dist/chaos.test.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/chaos.test.ts"],"sourcesContent":["import { randomInt } from \"node:crypto\";\nimport { describe, expect, test } from \"vitest\";\nimport { OpenWorkflow } from \"./client\";\nimport { createBackend } from \"./testing/connection\";\nimport type { Worker } from \"./worker\";\n\nconst TOTAL_STEPS = 50;\nconst WORKER_COUNT = 3;\nconst WORKER_CONCURRENCY = 2;\nconst STEP_DURATION_MS = 25;\nconst CHAOS_DURATION_MS = 5000;\nconst CHAOS_INTERVAL_MS = 200;\nconst TEST_TIMEOUT_MS = 30_000;\n\ndescribe(\"chaos test\", () => {\n  test(\n    \"workflow completes despite random worker deaths (known slow test)\",\n    async () => {\n      const backend = await createBackend();\n      const client = new OpenWorkflow({ backend });\n\n      const workflow = client.defineWorkflow({ name: \"chaos-workflow\" }, async ({ step }) => {\n        const results: number[] = [];\n        for (let i = 0; i < TOTAL_STEPS; i++) {\n          const stepName = `step-${i.toString()}`;\n          const result = await step.run({ name: stepName }, async () => {\n            await sleep(STEP_DURATION_MS); // fake work\n            return i;\n          });\n          results.push(result);\n        }\n        return results;\n      });\n\n      const workers = await Promise.all(\n        Array.from({ length: WORKER_COUNT }, () => createAndStartWorker(client)),\n      );\n\n      const handle = await workflow.run();\n      let workflowCompleted = false;\n      let chaosTask: Promise<number> | null = null;\n\n      try {\n        chaosTask = runChaosTest({\n          client,\n          workers,\n          durationMs: CHAOS_DURATION_MS,\n          intervalMs: CHAOS_INTERVAL_MS,\n          shouldStop: () => workflowCompleted,\n        });\n\n        const result = await handle.result();\n        workflowCompleted = true;\n        const restarts = await chaosTask;\n\n        expect(result).toHaveLength(TOTAL_STEPS);\n        expect(result[TOTAL_STEPS - 1]).toBe(TOTAL_STEPS - 1);\n        expect(restarts).toBeGreaterThan(0);\n      } finally {\n        workflowCompleted = true;\n        if (chaosTask) await chaosTask;\n        await Promise.all(workers.map((worker) => worker.stop()));\n        await backend.stop();\n      }\n    },\n    TEST_TIMEOUT_MS,\n  );\n});\n\nasync function runChaosTest(params: {\n  client: OpenWorkflow;\n  workers: Worker[];\n  durationMs: number;\n  intervalMs: number;\n  shouldStop: () => boolean;\n}): Promise<number> {\n  const { client, workers, durationMs, intervalMs, shouldStop } = params;\n  const chaosEndsAt = Date.now() + durationMs;\n  let restartCount = 0;\n\n  while (Date.now() < chaosEndsAt && !shouldStop()) {\n    await sleep(intervalMs);\n    if (workers.length === 0) {\n      workers.push(await createAndStartWorker(client));\n      continue;\n    }\n\n    const index = randomInt(workers.length);\n    const victim = workers.splice(index, 1)[0];\n    await victim?.stop();\n\n    const replacement = await createAndStartWorker(client);\n    workers.push(replacement);\n    restartCount++;\n  }\n\n  return restartCount;\n}\n\nasync function createAndStartWorker(client: OpenWorkflow): Promise<Worker> {\n  const worker = client.newWorker({ concurrency: WORKER_CONCURRENCY });\n  await worker.start();\n  return worker;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"],"names":["randomInt","describe","expect","test","OpenWorkflow","createBackend","TOTAL_STEPS","WORKER_COUNT","WORKER_CONCURRENCY","STEP_DURATION_MS","CHAOS_DURATION_MS","CHAOS_INTERVAL_MS","TEST_TIMEOUT_MS","backend","client","workflow","defineWorkflow","name","step","results","i","stepName","toString","result","run","sleep","push","workers","Promise","all","Array","from","length","createAndStartWorker","handle","workflowCompleted","chaosTask","runChaosTest","durationMs","intervalMs","shouldStop","restarts","toHaveLength","toBe","toBeGreaterThan","map","worker","stop","params","chaosEndsAt","Date","now","restartCount","index","victim","splice","replacement","newWorker","concurrency","start","ms","resolve","setTimeout"],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,178 @@
+import type { Backend } from "./backend";
+import type { StandardSchemaV1 } from "./core/schema";
+import type { SchemaInput, SchemaOutput, WorkflowRun } from "./core/workflow";
+import type { WorkflowFunction } from "./execution";
+import { Worker } from "./worker";
+import { defineWorkflowSpec, type Workflow, type WorkflowSpec } from "./workflow";
+type WorkflowHandlerInput<TSchema, Input> = SchemaOutput<TSchema, Input>;
+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 declare class OpenWorkflow {
+    private backend;
+    private registry;
+    constructor(options: OpenWorkflowOptions);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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();
+     * ```
+     */
+    runWorkflow<Input, Output, RunInput = Input>(spec: WorkflowSpec<Input, Output, RunInput>, input?: RunInput, options?: WorkflowRunOptions): Promise<WorkflowRunHandle<Output>>;
+    /**
+     * 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>>;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+/**
+ * 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() }),
+ * });
+ * ```
+ */
+export declare const declareWorkflow: typeof defineWorkflowSpec;
+/**
+ * A fully defined workflow with its implementation. This class is returned by
+ * `defineWorkflow` and provides the `.run()` method for scheduling workflow
+ * runs.
+ */
+export declare class RunnableWorkflow<Input, Output, RunInput = Input> {
+    private readonly ow;
+    readonly workflow: Workflow<Input, Output, RunInput>;
+    constructor(ow: OpenWorkflow, workflow: Workflow<Input, Output, RunInput>);
+    /**
+     * Starts a new workflow run.
+     * @param input - Workflow input
+     * @param options - Run options
+     * @returns Workflow run handle
+     */
+    run(input?: RunInput, options?: WorkflowRunOptions): Promise<WorkflowRunHandle<Output>>;
+}
+/**
+ * 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 declare class WorkflowRunHandle<Output> {
+    private backend;
+    readonly workflowRun: WorkflowRun;
+    private resultPollIntervalMs;
+    private resultTimeoutMs;
+    constructor(options: WorkflowHandleOptions);
+    /**
+     * Waits for the workflow run to complete and returns the result.
+     * @returns Workflow output
+     */
+    result(): Promise<Output>;
+    /**
+     * Cancels the workflow run. Only workflows in pending, running, or sleeping
+     * status can be canceled.
+     */
+    cancel(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}