@redflow/client 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,280 @@
+# redflow
+
+Redis-backed workflow runtime for Bun.
+
+## Warning
+
+This project is still in early alpha stage.
+
+## Install
+
+```bash
+bun add @redflow/client -E
+```
+
+## Most users start here: `defineWorkflow`
+
+```ts
+import { defineWorkflow } from "@redflow/client";
+import { z } from "zod";
+
+export const sendWelcomeEmail = defineWorkflow(
+  "send-welcome-email",
+  {
+    schema: z.object({ userId: z.string().min(1) })
+  },
+  async ({ input, step }) => {
+    const user = await step.run({ name: "fetch-user" }, async () => {
+      return { id: input.userId, email: "test@example.com" };
+    });
+
+    await step.run({ name: "send-email" }, async () => {
+      return { ok: true, to: user.email };
+    });
+
+    return { sent: true };
+  },
+);
+```
+
+Handler context gives you:
+
+- `input` — validated input (if `schema` is provided)
+- `run` — run metadata (`id`, `workflow`, `queue`, `attempt`, `maxAttempts`)
+- `signal` — cancellation signal
+- `step` — durable step API
+
+## Step API (inside workflow handlers)
+
+### 1) `step.run`
+
+Use for durable, cached units of work.
+
+```ts
+const payment = await step.run(
+  { name: "capture-payment", timeoutMs: 4_000 },
+  async ({ signal }) => {
+    // pass signal to external APIs when supported
+    return { chargeId: "ch_123" };
+  },
+);
+```
+
+### 2) `step.runWorkflow`
+
+Use when parent workflow must wait for child workflow output.
+
+```ts
+const receipt = await step.runWorkflow(
+  {
+    name: "send-receipt",
+    timeoutMs: 20_000,
+    runAt: new Date(Date.now() + 500),
+    idempotencyTtl: 60 * 60 * 24,
+    idempotencyKey: `receipt:${input.orderId}`,
+  },
+  sendReceiptWorkflow,
+  {
+    orderId: input.orderId,
+    email: input.email,
+    totalCents: input.totalCents,
+  },
+);
+```
+
+`step.runWorkflow` waits for child completion until the step is canceled.
+Set `timeoutMs` to cap total waiting time.
+
+### 3) `step.emitWorkflow`
+
+Use to trigger child workflow and keep only child run id.
+
+```ts
+const analyticsRunId = await step.emitWorkflow(
+  {
+    name: "emit-analytics",
+    runAt: new Date(Date.now() + 2_000),
+    idempotencyTtl: 60 * 60,
+    idempotencyKey: `analytics:${input.orderId}`,
+  },
+  analyticsWorkflow,
+  {
+    orderId: input.orderId,
+    totalCents: input.totalCents,
+  },
+);
+```
+
+## Run workflows
+
+The object returned by `defineWorkflow(...)` has `.run(...)`.
+
+```ts
+const handle = await sendWelcomeEmail.run(
+  { userId: "user_123" },
+  {
+    idempotencyKey: "welcome:user_123",
+    idempotencyTtl: 60 * 60,
+  },
+);
+
+const output = await handle.result({ timeoutMs: 15_000 });
+```
+
+Delayed run:
+
+```ts
+const handle = await sendWelcomeEmail.run(
+  { userId: "user_789" },
+  {
+    runAt: new Date(Date.now() + 60_000),
+    idempotencyKey: "welcome:user_789:delayed",
+  },
+);
+
+const output = await handle.result({ timeoutMs: 90_000 });
+```
+
+## Start a worker
+
+Import workflows, then run `startWorker()`.
+
+```ts
+import { startWorker } from "@redflow/client";
+import "./workflows";
+
+const worker = await startWorker({
+  url: process.env.REDIS_URL,
+  prefix: "redflow:prod",
+  concurrency: 4,
+});
+```
+
+Explicit queues + runtime tuning:
+
+```ts
+const worker = await startWorker({
+  url: process.env.REDIS_URL,
+  prefix: "redflow:prod",
+  queues: ["critical", "io", "analytics"],
+  concurrency: 8,
+  runtime: {
+    leaseMs: 5000,
+    blmoveTimeoutSec: 1,
+    reaperIntervalMs: 500,
+  },
+});
+```
+
+## Workflow options examples
+
+### Cron
+
+```ts
+defineWorkflow(
+  "digest-cron",
+  {
+    queue: "ops",
+    cron: [
+      { id: "digest-10s", expression: "*/10 * * * * *" },
+      { expression: "0 */5 * * * *", timezone: "UTC", input: { source: "cron" } },
+    ],
+  },
+  async ({ input }) => ({ tick: true, input }),
+);
+```
+
+### onFailure
+
+```ts
+import { NonRetriableError } from "@redflow/client";
+
+defineWorkflow(
+  "invoice-sync",
+  {
+    queue: "billing",
+    retries: { maxAttempts: 4 },
+    onFailure: async ({ error, run }) => {
+      console.error("workflow failed", run.id, run.workflow, error);
+    },
+  },
+  async () => {
+    throw new NonRetriableError("invoice not found in upstream system");
+  },
+);
+```
+
+## Client APIs (advanced)
+
+Use this when you need manual triggering, inspection, registry sync, or custom client setup.
+
+### Setup
+
+```ts
+import { createClient, setDefaultClient } from "@redflow/client";
+
+const client = createClient({
+  url: process.env.REDIS_URL,
+  prefix: "redflow:prod",
+});
+
+setDefaultClient(client);
+```
+
+### Trigger by workflow name
+
+```ts
+const h1 = await client.runByName(
+  "checkout",
+  { orderId: "ord_2", totalCents: 1999 },
+  {
+    queueOverride: "critical",
+    idempotencyKey: "checkout:ord_2",
+  },
+);
+
+const h2 = await client.emitWorkflow(
+  "send-welcome-email",
+  { userId: "user_456" },
+  { idempotencyKey: "welcome:user_456" },
+);
+```
+
+### Inspect and control runs
+
+```ts
+const run = await client.getRun("run_123");
+const steps = await client.getRunSteps("run_123");
+
+const recent = await client.listRuns({ limit: 50 });
+const failedCheckout = await client.listRuns({
+  workflow: "checkout",
+  status: "failed",
+  limit: 20,
+});
+
+const workflows = await client.listWorkflows();
+const checkoutMeta = await client.getWorkflowMeta("checkout");
+
+const canceled = await client.cancelRun("run_123", { reason: "requested by user" });
+```
+
+### RunHandle
+
+```ts
+const handle = await client.emitWorkflow("checkout", { orderId: "ord_3", totalCents: 2999 });
+
+const state = await handle.getState();
+console.log(state?.status);
+
+const output = await handle.result({ timeoutMs: 30_000 });
+console.log(output);
+```
+
+### Registry sync ownership
+
+```ts
+import { getDefaultRegistry } from "@redflow/client";
+
+await client.syncRegistry(getDefaultRegistry(), { owner: "billing-service" });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redflow/client",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "src/index.ts",
   "module": "src/index.ts",

package/src/client.ts

@@ -17,12 +17,11 @@ import { safeJsonParse, safeJsonStringify, safeJsonTryParse } from "./internal/j
 import { nowMs } from "./internal/time";
 import { sleep } from "./internal/sleep";
 import type {
-  EmitEventOptions,
+  EmitWorkflowOptions,
   ListedRun,
   ListRunsParams,
   RunHandle,
   RunOptions,
-  ScheduleEventOptions,
   RunState,
   RunStatus,
   StepState,
@@ -50,6 +49,7 @@ export function defaultPrefix(): string {
 
 const STALE_WORKFLOW_GRACE_MS = 30_000;
 const IDEMPOTENCY_TTL_SEC = 60 * 60 * 24 * 7;
+const POLL_MS = 250;
 
 const ENQUEUE_RUN_LUA = `
 local runId = ARGV[1]
@@ -249,10 +249,6 @@ function encodeCompositePart(value: string): string {
   return `${value.length}:${value}`;
 }
 
-function eventScopedIdempotencyKey(eventName: string, idempotencyKey: string): string {
-  return `event:${encodeCompositePart(eventName)}:${encodeCompositePart(idempotencyKey)}`;
-}
-
 function defaultRegistryOwner(): string {
   const envOwner = process.env.REDFLOW_SYNC_OWNER?.trim();
   if (envOwner) return envOwner;
@@ -356,70 +352,35 @@ export class RedflowClient {
     const data = await this.redis.hgetall(keys.workflow(this.prefix, name));
     if (!data || Object.keys(data).length === 0) return null;
 
-    const triggers = safeJsonTryParse<any>(data.triggersJson ?? null) as any;
+    const cron = safeJsonTryParse<any>(data.cronJson ?? null) as any;
     const retries = safeJsonTryParse<any>(data.retriesJson ?? null) as any;
     const updatedAt = Number(data.updatedAt ?? "0");
     const queue = data.queue ?? "default";
     return {
       name,
       queue,
-      triggers,
+      cron: Array.isArray(cron) && cron.length > 0 ? cron : undefined,
       retries,
       updatedAt,
     };
   }
 
-  async emitEvent(name: string, payload: unknown, options?: EmitEventOptions): Promise<string[]> {
-    return await this.dispatchEvent(name, payload, {
+  /**
+   * Trigger a workflow by name. This is a direct run, not a fan-out.
+   * Use this when you want to start a workflow from outside a handler.
+   */
+  async emitWorkflow<TOutput = unknown>(
+    workflowName: string,
+    input: unknown,
+    options?: EmitWorkflowOptions,
+  ): Promise<RunHandle<TOutput>> {
+    return await this.runByName<TOutput>(workflowName, input, {
       idempotencyKey: options?.idempotencyKey,
       idempotencyTtl: options?.idempotencyTtl,
+      runAt: options?.runAt,
     });
   }
 
-  async scheduleEvent(name: string, payload: unknown, options: ScheduleEventOptions): Promise<string[]> {
-    if (!options || !isValidDate(options.availableAt)) {
-      throw new Error("Invalid 'availableAt' for scheduleEvent");
-    }
-
-    return await this.dispatchEvent(name, payload, {
-      idempotencyKey: options.idempotencyKey,
-      idempotencyTtl: options.idempotencyTtl,
-      availableAt: options.availableAt,
-    });
-  }
-
-  private async dispatchEvent(
-    name: string,
-    payload: unknown,
-    options: { idempotencyKey?: string; idempotencyTtl?: number; availableAt?: Date },
-  ): Promise<string[]> {
-    const subsKey = keys.eventWorkflows(this.prefix, name);
-    const workflowNames = await this.redis.smembers(subsKey);
-    const runIds: string[] = [];
-
-    for (const workflowName of workflowNames) {
-      const idempotencyKey = options.idempotencyKey ? eventScopedIdempotencyKey(name, options.idempotencyKey) : undefined;
-      try {
-        const handle = await this.runByName(workflowName, payload, {
-          idempotencyKey,
-          idempotencyTtl: options.idempotencyTtl,
-          availableAt: options.availableAt,
-        });
-        runIds.push(handle.id);
-      } catch (err) {
-        if (err instanceof UnknownWorkflowError) {
-          // Stale event subscriptions can remain briefly across deployments.
-          // Drop them lazily so valid subscribers still receive events.
-          await this.redis.srem(subsKey, workflowName);
-          continue;
-        }
-        throw err;
-      }
-    }
-
-    return runIds;
-  }
-
   async runByName<TOutput = unknown>(workflowName: string, input: unknown, options?: RunOptions): Promise<RunHandle<TOutput>> {
     const queueFromRegistry = await this.getQueueForWorkflow(workflowName);
     const queue = options?.queueOverride ?? queueFromRegistry;
@@ -440,7 +401,7 @@ export class RedflowClient {
       workflowName,
       queue,
       input,
-      availableAt: options?.availableAt,
+      availableAt: options?.runAt,
       idempotencyKey: options?.idempotencyKey,
       idempotencyTtl: options?.idempotencyTtl,
       maxAttempts,
@@ -606,12 +567,11 @@ export class RedflowClient {
 
   async waitForResult<TOutput = unknown>(
     runId: string,
-    options?: { timeoutMs?: number; pollMs?: number },
+    options?: { timeoutMs?: number },
   ): Promise<TOutput> {
     const timeoutMs = options?.timeoutMs ?? 30_000;
-    const pollMs = options?.pollMs ?? 250;
     const deadline = nowMs() + timeoutMs;
-    const missingGraceMs = Math.max(250, Math.min(2000, pollMs * 4));
+    const missingGraceMs = Math.max(250, Math.min(2000, POLL_MS * 4));
 
     let missingSince: number | null = null;
     let seenState = false;
@@ -630,7 +590,7 @@ export class RedflowClient {
         }
 
         if (t > deadline) throw new TimeoutError(`Timed out waiting for run result (${runId})`);
-        await sleep(pollMs);
+        await sleep(POLL_MS);
         continue;
       }
 
@@ -642,7 +602,7 @@ export class RedflowClient {
       if (state.status === "canceled") throw new CanceledError(state.cancelReason ? `Run canceled: ${state.cancelReason}` : "Run canceled");
 
       if (nowMs() > deadline) throw new TimeoutError(`Timed out waiting for run result (${runId})`);
-      await sleep(pollMs);
+      await sleep(POLL_MS);
     }
   }
 
@@ -657,39 +617,24 @@ export class RedflowClient {
     for (const def of defs) {
       const name = def.options.name;
       const queue = def.options.queue ?? "default";
-      const triggers = def.options.triggers ?? {};
+      const cron = def.options.cron ?? [];
       const retries = def.options.retries ?? {};
       const updatedAt = nowMs();
 
       const customCronIds = new Set<string>();
-      for (const cron of triggers.cron ?? []) {
-        if (!cron.id) continue;
-        if (customCronIds.has(cron.id)) {
-          throw new Error(`Duplicate cron trigger id '${cron.id}' in workflow '${name}'`);
+      for (const c of cron) {
+        if (!c.id) continue;
+        if (customCronIds.has(c.id)) {
+          throw new Error(`Duplicate cron trigger id '${c.id}' in workflow '${name}'`);
         }
-        customCronIds.add(cron.id);
+        customCronIds.add(c.id);
       }
 
       const workflowKey = keys.workflow(this.prefix, name);
       await this.redis.sadd(keys.workflows(this.prefix), name);
 
-      const prevEvents = safeJsonTryParse<string[]>(await this.redis.hget(workflowKey, "eventsJson")) ?? [];
-      const nextEvents = Array.from(new Set(triggers.events ?? [])).sort();
-
-      for (const ev of prevEvents) {
-        if (!nextEvents.includes(ev)) {
-          await this.redis.srem(keys.eventWorkflows(this.prefix, ev), name);
-        }
-      }
-
-      for (const ev of nextEvents) {
-        if (!prevEvents.includes(ev)) {
-          await this.redis.sadd(keys.eventWorkflows(this.prefix, ev), name);
-        }
-      }
-
       const prevCronIds = safeJsonTryParse<string[]>(await this.redis.hget(workflowKey, "cronIdsJson")) ?? [];
-      const nextCronIds = (triggers.cron ?? []).map((c) => this.computeCronId(name, c.id, c.expression, c.timezone, c.input));
+      const nextCronIds = cron.map((c) => this.computeCronId(name, c.id, c.expression, c.timezone, c.input));
 
       const nextCronIdSet = new Set(nextCronIds);
       for (const oldId of prevCronIds) {
@@ -699,23 +644,23 @@ export class RedflowClient {
         }
       }
 
-      for (let i = 0; i < (triggers.cron ?? []).length; i++) {
-        const cron = triggers.cron![i]!;
+      for (let i = 0; i < cron.length; i++) {
+        const c = cron[i]!;
         const cronId = nextCronIds[i]!;
-        const cronInput = Object.prototype.hasOwnProperty.call(cron, "input") ? cron.input : {};
+        const cronInput = Object.prototype.hasOwnProperty.call(c, "input") ? c.input : {};
 
         const cronDef = {
           id: cronId,
           workflow: name,
           queue,
-          expression: cron.expression,
-          timezone: cron.timezone,
+          expression: c.expression,
+          timezone: c.timezone,
           inputJson: safeJsonStringify(cronInput),
         };
 
         await this.redis.hset(keys.cronDef(this.prefix), { [cronId]: safeJsonStringify(cronDef) });
 
-        const nextAt = this.computeNextCronAtMs(cron.expression, cron.timezone);
+        const nextAt = this.computeNextCronAtMs(c.expression, c.timezone);
         if (nextAt != null) {
           await this.redis.zadd(keys.cronNext(this.prefix), nextAt, cronId);
         } else {
@@ -728,9 +673,8 @@ export class RedflowClient {
         queue,
         owner,
         updatedAt: String(updatedAt),
-        triggersJson: safeJsonStringify(triggers),
+        cronJson: safeJsonStringify(cron),
         retriesJson: safeJsonStringify(retries),
-        eventsJson: safeJsonStringify(nextEvents),
         cronIdsJson: safeJsonStringify(nextCronIds),
       };
 
@@ -803,11 +747,6 @@ export class RedflowClient {
   private async deleteWorkflowMetadata(workflowName: string): Promise<void> {
     const workflowKey = keys.workflow(this.prefix, workflowName);
 
-    const prevEvents = safeJsonTryParse<string[]>(await this.redis.hget(workflowKey, "eventsJson")) ?? [];
-    for (const eventName of prevEvents) {
-      await this.redis.srem(keys.eventWorkflows(this.prefix, eventName), workflowName);
-    }
-
     const prevCronIds = safeJsonTryParse<string[]>(await this.redis.hget(workflowKey, "cronIdsJson")) ?? [];
     for (const cronId of prevCronIds) {
       await this.redis.hdel(keys.cronDef(this.prefix), cronId);
@@ -1108,4 +1047,4 @@ export function makeErrorJson(err: unknown): string {
   } catch {
     return '{"name":"Error","message":"Failed to serialize original error","kind":"error"}';
   }
-}
+}

package/src/internal/keys.ts

@@ -16,7 +16,6 @@ export const keys = {
   // 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}`),
@@ -35,4 +34,4 @@ export const keys = {
 
   idempotency: (prefix: KeyPrefix, workflowName: string, idempotencyKey: string) =>
     withPrefix(prefix, `idempo:${encodeCompositePart(workflowName)}:${encodeCompositePart(idempotencyKey)}`),
-};
+};

package/src/types.ts

@@ -3,11 +3,6 @@ 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;
@@ -38,7 +33,7 @@ export type DefineWorkflowOptions<TSchema extends ZodTypeAny | undefined = ZodTy
   name: string;
   queue?: string;
   schema?: TSchema;
-  triggers?: WorkflowTriggers;
+  cron?: CronTrigger[];
   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>;
@@ -46,15 +41,20 @@ export type DefineWorkflowOptions<TSchema extends ZodTypeAny | undefined = ZodTy
 
 export type StepRunOptions = {
   name: string;
+  /**
+   * Overall timeout for the step execution.
+   * For step.runWorkflow this also bounds child result waiting.
+   */
   timeoutMs?: number;
 };
 
 export type StepRunWorkflowOptions = StepRunOptions & {
-  run?: Omit<RunOptions, "idempotencyKey" | "__maxAttemptsOverride">;
-  result?: {
-    timeoutMs?: number;
-    pollMs?: number;
-  };
+  /** Earliest time when the child run becomes eligible for processing. */
+  runAt?: Date;
+  /** Override the queue for the child run. */
+  queueOverride?: string;
+  /** TTL for the idempotency key in seconds. Default: 7 days. */
+  idempotencyTtl?: number;
   /**
    * Optional override for child-run idempotency.
    * By default, redflow derives a stable key from parent run id + step name + child workflow name.
@@ -62,28 +62,23 @@ export type StepRunWorkflowOptions = StepRunOptions & {
   idempotencyKey?: string;
 };
 
-export type StepEmitEventOptions = StepRunOptions & {
-  event: string;
-  emit?: Omit<EmitEventOptions, "idempotencyKey">;
+export type StepEmitWorkflowOptions = StepRunOptions & {
+  /** Earliest time when the run becomes eligible for processing. */
+  runAt?: Date;
+  /** Override the queue for the run. */
+  queueOverride?: string;
+  /** TTL for the idempotency key in seconds. Default: 7 days. */
+  idempotencyTtl?: number;
   /**
    * 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.
+   * By default, redflow derives a stable key from parent run id + step name + workflow name.
    */
   idempotencyKey?: string;
 };
 
 export type RunOptions = {
-  availableAt?: Date;
+  /** Earliest time when the run becomes eligible for processing. */
+  runAt?: Date;
   idempotencyKey?: string;
   /** TTL for the idempotency key in seconds. Default: 7 days (604 800s). */
   idempotencyTtl?: number;
@@ -92,20 +87,18 @@ export type RunOptions = {
   __maxAttemptsOverride?: number;
 };
 
-export type EmitEventOptions = {
+export type EmitWorkflowOptions = {
+  /** Earliest time when the run becomes eligible for processing. */
+  runAt?: Date;
   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>;
+  result(options?: { timeoutMs?: number }): Promise<TOutput>;
 };
 
 export type WorkflowLike<TInput = unknown, TOutput = unknown> = {
@@ -120,8 +113,7 @@ export type StepApi = {
     workflow: WorkflowLike<TInput, TOutput>,
     input: TInput,
   ): Promise<TOutput>;
-  emitEvent(options: StepEmitEventOptions, payload: unknown): Promise<string[]>;
-  scheduleEvent(options: StepScheduleEventOptions, payload: unknown): Promise<string[]>;
+  emitWorkflow(options: StepEmitWorkflowOptions, workflow: WorkflowLike, input: unknown): Promise<string>;
 };
 
 export type RunState = {
@@ -175,7 +167,7 @@ export type ListedRun = {
 export type WorkflowMeta = {
   name: string;
   queue: string;
-  triggers?: WorkflowTriggers;
+  cron?: CronTrigger[];
   retries?: WorkflowRetries;
   updatedAt: number;
-};
+};