@hotmeshio/hotmesh 0.4.0 → 0.4.2

package/build/services/memflow/exporter.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExporterService = void 0;
+const utils_1 = require("../../modules/utils");
+const serializer_1 = require("../serializer");
+class ExporterService {
+    constructor(appId, store, logger) {
+        this.appId = appId;
+        this.logger = logger;
+        this.store = store;
+    }
+    /**
+     * Convert the job hash from its compiles format into a MemFlowJobExport object with
+     * facets that describe the workflow in terms relevant to narrative storytelling.
+     */
+    async export(jobId, options = {}) {
+        if (!ExporterService.symbols.has(this.appId)) {
+            const symbols = this.store.getAllSymbols();
+            ExporterService.symbols.set(this.appId, await symbols);
+        }
+        const jobData = await this.store.getRaw(jobId);
+        const jobExport = this.inflate(jobData, options);
+        return jobExport;
+    }
+    /**
+     * Inflates the job data from Redis into a MemFlowJobExport object
+     * @param jobHash - the job data from Redis
+     * @param dependencyList - the list of dependencies for the job
+     * @returns - the inflated job data
+     */
+    inflate(jobHash, options) {
+        const timeline = [];
+        const state = {};
+        const data = {};
+        const transitionsObject = {};
+        const regex = /^([a-zA-Z]{3}),(\d+(?:,\d+)*)/;
+        Object.entries(jobHash).forEach(([key, value]) => {
+            const match = key.match(regex);
+            if (match) {
+                //transitions
+                this.inflateTransition(match, value, transitionsObject);
+            }
+            else if (key.startsWith('_')) {
+                //data
+                data[key.substring(1)] = value;
+            }
+            else if (key.startsWith('-')) {
+                //timeline
+                const keyParts = this.keyToObject(key);
+                timeline.push({
+                    ...keyParts,
+                    key,
+                    value: this.resolveValue(value, options.values),
+                });
+            }
+            else if (key.length === 3) {
+                //state
+                state[this.inflateKey(key)] = serializer_1.SerializerService.fromString(value);
+            }
+        });
+        return this.filterFields({
+            data: (0, utils_1.restoreHierarchy)(data),
+            state: Object.entries((0, utils_1.restoreHierarchy)(state))[0][1],
+            status: parseInt(jobHash[':'], 10),
+            timeline: this.sortParts(timeline),
+            transitions: this.sortEntriesByCreated(transitionsObject),
+        }, options.block, options.allow);
+    }
+    resolveValue(raw, withValues) {
+        const resolved = serializer_1.SerializerService.fromString(raw);
+        if (withValues !== false) {
+            return resolved;
+        }
+        if (resolved && typeof resolved === 'object') {
+            if ('data' in resolved) {
+                resolved.data = {};
+            }
+            if ('$error' in resolved) {
+                resolved.$error = {};
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Inflates the key from Redis, 3-character symbol
+     * into a human-readable JSON path, reflecting the
+     * tree-like structure of the unidimensional Hash
+     * @private
+     */
+    inflateKey(key) {
+        const symbols = ExporterService.symbols.get(this.appId);
+        if (key in symbols) {
+            const path = symbols[key];
+            const parts = path.split('/');
+            return parts.join('/');
+        }
+        return key;
+    }
+    filterFields(fullObject, block = [], allow = []) {
+        let result = {};
+        if (allow && allow.length > 0) {
+            allow.forEach((field) => {
+                if (field in fullObject) {
+                    result[field] = fullObject[field];
+                }
+            });
+        }
+        else {
+            result = { ...fullObject };
+        }
+        if (block && block.length > 0) {
+            block.forEach((field) => {
+                if (field in result) {
+                    delete result[field];
+                }
+            });
+        }
+        return result;
+    }
+    inflateTransition(match, value, transitionsObject) {
+        const [_, letters, dimensions] = match;
+        const path = this.inflateKey(letters);
+        const parts = path.split('/');
+        const activity = parts[0];
+        const isCreate = path.endsWith('/output/metadata/ac');
+        const isUpdate = path.endsWith('/output/metadata/au');
+        //for now only export activity start/stop; activity data would also be interesting
+        if (isCreate || isUpdate) {
+            const targetName = `${activity},${dimensions}`;
+            const target = transitionsObject[targetName];
+            if (!target) {
+                transitionsObject[targetName] = {
+                    activity,
+                    dimensions,
+                    created: isCreate ? value : null,
+                    updated: isUpdate ? value : null,
+                };
+            }
+            else {
+                target[isCreate ? 'created' : 'updated'] = value;
+            }
+        }
+    }
+    sortEntriesByCreated(obj) {
+        const entriesArray = Object.values(obj);
+        entriesArray.sort((a, b) => {
+            return (a.created || a.updated).localeCompare(b.created || b.updated);
+        });
+        return entriesArray;
+    }
+    /**
+     * marker names are overloaded with details like sequence, type, etc
+     */
+    keyToObject(key) {
+        function extractDimension(label) {
+            const parts = label.split(',');
+            if (parts.length > 1) {
+                parts.shift();
+                return parts.join(',');
+            }
+        }
+        const parts = key.split('-');
+        if (parts.length === 4) {
+            //-proxy-5-     -search-1-1-
+            return {
+                index: parseInt(parts[2], 10),
+                dimension: extractDimension(parts[1]),
+            };
+        }
+        else {
+            //-search,0,0-1-1-    -proxy,0,0-1-
+            return {
+                index: parseInt(parts[2], 10),
+                secondary: parseInt(parts[3], 10),
+                dimension: extractDimension(parts[1]),
+            };
+        }
+    }
+    /**
+     * idem list has a complicated sort order based on indexes and dimensions
+     */
+    sortParts(parts) {
+        return parts.sort((a, b) => {
+            const { dimension: aDim, index: aIdx, secondary: aSec } = a;
+            const { dimension: bDim, index: bIdx, secondary: bSec } = b;
+            if (aDim === undefined && bDim !== undefined)
+                return -1;
+            if (aDim !== undefined && bDim === undefined)
+                return 1;
+            if (aDim !== undefined && bDim !== undefined) {
+                if (aDim < bDim)
+                    return -1;
+                if (aDim > bDim)
+                    return 1;
+            }
+            if (aIdx < bIdx)
+                return -1;
+            if (aIdx > bIdx)
+                return 1;
+            if (aSec === undefined && bSec !== undefined)
+                return -1;
+            if (aSec !== undefined && bSec === undefined)
+                return 1;
+            if (aSec !== undefined && bSec !== undefined) {
+                if (aSec < bSec)
+                    return -1;
+                if (aSec > bSec)
+                    return 1;
+            }
+            return 0;
+        });
+    }
+}
+exports.ExporterService = ExporterService;
+ExporterService.symbols = new Map();

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

@@ -0,0 +1,90 @@
+import { HotMesh } from '../hotmesh';
+import { MemFlowJobExport, ExportOptions } from '../../types/exporter';
+import { JobInterruptOptions } from '../../types/job';
+import { StreamError } from '../../types/stream';
+import { ExporterService } from './exporter';
+/**
+ * The WorkflowHandleService provides methods to interact with a running
+ * workflow. This includes exporting the workflow, sending signals, and
+ * querying the state of the workflow. It is instanced/accessed via the
+ * MemFlow.Client class.
+ *
+ * @example
+ * ```typescript
+ * import { Client } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Client({ connection: {
+ *   class: Postgres,
+ *   options: { connectionString: 'postgres://user:pass@localhost:5432/db' }
+ * }});
+ *
+ * const handle = await client.workflow.start({
+ *  args: ['HotMesh'],
+ *  taskQueue: 'hello-world',
+ * });
+ *
+ * //perform actions like send a signal
+ * await handle.signal('my-signal', { data: 'Hello' });
+ * ```
+ */
+export declare class WorkflowHandleService {
+    /**
+     * @private
+     */
+    exporter: ExporterService;
+    hotMesh: HotMesh;
+    workflowTopic: string;
+    workflowId: string;
+    /**
+     * @private
+     */
+    constructor(hotMesh: HotMesh, workflowTopic: string, workflowId: string);
+    /**
+     * Exports the workflow state to a JSON object.
+     */
+    export(options?: ExportOptions): Promise<MemFlowJobExport>;
+    /**
+     * Sends a signal to the workflow. This is a way to send
+     * a message to a workflow that is paused due to having
+     * executed `MemFlow.workflow.waitFor`. The workflow
+     * will awaken if no other signals are pending.
+     */
+    signal(signalId: string, data: Record<any, any>): Promise<void>;
+    /**
+     * Returns the job state of the workflow. If the workflow has completed
+     * this is also the job output. If the workflow is still running, this
+     * is the current state of the job, but it may change depending upon
+     * the activities that remain.
+     */
+    state(metadata?: boolean): Promise<Record<string, any>>;
+    /**
+     * Returns the current search state of the workflow. This is
+     * different than the job state or individual activity state.
+     * Search state represents name/value pairs that were added
+     * to the workflow.
+     */
+    queryState(fields: string[]): Promise<Record<string, any>>;
+    /**
+     * Returns the current status of the workflow. This is a semaphore
+     * value that represents the current state of the workflow, where
+     * 0 is complete and a negative value represents that the flow was
+     * interrupted.
+     */
+    status(): Promise<number>;
+    /**
+     * Interrupts a running workflow. Standard Job Completion tasks will
+     * run. Subscribers will be notified and the job hash will be expired.
+     */
+    interrupt(options?: JobInterruptOptions): Promise<string>;
+    /**
+     * Waits for the workflow to complete and returns the result. If
+     * the workflow response includes an error, this method will rethrow
+     * the error, including the stack trace if available.
+     * Wrap calls in a try/catch as necessary to avoid unhandled exceptions.
+     */
+    result<T>(config?: {
+        state?: boolean;
+        throwOnError?: boolean;
+    }): Promise<T | StreamError>;
+}

package/build/services/memflow/handle.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowHandleService = void 0;
+const exporter_1 = require("./exporter");
+/**
+ * The WorkflowHandleService provides methods to interact with a running
+ * workflow. This includes exporting the workflow, sending signals, and
+ * querying the state of the workflow. It is instanced/accessed via the
+ * MemFlow.Client class.
+ *
+ * @example
+ * ```typescript
+ * import { Client } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Client({ connection: {
+ *   class: Postgres,
+ *   options: { connectionString: 'postgres://user:pass@localhost:5432/db' }
+ * }});
+ *
+ * const handle = await client.workflow.start({
+ *  args: ['HotMesh'],
+ *  taskQueue: 'hello-world',
+ * });
+ *
+ * //perform actions like send a signal
+ * await handle.signal('my-signal', { data: 'Hello' });
+ * ```
+ */
+class WorkflowHandleService {
+    /**
+     * @private
+     */
+    constructor(hotMesh, workflowTopic, workflowId) {
+        this.workflowTopic = workflowTopic;
+        this.workflowId = workflowId;
+        this.hotMesh = hotMesh;
+        this.exporter = new exporter_1.ExporterService(this.hotMesh.appId, this.hotMesh.engine.store, this.hotMesh.engine.logger);
+    }
+    /**
+     * Exports the workflow state to a JSON object.
+     */
+    async export(options) {
+        return this.exporter.export(this.workflowId, options);
+    }
+    /**
+     * Sends a signal to the workflow. This is a way to send
+     * a message to a workflow that is paused due to having
+     * executed `MemFlow.workflow.waitFor`. The workflow
+     * will awaken if no other signals are pending.
+     */
+    async signal(signalId, data) {
+        await this.hotMesh.hook(`${this.hotMesh.appId}.wfs.signal`, {
+            id: signalId,
+            data,
+        });
+    }
+    /**
+     * Returns the job state of the workflow. If the workflow has completed
+     * this is also the job output. If the workflow is still running, this
+     * is the current state of the job, but it may change depending upon
+     * the activities that remain.
+     */
+    async state(metadata = false) {
+        const state = await this.hotMesh.getState(`${this.hotMesh.appId}.execute`, this.workflowId);
+        if (!state.data && state.metadata.err) {
+            throw new Error(JSON.parse(state.metadata.err));
+        }
+        return metadata ? state : state.data;
+    }
+    /**
+     * Returns the current search state of the workflow. This is
+     * different than the job state or individual activity state.
+     * Search state represents name/value pairs that were added
+     * to the workflow.
+     */
+    async queryState(fields) {
+        return await this.hotMesh.getQueryState(this.workflowId, fields);
+    }
+    /**
+     * Returns the current status of the workflow. This is a semaphore
+     * value that represents the current state of the workflow, where
+     * 0 is complete and a negative value represents that the flow was
+     * interrupted.
+     */
+    async status() {
+        return await this.hotMesh.getStatus(this.workflowId);
+    }
+    /**
+     * Interrupts a running workflow. Standard Job Completion tasks will
+     * run. Subscribers will be notified and the job hash will be expired.
+     */
+    async interrupt(options) {
+        return await this.hotMesh.interrupt(`${this.hotMesh.appId}.execute`, this.workflowId, options);
+    }
+    /**
+     * Waits for the workflow to complete and returns the result. If
+     * the workflow response includes an error, this method will rethrow
+     * the error, including the stack trace if available.
+     * Wrap calls in a try/catch as necessary to avoid unhandled exceptions.
+     */
+    async result(config) {
+        const topic = `${this.hotMesh.appId}.executed.${this.workflowId}`;
+        let isResolved = false;
+        return new Promise(async (resolve, reject) => {
+            /**
+             * rejects/resolves the promise based on the `throwOnError`
+             * default behavior is to throw if error
+             */
+            const safeReject = (err) => {
+                if (config?.throwOnError === false) {
+                    return resolve(err);
+                }
+                reject(err);
+            };
+            /**
+             * Common completion function that unsubscribes from the topic/returns
+             */
+            const complete = async (response, err) => {
+                if (isResolved)
+                    return;
+                isResolved = true;
+                if (err) {
+                    return safeReject(err);
+                }
+                else if (!response) {
+                    const state = await this.hotMesh.getState(`${this.hotMesh.appId}.execute`, this.workflowId);
+                    if (state.data?.done && !state.data?.$error) {
+                        return resolve(state.data.response);
+                    }
+                    else if (state.data?.$error) {
+                        return safeReject(state.data.$error);
+                    }
+                    else if (state.metadata.err) {
+                        return safeReject(JSON.parse(state.metadata.err));
+                    }
+                    response = state.data?.response;
+                }
+                resolve(response);
+            };
+            //more expensive; fetches the entire job, not just the `status`
+            if (config?.state) {
+                const state = await this.hotMesh.getState(`${this.hotMesh.appId}.execute`, this.workflowId);
+                if (state?.data?.done && !state.data?.$error) {
+                    return complete(state.data.response);
+                }
+                else if (state.data?.$error) {
+                    return complete(null, state.data.$error);
+                }
+                else if (state.metadata.err) {
+                    return complete(null, JSON.parse(state.metadata.err));
+                }
+            }
+            //subscribe to 'done' topic
+            this.hotMesh.sub(topic, async (_topic, state) => {
+                this.hotMesh.unsub(topic);
+                if (state.data.done && !state.data?.$error) {
+                    await complete(state.data?.response);
+                }
+                else if (state.data?.$error) {
+                    return complete(null, state.data.$error);
+                }
+                else if (state.metadata.err) {
+                    const error = JSON.parse(state.metadata.err);
+                    return await complete(null, error);
+                }
+            });
+            //check state in case completed during wiring
+            const status = await this.hotMesh.getStatus(this.workflowId);
+            if (status <= 0) {
+                await complete();
+            }
+        });
+    }
+}
+exports.WorkflowHandleService = WorkflowHandleService;

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

@@ -0,0 +1,116 @@
+import { ContextType } from '../../types/memflow';
+import { ClientService } from './client';
+import { ConnectionService } from './connection';
+import { Search } from './search';
+import { Context } from './context';
+import { WorkerService } from './worker';
+import { WorkflowService } from './workflow';
+import { WorkflowHandleService } from './handle';
+/**
+ * The MemFlow service is a collection of services that
+ * emulate Temporal's capabilities, but instead are
+ * backed by Postgres or Redis/ValKey. The following lifecycle example
+ * demonstrates how to start a new workflow, subscribe
+ * to the result, and shutdown the system.
+ *
+ * @example
+ * ```typescript
+ * import { Client, Worker, MemFlow, HotMesh } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres} from 'pg';
+ * import * as workflows from './workflows';
+ *
+ * //1) Initialize the worker
+ * await Worker.create({
+ *   connection: {
+ *     class: Postgres,
+ *     options: {
+ *       connectionString: 'postgresql://usr:pwd@localhost:5432/db',
+ *     }
+ *   }
+ *   taskQueue: 'default',
+ *   namespace: 'memflow',
+ *   workflow: workflows.example,
+ *   options: {
+ *     backoffCoefficient: 2,
+ *     maximumAttempts: 1_000,
+ *     maximumInterval: '5 seconds'
+ *   }
+ * });
+ *
+ * //2) initialize the client
+ * const client = new Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: {
+ *       connectionString: 'postgresql://usr:pwd@localhost:5432/db',
+ *     }
+ *   }
+ * });
+ *
+ * //3) start a new workflow
+ * const handle = await client.workflow.start({
+ *   args: ['HotMesh', 'es'],
+ *   taskQueue: 'default',
+ *   workflowName: 'example',
+ *   workflowId: HotMesh.guid(),
+ *   namespace: 'memflow',
+ * });
+ *
+ * //4) subscribe to the eventual result
+ * console.log('\nRESPONSE', await handle.result(), '\n');
+ * //logs '¡Hola, HotMesh!'
+ *
+ * //5) Shutdown (typically on sigint)
+ * await MemFlow.shutdown();
+ * ```
+ */
+declare class MemFlowClass {
+    /**
+     * @private
+     */
+    constructor();
+    /**
+     * The MemFlow `Client` service is functionally
+     * equivalent to the Temporal `Client` service.
+     */
+    static Client: typeof ClientService;
+    /**
+     * The MemFlow `Connection` service is functionally
+     * equivalent to the Temporal `Connection` service.
+     */
+    static Connection: typeof ConnectionService;
+    /**
+     * @private
+     */
+    static Search: typeof Search;
+    /**
+     * @private
+     */
+    static Context: typeof Context;
+    /**
+     * The Handle provides methods to interact with a running
+     * workflow. This includes exporting the workflow, sending signals, and
+     * querying the state of the workflow. An instance of the Handle service
+     * is typically accessed via the MemFlow.Client class (workflow.getHandle).
+     */
+    static Handle: typeof WorkflowHandleService;
+    /**
+     * The MemFlow `Worker` service is functionally
+     * equivalent to the Temporal `Worker` service.
+     */
+    static Worker: typeof WorkerService;
+    /**
+     * The MemFlow `workflow` service is functionally
+     * equivalent to the Temporal `Workflow` service
+     * with additional methods for managing workflows,
+     * including: `execChild`, `waitFor`, `sleep`, etc
+     */
+    static workflow: typeof WorkflowService;
+    /**
+     * Shutdown everything. All connections, workers, and clients will be closed.
+     * Include in your signal handlers to ensure a clean shutdown.
+     */
+    static shutdown(): Promise<void>;
+}
+export { MemFlowClass as MemFlow };
+export type { ContextType };