create-bcp-app 0.2.10 → 0.2.11

package/README.md

@@ -92,10 +92,10 @@ Example:
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.10",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.11",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.10"
+    "version": "0.2.11"
   },
   "packageManager": "npm",
   "presets": {
@@ -263,87 +263,87 @@ const worker =
     });
 ```
 
-Inspect failed jobs:
+BCP intentionally does not install a Redis client library. Applications own the Redis connection and can pass a minimal `RedisCommandClient` to `createRedisJobQueueAdapter()` and `createRedisJobScheduleStore()`.
 
-```ts
-const deadLetters =
-    await jobs.deadLetters();
-```
-
-Requeue:
-
-```ts
-await jobs.requeueDeadLetter(
-    deadLetters[0].id,
-    {
-        resetAttempts: true,
-    }
-);
-```
+`bcp/jobs` is server-only and must not be imported into page/client bundles.
 
-### Redis-compatible durable adapters
+## Workflow orchestration — 0.2.11+
 
-BCP intentionally does not install a Redis client library. Applications own the Redis connection and pass a minimal command client to BCP:
+Generated applications can define persistent backend workflows with the new server-only `bcp/workflow` entrypoint:
 
 ```ts
-interface RedisCommandClient {
-    sendCommand(
-        command: string[]
-    ): Promise<unknown>;
-}
+import {
+    createWorkflow,
+} from "bcp/workflow";
+
+export const onboarding =
+    createWorkflow<{
+        userId: number;
+    }>(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                createProfile
+            );
+
+            workflow.parallel(
+                "initialize",
+                parallel => {
+                    parallel.step(
+                        "preferences",
+                        createPreferences
+                    );
+                    parallel.step(
+                        "workspace",
+                        createWorkspace
+                    );
+                }
+            );
+
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
 ```
 
-Queue adapter:
+Step-level retry and compensation are supported:
 
 ```ts
-import {
-    createJobQueue,
-    createRedisJobQueueAdapter,
-} from "bcp/jobs";
-
-const adapter =
-    createRedisJobQueueAdapter({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
-
-export const jobs =
-    createJobQueue({
-        adapter,
-    });
+workflow.step(
+    "reserve-stock",
+    reserveStock,
+    {
+        maxAttempts: 3,
+        retryDelayMs: 1_000,
+        compensate:
+            releaseStock,
+    }
+);
 ```
 
-Scheduler store:
+For durable queue-backed execution, pass an existing `BackgroundJobQueue` and a durable shared `WorkflowStore`:
 
 ```ts
-import {
-    createJobScheduler,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
-
-const store =
-    createRedisJobScheduleStore({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
-
-export const scheduler =
-    createJobScheduler({
-        queue: jobs,
-        store,
-        ownerId: "scheduler-a",
-    });
+const fulfillment =
+    createWorkflow(
+        "order.fulfillment",
+        defineWorkflow,
+        {
+            queue: jobs,
+            store:
+                workflowStore,
+        }
+    );
 ```
 
-A typical application may configure its Redis client with:
+The built-in `createMemoryWorkflowStore()` is intended for development/tests. Multi-instance production stores should make `claim()` atomic so only one executor owns a workflow run lease at a time.
 
-```dotenv
-REDIS_URL=redis://localhost:6379
-```
+External side effects should remain idempotent because durable queue execution is at-least-once.
 
-BCP does not read `REDIS_URL` automatically. Redis credentials, TLS/Cluster/Sentinel configuration and connection lifecycle stay application-owned.
-
-`bcp/jobs` is server-only and must not be imported into page/client bundles.
+`bcp/workflow` is server-only and cannot be imported into page/client bundles.
 
 ## Application Packaging — 0.2.4+
 
@@ -390,5 +390,5 @@ bcp generate migration create_users
 The `--bcp` option is mainly for prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.10.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.11.tgz
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Create a new BCP Framework application.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -216,6 +216,84 @@ The processing model is at-least-once, so side-effecting job handlers should be
 
 `bcp/jobs` is server-only and cannot be imported into page/client bundles.
 
+## Workflow orchestration — BCP 0.2.11+
+
+Define persistent server-side workflows through `bcp/workflow`:
+
+```ts
+import {
+    createWorkflow,
+} from "bcp/workflow";
+
+export const onboarding =
+    createWorkflow<{
+        userId: number;
+    }>(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                createProfile
+            );
+
+            workflow.parallel(
+                "initialize",
+                parallel => {
+                    parallel.step(
+                        "preferences",
+                        createPreferences
+                    );
+                    parallel.step(
+                        "workspace",
+                        createWorkspace
+                    );
+                }
+            );
+
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
+```
+
+Step retry and compensation:
+
+```ts
+workflow.step(
+    "reserve-stock",
+    reserveStock,
+    {
+        maxAttempts: 3,
+        retryDelayMs: 1_000,
+        compensate:
+            releaseStock,
+    }
+);
+```
+
+For queue-backed execution:
+
+```ts
+const fulfillment =
+    createWorkflow(
+        "order.fulfillment",
+        defineWorkflow,
+        {
+            queue: jobs,
+            store:
+                workflowStore,
+        }
+    );
+```
+
+The default `createMemoryWorkflowStore()` is for local development/tests. Multi-instance production deployments should implement a shared durable `WorkflowStore` with atomic `claim()` behavior.
+
+Workflow handlers that perform external side effects should be idempotent because durable job execution is at-least-once.
+
+`bcp/workflow` is server-only and cannot be imported into page/client bundles.
+
 ## Generate framework files
 
 ```bash