@hotmeshio/hotmesh 0.0.57 → 0.0.58

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

@@ -4,22 +4,140 @@ import { ActivityConfig, HookOptions, ProxyType, WorkflowContext, WorkflowOption
 import { JobInterruptOptions } from '../../types/job';
 import { DurableChildErrorType, DurableProxyErrorType } from '../../types/error';
 export declare class WorkflowService {
+    /**
+     * Returns the synchronous output from the activity (replay)
+     * if available locally, revealing whether or not the activity already
+     * ran during a prior execution cycle
+     * @param {string} prefix - one of: proxy, child, start, wait etc
+     * @returns
+     */
     static didRun(prefix: string): Promise<[boolean, number, any]>;
+    /**
+     * Those methods that may only be called once must be protected by flagging
+     * their execution with a unique key (the key is stored in the HASH alongside
+     * process state and job state)
+     * @private
+     */
     static isSideEffectAllowed(hotMeshClient: HotMesh, prefix: string): Promise<boolean>;
+    /**
+     * Returns the current workflow context restored
+     * from Redis
+     */
     static getContext(): WorkflowContext;
+    /**
+     * Return a handle to the hotmesh client hosting the workflow execution
+     * @returns {Promise<HotMesh>} - a hotmesh client
+     */
     static getHotMesh(): Promise<HotMesh>;
+    /**
+     * Spawns a child workflow and awaits the return.
+     * @template T - the result type
+     * @param {WorkflowOptions} options - the workflow options
+     * @returns {Promise<T>} - the result of the child workflow
+     * @example
+     * const result = await Durable.workflow.execChild<typeof resultType>({ ...options });
+     */
     static execChild<T>(options: WorkflowOptions): Promise<T>;
+    /**
+     * constructs the payload necessary to spawn a child job
+     * @private
+     */
     static getChildInterruptPayload(context: WorkflowContext, options: WorkflowOptions, execIndex: number): DurableChildErrorType;
+    /**
+     * Spawns a child workflow and returns the child Job ID.
+     * This method guarantees the spawned child has reserved the Job ID,
+     * returning a 'DuplicateJobError' error if not. Otherwise,
+     * this is a fire-and-forget method.
+     *
+     * @param {WorkflowOptions} options - the workflow options
+     * @returns {Promise<string>} - the childJobId
+     * @example
+     * const childJobId = await Durable.workflow.startChild({ ...options });
+     */
     static startChild(options: WorkflowOptions): Promise<string>;
+    /**
+     * Wraps activities in a proxy that durably runs/re-runs them to completion.
+     * TODO: verify that activities do not collide if named same on same server but bound to different workflows
+     *
+     * @param {ActivityConfig} options - the activity configuration
+     * that will be used to wrap the activities.
+     * @returns {ProxyType<ACT>} - a proxy object with the same keys as the
+     * activities object, but with the values replaced by a wrapped function
+     *
+     * @example
+     * // import the activities
+     * import * as activities from './activities';
+     * const proxy = WorkflowService.proxyActivities<typeof activities>({ activities });
+     *
+     * //or destructure the proxy object, as the function names are the keys
+     * const { activity1, activity2 } = WorkflowService.proxyActivities<typeof activities>({ activities });
+     */
     static proxyActivities<ACT>(options?: ActivityConfig): ProxyType<ACT>;
     static wrapActivity<T>(activityName: string, options?: ActivityConfig): T;
+    /**
+      * constructs the payload necessary to spawn a proxyActivity job
+      * @private
+      */
     static getProxyInterruptPayload(context: WorkflowContext, activityName: string, execIndex: number, args: any[], options?: ActivityConfig): DurableProxyErrorType;
+    /**
+     * Returns a search session for use when reading/writing to the workflow HASH.
+     * The search session provides access to methods like `get`, `mget`, `set`, `del`, and `incr`.
+     * @returns {Promise<Search>} - a search session
+     */
     static search(): Promise<Search>;
+    /**
+     * Returns a random number between 0 and 1. This number is deterministic
+     * and will never vary for a given seed. This is useful for randomizing
+     * pathways in a workflow that can be safely replayed.
+     * @returns {number} - a random number between 0 and 1
+     */
     static random(): number;
+    /**
+     * Sends signal data into any other paused thread (which is currently
+     * awaiting the signal)
+     * @param {string} signalId - the signal id
+     * @param {Record<any, any>} data - the signal data
+     * @returns {Promise<string>} - the stream id
+     */
     static signal(signalId: string, data: Record<any, any>): Promise<string>;
+    /**
+     * Spawns a hook from either the main thread or a hook thread with
+     * the provided options; worflowId/TaskQueue/Name are optional and will
+     * default to the current workflowId/WorkflowTopic if not provided
+     * @param {HookOptions} options - the hook options
+     */
     static hook(options: HookOptions): Promise<string>;
+    /**
+     * Executes a function once and caches the result. If the function is called
+     * again, the cached result is returned. This is useful for wrapping
+     * expensive activity calls that should only be run once, but which might
+     * not require the cost and safety provided by proxyActivities.
+     * @template T - the result type
+     */
     static once<T>(fn: (...args: any[]) => Promise<T>, ...args: any[]): Promise<T>;
+    /**
+     * Interrupts a running job
+     */
     static interrupt(jobId: string, options?: JobInterruptOptions): Promise<string | void>;
+    /**
+     * Promise.all (limited to 25 total concurrent workflow)
+     */
+    static all<T>(...promises: Promise<T>[]): Promise<T[]>;
+    /**
+     * Sleeps the workflow for a duration. As the function is reentrant,
+     * upon reentry, the function will traverse prior execution paths up
+     * until the sleep command and then resume execution thereafter.
+     * @param {string} duration - See the `ms` package for syntax examples: '1 minute', '2 hours', '3 days'
+     * @returns {Promise<number>} - resolved duration in seconds
+     */
     static sleepFor(duration: string): Promise<number>;
+    /**
+     * Pauses the workflow until `signalId` is received.
+     * @template T - the result type
+     * @param {string} signalId - a unique, shareable guid (e.g, 'abc123')
+     * @returns {Promise<T>}
+     * @example
+     * const result = await Durable.workflow.waitFor<typeof resultType>('abc123');
+     */
     static waitFor<T>(signalId: string): Promise<T>;
 }

package/build/services/durable/workflow.js

@@ -15,6 +15,13 @@ const serializer_1 = require("../serializer");
 const stream_1 = require("../../types/stream");
 const enums_1 = require("../../modules/enums");
 class WorkflowService {
+    /**
+     * Returns the synchronous output from the activity (replay)
+     * if available locally, revealing whether or not the activity already
+     * ran during a prior execution cycle
+     * @param {string} prefix - one of: proxy, child, start, wait etc
+     * @returns
+     */
     static async didRun(prefix) {
         const { COUNTER, replay, workflowDimension, } = WorkflowService.getContext();
         const execIndex = COUNTER.counter = COUNTER.counter + 1;
@@ -25,6 +32,12 @@ class WorkflowService {
         }
         return [false, execIndex, null];
     }
+    /**
+     * Those methods that may only be called once must be protected by flagging
+     * their execution with a unique key (the key is stored in the HASH alongside
+     * process state and job state)
+     * @private
+     */
     static async isSideEffectAllowed(hotMeshClient, prefix) {
         const store = storage_1.asyncLocalStorage.getStore();
         const workflowId = store.get('workflowId');
@@ -44,6 +57,10 @@ class WorkflowService {
         const guidValue = Number(await hotMeshClient.engine.store.exec('HINCRBYFLOAT', workflowGuid, sessionId, '1'));
         return guidValue === 1;
     }
+    /**
+     * Returns the current workflow context restored
+     * from Redis
+     */
     static getContext() {
         const store = storage_1.asyncLocalStorage.getStore();
         const workflowId = store.get('workflowId');
@@ -76,13 +93,27 @@ class WorkflowService {
             workflowSpan,
         };
     }
+    /**
+     * Return a handle to the hotmesh client hosting the workflow execution
+     * @returns {Promise<HotMesh>} - a hotmesh client
+     */
     static async getHotMesh() {
         const store = storage_1.asyncLocalStorage.getStore();
         const workflowTopic = store.get('workflowTopic');
         const namespace = store.get('namespace');
         return await worker_1.WorkerService.getHotMesh(workflowTopic, { namespace });
     }
+    /**
+     * Spawns a child workflow and awaits the return.
+     * @template T - the result type
+     * @param {WorkflowOptions} options - the workflow options
+     * @returns {Promise<T>} - the result of the child workflow
+     * @example
+     * const result = await Durable.workflow.execChild<typeof resultType>({ ...options });
+     */
     static async execChild(options) {
+        //SYNC
+        //check if the activity already ran (check $error/done)
         const isStartChild = options.await === false;
         const prefix = isStartChild ? 'start' : 'child';
         const [didRun, execIndex, result] = await WorkflowService.didRun(prefix);
@@ -91,6 +122,7 @@ class WorkflowService {
         if (didRun) {
             if (result?.$error && (!result.$error.is_stream_error || (result.$error.is_stream_error && !canRetry))) {
                 if (options?.config?.throwOnError !== false) {
+                    //rethrow remote execution error (simulates local failure)
                     const code = result.$error.code;
                     const message = result.$error.message;
                     const stack = result.$error.stack;
@@ -114,13 +146,20 @@ class WorkflowService {
             }
         }
         const interruptionMessage = WorkflowService.getChildInterruptPayload(context, options, execIndex);
+        //push the packaged inputs to the registry
         interruptionRegistry.push({
             code: enums_1.HMSH_CODE_DURABLE_CHILD,
             ...interruptionMessage,
         });
-        await (0, utils_1.sleepFor)(0);
+        //ASYNC
+        //sleep (allow others to be packaged / registered) and throw the error
+        await (0, utils_1.sleepImmediate)();
         throw new errors_1.DurableChildError(interruptionMessage);
     }
+    /**
+     * constructs the payload necessary to spawn a child job
+     * @private
+     */
     static getChildInterruptPayload(context, options, execIndex) {
         const { workflowId, originJobId, workflowDimension } = context;
         let childJobId;
@@ -134,7 +173,7 @@ class WorkflowService {
             childJobId = `-${options.workflowName}-${(0, utils_1.guid)()}-${workflowDimension}-${execIndex}`;
         }
         const parentWorkflowId = workflowId;
-        const taskQueueName = options.entity ?? options.taskQueue;
+        const taskQueueName = options.taskQueue ?? options.entity;
         const workflowName = options.entity ?? options.workflowName;
         const workflowTopic = `${taskQueueName}-${workflowName}`;
         return {
@@ -151,9 +190,37 @@ class WorkflowService {
             workflowTopic,
         };
     }
+    /**
+     * Spawns a child workflow and returns the child Job ID.
+     * This method guarantees the spawned child has reserved the Job ID,
+     * returning a 'DuplicateJobError' error if not. Otherwise,
+     * this is a fire-and-forget method.
+     *
+     * @param {WorkflowOptions} options - the workflow options
+     * @returns {Promise<string>} - the childJobId
+     * @example
+     * const childJobId = await Durable.workflow.startChild({ ...options });
+     */
     static async startChild(options) {
         return WorkflowService.execChild({ ...options, await: false });
     }
+    /**
+     * Wraps activities in a proxy that durably runs/re-runs them to completion.
+     * TODO: verify that activities do not collide if named same on same server but bound to different workflows
+     *
+     * @param {ActivityConfig} options - the activity configuration
+     * that will be used to wrap the activities.
+     * @returns {ProxyType<ACT>} - a proxy object with the same keys as the
+     * activities object, but with the values replaced by a wrapped function
+     *
+     * @example
+     * // import the activities
+     * import * as activities from './activities';
+     * const proxy = WorkflowService.proxyActivities<typeof activities>({ activities });
+     *
+     * //or destructure the proxy object, as the function names are the keys
+     * const { activity1, activity2 } = WorkflowService.proxyActivities<typeof activities>({ activities });
+     */
     static proxyActivities(options) {
         if (options.activities) {
             worker_1.WorkerService.registerActivities(options.activities);
@@ -170,10 +237,13 @@ class WorkflowService {
     }
     static wrapActivity(activityName, options) {
         return async function () {
+            //SYNC
+            //check if the activity already ran
             const [didRun, execIndex, result] = await WorkflowService.didRun('proxy');
             if (didRun) {
                 if (result?.$error) {
                     if (options?.retryPolicy?.throwOnError !== false) {
+                        //rethrow remote execution error (simulates throw)
                         const code = result.$error.code;
                         const message = result.$error.message;
                         const stack = result.$error.stack;
@@ -191,17 +261,25 @@ class WorkflowService {
                 }
                 return result.data;
             }
+            //package the interruption inputs
             const context = WorkflowService.getContext();
             const { interruptionRegistry } = context;
             const interruptionMessage = WorkflowService.getProxyInterruptPayload(context, activityName, execIndex, Array.from(arguments), options);
+            //push the packaged inputs to the registry
             interruptionRegistry.push({
                 code: enums_1.HMSH_CODE_DURABLE_PROXY,
                 ...interruptionMessage,
             });
-            await (0, utils_1.sleepFor)(0);
+            //ASYNC
+            //sleep (allow others to be packaged / registered) and throw the error
+            await (0, utils_1.sleepImmediate)();
             throw new errors_1.DurableProxyError(interruptionMessage);
         };
     }
+    /**
+      * constructs the payload necessary to spawn a proxyActivity job
+      * @private
+      */
     static getProxyInterruptPayload(context, activityName, execIndex, args, options) {
         const { workflowDimension, workflowId, originJobId, workflowTopic } = context;
         const activityTopic = `${workflowTopic}-activity`;
@@ -224,6 +302,11 @@ class WorkflowService {
             maximumInterval: maximumInterval ?? undefined,
         };
     }
+    /**
+     * Returns a search session for use when reading/writing to the workflow HASH.
+     * The search session provides access to methods like `get`, `mget`, `set`, `del`, and `incr`.
+     * @returns {Promise<Search>} - a search session
+     */
     static async search() {
         const store = storage_1.asyncLocalStorage.getStore();
         const workflowId = store.get('workflowId');
@@ -233,15 +316,29 @@ class WorkflowService {
         const COUNTER = store.get('counter');
         const execIndex = COUNTER.counter = COUNTER.counter + 1;
         const hotMeshClient = await worker_1.WorkerService.getHotMesh(workflowTopic, { namespace });
+        //this ID is used as a item key with a hash (dash prefix ensures no collision)
         const searchSessionId = `-search${workflowDimension}-${execIndex}`;
         return new search_1.Search(workflowId, hotMeshClient, searchSessionId);
     }
+    /**
+     * Returns a random number between 0 and 1. This number is deterministic
+     * and will never vary for a given seed. This is useful for randomizing
+     * pathways in a workflow that can be safely replayed.
+     * @returns {number} - a random number between 0 and 1
+     */
     static random() {
         const store = storage_1.asyncLocalStorage.getStore();
         const COUNTER = store.get('counter');
         const seed = COUNTER.counter = COUNTER.counter + 1;
         return (0, utils_1.deterministicRandom)(seed);
     }
+    /**
+     * Sends signal data into any other paused thread (which is currently
+     * awaiting the signal)
+     * @param {string} signalId - the signal id
+     * @param {Record<any, any>} data - the signal data
+     * @returns {Promise<string>} - the stream id
+     */
     static async signal(signalId, data) {
         const store = storage_1.asyncLocalStorage.getStore();
         const workflowTopic = store.get('workflowTopic');
@@ -251,6 +348,12 @@ class WorkflowService {
             return await hotMeshClient.hook(`${namespace}.wfs.signal`, { id: signalId, data });
         }
     }
+    /**
+     * Spawns a hook from either the main thread or a hook thread with
+     * the provided options; worflowId/TaskQueue/Name are optional and will
+     * default to the current workflowId/WorkflowTopic if not provided
+     * @param {HookOptions} options - the hook options
+     */
     static async hook(options) {
         const { workflowId, namespace, workflowTopic, } = WorkflowService.getContext();
         const hotMeshClient = await worker_1.WorkerService.getHotMesh(workflowTopic, { namespace });
@@ -272,6 +375,13 @@ class WorkflowService {
             return await hotMeshClient.hook(`${namespace}.flow.signal`, payload, stream_1.StreamStatus.PENDING, 202);
         }
     }
+    /**
+     * Executes a function once and caches the result. If the function is called
+     * again, the cached result is returned. This is useful for wrapping
+     * expensive activity calls that should only be run once, but which might
+     * not require the cost and safety provided by proxyActivities.
+     * @template T - the result type
+     */
     static async once(fn, ...args) {
         const { COUNTER, namespace, workflowId, workflowTopic, workflowDimension, replay, } = WorkflowService.getContext();
         const execIndex = COUNTER.counter = COUNTER.counter + 1;
@@ -296,6 +406,9 @@ class WorkflowService {
         await hotMeshClient.engine.store.exec('HSET', workflowGuid, sessionId, serializer_1.SerializerService.toString(payload));
         return response;
     }
+    /**
+     * Interrupts a running job
+     */
     static async interrupt(jobId, options = {}) {
         const { workflowTopic, namespace } = WorkflowService.getContext();
         const hotMeshClient = await worker_1.WorkerService.getHotMesh(workflowTopic, { namespace });
@@ -303,11 +416,28 @@ class WorkflowService {
             return await hotMeshClient.interrupt(`${hotMeshClient.appId}.execute`, jobId, options);
         }
     }
+    /**
+     * Promise.all (limited to 25 total concurrent workflow)
+     */
+    static async all(...promises) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        return await Promise.all(promises);
+    }
+    /**
+     * Sleeps the workflow for a duration. As the function is reentrant,
+     * upon reentry, the function will traverse prior execution paths up
+     * until the sleep command and then resume execution thereafter.
+     * @param {string} duration - See the `ms` package for syntax examples: '1 minute', '2 hours', '3 days'
+     * @returns {Promise<number>} - resolved duration in seconds
+     */
     static async sleepFor(duration) {
+        //SYNC
+        //return early if this sleep command has already run
         const [didRun, execIndex, result] = await WorkflowService.didRun('sleep');
         if (didRun) {
-            return result.duration;
+            return result.duration; //in seconds
         }
+        //package the interruption inputs
         const store = storage_1.asyncLocalStorage.getStore();
         const interruptionRegistry = store.get('interruptionRegistry');
         const workflowId = store.get('workflowId');
@@ -322,14 +452,28 @@ class WorkflowService {
             code: enums_1.HMSH_CODE_DURABLE_SLEEP,
             ...interruptionMessage,
         });
-        await (0, utils_1.sleepFor)(0);
+        //ASYNC
+        //sleep to allow other interruptions to be packaged and registered
+        await (0, utils_1.sleepImmediate)();
+        // NOTE: If you are reading this in the stack trace, await `sleepFor`
         throw new errors_1.DurableSleepError(interruptionMessage);
     }
+    /**
+     * Pauses the workflow until `signalId` is received.
+     * @template T - the result type
+     * @param {string} signalId - a unique, shareable guid (e.g, 'abc123')
+     * @returns {Promise<T>}
+     * @example
+     * const result = await Durable.workflow.waitFor<typeof resultType>('abc123');
+     */
     static async waitFor(signalId) {
+        //SYNC
+        //return early if this waitFor command has already run
         const [didRun, execIndex, result] = await WorkflowService.didRun('wait');
         if (didRun) {
             return result.data.data;
         }
+        //package the interruption inputs
         const store = storage_1.asyncLocalStorage.getStore();
         const interruptionRegistry = store.get('interruptionRegistry');
         const workflowId = store.get('workflowId');
@@ -344,7 +488,10 @@ class WorkflowService {
             code: enums_1.HMSH_CODE_DURABLE_WAIT,
             ...interruptionMessage,
         });
-        await (0, utils_1.sleepFor)(0);
+        //ASYNC
+        //sleep to allow other interruptions to be packaged and registered
+        await (0, utils_1.sleepImmediate)();
+        // NOTE: If you are reading this in the stack trace, await `waitFor`
         throw new errors_1.DurableWaitForError(interruptionMessage);
     }
 }

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

@@ -86,6 +86,11 @@ declare class EngineService {
     delistJobCallback(jobId: string): void;
     hasOneTimeSubscription(context: JobState): boolean;
     runJobCompletionTasks(context: JobState, options?: JobCompletionOptions): Promise<string | void>;
+    /**
+     * Job hash expiration is typically reliant on the metadata field
+     * if the activity concludes normally. However, if the job is `interrupted`,
+     * it will be expired immediately.
+     */
     resolveExpires(context: JobState, options: JobCompletionOptions): number;
     export(jobId: string): Promise<JobExport>;
     getRaw(jobId: string): Promise<StringStringType>;