@hotmeshio/hotmesh 0.4.0 → 0.4.2

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

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interrupt = void 0;
+const common_1 = require("./common");
+const context_1 = require("./context");
+const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
+/**
+ * Interrupts a running job by sending an interruption request.
+ *
+ * @param {string} jobId - The ID of the job to interrupt.
+ * @param {JobInterruptOptions} options - Additional interruption options.
+ * @returns {Promise<string|void>} Result of the interruption, if any.
+ */
+async function interrupt(jobId, options = {}) {
+    const { workflowTopic, connection, namespace } = (0, context_1.getContext)();
+    const hotMeshClient = await common_1.WorkerService.getHotMesh(workflowTopic, {
+        connection,
+        namespace,
+    });
+    if (await (0, isSideEffectAllowed_1.isSideEffectAllowed)(hotMeshClient, 'interrupt')) {
+        return await hotMeshClient.interrupt(`${hotMeshClient.appId}.execute`, jobId, options);
+    }
+}
+exports.interrupt = interrupt;

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

@@ -0,0 +1,10 @@
+import { HotMesh } from './common';
+/**
+ * Checks if a side-effect is allowed to run. This ensures certain actions
+ * are executed exactly once.
+ * @private
+ * @param {HotMesh} hotMeshClient - The HotMesh client.
+ * @param {string} prefix - A unique prefix representing the action (e.g., 'trace', 'emit', etc.)
+ * @returns {Promise<boolean>} True if the side effect can run, false otherwise.
+ */
+export declare function isSideEffectAllowed(hotMeshClient: HotMesh, prefix: string): Promise<boolean>;

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSideEffectAllowed = void 0;
+const common_1 = require("./common");
+/**
+ * Checks if a side-effect is allowed to run. This ensures certain actions
+ * are executed exactly once.
+ * @private
+ * @param {HotMesh} hotMeshClient - The HotMesh client.
+ * @param {string} prefix - A unique prefix representing the action (e.g., 'trace', 'emit', etc.)
+ * @returns {Promise<boolean>} True if the side effect can run, false otherwise.
+ */
+async function isSideEffectAllowed(hotMeshClient, prefix) {
+    const store = common_1.asyncLocalStorage.getStore();
+    const workflowId = store.get('workflowId');
+    const workflowDimension = store.get('workflowDimension') ?? '';
+    const COUNTER = store.get('counter');
+    const execIndex = COUNTER.counter = COUNTER.counter + 1;
+    const sessionId = `-${prefix}${workflowDimension}-${execIndex}-`;
+    const replay = store.get('replay');
+    if (sessionId in replay) {
+        return false;
+    }
+    const keyParams = {
+        appId: hotMeshClient.appId,
+        jobId: workflowId,
+    };
+    const workflowGuid = common_1.KeyService.mintKey(hotMeshClient.namespace, common_1.KeyType.JOB_STATE, keyParams);
+    const searchClient = hotMeshClient.engine.search;
+    const guidValue = await searchClient.incrementFieldByFloat(workflowGuid, sessionId, 1);
+    return guidValue === 1;
+}
+exports.isSideEffectAllowed = isSideEffectAllowed;

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

@@ -0,0 +1,20 @@
+import { ActivityConfig, ProxyType, MemFlowProxyErrorType } from './common';
+import { getContext } from './context';
+/**
+ * Constructs payload for spawning a proxyActivity job.
+ * @private
+ */
+declare function getProxyInterruptPayload(context: ReturnType<typeof getContext>, activityName: string, execIndex: number, args: any[], options?: ActivityConfig): MemFlowProxyErrorType;
+/**
+ * Wraps a single activity in a proxy, orchestrating its execution and replay.
+ * @private
+ */
+declare function wrapActivity<T>(activityName: string, options?: ActivityConfig): T;
+/**
+ * Provides a proxy for defined activities, ensuring deterministic replay and retry.
+ * @template ACT
+ * @param {ActivityConfig} [options] - Optional activity config (includes retryPolicy).
+ * @returns {ProxyType<ACT>} A proxy to call activities as if local, but durably managed by the workflow.
+ */
+export declare function proxyActivities<ACT>(options?: ActivityConfig): ProxyType<ACT>;
+export { wrapActivity, getProxyInterruptPayload };

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

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProxyInterruptPayload = exports.wrapActivity = exports.proxyActivities = void 0;
+const common_1 = require("./common");
+const context_1 = require("./context");
+const didRun_1 = require("./didRun");
+/**
+ * Constructs payload for spawning a proxyActivity job.
+ * @private
+ */
+function getProxyInterruptPayload(context, activityName, execIndex, args, options) {
+    const { workflowDimension, workflowId, originJobId, workflowTopic, expire } = context;
+    const activityTopic = `${workflowTopic}-activity`;
+    const activityJobId = `-${workflowId}-$${activityName}${workflowDimension}-${execIndex}`;
+    let maximumInterval;
+    if (options?.retryPolicy?.maximumInterval) {
+        maximumInterval = (0, common_1.s)(options.retryPolicy.maximumInterval);
+    }
+    return {
+        arguments: args,
+        workflowDimension,
+        index: execIndex,
+        originJobId: originJobId || workflowId,
+        parentWorkflowId: workflowId,
+        workflowId: activityJobId,
+        workflowTopic: activityTopic,
+        activityName,
+        expire: options?.expire ?? expire,
+        backoffCoefficient: options?.retryPolicy?.backoffCoefficient ?? undefined,
+        maximumAttempts: options?.retryPolicy?.maximumAttempts ?? undefined,
+        maximumInterval: maximumInterval ?? undefined,
+    };
+}
+exports.getProxyInterruptPayload = getProxyInterruptPayload;
+/**
+ * Wraps a single activity in a proxy, orchestrating its execution and replay.
+ * @private
+ */
+function wrapActivity(activityName, options) {
+    return async function (...args) {
+        const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('proxy');
+        if (didRunAlready) {
+            if (result?.$error) {
+                if (options?.retryPolicy?.throwOnError !== false) {
+                    const code = result.$error.code;
+                    const message = result.$error.message;
+                    const stack = result.$error.stack;
+                    if (code === common_1.HMSH_CODE_MEMFLOW_FATAL) {
+                        throw new common_1.MemFlowFatalError(message, stack);
+                    }
+                    else if (code === common_1.HMSH_CODE_MEMFLOW_MAXED) {
+                        throw new common_1.MemFlowMaxedError(message, stack);
+                    }
+                    else if (code === common_1.HMSH_CODE_MEMFLOW_TIMEOUT) {
+                        throw new common_1.MemFlowTimeoutError(message, stack);
+                    }
+                    else {
+                        // Non-fatal error
+                    }
+                }
+                return result.$error;
+            }
+            return result.data;
+        }
+        const context = (0, context_1.getContext)();
+        const { interruptionRegistry } = context;
+        const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, args, options);
+        interruptionRegistry.push({
+            code: common_1.HMSH_CODE_MEMFLOW_PROXY,
+            ...interruptionMessage,
+        });
+        await (0, common_1.sleepImmediate)();
+        throw new common_1.MemFlowProxyError(interruptionMessage);
+    };
+}
+exports.wrapActivity = wrapActivity;
+/**
+ * Provides a proxy for defined activities, ensuring deterministic replay and retry.
+ * @template ACT
+ * @param {ActivityConfig} [options] - Optional activity config (includes retryPolicy).
+ * @returns {ProxyType<ACT>} A proxy to call activities as if local, but durably managed by the workflow.
+ */
+function proxyActivities(options) {
+    if (options?.activities) {
+        common_1.WorkerService.registerActivities(options.activities);
+    }
+    const proxy = {};
+    const keys = Object.keys(common_1.WorkerService.activityRegistry);
+    if (keys.length) {
+        keys.forEach((key) => {
+            const activityFunction = common_1.WorkerService.activityRegistry[key];
+            proxy[key] = wrapActivity(key, options);
+        });
+    }
+    return proxy;
+}
+exports.proxyActivities = proxyActivities;

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

@@ -0,0 +1,6 @@
+/**
+ * Returns a deterministic random number between 0 and 1. The number is derived from the
+ * current execution index, ensuring deterministic replay.
+ * @returns {number} A deterministic pseudo-random number between 0 and 1.
+ */
+export declare function random(): number;

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

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.random = void 0;
+const common_1 = require("./common");
+/**
+ * Returns a deterministic random number between 0 and 1. The number is derived from the
+ * current execution index, ensuring deterministic replay.
+ * @returns {number} A deterministic pseudo-random number between 0 and 1.
+ */
+function random() {
+    const store = common_1.asyncLocalStorage.getStore();
+    const COUNTER = store.get('counter');
+    const seed = COUNTER.counter = COUNTER.counter + 1;
+    return (0, common_1.deterministicRandom)(seed);
+}
+exports.random = random;

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

@@ -0,0 +1,6 @@
+import { Search } from './common';
+/**
+ * Returns a search session handle for interacting with the workflow's HASH storage.
+ * @returns {Promise<Search>} A search session for workflow data.
+ */
+export declare function search(): Promise<Search>;

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.search = void 0;
+const common_1 = require("./common");
+/**
+ * Returns a search session handle for interacting with the workflow's HASH storage.
+ * @returns {Promise<Search>} A search session for workflow data.
+ */
+async function search() {
+    const store = common_1.asyncLocalStorage.getStore();
+    const workflowId = store.get('workflowId');
+    const workflowDimension = store.get('workflowDimension') ?? '';
+    const workflowTopic = store.get('workflowTopic');
+    const connection = store.get('connection');
+    const namespace = store.get('namespace');
+    const COUNTER = store.get('counter');
+    const execIndex = COUNTER.counter = COUNTER.counter + 1;
+    const hotMeshClient = await common_1.WorkerService.getHotMesh(workflowTopic, {
+        connection,
+        namespace,
+    });
+    const searchSessionId = `-search${workflowDimension}-${execIndex}`;
+    return new common_1.Search(workflowId, hotMeshClient, searchSessionId);
+}
+exports.search = search;

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

@@ -0,0 +1,29 @@
+/**
+ * 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 });
+ * }
+ *
+ * @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.
+ */
+export declare function signal(signalId: string, data: Record<any, any>): Promise<string>;

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 });
+ * }
+ *
+ * @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.
+ */
+async function signal(signalId, data) {
+    const store = common_1.asyncLocalStorage.getStore();
+    const workflowTopic = store.get('workflowTopic');
+    const connection = store.get('connection');
+    const namespace = store.get('namespace');
+    const hotMeshClient = await common_1.WorkerService.getHotMesh(workflowTopic, {
+        connection,
+        namespace,
+    });
+    if (await (0, isSideEffectAllowed_1.isSideEffectAllowed)(hotMeshClient, 'signal')) {
+        return await hotMeshClient.hook(`${namespace}.wfs.signal`, {
+            id: signalId,
+            data,
+        });
+    }
+}
+exports.signal = signal;

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

@@ -0,0 +1,24 @@
+/**
+ * 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')
+ * ]);
+ *
+ * @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

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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')
+ * ]);
+ *
+ * @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) {
+    const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('sleep');
+    if (didRunAlready) {
+        return result.duration;
+    }
+    const store = common_1.asyncLocalStorage.getStore();
+    const interruptionRegistry = store.get('interruptionRegistry');
+    const workflowId = store.get('workflowId');
+    const workflowDimension = store.get('workflowDimension') ?? '';
+    const interruptionMessage = {
+        workflowId,
+        duration: (0, common_1.s)(duration),
+        index: execIndex,
+        workflowDimension,
+    };
+    interruptionRegistry.push({
+        code: common_1.HMSH_CODE_MEMFLOW_SLEEP,
+        ...interruptionMessage,
+    });
+    await (0, common_1.sleepImmediate)();
+    throw new common_1.MemFlowSleepError(interruptionMessage);
+}
+exports.sleepFor = sleepFor;

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

@@ -0,0 +1,14 @@
+import { StringScalarType } from './common';
+/**
+ * Executes a distributed trace, outputting the provided attributes
+ * to the telemetry sink (e.g. OpenTelemetry).
+ *
+ * This trace will only run once per workflow execution by default.
+ *
+ * @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.
+ */
+export declare function trace(attributes: StringScalarType, config?: {
+    once: boolean;
+}): Promise<boolean>;

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trace = void 0;
+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).
+ *
+ * This trace will only run once per workflow execution by default.
+ *
+ * @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.
+ */
+async function trace(attributes, config = { once: true }) {
+    const store = common_1.asyncLocalStorage.getStore();
+    const workflowTopic = store.get('workflowTopic');
+    const connection = store.get('connection');
+    const namespace = store.get('namespace');
+    const hotMeshClient = await common_1.WorkerService.getHotMesh(workflowTopic, {
+        connection,
+        namespace,
+    });
+    const { raw, COUNTER } = (0, context_1.getContext)();
+    const { trc: traceId, spn: spanId, aid: activityId } = raw.metadata;
+    if (!config.once || await (0, isSideEffectAllowed_1.isSideEffectAllowed)(hotMeshClient, 'trace')) {
+        return await common_1.TelemetryService.traceActivity(namespace, attributes, activityId, traceId, spanId, COUNTER.counter);
+    }
+    return true;
+}
+exports.trace = trace;

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

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare function waitFor<T>(signalId: string): Promise<T>;

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

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitFor = void 0;
+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.
+ *
+ * @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.
+ */
+async function waitFor(signalId) {
+    const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('wait');
+    if (didRunAlready) {
+        return result.data.data;
+    }
+    const store = common_1.asyncLocalStorage.getStore();
+    const interruptionRegistry = store.get('interruptionRegistry');
+    const workflowId = store.get('workflowId');
+    const workflowDimension = store.get('workflowDimension') ?? '';
+    const interruptionMessage = {
+        workflowId,
+        signalId,
+        index: execIndex,
+        workflowDimension,
+    };
+    interruptionRegistry.push({
+        code: common_1.HMSH_CODE_MEMFLOW_WAIT,
+        ...interruptionMessage,
+    });
+    await (0, common_1.sleepImmediate)();
+    throw new common_1.MemFlowWaitForError(interruptionMessage);
+}
+exports.waitFor = waitFor;