@hotmeshio/hotmesh 0.9.0 → 0.10.0

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

@@ -1,4 +1,4 @@
-import { ContextType, WorkflowInterceptor } from '../../types/memflow';
+import { ContextType, WorkflowInterceptor, ActivityInterceptor } from '../../types/durable';
 import { guid } from '../../modules/utils';
 import { ClientService } from './client';
 import { ConnectionService } from './connection';
@@ -9,9 +9,9 @@ import { WorkflowService } from './workflow';
 import { WorkflowHandleService } from './handle';
 import { didInterrupt } from './workflow/interruption';
 /**
- * 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
  *
@@ -19,7 +19,7 @@ import { didInterrupt } from './workflow/interruption';
  * 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({
@@ -38,14 +38,14 @@ import { didInterrupt } from './workflow/interruption';
  * 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],
@@ -54,8 +54,8 @@ import { didInterrupt } from './workflow/interruption';
  *
  * // 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')
  * ]);
  * ```
  *
@@ -63,7 +63,7 @@ import { didInterrupt } from './workflow/interruption';
  * 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;
  * }>({
@@ -83,7 +83,7 @@ import { didInterrupt } from './workflow/interruption';
  * 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' }
@@ -92,7 +92,7 @@ import { didInterrupt } from './workflow/interruption';
  * }, 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' }
@@ -105,7 +105,7 @@ import { didInterrupt } from './workflow/interruption';
  * 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],
@@ -117,7 +117,7 @@ import { didInterrupt } from './workflow/interruption';
  * });
  *
  * // Fire-and-forget child workflow
- * await MemFlow.workflow.startChild({
+ * await Durable.workflow.startChild({
  *   taskQueue: 'notifications',
  *   workflowName: 'sendUpdates',
  *   args: [updates]
@@ -128,7 +128,7 @@ import { didInterrupt } from './workflow/interruption';
  * 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' }
@@ -137,11 +137,11 @@ import { didInterrupt } from './workflow/interruption';
  * }, { 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 }
@@ -156,7 +156,7 @@ import { didInterrupt } from './workflow/interruption';
  *       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;
@@ -165,15 +165,71 @@ import { didInterrupt } from './workflow/interruption';
  * });
  * ```
  *
+ * ### 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' }
@@ -204,28 +260,28 @@ import { didInterrupt } from './workflow/interruption';
  *   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();
  * ```
  */
-declare class MemFlowClass {
+declare class DurableClass {
     /**
      * @private
      */
     constructor();
     /**
-     * The MemFlow `Client` service is functionally
+     * The Durable `Client` service is functionally
      * equivalent to the Temporal `Client` service.
      */
     static Client: typeof ClientService;
     /**
-     * The MemFlow `Connection` service is functionally
+     * The Durable `Connection` service is functionally
      * equivalent to the Temporal `Connection` service.
      */
     static Connection: typeof ConnectionService;
@@ -241,11 +297,11 @@ declare class MemFlowClass {
      * 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).
      */
     static Handle: typeof WorkflowHandleService;
     /**
-     * The MemFlow `Worker` service is functionally
+     * The Durable `Worker` service is functionally
      * equivalent to the Temporal `Worker` service.
      */
     static Worker: typeof WorkerService;
@@ -261,7 +317,7 @@ declare class MemFlowClass {
      *   async sendEmail(to: string, msg: string) { /* ... *\/ }
      * };
      *
-     * await MemFlow.registerActivityWorker({
+     * await Durable.registerActivityWorker({
      *   connection: {
      *     class: Postgres,
      *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
@@ -271,7 +327,7 @@ declare class MemFlowClass {
      *
      * // 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>;
      *   }>({
@@ -284,7 +340,7 @@ declare class MemFlowClass {
      *   return result;
      * }
      *
-     * await MemFlow.Worker.create({
+     * await Durable.Worker.create({
      *   connection: { class: Postgres, options: { connectionString: '...' } },
      *   taskQueue: 'orders',
      *   workflow: orderWorkflow
@@ -293,7 +349,7 @@ declare class MemFlowClass {
      */
     static registerActivityWorker: typeof 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
@@ -313,9 +369,45 @@ declare class MemFlowClass {
      */
     static registerInterceptor(interceptor: WorkflowInterceptor): void;
     /**
-     * Clear all registered workflow interceptors
+     * Clear all registered interceptors (both workflow and activity)
      */
     static clearInterceptors(): void;
+    /**
+     * 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: ActivityInterceptor): void;
+    /**
+     * Clear all registered activity interceptors
+     */
+    static clearActivityInterceptors(): void;
     /**
      * Generate a unique identifier for workflow IDs
      */
@@ -326,5 +418,5 @@ declare class MemFlowClass {
      */
     static shutdown(): Promise<void>;
 }
-export { MemFlowClass as MemFlow };
+export { DurableClass as Durable };
 export type { ContextType };