@hotmeshio/hotmesh 0.5.4 → 0.5.6

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

package/build/services/search/providers/postgres/postgres.js

@@ -156,7 +156,9 @@ class PostgresSearchService extends index_1.SearchService {
             const params = [entity];
             let paramIndex = 2;
             for (const [key, value] of Object.entries(conditions)) {
-                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                if (typeof value === 'object' &&
+                    value !== null &&
+                    !Array.isArray(value)) {
                     // Handle MongoDB-style operators like { $gte: 18 }
                     for (const [op, opValue] of Object.entries(value)) {
                         const sqlOp = this.mongoToSqlOperator(op);
@@ -188,14 +190,20 @@ class PostgresSearchService extends index_1.SearchService {
                 params.push(options.offset);
             }
             const result = await this.pgClient.query(sql, params);
-            return result.rows.map(row => ({
+            return result.rows.map((row) => ({
                 key: row.key,
-                context: typeof row.context === 'string' ? JSON.parse(row.context || '{}') : (row.context || {}),
+                context: typeof row.context === 'string'
+                    ? JSON.parse(row.context || '{}')
+                    : row.context || {},
                 status: row.status,
             }));
         }
         catch (error) {
-            this.logger.error(`postgres-find-entities-error`, { entity, conditions, error });
+            this.logger.error(`postgres-find-entities-error`, {
+                entity,
+                conditions,
+                error,
+            });
             throw error;
         }
     }
@@ -206,7 +214,7 @@ class PostgresSearchService extends index_1.SearchService {
             // Use KeyService to mint the job state key
             const fullKey = key_1.KeyService.mintKey(key_1.HMNS, key_1.KeyType.JOB_STATE, {
                 appId: this.appId,
-                jobId: id
+                jobId: id,
             });
             const sql = `
         SELECT key, context, status, entity
@@ -221,12 +229,18 @@ class PostgresSearchService extends index_1.SearchService {
             const row = result.rows[0];
             return {
                 key: row.key,
-                context: typeof row.context === 'string' ? JSON.parse(row.context || '{}') : (row.context || {}),
+                context: typeof row.context === 'string'
+                    ? JSON.parse(row.context || '{}')
+                    : row.context || {},
                 status: row.status,
             };
         }
         catch (error) {
-            this.logger.error(`postgres-find-entity-by-id-error`, { entity, id, error });
+            this.logger.error(`postgres-find-entity-by-id-error`, {
+                entity,
+                id,
+                error,
+            });
             throw error;
         }
     }
@@ -278,15 +292,21 @@ class PostgresSearchService extends index_1.SearchService {
                 params.push(options.offset);
             }
             const result = await this.pgClient.query(sql, params);
-            return result.rows.map(row => ({
+            return result.rows.map((row) => ({
                 key: row.key,
-                context: typeof row.context === 'string' ? JSON.parse(row.context || '{}') : (row.context || {}),
+                context: typeof row.context === 'string'
+                    ? JSON.parse(row.context || '{}')
+                    : row.context || {},
                 status: row.status,
             }));
         }
         catch (error) {
             this.logger.error(`postgres-find-entities-by-condition-error`, {
-                entity, field, value, operator, error
+                entity,
+                field,
+                value,
+                operator,
+                error,
             });
             throw error;
         }
@@ -323,11 +343,19 @@ class PostgresSearchService extends index_1.SearchService {
         `;
             }
             await this.pgClient.query(sql);
-            this.logger.info(`postgres-entity-index-created`, { entity, field, indexType, indexName });
+            this.logger.info(`postgres-entity-index-created`, {
+                entity,
+                field,
+                indexType,
+                indexName,
+            });
         }
         catch (error) {
             this.logger.error(`postgres-create-entity-index-error`, {
-                entity, field, indexType, error
+                entity,
+                field,
+                indexType,
+                error,
             });
             throw error;
         }
@@ -335,13 +363,13 @@ class PostgresSearchService extends index_1.SearchService {
     // Helper methods for entity operations
     mongoToSqlOperator(mongoOp) {
         const mapping = {
-            '$eq': '=',
-            '$ne': '!=',
-            '$gt': '>',
-            '$gte': '>=',
-            '$lt': '<',
-            '$lte': '<=',
-            '$in': 'IN',
+            $eq: '=',
+            $ne: '!=',
+            $gt: '>',
+            $gte: '>=',
+            $lt: '<',
+            $lte: '<=',
+            $in: 'IN',
         };
         return mapping[mongoOp] || '=';
     }

package/build/services/store/providers/postgres/kvtypes/hash/basic.js

@@ -31,7 +31,7 @@ function createBasicOperations(context) {
                 try {
                     const res = await context.pgClient.query(sql, params);
                     // Check if this is a JSONB operation that returns a value
-                    const isJsonbOperation = Object.keys(fields).some(k => k.startsWith('@context:') && k !== '@context');
+                    const isJsonbOperation = Object.keys(fields).some((k) => k.startsWith('@context:') && k !== '@context');
                     if (isJsonbOperation && res.rows[0]?.new_value !== undefined) {
                         let returnValue;
                         try {

package/build/services/store/providers/postgres/kvtypes/hash/index.js

@@ -75,7 +75,7 @@ const hashModule = (context) => {
                     const { sql, params } = jsonbOps.handleContextSetIfNotExists(key, fields, options);
                     return executeJsonbOperation(sql, params, multi);
                 }
-                else if (Object.keys(fields).some(k => k.startsWith('@context:get:'))) {
+                else if (Object.keys(fields).some((k) => k.startsWith('@context:get:'))) {
                     const { sql, params } = jsonbOps.handleContextGetPath(key, fields, options);
                     return executeJsonbOperation(sql, params, multi);
                 }
@@ -120,7 +120,7 @@ const hashModule = (context) => {
                 else if ('@context:setIfNotExists' in fields) {
                     return jsonbOps.handleContextSetIfNotExists(key, fields, options);
                 }
-                else if (Object.keys(fields).some(k => k.startsWith('@context:get:'))) {
+                else if (Object.keys(fields).some((k) => k.startsWith('@context:get:'))) {
                     return jsonbOps.handleContextGetPath(key, fields, options);
                 }
                 else if ('@context:get' in fields) {