@sonamu-kit/tasks 0.0.1

package/src/core/workflow.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "vitest";
+import type { StandardSchemaV1 } from "./schema";
+import { DEFAULT_WORKFLOW_RESULT_CONFIG, isTerminalStatus, validateInput } from "./workflow";
+
+describe("validateInput", () => {
+  test("returns success with input when no schema provided (null)", async () => {
+    const input = { name: "test", value: 42 };
+    const result = await validateInput(null, input);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.value).toBe(input);
+    }
+  });
+
+  test("returns success with input when no schema provided (undefined)", async () => {
+    const input = "string input";
+    const result = await validateInput(undefined, input);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.value).toBe(input);
+    }
+  });
+
+  test("validates input successfully against schema", async () => {
+    const schema = createMockSchema<{ name: string }>({
+      validate: (input) => ({ value: input as { name: string } }),
+    });
+    const input = { name: "test" };
+
+    const result = await validateInput(schema, input);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.value).toEqual({ name: "test" });
+    }
+  });
+
+  test("transforms input using schema", async () => {
+    const schema = createMockSchema<string, number>({
+      validate: (input) => ({ value: Number.parseInt(input as string, 10) }),
+    });
+
+    const result = await validateInput(schema, "42");
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.value).toBe(42);
+    }
+  });
+
+  test("returns failure with error message when validation fails", async () => {
+    const schema = createMockSchema<string>({
+      validate: () => ({
+        issues: [{ message: "Invalid input" }],
+      }),
+    });
+
+    const result = await validateInput(schema, "bad input");
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toBe("Invalid input");
+    }
+  });
+
+  test("combines multiple validation error messages", async () => {
+    const schema = createMockSchema<{ email: string; age: number }>({
+      validate: () => ({
+        issues: [{ message: "Invalid email format" }, { message: "Age must be positive" }],
+      }),
+    });
+
+    const result = await validateInput(schema, {
+      email: "invalid",
+      age: -5,
+    });
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toBe("Invalid email format; Age must be positive");
+    }
+  });
+
+  test("returns generic message when issues array is empty", async () => {
+    const schema = createMockSchema<string>({
+      validate: () => ({
+        issues: [],
+      }),
+    });
+
+    const result = await validateInput(schema, "test");
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toBe("Validation failed");
+    }
+  });
+
+  test("handles async schema validation", async () => {
+    const schema = createMockSchema<string>({
+      validate: async (input) => {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        return { value: (input as string).toUpperCase() };
+      },
+    });
+
+    const result = await validateInput(schema, "hello");
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.value).toBe("HELLO");
+    }
+  });
+
+  test("handles undefined input when no schema", async () => {
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    const result = await validateInput(null, undefined);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.value).toBeUndefined();
+    }
+  });
+});
+
+describe("isTerminalStatus", () => {
+  test("returns true for 'completed' status", () => {
+    expect(isTerminalStatus("completed")).toBe(true);
+  });
+
+  test("returns true for 'succeeded' status (deprecated)", () => {
+    expect(isTerminalStatus("succeeded")).toBe(true);
+  });
+
+  test("returns true for 'failed' status", () => {
+    expect(isTerminalStatus("failed")).toBe(true);
+  });
+
+  test("returns true for 'canceled' status", () => {
+    expect(isTerminalStatus("canceled")).toBe(true);
+  });
+
+  test("returns false for 'pending' status", () => {
+    expect(isTerminalStatus("pending")).toBe(false);
+  });
+
+  test("returns false for 'running' status", () => {
+    expect(isTerminalStatus("running")).toBe(false);
+  });
+
+  test("returns false for 'sleeping' status", () => {
+    expect(isTerminalStatus("sleeping")).toBe(false);
+  });
+
+  test("returns false for unknown status strings", () => {
+    expect(isTerminalStatus("unknown")).toBe(false);
+    expect(isTerminalStatus("")).toBe(false);
+    expect(isTerminalStatus("COMPLETED")).toBe(false);
+  });
+});
+
+describe("DEFAULT_WORKFLOW_RESULT_CONFIG", () => {
+  test("has expected poll interval", () => {
+    expect(DEFAULT_WORKFLOW_RESULT_CONFIG.pollIntervalMs).toBe(1000);
+  });
+
+  test("has expected timeout (5 minutes)", () => {
+    expect(DEFAULT_WORKFLOW_RESULT_CONFIG.timeoutMs).toBe(5 * 60 * 1000);
+  });
+});
+
+function createMockSchema<I, O = I>(options: {
+  validate: (input: unknown) => StandardSchemaV1.Result<O> | Promise<StandardSchemaV1.Result<O>>;
+}): StandardSchemaV1<I, O> {
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "test",
+      validate: options.validate,
+    },
+  };
+}

package/src/core/workflow.ts

@@ -0,0 +1,127 @@
+import type { SerializedError } from "./error";
+import type { JsonValue } from "./json";
+import type { StandardSchemaV1 } from "./schema";
+
+/**
+ * Status of a workflow run through its lifecycle.
+ */
+export type WorkflowRunStatus =
+  | "pending"
+  | "running"
+  | "sleeping"
+  | "succeeded" // deprecated in favor of 'completed'
+  | "completed"
+  | "failed"
+  | "canceled";
+
+/**
+ * WorkflowRun represents a single execution instance of a workflow.
+ */
+export interface WorkflowRun {
+  namespaceId: string;
+  id: string;
+  workflowName: string;
+  version: string | null;
+  status: WorkflowRunStatus;
+  idempotencyKey: string | null;
+  config: JsonValue; // user-defined config
+  context: JsonValue | null; // runtime execution metadata
+  input: JsonValue | null;
+  output: JsonValue | null;
+  error: SerializedError | null;
+  attempts: number;
+  parentStepAttemptNamespaceId: string | null;
+  parentStepAttemptId: string | null;
+  workerId: string | null;
+  availableAt: Date | null;
+  deadlineAt: Date | null;
+  startedAt: Date | null;
+  finishedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Infers the input type from a Standard Schema.
+ */
+export type SchemaInput<TSchema, Fallback> = TSchema extends StandardSchemaV1
+  ? StandardSchemaV1.InferInput<TSchema>
+  : Fallback;
+
+/**
+ * Infers the output type from a Standard Schema.
+ */
+export type SchemaOutput<TSchema, Fallback> = TSchema extends StandardSchemaV1
+  ? StandardSchemaV1.InferOutput<TSchema>
+  : Fallback;
+
+/**
+ * Result of input validation - either success with a value or failure with an
+ * error message.
+ */
+export type ValidationResult<T> = { success: true; value: T } | { success: false; error: string };
+
+/**
+ * Default configuration for result polling when awaiting workflow completion.
+ */
+export const DEFAULT_WORKFLOW_RESULT_CONFIG = {
+  /** Polling interval in milliseconds (1 second) */
+  pollIntervalMs: 1000,
+  /** Timeout in milliseconds (5 minutes) */
+  timeoutMs: 5 * 60 * 1000,
+} as const;
+
+/**
+ * Validate input against a Standard Schema. Pure async function that validates
+ * input and returns a ValidationResult.
+ * @param schema - The Standard Schema to validate against (or null/undefined
+ * for no validation)
+ * @param input - The input value to validate
+ * @returns A ValidationResult containing either the validated value or an error
+ * message
+ */
+export async function validateInput<RunInput, Input>(
+  schema: StandardSchemaV1<RunInput, Input> | null | undefined,
+  input: RunInput | undefined,
+): Promise<ValidationResult<Input>> {
+  // No schema means no validation - pass through as-is
+  if (!schema) {
+    return {
+      success: true,
+      value: input as unknown as Input,
+    };
+  }
+
+  // Validate using Standard Schema v1 protocol https://standardschema.dev
+  const result = schema["~standard"].validate(input);
+  const resolved = await Promise.resolve(result);
+
+  if (resolved.issues) {
+    const messages =
+      resolved.issues.length > 0
+        ? resolved.issues.map((issue) => issue.message).join("; ")
+        : "Validation failed";
+    return {
+      success: false,
+      error: messages,
+    };
+  }
+
+  return {
+    success: true,
+    value: resolved.value,
+  };
+}
+
+/**
+ * Check if a workflow run status represents a terminal state.
+ * @param status - The workflow run status
+ * @returns True if the status is terminal (completed, failed, or canceled)
+ */
+export function isTerminalStatus(
+  status: string,
+): status is "succeeded" | "completed" | "failed" | "canceled" {
+  return (
+    status === "succeeded" || status === "completed" || status === "failed" || status === "canceled"
+  );
+}

package/src/database/backend.test.ts

@@ -0,0 +1,16 @@
+import { randomUUID } from "node:crypto";
+import { KNEX_GLOBAL_CONFIG } from "../testing/connection";
+import { BackendPostgres } from "./backend";
+import { testBackend } from "./backend.testsuite";
+
+testBackend({
+  setup: async () => {
+    return await BackendPostgres.connect(KNEX_GLOBAL_CONFIG, {
+      namespaceId: randomUUID(),
+      runMigrations: false,
+    });
+  },
+  teardown: async (backend) => {
+    await (backend as BackendPostgres).stop();
+  },
+});