@chidchanun/bcp 0.2.10 → 0.2.12

package/docs/workflow-orchestration.md

@@ -0,0 +1,374 @@
+# Workflow Orchestration
+
+BCP `0.2.11` adds a server-only workflow orchestration layer through `bcp/workflow`.
+
+The workflow runtime is designed for application processes that need to coordinate multiple backend operations as one observable run instead of manually chaining unrelated jobs.
+
+## Public entrypoint
+
+```ts
+import {
+    createMemoryWorkflowStore,
+    createWorkflow,
+} from "bcp/workflow";
+```
+
+`bcp/workflow` is server-only and must not be imported into page/client bundles.
+
+## Basic workflow
+
+```ts
+import {
+    createWorkflow,
+} from "bcp/workflow";
+
+export const onboarding =
+    createWorkflow<{
+        userId: number;
+    }>(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "create-profile",
+                async ({ input }) => {
+                    await createProfile(
+                        input.userId
+                    );
+                }
+            );
+
+            workflow.step(
+                "send-email",
+                async ({ input }) => {
+                    await sendWelcomeEmail(
+                        input.userId
+                    );
+                }
+            );
+        }
+    );
+```
+
+Start a run:
+
+```ts
+const run =
+    await onboarding.start({
+        userId: 42,
+    });
+```
+
+Without a background queue, `start()` executes immediately until the workflow either succeeds, fails, is cancelled or reaches a delay.
+
+## Step retries
+
+Each step can define its own retry policy:
+
+```ts
+workflow.step(
+    "charge-card",
+    chargeCard,
+    {
+        maxAttempts: 3,
+        retryDelayMs:
+            attempt =>
+                attempt * 1_000,
+    }
+);
+```
+
+The runtime persists the step attempt count and terminal error in the workflow run record.
+
+Step retries happen inside the workflow execution attempt. Long-running production workflows should prefer idempotent handlers so a process restart or at-least-once queue delivery can safely repeat work.
+
+## Parallel steps
+
+Use `parallel()` when independent operations can run together:
+
+```ts
+workflow.parallel(
+    "initialize",
+    parallel => {
+        parallel.step(
+            "preferences",
+            createPreferences
+        );
+
+        parallel.step(
+            "workspace",
+            createDefaultWorkspace
+        );
+    }
+);
+```
+
+All child step records are persisted under the parent parallel step.
+
+The parallel group succeeds only when every child succeeds.
+
+## Delays
+
+A workflow delay is persisted instead of blocking a process with a long timer:
+
+```ts
+workflow.delay(
+    "cooldown",
+    5 * 60 * 1000
+);
+```
+
+The run transitions to:
+
+```text
+waiting
+```
+
+with a persisted `waitUntil` timestamp.
+
+For an in-process workflow, resume after the timestamp:
+
+```ts
+await workflow.resume(
+    run.id
+);
+```
+
+Calling `resume()` before `waitUntil` returns the current waiting run unchanged.
+
+For administrative tooling, a forced resume is available:
+
+```ts
+await workflow.resume(
+    run.id,
+    {
+        force: true,
+    }
+);
+```
+
+## Queue-backed execution
+
+A workflow can use the BCP background job queue as its execution layer:
+
+```ts
+import {
+    createJobQueue,
+} from "bcp/jobs";
+import {
+    createWorkflow,
+} from "bcp/workflow";
+
+const jobs =
+    createJobQueue({
+        adapter:
+            redisQueueAdapter,
+    });
+
+export const workflow =
+    createWorkflow(
+        "order.fulfillment",
+        defineOrderWorkflow,
+        {
+            queue: jobs,
+            store:
+                workflowStore,
+        }
+    );
+```
+
+When a queue is configured:
+
+- `start()` persists the run and enqueues execution,
+- `retry()` enqueues another execution attempt,
+- `resume()` enqueues continuation,
+- workflow delays enqueue a delayed continuation job,
+- worker concurrency, visibility leases, heartbeat and stale-job recovery remain owned by `bcp/jobs`.
+
+This keeps job delivery and workflow state as separate contracts.
+
+## Workflow store
+
+`WorkflowStore` is the persistence boundary:
+
+```ts
+interface WorkflowStore {
+    create(run): Promise<void>;
+    update(run): Promise<void>;
+    get(id): Promise<WorkflowRunRecord | null>;
+    list(workflowName?): Promise<WorkflowRunRecord[]>;
+
+    claim(
+        id,
+        {
+            ownerId,
+            now,
+            leaseMs,
+        }
+    ): Promise<boolean>;
+
+    release(
+        id,
+        ownerId
+    ): Promise<void>;
+}
+```
+
+The built-in:
+
+```ts
+createMemoryWorkflowStore()
+```
+
+is intended for local development and deterministic tests.
+
+Production multi-instance deployments should use a shared durable store whose `claim()` operation is atomic.
+
+The claim is the workflow concurrency boundary. Only one owner should execute a run while its lease is active.
+
+## Run states
+
+Workflow runs use:
+
+```text
+pending
+running
+waiting
+succeeded
+failed
+cancelled
+compensating
+compensated
+```
+
+Step records use the corresponding lifecycle states where applicable.
+
+## Inspect runs
+
+```ts
+const run =
+    await workflow.get(
+        runId
+    );
+
+const runs =
+    await workflow.list();
+```
+
+A run includes:
+
+- workflow name,
+- input payload,
+- current state,
+- timestamps,
+- current step,
+- step attempts/errors,
+- parallel child state,
+- `waitUntil`,
+- completion order,
+- current workflow lease metadata.
+
+## Manual retry
+
+A failed run can retry its failed step without rerunning already successful preceding steps:
+
+```ts
+await workflow.retry(
+    runId
+);
+```
+
+The failed step attempt counter is reset for the new manual retry cycle.
+
+## Compensation
+
+A successful step can provide a compensation handler:
+
+```ts
+workflow.step(
+    "reserve-stock",
+    reserveStock,
+    {
+        compensate:
+            releaseStock,
+    }
+);
+```
+
+If a later step fails, application code can request compensation:
+
+```ts
+await workflow.compensate(
+    runId
+);
+```
+
+Compensation runs successful compensatable steps in reverse completion order.
+
+This is a saga-style compensation mechanism. It does not provide database transaction rollback across external services.
+
+Cancellation can also request compensation:
+
+```ts
+await workflow.cancel(
+    runId,
+    {
+        compensate: true,
+    }
+);
+```
+
+## Idempotency
+
+Workflow state and background queues provide orchestration and delivery coordination, but external side effects should still be idempotent.
+
+For example, payment and email handlers should use application-level idempotency keys where duplicate execution would be harmful.
+
+A durable queue provides at-least-once delivery semantics, not exactly-once external side effects.
+
+## Recommended production topology
+
+```text
+API / application
+       |
+       v
+WorkflowStore (shared durable state)
+       |
+       v
+BCP Workflow
+       |
+       v
+Durable JobQueueAdapter
+       |
+   +---+---+
+   |       |
+Worker A Worker B
+```
+
+The workflow store and queue do not have to use the same backend.
+
+## Lifecycle
+
+```ts
+await workflow.close();
+await jobs.close();
+```
+
+`workflow.close()` unregisters its internal queue handler and closes the configured workflow store when the store exposes `close()`.
+
+The application remains responsible for lifecycle of external database/Redis clients used by custom stores/adapters.
+
+## Current scope
+
+`0.2.11` intentionally focuses on the orchestration core:
+
+- sequential steps,
+- parallel steps,
+- step retries,
+- persisted delays,
+- manual retry/resume/cancel,
+- compensation,
+- workflow state persistence,
+- run leases,
+- optional `bcp/jobs` execution.
+
+Transactional outbox/event delivery remains a separate future milestone so workflow orchestration does not pretend to make a database transaction and external queue publish atomic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -67,6 +67,16 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/jobs.mjs"
     },
+    "./workflow": {
+      "types": "./packages/client/src/workflow.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/workflow.mjs"
+    },
+    "./events": {
+      "types": "./packages/client/src/events.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/events.mjs"
+    },
     "./observability": {
       "types": "./packages/client/src/observability.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -29,6 +29,8 @@ const SERVER_ONLY_IMPORTS =
         "bcp/database",
         "bcp/auth",
         "bcp/jobs",
+        "bcp/workflow",
+        "bcp/events",
         "bcp/observability",
     ]);