@hotmeshio/hotmesh 0.5.4 → 0.5.6

package/build/services/memflow/index.d.ts

@@ -1,4 +1,4 @@
-import { ContextType } from '../../types/memflow';
+import { ContextType, WorkflowInterceptor } from '../../types/memflow';
 import { ClientService } from './client';
 import { ConnectionService } from './connection';
 import { Search } from './search';
@@ -8,60 +8,170 @@ import { WorkflowService } from './workflow';
 import { WorkflowHandleService } from './handle';
 import { didInterrupt } from './workflow/interruption';
 /**
- * The MemFlow service is a collection of services that
- * emulate Temporal's capabilities, but instead are
- * backed by Postgres or Redis/ValKey. The following lifecycle example
- * demonstrates how to start a new workflow, subscribe
- * to the result, and shutdown the system.
+ * The MemFlow service provides a Temporal-compatible workflow framework backed by
+ * Postgres or Redis/ValKey. It offers durable execution, entity-based memory management,
+ * and composable workflows.
  *
- * @example
+ * ## Core Features
+ *
+ * ### 1. Entity-Based Memory Model
+ * Each workflow has a durable JSONB entity that serves as its memory:
+ * ```typescript
+ * export async function researchAgent(query: string) {
+ *   const agent = await MemFlow.workflow.entity();
+ *
+ *   // Initialize entity state
+ *   await agent.set({
+ *     query,
+ *     findings: [],
+ *     status: 'researching'
+ *   });
+ *
+ *   // Update state atomically
+ *   await agent.merge({ status: 'analyzing' });
+ *   await agent.append('findings', newFinding);
+ * }
+ * ```
+ *
+ * ### 2. Hook Functions & Workflow Coordination
+ * Spawn and coordinate multiple perspectives/phases:
  * ```typescript
- * import { Client, Worker, MemFlow, HotMesh } from '@hotmeshio/hotmesh';
- * import { Client as Postgres} from 'pg';
- * import * as workflows from './workflows';
+ * // Launch parallel research perspectives
+ * await MemFlow.workflow.execHook({
+ *   taskQueue: 'research',
+ *   workflowName: 'optimisticView',
+ *   args: [query],
+ *   signalId: 'optimistic-complete'
+ * });
+ *
+ * await MemFlow.workflow.execHook({
+ *   taskQueue: 'research',
+ *   workflowName: 'skepticalView',
+ *   args: [query],
+ *   signalId: 'skeptical-complete'
+ * });
  *
- * //1) Initialize the worker
+ * // Wait for both perspectives
+ * await Promise.all([
+ *   MemFlow.workflow.waitFor('optimistic-complete'),
+ *   MemFlow.workflow.waitFor('skeptical-complete')
+ * ]);
+ * ```
+ *
+ * ### 3. Durable Activities & Proxies
+ * Define and execute durable activities with automatic retry:
+ * ```typescript
+ * const activities = MemFlow.workflow.proxyActivities<{
+ *   analyzeDocument: typeof analyzeDocument;
+ *   validateFindings: typeof validateFindings;
+ * }>({
+ *   activities: { analyzeDocument, validateFindings },
+ *   retryPolicy: {
+ *     maximumAttempts: 3,
+ *     backoffCoefficient: 2
+ *   }
+ * });
+ *
+ * // Activities are durable and automatically retried
+ * const analysis = await activities.analyzeDocument(data);
+ * const validation = await activities.validateFindings(analysis);
+ * ```
+ *
+ * ### 4. Workflow Composition
+ * Build complex workflows through composition:
+ * ```typescript
+ * // Start a child workflow
+ * const childResult = await MemFlow.workflow.execChild({
+ *   taskQueue: 'analysis',
+ *   workflowName: 'detailedAnalysis',
+ *   args: [data],
+ *   // Child workflow config
+ *   config: {
+ *     maximumAttempts: 5,
+ *     backoffCoefficient: 2
+ *   }
+ * });
+ *
+ * // Fire-and-forget child workflow
+ * await MemFlow.workflow.startChild({
+ *   taskQueue: 'notifications',
+ *   workflowName: 'sendUpdates',
+ *   args: [updates]
+ * });
+ * ```
+ *
+ * ### 5. Workflow Interceptors
+ * Add cross-cutting concerns through interceptors that run as durable functions:
+ * ```typescript
+ * // Add audit interceptor that uses MemFlow functions
+ * MemFlow.registerInterceptor({
+ *   async execute(ctx, next) {
+ *     try {
+ *       // Interceptors can use MemFlow functions and participate in replay
+ *       const entity = await MemFlow.workflow.entity();
+ *       await entity.append('auditLog', {
+ *         action: 'started',
+ *         timestamp: new Date().toISOString()
+ *       });
+ *
+ *       // Rate limiting with durable sleep
+ *       await MemFlow.workflow.sleepFor('100 milliseconds');
+ *
+ *       const result = await next();
+ *
+ *       await entity.append('auditLog', {
+ *         action: 'completed',
+ *         timestamp: new Date().toISOString()
+ *       });
+ *
+ *       return result;
+ *     } catch (err) {
+ *       // CRITICAL: Always check for HotMesh interruptions
+ *       if (MemFlow.didInterrupt(err)) {
+ *         throw err; // Rethrow for replay system
+ *       }
+ *       throw err;
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * ## Basic Usage Example
+ *
+ * ```typescript
+ * import { Client, Worker, MemFlow } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * // Initialize worker
  * await Worker.create({
  *   connection: {
  *     class: Postgres,
- *     options: {
- *       connectionString: 'postgresql://usr:pwd@localhost:5432/db',
- *     }
- *   }
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+ *   },
  *   taskQueue: 'default',
- *   namespace: 'memflow',
- *   workflow: workflows.example,
- *   options: {
- *     backoffCoefficient: 2,
- *     maximumAttempts: 1_000,
- *     maximumInterval: '5 seconds'
- *   }
+ *   workflow: workflows.example
  * });
  *
- * //2) initialize the client
+ * // Initialize client
  * const client = new Client({
  *   connection: {
  *     class: Postgres,
- *     options: {
- *       connectionString: 'postgresql://usr:pwd@localhost:5432/db',
- *     }
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
  *   }
  * });
  *
- * //3) start a new workflow
+ * // Start workflow
  * const handle = await client.workflow.start({
- *   args: ['HotMesh', 'es'],
+ *   args: ['input data'],
  *   taskQueue: 'default',
  *   workflowName: 'example',
- *   workflowId: HotMesh.guid(),
- *   namespace: 'memflow',
+ *   workflowId: MemFlow.guid()
  * });
  *
- * //4) subscribe to the eventual result
- * console.log('\nRESPONSE', await handle.result(), '\n');
- * //logs '¡Hola, HotMesh!'
+ * // Get result
+ * const result = await handle.result();
  *
- * //5) Shutdown (typically on sigint)
+ * // Cleanup
  * await MemFlow.shutdown();
  * ```
  */
@@ -114,6 +224,16 @@ declare class MemFlowClass {
      * @see {@link utils/interruption.didInterrupt} for detailed documentation
      */
     static didInterrupt: typeof didInterrupt;
+    private static interceptorService;
+    /**
+     * Register a workflow interceptor
+     * @param interceptor The interceptor to register
+     */
+    static registerInterceptor(interceptor: WorkflowInterceptor): void;
+    /**
+     * Clear all registered workflow interceptors
+     */
+    static clearInterceptors(): void;
     /**
      * Shutdown everything. All connections, workers, and clients will be closed.
      * Include in your signal handlers to ensure a clean shutdown.

package/build/services/memflow/index.js

@@ -10,61 +10,172 @@ const worker_1 = require("./worker");
 const workflow_1 = require("./workflow");
 const handle_1 = require("./handle");
 const interruption_1 = require("./workflow/interruption");
+const interceptor_1 = require("./interceptor");
 /**
- * The MemFlow service is a collection of services that
- * emulate Temporal's capabilities, but instead are
- * backed by Postgres or Redis/ValKey. The following lifecycle example
- * demonstrates how to start a new workflow, subscribe
- * to the result, and shutdown the system.
+ * The MemFlow service provides a Temporal-compatible workflow framework backed by
+ * Postgres or Redis/ValKey. It offers durable execution, entity-based memory management,
+ * and composable workflows.
  *
- * @example
+ * ## Core Features
+ *
+ * ### 1. Entity-Based Memory Model
+ * Each workflow has a durable JSONB entity that serves as its memory:
+ * ```typescript
+ * export async function researchAgent(query: string) {
+ *   const agent = await MemFlow.workflow.entity();
+ *
+ *   // Initialize entity state
+ *   await agent.set({
+ *     query,
+ *     findings: [],
+ *     status: 'researching'
+ *   });
+ *
+ *   // Update state atomically
+ *   await agent.merge({ status: 'analyzing' });
+ *   await agent.append('findings', newFinding);
+ * }
+ * ```
+ *
+ * ### 2. Hook Functions & Workflow Coordination
+ * Spawn and coordinate multiple perspectives/phases:
+ * ```typescript
+ * // Launch parallel research perspectives
+ * await MemFlow.workflow.execHook({
+ *   taskQueue: 'research',
+ *   workflowName: 'optimisticView',
+ *   args: [query],
+ *   signalId: 'optimistic-complete'
+ * });
+ *
+ * await MemFlow.workflow.execHook({
+ *   taskQueue: 'research',
+ *   workflowName: 'skepticalView',
+ *   args: [query],
+ *   signalId: 'skeptical-complete'
+ * });
+ *
+ * // Wait for both perspectives
+ * await Promise.all([
+ *   MemFlow.workflow.waitFor('optimistic-complete'),
+ *   MemFlow.workflow.waitFor('skeptical-complete')
+ * ]);
+ * ```
+ *
+ * ### 3. Durable Activities & Proxies
+ * Define and execute durable activities with automatic retry:
+ * ```typescript
+ * const activities = MemFlow.workflow.proxyActivities<{
+ *   analyzeDocument: typeof analyzeDocument;
+ *   validateFindings: typeof validateFindings;
+ * }>({
+ *   activities: { analyzeDocument, validateFindings },
+ *   retryPolicy: {
+ *     maximumAttempts: 3,
+ *     backoffCoefficient: 2
+ *   }
+ * });
+ *
+ * // Activities are durable and automatically retried
+ * const analysis = await activities.analyzeDocument(data);
+ * const validation = await activities.validateFindings(analysis);
+ * ```
+ *
+ * ### 4. Workflow Composition
+ * Build complex workflows through composition:
+ * ```typescript
+ * // Start a child workflow
+ * const childResult = await MemFlow.workflow.execChild({
+ *   taskQueue: 'analysis',
+ *   workflowName: 'detailedAnalysis',
+ *   args: [data],
+ *   // Child workflow config
+ *   config: {
+ *     maximumAttempts: 5,
+ *     backoffCoefficient: 2
+ *   }
+ * });
+ *
+ * // Fire-and-forget child workflow
+ * await MemFlow.workflow.startChild({
+ *   taskQueue: 'notifications',
+ *   workflowName: 'sendUpdates',
+ *   args: [updates]
+ * });
+ * ```
+ *
+ * ### 5. Workflow Interceptors
+ * Add cross-cutting concerns through interceptors that run as durable functions:
  * ```typescript
- * import { Client, Worker, MemFlow, HotMesh } from '@hotmeshio/hotmesh';
- * import { Client as Postgres} from 'pg';
- * import * as workflows from './workflows';
+ * // Add audit interceptor that uses MemFlow functions
+ * MemFlow.registerInterceptor({
+ *   async execute(ctx, next) {
+ *     try {
+ *       // Interceptors can use MemFlow functions and participate in replay
+ *       const entity = await MemFlow.workflow.entity();
+ *       await entity.append('auditLog', {
+ *         action: 'started',
+ *         timestamp: new Date().toISOString()
+ *       });
+ *
+ *       // Rate limiting with durable sleep
+ *       await MemFlow.workflow.sleepFor('100 milliseconds');
+ *
+ *       const result = await next();
+ *
+ *       await entity.append('auditLog', {
+ *         action: 'completed',
+ *         timestamp: new Date().toISOString()
+ *       });
  *
- * //1) Initialize the worker
+ *       return result;
+ *     } catch (err) {
+ *       // CRITICAL: Always check for HotMesh interruptions
+ *       if (MemFlow.didInterrupt(err)) {
+ *         throw err; // Rethrow for replay system
+ *       }
+ *       throw err;
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * ## Basic Usage Example
+ *
+ * ```typescript
+ * import { Client, Worker, MemFlow } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * // Initialize worker
  * await Worker.create({
  *   connection: {
  *     class: Postgres,
- *     options: {
- *       connectionString: 'postgresql://usr:pwd@localhost:5432/db',
- *     }
- *   }
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+ *   },
  *   taskQueue: 'default',
- *   namespace: 'memflow',
- *   workflow: workflows.example,
- *   options: {
- *     backoffCoefficient: 2,
- *     maximumAttempts: 1_000,
- *     maximumInterval: '5 seconds'
- *   }
+ *   workflow: workflows.example
  * });
  *
- * //2) initialize the client
+ * // Initialize client
  * const client = new Client({
  *   connection: {
  *     class: Postgres,
- *     options: {
- *       connectionString: 'postgresql://usr:pwd@localhost:5432/db',
- *     }
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
  *   }
  * });
  *
- * //3) start a new workflow
+ * // Start workflow
  * const handle = await client.workflow.start({
- *   args: ['HotMesh', 'es'],
+ *   args: ['input data'],
  *   taskQueue: 'default',
  *   workflowName: 'example',
- *   workflowId: HotMesh.guid(),
- *   namespace: 'memflow',
+ *   workflowId: MemFlow.guid()
  * });
  *
- * //4) subscribe to the eventual result
- * console.log('\nRESPONSE', await handle.result(), '\n');
- * //logs '¡Hola, HotMesh!'
+ * // Get result
+ * const result = await handle.result();
  *
- * //5) Shutdown (typically on sigint)
+ * // Cleanup
  * await MemFlow.shutdown();
  * ```
  */
@@ -73,6 +184,26 @@ class MemFlowClass {
      * @private
      */
     constructor() { }
+    /**
+     * Register a workflow interceptor
+     * @param interceptor The interceptor to register
+     */
+    static registerInterceptor(interceptor) {
+        MemFlowClass.interceptorService.register(interceptor);
+    }
+    /**
+     * Clear all registered workflow interceptors
+     */
+    static clearInterceptors() {
+        MemFlowClass.interceptorService.clear();
+    }
+    /**
+     * Get the interceptor service instance
+     * @internal
+     */
+    static getInterceptorService() {
+        return MemFlowClass.interceptorService;
+    }
     /**
      * Shutdown everything. All connections, workers, and clients will be closed.
      * Include in your signal handlers to ensure a clean shutdown.
@@ -128,3 +259,4 @@ MemFlowClass.workflow = workflow_1.WorkflowService;
  * @see {@link utils/interruption.didInterrupt} for detailed documentation
  */
 MemFlowClass.didInterrupt = interruption_1.didInterrupt;
+MemFlowClass.interceptorService = new interceptor_1.InterceptorService();

package/build/services/memflow/interceptor.d.ts

@@ -0,0 +1,241 @@
+import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
+/**
+ * Service for managing workflow interceptors that wrap workflow execution
+ * in an onion-like pattern. Each interceptor can perform actions before
+ * and after workflow execution, add cross-cutting concerns, and handle errors.
+ *
+ * ## Basic Interceptor Pattern
+ *
+ * @example
+ * ```typescript
+ * // Create and configure interceptors
+ * const service = new InterceptorService();
+ *
+ * // Add logging interceptor (outermost)
+ * service.register({
+ *   async execute(ctx, next) {
+ *     console.log('Starting workflow');
+ *     const result = await next();
+ *     console.log('Workflow completed');
+ *     return result;
+ *   }
+ * });
+ *
+ * // Add metrics interceptor (middle)
+ * service.register({
+ *   async execute(ctx, next) {
+ *     const timer = startTimer();
+ *     const result = await next();
+ *     recordDuration(timer.end());
+ *     return result;
+ *   }
+ * });
+ *
+ * // Add error handling interceptor (innermost)
+ * service.register({
+ *   async execute(ctx, next) {
+ *     try {
+ *       return await next();
+ *     } catch (err) {
+ *       reportError(err);
+ *       throw err;
+ *     }
+ *   }
+ * });
+ *
+ * // Execute workflow through interceptor chain
+ * const result = await service.executeChain(context, async () => {
+ *   return await workflowFn();
+ * });
+ * ```
+ *
+ * ## Durable Interceptors with MemFlow Functions
+ *
+ * Interceptors run within the workflow's async local storage context, which means
+ * they can use MemFlow functions like `sleepFor`, `entity`, `proxyActivities`, etc.
+ * These interceptors participate in the HotMesh interruption/replay pattern.
+ *
+ * @example
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Rate limiting interceptor that sleeps before execution
+ * const rateLimitInterceptor: WorkflowInterceptor = {
+ *   async execute(ctx, next) {
+ *     try {
+ *       // This sleep will cause an interruption on first execution
+ *       await MemFlow.workflow.sleepFor('1 second');
+ *
+ *       const result = await next();
+ *
+ *       // Another sleep after workflow completes
+ *       await MemFlow.workflow.sleepFor('500 milliseconds');
+ *
+ *       return result;
+ *     } catch (err) {
+ *       // CRITICAL: Always check for HotMesh interruptions
+ *       if (MemFlow.didInterrupt(err)) {
+ *         throw err; // Rethrow interruptions for replay system
+ *       }
+ *       // Handle actual errors
+ *       console.error('Interceptor error:', err);
+ *       throw err;
+ *     }
+ *   }
+ * };
+ *
+ * // Entity-based audit interceptor
+ * const auditInterceptor: WorkflowInterceptor = {
+ *   async execute(ctx, next) {
+ *     try {
+ *       const entity = await MemFlow.workflow.entity();
+ *       await entity.append('auditLog', {
+ *         action: 'workflow_started',
+ *         timestamp: new Date().toISOString(),
+ *         workflowId: ctx.get('workflowId')
+ *       });
+ *
+ *       const startTime = Date.now();
+ *       const result = await next();
+ *       const duration = Date.now() - startTime;
+ *
+ *       await entity.append('auditLog', {
+ *         action: 'workflow_completed',
+ *         timestamp: new Date().toISOString(),
+ *         duration,
+ *         success: true
+ *       });
+ *
+ *       return result;
+ *     } catch (err) {
+ *       if (MemFlow.didInterrupt(err)) {
+ *         throw err;
+ *       }
+ *
+ *       // Log failure to entity
+ *       const entity = await MemFlow.workflow.entity();
+ *       await entity.append('auditLog', {
+ *         action: 'workflow_failed',
+ *         timestamp: new Date().toISOString(),
+ *         error: err.message
+ *       });
+ *
+ *       throw err;
+ *     }
+ *   }
+ * };
+ *
+ * // Register interceptors
+ * MemFlow.registerInterceptor(rateLimitInterceptor);
+ * MemFlow.registerInterceptor(auditInterceptor);
+ * ```
+ *
+ * ## Execution Pattern with Interruptions
+ *
+ * When interceptors use MemFlow functions, the workflow will execute multiple times
+ * due to the interruption/replay pattern:
+ *
+ * 1. **First execution**: Interceptor calls `sleepFor` → throws `MemFlowSleepError` → workflow pauses
+ * 2. **Second execution**: Interceptor sleep replays (skipped), workflow runs → proxy activity throws `MemFlowProxyError` → workflow pauses
+ * 3. **Third execution**: All previous operations replay, interceptor sleep after workflow → throws `MemFlowSleepError` → workflow pauses
+ * 4. **Fourth execution**: Everything replays successfully, workflow completes
+ *
+ * This pattern ensures deterministic, durable execution across all interceptors and workflow code.
+ *
+ * @example
+ * ```typescript
+ * // Interceptor with complex MemFlow operations
+ * const complexInterceptor: WorkflowInterceptor = {
+ *   async execute(ctx, next) {
+ *     try {
+ *       // Get persistent state
+ *       const entity = await MemFlow.workflow.entity();
+ *       const state = await entity.get() as any;
+ *
+ *       // Conditional durable operations
+ *       if (!state.preProcessed) {
+ *         await MemFlow.workflow.sleepFor('100 milliseconds');
+ *         await entity.merge({ preProcessed: true });
+ *       }
+ *
+ *       // Execute the workflow
+ *       const result = await next();
+ *
+ *       // Post-processing with child workflow
+ *       if (!state.postProcessed) {
+ *         await MemFlow.workflow.execChild({
+ *           taskQueue: 'cleanup',
+ *           workflowName: 'cleanupWorkflow',
+ *           args: [result]
+ *         });
+ *         await entity.merge({ postProcessed: true });
+ *       }
+ *
+ *       return result;
+ *     } catch (err) {
+ *       if (MemFlow.didInterrupt(err)) {
+ *         throw err;
+ *       }
+ *       throw err;
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export declare class InterceptorService implements InterceptorRegistry {
+    interceptors: WorkflowInterceptor[];
+    /**
+     * Register a new workflow interceptor that will wrap workflow execution.
+     * Interceptors are executed in the order they are registered, with the
+     * first registered interceptor being the outermost wrapper.
+     *
+     * @param interceptor The interceptor to register
+     *
+     * @example
+     * ```typescript
+     * service.register({
+     *   async execute(ctx, next) {
+     *     console.time('workflow');
+     *     try {
+     *       return await next();
+     *     } finally {
+     *       console.timeEnd('workflow');
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    register(interceptor: WorkflowInterceptor): void;
+    /**
+     * Execute the interceptor chain around the workflow function.
+     * The chain is built in an onion pattern where each interceptor
+     * wraps the next one, with the workflow function at the center.
+     *
+     * @param ctx The workflow context map
+     * @param fn The workflow function to execute
+     * @returns The result of the workflow execution
+     *
+     * @example
+     * ```typescript
+     * // Execute workflow with timing
+     * const result = await service.executeChain(context, async () => {
+     *   const start = Date.now();
+     *   try {
+     *     return await workflowFn();
+     *   } finally {
+     *     console.log('Duration:', Date.now() - start);
+     *   }
+     * });
+     * ```
+     */
+    executeChain(ctx: Map<string, any>, fn: () => Promise<any>): Promise<any>;
+    /**
+     * Clear all registered interceptors.
+     *
+     * @example
+     * ```typescript
+     * service.clear();
+     * ```
+     */
+    clear(): void;
+}