@sonamu-kit/tasks 0.0.1

package/src/core/schema.ts

@@ -0,0 +1,74 @@
+/** The Standard Schema interface. https://standardschema.dev */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  // eslint-disable-next-line functional/no-mixed-types
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: readonly Issue[];
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: readonly (PropertyKey | PathSegment)[] | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["input"];
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    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
+  export {};
+}

package/src/core/step.test.ts

@@ -0,0 +1,362 @@
+import { describe, expect, test } from "vitest";
+import { ok } from "./result";
+import type { StepAttempt, StepAttemptCache } from "./step";
+import {
+  addToStepAttemptCache,
+  calculateSleepResumeAt,
+  createSleepContext,
+  createStepAttemptCacheFromAttempts,
+  getCachedStepAttempt,
+  hasCompletedStep,
+  normalizeStepOutput,
+} from "./step";
+
+describe("createStepAttemptCacheFromAttempts", () => {
+  test("creates empty cache from empty array", () => {
+    const cache = createStepAttemptCacheFromAttempts([]);
+
+    expect(cache.size).toBe(0);
+  });
+
+  test("includes completed attempts in cache", () => {
+    const attempt = createMockStepAttempt({
+      stepName: "step-a",
+      status: "completed",
+      output: "result",
+    });
+    const cache = createStepAttemptCacheFromAttempts([attempt]);
+
+    expect(cache.size).toBe(1);
+    expect(cache.get("step-a")).toBe(attempt);
+  });
+
+  test("includes succeeded attempts in cache (deprecated status)", () => {
+    const attempt = createMockStepAttempt({
+      stepName: "step-b",
+      status: "succeeded",
+      output: "result",
+    });
+    const cache = createStepAttemptCacheFromAttempts([attempt]);
+
+    expect(cache.size).toBe(1);
+    expect(cache.get("step-b")).toBe(attempt);
+  });
+
+  test("excludes running attempts from cache", () => {
+    const attempt = createMockStepAttempt({
+      stepName: "step-c",
+      status: "running",
+    });
+    const cache = createStepAttemptCacheFromAttempts([attempt]);
+
+    expect(cache.size).toBe(0);
+  });
+
+  test("excludes failed attempts from cache", () => {
+    const attempt = createMockStepAttempt({
+      stepName: "step-d",
+      status: "failed",
+      error: { message: "failed" },
+    });
+    const cache = createStepAttemptCacheFromAttempts([attempt]);
+
+    expect(cache.size).toBe(0);
+  });
+
+  test("filters mixed statuses correctly", () => {
+    const attempts = [
+      createMockStepAttempt({
+        stepName: "completed-step",
+        status: "completed",
+      }),
+      createMockStepAttempt({ stepName: "running-step", status: "running" }),
+      createMockStepAttempt({ stepName: "failed-step", status: "failed" }),
+      createMockStepAttempt({
+        stepName: "succeeded-step",
+        status: "succeeded",
+      }),
+    ];
+    const cache = createStepAttemptCacheFromAttempts(attempts);
+
+    expect(cache.size).toBe(2);
+    expect(cache.has("completed-step")).toBe(true);
+    expect(cache.has("succeeded-step")).toBe(true);
+    expect(cache.has("running-step")).toBe(false);
+    expect(cache.has("failed-step")).toBe(false);
+  });
+
+  test("uses step name as cache key", () => {
+    const attempt = createMockStepAttempt({
+      stepName: "my-unique-step-name",
+      status: "completed",
+    });
+    const cache = createStepAttemptCacheFromAttempts([attempt]);
+
+    expect(cache.get("my-unique-step-name")).toBe(attempt);
+    expect(cache.get("other-name")).toBeUndefined();
+  });
+});
+
+describe("getCachedStepAttempt", () => {
+  test("returns cached attempt when present", () => {
+    const attempt = createMockStepAttempt({ stepName: "cached-step" });
+    const cache: StepAttemptCache = new Map([["cached-step", attempt]]);
+
+    const result = getCachedStepAttempt(cache, "cached-step");
+
+    expect(result).toBe(attempt);
+  });
+
+  test("returns undefined when step not in cache", () => {
+    const cache: StepAttemptCache = new Map();
+
+    const result = getCachedStepAttempt(cache, "missing-step");
+
+    expect(result).toBeUndefined();
+  });
+
+  test("returns undefined for similar but different step names", () => {
+    const attempt = createMockStepAttempt({ stepName: "step-1" });
+    const cache: StepAttemptCache = new Map([["step-1", attempt]]);
+
+    expect(getCachedStepAttempt(cache, "step-2")).toBeUndefined();
+    expect(getCachedStepAttempt(cache, "Step-1")).toBeUndefined();
+    expect(getCachedStepAttempt(cache, "step-1 ")).toBeUndefined();
+  });
+});
+
+describe("hasCompletedStep", () => {
+  test("returns true when step is in cache", () => {
+    const attempt = createMockStepAttempt({ stepName: "step-x" });
+    const cache: StepAttemptCache = new Map([["step-x", attempt]]);
+
+    expect(hasCompletedStep(cache, "step-x")).toBe(true);
+  });
+
+  test("returns false when step is not in cache", () => {
+    const cache: StepAttemptCache = new Map();
+
+    expect(hasCompletedStep(cache, "step-y")).toBe(false);
+  });
+
+  test("returns false for empty cache", () => {
+    const cache: StepAttemptCache = new Map();
+
+    expect(hasCompletedStep(cache, "any-step")).toBe(false);
+  });
+});
+
+describe("addToStepAttemptCache", () => {
+  test("adds attempt to empty cache", () => {
+    const cache: StepAttemptCache = new Map();
+    const attempt = createMockStepAttempt({ stepName: "new-step" });
+
+    const newCache = addToStepAttemptCache(cache, attempt);
+
+    expect(newCache.size).toBe(1);
+    expect(newCache.get("new-step")).toBe(attempt);
+  });
+
+  test("adds attempt to existing cache", () => {
+    const existing = createMockStepAttempt({ stepName: "existing-step" });
+    const cache: StepAttemptCache = new Map([["existing-step", existing]]);
+    const newAttempt = createMockStepAttempt({ stepName: "new-step" });
+
+    const newCache = addToStepAttemptCache(cache, newAttempt);
+
+    expect(newCache.size).toBe(2);
+    expect(newCache.get("existing-step")).toBe(existing);
+    expect(newCache.get("new-step")).toBe(newAttempt);
+  });
+
+  test("does not mutate original cache (immutable)", () => {
+    const existing = createMockStepAttempt({ stepName: "existing-step" });
+    const cache: StepAttemptCache = new Map([["existing-step", existing]]);
+    const newAttempt = createMockStepAttempt({ stepName: "new-step" });
+
+    const newCache = addToStepAttemptCache(cache, newAttempt);
+
+    expect(cache.size).toBe(1);
+    expect(cache.has("new-step")).toBe(false);
+    expect(newCache.size).toBe(2);
+  });
+
+  test("overwrites existing entry with same step name", () => {
+    const original = createMockStepAttempt({
+      stepName: "step",
+      output: "original",
+    });
+    const cache: StepAttemptCache = new Map([["step", original]]);
+    const replacement = createMockStepAttempt({
+      stepName: "step",
+      output: "replacement",
+    });
+
+    const newCache = addToStepAttemptCache(cache, replacement);
+
+    expect(newCache.size).toBe(1);
+    expect(newCache.get("step")?.output).toBe("replacement");
+  });
+});
+
+describe("normalizeStepOutput", () => {
+  test("passes through string values", () => {
+    expect(normalizeStepOutput("hello")).toBe("hello");
+  });
+
+  test("passes through number values", () => {
+    expect(normalizeStepOutput(42)).toBe(42);
+    expect(normalizeStepOutput(3.14)).toBe(3.14);
+    expect(normalizeStepOutput(0)).toBe(0);
+    expect(normalizeStepOutput(-1)).toBe(-1);
+  });
+
+  test("passes through boolean values", () => {
+    expect(normalizeStepOutput(true)).toBe(true);
+    expect(normalizeStepOutput(false)).toBe(false);
+  });
+
+  test("passes through null", () => {
+    expect(normalizeStepOutput(null)).toBeNull();
+  });
+
+  test("converts undefined to null", () => {
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    expect(normalizeStepOutput(undefined)).toBeNull();
+  });
+
+  test("passes through object values", () => {
+    const obj = { foo: "bar", nested: { baz: 123 } };
+    expect(normalizeStepOutput(obj)).toBe(obj);
+  });
+
+  test("passes through array values", () => {
+    const arr = [1, 2, 3];
+    expect(normalizeStepOutput(arr)).toBe(arr);
+  });
+
+  test("passes through empty object", () => {
+    const obj = {};
+    expect(normalizeStepOutput(obj)).toBe(obj);
+  });
+
+  test("passes through empty array", () => {
+    const arr: unknown[] = [];
+    expect(normalizeStepOutput(arr)).toBe(arr);
+  });
+});
+
+describe("calculateSleepResumeAt", () => {
+  test("calculates resume time from duration string", () => {
+    const now = 1_000_000;
+    const result = calculateSleepResumeAt("5s", now);
+
+    expect(result).toEqual(ok(new Date(now + 5000)));
+  });
+
+  test("calculates resume time with milliseconds", () => {
+    const now = 1_000_000;
+    const result = calculateSleepResumeAt("500ms", now);
+
+    expect(result).toEqual(ok(new Date(now + 500)));
+  });
+
+  test("calculates resume time with minutes", () => {
+    const now = 1_000_000;
+    const result = calculateSleepResumeAt("2m", now);
+
+    expect(result).toEqual(ok(new Date(now + 2 * 60 * 1000)));
+  });
+
+  test("calculates resume time with hours", () => {
+    const now = 1_000_000;
+    const result = calculateSleepResumeAt("1h", now);
+
+    expect(result).toEqual(ok(new Date(now + 60 * 60 * 1000)));
+  });
+
+  test("uses Date.now() when now is not provided", () => {
+    const before = Date.now();
+    const result = calculateSleepResumeAt("1s");
+    const after = Date.now();
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const resumeTime = result.value.getTime();
+      expect(resumeTime).toBeGreaterThanOrEqual(before + 1000);
+      expect(resumeTime).toBeLessThanOrEqual(after + 1000);
+    }
+  });
+
+  test("returns error for invalid duration", () => {
+    // @ts-expect-error testing invalid input
+    const result = calculateSleepResumeAt("invalid");
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(Error);
+    }
+  });
+
+  test("returns error for empty duration", () => {
+    // @ts-expect-error testing invalid input
+    const result = calculateSleepResumeAt("");
+
+    expect(result.ok).toBe(false);
+  });
+});
+
+describe("createSleepContext", () => {
+  test("creates sleep context with ISO string timestamp", () => {
+    const resumeAt = new Date("2025-06-15T10:30:00.000Z");
+    const context = createSleepContext(resumeAt);
+
+    expect(context).toEqual({
+      kind: "sleep",
+      resumeAt: "2025-06-15T10:30:00.000Z",
+    });
+  });
+
+  test("preserves millisecond precision", () => {
+    const resumeAt = new Date("2025-01-01T00:00:00.123Z");
+    const context = createSleepContext(resumeAt);
+
+    expect(context.resumeAt).toBe("2025-01-01T00:00:00.123Z");
+  });
+
+  test("always has kind set to sleep", () => {
+    const resumeAt = new Date();
+    const context = createSleepContext(resumeAt);
+
+    expect(context.kind).toBe("sleep");
+  });
+
+  test("creates context from current date", () => {
+    const now = new Date();
+    const context = createSleepContext(now);
+
+    expect(context.resumeAt).toBe(now.toISOString());
+  });
+});
+
+function createMockStepAttempt(overrides: Partial<StepAttempt> = {}): StepAttempt {
+  return {
+    namespaceId: "default",
+    id: "step-1",
+    workflowRunId: "workflow-1",
+    stepName: "test-step",
+    kind: "function",
+    status: "completed",
+    config: {},
+    context: null,
+    output: null,
+    error: null,
+    childWorkflowRunNamespaceId: null,
+    childWorkflowRunId: null,
+    startedAt: new Date("2025-01-01T00:00:00Z"),
+    finishedAt: new Date("2025-01-01T00:00:01Z"),
+    createdAt: new Date("2025-01-01T00:00:00Z"),
+    updatedAt: new Date("2025-01-01T00:00:01Z"),
+    ...overrides,
+  };
+}

package/src/core/step.ts

@@ -0,0 +1,152 @@
+import type { DurationString } from "./duration";
+import { parseDuration } from "./duration";
+import type { JsonValue } from "./json";
+import type { Result } from "./result";
+import { err, ok } from "./result";
+
+/**
+ * The kind of step in a workflow.
+ */
+export type StepKind = "function" | "sleep";
+
+/**
+ * Status of a step attempt through its lifecycle.
+ */
+export type StepAttemptStatus =
+  | "running"
+  | "succeeded" // deprecated in favor of 'completed'
+  | "completed"
+  | "failed";
+
+/**
+ * Context for a step attempt (currently only used for sleep steps).
+ */
+export interface StepAttemptContext {
+  kind: "sleep";
+  resumeAt: string;
+}
+
+/**
+ * StepAttempt represents a single attempt of a step within a workflow.
+ */
+export interface StepAttempt {
+  namespaceId: string;
+  id: string;
+  workflowRunId: string;
+  stepName: string;
+  kind: StepKind;
+  status: StepAttemptStatus;
+  config: JsonValue; // user-defined config
+  context: StepAttemptContext | null; // runtime execution metadata
+  output: JsonValue | null;
+  error: JsonValue | null;
+  childWorkflowRunNamespaceId: string | null;
+  childWorkflowRunId: string | null;
+  startedAt: Date | null;
+  finishedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Immutable cache for step attempts, keyed by step name.
+ */
+export type StepAttemptCache = ReadonlyMap<string, StepAttempt>;
+
+/**
+ * Create a step attempt cache from an array of attempts. Only includes
+ * successful attempts (completed or succeeded status).
+ * @param attempts - Array of step attempts to cache
+ * @returns An immutable map of step name to successful attempt
+ */
+export function createStepAttemptCacheFromAttempts(
+  attempts: readonly StepAttempt[],
+): StepAttemptCache {
+  // 'succeeded' status is deprecated in favor of 'completed'
+  const successfulAttempts = attempts.filter(
+    (attempt) => attempt.status === "succeeded" || attempt.status === "completed",
+  );
+
+  return new Map(successfulAttempts.map((attempt) => [attempt.stepName, attempt]));
+}
+
+/**
+ * Get a cached step attempt by name.
+ * @param cache - The step attempt cache
+ * @param stepName - The name of the step to look up
+ * @returns The cached attempt or undefined if not found
+ */
+export function getCachedStepAttempt(
+  cache: StepAttemptCache,
+  stepName: string,
+): StepAttempt | undefined {
+  return cache.get(stepName);
+}
+
+/**
+ * Check if a step attempt is cached (has completed successfully).
+ * @param cache - The step attempt cache
+ * @param stepName - The name of the step to check
+ * @returns True if the step has a cached successful result
+ */
+export function hasCompletedStep(cache: StepAttemptCache, stepName: string): boolean {
+  return cache.has(stepName);
+}
+
+/**
+ * Add a step attempt to the cache (returns new cache, original unchanged). This
+ * is an immutable operation.
+ * @param cache - The existing step attempt cache
+ * @param attempt - The attempt to add
+ * @returns A new cache with the attempt added
+ */
+export function addToStepAttemptCache(
+  cache: StepAttemptCache,
+  attempt: Readonly<StepAttempt>,
+): StepAttemptCache {
+  return new Map([...cache, [attempt.stepName, attempt]]);
+}
+
+/**
+ * Convert a step function result to a JSON-compatible value. Undefined values
+ * are converted to null for JSON serialization.
+ * @param result - The result from a step function
+ * @returns A JSON-serializable value
+ */
+export function normalizeStepOutput(result: unknown): JsonValue {
+  return (result ?? null) as JsonValue;
+}
+
+/**
+ * Calculate the resume time for a sleep step.
+ * @param duration - The duration string to sleep for
+ * @param now - The current timestamp (defaults to Date.now())
+ * @returns A Result containing the resume Date or an Error
+ */
+export function calculateSleepResumeAt(
+  duration: DurationString,
+  now: number = Date.now(),
+): Result<Date> {
+  const result = parseDuration(duration);
+
+  if (!result.ok) {
+    return err(result.error);
+  }
+
+  return ok(new Date(now + result.value));
+}
+
+/**
+ * Create the context object for a sleep step attempt.
+ * @param resumeAt - The time when the sleep should resume
+ * @returns The context object for the sleep step
+ */
+export function createSleepContext(resumeAt: Readonly<Date>): {
+  kind: "sleep";
+  resumeAt: string;
+} {
+  return {
+    kind: "sleep" as const,
+    resumeAt: resumeAt.toISOString(),
+  };
+}