@hotmeshio/hotmesh 0.4.1 → 0.4.3

package/build/services/memflow/{context.js → entity.js}

@@ -1,29 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Context = void 0;
+exports.Entity = void 0;
 const key_1 = require("../../modules/key");
 const storage_1 = require("../../modules/storage");
 /**
- * The Context module provides methods for reading and writing
- * JSONB data to a workflow's context. The instance methods
+ * The Entity module provides methods for reading and writing
+ * JSONB data to a workflow's entity. The instance methods
  * exposed by this class are available for use from within
  * a running workflow.
  *
  * @example
  * ```typescript
- * //contextWorkflow.ts
+ * //entityWorkflow.ts
  * import { workflow } from '@hotmeshio/hotmesh';
  *
- * export async function contextExample(): Promise<void> {
- *   const context = await workflow.context();
- *   await context.set({ user: { id: 123 } });
- *   await context.merge({ user: { name: "John" } });
- *   const user = await context.get("user");
+ * export async function entityExample(): Promise<void> {
+ *   const entity = await workflow.entity();
+ *   await entity.set({ user: { id: 123 } });
+ *   await entity.merge({ user: { name: "John" } });
+ *   const user = await entity.get("user");
  *   // user = { id: 123, name: "John" }
  * }
  * ```
  */
-class Context {
+class Entity {
     /**
      * @private
      */
@@ -53,11 +53,11 @@ class Context {
         return `${this.searchSessionId}-${this.searchSessionIndex++}-`;
     }
     /**
-     * Sets the entire context object. This replaces any existing context.
+     * Sets the entire entity object. This replaces any existing entity.
      *
      * @example
-     * const context = await workflow.context();
-     * await context.set({ user: { id: 123, name: "John" } });
+     * const entity = await workflow.entity();
+     * await entity.set({ user: { id: 123, name: "John" } });
      */
     async set(value) {
         const ssGuid = this.getSearchSessionGuid();
@@ -66,7 +66,7 @@ class Context {
         if (ssGuid in replay) {
             return JSON.parse(replay[ssGuid]);
         }
-        // Use single transactional call to update context and store replay value
+        // Use single transactional call to update entity and store replay value
         const result = await this.search.updateContext(this.jobId, {
             '@context': JSON.stringify(value),
             [ssGuid]: '', // Pass replay ID to hash module for transactional replay storage
@@ -74,11 +74,11 @@ class Context {
         return result || value;
     }
     /**
-     * Deep merges the provided object with the existing context
+     * Deep merges the provided object with the existing entity
      *
      * @example
-     * const context = await workflow.context();
-     * await context.merge({ user: { email: "john@example.com" } });
+     * const entity = await workflow.entity();
+     * await entity.merge({ user: { email: "john@example.com" } });
      */
     async merge(value) {
         const ssGuid = this.getSearchSessionGuid();
@@ -95,29 +95,29 @@ class Context {
         return newContext;
     }
     /**
-     * Gets a value from the context by path
+     * Gets a value from the entity by path
      *
      * @example
-     * const context = await workflow.context();
-     * const user = await context.get("user");
-     * const email = await context.get("user.email");
+     * const entity = await workflow.entity();
+     * const user = await entity.get("user");
+     * const email = await entity.get("user.email");
      */
     async get(path) {
         const ssGuid = this.getSearchSessionGuid();
         const store = storage_1.asyncLocalStorage.getStore();
         const replay = store?.get('replay') ?? {};
         if (ssGuid in replay) {
-            // Replay cache stores the already-extracted value, not full context
+            // Replay cache stores the already-extracted value, not full entity
             return JSON.parse(replay[ssGuid]);
         }
         let value;
         if (!path) {
-            // No path - fetch entire context with replay storage
+            // No path - fetch entire entity with replay storage
             const result = await this.search.updateContext(this.jobId, {
                 '@context:get': '',
                 [ssGuid]: '', // Pass replay ID to hash module
             });
-            // setFields returns the actual context value for @context:get operations
+            // setFields returns the actual entity value for @context:get operations
             value = result || {};
         }
         else {
@@ -132,11 +132,11 @@ class Context {
         return value;
     }
     /**
-     * Deletes a value from the context by path
+     * Deletes a value from the entity by path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.delete("user.email");
+     * const entity = await workflow.entity();
+     * await entity.delete("user.email");
      */
     async delete(path) {
         const ssGuid = this.getSearchSessionGuid();
@@ -156,8 +156,8 @@ class Context {
      * Appends a value to an array at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.append("items", { id: 1, name: "New Item" });
+     * const entity = await workflow.entity();
+     * await entity.append("items", { id: 1, name: "New Item" });
      */
     async append(path, value) {
         const ssGuid = this.getSearchSessionGuid();
@@ -177,8 +177,8 @@ class Context {
      * Prepends a value to an array at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.prepend("items", { id: 0, name: "First Item" });
+     * const entity = await workflow.entity();
+     * await entity.prepend("items", { id: 0, name: "First Item" });
      */
     async prepend(path, value) {
         const ssGuid = this.getSearchSessionGuid();
@@ -198,8 +198,8 @@ class Context {
      * Removes an item from an array at the specified path and index
      *
      * @example
-     * const context = await workflow.context();
-     * await context.remove("items", 0); // Remove first item
+     * const entity = await workflow.entity();
+     * await entity.remove("items", 0); // Remove first item
      */
     async remove(path, index) {
         const ssGuid = this.getSearchSessionGuid();
@@ -219,8 +219,8 @@ class Context {
      * Increments a numeric value at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.increment("counter", 5);
+     * const entity = await workflow.entity();
+     * await entity.increment("counter", 5);
      */
     async increment(path, value = 1) {
         const ssGuid = this.getSearchSessionGuid();
@@ -240,8 +240,8 @@ class Context {
      * Toggles a boolean value at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.toggle("settings.enabled");
+     * const entity = await workflow.entity();
+     * await entity.toggle("settings.enabled");
      */
     async toggle(path) {
         const ssGuid = this.getSearchSessionGuid();
@@ -261,8 +261,8 @@ class Context {
      * Sets a value at the specified path only if it doesn't already exist
      *
      * @example
-     * const context = await workflow.context();
-     * await context.setIfNotExists("user.id", 123);
+     * const entity = await workflow.entity();
+     * await entity.setIfNotExists("user.id", 123);
      */
     async setIfNotExists(path, value) {
         const ssGuid = this.getSearchSessionGuid();
@@ -296,4 +296,4 @@ class Context {
         return output;
     }
 }
-exports.Context = Context;
+exports.Entity = Entity;

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

@@ -2,7 +2,7 @@ import { ContextType } from '../../types/memflow';
 import { ClientService } from './client';
 import { ConnectionService } from './connection';
 import { Search } from './search';
-import { Context } from './context';
+import { Entity } from './entity';
 import { WorkerService } from './worker';
 import { WorkflowService } from './workflow';
 import { WorkflowHandleService } from './handle';
@@ -86,7 +86,7 @@ declare class MemFlowClass {
     /**
      * @private
      */
-    static Context: typeof Context;
+    static Entity: typeof Entity;
     /**
      * The Handle provides methods to interact with a running
      * workflow. This includes exporting the workflow, sending signals, and

package/build/services/memflow/index.js

@@ -5,7 +5,7 @@ const hotmesh_1 = require("../hotmesh");
 const client_1 = require("./client");
 const connection_1 = require("./connection");
 const search_1 = require("./search");
-const context_1 = require("./context");
+const entity_1 = require("./entity");
 const worker_1 = require("./worker");
 const workflow_1 = require("./workflow");
 const handle_1 = require("./handle");
@@ -100,7 +100,7 @@ MemFlowClass.Search = search_1.Search;
 /**
  * @private
  */
-MemFlowClass.Context = context_1.Context;
+MemFlowClass.Entity = entity_1.Entity;
 /**
  * The Handle provides methods to interact with a running
  * workflow. This includes exporting the workflow, sending signals, and

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

@@ -15,6 +15,6 @@ import { QuorumMessage } from '../../../types';
 import { UserMessage } from '../../../types/quorum';
 import { Search } from '../search';
 import { WorkerService } from '../worker';
-import { Context } from '../context';
+import { Entity } from '../entity';
 import { ExecHookOptions } from './execHook';
-export { MemFlowChildError, MemFlowFatalError, MemFlowMaxedError, MemFlowProxyError, MemFlowRetryError, MemFlowSleepError, MemFlowTimeoutError, MemFlowWaitForError, KeyService, KeyType, asyncLocalStorage, deterministicRandom, guid, s, sleepImmediate, HotMesh, SerializerService, ActivityConfig, ChildResponseType, HookOptions, ExecHookOptions, ProxyResponseType, ProxyType, WorkflowContext, WorkflowOptions, JobInterruptOptions, StreamCode, StreamStatus, StringAnyType, StringScalarType, StringStringType, HMSH_CODE_MEMFLOW_CHILD, HMSH_CODE_MEMFLOW_FATAL, HMSH_CODE_MEMFLOW_MAXED, HMSH_CODE_MEMFLOW_PROXY, HMSH_CODE_MEMFLOW_SLEEP, HMSH_CODE_MEMFLOW_TIMEOUT, HMSH_CODE_MEMFLOW_WAIT, HMSH_MEMFLOW_EXP_BACKOFF, HMSH_MEMFLOW_MAX_ATTEMPTS, HMSH_MEMFLOW_MAX_INTERVAL, MemFlowChildErrorType, MemFlowProxyErrorType, TelemetryService, QuorumMessage, UserMessage, Search, WorkerService, Context, };
+export { MemFlowChildError, MemFlowFatalError, MemFlowMaxedError, MemFlowProxyError, MemFlowRetryError, MemFlowSleepError, MemFlowTimeoutError, MemFlowWaitForError, KeyService, KeyType, asyncLocalStorage, deterministicRandom, guid, s, sleepImmediate, HotMesh, SerializerService, ActivityConfig, ChildResponseType, HookOptions, ExecHookOptions, ProxyResponseType, ProxyType, WorkflowContext, WorkflowOptions, JobInterruptOptions, StreamCode, StreamStatus, StringAnyType, StringScalarType, StringStringType, HMSH_CODE_MEMFLOW_CHILD, HMSH_CODE_MEMFLOW_FATAL, HMSH_CODE_MEMFLOW_MAXED, HMSH_CODE_MEMFLOW_PROXY, HMSH_CODE_MEMFLOW_SLEEP, HMSH_CODE_MEMFLOW_TIMEOUT, HMSH_CODE_MEMFLOW_WAIT, HMSH_MEMFLOW_EXP_BACKOFF, HMSH_MEMFLOW_MAX_ATTEMPTS, HMSH_MEMFLOW_MAX_INTERVAL, MemFlowChildErrorType, MemFlowProxyErrorType, TelemetryService, QuorumMessage, UserMessage, Search, WorkerService, Entity, };

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Context = exports.WorkerService = exports.Search = exports.TelemetryService = exports.HMSH_MEMFLOW_MAX_INTERVAL = exports.HMSH_MEMFLOW_MAX_ATTEMPTS = exports.HMSH_MEMFLOW_EXP_BACKOFF = exports.HMSH_CODE_MEMFLOW_WAIT = exports.HMSH_CODE_MEMFLOW_TIMEOUT = exports.HMSH_CODE_MEMFLOW_SLEEP = exports.HMSH_CODE_MEMFLOW_PROXY = exports.HMSH_CODE_MEMFLOW_MAXED = exports.HMSH_CODE_MEMFLOW_FATAL = exports.HMSH_CODE_MEMFLOW_CHILD = exports.StreamStatus = exports.SerializerService = exports.HotMesh = exports.sleepImmediate = exports.s = exports.guid = exports.deterministicRandom = exports.asyncLocalStorage = exports.KeyType = exports.KeyService = exports.MemFlowWaitForError = exports.MemFlowTimeoutError = exports.MemFlowSleepError = exports.MemFlowRetryError = exports.MemFlowProxyError = exports.MemFlowMaxedError = exports.MemFlowFatalError = exports.MemFlowChildError = void 0;
+exports.Entity = exports.WorkerService = exports.Search = exports.TelemetryService = exports.HMSH_MEMFLOW_MAX_INTERVAL = exports.HMSH_MEMFLOW_MAX_ATTEMPTS = exports.HMSH_MEMFLOW_EXP_BACKOFF = exports.HMSH_CODE_MEMFLOW_WAIT = exports.HMSH_CODE_MEMFLOW_TIMEOUT = exports.HMSH_CODE_MEMFLOW_SLEEP = exports.HMSH_CODE_MEMFLOW_PROXY = exports.HMSH_CODE_MEMFLOW_MAXED = exports.HMSH_CODE_MEMFLOW_FATAL = exports.HMSH_CODE_MEMFLOW_CHILD = exports.StreamStatus = exports.SerializerService = exports.HotMesh = exports.sleepImmediate = exports.s = exports.guid = exports.deterministicRandom = exports.asyncLocalStorage = exports.KeyType = exports.KeyService = exports.MemFlowWaitForError = exports.MemFlowTimeoutError = exports.MemFlowSleepError = exports.MemFlowRetryError = exports.MemFlowProxyError = exports.MemFlowMaxedError = exports.MemFlowFatalError = exports.MemFlowChildError = void 0;
 const errors_1 = require("../../../modules/errors");
 Object.defineProperty(exports, "MemFlowChildError", { enumerable: true, get: function () { return errors_1.MemFlowChildError; } });
 Object.defineProperty(exports, "MemFlowFatalError", { enumerable: true, get: function () { return errors_1.MemFlowFatalError; } });
@@ -43,5 +43,5 @@ const search_1 = require("../search");
 Object.defineProperty(exports, "Search", { enumerable: true, get: function () { return search_1.Search; } });
 const worker_1 = require("../worker");
 Object.defineProperty(exports, "WorkerService", { enumerable: true, get: function () { return worker_1.WorkerService; } });
-const context_1 = require("../context");
-Object.defineProperty(exports, "Context", { enumerable: true, get: function () { return context_1.Context; } });
+const entity_1 = require("../entity");
+Object.defineProperty(exports, "Entity", { enumerable: true, get: function () { return entity_1.Entity; } });

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

@@ -0,0 +1,14 @@
+import { Entity } from './common';
+/**
+ * Returns an entity session handle for interacting with the workflow's JSONB entity storage.
+ * @returns {Promise<Entity>} An entity session for workflow data.
+ *
+ * @example
+ * ```typescript
+ * const entity = await workflow.entity();
+ * await entity.set({ user: { id: 123 } });
+ * await entity.merge({ user: { name: "John" } });
+ * const user = await entity.get("user");
+ * ```
+ */
+export declare function entity(): Promise<Entity>;

package/build/services/memflow/workflow/{contextMethods.js → entityMethods.js}

@@ -1,20 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.context = void 0;
+exports.entity = void 0;
 const common_1 = require("./common");
 /**
- * Returns a context session handle for interacting with the workflow's JSONB context storage.
- * @returns {Promise<Context>} A context session for workflow data.
+ * Returns an entity session handle for interacting with the workflow's JSONB entity storage.
+ * @returns {Promise<Entity>} An entity session for workflow data.
  *
  * @example
  * ```typescript
- * const context = await workflow.context();
- * await context.set({ user: { id: 123 } });
- * await context.merge({ user: { name: "John" } });
- * const user = await context.get("user");
+ * const entity = await workflow.entity();
+ * await entity.set({ user: { id: 123 } });
+ * await entity.merge({ user: { name: "John" } });
+ * const user = await entity.get("user");
  * ```
  */
-async function context() {
+async function entity() {
     const store = common_1.asyncLocalStorage.getStore();
     const workflowId = store.get('workflowId');
     const workflowDimension = store.get('workflowDimension') ?? '';
@@ -27,7 +27,7 @@ async function context() {
         connection,
         namespace,
     });
-    const contextSessionId = `-context${workflowDimension}-${execIndex}`;
-    return new common_1.Context(workflowId, hotMeshClient, contextSessionId);
+    const entitySessionId = `-entity${workflowDimension}-${execIndex}`;
+    return new common_1.Entity(workflowId, hotMeshClient, entitySessionId);
 }
-exports.context = context;
+exports.entity = entity;

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

@@ -16,7 +16,7 @@ import { all } from './all';
 import { sleepFor } from './sleepFor';
 import { waitFor } from './waitFor';
 import { HotMesh } from './common';
-import { context } from './contextMethods';
+import { entity } from './entityMethods';
 /**
  * The WorkflowService class provides a set of static methods to be used within a workflow function.
  * These methods ensure deterministic replay, persistence of state, and error handling across
@@ -58,7 +58,7 @@ export declare class WorkflowService {
     static execHook: typeof execHook;
     static proxyActivities: typeof proxyActivities;
     static search: typeof search;
-    static context: typeof context;
+    static entity: typeof entity;
     static random: typeof random;
     static signal: typeof signal;
     static hook: typeof hook;

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

@@ -19,7 +19,7 @@ const all_1 = require("./all");
 const sleepFor_1 = require("./sleepFor");
 const waitFor_1 = require("./waitFor");
 const common_1 = require("./common");
-const contextMethods_1 = require("./contextMethods");
+const entityMethods_1 = require("./entityMethods");
 /**
  * The WorkflowService class provides a set of static methods to be used within a workflow function.
  * These methods ensure deterministic replay, persistence of state, and error handling across
@@ -76,7 +76,7 @@ WorkflowService.startChild = execChild_1.startChild;
 WorkflowService.execHook = execHook_1.execHook;
 WorkflowService.proxyActivities = proxyActivities_1.proxyActivities;
 WorkflowService.search = searchMethods_1.search;
-WorkflowService.context = contextMethods_1.context;
+WorkflowService.entity = entityMethods_1.entity;
 WorkflowService.random = random_1.random;
 WorkflowService.signal = signal_1.signal;
 WorkflowService.hook = hook_1.hook;

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

@@ -1,6 +1,28 @@
 /**
  * Sends a signal payload to any paused workflow thread awaiting this signal.
- * @param {string} signalId - Unique signal identifier.
+ * 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 });
+ * }
+ *
+ * @example
+ * // Signal with complex data structure
+ * await MemFlow.workflow.signal('process-complete', {
+ *   status: 'success',
+ *   data: { id: 123, name: 'test' },
+ *   timestamp: new Date().toISOString()
+ * });
+ *
+ * @param {string} signalId - Unique signal identifier that matches a waitFor() call.
  * @param {Record<any, any>} data - The payload to send with the signal.
  * @returns {Promise<string>} The resulting hook/stream ID.
  */

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

@@ -5,7 +5,29 @@ const common_1 = require("./common");
 const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
 /**
  * Sends a signal payload to any paused workflow thread awaiting this signal.
- * @param {string} signalId - Unique signal identifier.
+ * 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 });
+ * }
+ *
+ * @example
+ * // Signal with complex data structure
+ * await MemFlow.workflow.signal('process-complete', {
+ *   status: 'success',
+ *   data: { id: 123, name: 'test' },
+ *   timestamp: new Date().toISOString()
+ * });
+ *
+ * @param {string} signalId - Unique signal identifier that matches a waitFor() call.
  * @param {Record<any, any>} data - The payload to send with the signal.
  * @returns {Promise<string>} The resulting hook/stream ID.
  */

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

@@ -2,7 +2,23 @@
  * Sleeps the workflow for a specified duration, deterministically.
  * On replay, it will not actually sleep again, but resume after sleep.
  *
- * @param {string} duration - A human-readable duration string (e.g., '1m', '2 hours').
+ * @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')
+ * ]);
+ *
+ * @example
+ * // Multiple sequential sleeps
+ * await MemFlow.workflow.sleepFor('1 seconds');  // First pause
+ * await MemFlow.workflow.sleepFor('2 seconds');  // Second pause
+ *
+ * @param {string} duration - A human-readable duration string (e.g., '1m', '2 hours', '30 seconds').
  * @returns {Promise<number>} The resolved duration in seconds.
  */
 export declare function sleepFor(duration: string): Promise<number>;

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

@@ -7,7 +7,23 @@ 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.
  *
- * @param {string} duration - A human-readable duration string (e.g., '1m', '2 hours').
+ * @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')
+ * ]);
+ *
+ * @example
+ * // Multiple sequential sleeps
+ * await MemFlow.workflow.sleepFor('1 seconds');  // First pause
+ * await MemFlow.workflow.sleepFor('2 seconds');  // Second pause
+ *
+ * @param {string} duration - A human-readable duration string (e.g., '1m', '2 hours', '30 seconds').
  * @returns {Promise<number>} The resolved duration in seconds.
  */
 async function sleepFor(duration) {

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

@@ -1,7 +1,28 @@
 /**
  * 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.
  *
- * @template T
+ * @example
+ * // Basic usage - wait for a single signal
+ * const payload = await MemFlow.workflow.waitFor<PayloadType>('abcdefg');
+ *
+ * @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')
+ * ]);
+ *
+ * @example
+ * // Typical pattern with hook functions
+ * // In main workflow:
+ * await MemFlow.workflow.waitFor<ResponseType>('hook-complete');
+ *
+ * // In hook function:
+ * await MemFlow.workflow.signal('hook-complete', { data: result });
+ *
+ * @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,8 +5,29 @@ 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.
  *
- * @template T
+ * @example
+ * // Basic usage - wait for a single signal
+ * const payload = await MemFlow.workflow.waitFor<PayloadType>('abcdefg');
+ *
+ * @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')
+ * ]);
+ *
+ * @example
+ * // Typical pattern with hook functions
+ * // In main workflow:
+ * await MemFlow.workflow.waitFor<ResponseType>('hook-complete');
+ *
+ * // In hook function:
+ * await MemFlow.workflow.signal('hook-complete', { data: result });
+ *
+ * @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

@@ -40,7 +40,7 @@ declare abstract class StoreService<Provider extends ProviderClient, Transaction
     abstract getJobIds(indexKeys: string[], idRange: [number, number]): Promise<IdsData>;
     abstract setStatus(collationKeyStatus: number, jobId: string, appId: string, transaction?: TransactionProvider): Promise<any>;
     abstract getStatus(jobId: string, appId: string): Promise<number>;
-    abstract setStateNX(jobId: string, appId: string, status?: number): Promise<boolean>;
+    abstract setStateNX(jobId: string, appId: string, status?: number, entity?: string): 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/kvsql.d.ts

@@ -52,7 +52,7 @@ export declare class KVSQL {
         sql: string;
         params: any[];
     };
-    hsetnx: (key: string, field: string, value: string, multi?: ProviderTransaction) => Promise<number>;
+    hsetnx: (key: string, field: string, value: string, multi?: ProviderTransaction, entity?: string) => Promise<number>;
     hget: (key: string, field: string, multi?: ProviderTransaction) => Promise<string>;
     _hget: (key: string, field: string) => {
         sql: string;

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

@@ -2,7 +2,7 @@ import { PostgresJobEnumType } from '../../../../../types/postgres';
 import { HScanResult, HSetOptions, ProviderTransaction } from '../../../../../types/provider';
 import type { KVSQL } from '../kvsql';
 export declare const hashModule: (context: KVSQL) => {
-    hsetnx(key: string, field: string, value: string, multi?: ProviderTransaction): Promise<number>;
+    hsetnx(key: string, field: string, value: string, multi?: ProviderTransaction, entity?: string): Promise<number>;
     hset(key: string, fields: Record<string, string>, options?: HSetOptions, multi?: ProviderTransaction): Promise<number | any>;
     /**
      * Derives the enumerated `type` value based on the field name when

package/build/services/store/providers/postgres/kvtypes/hash.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hashModule = void 0;
 const hashModule = (context) => ({
-    async hsetnx(key, field, value, multi) {
-        const { sql, params } = this._hset(key, { [field]: value }, { nx: true });
+    async hsetnx(key, field, value, multi, entity) {
+        const { sql, params } = this._hset(key, { [field]: value }, { nx: true, entity });
         if (multi) {
             multi.addCommand(sql, params, 'number');
             return Promise.resolve(0);
@@ -97,25 +97,25 @@ const hashModule = (context) => ({
             if (options?.nx) {
                 // Use WHERE NOT EXISTS to enforce nx
                 sql = `
-          INSERT INTO ${targetTable} (id, key, status)
-          SELECT gen_random_uuid(), $1, $2
+          INSERT INTO ${targetTable} (id, key, status, entity)
+          SELECT gen_random_uuid(), $1, $2, $3
           WHERE NOT EXISTS (
             SELECT 1 FROM ${targetTable}
             WHERE key = $1 AND is_live
           )
           RETURNING 1 as count
         `;
-                params.push(key, fields[':']);
+                params.push(key, fields[':'], options?.entity ?? null);
             }
             else {
                 // Update existing job or insert new one
                 sql = `
-          INSERT INTO ${targetTable} (id, key, status)
-          VALUES (gen_random_uuid(), $1, $2)
+          INSERT INTO ${targetTable} (id, key, status, entity)
+          VALUES (gen_random_uuid(), $1, $2, $3)
           ON CONFLICT (key) WHERE is_live DO UPDATE SET status = EXCLUDED.status
           RETURNING 1 as count
         `;
-                params.push(key, fields[':']);
+                params.push(key, fields[':'], options?.entity ?? null);
             }
         }
         else if (isJobsTable && '@context' in fields) {