@hotmeshio/hotmesh 0.10.0 → 0.10.1

package/README.md

@@ -11,7 +11,7 @@ npm install @hotmeshio/hotmesh
 ## Use HotMesh for
 
 - **Durable pipelines** — Orchestrate long-running, multi-step pipelines transactionally.
-- **Temporal replacement** — The `Durable` module provides a Temporal-compatible API (`Client`, `Worker`, `proxyActivities`, `sleepFor`, `startChild`, signals) that runs directly on Postgres. No app server required.
+- **Temporal alternative** — The `Durable` module provides a Temporal-compatible API (`Client`, `Worker`, `proxyActivities`, `sleepFor`, `startChild`, signals) that runs directly on Postgres. No app server required.
 - **Distributed state machines** — Build stateful applications where every component can [fail and recover](https://github.com/hotmeshio/sdk-typescript/blob/main/services/collator/README.md).
 - **AI and training pipelines** — Multi-step AI workloads where each stage is expensive and must not be repeated on failure. A crashed pipeline resumes from the last committed step, not from the beginning.
 
@@ -337,7 +337,7 @@ Durable is designed as a drop-in-compatible alternative for common Temporal patt
 
 **What's the same:** `Client`, `Worker`, `proxyActivities`, `sleepFor`, `startChild`/`execChild`, signals (`waitFor`/`signal`), retry policies, and the overall workflow-as-code programming model.
 
-**What's different:** No Temporal server or cluster to operate. Postgres is the only infrastructure dependency — it stores state, coordinates workers, and delivers messages. HotMesh also offers a YAML-based approach for declarative workflows that compile to the same execution model.
+**What's different:** Postgres is the only infrastructure dependency — it stores state and coordinates workers.
 
 ## Running tests
 

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.10.0",
+    "version": "0.10.1",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -110,13 +110,12 @@
         "nats": "^2.28.0",
         "openai": "^5.9.0",
         "pg": "^8.10.0",
-        "rimraf": "^4.4.1",
+        "rimraf": "^6.1.3",
         "terser": "^5.37.0",
         "ts-node": "^10.9.1",
-        "ts-node-dev": "^2.0.0",
         "typedoc": "^0.26.4",
         "typescript": "^5.0.4",
-        "vitest": "^2.1.9"
+        "vitest": "^4.0.18"
     },
     "peerDependencies": {
         "nats": "^2.0.0",

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

@@ -364,12 +364,41 @@ declare class DurableClass {
     static didInterrupt: typeof didInterrupt;
     private static interceptorService;
     /**
-     * Register a workflow interceptor
+     * Register a workflow interceptor that wraps the entire workflow execution
+     * in an onion-like pattern. Interceptors execute in registration order
+     * (first registered is outermost) and can perform actions before and after
+     * workflow execution, handle errors, and add cross-cutting concerns like
+     * logging, metrics, or tracing.
+     *
+     * Workflow interceptors run inside the workflow's async local storage context,
+     * so all Durable workflow methods (`proxyActivities`, `sleepFor`, `waitFor`,
+     * `execChild`, etc.) are available. When using Durable functions, always check
+     * for interruptions with `Durable.didInterrupt(err)` and rethrow them.
+     *
      * @param interceptor The interceptor to register
+     *
+     * @example
+     * ```typescript
+     * // Logging interceptor
+     * Durable.registerInterceptor({
+     *   async execute(ctx, next) {
+     *     console.log(`Workflow ${ctx.get('workflowName')} starting`);
+     *     try {
+     *       const result = await next();
+     *       console.log(`Workflow ${ctx.get('workflowName')} completed`);
+     *       return result;
+     *     } catch (err) {
+     *       if (Durable.didInterrupt(err)) throw err;
+     *       console.error(`Workflow ${ctx.get('workflowName')} failed`);
+     *       throw err;
+     *     }
+     *   }
+     * });
+     * ```
      */
     static registerInterceptor(interceptor: WorkflowInterceptor): void;
     /**
-     * Clear all registered interceptors (both workflow and activity)
+     * Clear all registered interceptors (both workflow and activity).
      */
     static clearInterceptors(): void;
     /**

package/build/services/durable/index.js

@@ -280,14 +280,43 @@ class DurableClass {
      */
     constructor() { }
     /**
-     * Register a workflow interceptor
+     * Register a workflow interceptor that wraps the entire workflow execution
+     * in an onion-like pattern. Interceptors execute in registration order
+     * (first registered is outermost) and can perform actions before and after
+     * workflow execution, handle errors, and add cross-cutting concerns like
+     * logging, metrics, or tracing.
+     *
+     * Workflow interceptors run inside the workflow's async local storage context,
+     * so all Durable workflow methods (`proxyActivities`, `sleepFor`, `waitFor`,
+     * `execChild`, etc.) are available. When using Durable functions, always check
+     * for interruptions with `Durable.didInterrupt(err)` and rethrow them.
+     *
      * @param interceptor The interceptor to register
+     *
+     * @example
+     * ```typescript
+     * // Logging interceptor
+     * Durable.registerInterceptor({
+     *   async execute(ctx, next) {
+     *     console.log(`Workflow ${ctx.get('workflowName')} starting`);
+     *     try {
+     *       const result = await next();
+     *       console.log(`Workflow ${ctx.get('workflowName')} completed`);
+     *       return result;
+     *     } catch (err) {
+     *       if (Durable.didInterrupt(err)) throw err;
+     *       console.error(`Workflow ${ctx.get('workflowName')} failed`);
+     *       throw err;
+     *     }
+     *   }
+     * });
+     * ```
      */
     static registerInterceptor(interceptor) {
         DurableClass.interceptorService.register(interceptor);
     }
     /**
-     * Clear all registered interceptors (both workflow and activity)
+     * Clear all registered interceptors (both workflow and activity).
      */
     static clearInterceptors() {
         DurableClass.interceptorService.clear();

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

@@ -181,6 +181,79 @@ import { WorkflowInterceptor, InterceptorRegistry, ActivityInterceptor, Activity
  *   }
  * };
  * ```
+ *
+ * ## Activity Interceptors
+ *
+ * Activity interceptors wrap individual proxied activity calls, supporting
+ * both **before** and **after** phases. The before phase receives the activity
+ * input (and can modify `activityCtx.args`). The after phase receives the
+ * activity output as the return value of `next()`.
+ *
+ * This enables patterns like publishing activity results to an external
+ * system (e.g., SNS, audit log) without modifying the workflow itself.
+ *
+ * **Important:** The after-phase proxy activity calls go through the same
+ * interceptor chain. Guard against recursion by checking `activityCtx.activityName`
+ * to skip the interceptor's own calls.
+ *
+ * @example
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * import type { ActivityInterceptor } from '@hotmeshio/hotmesh/types/durable';
+ * import * as activities from './activities';
+ *
+ * // Activity interceptor that publishes results via a proxy activity
+ * const publishResultInterceptor: ActivityInterceptor = {
+ *   async execute(activityCtx, workflowCtx, next) {
+ *     try {
+ *       // BEFORE: inspect or modify the activity input
+ *       console.log(`Calling ${activityCtx.activityName}`, activityCtx.args);
+ *
+ *       // Execute the activity (returns stored result on replay)
+ *       const result = await next();
+ *
+ *       // AFTER: use the activity output (only runs on replay,
+ *       // once the result is available)
+ *
+ *       // Guard: skip for the interceptor's own proxy calls
+ *       if (activityCtx.activityName !== 'publishToSNS') {
+ *         const { publishToSNS } = Durable.workflow.proxyActivities<{
+ *           publishToSNS: (topic: string, payload: any) => Promise<void>;
+ *         }>({
+ *           taskQueue: 'shared-notifications',
+ *           retryPolicy: { maximumAttempts: 3, throwOnError: true },
+ *         });
+ *
+ *         await publishToSNS('activity-results', {
+ *           workflowId: workflowCtx.get('workflowId'),
+ *           activityName: activityCtx.activityName,
+ *           input: activityCtx.args,
+ *           output: result,
+ *         });
+ *       }
+ *
+ *       return result;
+ *     } catch (err) {
+ *       if (Durable.didInterrupt(err)) throw err;
+ *       throw err;
+ *     }
+ *   },
+ * };
+ *
+ * Durable.registerActivityInterceptor(publishResultInterceptor);
+ * ```
+ *
+ * ## Activity Interceptor Replay Pattern
+ *
+ * Activity interceptors participate in the interruption/replay cycle:
+ *
+ * 1. **First execution**: Before-phase runs → `next()` registers the activity
+ *    interruption and throws `DurableProxyError` → workflow pauses
+ * 2. **Second execution**: Before-phase replays → `next()` returns the stored
+ *    activity result → after-phase runs → after-phase proxy call (e.g.,
+ *    `publishToSNS`) registers its own interruption → workflow pauses
+ * 3. **Third execution**: Everything replays → after-phase proxy call returns
+ *    its stored result → interceptor returns → workflow continues
  */
 export declare class InterceptorService implements InterceptorRegistry {
     interceptors: WorkflowInterceptor[];

package/build/services/durable/interceptor.js

@@ -183,6 +183,79 @@ exports.InterceptorService = void 0;
  *   }
  * };
  * ```
+ *
+ * ## Activity Interceptors
+ *
+ * Activity interceptors wrap individual proxied activity calls, supporting
+ * both **before** and **after** phases. The before phase receives the activity
+ * input (and can modify `activityCtx.args`). The after phase receives the
+ * activity output as the return value of `next()`.
+ *
+ * This enables patterns like publishing activity results to an external
+ * system (e.g., SNS, audit log) without modifying the workflow itself.
+ *
+ * **Important:** The after-phase proxy activity calls go through the same
+ * interceptor chain. Guard against recursion by checking `activityCtx.activityName`
+ * to skip the interceptor's own calls.
+ *
+ * @example
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * import type { ActivityInterceptor } from '@hotmeshio/hotmesh/types/durable';
+ * import * as activities from './activities';
+ *
+ * // Activity interceptor that publishes results via a proxy activity
+ * const publishResultInterceptor: ActivityInterceptor = {
+ *   async execute(activityCtx, workflowCtx, next) {
+ *     try {
+ *       // BEFORE: inspect or modify the activity input
+ *       console.log(`Calling ${activityCtx.activityName}`, activityCtx.args);
+ *
+ *       // Execute the activity (returns stored result on replay)
+ *       const result = await next();
+ *
+ *       // AFTER: use the activity output (only runs on replay,
+ *       // once the result is available)
+ *
+ *       // Guard: skip for the interceptor's own proxy calls
+ *       if (activityCtx.activityName !== 'publishToSNS') {
+ *         const { publishToSNS } = Durable.workflow.proxyActivities<{
+ *           publishToSNS: (topic: string, payload: any) => Promise<void>;
+ *         }>({
+ *           taskQueue: 'shared-notifications',
+ *           retryPolicy: { maximumAttempts: 3, throwOnError: true },
+ *         });
+ *
+ *         await publishToSNS('activity-results', {
+ *           workflowId: workflowCtx.get('workflowId'),
+ *           activityName: activityCtx.activityName,
+ *           input: activityCtx.args,
+ *           output: result,
+ *         });
+ *       }
+ *
+ *       return result;
+ *     } catch (err) {
+ *       if (Durable.didInterrupt(err)) throw err;
+ *       throw err;
+ *     }
+ *   },
+ * };
+ *
+ * Durable.registerActivityInterceptor(publishResultInterceptor);
+ * ```
+ *
+ * ## Activity Interceptor Replay Pattern
+ *
+ * Activity interceptors participate in the interruption/replay cycle:
+ *
+ * 1. **First execution**: Before-phase runs → `next()` registers the activity
+ *    interruption and throws `DurableProxyError` → workflow pauses
+ * 2. **Second execution**: Before-phase replays → `next()` returns the stored
+ *    activity result → after-phase runs → after-phase proxy call (e.g.,
+ *    `publishToSNS`) registers its own interruption → workflow pauses
+ * 3. **Third execution**: Everything replays → after-phase proxy call returns
+ *    its stored result → interceptor returns → workflow continues
  */
 class InterceptorService {
     constructor() {

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

@@ -42,36 +42,40 @@ exports.getProxyInterruptPayload = getProxyInterruptPayload;
  */
 function wrapActivity(activityName, options) {
     return async function (...args) {
+        // Increment counter first for deterministic replay ordering
         const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('proxy');
-        if (didRunAlready) {
-            if (result?.$error) {
-                if (options?.retryPolicy?.throwOnError !== false) {
-                    const code = result.$error.code;
-                    const message = result.$error.message;
-                    const stack = result.$error.stack;
-                    if (code === common_1.HMSH_CODE_DURABLE_FATAL) {
-                        throw new common_1.DurableFatalError(message, stack);
-                    }
-                    else if (code === common_1.HMSH_CODE_DURABLE_MAXED) {
-                        throw new common_1.DurableMaxedError(message, stack);
-                    }
-                    else if (code === common_1.HMSH_CODE_DURABLE_TIMEOUT) {
-                        throw new common_1.DurableTimeoutError(message, stack);
-                    }
-                    else {
-                        // For any other error code, throw a DurableFatalError to stop the workflow
-                        throw new common_1.DurableFatalError(message, stack);
+        const context = (0, context_1.getContext)();
+        const { interruptionRegistry } = context;
+        // Build activityCtx so interceptors can inspect/modify args
+        const activityCtx = { activityName, args, options };
+        // Core function: returns stored result on replay, or registers
+        // the interruption and throws on first execution. Reads args
+        // from activityCtx so "before" interceptors can modify them.
+        const coreFunction = async () => {
+            if (didRunAlready) {
+                if (result?.$error) {
+                    if (options?.retryPolicy?.throwOnError !== false) {
+                        const code = result.$error.code;
+                        const message = result.$error.message;
+                        const stack = result.$error.stack;
+                        if (code === common_1.HMSH_CODE_DURABLE_FATAL) {
+                            throw new common_1.DurableFatalError(message, stack);
+                        }
+                        else if (code === common_1.HMSH_CODE_DURABLE_MAXED) {
+                            throw new common_1.DurableMaxedError(message, stack);
+                        }
+                        else if (code === common_1.HMSH_CODE_DURABLE_TIMEOUT) {
+                            throw new common_1.DurableTimeoutError(message, stack);
+                        }
+                        else {
+                            throw new common_1.DurableFatalError(message, stack);
+                        }
                     }
+                    return result.$error;
                 }
-                return result.$error;
+                return result.data;
             }
-            return result.data;
-        }
-        const context = (0, context_1.getContext)();
-        const { interruptionRegistry } = context;
-        // Core activity registration logic
-        const executeActivity = async () => {
-            const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, args, options);
+            const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, activityCtx.args, options);
             interruptionRegistry.push({
                 code: common_1.HMSH_CODE_DURABLE_PROXY,
                 type: 'DurableProxyError',
@@ -80,13 +84,13 @@ function wrapActivity(activityName, options) {
             await (0, common_1.sleepImmediate)();
             throw new common_1.DurableProxyError(interruptionMessage);
         };
-        // Check for activity interceptors
+        // Run through interceptor chain if interceptors exist
         const store = common_1.asyncLocalStorage.getStore();
         const interceptorService = store?.get('activityInterceptorService');
         if (interceptorService?.activityInterceptors?.length > 0) {
-            return await interceptorService.executeActivityChain({ activityName, args, options }, store, executeActivity);
+            return await interceptorService.executeActivityChain(activityCtx, store, coreFunction);
         }
-        return await executeActivity();
+        return await coreFunction();
     };
 }
 exports.wrapActivity = wrapActivity;

package/build/types/durable.d.ts

@@ -596,15 +596,21 @@ export interface WorkflowInterceptor {
     execute(ctx: Map<string, any>, next: () => Promise<any>): Promise<any>;
 }
 /**
- * Registry for workflow interceptors that are executed in order
- * for each workflow execution
+ * Registry for workflow and activity interceptors that are executed in order
+ * for each workflow or activity execution.
  */
 export interface InterceptorRegistry {
     /**
-     * Array of registered interceptors that will wrap workflow execution
-     * in the order they were registered (first registered = outermost wrapper)
+     * Array of registered workflow interceptors that will wrap workflow execution
+     * in the order they were registered (first registered = outermost wrapper).
      */
     interceptors: WorkflowInterceptor[];
+    /**
+     * Array of registered activity interceptors that will wrap individual
+     * proxied activity calls in the order they were registered
+     * (first registered = outermost wrapper).
+     */
+    activityInterceptors: ActivityInterceptor[];
 }
 /**
  * Context provided to an activity interceptor, containing metadata
@@ -624,11 +630,21 @@ export interface ActivityInterceptorContext {
  * workflow methods (proxyActivities, sleepFor, waitFor, execChild, etc.)
  * are available.
  *
- * Activity interceptors execute BEFORE the activity registers with the
- * interruptionRegistry and throws. Any Durable operations called within
- * the interceptor will register their own interruptions first, and those
- * will be processed before the wrapped activity's interruption during
- * the replay cycle.
+ * Activity interceptors wrap proxied activity calls in an onion pattern,
+ * supporting both **before** and **after** phases:
+ *
+ * - **Before phase** (code before `await next()`): Runs before the activity
+ *   executes. The interceptor can inspect or modify `activityCtx.args` to
+ *   transform the activity input before it is sent.
+ *
+ * - **After phase** (code after `await next()`): Runs on replay once the
+ *   activity result is available. The interceptor receives the activity
+ *   output as the return value of `next()` and can inspect or transform it.
+ *
+ * On first execution, `next()` registers the activity with the interruption
+ * system and throws (the activity has not completed yet). On replay, `next()`
+ * returns the stored result and the after-phase code executes. This follows
+ * the same deterministic replay pattern as workflow interceptors.
  *
  * @example
  * ```typescript
@@ -653,11 +669,13 @@ export interface ActivityInterceptorContext {
  */
 export interface ActivityInterceptor {
     /**
-     * Called before each proxied activity invocation.
+     * Called around each proxied activity invocation. Code before `next()`
+     * runs in the before phase; code after `next()` runs in the after phase
+     * once the activity result is available on replay.
      *
-     * @param activityCtx - Metadata about the activity being called
+     * @param activityCtx - Metadata about the activity being called (args may be modified)
      * @param workflowCtx - The workflow context map (same as WorkflowInterceptor receives)
-     * @param next - Call to proceed to the next interceptor or the actual activity registration
+     * @param next - Call to proceed to the next interceptor or the core activity function
      * @returns The activity result (from replay or after interruption/re-execution)
      */
     execute(activityCtx: ActivityInterceptorContext, workflowCtx: Map<string, any>, next: () => Promise<any>): Promise<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -110,13 +110,12 @@
     "nats": "^2.28.0",
     "openai": "^5.9.0",
     "pg": "^8.10.0",
-    "rimraf": "^4.4.1",
+    "rimraf": "^6.1.3",
     "terser": "^5.37.0",
     "ts-node": "^10.9.1",
-    "ts-node-dev": "^2.0.0",
     "typedoc": "^0.26.4",
     "typescript": "^5.0.4",
-    "vitest": "^2.1.9"
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "nats": "^2.0.0",