@brandboostinggmbh/observable-workflows 0.5.0 → 0.7.0

package/README.md

@@ -1,15 +1,396 @@
-# observable-workflows [![npm](https://img.shields.io/npm/v/ts-starter.svg)](https://npmjs.com/package/ts-starter)
+# Observable Workflows [![npm](https://img.shields.io/npm/v/@brandboostinggmbh/observable-workflows.svg)](https://npmjs.com/package/@brandboostinggmbh/observable-workflows)
 
-[![Unit Test](https://github.com/sxzz/ts-starter/actions/workflows/unit-test.yml/badge.svg)](https://github.com/sxzz/ts-starter/actions/workflows/unit-test.yml)
+[![Build Status](https://github.com/Brand-Boosting-GmbH/observable-workflows/actions/workflows/ci.yml/badge.svg)](https://github.com/Brand-Boosting-GmbH/observable-workflows/actions/workflows/ci.yml)
 
-TODO
+A powerful TypeScript library for creating observable, durable workflows with step-by-step tracking, comprehensive logging, and database persistence. Built specifically for Cloudflare Workers and D1 database environments.
 
-## Install
+## Features
+
+- 🔍 **Observable Execution** - Track every step of your workflow with detailed logging
+- 💾 **Durable Persistence** - Automatic state persistence using Cloudflare D1 database
+- 🔄 **Retry Mechanisms** - Built-in workflow retry with step result reuse
+- 📊 **Multi-tenancy Support** - Isolate workflows by tenant for SaaS applications
+- ⚡ **Queue Integration** - Support for queue-based workflow processing
+- 🏷️ **Property Management** - Attach and query custom properties on workflows
+- 🔎 **Advanced Filtering** - Filter workflows by status, properties, date ranges
+- 📝 **Comprehensive Logging** - Structured logging with multiple levels (info, warn, error)
+- 🔧 **TypeScript First** - Full type safety and excellent developer experience
+
+## Installation
 
 ```bash
-npm i @brandboostinggmbh/observable-workflows
+npm install @brandboostinggmbh/observable-workflows
+```
+
+## Quick Start
+
+### 1. Define a Workflow
+
+```typescript
+import { defineWorkflow } from '@brandboostinggmbh/observable-workflows'
+
+interface EmailInput {
+  to: string
+  subject: string
+  body: string
+}
+
+const sendEmailWorkflow = defineWorkflow<EmailInput>(
+  'send-email',
+  async (input, { step, console }) => {
+    // Step 1: Validate email
+    await step('validate-email', async () => {
+      console.log('Validating email address:', input.to)
+      if (!input.to.includes('@')) {
+        throw new Error('Invalid email address')
+      }
+      return { valid: true }
+    })
+
+    // Step 2: Send email
+    const result = await step('send-email', async () => {
+      console.log('Sending email to:', input.to)
+      // Your email sending logic here - simulate async operation
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      return { messageId: 'msg_123', status: 'sent' }
+    })
+
+    // Step 3: Log result
+    await step('log-result', async () => {
+      console.log('Email sent successfully:', result.messageId)
+      return { logged: true }
+    })
+
+    return result
+  },
+)
+```
+
+### 2. Create Workflow Context and Execute
+
+```typescript
+import { createWorkflowContext } from '@brandboostinggmbh/observable-workflows'
+
+// Create workflow context with D1 database
+const workflowContext = createWorkflowContext({
+  D1: env.D1, // Cloudflare D1 database binding
+})
+
+// Execute the workflow
+const result = await workflowContext.call({
+  workflow: sendEmailWorkflow,
+  input: {
+    to: 'user@example.com',
+    subject: 'Welcome!',
+    body: 'Welcome to our service!',
+  },
+  workflowName: 'Welcome Email',
+  tenantId: 'tenant-123',
+})
+```
+
+### 3. Access Workflow Logs and Data
+
+```typescript
+import { createLogAccessor } from '@brandboostinggmbh/observable-workflows'
+
+const logAccessor = createLogAccessor({
+  D1: env.D1,
+  tenantId: 'tenant-123',
+})
+
+// List recent workflows
+const workflows = await logAccessor.listWorkflows(10, 0)
+
+// Get specific workflow with steps and logs
+const workflow = await logAccessor.getWorkflow(instanceId)
+console.log('Workflow status:', workflow.workflowStatus)
+console.log('Steps:', workflow.steps)
+console.log('Logs:', workflow.logs)
+```
+
+## Core Concepts
+
+### Workflows
+
+A workflow is a series of steps that execute in sequence. Each workflow has:
+
+- **Type**: A unique identifier for the workflow type
+- **Instance**: A specific execution of a workflow
+- **Steps**: Individual units of work within the workflow
+- **Properties**: Custom metadata that can be attached and queried
+
+### Steps
+
+Steps are the individual units of work within a workflow. They provide:
+
+- **Automatic retry** - Failed steps can be retried
+- **Result caching** - Successful step results are cached for retry scenarios
+- **Isolated logging** - Each step has its own log context
+- **Error handling** - Failed steps capture error details
+
+### Tenancy
+
+All workflows are isolated by tenant ID, enabling multi-tenant applications:
+
+- Each workflow execution requires a `tenantId`
+- Queries are automatically scoped to the tenant
+- Complete data isolation between tenants
+
+## Advanced Usage
+
+### Workflow with Metadata and Properties
+
+```typescript
+const processOrderWorkflow = defineWorkflow(
+  {
+    workflowType: 'process-order',
+    metadata: { version: '1.0', category: 'ecommerce' },
+  },
+  async (input, { step, console, setWorkflowProperty, setWorkflowName }) => {
+    // Set dynamic workflow name
+    await setWorkflowName(`Order ${input.orderId}`)
+
+    // Set searchable properties
+    await setWorkflowProperty('orderId', input.orderId)
+    await setWorkflowProperty('customerId', input.customerId)
+    await setWorkflowProperty('amount', input.amount)
+
+    const result = await step('process-payment', async () => {
+      // Payment processing logic - simulate async operation
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      return { transactionId: 'txn_123' }
+    })
+
+    await step('update-inventory', async () => {
+      // Inventory update logic - simulate async operation
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      return { updated: true }
+    })
+
+    return result
+  },
+)
+```
+
+### Retry Failed Workflows
+
+```typescript
+// Retry a failed workflow, reusing successful step results
+await workflowContext.retry(processOrderWorkflow, failedWorkflowId, {
+  reuseSuccessfulSteps: true, // Default: true
+})
+```
+
+### Queue-based Workflow Processing
+
+```typescript
+import { createQueueWorkflowContext } from '@brandboostinggmbh/observable-workflows'
+
+const queueContext = createQueueWorkflowContext({
+  workflowContext,
+  queue: env.WORKFLOW_QUEUE, // Cloudflare Queue binding
+})
+
+// Queue a workflow for processing
+await queueContext.queueWorkflow({
+  workflow: sendEmailWorkflow,
+  input: emailData,
+  workflowName: 'Queued Email',
+  tenantId: 'tenant-123',
+})
+```
+
+### Advanced Filtering and Querying
+
+```typescript
+// Filter workflows by properties and status
+const filteredWorkflows = await logAccessor.listWorkflows(50, 0, {
+  workflowStatus: ['completed', 'failed'],
+  properties: {
+    amount: { gt: 100 }, // Amount greater than 100
+    customerId: { equals: 'customer-456' },
+  },
+  startTime: {
+    gte: Date.now() - 24 * 60 * 60 * 1000, // Last 24 hours
+  },
+  workflowType: { contains: 'order' },
+})
+
+// Get workflow properties
+const properties = await logAccessor.getWorkflowProperties(instanceId)
 ```
 
+## API Reference
+
+### Core Functions
+
+#### `defineWorkflow<T>(type, callback)`
+
+Defines a new workflow type.
+
+**Parameters:**
+
+- `type` (string | object): Workflow type or configuration object
+- `callback` (function): Workflow implementation function
+
+**Returns:** `WorkflowFunction<T>`
+
+#### `createWorkflowContext(options)`
+
+Creates a workflow execution context.
+
+**Parameters:**
+
+- `options.D1` (D1Database): Cloudflare D1 database instance
+- `options.serializer?` (Serializer): Custom serialization (optional)
+- `options.idFactory?` (function): Custom ID generation (optional)
+
+**Returns:** `WorkflowContextInstance`
+
+#### `createLogAccessor(options)`
+
+Creates an accessor for querying workflow data.
+
+**Parameters:**
+
+- `options.D1` (D1Database): Cloudflare D1 database instance
+- `options.tenantId` (string): Tenant identifier
+- `options.serializer?` (Serializer): Custom serialization (optional)
+
+**Returns:** Log accessor with query methods
+
+### Workflow Context Methods
+
+#### `call(params)`
+
+Executes a workflow.
+
+**Parameters (object):**
+
+- `workflow` (WorkflowFunction): The workflow to execute
+- `input` (T): Input data for the workflow
+- `workflowName` (string): Human-readable workflow name
+- `tenantId` (string): Tenant identifier
+- `parentInstanceId?` (string): Parent workflow ID (for retries)
+- `reuseSuccessfulSteps?` (boolean): Whether to reuse successful steps in retries
+
+#### `retry(workflow, retryInstanceId, retryOptions?)`
+
+Retries a failed workflow.
+
+**Parameters:**
+
+- `workflow` (WorkflowFunction): The workflow definition
+- `retryInstanceId` (string): ID of the workflow to retry
+- `retryOptions?` (RetryWorkflowOptions): Retry configuration
+
+### Step Context
+
+Within a workflow, the step function provides:
+
+```typescript
+await step('step-name', async ({ console }) => {
+  console.log('Step is executing')
+  console.error('Something went wrong')
+  console.warn('Warning message')
+  // Simulate async operation
+  await new Promise((resolve) => setTimeout(resolve, 100))
+  // Return step result
+  return { success: true }
+})
+```
+
+### Workflow Context
+
+The workflow callback receives a context with:
+
+- `step` (function): Execute a workflow step
+- `console` (ConsoleWrapper): Logging interface
+- `setWorkflowName` (function): Update workflow name
+- `setWorkflowProperty` (function): Set workflow property
+
+## Configuration
+
+### Custom Serialization
+
+```typescript
+import { createWorkflowContext } from '@brandboostinggmbh/observable-workflows'
+
+const customSerializer = {
+  serialize: (obj: any) => JSON.stringify(obj),
+  deserialize: (str: string) => JSON.parse(str),
+}
+
+const context = createWorkflowContext({
+  D1: env.D1,
+  serializer: customSerializer,
+})
+```
+
+### Custom ID Generation
+
+```typescript
+const customIdFactory = () => `custom_${Date.now()}_${Math.random()}`
+
+const context = createWorkflowContext({
+  D1: env.D1,
+  idFactory: customIdFactory,
+})
+```
+
+## Database Schema
+
+The library automatically creates the following tables in your D1 database:
+
+- **WorkflowTable**: Stores workflow instances
+- **StepTable**: Stores individual step executions
+- **LogTable**: Stores all log entries
+- **WorkflowProperties**: Stores custom workflow properties
+
+Tables are created automatically when first accessing the database.
+
+## Error Handling
+
+The library provides comprehensive error handling:
+
+- **Step Failures**: Captured with full error details and stack traces
+- **Workflow Failures**: Marked with appropriate status and error information
+- **Retry Logic**: Failed workflows can be retried with step result reuse
+- **Validation**: Input validation and type checking
+
+## Best Practices
+
+1. **Use Descriptive Step Names**: Make step names descriptive for better observability
+2. **Keep Steps Atomic**: Each step should represent a single unit of work
+3. **Handle Errors Gracefully**: Use try-catch within steps for custom error handling
+4. **Use Properties for Searching**: Add relevant properties to make workflows searchable
+5. **Monitor Performance**: Use the logging data to monitor workflow performance
+6. **Tenant Isolation**: Always use consistent tenant IDs for proper data isolation
+
+## TypeScript Support
+
+This library is built with TypeScript and provides full type safety:
+
+```typescript
+interface MyInput {
+  userId: string
+  data: Record<string, any>
+}
+
+const typedWorkflow = defineWorkflow<MyInput>(
+  'my-workflow',
+  async (input, ctx) => {
+    // input is fully typed as MyInput
+    // ctx provides typed workflow context
+  },
+)
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
+
 ## License
 
 [MIT](./LICENSE) License © 2025 [Tim Stepanov](https://github.com/TimStepanovAtBrandBoosting)

package/dist/index.d.ts

@@ -49,7 +49,9 @@ declare function insertStepRecordFull(context: StepContextOptions, {
   startTime,
   endTime,
   result,
-  error
+  error,
+  resultRef,
+  errorRef
 }: {
   instanceId: string;
   name: string;
@@ -59,6 +61,8 @@ declare function insertStepRecordFull(context: StepContextOptions, {
   endTime: number | null;
   result: string | null;
   error: string | null;
+  resultRef?: string | null;
+  errorRef?: string | null;
 }): Promise<D1Result<Record<string, unknown>>>;
 declare function pushLogToDB(options: InternalWorkflowContextOptions, {
   instanceId,
@@ -78,6 +82,18 @@ declare function pushLogToDB(options: InternalWorkflowContextOptions, {
   tenantId: string;
 }): Promise<D1Result<Record<string, unknown>>>;
 declare function tryDeserializeObj(obj: string, serializer: Serializer): any;
+/**
+ * Serialize data and store externally if it exceeds the threshold
+ * Returns tuple of [data, externalRef] where one will be non-null
+ */
+declare function serializeWithExternalStorage(obj: any, serializer: Serializer, externalBlobStorage?: ExternalBlobStorage): Promise<{
+  data: string | null;
+  externalRef: string | null;
+}>;
+/**
+ * Deserialize data from direct storage or external storage
+ */
+declare function deserializeWithExternalStorage(data: string | null, externalRef: string | null, serializer: Serializer, externalBlobStorage?: ExternalBlobStorage): Promise<any>;
 /**
  * We want to save steps to a databse, we are using D1, so SQLite is the database.
  * Step Table:
@@ -98,7 +114,8 @@ declare function tryDeserializeObj(obj: string, serializer: Serializer): any;
  * - type: string (info, error, warning)
  */
 /**
- * Ensure that the required tables exist in D1 (SQLite).
+ * Ensure that the required tables exist in D1 (SQLite) and migrate schema if needed.
+ * This function is idempotent and ensures the schema matches the current requirements.
  */
 declare function ensureTables(db: D1Database): Promise<void>;
 declare function workflowTableRowToWorkflowRun(row: {
@@ -106,12 +123,13 @@ declare function workflowTableRowToWorkflowRun(row: {
   workflowType: string;
   workflowName: string;
   input: string;
+  inputRef: string | null;
   tenantId: string;
   workflowStatus: StepWorkflowStatus;
   startTime: number;
   endTime: number | null;
   parentInstanceId: string | null;
-}, serializer: Serializer): WorkflowRun;
+}, serializer: Serializer, externalBlobStorage?: ExternalBlobStorage): Promise<WorkflowRun>;
 declare function updateWorkflowName(context: {
   D1: D1Database;
 }, instanceId: string, newWorkflowName: string): Promise<D1Result<Record<string, unknown>>>;
@@ -149,6 +167,8 @@ type StepContextOptions = {
   idFactory: () => string;
   /** If true this step context will attempt to reuse results from parent instance steps where possible. Defaults to True */
   reuseSuccessfulSteps?: boolean;
+  /** Optional external blob storage for large data that exceeds D1 size limits */
+  externalBlobStorage?: ExternalBlobStorage;
 };
 type ConsoleWrapper = {
   log: (message?: any, ...optionalParams: any[]) => void;
@@ -205,15 +225,120 @@ type WorkflowPropertyDefinition = {
   key: string;
   valueType: 'string' | 'number' | 'boolean' | 'object';
 };
+/**
+ * Date range filter for filtering workflows by time periods
+ */
+type DateRangeFilter = {
+  /** Greater than or equal to (inclusive) */
+  gte?: number;
+  /** Less than or equal to (inclusive) */
+  lte?: number;
+  /** Greater than (exclusive) */
+  gt?: number;
+  /** Less than (exclusive) */
+  lt?: number;
+};
+/**
+ * String filter supporting exact match or substring matching
+ */
+type StringFilter = string | {
+  equals: string;
+} | {
+  contains: string;
+};
+/**
+ * Property filter supporting various comparison operators for custom workflow properties
+ */
+type PropertyFilter = {
+  /** Exact match */
+  equals?: any;
+  /** Substring match (for string values) */
+  contains?: string;
+  /** Greater than (for numeric values) */
+  gt?: number;
+  /** Greater than or equal to (for numeric values) */
+  gte?: number;
+  /** Less than (for numeric values) */
+  lt?: number;
+  /** Less than or equal to (for numeric values) */
+  lte?: number;
+  /** Match any value in the array */
+  in?: any[];
+};
+/**
+ * Comprehensive filter object for workflow listing with support for:
+ * - Text search across workflow names and types
+ * - Direct field filtering with various operators
+ * - Date range filtering
+ * - Custom property filtering with joins
+ *
+ * @example
+ * ```typescript
+ * // Text search
+ * const workflows = await listWorkflows(10, 0, { search: "payment" })
+ *
+ * // Status and type filtering
+ * const workflows = await listWorkflows(10, 0, {
+ *   workflowStatus: ["completed", "failed"],
+ *   workflowType: "PaymentWorkflow"
+ * })
+ *
+ * // Date range filtering
+ * const workflows = await listWorkflows(10, 0, {
+ *   startTime: { gte: Date.now() - 86400000 } // Last 24 hours
+ * })
+ *
+ * // Property filtering
+ * const workflows = await listWorkflows(10, 0, {
+ *   properties: {
+ *     amount: { gt: 100, lte: 1000 },
+ *     currency: { equals: "USD" },
+ *     customer: { contains: "acme" }
+ *   }
+ * })
+ *
+ * // Combined filtering
+ * const workflows = await listWorkflows(10, 0, {
+ *   search: "payment",
+ *   workflowStatus: "completed",
+ *   startTime: { gte: Date.now() - 86400000 },
+ *   properties: { amount: { gt: 100 } }
+ * })
+ * ```
+ */
+type WorkflowFilter = {
+  /** Text search across workflow name and type */
+  search?: string;
+  /** Filter by workflow type (exact match) */
+  workflowType?: string | string[];
+  /** Filter by workflow status */
+  workflowStatus?: StepWorkflowStatus | StepWorkflowStatus[];
+  /** Filter by workflow name with string matching */
+  workflowName?: StringFilter;
+  /** Filter by workflow start time */
+  startTime?: DateRangeFilter;
+  /** Filter by workflow end time */
+  endTime?: DateRangeFilter;
+  /** Filter by custom workflow properties */
+  properties?: {
+    [key: string]: PropertyFilter;
+  };
+};
 type StepContext = Awaited<ReturnType<typeof createStepContext>>;
 type Serializer = {
   serialize: (data: any) => string;
   deserialize: (data: string) => any;
 };
+type ExternalBlobStorage = {
+  threshold: number;
+  set: (data: string) => Promise<string>;
+  get: (id: string) => Promise<string>;
+};
 type WorkflowContextOptions = {
   D1: D1Database;
   idFactory?: () => string;
   serializer?: Serializer;
+  externalBlobStorage?: ExternalBlobStorage;
 };
 type InternalWorkflowContextOptions = WorkflowContextOptions & Required<Pick<WorkflowContextOptions, 'serializer' | 'idFactory'>>;
 type WorkflowContextInstance = {
@@ -263,43 +388,36 @@ type RetryWorkflowOptions = {
   reuseSuccessfulSteps?: boolean;
 };
 
-//#endregion
-//#region src/observableWorkflows/defineWorkflow.d.ts
-declare function defineWorkflow<I extends {} | null>(workflow: {
-  workflowType: string;
-  metadata?: Record<string, any>;
-}, callback: (input: I, ctx: WorkflowContext) => Promise<any>): WorkflowFunction<I>;
-declare function defineWorkflow<I extends {} | null>(workflowType: string, callback: (input: I, ctx: WorkflowContext) => Promise<any>): WorkflowFunction<I>;
-
-//#endregion
-//#region src/observableWorkflows/createWorkflowContext.d.ts
-declare function createWorkflowContext(options: WorkflowContextOptions): WorkflowContextInstance;
-
-//#endregion
-//#region src/observableWorkflows/createQueueWorkflowContext.d.ts
-declare function createQueueWorkflowContext(options: QueueWorkflowContextOptions): {
-  enqueueWorkflow: <I>(workflow: WorkflowFunction<I>, tenantId: string, input: I, initialName: string) => Promise<void>;
-  enqueueRetryWorkflow: <I>(workflow: WorkflowFunction<I>, tenantId: string, oldInstanceId: string) => Promise<void>;
-  handleWorkflowQueueMessage: (message: WorkflowQueueMessage, env: {
-    LOG_DB: D1Database;
-  }, workflowResolver: (workflowType: string) => WorkflowFunction<any> | undefined) => Promise<void>;
-};
-
 //#endregion
 //#region src/observableWorkflows/createLogAccessor.d.ts
 declare const createLogAccessor: (context: {
   D1: D1Database;
   tenantId: string;
   serializer?: Serializer;
+  externalBlobStorage?: ExternalBlobStorage;
 }) => {
   listSteps: (limit: number, offset: number, instanceId?: string | undefined) => Promise<Step[]>;
   getStep: (instanceId: string, stepName: string) => Promise<Step | null>;
-  listWorkflows: (limit: number, offset: number) => Promise<WorkflowRun[]>;
+  listWorkflows: (limit: number, offset: number, filter?: WorkflowFilter) => Promise<WorkflowRun[]>;
   getWorkflow: (instanceId: string) => Promise<WorkflowRun | null>;
   getWorkflowTypesByTenantId: (tenantId: string) => Promise<string[]>;
   getPropertiesKeys: (instanceId?: string) => Promise<WorkflowPropertyDefinition[]>;
 };
 
+//#endregion
+//#region src/observableWorkflows/createQueueWorkflowContext.d.ts
+declare function createQueueWorkflowContext(options: QueueWorkflowContextOptions): {
+  enqueueWorkflow: <I>(workflow: WorkflowFunction<I>, tenantId: string, input: I, initialName: string) => Promise<void>;
+  enqueueRetryWorkflow: <I>(workflow: WorkflowFunction<I>, tenantId: string, oldInstanceId: string) => Promise<void>;
+  handleWorkflowQueueMessage: (message: WorkflowQueueMessage, env: {
+    LOG_DB: D1Database;
+  }, workflowResolver: (workflowType: string) => WorkflowFunction<any> | undefined) => Promise<void>;
+};
+
+//#endregion
+//#region src/observableWorkflows/createWorkflowContext.d.ts
+declare function createWorkflowContext(options: WorkflowContextOptions): WorkflowContextInstance;
+
 //#endregion
 //#region src/observableWorkflows/defaultImplementations.d.ts
 declare const defaultSerializer: {
@@ -312,4 +430,48 @@ declare const defaultSerializer: {
 declare const defaultIdFactory: () => string;
 
 //#endregion
-export { ConsoleWrapper, InternalWorkflowContextOptions, Log, PossibleValueTypeNames, PossibleValueTypes, QueueWorkflowContextOptions, Serializer, Step, StepContextOptions, StepCtx, StepWorkflowStatus, ValueTypeMap, WorkflowContext, WorkflowContextInstance, WorkflowContextOptions, WorkflowFunction, WorkflowProperty, WorkflowPropertyDefinition, WorkflowQueueMessage, WorkflowRun, createLogAccessor, createQueueWorkflowContext, createStepContext, createWorkflowContext, defaultIdFactory, defaultSerializer, defineWorkflow, ensureTables, finalizeWorkflowRecord, insertStepRecordFull, insertWorkflowRecord, pushLogToDB, tryDeserializeObj, updateWorkflowName, upsertWorkflowProperty, workflowTableRowToWorkflowRun };
+//#region src/observableWorkflows/defineWorkflow.d.ts
+declare function defineWorkflow<I extends {} | null>(workflow: {
+  workflowType: string;
+  metadata?: Record<string, any>;
+}, callback: (input: I, ctx: WorkflowContext) => Promise<any>): WorkflowFunction<I>;
+declare function defineWorkflow<I extends {} | null>(workflowType: string, callback: (input: I, ctx: WorkflowContext) => Promise<any>): WorkflowFunction<I>;
+
+//#endregion
+//#region src/observableWorkflows/r2ExternalBlobStorage.d.ts
+/**
+ * Configuration options for Cloudflare R2 external blob storage
+ */
+type R2ExternalBlobStorageOptions = {
+  /** The R2 bucket instance to use for storage */
+  bucket: R2Bucket;
+  /** Size threshold in bytes for when to use external storage */
+  threshold: number;
+  /** Optional prefix for all keys stored in R2 */
+  keyPrefix?: string;
+  /** Optional custom ID factory for generating unique keys */
+  idFactory?: () => string;
+};
+/**
+ * Cloudflare R2 implementation of ExternalBlobStorage interface
+ *
+ * @example
+ * ```typescript
+ * import { createWorkflowContext, createR2ExternalBlobStorage } from '@brandboostinggmbh/observable-workflows'
+ *
+ * const externalBlobStorage = createR2ExternalBlobStorage({
+ *   bucket: env.MY_R2_BUCKET,
+ *   threshold: 1024 * 1024, // 1MB threshold
+ *   keyPrefix: 'workflows/', // Optional prefix
+ * })
+ *
+ * const workflowContext = createWorkflowContext({
+ *   D1: env.D1,
+ *   externalBlobStorage,
+ * })
+ * ```
+ */
+declare function createR2ExternalBlobStorage(options: R2ExternalBlobStorageOptions): ExternalBlobStorage;
+
+//#endregion
+export { ConsoleWrapper, DateRangeFilter, ExternalBlobStorage, InternalWorkflowContextOptions, Log, PossibleValueTypeNames, PossibleValueTypes, PropertyFilter, QueueWorkflowContextOptions, R2ExternalBlobStorageOptions, Serializer, Step, StepContextOptions, StepCtx, StepWorkflowStatus, StringFilter, ValueTypeMap, WorkflowContext, WorkflowContextInstance, WorkflowContextOptions, WorkflowFilter, WorkflowFunction, WorkflowProperty, WorkflowPropertyDefinition, WorkflowQueueMessage, WorkflowRun, createLogAccessor, createQueueWorkflowContext, createR2ExternalBlobStorage, createStepContext, createWorkflowContext, defaultIdFactory, defaultSerializer, defineWorkflow, deserializeWithExternalStorage, ensureTables, finalizeWorkflowRecord, insertStepRecordFull, insertWorkflowRecord, pushLogToDB, serializeWithExternalStorage, tryDeserializeObj, updateWorkflowName, upsertWorkflowProperty, workflowTableRowToWorkflowRun };