@hotmeshio/hotmesh 0.5.5 → 0.5.6

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;
+}

package/build/services/memflow/interceptor.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InterceptorService = void 0;
+/**
+ * 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;
+ *     }
+ *   }
+ * };
+ * ```
+ */
+class InterceptorService {
+    constructor() {
+        this.interceptors = [];
+    }
+    /**
+     * 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) {
+        this.interceptors.push(interceptor);
+    }
+    /**
+     * 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);
+     *   }
+     * });
+     * ```
+     */
+    async executeChain(ctx, fn) {
+        // Create the onion-like chain of interceptors
+        const chain = this.interceptors.reduceRight((next, interceptor) => {
+            return () => interceptor.execute(ctx, next);
+        }, fn);
+        return chain();
+    }
+    /**
+     * Clear all registered interceptors.
+     *
+     * @example
+     * ```typescript
+     * service.clear();
+     * ```
+     */
+    clear() {
+        this.interceptors = [];
+    }
+}
+exports.InterceptorService = InterceptorService;

package/build/services/memflow/worker.js

@@ -10,6 +10,7 @@ const hotmesh_1 = require("../hotmesh");
 const stream_1 = require("../../types/stream");
 const search_1 = require("./search");
 const factory_1 = require("./schemas/factory");
+const index_1 = require("./index");
 /**
  * The *Worker* service Registers worker functions and connects them to the mesh,
  * using the target backend provider/s (Redis, Postgres, NATS, etc).
@@ -321,8 +322,16 @@ class WorkerService {
                 const [cursor, replay] = await store.findJobFields(workflowInput.workflowId, replayQuery, 50000, 5000);
                 context.set('replay', replay);
                 context.set('cursor', cursor); // if != 0, more remain
+                // Execute workflow with interceptors
                 const workflowResponse = await storage_1.asyncLocalStorage.run(context, async () => {
-                    return await workflowFunction.apply(this, workflowInput.arguments);
+                    // Get the interceptor service
+                    const interceptorService = index_1.MemFlow.getInterceptorService();
+                    // Create the workflow execution function
+                    const execWorkflow = async () => {
+                        return await workflowFunction.apply(this, workflowInput.arguments);
+                    };
+                    // Execute the workflow through the interceptor chain
+                    return await interceptorService.executeChain(context, execWorkflow);
                 });
                 //if the embedded function has a try/catch, it can interrup the throw
                 // throw here to interrupt the workflow if the embedded function caught and suppressed

package/build/services/memflow/workflow/execChild.js

@@ -22,7 +22,9 @@ function getChildInterruptPayload(context, options, execIndex) {
     }
     const parentWorkflowId = workflowId;
     const taskQueueName = options.taskQueue ?? options.entity;
-    const workflowName = options.taskQueue ? options.workflowName : (options.entity ?? options.workflowName);
+    const workflowName = options.taskQueue
+        ? options.workflowName
+        : options.entity ?? options.workflowName;
     const workflowTopic = `${taskQueueName}-${workflowName}`;
     return {
         arguments: [...(options.args || [])],

package/build/services/memflow/workflow/execHook.js

@@ -67,7 +67,7 @@ async function execHook(options) {
         }
         const hookOptions = {
             ...options,
-            args: [...options.args, { signal: options.signalId, $memflow: true }]
+            args: [...options.args, { signal: options.signalId, $memflow: true }],
         };
         // Execute the hook with the signal information
         await (0, hook_1.hook)(hookOptions);

package/build/services/memflow/workflow/hook.js

@@ -27,7 +27,9 @@ async function hook(options) {
             targetTopic = workflowTopic;
         }
         // DEFENSIVE CHECK: Prevent infinite loops
-        if (targetTopic === workflowTopic && !options.entity && !options.taskQueue) {
+        if (targetTopic === workflowTopic &&
+            !options.entity &&
+            !options.taskQueue) {
             throw new Error(`MemFlow Hook Error: Potential infinite loop detected!\n\n` +
                 `The hook would target the same workflow topic ('${workflowTopic}') as the current workflow, ` +
                 `creating an infinite loop.\n\n` +
@@ -39,7 +41,7 @@ async function hook(options) {
                 `Provided options: ${JSON.stringify({
                     workflowName: options.workflowName,
                     taskQueue: options.taskQueue,
-                    entity: options.entity
+                    entity: options.entity,
                 }, null, 2)}`);
         }
         const payload = {

package/build/services/memflow/workflow/proxyActivities.js

@@ -55,7 +55,8 @@ function wrapActivity(activityName, options) {
                         throw new common_1.MemFlowTimeoutError(message, stack);
                     }
                     else {
-                        // Non-fatal error
+                        // For any other error code, throw a MemFlowFatalError to stop the workflow
+                        throw new common_1.MemFlowFatalError(message, stack);
                     }
                 }
                 return result.$error;

package/build/services/router/consumption/index.js

@@ -49,12 +49,20 @@ class ConsumptionManager {
         const features = this.stream.getProviderSpecificFeatures();
         const supportsNotifications = features.supportsNotifications;
         if (supportsNotifications) {
-            this.logger.info(`router-stream-using-notifications`, { group, consumer, stream });
+            this.logger.info(`router-stream-using-notifications`, {
+                group,
+                consumer,
+                stream,
+            });
             this.lifecycleManager.setIsUsingNotifications(true);
             return this.consumeWithNotifications(stream, group, consumer, callback);
         }
         else {
-            this.logger.info(`router-stream-using-polling`, { group, consumer, stream });
+            this.logger.info(`router-stream-using-polling`, {
+                group,
+                consumer,
+                stream,
+            });
             this.lifecycleManager.setIsUsingNotifications(false);
             return this.consumeWithPolling(stream, group, consumer, callback);
         }
@@ -67,7 +75,8 @@ class ConsumptionManager {
                 return;
             }
             await this.throttleManager.customSleep(); // respect throttle
-            if (this.lifecycleManager.isStopped(group, consumer, stream) || this.throttleManager.isPaused()) {
+            if (this.lifecycleManager.isStopped(group, consumer, stream) ||
+                this.throttleManager.isPaused()) {
                 return;
             }
             // Process messages - use parallel processing for PostgreSQL
@@ -78,7 +87,7 @@ class ConsumptionManager {
                 this.logger.debug('postgres-stream-parallel-processing', {
                     streamName: stream,
                     groupName: group,
-                    messageCount: messages.length
+                    messageCount: messages.length,
                 });
                 const processingStart = Date.now();
                 const processingPromises = messages.map(async (message) => {
@@ -93,7 +102,7 @@ class ConsumptionManager {
                     streamName: stream,
                     groupName: group,
                     messageCount: messages.length,
-                    processingDuration: Date.now() - processingStart
+                    processingDuration: Date.now() - processingStart,
                 });
             }
             else {
@@ -153,7 +162,11 @@ class ConsumptionManager {
                 consumer,
             });
             // Fall back to polling if notifications fail
-            this.logger.info(`router-stream-fallback-to-polling`, { group, consumer, stream });
+            this.logger.info(`router-stream-fallback-to-polling`, {
+                group,
+                consumer,
+                stream,
+            });
             this.lifecycleManager.setIsUsingNotifications(false);
             return this.consumeWithPolling(stream, group, consumer, callback);
         }
@@ -223,7 +236,7 @@ class ConsumptionManager {
                         this.logger.debug('postgres-stream-parallel-processing-polling', {
                             streamName: stream,
                             groupName: group,
-                            messageCount: messages.length
+                            messageCount: messages.length,
                         });
                         const processingStart = Date.now();
                         const processingPromises = messages.map(async (message) => {
@@ -238,7 +251,7 @@ class ConsumptionManager {
                             streamName: stream,
                             groupName: group,
                             messageCount: messages.length,
-                            processingDuration: Date.now() - processingStart
+                            processingDuration: Date.now() - processingStart,
                         });
                     }
                     else {
@@ -299,7 +312,8 @@ class ConsumptionManager {
                 }
             }
             catch (error) {
-                if (this.lifecycleManager.getShouldConsume() && process.env.NODE_ENV !== 'test') {
+                if (this.lifecycleManager.getShouldConsume() &&
+                    process.env.NODE_ENV !== 'test') {
                     this.logger.error(`router-stream-error`, {
                         error,
                         stream,

package/build/services/router/error-handling/index.js

@@ -82,16 +82,16 @@ class ErrorHandler {
         const [shouldRetry, timeout] = this.shouldRetry(input, output);
         if (shouldRetry) {
             await (0, utils_1.sleepFor)(timeout);
-            return await publishMessage(input.metadata.topic, {
+            return (await publishMessage(input.metadata.topic, {
                 data: input.data,
                 //note: retain guid (this is a retry attempt)
                 metadata: { ...input.metadata, try: (input.metadata.try || 0) + 1 },
                 policies: input.policies,
-            });
+            }));
         }
         else {
             const structuredError = this.structureError(input, output);
-            return await publishMessage(null, structuredError);
+            return (await publishMessage(null, structuredError));
         }
     }
 }