@bobtail.software/b-durable 1.0.3 → 1.0.5

package/README.md

@@ -0,0 +1,232 @@
+
+# `@bobtail.software/b-durable`: Composable, Type-Safe, Durable Workflows for TypeScript
+
+![NPM Version](https://img.shields.io/npm/v/@bobtail.software/b-durable.svg)
+![License](https://img.shields.io/npm/l/@bobtail.software/eslint-plugin-b-durable.svg)
+
+`b-durable` is a powerful system that transforms standard `async` functions into **composable, interactive, durable, and resilient workflows**. It lets you write long-running business logic—spanning hours, days, or months—as simple, linear `async/await` code. The system handles state persistence, orchestration, external events, and crash recovery, allowing you to focus on your business logic.
+
+## The Problem
+
+Standard `async/await` is great for short-lived operations, but it breaks down for complex, long-running processes:
+
+1.  **Fragility**: If your server restarts mid-execution, all in-memory state is lost.
+2.  **Inefficiency**: An operation like `await bSleep('7 days')` is impossible. It would hold a process hostage, consume resources, and wouldn't survive a single deployment.
+3.  **Orchestration Complexity**: Coordinating processes that involve multiple services, human-in-the-loop steps (like approvals), or external system webhooks often leads to a tangled mess of state machines, queues, and database flags.
+
+## The `b-durable` Solution
+
+`b-durable` allows you to express this complexity as a single, readable `async` function. The system automatically persists the workflow's state after each `await` step, ensuring it can resume from the exact point of interruption.
+
+Imagine orchestrating an e-commerce order. With `b-durable`, the code is as clear as the business process itself:
+
+```typescript
+// Define a reusable sub-workflow for handling payments
+export const paymentWorkflow = bDurable({
+  workflow: async (input: { orderId: string; amount: number }, context) => {
+    // 1. Call a service to process the payment
+    const result = await processPayment({ orderId: input.orderId, amount: input.amount });
+    if (!result.success) {
+      throw new Error('Payment failed!');
+    }
+    // 2. Pause durably for fraud checks
+    await context.bSleep('30m');
+    return { transactionId: result.transactionId };
+  },
+});
+
+// Define the main order processing workflow
+export const orderProcessingWorkflow = bDurable({
+  workflow: async (input: { orderId: string; items: Item[] }, context) => {
+    try {
+      // 1. Call another workflow and await its result
+      const payment = await context.bExecute(paymentWorkflow, { orderId: input.orderId, amount: 99.99 });
+      context.log(`Payment successful: ${payment.transactionId}`);
+      
+      // 2. Pause and wait for an external event (e.g., from a UI or webhook)
+      const approval = await context.bWaitForEvent('order.approved');
+      context.log(`Order approved by ${approval.approverId}`);
+
+      // 3. Call the final service function
+      await shipOrder(input.orderId);
+
+      return { status: 'completed' };
+    } catch (error) {
+      // 4. Handle errors durably
+      await notifyCustomerOfFailure(input.orderId, error.message);
+      await cancelOrder(input.orderId);
+      return { status: 'failed', reason: error.message };
+    }
+  },
+});
+```
+
+## Core Features
+
+-   **Composable Orchestration**: Workflows can call other workflows using `await context.bExecute()`, allowing you to build complex processes from smaller, reusable parts. Results and errors are propagated automatically.
+-   **Interactive & Event-Driven**: Pause a workflow indefinitely with `await context.bWaitForEvent()` until an external event is received, enabling human-in-the-loop patterns and webhook integrations.
+-   **Durable & Resilient**: Workflows survive server restarts, crashes, and deployments, resuming exactly where they left off.
+-   **Built-in Error Handling**: Use standard `try/catch` blocks to handle errors from tasks or sub-workflows. Your `catch` block will execute reliably, even if the failure occurs hours after the `try` block started.
+-   **Durable Timers**: Use `await context.bSleep('30 days')` to pause workflows for extended periods without consuming server resources.
+-   **Type Safety End-to-End**: Leverages TypeScript for type safety across steps, I/O, events, and workflow composition.
+-   **Compiler-Powered**: A smart CLI compiler transforms your workflows into a step-by-step executable format, preserving types and ensuring runtime correctness.
+
+## How It Works: Compiler + Runtime
+
+1.  **The Smart Compiler (`b-durable-compiler`)**:
+    Analyzes your workflow files (`*.workflow.ts`). For each function wrapped in `bDurable(...)`, it:
+    -   **Maps Control Flow**: Breaks the function into steps at each `await`, analyzing `if/else` and `try/catch` blocks to build a complete state machine.
+    -   **Identifies Durable Calls**: Differentiates between a durable instruction (`context.bSleep`, `context.bExecute`) and a standard service task call.
+    -   **Generates Durable Artifacts**: Produces compiled `.mts` files that the runtime can execute step-by-step.
+
+2.  **The Durable Runtime**:
+    The engine that executes the compiled workflows.
+    -   **State Persistence**: Uses Redis to store the state, step, and context of every workflow instance.
+    -   **Orchestration Logic**: Manages parent/child workflow relationships, passing results and errors up the chain.
+    -   **Event System**: Tracks which workflows are waiting for which events.
+    -   **Task Queue & Scheduler**: Reliably executes service function calls and manages long-running timers.
+
+## Getting Started
+
+### 1. Installation
+
+Install the core library and its peer dependencies. We also highly recommend the ESLint plugin for the best developer experience.
+
+```bash
+pnpm add @bobtail.software/b-durable ioredis
+pnpm add -D @bobtail.software/eslint-plugin-b-durable
+```
+
+### 2. Set Up ESLint (Highly Recommended)
+
+Our ESLint plugin prevents common errors by flagging unsupported code constructs (like loops) inside your workflows.
+
+**In `eslint.config.js` (Flat Config):**
+```javascript
+import bDurablePlugin from '@bobtail.software/eslint-plugin-b-durable';
+
+export default [
+  // ... your other configs
+  bDurablePlugin.configs.recommended,
+];
+```
+For legacy `.eslintrc.js` setup, see the [plugin's documentation](link-to-your-eslint-plugin-readme).
+
+### 3. Define a Workflow
+
+Create a file ending in `.workflow.ts`. The `(input, context)` signature gives you access to durable functions.
+
+```typescript
+// src/workflows/onboarding.workflow.ts
+import { bDurable, DurableContext } from '@bobtail.software/b-durable';
+import { createUser, sendWelcomeEmail } from '../services';
+
+interface OnboardingInput {
+  userId: string;
+  email: string;
+}
+
+export const userOnboardingWorkflow = bDurable({
+  workflow: async (input: OnboardingInput, context: DurableContext) => {
+    const user = await createUser({ id: input.userId, email: input.email });
+
+    await context.bSleep('10s');
+
+    await sendWelcomeEmail(user.email);
+
+    return { status: 'completed', userId: user.id };
+  },
+});
+```
+
+### 4. Compile Workflows
+
+Add a script to your `package.json` to run the compiler.
+
+```json
+// package.json
+"scripts": {
+  "compile-workflows": "b-durable-compiler --in src/workflows --out src/generated"
+}
+```
+Run `pnpm compile-workflows`. This generates the durable definitions in `src/generated`.
+
+### 5. Initialize the Runtime
+
+In your application's entry point, initialize the system and start a workflow.
+
+```typescript
+// src/main.ts
+import { bDurableInitialize } from '@bobtail.software/b-durable';
+import Redis from 'ioredis';
+import durableFunctions, { userOnboardingWorkflow } from './generated';
+
+async function main() {
+  const redis = new Redis();
+  const blockingRedis = new Redis(); // Required for reliable queue operations
+
+  const durableSystem = bDurableInitialize({
+    durableFunctions,
+    sourceRoot: process.cwd(),
+    redisClient: redis,
+    blockingRedisClient: blockingRedis,
+  });
+
+  console.log('Durable system ready. Starting workflows...');
+
+  // --- Start a workflow with a system-generated ID ---
+  const workflowId1 = await durableSystem.start(userOnboardingWorkflow, {
+    input: {
+      userId: `user-${Date.now()}`,
+      email: 'test.user@example.com',
+    }
+  });
+  console.log(`Workflow ${workflowId1} started.`);
+
+  // --- Start a workflow with a predictable, user-provided ID ---
+  const orderId = `order-abc-123`;
+  const workflowId2 = await durableSystem.start(userOnboardingWorkflow, {
+    workflowId: orderId,
+    input: {
+      userId: 'user-from-order-123',
+      email: 'customer@example.com',
+    }
+  });
+  console.log(`Workflow started with predictable ID: ${workflowId2}`);
+  // Now you can easily send events using the 'orderId'
+  // durableSystem.sendEvent(..., orderId, ...);
+}
+
+main().catch(console.error);
+```
+
+### 6. Run Your Application
+
+Run your app (`node src/main.ts`). You'll see the workflow execute, pause, and resume, with all its state managed by `b-durable`.
+
+## Development Setup (for contributors)
+
+The project is a `pnpm` monorepo.
+
+1.  **Clone & Install**:
+    ```bash
+    git clone <repository-url>
+    cd b-durable-monorepo
+    pnpm install
+    ```
+
+2.  **Run in Development Mode**:
+    This command builds the library, compiles example workflows, and starts the example app with hot-reloading.
+    ```bash
+    pnpm dev
+    ```
+
+3.  **Run Tests**:
+    Tests use Vitest and a real Redis instance.
+    ```bash
+    pnpm --filter @bobtail.software/b-durable test
+    ```
+
+## License
+
+This project is licensed under the GPL-3.0 License. See the [LICENSE](LICENSE) file for details.