@hotmeshio/hotmesh 0.9.0 → 0.10.0

package/build/services/{memflow → durable}/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemFlow = void 0;
+exports.Durable = void 0;
 const hotmesh_1 = require("../hotmesh");
 const utils_1 = require("../../modules/utils");
 const client_1 = require("./client");
@@ -13,9 +13,9 @@ const handle_1 = require("./handle");
 const interruption_1 = require("./workflow/interruption");
 const interceptor_1 = require("./interceptor");
 /**
- * The MemFlow service provides a Temporal-compatible workflow framework backed by
- * Postgres. It offers durable execution, entity-based memory management,
- * and composable workflows.
+ * The Durable service provides a Temporal-compatible workflow framework backed
+ * by Postgres. It offers entity-based memory management and composable,
+ * fault-tolerant workflows.
  *
  * ## Core Features
  *
@@ -23,7 +23,7 @@ const interceptor_1 = require("./interceptor");
  * 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();
+ *   const agent = await Durable.workflow.entity();
  *
  *   // Initialize entity state
  *   await agent.set({
@@ -42,14 +42,14 @@ const interceptor_1 = require("./interceptor");
  * Spawn and coordinate multiple perspectives/phases:
  * ```typescript
  * // Launch parallel research perspectives
- * await MemFlow.workflow.execHook({
+ * await Durable.workflow.execHook({
  *   taskQueue: 'research',
  *   workflowName: 'optimisticView',
  *   args: [query],
  *   signalId: 'optimistic-complete'
  * });
  *
- * await MemFlow.workflow.execHook({
+ * await Durable.workflow.execHook({
  *   taskQueue: 'research',
  *   workflowName: 'skepticalView',
  *   args: [query],
@@ -58,8 +58,8 @@ const interceptor_1 = require("./interceptor");
  *
  * // Wait for both perspectives
  * await Promise.all([
- *   MemFlow.workflow.waitFor('optimistic-complete'),
- *   MemFlow.workflow.waitFor('skeptical-complete')
+ *   Durable.workflow.waitFor('optimistic-complete'),
+ *   Durable.workflow.waitFor('skeptical-complete')
  * ]);
  * ```
  *
@@ -67,7 +67,7 @@ const interceptor_1 = require("./interceptor");
  * Define and execute durable activities with automatic retry:
  * ```typescript
  * // Default: activities use workflow's task queue
- * const activities = MemFlow.workflow.proxyActivities<{
+ * const activities = Durable.workflow.proxyActivities<{
  *   analyzeDocument: typeof analyzeDocument;
  *   validateFindings: typeof validateFindings;
  * }>({
@@ -87,7 +87,7 @@ const interceptor_1 = require("./interceptor");
  * Register activity workers explicitly before workflows start:
  * ```typescript
  * // Register shared activity pool for interceptors
- * await MemFlow.registerActivityWorker({
+ * await Durable.registerActivityWorker({
  *   connection: {
  *     class: Postgres,
  *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
@@ -96,7 +96,7 @@ const interceptor_1 = require("./interceptor");
  * }, sharedActivities, 'shared-activities');
  *
  * // Register custom activity pool for specific use cases
- * await MemFlow.registerActivityWorker({
+ * await Durable.registerActivityWorker({
  *   connection: {
  *     class: Postgres,
  *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
@@ -109,7 +109,7 @@ const interceptor_1 = require("./interceptor");
  * Build complex workflows through composition:
  * ```typescript
  * // Start a child workflow
- * const childResult = await MemFlow.workflow.execChild({
+ * const childResult = await Durable.workflow.execChild({
  *   taskQueue: 'analysis',
  *   workflowName: 'detailedAnalysis',
  *   args: [data],
@@ -121,7 +121,7 @@ const interceptor_1 = require("./interceptor");
  * });
  *
  * // Fire-and-forget child workflow
- * await MemFlow.workflow.startChild({
+ * await Durable.workflow.startChild({
  *   taskQueue: 'notifications',
  *   workflowName: 'sendUpdates',
  *   args: [updates]
@@ -132,7 +132,7 @@ const interceptor_1 = require("./interceptor");
  * Add cross-cutting concerns through interceptors that run as durable functions:
  * ```typescript
  * // First register shared activity worker for interceptors
- * await MemFlow.registerActivityWorker({
+ * await Durable.registerActivityWorker({
  *   connection: {
  *     class: Postgres,
  *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
@@ -141,11 +141,11 @@ const interceptor_1 = require("./interceptor");
  * }, { auditLog }, 'interceptor-activities');
  *
  * // Add audit interceptor that uses activities with explicit taskQueue
- * MemFlow.registerInterceptor({
+ * Durable.registerInterceptor({
  *   async execute(ctx, next) {
  *     try {
  *       // Interceptors use explicit taskQueue to prevent per-workflow queues
- *       const { auditLog } = MemFlow.workflow.proxyActivities<typeof activities>({
+ *       const { auditLog } = Durable.workflow.proxyActivities<typeof activities>({
  *         activities: { auditLog },
  *         taskQueue: 'interceptor-activities', // Explicit shared queue
  *         retryPolicy: { maximumAttempts: 3 }
@@ -160,7 +160,7 @@ const interceptor_1 = require("./interceptor");
  *       return result;
  *     } catch (err) {
  *       // CRITICAL: Always check for HotMesh interruptions
- *       if (MemFlow.didInterrupt(err)) {
+ *       if (Durable.didInterrupt(err)) {
  *         throw err; // Rethrow for replay system
  *       }
  *       throw err;
@@ -169,15 +169,71 @@ const interceptor_1 = require("./interceptor");
  * });
  * ```
  *
+ * ### 7. Activity Interceptors
+ * Wrap individual proxied activity calls with cross-cutting logic.
+ * Unlike workflow interceptors (which wrap the entire workflow), activity
+ * interceptors execute around each `proxyActivities` call. They run inside
+ * the workflow's execution context and have access to all Durable workflow
+ * methods (`proxyActivities`, `sleepFor`, `waitFor`, `execChild`, etc.).
+ * Multiple activity interceptors execute in onion order (first registered
+ * is outermost).
+ * ```typescript
+ * // Simple logging interceptor
+ * Durable.registerActivityInterceptor({
+ *   async execute(activityCtx, workflowCtx, next) {
+ *     console.log(`Activity ${activityCtx.activityName} starting`);
+ *     try {
+ *       const result = await next();
+ *       console.log(`Activity ${activityCtx.activityName} completed`);
+ *       return result;
+ *     } catch (err) {
+ *       if (Durable.didInterrupt(err)) throw err;
+ *       console.error(`Activity ${activityCtx.activityName} failed`);
+ *       throw err;
+ *     }
+ *   }
+ * });
+ *
+ * // Interceptor that calls its own proxy activities
+ * await Durable.registerActivityWorker({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+ *   },
+ *   taskQueue: 'audit-activities'
+ * }, { auditLog }, 'audit-activities');
+ *
+ * Durable.registerActivityInterceptor({
+ *   async execute(activityCtx, workflowCtx, next) {
+ *     try {
+ *       const { auditLog } = Durable.workflow.proxyActivities<{
+ *         auditLog: (id: string, action: string) => Promise<void>;
+ *       }>({
+ *         taskQueue: 'audit-activities',
+ *         retryPolicy: { maximumAttempts: 3 }
+ *       });
+ *
+ *       await auditLog(workflowCtx.get('workflowId'), `before:${activityCtx.activityName}`);
+ *       const result = await next();
+ *       await auditLog(workflowCtx.get('workflowId'), `after:${activityCtx.activityName}`);
+ *       return result;
+ *     } catch (err) {
+ *       if (Durable.didInterrupt(err)) throw err;
+ *       throw err;
+ *     }
+ *   }
+ * });
+ * ```
+ *
  * ## Basic Usage Example
  *
  * ```typescript
- * import { Client, Worker, MemFlow } from '@hotmeshio/hotmesh';
+ * import { Client, Worker, Durable } from '@hotmeshio/hotmesh';
  * import { Client as Postgres } from 'pg';
  * import * as activities from './activities';
  *
  * // (Optional) Register shared activity workers for interceptors
- * await MemFlow.registerActivityWorker({
+ * await Durable.registerActivityWorker({
  *   connection: {
  *     class: Postgres,
  *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
@@ -208,17 +264,17 @@ const interceptor_1 = require("./interceptor");
  *   args: ['input data'],
  *   taskQueue: 'default',
  *   workflowName: 'example',
- *   workflowId: MemFlow.guid()
+ *   workflowId: Durable.guid()
  * });
  *
  * // Get result
  * const result = await handle.result();
  *
  * // Cleanup
- * await MemFlow.shutdown();
+ * await Durable.shutdown();
  * ```
  */
-class MemFlowClass {
+class DurableClass {
     /**
      * @private
      */
@@ -228,62 +284,102 @@ class MemFlowClass {
      * @param interceptor The interceptor to register
      */
     static registerInterceptor(interceptor) {
-        MemFlowClass.interceptorService.register(interceptor);
+        DurableClass.interceptorService.register(interceptor);
     }
     /**
-     * Clear all registered workflow interceptors
+     * Clear all registered interceptors (both workflow and activity)
      */
     static clearInterceptors() {
-        MemFlowClass.interceptorService.clear();
+        DurableClass.interceptorService.clear();
+    }
+    /**
+     * Register an activity interceptor that wraps individual proxied
+     * activity calls within workflows. Interceptors execute in registration
+     * order (first registered is outermost) using the onion pattern.
+     *
+     * Activity interceptors run inside the workflow's execution context
+     * and have access to all Durable workflow methods (`proxyActivities`,
+     * `sleepFor`, `waitFor`, `execChild`, etc.). The `activityCtx` parameter
+     * provides `activityName`, `args`, and `options` for the call being
+     * intercepted. The `workflowCtx` map provides workflow metadata
+     * (`workflowId`, `workflowName`, `namespace`, etc.).
+     *
+     * @param interceptor The activity interceptor to register
+     *
+     * @example
+     * ```typescript
+     * Durable.registerActivityInterceptor({
+     *   async execute(activityCtx, workflowCtx, next) {
+     *     const start = Date.now();
+     *     try {
+     *       const result = await next();
+     *       console.log(`${activityCtx.activityName} took ${Date.now() - start}ms`);
+     *       return result;
+     *     } catch (err) {
+     *       if (Durable.didInterrupt(err)) throw err;
+     *       throw err;
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    static registerActivityInterceptor(interceptor) {
+        DurableClass.interceptorService.registerActivity(interceptor);
+    }
+    /**
+     * Clear all registered activity interceptors
+     */
+    static clearActivityInterceptors() {
+        DurableClass.interceptorService.clearActivity();
     }
     /**
      * Get the interceptor service instance
      * @internal
      */
     static getInterceptorService() {
-        return MemFlowClass.interceptorService;
+        return DurableClass.interceptorService;
     }
     /**
      * Shutdown everything. All connections, workers, and clients will be closed.
      * Include in your signal handlers to ensure a clean shutdown.
      */
     static async shutdown() {
-        await MemFlowClass.Client.shutdown();
-        await MemFlowClass.Worker.shutdown();
+        await DurableClass.Client.shutdown();
+        await DurableClass.Worker.shutdown();
         await hotmesh_1.HotMesh.stop();
     }
 }
-exports.MemFlow = MemFlowClass;
+exports.Durable = DurableClass;
 /**
- * The MemFlow `Client` service is functionally
+ * The Durable `Client` service is functionally
  * equivalent to the Temporal `Client` service.
  */
-MemFlowClass.Client = client_1.ClientService;
+DurableClass.Client = client_1.ClientService;
 /**
- * The MemFlow `Connection` service is functionally
+ * The Durable `Connection` service is functionally
  * equivalent to the Temporal `Connection` service.
  */
-MemFlowClass.Connection = connection_1.ConnectionService;
+DurableClass.Connection = connection_1.ConnectionService;
 /**
  * @private
  */
-MemFlowClass.Search = search_1.Search;
+DurableClass.Search = search_1.Search;
 /**
  * @private
  */
-MemFlowClass.Entity = entity_1.Entity;
+DurableClass.Entity = entity_1.Entity;
 /**
  * The Handle provides methods to interact with a running
  * workflow. This includes exporting the workflow, sending signals, and
  * querying the state of the workflow. An instance of the Handle service
- * is typically accessed via the MemFlow.Client class (workflow.getHandle).
+ * is typically accessed via the Durable.Client class (workflow.getHandle).
  */
-MemFlowClass.Handle = handle_1.WorkflowHandleService;
+DurableClass.Handle = handle_1.WorkflowHandleService;
 /**
- * The MemFlow `Worker` service is functionally
+ * The Durable `Worker` service is functionally
  * equivalent to the Temporal `Worker` service.
  */
-MemFlowClass.Worker = worker_1.WorkerService;
+DurableClass.Worker = worker_1.WorkerService;
 /**
  * Register activity workers for a task queue. Activities execute via message queue
  * and can run on different servers from workflows.
@@ -296,7 +392,7 @@ MemFlowClass.Worker = worker_1.WorkerService;
  *   async sendEmail(to: string, msg: string) { /* ... *\/ }
  * };
  *
- * await MemFlow.registerActivityWorker({
+ * await Durable.registerActivityWorker({
  *   connection: {
  *     class: Postgres,
  *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
@@ -306,7 +402,7 @@ MemFlowClass.Worker = worker_1.WorkerService;
  *
  * // Workflow worker (can be on different server)
  * async function orderWorkflow(amount: number) {
- *   const { processPayment, sendEmail } = MemFlow.workflow.proxyActivities<{
+ *   const { processPayment, sendEmail } = Durable.workflow.proxyActivities<{
  *     processPayment: (amount: number) => Promise<string>;
  *     sendEmail: (to: string, msg: string) => Promise<void>;
  *   }>({
@@ -319,30 +415,30 @@ MemFlowClass.Worker = worker_1.WorkerService;
  *   return result;
  * }
  *
- * await MemFlow.Worker.create({
+ * await Durable.Worker.create({
  *   connection: { class: Postgres, options: { connectionString: '...' } },
  *   taskQueue: 'orders',
  *   workflow: orderWorkflow
  * });
  * ```
  */
-MemFlowClass.registerActivityWorker = worker_1.WorkerService.registerActivityWorker;
+DurableClass.registerActivityWorker = worker_1.WorkerService.registerActivityWorker;
 /**
- * The MemFlow `workflow` service is functionally
+ * The Durable `workflow` service is functionally
  * equivalent to the Temporal `Workflow` service
  * with additional methods for managing workflows,
  * including: `execChild`, `waitFor`, `sleep`, etc
  */
-MemFlowClass.workflow = workflow_1.WorkflowService;
+DurableClass.workflow = workflow_1.WorkflowService;
 /**
  * Checks if an error is a HotMesh reserved error type that indicates
  * a workflow interruption rather than a true error condition.
  *
  * @see {@link didInterrupt} for detailed documentation
  */
-MemFlowClass.didInterrupt = interruption_1.didInterrupt;
-MemFlowClass.interceptorService = new interceptor_1.InterceptorService();
+DurableClass.didInterrupt = interruption_1.didInterrupt;
+DurableClass.interceptorService = new interceptor_1.InterceptorService();
 /**
  * Generate a unique identifier for workflow IDs
  */
-MemFlowClass.guid = utils_1.guid;
+DurableClass.guid = utils_1.guid;

package/build/services/{memflow → durable}/interceptor.d.ts

@@ -1,4 +1,4 @@
-import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
+import { WorkflowInterceptor, InterceptorRegistry, ActivityInterceptor, ActivityInterceptorContext } from '../../types/durable';
 /**
  * Service for managing workflow interceptors that wrap workflow execution
  * in an onion-like pattern. Each interceptor can perform actions before
@@ -49,32 +49,32 @@ import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
  * });
  * ```
  *
- * ## Durable Interceptors with MemFlow Functions
+ * ## Durable Interceptors with Durable Functions
  *
  * Interceptors run within the workflow's async local storage context, which means
- * they can use MemFlow functions like `sleepFor`, `entity`, `proxyActivities`, etc.
+ * they can use Durable functions like `sleepFor`, `entity`, `proxyActivities`, etc.
  * These interceptors participate in the HotMesh interruption/replay pattern.
  *
  * @example
  * ```typescript
- * import { MemFlow } from '@hotmeshio/hotmesh';
+ * import { Durable } 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');
+ *       await Durable.workflow.sleepFor('1 second');
  *
  *       const result = await next();
  *
  *       // Another sleep after workflow completes
- *       await MemFlow.workflow.sleepFor('500 milliseconds');
+ *       await Durable.workflow.sleepFor('500 milliseconds');
  *
  *       return result;
  *     } catch (err) {
  *       // CRITICAL: Always check for HotMesh interruptions
- *       if (MemFlow.didInterrupt(err)) {
+ *       if (Durable.didInterrupt(err)) {
  *         throw err; // Rethrow interruptions for replay system
  *       }
  *       // Handle actual errors
@@ -88,7 +88,7 @@ import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
  * const auditInterceptor: WorkflowInterceptor = {
  *   async execute(ctx, next) {
  *     try {
- *       const entity = await MemFlow.workflow.entity();
+ *       const entity = await Durable.workflow.entity();
  *       await entity.append('auditLog', {
  *         action: 'workflow_started',
  *         timestamp: new Date().toISOString(),
@@ -108,12 +108,12 @@ import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
  *
  *       return result;
  *     } catch (err) {
- *       if (MemFlow.didInterrupt(err)) {
+ *       if (Durable.didInterrupt(err)) {
  *         throw err;
  *       }
  *
  *       // Log failure to entity
- *       const entity = await MemFlow.workflow.entity();
+ *       const entity = await Durable.workflow.entity();
  *       await entity.append('auditLog', {
  *         action: 'workflow_failed',
  *         timestamp: new Date().toISOString(),
@@ -126,35 +126,35 @@ import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
  * };
  *
  * // Register interceptors
- * MemFlow.registerInterceptor(rateLimitInterceptor);
- * MemFlow.registerInterceptor(auditInterceptor);
+ * Durable.registerInterceptor(rateLimitInterceptor);
+ * Durable.registerInterceptor(auditInterceptor);
  * ```
  *
  * ## Execution Pattern with Interruptions
  *
- * When interceptors use MemFlow functions, the workflow will execute multiple times
+ * When interceptors use Durable 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
+ * 1. **First execution**: Interceptor calls `sleepFor` → throws `DurableSleepError` → workflow pauses
+ * 2. **Second execution**: Interceptor sleep replays (skipped), workflow runs → proxy activity throws `DurableProxyError` → workflow pauses
+ * 3. **Third execution**: All previous operations replay, interceptor sleep after workflow → throws `DurableSleepError` → 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
+ * // Interceptor with complex Durable operations
  * const complexInterceptor: WorkflowInterceptor = {
  *   async execute(ctx, next) {
  *     try {
  *       // Get persistent state
- *       const entity = await MemFlow.workflow.entity();
+ *       const entity = await Durable.workflow.entity();
  *       const state = await entity.get() as any;
  *
  *       // Conditional durable operations
  *       if (!state.preProcessed) {
- *         await MemFlow.workflow.sleepFor('100 milliseconds');
+ *         await Durable.workflow.sleepFor('100 milliseconds');
  *         await entity.merge({ preProcessed: true });
  *       }
  *
@@ -163,7 +163,7 @@ import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
  *
  *       // Post-processing with child workflow
  *       if (!state.postProcessed) {
- *         await MemFlow.workflow.execChild({
+ *         await Durable.workflow.execChild({
  *           taskQueue: 'cleanup',
  *           workflowName: 'cleanupWorkflow',
  *           args: [result]
@@ -173,7 +173,7 @@ import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
  *
  *       return result;
  *     } catch (err) {
- *       if (MemFlow.didInterrupt(err)) {
+ *       if (Durable.didInterrupt(err)) {
  *         throw err;
  *       }
  *       throw err;
@@ -184,6 +184,7 @@ import { WorkflowInterceptor, InterceptorRegistry } from '../../types/memflow';
  */
 export declare class InterceptorService implements InterceptorRegistry {
     interceptors: WorkflowInterceptor[];
+    activityInterceptors: ActivityInterceptor[];
     /**
      * Register a new workflow interceptor that will wrap workflow execution.
      * Interceptors are executed in the order they are registered, with the
@@ -230,7 +231,29 @@ export declare class InterceptorService implements InterceptorRegistry {
      */
     executeChain(ctx: Map<string, any>, fn: () => Promise<any>): Promise<any>;
     /**
-     * Clear all registered interceptors.
+     * Register a new activity interceptor that will wrap individual
+     * proxied activity calls. Interceptors are executed in the order
+     * they are registered, with the first registered being the outermost wrapper.
+     *
+     * @param interceptor The activity interceptor to register
+     */
+    registerActivity(interceptor: ActivityInterceptor): void;
+    /**
+     * Execute the activity interceptor chain around an activity invocation.
+     * Uses the same onion/reduceRight pattern as executeChain.
+     *
+     * @param activityCtx - Metadata about the activity (name, args, options)
+     * @param workflowCtx - The workflow context Map
+     * @param fn - The core activity function (registers with interruptionRegistry, sleeps, throws)
+     * @returns The result of the activity (from replay or after future execution)
+     */
+    executeActivityChain(activityCtx: ActivityInterceptorContext, workflowCtx: Map<string, any>, fn: () => Promise<any>): Promise<any>;
+    /**
+     * Clear all registered activity interceptors.
+     */
+    clearActivity(): void;
+    /**
+     * Clear all registered interceptors (both workflow and activity).
      *
      * @example
      * ```typescript