@sonamu-kit/tasks 0.2.0 → 0.3.0

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@sonamu-kit/tasks",
-  "version": "0.2.0",
-  "type": "module",
+  "version": "0.3.0",
   "description": "Sonamu Task - Simple & Distributed Task Queue",
+  "author": "CartaNova <dev@cartanova.ai>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cartanova-ai/sonamu.git"
+  },
+  "type": "module",
   "main": "./dist/index.js",
   "exports": {
     ".": {
@@ -16,12 +21,8 @@
       "development": "./src/internal.ts"
     }
   },
-  "author": "CartaNova <dev@cartanova.ai>",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/cartanova-ai/sonamu.git"
-  },
   "dependencies": {
+    "c12": "^3.3.2",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0",
     "inflection": "^3.0.2",
@@ -30,33 +31,30 @@
     "pg": "^8.16.3",
     "rou3": "^0.7.10",
     "uuid": "^13.0.0",
-    "zod": "^4.1.12",
-    "c12": "^3.3.2"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/inflection": "^2.0.0",
-    "@biomejs/biome": "^2.3.10",
-    "@swc/cli": "^0.7.8",
-    "@swc/core": "^1.13.5",
     "@types/node": "25.0.7",
     "nodemon": "^3.1.10",
+    "tsdown": "^0.12.5",
     "tsx": "^4.20.6",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.10"
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.2"
   },
   "peerDependencies": {
-    "knex": "^3.1.0",
-    "@logtape/logtape": "2.0.0"
+    "@logtape/logtape": "2.0.0",
+    "knex": "^3.1.0"
   },
   "optionalDependencies": {
     "pg-native": "^3.5.2"
   },
   "scripts": {
     "dev": "nodemon exec",
-    "build": "swc src --config-file .swcrc -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "check": "tsc --noEmit && biome format --write ./src/**/*.ts",
+    "build": "tsdown",
+    "check": "tsc --noEmit && oxlint src && oxfmt --check src",
     "check:type": "tsc --noEmit",
-    "check:format": "biome format --write ./src/**/*.ts",
+    "check:format": "oxfmt src",
     "pretest": "tsx scripts/migrate.ts",
     "test": "vitest run",
     "test:watch": "vitest watch --standalone",

package/src/backend.ts

@@ -1,9 +1,9 @@
-import type { SerializedError } from "./core/error";
-import type { JsonValue } from "./core/json";
-import type { SerializableRetryPolicy } from "./core/retry";
-import type { StepAttempt, StepAttemptContext, StepKind } from "./core/step";
-import type { WorkflowRun } from "./core/workflow";
-import type { OnSubscribed } from "./database/pubsub";
+import { type SerializedError } from "./core/error";
+import { type JsonValue } from "./core/json";
+import { type SerializableRetryPolicy } from "./core/retry";
+import { type StepAttempt, type StepAttemptContext, type StepKind } from "./core/step";
+import { type WorkflowRun } from "./core/workflow";
+import { type OnSubscribed } from "./database/pubsub";
 
 export const DEFAULT_NAMESPACE_ID = "default";
 
@@ -27,6 +27,8 @@ export interface Backend {
   completeWorkflowRun(params: Readonly<CompleteWorkflowRunParams>): Promise<WorkflowRun>;
   failWorkflowRun(params: Readonly<FailWorkflowRunParams>): Promise<WorkflowRun>;
   cancelWorkflowRun(params: Readonly<CancelWorkflowRunParams>): Promise<WorkflowRun>;
+  pauseWorkflowRun(params: Readonly<PauseWorkflowRunParams>): Promise<WorkflowRun>;
+  resumeWorkflowRun(params: Readonly<ResumeWorkflowRunParams>): Promise<WorkflowRun>;
 
   // Step Attempts
   createStepAttempt(params: Readonly<CreateStepAttemptParams>): Promise<StepAttempt>;
@@ -34,8 +36,8 @@ export interface Backend {
   listStepAttempts(
     params: Readonly<ListStepAttemptsParams>,
   ): Promise<PaginatedResponse<StepAttempt>>;
-  completeStepAttempt(params: Readonly<CompleteStepAttemptParams>): Promise<StepAttempt>;
-  failStepAttempt(params: Readonly<FailStepAttemptParams>): Promise<StepAttempt>;
+  completeStepAttempt(params: Readonly<CompleteStepAttemptParams>): Promise<StepAttempt | null>;
+  failStepAttempt(params: Readonly<FailStepAttemptParams>): Promise<StepAttempt | null>;
 }
 
 export interface CreateWorkflowRunParams {
@@ -54,7 +56,12 @@ export interface GetWorkflowRunParams {
   workflowRunId: string;
 }
 
-export type ListWorkflowRunsParams = PaginationOptions;
+export interface ListWorkflowRunsParams extends PaginationOptions {
+  status?: string[];
+  workflowName?: string;
+  createdAfter?: Date;
+  createdBefore?: Date;
+}
 
 export interface ClaimWorkflowRunParams {
   workerId: string;
@@ -91,6 +98,14 @@ export interface CancelWorkflowRunParams {
   workflowRunId: string;
 }
 
+export interface PauseWorkflowRunParams {
+  workflowRunId: string;
+}
+
+export interface ResumeWorkflowRunParams {
+  workflowRunId: string;
+}
+
 export interface CreateStepAttemptParams {
   workflowRunId: string;
   workerId: string;
@@ -126,6 +141,7 @@ export interface PaginationOptions {
   limit?: number;
   after?: string;
   before?: string;
+  order?: "asc" | "desc";
 }
 
 export interface PaginatedResponse<T> {

package/src/chaos.test.ts

@@ -1,8 +1,10 @@
 import { randomInt } from "node:crypto";
+
 import { describe, expect, test } from "vitest";
+
 import { OpenWorkflow } from "./client";
 import { createBackend } from "./testing/connection";
-import type { Worker } from "./worker";
+import { type Worker } from "./worker";
 
 const TOTAL_STEPS = 50;
 const WORKER_COUNT = 3;

package/src/client.test.ts

@@ -1,6 +1,8 @@
 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";

package/src/client.ts

@@ -1,12 +1,14 @@
-import type { Backend } from "./backend";
+import { type Backend } from "./backend";
 import { serializeRetryPolicy } from "./core/retry";
-import type { StandardSchemaV1 } from "./core/schema";
-import type { SchemaInput, SchemaOutput, WorkflowRun } from "./core/workflow";
+import { type StandardSchemaV1 } from "./core/schema";
+import { type SchemaInput, type SchemaOutput, type WorkflowRun } from "./core/workflow";
 import { validateInput } from "./core/workflow";
-import type { WorkflowFunction } from "./execution";
+import { type WorkflowFunction } from "./execution";
 import { WorkflowRegistry } from "./registry";
-import { Worker, type WorkerOptions } from "./worker";
-import { defineWorkflow, defineWorkflowSpec, type Workflow, type WorkflowSpec } from "./workflow";
+import { Worker } from "./worker";
+import { type WorkerOptions } from "./worker";
+import { defineWorkflow, defineWorkflowSpec } from "./workflow";
+import { type Workflow, type WorkflowSpec } from "./workflow";
 
 const DEFAULT_RESULT_POLL_INTERVAL_MS = 1000; // 1s
 const DEFAULT_RESULT_TIMEOUT_MS = 5 * 60 * 1000; // 5m
@@ -321,12 +323,32 @@ export class WorkflowRunHandle<Output> {
   }
 
   /**
-   * Cancels the workflow run. Only workflows in pending, running, or sleeping
-   * status can be canceled.
+   * Cancels the workflow run. Only workflows in pending, running, sleeping,
+   * or paused status can be canceled.
    */
   async cancel(): Promise<void> {
     await this.backend.cancelWorkflowRun({
       workflowRunId: this.workflowRun.id,
     });
   }
+
+  /**
+   * Pauses the workflow run. Only workflows in pending, running, or sleeping
+   * status can be paused.
+   */
+  async pause(): Promise<void> {
+    await this.backend.pauseWorkflowRun({
+      workflowRunId: this.workflowRun.id,
+    });
+  }
+
+  /**
+   * Resumes a paused workflow run. Sets the status back to pending so that
+   * a worker can reclaim it.
+   */
+  async resume(): Promise<void> {
+    await this.backend.resumeWorkflowRun({
+      workflowRunId: this.workflowRun.id,
+    });
+  }
 }

package/src/config.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "vitest";
+
 import { defineConfig } from "./config";
 import { createBackend } from "./testing/connection";
 

package/src/config.ts

@@ -1,6 +1,7 @@
 import { loadConfig as loadC12Config } from "c12";
-import type { Backend } from "./backend";
-import type { WorkerOptions } from "./worker";
+
+import { type Backend } from "./backend";
+import { type WorkerOptions } from "./worker";
 
 export interface OpenWorkflowConfig {
   backend: Backend;

package/src/core/duration.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
-import type { DurationString } from "./duration";
+
+import { type DurationString } from "./duration";
 import { parseDuration } from "./duration";
 import { err, ok } from "./result";
 

package/src/core/duration.ts

@@ -1,4 +1,4 @@
-import type { Result } from "./result";
+import { type Result } from "./result";
 import { err, ok } from "./result";
 
 type Years = "years" | "year" | "yrs" | "yr" | "y";

package/src/core/error.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "vitest";
+
 import { serializeError } from "./error";
 
 describe("serializeError", () => {

package/src/core/error.ts

@@ -1,4 +1,4 @@
-import type { JsonValue } from "./json";
+import { type JsonValue } from "./json";
 
 export type SerializedError = {
   name?: string;

package/src/core/result.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "vitest";
+
 import { err, ok } from "./result";
 
 describe("Result helpers", () => {

package/src/core/retry.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
-import type { SerializedError } from "./error";
-import type { DynamicRetryPolicy, StaticRetryPolicy } from "./retry";
+
+import { type SerializedError } from "./error";
+import { type DynamicRetryPolicy, type StaticRetryPolicy } from "./retry";
 import {
   calculateRetryDelayMs,
   DEFAULT_RETRY_POLICY,

package/src/core/retry.ts

@@ -1,4 +1,4 @@
-import type { SerializedError } from "./error";
+import { type SerializedError } from "./error";
 
 export interface RetryDecision {
   shouldRetry: boolean;

package/src/core/schema.ts

@@ -68,7 +68,7 @@ export declare namespace StandardSchemaV1 {
     Schema["~standard"]["types"]
   >["output"];
 
-  // eslint-disable-next-line unicorn/require-module-specifiers
-  // biome-ignore lint/complexity/noUselessEmptyExport: needed for granular visibility control of TS namespace
+  // needed for granular visibility control of TS namespace
+  // oxlint-disable-next-line
   export {};
 }

package/src/core/step.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "vitest";
+
 import { ok } from "./result";
-import type { StepAttempt, StepAttemptCache } from "./step";
+import { type StepAttempt, type StepAttemptCache } from "./step";
 import {
   addToStepAttemptCache,
   calculateSleepResumeAt,

package/src/core/step.ts

@@ -1,7 +1,7 @@
-import type { DurationString } from "./duration";
+import { type DurationString } from "./duration";
 import { parseDuration } from "./duration";
-import type { JsonValue } from "./json";
-import type { Result } from "./result";
+import { type JsonValue } from "./json";
+import { type Result } from "./result";
 import { err, ok } from "./result";
 
 /**
@@ -14,6 +14,7 @@ export type StepKind = "function" | "sleep";
  */
 export type StepAttemptStatus =
   | "running"
+  | "paused"
   | "succeeded" // deprecated in favor of 'completed'
   | "completed"
   | "failed";

package/src/core/workflow.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
-import type { StandardSchemaV1 } from "./schema";
+
+import { type StandardSchemaV1 } from "./schema";
 import { DEFAULT_WORKFLOW_RESULT_CONFIG, isTerminalStatus, validateInput } from "./workflow";
 
 describe("validateInput", () => {

package/src/core/workflow.ts

@@ -1,6 +1,6 @@
-import type { SerializedError } from "./error";
-import type { JsonValue } from "./json";
-import type { StandardSchemaV1 } from "./schema";
+import { type SerializedError } from "./error";
+import { type JsonValue } from "./json";
+import { type StandardSchemaV1 } from "./schema";
 
 /**
  * Status of a workflow run through its lifecycle.
@@ -9,6 +9,7 @@ export type WorkflowRunStatus =
   | "pending"
   | "running"
   | "sleeping"
+  | "paused"
   | "succeeded" // deprecated in favor of 'completed'
   | "completed"
   | "failed"

package/src/database/backend.test.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+
 import { KNEX_GLOBAL_CONFIG } from "../testing/connection";
 import { BackendPostgres } from "./backend";
 import { testBackend } from "./backend.testsuite";