@hotmeshio/hotmesh 0.8.0 → 0.9.0

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

@@ -1,29 +1,58 @@
 /**
- * Sends a signal payload to any paused workflow thread awaiting this signal.
- * This method is commonly used to coordinate between workflows, hook functions,
- * and external events.
- *
- * @example
- * // Basic usage - send a simple signal with data
- * await MemFlow.workflow.signal('signal-id', { name: 'WarmMash' });
- *
- * @example
- * // Hook function signaling completion
- * export async function exampleHook(name: string): Promise<void> {
- *   const result = await processData(name);
- *   await MemFlow.workflow.signal('hook-complete', { data: result });
+ * Sends a signal payload to a paused workflow thread that is awaiting this
+ * `signalId` via `waitFor()`. Signals are the primary mechanism for
+ * inter-workflow communication and for delivering results from hook
+ * functions back to the orchestrating workflow.
+ *
+ * `signal` is the **send** side of the coordination pair. The **receive**
+ * side is `waitFor()`. A signal can be sent from:
+ * - Another workflow function
+ * - A hook function (most common pattern with `execHook`)
+ * - An external client via `MemFlow.Client.workflow.signal()`
+ *
+ * Signals fire exactly once per workflow execution — the `isSideEffectAllowed`
+ * guard ensures they are not re-sent on replay.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Hook function that signals completion back to the parent workflow
+ * export async function processOrder(
+ *   orderId: string,
+ *   signalInfo?: { signal: string; $memflow: boolean },
+ * ): Promise<{ total: number }> {
+ *   const { calculateTotal } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   const total = await calculateTotal(orderId);
+ *
+ *   // Signal the waiting workflow with the result
+ *   if (signalInfo?.signal) {
+ *     await MemFlow.workflow.signal(signalInfo.signal, { total });
+ *   }
+ *   return { total };
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Cross-workflow coordination: workflow A signals workflow B
+ * export async function coordinatorWorkflow(): Promise<void> {
+ *   const { prepareData } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   const data = await prepareData();
+ *
+ *   // Signal another workflow that is paused on waitFor('data-ready')
+ *   await MemFlow.workflow.signal('data-ready', { payload: data });
  * }
+ * ```
  *
- * @example
- * // Signal with complex data structure
- * await MemFlow.workflow.signal('process-complete', {
- *   status: 'success',
- *   data: { id: 123, name: 'test' },
- *   timestamp: new Date().toISOString()
- * });
+ * ```typescript
+ * // External signal from an API handler (outside a workflow)
+ * const client = new MemFlow.Client({ connection });
+ * await client.workflow.signal('approval-signal', { approved: true });
+ * ```
  *
- * @param {string} signalId - Unique signal identifier that matches a waitFor() call.
- * @param {Record<any, any>} data - The payload to send with the signal.
+ * @param {string} signalId - Unique signal identifier that matches a `waitFor()` call.
+ * @param {Record<any, any>} data - The payload to deliver to the waiting workflow.
  * @returns {Promise<string>} The resulting hook/stream ID.
  */
 export declare function signal(signalId: string, data: Record<any, any>): Promise<string>;

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

@@ -4,31 +4,60 @@ exports.signal = void 0;
 const common_1 = require("./common");
 const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
 /**
- * Sends a signal payload to any paused workflow thread awaiting this signal.
- * This method is commonly used to coordinate between workflows, hook functions,
- * and external events.
- *
- * @example
- * // Basic usage - send a simple signal with data
- * await MemFlow.workflow.signal('signal-id', { name: 'WarmMash' });
- *
- * @example
- * // Hook function signaling completion
- * export async function exampleHook(name: string): Promise<void> {
- *   const result = await processData(name);
- *   await MemFlow.workflow.signal('hook-complete', { data: result });
+ * Sends a signal payload to a paused workflow thread that is awaiting this
+ * `signalId` via `waitFor()`. Signals are the primary mechanism for
+ * inter-workflow communication and for delivering results from hook
+ * functions back to the orchestrating workflow.
+ *
+ * `signal` is the **send** side of the coordination pair. The **receive**
+ * side is `waitFor()`. A signal can be sent from:
+ * - Another workflow function
+ * - A hook function (most common pattern with `execHook`)
+ * - An external client via `MemFlow.Client.workflow.signal()`
+ *
+ * Signals fire exactly once per workflow execution — the `isSideEffectAllowed`
+ * guard ensures they are not re-sent on replay.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Hook function that signals completion back to the parent workflow
+ * export async function processOrder(
+ *   orderId: string,
+ *   signalInfo?: { signal: string; $memflow: boolean },
+ * ): Promise<{ total: number }> {
+ *   const { calculateTotal } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   const total = await calculateTotal(orderId);
+ *
+ *   // Signal the waiting workflow with the result
+ *   if (signalInfo?.signal) {
+ *     await MemFlow.workflow.signal(signalInfo.signal, { total });
+ *   }
+ *   return { total };
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Cross-workflow coordination: workflow A signals workflow B
+ * export async function coordinatorWorkflow(): Promise<void> {
+ *   const { prepareData } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   const data = await prepareData();
+ *
+ *   // Signal another workflow that is paused on waitFor('data-ready')
+ *   await MemFlow.workflow.signal('data-ready', { payload: data });
  * }
+ * ```
  *
- * @example
- * // Signal with complex data structure
- * await MemFlow.workflow.signal('process-complete', {
- *   status: 'success',
- *   data: { id: 123, name: 'test' },
- *   timestamp: new Date().toISOString()
- * });
+ * ```typescript
+ * // External signal from an API handler (outside a workflow)
+ * const client = new MemFlow.Client({ connection });
+ * await client.workflow.signal('approval-signal', { approved: true });
+ * ```
  *
- * @param {string} signalId - Unique signal identifier that matches a waitFor() call.
- * @param {Record<any, any>} data - The payload to send with the signal.
+ * @param {string} signalId - Unique signal identifier that matches a `waitFor()` call.
+ * @param {Record<any, any>} data - The payload to deliver to the waiting workflow.
  * @returns {Promise<string>} The resulting hook/stream ID.
  */
 async function signal(signalId, data) {
@@ -41,7 +70,7 @@ async function signal(signalId, data) {
         namespace,
     });
     if (await (0, isSideEffectAllowed_1.isSideEffectAllowed)(hotMeshClient, 'signal')) {
-        return await hotMeshClient.hook(`${namespace}.wfs.signal`, {
+        return await hotMeshClient.signal(`${namespace}.wfs.signal`, {
             id: signalId,
             data,
         });

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

@@ -1,24 +1,63 @@
 /**
- * Sleeps the workflow for a specified duration, deterministically.
- * On replay, it will not actually sleep again, but resume after sleep.
- *
- * @example
- * // Basic usage - sleep for a specific duration
- * await MemFlow.workflow.sleepFor('2 seconds');
- *
- * @example
- * // Using with Promise.all for parallel operations
- * const [greeting, timeInSeconds] = await Promise.all([
- *   someActivity(name),
- *   MemFlow.workflow.sleepFor('1 second')
- * ]);
+ * Suspends workflow execution for a durable, crash-safe duration. Unlike
+ * `setTimeout`, this sleep survives process restarts — the engine persists
+ * the wake-up time and resumes the workflow when the timer expires.
+ *
+ * On replay, `sleepFor` returns immediately with the stored duration
+ * (no actual waiting occurs). This makes it safe for deterministic
+ * re-execution.
+ *
+ * ## Duration Formats
+ *
+ * Accepts any human-readable duration string parsed by the `ms` module:
+ * `'5 seconds'`, `'30s'`, `'2 minutes'`, `'1m'`, `'1 hour'`, `'2h'`,
+ * `'1 day'`, `'7d'`.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Simple delay before continuing
+ * export async function reminderWorkflow(userId: string): Promise<void> {
+ *   const { sendReminder } = MemFlow.workflow.proxyActivities<typeof activities>();
  *
- * @example
- * // Multiple sequential sleeps
- * await MemFlow.workflow.sleepFor('1 seconds');  // First pause
- * await MemFlow.workflow.sleepFor('2 seconds');  // Second pause
+ *   // Wait 24 hours (survives server restarts)
+ *   await MemFlow.workflow.sleepFor('24 hours');
+ *   await sendReminder(userId, 'Your trial expires tomorrow');
+ *
+ *   // Wait another 6 days
+ *   await MemFlow.workflow.sleepFor('6 days');
+ *   await sendReminder(userId, 'Your trial has expired');
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Exponential backoff with retry loop
+ * export async function pollingWorkflow(resourceId: string): Promise<string> {
+ *   const { checkStatus } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   for (let attempt = 0; attempt < 10; attempt++) {
+ *     const status = await checkStatus(resourceId);
+ *     if (status === 'ready') return status;
+ *
+ *     // Exponential backoff: 1s, 2s, 4s, 8s, ...
+ *     const delay = Math.pow(2, attempt);
+ *     await MemFlow.workflow.sleepFor(`${delay} seconds`);
+ *   }
+ *   return 'timeout';
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Race a sleep against an activity
+ * const [result, _] = await Promise.all([
+ *   activities.fetchData(id),
+ *   MemFlow.workflow.sleepFor('30 seconds'),
+ * ]);
+ * ```
  *
- * @param {string} duration - A human-readable duration string (e.g., '1m', '2 hours', '30 seconds').
+ * @param {string} duration - A human-readable duration string.
  * @returns {Promise<number>} The resolved duration in seconds.
  */
 export declare function sleepFor(duration: string): Promise<number>;

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

@@ -4,26 +4,65 @@ exports.sleepFor = void 0;
 const common_1 = require("./common");
 const didRun_1 = require("./didRun");
 /**
- * Sleeps the workflow for a specified duration, deterministically.
- * On replay, it will not actually sleep again, but resume after sleep.
- *
- * @example
- * // Basic usage - sleep for a specific duration
- * await MemFlow.workflow.sleepFor('2 seconds');
- *
- * @example
- * // Using with Promise.all for parallel operations
- * const [greeting, timeInSeconds] = await Promise.all([
- *   someActivity(name),
- *   MemFlow.workflow.sleepFor('1 second')
- * ]);
+ * Suspends workflow execution for a durable, crash-safe duration. Unlike
+ * `setTimeout`, this sleep survives process restarts — the engine persists
+ * the wake-up time and resumes the workflow when the timer expires.
+ *
+ * On replay, `sleepFor` returns immediately with the stored duration
+ * (no actual waiting occurs). This makes it safe for deterministic
+ * re-execution.
+ *
+ * ## Duration Formats
+ *
+ * Accepts any human-readable duration string parsed by the `ms` module:
+ * `'5 seconds'`, `'30s'`, `'2 minutes'`, `'1m'`, `'1 hour'`, `'2h'`,
+ * `'1 day'`, `'7d'`.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Simple delay before continuing
+ * export async function reminderWorkflow(userId: string): Promise<void> {
+ *   const { sendReminder } = MemFlow.workflow.proxyActivities<typeof activities>();
  *
- * @example
- * // Multiple sequential sleeps
- * await MemFlow.workflow.sleepFor('1 seconds');  // First pause
- * await MemFlow.workflow.sleepFor('2 seconds');  // Second pause
+ *   // Wait 24 hours (survives server restarts)
+ *   await MemFlow.workflow.sleepFor('24 hours');
+ *   await sendReminder(userId, 'Your trial expires tomorrow');
+ *
+ *   // Wait another 6 days
+ *   await MemFlow.workflow.sleepFor('6 days');
+ *   await sendReminder(userId, 'Your trial has expired');
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Exponential backoff with retry loop
+ * export async function pollingWorkflow(resourceId: string): Promise<string> {
+ *   const { checkStatus } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   for (let attempt = 0; attempt < 10; attempt++) {
+ *     const status = await checkStatus(resourceId);
+ *     if (status === 'ready') return status;
+ *
+ *     // Exponential backoff: 1s, 2s, 4s, 8s, ...
+ *     const delay = Math.pow(2, attempt);
+ *     await MemFlow.workflow.sleepFor(`${delay} seconds`);
+ *   }
+ *   return 'timeout';
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Race a sleep against an activity
+ * const [result, _] = await Promise.all([
+ *   activities.fetchData(id),
+ *   MemFlow.workflow.sleepFor('30 seconds'),
+ * ]);
+ * ```
  *
- * @param {string} duration - A human-readable duration string (e.g., '1m', '2 hours', '30 seconds').
+ * @param {string} duration - A human-readable duration string.
  * @returns {Promise<number>} The resolved duration in seconds.
  */
 async function sleepFor(duration) {

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

@@ -1,13 +1,46 @@
 import { StringScalarType } from './common';
 /**
- * Executes a distributed trace, outputting the provided attributes
- * to the telemetry sink (e.g. OpenTelemetry).
+ * Emits a distributed trace span to the configured telemetry sink
+ * (e.g., OpenTelemetry). The span is linked to the workflow's trace
+ * context (`traceId`, `spanId`) for end-to-end observability across
+ * workflow executions, activities, and child workflows.
  *
- * This trace will only run once per workflow execution by default.
+ * By default (`config.once = true`), the trace is emitted exactly once
+ * per workflow execution — it will not re-fire on replay.
  *
- * @param {StringScalarType} attributes - Key-value attributes to attach to the trace.
- * @param {{ once: boolean }} [config={ once: true }] - If `once` is true, trace only runs once.
- * @returns {Promise<boolean>} True if tracing succeeded, otherwise false.
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Emit trace spans at key workflow milestones
+ * export async function orderWorkflow(orderId: string): Promise<void> {
+ *   await MemFlow.workflow.trace({
+ *     'order.id': orderId,
+ *     'order.stage': 'started',
+ *   });
+ *
+ *   const { processPayment } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   await processPayment(orderId);
+ *
+ *   await MemFlow.workflow.trace({
+ *     'order.id': orderId,
+ *     'order.stage': 'payment_completed',
+ *   });
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Trace on every re-execution (for debugging replay behavior)
+ * await MemFlow.workflow.trace(
+ *   { 'debug.counter': counter, 'debug.phase': 'retry' },
+ *   { once: false },
+ * );
+ * ```
+ *
+ * @param {StringScalarType} attributes - Key-value attributes to attach to the trace span.
+ * @param {{ once: boolean }} [config={ once: true }] - If `true`, trace fires only once (idempotent).
+ * @returns {Promise<boolean>} `true` if tracing succeeded.
  */
 export declare function trace(attributes: StringScalarType, config?: {
     once: boolean;

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

@@ -5,14 +5,47 @@ const common_1 = require("./common");
 const context_1 = require("./context");
 const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
 /**
- * Executes a distributed trace, outputting the provided attributes
- * to the telemetry sink (e.g. OpenTelemetry).
+ * Emits a distributed trace span to the configured telemetry sink
+ * (e.g., OpenTelemetry). The span is linked to the workflow's trace
+ * context (`traceId`, `spanId`) for end-to-end observability across
+ * workflow executions, activities, and child workflows.
  *
- * This trace will only run once per workflow execution by default.
+ * By default (`config.once = true`), the trace is emitted exactly once
+ * per workflow execution — it will not re-fire on replay.
  *
- * @param {StringScalarType} attributes - Key-value attributes to attach to the trace.
- * @param {{ once: boolean }} [config={ once: true }] - If `once` is true, trace only runs once.
- * @returns {Promise<boolean>} True if tracing succeeded, otherwise false.
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Emit trace spans at key workflow milestones
+ * export async function orderWorkflow(orderId: string): Promise<void> {
+ *   await MemFlow.workflow.trace({
+ *     'order.id': orderId,
+ *     'order.stage': 'started',
+ *   });
+ *
+ *   const { processPayment } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   await processPayment(orderId);
+ *
+ *   await MemFlow.workflow.trace({
+ *     'order.id': orderId,
+ *     'order.stage': 'payment_completed',
+ *   });
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Trace on every re-execution (for debugging replay behavior)
+ * await MemFlow.workflow.trace(
+ *   { 'debug.counter': counter, 'debug.phase': 'retry' },
+ *   { once: false },
+ * );
+ * ```
+ *
+ * @param {StringScalarType} attributes - Key-value attributes to attach to the trace span.
+ * @param {{ once: boolean }} [config={ once: true }] - If `true`, trace fires only once (idempotent).
+ * @returns {Promise<boolean>} `true` if tracing succeeded.
  */
 async function trace(attributes, config = { once: true }) {
     const store = common_1.asyncLocalStorage.getStore();

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

@@ -1,28 +1,65 @@
 /**
  * Pauses the workflow until a signal with the given `signalId` is received.
- * This method is commonly used to coordinate between the main workflow and hook functions,
- * or to wait for external events.
+ * The workflow suspends durably — it survives process restarts and will
+ * resume exactly once when the matching `signal()` call delivers data.
  *
- * @example
- * // Basic usage - wait for a single signal
- * const payload = await MemFlow.workflow.waitFor<PayloadType>('abcdefg');
+ * `waitFor` is the **receive** side of the signal coordination pair.
+ * The **send** side is `signal()`, which can be called from another
+ * workflow, a hook function, or externally via `MemFlow.Client.workflow.signal()`.
  *
- * @example
- * // Wait for multiple signals in parallel
- * const [signal1, signal2] = await Promise.all([
- *   MemFlow.workflow.waitFor<Record<string, any>>('signal1'),
- *   MemFlow.workflow.waitFor<Record<string, any>>('signal2')
- * ]);
+ * On replay, `waitFor` returns the previously stored signal payload
+ * immediately (no actual suspension occurs).
  *
- * @example
- * // Typical pattern with hook functions
- * // In main workflow:
- * await MemFlow.workflow.waitFor<ResponseType>('hook-complete');
+ * ## Examples
  *
- * // In hook function:
- * await MemFlow.workflow.signal('hook-complete', { data: result });
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
  *
- * @template T - The type of data expected in the signal payload
+ * // Human-in-the-loop approval pattern
+ * export async function approvalWorkflow(orderId: string): Promise<boolean> {
+ *   const { submitForReview } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   await submitForReview(orderId);
+ *
+ *   // Pause indefinitely until a human approves or rejects
+ *   const decision = await MemFlow.workflow.waitFor<{ approved: boolean }>('approval');
+ *
+ *   return decision.approved;
+ * }
+ *
+ * // Later, from outside the workflow (e.g., an API handler):
+ * await client.workflow.signal('approval', { approved: true });
+ * ```
+ *
+ * ```typescript
+ * // Fan-in: wait for multiple signals in parallel
+ * export async function gatherWorkflow(): Promise<[string, number]> {
+ *   const [name, score] = await Promise.all([
+ *     MemFlow.workflow.waitFor<string>('name-signal'),
+ *     MemFlow.workflow.waitFor<number>('score-signal'),
+ *   ]);
+ *   return [name, score];
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Paired with hook: spawn work and wait for the result
+ * export async function orchestrator(input: string): Promise<string> {
+ *   const signalId = `result-${MemFlow.workflow.random()}`;
+ *
+ *   // Spawn a hook that will signal back when done
+ *   await MemFlow.workflow.hook({
+ *     taskQueue: 'processors',
+ *     workflowName: 'processItem',
+ *     args: [input, signalId],
+ *   });
+ *
+ *   // Wait for the hook to signal completion
+ *   return await MemFlow.workflow.waitFor<string>(signalId);
+ * }
+ * ```
+ *
+ * @template T - The type of data expected in the signal payload.
  * @param {string} signalId - A unique signal identifier shared by the sender and receiver.
  * @returns {Promise<T>} The data payload associated with the received signal.
  */

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

@@ -5,29 +5,66 @@ const common_1 = require("./common");
 const didRun_1 = require("./didRun");
 /**
  * Pauses the workflow until a signal with the given `signalId` is received.
- * This method is commonly used to coordinate between the main workflow and hook functions,
- * or to wait for external events.
+ * The workflow suspends durably — it survives process restarts and will
+ * resume exactly once when the matching `signal()` call delivers data.
  *
- * @example
- * // Basic usage - wait for a single signal
- * const payload = await MemFlow.workflow.waitFor<PayloadType>('abcdefg');
+ * `waitFor` is the **receive** side of the signal coordination pair.
+ * The **send** side is `signal()`, which can be called from another
+ * workflow, a hook function, or externally via `MemFlow.Client.workflow.signal()`.
  *
- * @example
- * // Wait for multiple signals in parallel
- * const [signal1, signal2] = await Promise.all([
- *   MemFlow.workflow.waitFor<Record<string, any>>('signal1'),
- *   MemFlow.workflow.waitFor<Record<string, any>>('signal2')
- * ]);
+ * On replay, `waitFor` returns the previously stored signal payload
+ * immediately (no actual suspension occurs).
  *
- * @example
- * // Typical pattern with hook functions
- * // In main workflow:
- * await MemFlow.workflow.waitFor<ResponseType>('hook-complete');
+ * ## Examples
  *
- * // In hook function:
- * await MemFlow.workflow.signal('hook-complete', { data: result });
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
  *
- * @template T - The type of data expected in the signal payload
+ * // Human-in-the-loop approval pattern
+ * export async function approvalWorkflow(orderId: string): Promise<boolean> {
+ *   const { submitForReview } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   await submitForReview(orderId);
+ *
+ *   // Pause indefinitely until a human approves or rejects
+ *   const decision = await MemFlow.workflow.waitFor<{ approved: boolean }>('approval');
+ *
+ *   return decision.approved;
+ * }
+ *
+ * // Later, from outside the workflow (e.g., an API handler):
+ * await client.workflow.signal('approval', { approved: true });
+ * ```
+ *
+ * ```typescript
+ * // Fan-in: wait for multiple signals in parallel
+ * export async function gatherWorkflow(): Promise<[string, number]> {
+ *   const [name, score] = await Promise.all([
+ *     MemFlow.workflow.waitFor<string>('name-signal'),
+ *     MemFlow.workflow.waitFor<number>('score-signal'),
+ *   ]);
+ *   return [name, score];
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Paired with hook: spawn work and wait for the result
+ * export async function orchestrator(input: string): Promise<string> {
+ *   const signalId = `result-${MemFlow.workflow.random()}`;
+ *
+ *   // Spawn a hook that will signal back when done
+ *   await MemFlow.workflow.hook({
+ *     taskQueue: 'processors',
+ *     workflowName: 'processItem',
+ *     args: [input, signalId],
+ *   });
+ *
+ *   // Wait for the hook to signal completion
+ *   return await MemFlow.workflow.waitFor<string>(signalId);
+ * }
+ * ```
+ *
+ * @template T - The type of data expected in the signal payload.
  * @param {string} signalId - A unique signal identifier shared by the sender and receiver.
  * @returns {Promise<T>} The data payload associated with the received signal.
  */

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

@@ -45,7 +45,7 @@ declare abstract class StoreService<Provider extends ProviderClient, Transaction
     jobId: string, appId: string, guidField: string, // 
     guidWeight: number, transaction?: ProviderTransaction): Promise<any>;
     abstract getStatus(jobId: string, appId: string): Promise<number>;
-    abstract setStateNX(jobId: string, appId: string, status?: number, entity?: string): Promise<boolean>;
+    abstract setStateNX(jobId: string, appId: string, status?: number, entity?: string, transaction?: ProviderTransaction): Promise<boolean>;
     abstract setState(state: StringAnyType, status: number | null, jobId: string, symbolNames: string[], dIds: StringStringType, transaction?: TransactionProvider): Promise<string>;
     abstract getQueryState(jobId: string, fields: string[]): Promise<StringAnyType>;
     abstract getState(jobId: string, consumes: Consumes, dIds: StringStringType): Promise<[StringAnyType, number] | undefined>;

package/build/services/store/providers/postgres/postgres.d.ts

@@ -103,7 +103,7 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
      * `purposeful re-entry`.
      */
     collateSynthetic(jobId: string, guid: string, amount: number, transaction?: ProviderTransaction): Promise<number>;
-    setStateNX(jobId: string, appId: string, status?: number, entity?: string): Promise<boolean>;
+    setStateNX(jobId: string, appId: string, status?: number, entity?: string, transaction?: ProviderTransaction): Promise<boolean>;
     getSchema(activityId: string, appVersion: AppVID): Promise<ActivityType>;
     getSchemas(appVersion: AppVID): Promise<Record<string, ActivityType>>;
     setSchemas(schemas: Record<string, ActivityType>, appVersion: AppVID): Promise<any>;