@hotmeshio/hotmesh 0.13.0 → 0.14.0

package/build/services/durable/workflow/enrich.d.ts

@@ -31,6 +31,11 @@ import { StringStringType } from './common';
  * }
  * ```
  *
+ * **Not available with `workerCredentials`.** This is a convenience
+ * wrapper around `search().set()` and inherits the same restriction:
+ * it writes directly to tables, bypassing the stored procedures that
+ * scoped worker roles are restricted to.
+ *
  * @param {StringStringType} fields - Key-value fields to write to the workflow record.
  * @returns {Promise<boolean>} `true` when enrichment is completed.
  */

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

@@ -34,6 +34,11 @@ const searchMethods_1 = require("./searchMethods");
  * }
  * ```
  *
+ * **Not available with `workerCredentials`.** This is a convenience
+ * wrapper around `search().set()` and inherits the same restriction:
+ * it writes directly to tables, bypassing the stored procedures that
+ * scoped worker roles are restricted to.
+ *
  * @param {StringStringType} fields - Key-value fields to write to the workflow record.
  * @returns {Promise<boolean>} `true` when enrichment is completed.
  */

package/build/services/durable/workflow/entityMethods.d.ts

@@ -56,6 +56,13 @@ import { Entity } from './common';
  * }
  * ```
  *
+ * **Not available with `workerCredentials`.** This method writes directly
+ * to the `jobs` table (JSONB `context` column), bypassing the SECURITY
+ * DEFINER stored procedures that scoped worker roles are restricted to.
+ * Workers connecting with `workerCredentials` will receive a permission
+ * error. Use `entity()` only in workflows running with full database
+ * credentials.
+ *
  * @returns {Promise<Entity>} An entity session scoped to the current workflow job.
  */
 export declare function entity(): Promise<Entity>;

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

@@ -59,6 +59,13 @@ const common_1 = require("./common");
  * }
  * ```
  *
+ * **Not available with `workerCredentials`.** This method writes directly
+ * to the `jobs` table (JSONB `context` column), bypassing the SECURITY
+ * DEFINER stored procedures that scoped worker roles are restricted to.
+ * Workers connecting with `workerCredentials` will receive a permission
+ * error. Use `entity()` only in workflows running with full database
+ * credentials.
+ *
  * @returns {Promise<Entity>} An entity session scoped to the current workflow job.
  */
 async function entity() {

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

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.execHook = void 0;
 const hook_1 = require("./hook");
-const waitFor_1 = require("./waitFor");
+const condition_1 = require("./condition");
 const interruption_1 = require("./interruption");
 /**
  * Combines `hook()` + `waitFor()` into a single call: spawns a hook
@@ -85,8 +85,8 @@ async function execHook(options) {
         };
         // Execute the hook with the signal information
         await (0, hook_1.hook)(hookOptions);
-        // Wait for the signal response and return it
-        return await (0, waitFor_1.waitFor)(options.signalId);
+        // Wait for the signal response and return it (no timeout, so never returns false)
+        return await (0, condition_1.condition)(options.signalId);
     }
     catch (error) {
         if ((0, interruption_1.didInterrupt)(error)) {

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

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.execHookBatch = void 0;
 const hook_1 = require("./hook");
-const waitFor_1 = require("./waitFor");
+const condition_1 = require("./condition");
 /**
  * Executes multiple hooks in parallel and awaits all their signal responses,
  * returning a keyed object of results. This is the recommended way to run
@@ -122,7 +122,7 @@ async function execHookBatch(hookConfigs) {
     // STEP 2: Await all waitFor operations 
     // This ensures all waitFor registrations happen in the same call stack
     // before any DurableWaitForError is thrown (via setImmediate mechanism)
-    const results = await Promise.all(processedConfigs.map(config => (0, waitFor_1.waitFor)(config.options.signalId)));
+    const results = await Promise.all(processedConfigs.map(config => (0, condition_1.condition)(config.options.signalId)));
     // STEP 3: Return results as a keyed object
     return Object.fromEntries(processedConfigs.map((config, i) => [config.key, results[i]]));
 }

package/build/services/durable/workflow/{execChild.d.ts → executeChild.d.ts}

@@ -23,7 +23,7 @@ import { WorkflowOptions } from './common';
  *
  * // Spawn a child workflow and await its result
  * export async function parentWorkflow(orderId: string): Promise<string> {
- *   const result = await Durable.workflow.execChild<{ status: string }>({
+ *   const result = await Durable.workflow.executeChild<{ status: string }>({
  *     taskQueue: 'payments',
  *     workflowName: 'processPayment',
  *     args: [orderId, 99.99],
@@ -41,7 +41,7 @@ import { WorkflowOptions } from './common';
  * export async function batchWorkflow(items: string[]): Promise<string[]> {
  *   const results = await Promise.all(
  *     items.map((item) =>
- *       Durable.workflow.execChild<string>({
+ *       Durable.workflow.executeChild<string>({
  *         taskQueue: 'processors',
  *         workflowName: 'processItem',
  *         args: [item],
@@ -54,7 +54,7 @@ import { WorkflowOptions } from './common';
  *
  * ```typescript
  * // Entity-based child (uses entity name as task queue)
- * const user = await Durable.workflow.execChild<UserRecord>({
+ * const user = await Durable.workflow.executeChild<UserRecord>({
  *   entity: 'user',
  *   args: [{ name: 'Alice', email: 'alice@example.com' }],
  *   workflowId: 'user-alice',          // deterministic ID
@@ -66,41 +66,5 @@ import { WorkflowOptions } from './common';
  * @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 {@link execChild}.
- */
-export declare const executeChild: typeof execChild;
-/**
- * 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 { Durable } from '@hotmeshio/hotmesh';
- *
- * export async function dispatchWorkflow(taskId: string): Promise<string> {
- *   // Fire-and-forget: start the child and continue immediately
- *   const childJobId = await Durable.workflow.startChild({
- *     taskQueue: 'background',
- *     workflowName: 'longRunningTask',
- *     args: [taskId],
- *   });
- *
- *   // Optionally store the child ID for monitoring
- *   const search = await Durable.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 executeChild<T>(options: WorkflowOptions): Promise<T>;
 export declare function startChild(options: WorkflowOptions): Promise<string>;

package/build/services/durable/workflow/{execChild.js → executeChild.js}

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startChild = exports.executeChild = exports.execChild = void 0;
+exports.startChild = exports.executeChild = void 0;
 const common_1 = require("./common");
-const context_1 = require("./context");
+const cancellationScope_1 = require("./cancellationScope");
+const workflowInfo_1 = require("./workflowInfo");
 const didRun_1 = require("./didRun");
 /**
  * Constructs the payload necessary to spawn a child workflow.
@@ -32,6 +33,7 @@ function getChildInterruptPayload(context, options, execIndex) {
         await: options?.await ?? true,
         backoffCoefficient: options?.config?.backoffCoefficient ?? common_1.HMSH_DURABLE_EXP_BACKOFF,
         index: execIndex,
+        initialInterval: (0, common_1.s)(options?.config?.initialInterval ?? `${common_1.HMSH_DURABLE_INITIAL_INTERVAL}s`),
         maximumAttempts: options?.config?.maximumAttempts ?? common_1.HMSH_DURABLE_MAX_ATTEMPTS,
         maximumInterval: (0, common_1.s)(options?.config?.maximumInterval ?? common_1.HMSH_DURABLE_MAX_INTERVAL),
         originJobId: originJobId ?? workflowId,
@@ -71,7 +73,7 @@ function getChildInterruptPayload(context, options, execIndex) {
  *
  * // Spawn a child workflow and await its result
  * export async function parentWorkflow(orderId: string): Promise<string> {
- *   const result = await Durable.workflow.execChild<{ status: string }>({
+ *   const result = await Durable.workflow.executeChild<{ status: string }>({
  *     taskQueue: 'payments',
  *     workflowName: 'processPayment',
  *     args: [orderId, 99.99],
@@ -89,7 +91,7 @@ function getChildInterruptPayload(context, options, execIndex) {
  * export async function batchWorkflow(items: string[]): Promise<string[]> {
  *   const results = await Promise.all(
  *     items.map((item) =>
- *       Durable.workflow.execChild<string>({
+ *       Durable.workflow.executeChild<string>({
  *         taskQueue: 'processors',
  *         workflowName: 'processItem',
  *         args: [item],
@@ -102,7 +104,7 @@ function getChildInterruptPayload(context, options, execIndex) {
  *
  * ```typescript
  * // Entity-based child (uses entity name as task queue)
- * const user = await Durable.workflow.execChild<UserRecord>({
+ * const user = await Durable.workflow.executeChild<UserRecord>({
  *   entity: 'user',
  *   args: [{ name: 'Alice', email: 'alice@example.com' }],
  *   workflowId: 'user-alice',          // deterministic ID
@@ -114,13 +116,26 @@ function getChildInterruptPayload(context, options, execIndex) {
  * @param {WorkflowOptions} options - Child workflow configuration.
  * @returns {Promise<T>} The child workflow's return value.
  */
-async function execChild(options) {
+async function executeChild(options) {
     const isStartChild = options.await === false;
     const prefix = isStartChild ? 'start' : 'child';
     const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)(prefix);
-    const context = (0, context_1.getContext)();
+    (0, cancellationScope_1.checkCancellation)();
+    const context = (0, workflowInfo_1.workflowInfo)();
     const { canRetry, interruptionRegistry } = context;
     if (didRunAlready) {
+        // Emit RETURN span in debug mode
+        if (common_1.DurableTelemetryService.isVerbose() && result) {
+            const { workflowTrace, workflowSpan } = context;
+            if (workflowTrace && workflowSpan && result.ac && result.au) {
+                const workflowName = options.workflowName || options.entity || 'unknown';
+                common_1.DurableTelemetryService.emitDurationSpan(workflowTrace, workflowSpan, `RETURN/${prefix}/${workflowName}/${execIndex}`, common_1.DurableTelemetryService.parseTimestamp(result.ac), common_1.DurableTelemetryService.parseTimestamp(result.au), {
+                    'durable.operation.type': prefix,
+                    'durable.workflow.name': workflowName,
+                    'durable.exec.index': execIndex,
+                });
+            }
+        }
         if (result?.$error && (!result.$error.is_stream_error || !canRetry)) {
             if (options?.config?.throwOnError !== false) {
                 const code = result.$error.code;
@@ -145,6 +160,18 @@ async function execChild(options) {
             return result.data;
         }
     }
+    // Emit DISPATCH span in debug mode
+    if (common_1.DurableTelemetryService.isVerbose()) {
+        const { workflowTrace, workflowSpan } = context;
+        if (workflowTrace && workflowSpan) {
+            const workflowName = options.workflowName || options.entity || 'unknown';
+            common_1.DurableTelemetryService.emitPointSpan(workflowTrace, workflowSpan, `DISPATCH/${prefix}/${workflowName}/${execIndex}`, {
+                'durable.operation.type': prefix,
+                'durable.workflow.name': workflowName,
+                'durable.exec.index': execIndex,
+            });
+        }
+    }
     const interruptionMessage = getChildInterruptPayload(context, options, execIndex);
     interruptionRegistry.push({
         code: common_1.HMSH_CODE_DURABLE_CHILD,
@@ -154,44 +181,8 @@ async function execChild(options) {
     await (0, common_1.sleepImmediate)();
     throw new common_1.DurableChildError(interruptionMessage);
 }
-exports.execChild = execChild;
-/**
- * Alias for {@link execChild}.
- */
-exports.executeChild = execChild;
-/**
- * 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 { Durable } from '@hotmeshio/hotmesh';
- *
- * export async function dispatchWorkflow(taskId: string): Promise<string> {
- *   // Fire-and-forget: start the child and continue immediately
- *   const childJobId = await Durable.workflow.startChild({
- *     taskQueue: 'background',
- *     workflowName: 'longRunningTask',
- *     args: [taskId],
- *   });
- *
- *   // Optionally store the child ID for monitoring
- *   const search = await Durable.workflow.search();
- *   await search.set({ childJobId });
- *
- *   return childJobId;
- * }
- * ```
- *
- * @param {WorkflowOptions} options - Child workflow configuration.
- * @returns {Promise<string>} The child workflow's job ID.
- */
+exports.executeChild = executeChild;
 async function startChild(options) {
-    return execChild({ ...options, await: false });
+    return executeChild({ ...options, await: false });
 }
 exports.startChild = startChild;

package/build/services/durable/workflow/hook.d.ts

@@ -50,7 +50,7 @@ import { HookOptions } from './common';
  *   });
  *
  *   // Manually wait for the hook to signal back
- *   return await Durable.workflow.waitFor<string>(signalId);
+ *   return await Durable.workflow.condition<string>(signalId);
  * }
  * ```
  *

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

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hook = void 0;
 const common_1 = require("./common");
-const context_1 = require("./context");
+const workflowInfo_1 = require("./workflowInfo");
 const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
 /**
  * Spawns a hook execution against an existing workflow job. The hook runs
@@ -55,7 +55,7 @@ const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
  *   });
  *
  *   // Manually wait for the hook to signal back
- *   return await Durable.workflow.waitFor<string>(signalId);
+ *   return await Durable.workflow.condition<string>(signalId);
  * }
  * ```
  *
@@ -77,7 +77,7 @@ const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
  * @returns {Promise<string>} The resulting hook/stream ID.
  */
 async function hook(options) {
-    const { workflowId, connection, namespace, workflowTopic } = (0, context_1.getContext)();
+    const { workflowId, connection, namespace, workflowTopic } = (0, workflowInfo_1.workflowInfo)();
     const hotMeshClient = await common_1.WorkerService.getHotMesh(workflowTopic, {
         connection,
         namespace,
@@ -120,6 +120,7 @@ async function hook(options) {
             taskQueue: hookTaskQueue,
             workflowName: hookWorkflowName,
             backoffCoefficient: options.config?.backoffCoefficient || common_1.HMSH_DURABLE_EXP_BACKOFF,
+            initialInterval: (0, common_1.s)(options?.config?.initialInterval ?? `${common_1.HMSH_DURABLE_INITIAL_INTERVAL}s`),
             maximumAttempts: options.config?.maximumAttempts || common_1.HMSH_DURABLE_MAX_ATTEMPTS,
             maximumInterval: (0, common_1.s)(options?.config?.maximumInterval ?? common_1.HMSH_DURABLE_MAX_INTERVAL),
         };

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

@@ -1,63 +1,58 @@
-import { getContext } from './context';
+import { workflowInfo } from './workflowInfo';
 import { didRun } from './didRun';
 import { isSideEffectAllowed } from './isSideEffectAllowed';
 import { trace } from './trace';
 import { enrich } from './enrich';
 import { emit } from './emit';
-import { execChild, startChild } from './execChild';
+import { executeChild, startChild } from './executeChild';
 import { execHook } from './execHook';
 import { execHookBatch } from './execHookBatch';
 import { proxyActivities } from './proxyActivities';
 import { search } from './searchMethods';
 import { random } from './random';
+import { uuid4 } from './uuid4';
 import { signal } from './signal';
 import { hook } from './hook';
-import { interrupt } from './interrupt';
+import { terminate } from './terminate';
 import { didInterrupt } from './interruption';
 import { all } from './all';
-import { sleepFor } from './sleepFor';
-import { waitFor } from './waitFor';
+import { sleep } from './sleep';
+import { condition } from './condition';
+import { continueAsNew } from './continueAsNew';
+import { patched, deprecatePatch } from './patched';
+import { CancellationScope, CancelledFailure, isCancellation } from './cancellationScope';
 import { HotMesh } from './common';
 import { entity } from './entityMethods';
 /**
- * The workflow-internal API surface, exposed as `Durable.workflow`. Every
- * method on this class is designed to be called **inside** a workflow
- * function — they participate in deterministic replay and durable state
- * management.
+ * In-workflow API surface, exposed as `Durable.workflow`. Every method
+ * is called **inside** a workflow function and participates in
+ * deterministic replay — results are persisted and returned instantly
+ * on recovery without re-executing side effects.
  *
- * ## Core Primitives
+ * ## Primitives
  *
  * | Method | Purpose |
  * |--------|---------|
- * | {@link proxyActivities} | Create durable activity proxies with retry |
- * | {@link sleepFor} | Durable, crash-safe sleep |
- * | {@link waitFor} | Pause until a signal is received |
- * | {@link signal} | Send data to a waiting workflow |
- * | {@link execChild} | Spawn and await a child workflow |
- * | {@link startChild} | Spawn a child workflow (fire-and-forget) |
- * | {@link execHook} | Spawn a hook and await its signal response |
- * | {@link execHookBatch} | Spawn multiple hooks in parallel |
- * | {@link hook} | Low-level hook spawning |
- * | {@link interrupt} | Terminate a running workflow |
- *
- * ## Data & Observability
- *
- * | Method | Purpose |
- * |--------|---------|
- * | {@link search} | Read/write flat HASH key-value data |
- * | {@link enrich} | One-shot HASH enrichment |
- * | {@link entity} | Structured JSONB document storage |
- * | {@link emit} | Publish events to the event bus |
- * | {@link trace} | Emit OpenTelemetry trace spans |
+ * | {@link proxyActivities} | Execute activities with automatic retry |
+ * | {@link sleep} | Durable timer (survives restarts) |
+ * | {@link condition} | Pause until a named signal arrives (optional timeout) |
+ * | {@link signal} | Deliver data to a waiting `condition` |
+ * | {@link executeChild} | Spawn a child workflow and await its result |
+ * | {@link startChild} | Fire-and-forget child workflow |
+ * | {@link continueAsNew} | Restart with new args (resets history) |
+ * | {@link patched} / {@link deprecatePatch} | Safe versioning for in-flight code changes |
+ * | {@link CancellationScope} | Shield cleanup code from cancellation |
+ * | {@link isCancellation} | Detect `CancelledFailure` errors |
  *
  * ## Utilities
  *
  * | Method | Purpose |
  * |--------|---------|
- * | {@link getContext} | Access workflow ID, namespace, replay state |
+ * | {@link workflowInfo} | Access workflow ID, namespace, replay state |
  * | {@link random} | Deterministic pseudo-random numbers |
+ * | {@link uuid4} | Deterministic UUID v4 generation |
  * | {@link all} | Workflow-safe `Promise.all` |
- * | {@link didInterrupt} | Type guard for engine control-flow errors |
+ * | {@link didInterrupt} | Detect engine control-flow errors |
  *
  * ## Example
  *
@@ -66,26 +61,20 @@ import { entity } from './entityMethods';
  * import * as activities from './activities';
  *
  * export async function orderWorkflow(orderId: string): Promise<string> {
- *   // Proxy activities for durable execution
  *   const { validateOrder, processPayment, sendReceipt } =
  *     Durable.workflow.proxyActivities<typeof activities>({
  *       activities,
- *       retryPolicy: { maximumAttempts: 3 },
+ *       retry: { maximumAttempts: 3 },
  *     });
  *
  *   await validateOrder(orderId);
- *
- *   // Durable sleep (survives restarts)
- *   await Durable.workflow.sleepFor('5 seconds');
- *
+ *   await Durable.workflow.sleep('5 seconds');
  *   const receipt = await processPayment(orderId);
  *
- *   // Store searchable metadata
- *   await Durable.workflow.enrich({ orderId, status: 'paid' });
- *
- *   // Wait for external approval signal
- *   const approval = await Durable.workflow.waitFor<{ ok: boolean }>('approve');
- *   if (!approval.ok) return 'cancelled';
+ *   // Wait for external approval signal (with 1-hour timeout)
+ *   const approval = await Durable.workflow.condition<{ ok: boolean }>('approve', '1 hour');
+ *   if (!approval) return 'timed-out';
+ *   if (!approval.ok) return 'rejected';
  *
  *   await sendReceipt(orderId, receipt);
  *   return receipt;
@@ -99,14 +88,13 @@ export declare class WorkflowService {
      * all methods are static.
      */
     private constructor();
-    static getContext: typeof getContext;
+    static workflowInfo: typeof workflowInfo;
     static didRun: typeof didRun;
     static isSideEffectAllowed: typeof isSideEffectAllowed;
     static trace: typeof trace;
     static enrich: typeof enrich;
     static emit: typeof emit;
-    static execChild: typeof execChild;
-    static executeChild: typeof execChild;
+    static executeChild: typeof executeChild;
     static startChild: typeof startChild;
     static execHook: typeof execHook;
     static execHookBatch: typeof execHookBatch;
@@ -114,13 +102,20 @@ export declare class WorkflowService {
     static search: typeof search;
     static entity: typeof entity;
     static random: typeof random;
+    static uuid4: typeof uuid4;
     static signal: typeof signal;
     static hook: typeof hook;
     static didInterrupt: typeof didInterrupt;
-    static interrupt: typeof interrupt;
+    static terminate: typeof terminate;
     static all: typeof all;
-    static sleepFor: typeof sleepFor;
-    static waitFor: typeof waitFor;
+    static sleep: typeof sleep;
+    static condition: typeof condition;
+    static continueAsNew: typeof continueAsNew;
+    static patched: typeof patched;
+    static deprecatePatch: typeof deprecatePatch;
+    static CancellationScope: typeof CancellationScope;
+    static CancelledFailure: typeof CancelledFailure;
+    static isCancellation: typeof isCancellation;
     /**
      * Return a handle to the HotMesh client hosting the workflow execution.
      * @returns {Promise<HotMesh>} The HotMesh client instance.