@chidchanun/bcp 0.2.10 → 0.2.12

package/packages/client/src/events.ts

@@ -0,0 +1,31 @@
+export {
+    createEventBus,
+    createMemoryOutboxStore,
+    createOutboxDispatcher,
+    createOutboxMigrationSql,
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "../../server/src/events.js";
+
+export type {
+    ClaimOutboxEventsOptions,
+    CleanupOutboxOptions,
+    EventBus,
+    FailOutboxEventOptions,
+    MemoryOutboxStore,
+    OutboxDispatcher,
+    OutboxDispatcherOptions,
+    OutboxDispatcherRunner,
+    OutboxEventHandler,
+    OutboxEventHandlerContext,
+    OutboxEventRecord,
+    OutboxEventState,
+    OutboxRetryDelay,
+    OutboxStats,
+    OutboxStore,
+    PublishOutboxEventOptions,
+    SqlOutboxStore,
+    SqlOutboxStoreOptions,
+    TransactionalOutbox,
+    TransactionalOutboxOptions,
+} from "../../server/src/events.js";

package/packages/client/src/workflow.mjs

@@ -0,0 +1,601 @@
+// packages/server/src/workflow.ts
+import { randomUUID } from "node:crypto";
+function createMemoryWorkflowStore() {
+  const runs = /* @__PURE__ */ new Map();
+  return {
+    async create(run) {
+      if (runs.has(run.id)) {
+        throw new Error(`BCP Workflow: run id "${run.id}" already exists.`);
+      }
+      runs.set(run.id, cloneRun(run));
+    },
+    async update(run) {
+      if (!runs.has(run.id)) {
+        throw new Error(`BCP Workflow: run id "${run.id}" does not exist.`);
+      }
+      runs.set(run.id, cloneRun(run));
+    },
+    async get(id) {
+      const run = runs.get(id);
+      return run ? cloneRun(run) : null;
+    },
+    async list(workflowName) {
+      return [...runs.values()].filter((run) => !workflowName || run.workflowName === workflowName).map(cloneRun).sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+    },
+    async claim(id, options) {
+      const run = runs.get(id);
+      if (!run) {
+        return false;
+      }
+      if (run.leaseOwner && run.leaseOwner !== options.ownerId && run.leaseUntil !== void 0 && run.leaseUntil > options.now) {
+        return false;
+      }
+      run.leaseOwner = options.ownerId;
+      run.leaseUntil = options.now + options.leaseMs;
+      return true;
+    },
+    async release(id, ownerId) {
+      const run = runs.get(id);
+      if (!run || run.leaseOwner !== ownerId) {
+        return;
+      }
+      run.leaseOwner = void 0;
+      run.leaseUntil = void 0;
+    },
+    clear() {
+      runs.clear();
+    }
+  };
+}
+function createWorkflow(name, configure, options = {}) {
+  const workflowName = normalizeText(name, "workflow name");
+  const store = options.store ?? createMemoryWorkflowStore();
+  const queue = options.queue;
+  const now = options.now ?? Date.now;
+  const idFactory = options.idFactory ?? randomUUID;
+  const ownerId = normalizeText(options.ownerId ?? `workflow-${randomUUID()}`, "ownerId");
+  const leaseMs = positiveInteger(options.leaseMs ?? 3e4, "leaseMs");
+  const defaultMaxAttempts = positiveInteger(
+    options.defaultMaxAttempts ?? 1,
+    "defaultMaxAttempts"
+  );
+  const defaultRetryDelay = options.retryDelayMs ?? 0;
+  const definitions = [];
+  const ids = /* @__PURE__ */ new Set();
+  const builder = {
+    step(id, handler, stepOptions = {}) {
+      definitions.push(makeStep(id, handler, stepOptions, defaultMaxAttempts, ids));
+      return builder;
+    },
+    parallel(id, configureParallel) {
+      const parallelId = reserveId(id, ids);
+      const children = [];
+      const childIds = /* @__PURE__ */ new Set();
+      const parallelBuilder = {
+        step(childId, handler, stepOptions = {}) {
+          children.push(
+            makeStep(childId, handler, stepOptions, defaultMaxAttempts, childIds)
+          );
+          return parallelBuilder;
+        }
+      };
+      if (typeof configureParallel !== "function") {
+        throw new TypeError("BCP Workflow: parallel configure callback is required.");
+      }
+      configureParallel(parallelBuilder);
+      if (children.length === 0) {
+        throw new Error(`BCP Workflow: parallel step "${parallelId}" must contain child steps.`);
+      }
+      definitions.push({ kind: "parallel", id: parallelId, steps: children });
+      return builder;
+    },
+    delay(id, durationMs) {
+      definitions.push({
+        kind: "delay",
+        id: reserveId(id, ids),
+        durationMs: nonNegativeNumber(durationMs, "delay durationMs")
+      });
+      return builder;
+    }
+  };
+  if (typeof configure !== "function") {
+    throw new TypeError("BCP Workflow: configure callback is required.");
+  }
+  configure(builder);
+  if (definitions.length === 0) {
+    throw new Error("BCP Workflow: at least one step is required.");
+  }
+  const queueJobName = `bcp.workflow.${workflowName}`;
+  const unregisterQueueHandler = queue ? queue.register(queueJobName, async ({ payload, signal }) => {
+    await execute(payload.runId, signal);
+  }) : void 0;
+  const api = {
+    name: workflowName,
+    store,
+    queue,
+    ownerId,
+    async start(input, startOptions = {}) {
+      const createdAt = now();
+      const run = {
+        id: normalizeText(startOptions.id ?? idFactory(), "run id"),
+        workflowName,
+        input,
+        state: "pending",
+        createdAt,
+        updatedAt: createdAt,
+        steps: definitions.map(makeRecord),
+        completionOrder: []
+      };
+      await store.create(run);
+      if (queue) {
+        await enqueueRun(run.id);
+        return requireRun(run.id);
+      }
+      return execute(run.id, startOptions.signal);
+    },
+    run(id, signal) {
+      return execute(normalizeText(id, "run id"), signal);
+    },
+    get(id) {
+      return store.get(normalizeText(id, "run id"));
+    },
+    async list() {
+      return await store.list(workflowName);
+    },
+    async resume(id, resumeOptions = {}) {
+      const run = await requireRun(id);
+      if (run.state !== "waiting") {
+        return run;
+      }
+      if (!resumeOptions.force && run.waitUntil !== void 0 && run.waitUntil > now()) {
+        return run;
+      }
+      if (resumeOptions.force) {
+        forceWaitingStepDue(run, now());
+      }
+      run.state = "pending";
+      run.updatedAt = now();
+      await store.update(run);
+      if (queue) {
+        await enqueueRun(run.id);
+        return requireRun(run.id);
+      }
+      return execute(run.id, resumeOptions.signal);
+    },
+    async retry(id, retryOptions = {}) {
+      const run = await requireRun(id);
+      if (run.state !== "failed") {
+        return run;
+      }
+      if (!resetFailed(run.steps)) {
+        throw new Error(`BCP Workflow: failed run "${run.id}" has no failed step.`);
+      }
+      run.state = "pending";
+      run.error = void 0;
+      run.completedAt = void 0;
+      run.currentStep = void 0;
+      run.updatedAt = now();
+      await store.update(run);
+      if (queue) {
+        await enqueueRun(run.id);
+        return requireRun(run.id);
+      }
+      return execute(run.id, retryOptions.signal);
+    },
+    async cancel(id, cancelOptions = {}) {
+      const run = await requireRun(id);
+      if (isTerminal(run.state)) {
+        return run;
+      }
+      run.state = "cancelled";
+      run.completedAt = now();
+      run.updatedAt = run.completedAt;
+      run.waitUntil = void 0;
+      await store.update(run);
+      return cancelOptions.compensate ? compensateRun(run, cancelOptions.signal) : cloneRun(run);
+    },
+    async compensate(id, signal) {
+      const run = await requireRun(id);
+      if (run.state !== "failed" && run.state !== "cancelled") {
+        return run;
+      }
+      return compensateRun(run, signal);
+    },
+    async close() {
+      unregisterQueueHandler?.();
+      if (store.close) {
+        await store.close();
+      }
+    }
+  };
+  return api;
+  async function execute(rawId, signal = new AbortController().signal) {
+    const id = normalizeText(rawId, "run id");
+    const claimed = await store.claim(id, { ownerId, now: now(), leaseMs });
+    if (!claimed) {
+      return requireRun(id);
+    }
+    try {
+      const run = await requireRun(id);
+      if (isTerminal(run.state) || run.state === "compensating") {
+        return run;
+      }
+      if (run.state === "waiting" && run.waitUntil !== void 0 && run.waitUntil > now()) {
+        return run;
+      }
+      run.state = "running";
+      run.startedAt ??= now();
+      run.waitUntil = void 0;
+      run.updatedAt = now();
+      await store.update(run);
+      for (let index = 0; index < definitions.length; index += 1) {
+        if (signal.aborted) {
+          run.state = "cancelled";
+          run.completedAt = now();
+          run.updatedAt = run.completedAt;
+          await store.update(run);
+          return cloneRun(run);
+        }
+        const definition = definitions[index];
+        const record = run.steps[index];
+        if (!definition || !record) {
+          throw new Error("BCP Workflow: definition/run step mismatch.");
+        }
+        if (record.state === "succeeded" || record.state === "compensated") {
+          continue;
+        }
+        run.currentStep = definition.id;
+        run.updatedAt = now();
+        await store.update(run);
+        const outcome = await runDefinition(definition, record, run, signal);
+        if (outcome === "waiting") {
+          return cloneRun(run);
+        }
+        if (outcome === "failed") {
+          run.state = "failed";
+          run.error = record.error ?? `Workflow step "${definition.id}" failed.`;
+          run.completedAt = now();
+          run.updatedAt = run.completedAt;
+          await store.update(run);
+          return cloneRun(run);
+        }
+      }
+      run.state = "succeeded";
+      run.currentStep = void 0;
+      run.completedAt = now();
+      run.updatedAt = run.completedAt;
+      await store.update(run);
+      return cloneRun(run);
+    } finally {
+      await store.release(id, ownerId);
+    }
+  }
+  async function runDefinition(definition, record, run, signal) {
+    if (definition.kind === "delay") {
+      if (record.state === "waiting" && record.waitUntil !== void 0 && record.waitUntil <= now()) {
+        record.state = "succeeded";
+        record.completedAt = now();
+        record.waitUntil = void 0;
+        run.waitUntil = void 0;
+        await store.update(run);
+        return "ok";
+      }
+      if (definition.durationMs === 0) {
+        record.state = "succeeded";
+        record.startedAt ??= now();
+        record.completedAt = now();
+        await store.update(run);
+        return "ok";
+      }
+      const waitUntil = now() + definition.durationMs;
+      record.state = "waiting";
+      record.startedAt ??= now();
+      record.waitUntil = waitUntil;
+      run.state = "waiting";
+      run.waitUntil = waitUntil;
+      run.updatedAt = now();
+      await store.update(run);
+      if (queue) {
+        await queue.enqueue(
+          queueJobName,
+          { runId: run.id },
+          { delayMs: definition.durationMs, maxAttempts: 1 }
+        );
+      }
+      return "waiting";
+    }
+    if (definition.kind === "parallel") {
+      record.state = "running";
+      record.startedAt ??= now();
+      record.children ??= definition.steps.map(makeRecord);
+      await store.update(run);
+      const results = await Promise.all(
+        definition.steps.map(async (child, index) => {
+          const childRecord = record.children?.[index];
+          if (!childRecord) {
+            throw new Error("BCP Workflow: parallel child record is missing.");
+          }
+          if (childRecord.state === "succeeded" || childRecord.state === "compensated") {
+            return false;
+          }
+          return runLeaf(
+            child,
+            childRecord,
+            run,
+            signal,
+            `${definition.id}.${child.id}`
+          );
+        })
+      );
+      if (results.some(Boolean)) {
+        record.state = "failed";
+        record.completedAt = now();
+        record.error = record.children.find((child) => child.state === "failed")?.error ?? `Parallel step "${definition.id}" failed.`;
+        await store.update(run);
+        return "failed";
+      }
+      record.state = "succeeded";
+      record.completedAt = now();
+      await store.update(run);
+      return "ok";
+    }
+    return await runLeaf(definition, record, run, signal, definition.id) ? "failed" : "ok";
+  }
+  async function runLeaf(definition, record, run, signal, completionId) {
+    record.state = "running";
+    record.startedAt ??= now();
+    record.error = void 0;
+    await store.update(run);
+    while (record.attempts < definition.options.maxAttempts) {
+      if (signal.aborted) {
+        record.state = "cancelled";
+        record.completedAt = now();
+        await store.update(run);
+        return true;
+      }
+      record.attempts += 1;
+      await store.update(run);
+      try {
+        await definition.handler({ input: run.input, run: cloneRun(run), signal });
+        record.state = "succeeded";
+        record.completedAt = now();
+        record.error = void 0;
+        if (!run.completionOrder.includes(completionId)) {
+          run.completionOrder.push(completionId);
+        }
+        await store.update(run);
+        return false;
+      } catch (error) {
+        record.error = formatError(error);
+        if (record.attempts >= definition.options.maxAttempts) {
+          record.state = "failed";
+          record.completedAt = now();
+          await store.update(run);
+          return true;
+        }
+        const retryDelay = resolveRetryDelay(
+          definition.options.retryDelayMs ?? defaultRetryDelay,
+          record.attempts
+        );
+        if (retryDelay > 0) {
+          await sleep(retryDelay, signal);
+        }
+      }
+    }
+    record.state = "failed";
+    record.completedAt = now();
+    await store.update(run);
+    return true;
+  }
+  async function compensateRun(run, signal = new AbortController().signal) {
+    run.state = "compensating";
+    run.updatedAt = now();
+    await store.update(run);
+    try {
+      for (const completionId of [...run.completionOrder].reverse()) {
+        if (signal.aborted) {
+          throw new Error("Workflow compensation was aborted.");
+        }
+        const target = findCompensationTarget(completionId, definitions, run.steps);
+        if (!target?.definition.options.compensate) {
+          continue;
+        }
+        if (target.record.state !== "succeeded") {
+          continue;
+        }
+        target.record.state = "compensating";
+        await store.update(run);
+        await target.definition.options.compensate({
+          input: run.input,
+          run: cloneRun(run),
+          signal
+        });
+        target.record.state = "compensated";
+        target.record.completedAt = now();
+        await store.update(run);
+      }
+      run.state = "compensated";
+      run.completedAt = now();
+      run.updatedAt = run.completedAt;
+      await store.update(run);
+      return cloneRun(run);
+    } catch (error) {
+      run.state = "failed";
+      run.error = `Compensation failed: ${formatError(error)}`;
+      run.completedAt = now();
+      run.updatedAt = run.completedAt;
+      await store.update(run);
+      return cloneRun(run);
+    }
+  }
+  async function enqueueRun(runId) {
+    if (!queue) {
+      return;
+    }
+    await queue.enqueue(queueJobName, { runId }, { maxAttempts: 1 });
+  }
+  async function requireRun(rawId) {
+    const id = normalizeText(rawId, "run id");
+    const run = await store.get(id);
+    if (!run || run.workflowName !== workflowName) {
+      throw new Error(
+        `BCP Workflow: run "${id}" was not found for workflow "${workflowName}".`
+      );
+    }
+    return run;
+  }
+}
+function makeStep(id, handler, options, defaultMaxAttempts, ids) {
+  if (typeof handler !== "function") {
+    throw new TypeError("BCP Workflow: step handler must be a function.");
+  }
+  return {
+    kind: "step",
+    id: reserveId(id, ids),
+    handler,
+    options: {
+      ...options,
+      maxAttempts: positiveInteger(options.maxAttempts ?? defaultMaxAttempts, "step maxAttempts")
+    }
+  };
+}
+function makeRecord(definition) {
+  return {
+    id: definition.id,
+    kind: definition.kind,
+    state: "pending",
+    attempts: 0,
+    children: definition.kind === "parallel" ? definition.steps.map(makeRecord) : void 0
+  };
+}
+function resetFailed(steps) {
+  let found = false;
+  for (const step of steps) {
+    const childFound = step.children ? resetFailed(step.children) : false;
+    if (step.state === "failed" || childFound) {
+      step.state = "pending";
+      step.attempts = 0;
+      step.error = void 0;
+      step.completedAt = void 0;
+      step.waitUntil = void 0;
+      found = true;
+    }
+  }
+  return found;
+}
+function forceWaitingStepDue(run, timestamp) {
+  run.waitUntil = timestamp;
+  for (const step of run.steps) {
+    if (step.state === "waiting") {
+      step.waitUntil = timestamp;
+      return;
+    }
+  }
+}
+function findCompensationTarget(completionId, definitions, records) {
+  const parts = completionId.split(".");
+  for (let index = 0; index < definitions.length; index += 1) {
+    const definition = definitions[index];
+    const record = records[index];
+    if (!definition || !record) {
+      continue;
+    }
+    if (parts.length === 1 && definition.kind === "step" && definition.id === completionId) {
+      return { definition, record };
+    }
+    if (parts.length === 2 && definition.kind === "parallel" && definition.id === parts[0]) {
+      const childIndex = definition.steps.findIndex((child) => child.id === parts[1]);
+      const childDefinition = definition.steps[childIndex];
+      const childRecord = record.children?.[childIndex];
+      if (childDefinition && childRecord) {
+        return { definition: childDefinition, record: childRecord };
+      }
+    }
+  }
+  return null;
+}
+function reserveId(value, ids) {
+  const id = normalizeText(value, "step id");
+  if (id.includes(".")) {
+    throw new TypeError("BCP Workflow: step ids must not contain '.'.");
+  }
+  if (ids.has(id)) {
+    throw new Error(`BCP Workflow: duplicate step id "${id}".`);
+  }
+  ids.add(id);
+  return id;
+}
+function resolveRetryDelay(value, attempt) {
+  const delay = typeof value === "function" ? value(attempt) : value;
+  return nonNegativeNumber(delay, "retryDelayMs");
+}
+function sleep(durationMs, signal) {
+  if (durationMs === 0 || signal.aborted) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const timeout = setTimeout(finish, durationMs);
+    const onAbort = () => finish();
+    signal.addEventListener("abort", onAbort, { once: true });
+    function finish() {
+      clearTimeout(timeout);
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }
+  });
+}
+function isTerminal(state) {
+  return state === "succeeded" || state === "cancelled" || state === "compensated";
+}
+function normalizeText(value, field) {
+  const normalized = String(value).trim();
+  if (!normalized) {
+    throw new TypeError(`BCP Workflow: ${field} must be a non-empty string.`);
+  }
+  if (normalized.length > 200) {
+    throw new TypeError(`BCP Workflow: ${field} must not exceed 200 characters.`);
+  }
+  return normalized;
+}
+function positiveInteger(value, field) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(`BCP Workflow: ${field} must be a positive integer.`);
+  }
+  return value;
+}
+function nonNegativeNumber(value, field) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new TypeError(`BCP Workflow: ${field} must be a non-negative finite number.`);
+  }
+  return Math.floor(value);
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message || error.name;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error) ?? String(error);
+  } catch {
+    return String(error);
+  }
+}
+function cloneRun(run) {
+  return {
+    ...run,
+    steps: run.steps.map(cloneStep),
+    completionOrder: [...run.completionOrder]
+  };
+}
+function cloneStep(step) {
+  return {
+    ...step,
+    children: step.children?.map(cloneStep)
+  };
+}
+export {
+  createMemoryWorkflowStore,
+  createWorkflow
+};

package/packages/client/src/workflow.ts

@@ -0,0 +1,23 @@
+export {
+    createMemoryWorkflowStore,
+    createWorkflow,
+    type CancelWorkflowOptions,
+    type MemoryWorkflowStore,
+    type ResumeWorkflowOptions,
+    type StartWorkflowOptions,
+    type Workflow,
+    type WorkflowBuilder,
+    type WorkflowCompensationHandler,
+    type WorkflowOptions,
+    type WorkflowParallelBuilder,
+    type WorkflowRetryDelay,
+    type WorkflowRunRecord,
+    type WorkflowRunState,
+    type WorkflowStepContext,
+    type WorkflowStepHandler,
+    type WorkflowStepKind,
+    type WorkflowStepOptions,
+    type WorkflowStepRecord,
+    type WorkflowStepState,
+    type WorkflowStore,
+} from "../../server/src/workflow.js";