@hotmeshio/hotmesh 0.3.29 → 0.3.31

package/build/services/meshcall/index.js

@@ -8,8 +8,42 @@ const utils_1 = require("../../modules/utils");
 const key_1 = require("../../modules/key");
 const cron_1 = require("../pipe/functions/cron");
 const factory_1 = require("./schemas/factory");
+/**
+ * MeshCall connects any function as an idempotent endpoint.
+ * Call functions from anywhere on the network connected to the
+ * target backend (Postgres, Redis/ValKey, NATS, etc). Function
+ * responses are cacheable and invocations can be scheduled to
+ * run as idempotent cron jobs (this one runs nightly at midnight
+ * and uses Postgres as the backend provider).
+ *
+ * @example
+ * ```typescript
+ * import { Client as Postgres } from 'pg';
+ * import { MeshCall } from '@hotmesh/meshcall';
+ *
+ * MeshCall.cron({
+ *   topic: 'my.cron.function',
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+ *   },
+ *   callback: async () => {
+ *     //your code here...anything goes
+ *   },
+ *   options: { id: 'myDailyCron123', interval: '0 0 * * *' }
+ * });
+ * ```
+ */
 class MeshCall {
+    /**
+     * @private
+     */
     constructor() { }
+    /**
+     * iterates cached worker/engine instances to locate the first match
+     * with the provided namespace and connection options
+     * @private
+     */
     static async findFirstMatching(targets, namespace = key_1.HMNS, config, options = {}) {
         for (const [id, hotMeshInstance] of targets) {
             const hotMesh = await hotMeshInstance;
@@ -23,6 +57,9 @@ class MeshCall {
             }
         }
     }
+    /**
+     * @private
+     */
     static async verifyWorkflowActive(hotMesh, appId = key_1.HMNS, count = 0) {
         const app = await hotMesh.engine.store.getApp(appId);
         const appVersion = app?.version;
@@ -35,6 +72,9 @@ class MeshCall {
         }
         return true;
     }
+    /**
+     * @private
+     */
     static async activateWorkflow(hotMesh, appId = key_1.HMNS, version = factory_1.VERSION) {
         const app = await hotMesh.engine.store.getApp(appId);
         const appVersion = app?.version;
@@ -62,6 +102,10 @@ class MeshCall {
             }
         }
     }
+    /**
+     * Returns a cached worker instance or creates a new one
+     * @private
+     */
     static async getInstance(namespace, providerConfig, options = {}) {
         let hotMeshInstance;
         if (!options.readonly) {
@@ -75,11 +119,18 @@ class MeshCall {
         }
         return hotMeshInstance;
     }
+    /**
+     * connection re-use is important when making repeated calls, but
+     * only if the connection options are an exact match. this method
+     * hashes the connection options to ensure that the same connection
+     */
     static hashOptions(connection) {
         if ('options' in connection) {
+            //shorthand format
             return (0, utils_1.hashOptions)(connection.options);
         }
         else {
+            //longhand format (sub, store, stream, pub, search)
             const response = [];
             for (const p in connection) {
                 if (connection[p].options) {
@@ -89,6 +140,25 @@ class MeshCall {
             return response.join('');
         }
     }
+    /**
+     * Connects and links a worker function to the mesh
+     * @example
+     * ```typescript
+     * import { Client as Postgres } from 'pg';
+     * import { MeshCall } from '@hotmesh/meshcall';
+     *
+     * MeshCall.connect({
+     *   topic: 'my.function',
+     *   connection: {
+     *     class: Postgres,
+     *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+     *   },
+     *   callback: async (arg1: any) => {
+     *     //your code here...
+     *   }
+     * });
+     * ```
+     */
     static async connect(params) {
         const targetNamespace = params.namespace ?? key_1.HMNS;
         const optionsHash = MeshCall.hashOptions(utils_1.polyfill.providerConfig(params));
@@ -117,6 +187,23 @@ class MeshCall {
         await MeshCall.activateWorkflow(hotMeshWorker, targetNamespace);
         return hotMeshWorker;
     }
+    /**
+     * Calls a function and returns the response.
+     *
+     * @template U - the return type of the linked worker function
+     *
+     * @example
+     * ```typescript
+     * const response = await MeshCall.exec({
+     *   topic: 'my.function',
+     *   args: [{ my: 'args' }],
+     *   connection: {
+     *     class: Postgres,
+     *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+     *   }
+     * });
+     * ```
+     */
     static async exec(params) {
         const TOPIC = `${params.namespace ?? key_1.HMNS}.call`;
         const hotMeshInstance = await MeshCall.getInstance(params.namespace, utils_1.polyfill.providerConfig(params));
@@ -126,13 +213,16 @@ class MeshCall {
                 await hotMeshInstance.scrub(id);
             }
             else if (params.options?.ttl) {
+                //check cache
                 try {
                     const cached = await hotMeshInstance.getState(TOPIC, id);
                     if (cached) {
+                        //todo: check if present; await if not (subscribe)
                         return cached.data.response;
                     }
                 }
                 catch (error) {
+                    //just swallow error; it means the cache is empty (no doc by that id)
                 }
             }
         }
@@ -146,14 +236,59 @@ class MeshCall {
         const jobOutput = await hotMeshInstance.pubsub(TOPIC, { id, expire, topic: params.topic, args: params.args }, null, 30000);
         return jobOutput?.data?.response;
     }
+    /**
+     * Clears a cached function response.
+     *
+     * @example
+     * ```typescript
+     * import { Client as Postgres } from 'pg';
+     * import { MeshCall } from '@hotmesh/meshcall';
+     *
+     * MeshCall.flush({
+     *   topic: 'my.function',
+     *   connection: {
+     *     class: Postgres,
+     *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+     *   },
+     *   options: { id: 'myCachedExecFunctionId' }
+     * });
+     * ```
+     */
     static async flush(params) {
         const hotMeshInstance = await MeshCall.getInstance(params.namespace, utils_1.polyfill.providerConfig(params));
         await hotMeshInstance.scrub(params.id ?? params?.options?.id);
     }
+    /**
+     * Schedules a cron job to run at a specified interval
+     * with optional args. Provided arguments are passed to the
+     * callback function each time the cron job runs. The `id`
+     * option is used to uniquely identify the cron job, allowing
+     * it to be interrupted at any time.
+     *
+     * @example
+     * ```typescript
+     * import { Client as Postgres } from 'pg';
+     * import { MeshCall } from '@hotmesh/meshcall';
+     *
+     * MeshCall.cron({
+     *   topic: 'my.cron.function',
+     *   args: ['arg1', 'arg2'], //optionally pass args
+     *   connection: {
+     *     class: Postgres,
+     *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+     *   },
+     *   callback: async (arg1: any, arg2: any) => {
+     *     //your code here...
+     *   },
+     *   options: { id: 'myDailyCron123', interval: '0 0 * * *' }
+     * });
+     * ```
+     */
     static async cron(params) {
         let hotMeshInstance;
         let readonly = true;
         if (params.callback) {
+            //always connect cron worker if provided
             hotMeshInstance = await MeshCall.connect({
                 logLevel: params.logLevel,
                 guid: params.guid,
@@ -165,13 +300,19 @@ class MeshCall {
             readonly = false;
         }
         else {
+            //this is a readonly cron connection which means
+            //it is only being created to connect as a readonly member
+            //of the mesh network that the cron is running on. it
+            //can start a job, but it cannot run the job itself in RO mode.
         }
+        //configure job inputs
         const TOPIC = `${params.namespace ?? key_1.HMNS}.cron`;
         const maxCycles = params.options.maxCycles ?? 100000;
         let interval = enums_1.HMSH_FIDELITY_SECONDS;
         let delay;
         let cron;
         if ((0, utils_1.isValidCron)(params.options.interval)) {
+            //cron syntax
             cron = params.options.interval;
             const nextDelay = new cron_1.CronHandler().nextDelay(cron);
             delay = nextDelay > 0 ? nextDelay : undefined;
@@ -183,9 +324,11 @@ class MeshCall {
         }
         try {
             if (!hotMeshInstance) {
+                //get or create a read-only engine instance to start the cron
                 hotMeshInstance = await MeshCall.getInstance(params.namespace, utils_1.polyfill.providerConfig(params), { readonly, guid: params.guid });
                 await MeshCall.createStream(hotMeshInstance, params.topic, params.namespace);
             }
+            //spawn the job (ok if it's a duplicate)
             await hotMeshInstance.pub(TOPIC, {
                 id: params.options.id,
                 topic: params.topic,
@@ -204,16 +347,41 @@ class MeshCall {
             throw error;
         }
     }
+    /**
+     * Interrupts a running cron job. Returns `true` if the job
+     * was successfully interrupted, or `false` if the job was not
+     * found.
+     *
+     * @example
+     * ```typescript
+     * import { Client as Postgres } from 'pg';
+     * import { MeshCall } from '@hotmesh/meshcall';
+     *
+     * MeshCall.interrupt({
+     *   topic: 'my.cron.function',
+     *   connection: {
+     *     class: Postgres,
+     *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+     *   },
+     *   options: { id: 'myDailyCron123' }
+     * });
+     * ```
+     */
     static async interrupt(params) {
         const hotMeshInstance = await MeshCall.getInstance(params.namespace, utils_1.polyfill.providerConfig(params));
         try {
             await hotMeshInstance.interrupt(`${params.namespace ?? key_1.HMNS}.cron`, params.options.id, { throw: false, expire: 1 });
         }
         catch (error) {
+            //job doesn't exist; is already stopped
             return false;
         }
         return true;
     }
+    /**
+     * Shuts down all meshcall instances. Call this method
+     * from the SIGTERM handler in your application.
+     */
     static async shutdown() {
         for (const [_, hotMeshInstance] of MeshCall.workers) {
             (await hotMeshInstance).stop();
@@ -226,10 +394,24 @@ class MeshCall {
 }
 exports.MeshCall = MeshCall;
 _a = MeshCall;
+/**
+ * @private
+ */
 MeshCall.workers = new Map();
+/**
+ * @private
+ */
 MeshCall.engines = new Map();
+/**
+ * @private
+ */
 MeshCall.connections = new Map();
+/**
+ * @private
+ */
 MeshCall.getHotMeshClient = async (namespace, connection, options = {}) => {
+    //namespace isolation requires the connection options to be hashed
+    //as multiple intersecting databases can be used by the same service
     const optionsHash = MeshCall.hashOptions(connection);
     const targetNS = namespace ?? key_1.HMNS;
     const connectionNS = `${optionsHash}.${targetNS}`;
@@ -238,6 +420,7 @@ MeshCall.getHotMeshClient = async (namespace, connection, options = {}) => {
         await _a.verifyWorkflowActive(hotMeshClient, targetNS);
         return hotMeshClient;
     }
+    //create and cache an instance
     const hotMeshClient = hotmesh_1.HotMesh.init({
         guid: options.guid,
         appId: targetNS,
@@ -251,6 +434,12 @@ MeshCall.getHotMeshClient = async (namespace, connection, options = {}) => {
     await _a.activateWorkflow(await hotMeshClient, targetNS);
     return hotMeshClient;
 };
+/**
+ * Creates a stream where messages can be published to ensure there is a
+ * channel in place when the message arrives (a race condition for those
+ * platforms without implicit topic setup).
+ * @private
+ */
 MeshCall.createStream = async (hotMeshClient, workflowTopic, namespace) => {
     const params = { appId: namespace ?? key_1.HMNS, topic: workflowTopic };
     const streamKey = hotMeshClient.engine.store.mintKey(key_1.KeyType.STREAMS, params);
@@ -258,5 +447,6 @@ MeshCall.createStream = async (hotMeshClient, workflowTopic, namespace) => {
         await hotMeshClient.engine.stream.createConsumerGroup(streamKey, 'WORKER');
     }
     catch (err) {
+        //ignore if already exists
     }
 };

package/build/services/meshcall/schemas/factory.d.ts

@@ -1,2 +1,9 @@
 export declare const VERSION = "2";
+/**
+ * Provides the YAML necessary to create a workflow for the `MeshCall` service.
+ * The `appId` parameter is optional and defaults to the HMNS constant ('hmsh').
+ *
+ * The version is a string as it supports semantic versioning. It is also optional
+ * and defaults to '1'.
+ */
 export declare const getWorkflowYAML: (appId?: string, version?: string) => string;

package/build/services/meshcall/schemas/factory.js

@@ -3,6 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getWorkflowYAML = exports.VERSION = void 0;
 const key_1 = require("../../../modules/key");
 exports.VERSION = '2';
+/**
+ * Provides the YAML necessary to create a workflow for the `MeshCall` service.
+ * The `appId` parameter is optional and defaults to the HMNS constant ('hmsh').
+ *
+ * The version is a string as it supports semantic versioning. It is also optional
+ * and defaults to '1'.
+ */
 const getWorkflowYAML = (appId = key_1.HMNS, version = exports.VERSION) => {
     return `app:
   id: ${appId}