@redflow/client 0.0.1

package/src/default.ts

@@ -0,0 +1,13 @@
+import type { RedflowClient } from "./client";
+import { createClient } from "./client";
+
+let defaultClient: RedflowClient | null = null;
+
+export function getDefaultClient(): RedflowClient {
+  if (!defaultClient) defaultClient = createClient();
+  return defaultClient;
+}
+
+export function setDefaultClient(client: RedflowClient): void {
+  defaultClient = client;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { defineWorkflow } from "./workflow";
+export type { WorkflowHandler, WorkflowHandlerContext } from "./workflow";
+
+export { createClient, defaultPrefix } from "./client";
+export type { RedflowClient, CreateClientOptions, SyncRegistryOptions } from "./client";
+
+export { startWorker } from "./worker";
+export type { StartWorkerOptions, WorkerHandle } from "./worker";
+
+export { setDefaultClient, getDefaultClient } from "./default";
+
+export { getDefaultRegistry, __unstableResetDefaultRegistryForTests } from "./registry";
+export type { WorkflowRegistry, WorkflowDefinition } from "./registry";
+
+export * from "./types";
+
+export * from "./internal/errors";

package/src/internal/errors.ts

@@ -0,0 +1,150 @@
+export class RedflowError extends Error {
+  override name = "RedflowError";
+}
+
+export class InputValidationError extends RedflowError {
+  override name = "InputValidationError";
+
+  constructor(message: string, public readonly issues?: unknown) {
+    super(message);
+  }
+}
+
+export class UnknownWorkflowError extends RedflowError {
+  override name = "UnknownWorkflowError";
+
+  constructor(public readonly workflowName: string) {
+    super(`Unknown workflow: ${workflowName}`);
+  }
+}
+
+export class CanceledError extends RedflowError {
+  override name = "CanceledError";
+  constructor(message = "Run canceled") {
+    super(message);
+  }
+}
+
+export class TimeoutError extends RedflowError {
+  override name = "TimeoutError";
+  constructor(message = "Operation timed out") {
+    super(message);
+  }
+}
+
+export class OutputSerializationError extends RedflowError {
+  override name = "OutputSerializationError";
+
+  constructor(message = "Workflow output is not JSON-serializable", public readonly causeError?: unknown) {
+    super(message);
+  }
+}
+
+/**
+ * Throw this from workflow code to immediately fail the run without retries.
+ * Useful for permanent/deterministic failures (e.g. invalid external data,
+ * business-logic violations) where retrying would produce the same result.
+ */
+export class NonRetriableError extends RedflowError {
+  override name = "NonRetriableError";
+}
+
+export type SerializedError = {
+  name: string;
+  message: string;
+  stack?: string;
+  code?: string;
+  kind?: "canceled" | "timeout" | "validation" | "unknown_workflow" | "serialization" | "non_retriable" | "error";
+};
+
+function stringifyUnknownError(err: unknown): string {
+  if (typeof err === "string") return err;
+  if (typeof err === "bigint") return err.toString();
+
+  try {
+    const json = JSON.stringify(err);
+    if (typeof json === "string") return json;
+  } catch {
+    // Fall through to a safer string conversion.
+  }
+
+  try {
+    return String(err);
+  } catch {
+    return "Unknown error";
+  }
+}
+
+export function serializeError(err: unknown): SerializedError {
+  if (err instanceof InputValidationError) {
+    return {
+      name: err.name,
+      message: err.message,
+      stack: err.stack,
+      kind: "validation",
+    };
+  }
+
+  if (err instanceof UnknownWorkflowError) {
+    return {
+      name: err.name,
+      message: err.message,
+      stack: err.stack,
+      kind: "unknown_workflow",
+    };
+  }
+
+  if (err instanceof CanceledError) {
+    return {
+      name: err.name,
+      message: err.message,
+      stack: err.stack,
+      kind: "canceled",
+    };
+  }
+
+  if (err instanceof TimeoutError) {
+    return {
+      name: err.name,
+      message: err.message,
+      stack: err.stack,
+      kind: "timeout",
+    };
+  }
+
+  if (err instanceof OutputSerializationError) {
+    return {
+      name: err.name,
+      message: err.message,
+      stack: err.stack,
+      kind: "serialization",
+    };
+  }
+
+  if (err instanceof NonRetriableError) {
+    return {
+      name: err.name,
+      message: err.message,
+      stack: err.stack,
+      kind: "non_retriable",
+    };
+  }
+
+  if (err instanceof Error) {
+    // Prefer standard-ish fields when present.
+    const anyErr = err as any;
+    return {
+      name: err.name || "Error",
+      message: err.message || String(err),
+      stack: err.stack,
+      code: typeof anyErr.code === "string" ? anyErr.code : undefined,
+      kind: "error",
+    };
+  }
+
+  return {
+    name: "Error",
+    message: stringifyUnknownError(err),
+    kind: "error",
+  };
+}

package/src/internal/json.ts

@@ -0,0 +1,32 @@
+const REDFLOW_UNDEFINED_TOKEN = "__redflow_undefined_raw__:v1";
+
+export function safeJsonStringify(value: unknown): string {
+  if (value === undefined) {
+    return REDFLOW_UNDEFINED_TOKEN;
+  }
+
+  const json = JSON.stringify(value);
+  if (json === undefined) {
+    throw new Error("Value is not JSON-serializable");
+  }
+  return json;
+}
+
+export function safeJsonParse<T = unknown>(value: string | null): T {
+  if (value == null) throw new Error("Expected JSON string, got null");
+
+  if (value === REDFLOW_UNDEFINED_TOKEN) {
+    return undefined as T;
+  }
+
+  return JSON.parse(value) as T;
+}
+
+export function safeJsonTryParse<T = unknown>(value: string | null): T | undefined {
+  if (value == null) return undefined;
+  try {
+    return safeJsonParse<T>(value);
+  } catch {
+    return undefined;
+  }
+}

package/src/internal/keys.ts

@@ -0,0 +1,38 @@
+export type KeyPrefix = string;
+
+export function withPrefix(prefix: KeyPrefix, suffix: string): string {
+  const p = prefix.endsWith(":") ? prefix.slice(0, -1) : prefix;
+  const s = suffix.startsWith(":") ? suffix.slice(1) : suffix;
+  return `${p}:${s}`;
+}
+
+function encodeCompositePart(value: string): string {
+  return `${value.length}:${value}`;
+}
+
+export const keys = {
+  workflows: (prefix: KeyPrefix) => withPrefix(prefix, "workflows"),
+  workflow: (prefix: KeyPrefix, workflowName: string) => withPrefix(prefix, `workflow:${workflowName}`),
+  // Keep run indexes in a separate namespace to avoid collisions with workflow
+  // metadata keys when workflow names contain suffix-like segments (e.g. ":runs").
+  workflowRuns: (prefix: KeyPrefix, workflowName: string) => withPrefix(prefix, `workflow-runs:${workflowName}`),
+  eventWorkflows: (prefix: KeyPrefix, eventName: string) => withPrefix(prefix, `event:${eventName}:workflows`),
+
+  runsCreated: (prefix: KeyPrefix) => withPrefix(prefix, "runs:created"),
+  runsStatus: (prefix: KeyPrefix, status: string) => withPrefix(prefix, `runs:status:${status}`),
+
+  run: (prefix: KeyPrefix, runId: string) => withPrefix(prefix, `run:${runId}`),
+  runSteps: (prefix: KeyPrefix, runId: string) => withPrefix(prefix, `run:${runId}:steps`),
+  runLease: (prefix: KeyPrefix, runId: string) => withPrefix(prefix, `run:${runId}:lease`),
+
+  queueReady: (prefix: KeyPrefix, queue: string) => withPrefix(prefix, `q:${queue}:ready`),
+  queueProcessing: (prefix: KeyPrefix, queue: string) => withPrefix(prefix, `q:${queue}:processing`),
+  queueScheduled: (prefix: KeyPrefix, queue: string) => withPrefix(prefix, `q:${queue}:scheduled`),
+
+  cronDef: (prefix: KeyPrefix) => withPrefix(prefix, "cron:def"),
+  cronNext: (prefix: KeyPrefix) => withPrefix(prefix, "cron:next"),
+  lockCron: (prefix: KeyPrefix) => withPrefix(prefix, "lock:cron"),
+
+  idempotency: (prefix: KeyPrefix, workflowName: string, idempotencyKey: string) =>
+    withPrefix(prefix, `idempo:${encodeCompositePart(workflowName)}:${encodeCompositePart(idempotencyKey)}`),
+};

package/src/internal/sleep.ts

@@ -0,0 +1,4 @@
+export function sleep(ms: number): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/internal/time.ts

@@ -0,0 +1,3 @@
+export function nowMs(): number {
+  return Date.now();
+}

package/src/registry.ts

@@ -0,0 +1,55 @@
+import type { ZodTypeAny } from "zod";
+import type { DefineWorkflowOptions, StepApi } from "./types";
+
+export type WorkflowHandlerContext<TInput> = {
+  input: TInput;
+  run: {
+    id: string;
+    workflow: string;
+    queue: string;
+    attempt: number;
+    maxAttempts: number;
+  };
+  step: StepApi;
+  signal: AbortSignal;
+};
+
+export type WorkflowHandler<TInput, TOutput> = (ctx: WorkflowHandlerContext<TInput>) => Promise<TOutput>;
+
+export type WorkflowDefinition<TSchema extends ZodTypeAny | undefined = ZodTypeAny | undefined, TOutput = unknown> = {
+  options: DefineWorkflowOptions<TSchema>;
+  handler: WorkflowHandler<any, TOutput>;
+};
+
+export class WorkflowRegistry {
+  private readonly workflows = new Map<string, WorkflowDefinition>();
+
+  register(def: WorkflowDefinition): void {
+    // Last one wins. This is helpful for dev/hmr and test isolation.
+    this.workflows.set(def.options.name, def);
+  }
+
+  get(name: string): WorkflowDefinition | undefined {
+    return this.workflows.get(name);
+  }
+
+  list(): WorkflowDefinition[] {
+    return [...this.workflows.values()];
+  }
+
+  clear(): void {
+    this.workflows.clear();
+  }
+}
+
+let defaultRegistry: WorkflowRegistry | null = null;
+
+export function getDefaultRegistry(): WorkflowRegistry {
+  if (!defaultRegistry) defaultRegistry = new WorkflowRegistry();
+  return defaultRegistry;
+}
+
+/** @internal */
+export function __unstableResetDefaultRegistryForTests(): void {
+  defaultRegistry?.clear();
+}

package/src/types.ts

@@ -0,0 +1,181 @@
+import type { ZodTypeAny } from "zod";
+
+export type RunStatus = "scheduled" | "queued" | "running" | "succeeded" | "failed" | "canceled";
+export type StepStatus = "running" | "succeeded" | "failed";
+
+export type WorkflowTriggers = {
+  events?: string[];
+  cron?: CronTrigger[];
+};
+
+export type CronTrigger = {
+  /** Standard cron expression with seconds support (6-field) via croner. */
+  expression: string;
+  timezone?: string;
+  input?: unknown;
+  /** Optional stable id; otherwise derived from expression+input. */
+  id?: string;
+};
+
+export type WorkflowRetries = {
+  /** Total attempts including the first one. Default: 1 (no retries). */
+  maxAttempts?: number;
+};
+
+export type OnFailureContext = {
+  error: unknown;
+  input: unknown;
+  run: {
+    id: string;
+    workflow: string;
+    queue: string;
+    attempt: number;
+    maxAttempts: number;
+  };
+};
+
+export type DefineWorkflowOptions<TSchema extends ZodTypeAny | undefined = ZodTypeAny | undefined> = {
+  name: string;
+  queue?: string;
+  schema?: TSchema;
+  triggers?: WorkflowTriggers;
+  retries?: WorkflowRetries;
+  /** Called when the run reaches terminal failure (retries exhausted or non-retriable error). Not called on cancellation. */
+  onFailure?: (ctx: OnFailureContext) => void | Promise<void>;
+};
+
+export type StepRunOptions = {
+  name: string;
+  timeoutMs?: number;
+};
+
+export type StepRunWorkflowOptions = StepRunOptions & {
+  run?: Omit<RunOptions, "idempotencyKey" | "__maxAttemptsOverride">;
+  result?: {
+    timeoutMs?: number;
+    pollMs?: number;
+  };
+  /**
+   * Optional override for child-run idempotency.
+   * By default, redflow derives a stable key from parent run id + step name + child workflow name.
+   */
+  idempotencyKey?: string;
+};
+
+export type StepEmitEventOptions = StepRunOptions & {
+  event: string;
+  emit?: Omit<EmitEventOptions, "idempotencyKey">;
+  /**
+   * Optional override for emit idempotency.
+   * By default, redflow derives a stable key from parent run id + step name + event name.
+   */
+  idempotencyKey?: string;
+};
+
+export type StepScheduleEventOptions = StepRunOptions & {
+  event: string;
+  schedule: Omit<ScheduleEventOptions, "idempotencyKey">;
+  /**
+   * Optional override for schedule idempotency.
+   * By default, redflow derives a stable key from parent run id + step name + event name.
+   */
+  idempotencyKey?: string;
+};
+
+export type RunOptions = {
+  availableAt?: Date;
+  idempotencyKey?: string;
+  /** TTL for the idempotency key in seconds. Default: 7 days (604 800s). */
+  idempotencyTtl?: number;
+  queueOverride?: string;
+  /** @internal Runtime hint used by defineWorkflow(). */
+  __maxAttemptsOverride?: number;
+};
+
+export type EmitEventOptions = {
+  idempotencyKey?: string;
+  /** TTL for the idempotency key in seconds. Default: 7 days (604 800s). */
+  idempotencyTtl?: number;
+};
+
+export type ScheduleEventOptions = EmitEventOptions & {
+  availableAt: Date;
+};
+
+export type RunHandle<TOutput = unknown> = {
+  id: string;
+  getState(): Promise<RunState | null>;
+  result(options?: { timeoutMs?: number; pollMs?: number }): Promise<TOutput>;
+};
+
+export type WorkflowLike<TInput = unknown, TOutput = unknown> = {
+  name: string;
+  run(input: TInput, options?: RunOptions): Promise<RunHandle<TOutput>>;
+};
+
+export type StepApi = {
+  run<T>(options: StepRunOptions, fn: (ctx: { signal: AbortSignal }) => Promise<T>): Promise<T>;
+  runWorkflow<TInput, TOutput>(
+    options: StepRunWorkflowOptions,
+    workflow: WorkflowLike<TInput, TOutput>,
+    input: TInput,
+  ): Promise<TOutput>;
+  emitEvent(options: StepEmitEventOptions, payload: unknown): Promise<string[]>;
+  scheduleEvent(options: StepScheduleEventOptions, payload: unknown): Promise<string[]>;
+};
+
+export type RunState = {
+  id: string;
+  workflow: string;
+  queue: string;
+  status: RunStatus;
+  input: unknown;
+  output?: unknown;
+  error?: unknown;
+  attempt: number;
+  maxAttempts: number;
+  createdAt: number;
+  availableAt?: number;
+  startedAt?: number;
+  finishedAt?: number;
+  cancelRequestedAt?: number;
+  cancelReason?: string;
+};
+
+export type StepState = {
+  name: string;
+  status: StepStatus;
+  startedAt?: number;
+  finishedAt?: number;
+  output?: unknown;
+  error?: unknown;
+};
+
+export type ListRunsParams = {
+  status?: RunStatus;
+  workflow?: string;
+  offset?: number;
+  limit?: number;
+};
+
+export type ListedRun = {
+  id: string;
+  workflow: string;
+  queue: string;
+  status: RunStatus;
+  error?: unknown;
+  createdAt: number;
+  availableAt?: number;
+  startedAt?: number;
+  finishedAt?: number;
+  attempt: number;
+  maxAttempts: number;
+};
+
+export type WorkflowMeta = {
+  name: string;
+  queue: string;
+  triggers?: WorkflowTriggers;
+  retries?: WorkflowRetries;
+  updatedAt: number;
+};