@hotmeshio/hotmesh 0.8.0 → 0.9.0

package/build/services/memflow/workflow/execChild.d.ts

@@ -1,18 +1,106 @@
 import { WorkflowOptions } from './common';
 /**
- * Spawns a child workflow and awaits the result, or if `await` is false, returns immediately.
- * @template T
- * @param {WorkflowOptions} options - Workflow options.
- * @returns {Promise<T>} Result of the child workflow.
+ * Spawns a child workflow and awaits its result. The child runs as an
+ * independent job with its own lifecycle, retry policy, and dimensional
+ * isolation. If the child fails, the error is propagated to the parent
+ * as a typed error (`MemFlowFatalError`, `MemFlowMaxedError`,
+ * `MemFlowTimeoutError`, or `MemFlowRetryError`).
+ *
+ * On replay, the stored child result is returned immediately without
+ * re-spawning the child workflow.
+ *
+ * ## Child Job ID
+ *
+ * If `options.workflowId` is provided, it is used directly. Otherwise,
+ * the child ID is generated from the entity/workflow name, a GUID, the
+ * parent's dimensional coordinates, and the execution index — ensuring
+ * uniqueness across parallel and re-entrant executions.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Spawn a child workflow and await its result
+ * export async function parentWorkflow(orderId: string): Promise<string> {
+ *   const result = await MemFlow.workflow.execChild<{ status: string }>({
+ *     taskQueue: 'payments',
+ *     workflowName: 'processPayment',
+ *     args: [orderId, 99.99],
+ *     config: {
+ *       maximumAttempts: 3,
+ *       backoffCoefficient: 2,
+ *     },
+ *   });
+ *   return result.status;
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Fan-out: spawn multiple children in parallel
+ * export async function batchWorkflow(items: string[]): Promise<string[]> {
+ *   const results = await Promise.all(
+ *     items.map((item) =>
+ *       MemFlow.workflow.execChild<string>({
+ *         taskQueue: 'processors',
+ *         workflowName: 'processItem',
+ *         args: [item],
+ *       }),
+ *     ),
+ *   );
+ *   return results;
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Entity-based child (uses entity name as task queue)
+ * const user = await MemFlow.workflow.execChild<UserRecord>({
+ *   entity: 'user',
+ *   args: [{ name: 'Alice', email: 'alice@example.com' }],
+ *   workflowId: 'user-alice',          // deterministic ID
+ *   expire: 3600,                       // 1 hour TTL
+ * });
+ * ```
+ *
+ * @template T - The return type of the child workflow.
+ * @param {WorkflowOptions} options - Child workflow configuration.
+ * @returns {Promise<T>} The child workflow's return value.
  */
 export declare function execChild<T>(options: WorkflowOptions): Promise<T>;
 /**
- * Alias for execChild.
+ * Alias for {@link execChild}.
  */
 export declare const executeChild: typeof execChild;
 /**
- * Spawns a child workflow and returns the child Job ID without awaiting its completion.
- * @param {WorkflowOptions} options - Workflow options.
- * @returns {Promise<string>} The child job ID.
+ * Spawns a child workflow in fire-and-forget mode. The parent workflow
+ * continues immediately without waiting for the child to complete.
+ * Returns the child's job ID for later reference (e.g., to interrupt
+ * or query the child).
+ *
+ * This is a convenience wrapper around `execChild` with `await: false`.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * export async function dispatchWorkflow(taskId: string): Promise<string> {
+ *   // Fire-and-forget: start the child and continue immediately
+ *   const childJobId = await MemFlow.workflow.startChild({
+ *     taskQueue: 'background',
+ *     workflowName: 'longRunningTask',
+ *     args: [taskId],
+ *   });
+ *
+ *   // Optionally store the child ID for monitoring
+ *   const search = await MemFlow.workflow.search();
+ *   await search.set({ childJobId });
+ *
+ *   return childJobId;
+ * }
+ * ```
+ *
+ * @param {WorkflowOptions} options - Child workflow configuration.
+ * @returns {Promise<string>} The child workflow's job ID.
  */
 export declare function startChild(options: WorkflowOptions): Promise<string>;

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

@@ -45,10 +45,71 @@ function getChildInterruptPayload(context, options, execIndex) {
     };
 }
 /**
- * Spawns a child workflow and awaits the result, or if `await` is false, returns immediately.
- * @template T
- * @param {WorkflowOptions} options - Workflow options.
- * @returns {Promise<T>} Result of the child workflow.
+ * Spawns a child workflow and awaits its result. The child runs as an
+ * independent job with its own lifecycle, retry policy, and dimensional
+ * isolation. If the child fails, the error is propagated to the parent
+ * as a typed error (`MemFlowFatalError`, `MemFlowMaxedError`,
+ * `MemFlowTimeoutError`, or `MemFlowRetryError`).
+ *
+ * On replay, the stored child result is returned immediately without
+ * re-spawning the child workflow.
+ *
+ * ## Child Job ID
+ *
+ * If `options.workflowId` is provided, it is used directly. Otherwise,
+ * the child ID is generated from the entity/workflow name, a GUID, the
+ * parent's dimensional coordinates, and the execution index — ensuring
+ * uniqueness across parallel and re-entrant executions.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Spawn a child workflow and await its result
+ * export async function parentWorkflow(orderId: string): Promise<string> {
+ *   const result = await MemFlow.workflow.execChild<{ status: string }>({
+ *     taskQueue: 'payments',
+ *     workflowName: 'processPayment',
+ *     args: [orderId, 99.99],
+ *     config: {
+ *       maximumAttempts: 3,
+ *       backoffCoefficient: 2,
+ *     },
+ *   });
+ *   return result.status;
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Fan-out: spawn multiple children in parallel
+ * export async function batchWorkflow(items: string[]): Promise<string[]> {
+ *   const results = await Promise.all(
+ *     items.map((item) =>
+ *       MemFlow.workflow.execChild<string>({
+ *         taskQueue: 'processors',
+ *         workflowName: 'processItem',
+ *         args: [item],
+ *       }),
+ *     ),
+ *   );
+ *   return results;
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Entity-based child (uses entity name as task queue)
+ * const user = await MemFlow.workflow.execChild<UserRecord>({
+ *   entity: 'user',
+ *   args: [{ name: 'Alice', email: 'alice@example.com' }],
+ *   workflowId: 'user-alice',          // deterministic ID
+ *   expire: 3600,                       // 1 hour TTL
+ * });
+ * ```
+ *
+ * @template T - The return type of the child workflow.
+ * @param {WorkflowOptions} options - Child workflow configuration.
+ * @returns {Promise<T>} The child workflow's return value.
  */
 async function execChild(options) {
     const isStartChild = options.await === false;
@@ -92,13 +153,40 @@ async function execChild(options) {
 }
 exports.execChild = execChild;
 /**
- * Alias for execChild.
+ * Alias for {@link execChild}.
  */
 exports.executeChild = execChild;
 /**
- * Spawns a child workflow and returns the child Job ID without awaiting its completion.
- * @param {WorkflowOptions} options - Workflow options.
- * @returns {Promise<string>} The child job ID.
+ * Spawns a child workflow in fire-and-forget mode. The parent workflow
+ * continues immediately without waiting for the child to complete.
+ * Returns the child's job ID for later reference (e.g., to interrupt
+ * or query the child).
+ *
+ * This is a convenience wrapper around `execChild` with `await: false`.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * export async function dispatchWorkflow(taskId: string): Promise<string> {
+ *   // Fire-and-forget: start the child and continue immediately
+ *   const childJobId = await MemFlow.workflow.startChild({
+ *     taskQueue: 'background',
+ *     workflowName: 'longRunningTask',
+ *     args: [taskId],
+ *   });
+ *
+ *   // Optionally store the child ID for monitoring
+ *   const search = await MemFlow.workflow.search();
+ *   await search.set({ childJobId });
+ *
+ *   return childJobId;
+ * }
+ * ```
+ *
+ * @param {WorkflowOptions} options - Child workflow configuration.
+ * @returns {Promise<string>} The child workflow's job ID.
  */
 async function startChild(options) {
     return execChild({ ...options, await: false });

package/build/services/memflow/workflow/execHook.d.ts

@@ -1,65 +1,80 @@
 import { HookOptions } from './common';
 /**
- * Extended hook options that include signal configuration
+ * Extended hook options that include signal configuration.
+ * Used by `execHook()` and `execHookBatch()`.
  */
 export interface ExecHookOptions extends HookOptions {
     /** Signal ID to send after hook execution; if not provided, a random one will be generated */
     signalId?: string;
 }
 /**
- * Executes a hook function and awaits the signal response.
- * This is a convenience method that combines `hook()` and `waitFor()` operations.
+ * Combines `hook()` + `waitFor()` into a single call: spawns a hook
+ * function on a target workflow and suspends the current workflow until
+ * the hook signals completion. This is the recommended pattern for
+ * request/response communication between workflow threads.
  *
- * **Signal Injection**: The `signalId` is automatically injected as the LAST argument
- * to the hooked function. The hooked function should check for this signal parameter
- * and emit the signal when processing is complete.
+ * ## Signal Injection
  *
- * This behaves like `execChild` but targets the existing workflow instead of
- * spawning a new workflow.
+ * A `signalId` is automatically generated (or use the one you provide)
+ * and injected as the **last argument** to the hooked function as
+ * `{ signal: string, $memflow: true }`. The hook function must call
+ * `MemFlow.workflow.signal(signalInfo.signal, result)` to deliver
+ * its response back to the waiting workflow.
  *
- * @template T
- * @param {ExecHookOptions} options - Hook configuration with signal ID.
- * @returns {Promise<T>} The signal result from the hooked function.
+ * ## Difference from `execChild`
  *
- * @example
- * ```typescript
- * // Execute a hook and await its signal response
- * const result = await MemFlow.workflow.execHook({
- *   taskQueue: 'processing',
- *   workflowName: 'processData',
- *   args: ['user123', 'batch-process'],
- *   signalId: 'processing-complete'
- * });
+ * - `execChild` spawns a **new** workflow job with its own lifecycle.
+ * - `execHook` runs within an **existing** workflow's job, in an
+ *   isolated dimensional thread. This is lighter-weight and shares
+ *   the parent job's data namespace.
  *
- * // The hooked function receives the signal as the last argument:
- * export async function processData(userId: string, processType: string, signalInfo?: { signal: string }) {
- *   // ... do processing work ...
- *   const result = { userId, processType, status: 'completed' };
+ * ## Examples
  *
- *   // Check if called via execHook (signalInfo will be present)
- *   if (signalInfo?.signal) {
- *     await MemFlow.workflow.signal(signalInfo.signal, result);
- *   }
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
  *
- *   return result;
+ * // Orchestrator: spawn a hook and await its result
+ * export async function reviewWorkflow(docId: string): Promise<string> {
+ *   const verdict = await MemFlow.workflow.execHook<{ approved: boolean }>({
+ *     taskQueue: 'reviewers',
+ *     workflowName: 'reviewDocument',
+ *     args: [docId],
+ *   });
+ *
+ *   return verdict.approved ? 'accepted' : 'rejected';
  * }
  * ```
  *
- * @example
  * ```typescript
- * // Alternative pattern - check if last arg is signal object
- * export async function myHookFunction(arg1: string, arg2: number, ...rest: any[]) {
- *   // ... process arg1 and arg2 ...
- *   const result = { processed: true, data: [arg1, arg2] };
+ * // The hooked function (runs on the 'reviewers' worker)
+ * export async function reviewDocument(
+ *   docId: string,
+ *   signalInfo?: { signal: string; $memflow: boolean },
+ * ): Promise<{ approved: boolean }> {
+ *   const { analyzeDocument } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   const score = await analyzeDocument(docId);
+ *   const result = { approved: score > 0.8 };
  *
- *   // Check if last argument is a signal object
- *   const lastArg = rest[rest.length - 1];
- *   if (lastArg && typeof lastArg === 'object' && lastArg.signal) {
- *     await MemFlow.workflow.signal(lastArg.signal, result);
+ *   // Signal the waiting workflow with the result
+ *   if (signalInfo?.signal) {
+ *     await MemFlow.workflow.signal(signalInfo.signal, result);
  *   }
- *
  *   return result;
  * }
  * ```
+ *
+ * ```typescript
+ * // With explicit signalId for traceability
+ * const result = await MemFlow.workflow.execHook<AnalysisResult>({
+ *   taskQueue: 'analyzers',
+ *   workflowName: 'runAnalysis',
+ *   args: [datasetId],
+ *   signalId: `analysis-${datasetId}`,
+ * });
+ * ```
+ *
+ * @template T - The type of data returned by the hook function's signal.
+ * @param {ExecHookOptions} options - Hook configuration including target workflow and arguments.
+ * @returns {Promise<T>} The signal result from the hooked function.
  */
 export declare function execHook<T>(options: ExecHookOptions): Promise<T>;

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

@@ -5,60 +5,74 @@ const hook_1 = require("./hook");
 const waitFor_1 = require("./waitFor");
 const interruption_1 = require("./interruption");
 /**
- * Executes a hook function and awaits the signal response.
- * This is a convenience method that combines `hook()` and `waitFor()` operations.
+ * Combines `hook()` + `waitFor()` into a single call: spawns a hook
+ * function on a target workflow and suspends the current workflow until
+ * the hook signals completion. This is the recommended pattern for
+ * request/response communication between workflow threads.
  *
- * **Signal Injection**: The `signalId` is automatically injected as the LAST argument
- * to the hooked function. The hooked function should check for this signal parameter
- * and emit the signal when processing is complete.
+ * ## Signal Injection
  *
- * This behaves like `execChild` but targets the existing workflow instead of
- * spawning a new workflow.
+ * A `signalId` is automatically generated (or use the one you provide)
+ * and injected as the **last argument** to the hooked function as
+ * `{ signal: string, $memflow: true }`. The hook function must call
+ * `MemFlow.workflow.signal(signalInfo.signal, result)` to deliver
+ * its response back to the waiting workflow.
  *
- * @template T
- * @param {ExecHookOptions} options - Hook configuration with signal ID.
- * @returns {Promise<T>} The signal result from the hooked function.
+ * ## Difference from `execChild`
  *
- * @example
- * ```typescript
- * // Execute a hook and await its signal response
- * const result = await MemFlow.workflow.execHook({
- *   taskQueue: 'processing',
- *   workflowName: 'processData',
- *   args: ['user123', 'batch-process'],
- *   signalId: 'processing-complete'
- * });
+ * - `execChild` spawns a **new** workflow job with its own lifecycle.
+ * - `execHook` runs within an **existing** workflow's job, in an
+ *   isolated dimensional thread. This is lighter-weight and shares
+ *   the parent job's data namespace.
  *
- * // The hooked function receives the signal as the last argument:
- * export async function processData(userId: string, processType: string, signalInfo?: { signal: string }) {
- *   // ... do processing work ...
- *   const result = { userId, processType, status: 'completed' };
+ * ## Examples
  *
- *   // Check if called via execHook (signalInfo will be present)
- *   if (signalInfo?.signal) {
- *     await MemFlow.workflow.signal(signalInfo.signal, result);
- *   }
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
  *
- *   return result;
+ * // Orchestrator: spawn a hook and await its result
+ * export async function reviewWorkflow(docId: string): Promise<string> {
+ *   const verdict = await MemFlow.workflow.execHook<{ approved: boolean }>({
+ *     taskQueue: 'reviewers',
+ *     workflowName: 'reviewDocument',
+ *     args: [docId],
+ *   });
+ *
+ *   return verdict.approved ? 'accepted' : 'rejected';
  * }
  * ```
  *
- * @example
  * ```typescript
- * // Alternative pattern - check if last arg is signal object
- * export async function myHookFunction(arg1: string, arg2: number, ...rest: any[]) {
- *   // ... process arg1 and arg2 ...
- *   const result = { processed: true, data: [arg1, arg2] };
+ * // The hooked function (runs on the 'reviewers' worker)
+ * export async function reviewDocument(
+ *   docId: string,
+ *   signalInfo?: { signal: string; $memflow: boolean },
+ * ): Promise<{ approved: boolean }> {
+ *   const { analyzeDocument } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   const score = await analyzeDocument(docId);
+ *   const result = { approved: score > 0.8 };
  *
- *   // Check if last argument is a signal object
- *   const lastArg = rest[rest.length - 1];
- *   if (lastArg && typeof lastArg === 'object' && lastArg.signal) {
- *     await MemFlow.workflow.signal(lastArg.signal, result);
+ *   // Signal the waiting workflow with the result
+ *   if (signalInfo?.signal) {
+ *     await MemFlow.workflow.signal(signalInfo.signal, result);
  *   }
- *
  *   return result;
  * }
  * ```
+ *
+ * ```typescript
+ * // With explicit signalId for traceability
+ * const result = await MemFlow.workflow.execHook<AnalysisResult>({
+ *   taskQueue: 'analyzers',
+ *   workflowName: 'runAnalysis',
+ *   args: [datasetId],
+ *   signalId: `analysis-${datasetId}`,
+ * });
+ * ```
+ *
+ * @template T - The type of data returned by the hook function's signal.
+ * @param {ExecHookOptions} options - Hook configuration including target workflow and arguments.
+ * @returns {Promise<T>} The signal result from the hooked function.
  */
 async function execHook(options) {
     try {

package/build/services/memflow/workflow/execHookBatch.d.ts

@@ -1,6 +1,7 @@
 import { ExecHookOptions } from './execHook';
 /**
- * Configuration for a single hook in a batch execution
+ * Configuration for a single hook in a batch execution.
+ * @see {@link execHookBatch}
  */
 export interface BatchHookConfig<T = any> {
     /** Unique key to identify this hook's result in the returned object */
@@ -9,46 +10,98 @@ export interface BatchHookConfig<T = any> {
     options: ExecHookOptions;
 }
 /**
- * Executes multiple hooks in parallel and awaits all their signal responses.
- * This solves the race condition where Promise.all() with execHook() would prevent
- * all waitFor() registrations from completing.
+ * Executes multiple hooks in parallel and awaits all their signal responses,
+ * returning a keyed object of results. This is the recommended way to run
+ * concurrent hooks — it solves a race condition where calling
+ * `Promise.all([execHook(), execHook()])` would throw before all `waitFor`
+ * registrations complete.
  *
- * The method ensures all waitFor() registrations happen before any hooks execute,
- * preventing signals from being sent before the framework is ready to receive them.
+ * ## Three-Phase Execution
  *
- * @template T - Object type with keys matching the batch hook keys and values as expected response types
- * @param {BatchHookConfig[]} hookConfigs - Array of hook configurations with unique keys
- * @returns {Promise<T>} Object with keys from hookConfigs and values as the signal responses
+ * 1. **Fire all hooks** via `Promise.all` (registers streams immediately).
+ * 2. **Await all signals** via `Promise.all` (all `waitFor` registrations
+ *    happen together before any `MemFlowWaitForError` is thrown).
+ * 3. **Combine results** into a `{ [key]: result }` map.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Fan-out to multiple AI agents, gather all perspectives
+ * export async function researchWorkflow(query: string): Promise<Summary> {
+ *   const perspectives = await MemFlow.workflow.execHookBatch<{
+ *     optimistic: PerspectiveResult;
+ *     skeptical: PerspectiveResult;
+ *     neutral: PerspectiveResult;
+ *   }>([
+ *     {
+ *       key: 'optimistic',
+ *       options: {
+ *         taskQueue: 'agents',
+ *         workflowName: 'analyzeOptimistic',
+ *         args: [query],
+ *       },
+ *     },
+ *     {
+ *       key: 'skeptical',
+ *       options: {
+ *         taskQueue: 'agents',
+ *         workflowName: 'analyzeSkeptical',
+ *         args: [query],
+ *       },
+ *     },
+ *     {
+ *       key: 'neutral',
+ *       options: {
+ *         taskQueue: 'agents',
+ *         workflowName: 'analyzeNeutral',
+ *         args: [query],
+ *       },
+ *     },
+ *   ]);
+ *
+ *   // All three results are available as typed properties
+ *   const { synthesize } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   return await synthesize(
+ *     perspectives.optimistic,
+ *     perspectives.skeptical,
+ *     perspectives.neutral,
+ *   );
+ * }
+ * ```
  *
- * @example
  * ```typescript
- * // Execute multiple research perspectives in parallel
- * const results = await MemFlow.workflow.execHookBatch<{
- *   optimistic: OptimisticResult;
- *   skeptical: SkepticalResult;
+ * // Parallel validation with different services
+ * const checks = await MemFlow.workflow.execHookBatch<{
+ *   fraud: { safe: boolean };
+ *   compliance: { approved: boolean };
  * }>([
  *   {
- *     key: 'optimistic',
+ *     key: 'fraud',
  *     options: {
- *       taskQueue: 'agents',
- *       workflowName: 'optimisticPerspective',
- *       args: [query],
- *       signalId: 'optimistic-complete'
- *     }
+ *       taskQueue: 'fraud-detection',
+ *       workflowName: 'checkFraud',
+ *       args: [transactionId],
+ *     },
  *   },
  *   {
- *     key: 'skeptical',
+ *     key: 'compliance',
  *     options: {
- *       taskQueue: 'agents',
- *       workflowName: 'skepticalPerspective',
- *       args: [query],
- *       signalId: 'skeptical-complete'
- *     }
- *   }
+ *       taskQueue: 'compliance',
+ *       workflowName: 'checkCompliance',
+ *       args: [transactionId],
+ *     },
+ *   },
  * ]);
  *
- * // results.optimistic contains the OptimisticResult
- * // results.skeptical contains the SkepticalResult
+ * if (checks.fraud.safe && checks.compliance.approved) {
+ *   // proceed with transaction
+ * }
  * ```
+ *
+ * @template T - Object type with keys matching the batch hook keys.
+ * @param {BatchHookConfig[]} hookConfigs - Array of hook configurations with unique keys.
+ * @returns {Promise<T>} Object mapping each config's `key` to its signal response.
  */
 export declare function execHookBatch<T extends Record<string, any>>(hookConfigs: BatchHookConfig[]): Promise<T>;