@hotmeshio/hotmesh 0.2.1 → 0.2.3

package/README.md

@@ -9,8 +9,8 @@ npm install @hotmeshio/hotmesh
 ```
 You have a Redis instance? Good. You're ready to go.
 
-## SDK Docs
-[Read the Docs](https://hotmeshio.github.io/sdk-typescript/)
+## Learn
+[SDK Docs](https://hotmeshio.github.io/sdk-typescript/) | [Samples](https://github.com/hotmeshio/samples-typescript) | [Intro Video](https://www.loom.com/share/211bd4b4038d42f0ba34374ef5b6f961?sid=7b889a56-f60f-4ccc-84e7-8c2697e548a9)
 
 ## MeshCall | Connect Everything
 [MeshCall](https://hotmeshio.github.io/sdk-typescript/classes/services_meshcall.MeshCall.html) connects your functions to the Redis-backed mesh, exposing them as idempotent endpoints. Function responses are cacheable and functions can even run as idempotent cron jobs. Make blazing fast interservice calls that return in milliseconds without the overhead of HTTP.
@@ -19,9 +19,9 @@ You have a Redis instance? Good. You're ready to go.
   <summary style="font-size:1.25em;">Run an idempotent cron job</summary>
 
   ### Run a Cron
-  This example demonstrates an *idempotent* cron that runs every day. The `id` makes each cron job unique and ensures that only one instance runs, despite repeated invocations. *The `cron` method returns `false` if a workflow is already running with the same `id`.*
+  This example demonstrates an *idempotent* cron that runs daily at midnight. The `id` makes each cron job unique and ensures that only one instance runs, despite repeated invocations. *The `cron` method returns `false` if a workflow is already running with the same `id`.*
   
-  Optionally set a `delay` and/or set `maxCycles` to limit the number of cycles.
+  Optionally set a `delay` and/or set `maxCycles` to limit the number of cycles. The `interval` can be any human-readable time format (e.g., `1 day`, `2 hours`, `30 minutes`, etc) or a standard cron expression.
 
 1. Define the cron function.
     ```typescript
@@ -29,7 +29,7 @@ You have a Redis instance? Good. You're ready to go.
     import { MeshCall } from '@hotmeshio/hotmesh';
     import * as Redis from 'redis';
 
-    export const runMyCron = async (id: string, interval = '1 day'): Promise<boolean> => {
+    export const runMyCron = async (id: string, interval = '0 0 * * *'): Promise<boolean> => {
       return await MeshCall.cron({
         topic: 'my.cron.function',
         redis: {
@@ -48,7 +48,8 @@ You have a Redis instance? Good. You're ready to go.
     ```typescript
     //server.ts
     import { runMyCron } from './cron';
-    runMyCron('myDailyCron123');
+
+    runMyCron('myNightlyCron123');
     ```
 </details>
 
@@ -69,7 +70,7 @@ You have a Redis instance? Good. You're ready to go.
         class: Redis,
         options: { url: 'redis://:key_admin@redis:6379' }
       },
-      options: { id: 'myDailyCron123' }
+      options: { id: 'myNightlyCron123' }
     });
     ```
 </details>
@@ -694,9 +695,7 @@ HotMesh's telemetry output provides unmatched insight into long-running, multi-s
 <img src="./docs/img/visualize/opentelemetry.png" alt="Open Telemetry" style="width:600px;max-width:600px;">
 
 ## Visualize | HotMesh Dashboard
-The HotMesh dashboard provides a detailed overview of all running workflows. As HotMesh is a service mesh, it's also possible to throttle and pause workers and engines attached to the mesh. Redis will simply inflate like a balloon until the throttle is removed and ingestion is resumed.
-
-An LLM is included to simplify querying and analyzing workflow data for those deployments that include the Redis `FT.SEARCH` module.
+The HotMesh dashboard provides a detailed overview of all running workflows. An LLM is included to simplify querying and analyzing workflow data for those deployments that include the Redis `FT.SEARCH` module.
 
 <img src="./docs/img/visualize/hotmesh_dashboard.png" alt="HotMesh Dashboard" style="width:600px;max-width:600px;">
 
@@ -705,35 +704,8 @@ View commands, streams, data, CPU, load, etc using the RedisInsight data browser
 
 <img src="./docs/img/visualize/redisinsight.png" alt="Redis Insight" style="width:600px;max-width:600px;">
 
-## HotMesh
-The *MeshData*, *MeshCall*, and *MeshFlow* modules are all created using the HotMesh modeling system. Refer to the following documents to better understand the platform and how it delivers workflow orchestration without a central application server. 
-
-### FAQ
-Refer to the [FAQ](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/faq.md) for terminology, definitions, and an exploration of how HotMesh facilitates orchestration use cases.
-
-### Quick Start
-Refer to the [Quick Start](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/quickstart.md) for sample YAML workflows you can copy, paste, and modify to get started with HotMesh.
-
-### Developer Guide
-For more details on the complete development process, including information about schemas, APIs, and deployment, consult the [Developer Guide](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/developer_guide.md).
-
-### Model Driven Development
-[Model Driven Development](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/model_driven_development.md) is an established strategy for managing process-oriented tasks. Check out this guide to understand its foundational principles.
-
-### Data Mapping
-Exchanging data between activities is central to HotMesh. For detailed information on supported functions and the functional mapping syntax (@pipes), see the [Data Mapping Overview](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/data_mapping.md).
-
-### Composition
-While the simplest graphs are linear, detailing a consistent sequence of non-cyclical activities, graphs can be layered to represent intricate business scenarios. Some can even be designed to accommodate long-lasting workflows that span months. For more details, check out the [Composable Workflow Guide](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/composable_workflow.md).
-
-### System Lifecycle
-Gain insight into HotMesh's monitoring, exception handling, and alarm configurations via the [System Lifecycle Guide](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/system_lifecycle.md).
-
-### Distributed Orchestration | System Overview
-HotMesh is a distributed orchestration engine. Refer to the [Distributed Orchestration Guide](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/distributed_orchestration.md) for a high-level overview of the approach.
-
-### Distributed Orchestration | System Design
-HotMesh is more than Redis and TypeScript. The theory that underlies the architecture is applicable to any number of data storage and streaming backends: [A Message-Oriented Approach to Decentralized Process Orchestration](https://zenodo.org/records/12168558).
+## Samples
+Refer to the [hotmeshio/samples-typescript](https://github.com/hotmeshio/samples-typescript) Git repo for *tutorials* and instructions on deploying the *HotMesh Dashboard*.
 
-### Samples
-Refer to the [hotmeshio/samples-javascript](https://github.com/hotmeshio/samples-javascript) repo for usage examples.
+## Advanced
+For more advanced topics, including details on the underlying modeling and design system (HotMesh) refer to the [Advanced README](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/advanced.md).

package/build/modules/utils.d.ts

@@ -35,3 +35,4 @@ export declare function getValueByPath(obj: {
     [key: string]: any;
 }, path: string): any;
 export declare function restoreHierarchy(obj: StringAnyType): StringAnyType;
+export declare function isValidCron(cronExpression: string): boolean;

package/build/modules/utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.restoreHierarchy = exports.getValueByPath = exports.getIndexedHash = exports.getSymVal = exports.getSymKey = exports.formatISODate = exports.getTimeSeries = exports.getSubscriptionTopic = exports.findSubscriptionForTrigger = exports.findTopKey = exports.matchesStatus = exports.matchesStatusCode = exports.identifyRedisTypeFromClass = exports.polyfill = exports.identifyRedisType = exports.XSleepFor = exports.sleepImmediate = exports.sleepFor = exports.guid = exports.deterministicRandom = exports.deepCopy = exports.getSystemHealth = exports.hashOptions = void 0;
+exports.isValidCron = exports.restoreHierarchy = exports.getValueByPath = exports.getIndexedHash = exports.getSymVal = exports.getSymKey = exports.formatISODate = exports.getTimeSeries = exports.getSubscriptionTopic = exports.findSubscriptionForTrigger = exports.findTopKey = exports.matchesStatus = exports.matchesStatusCode = exports.identifyRedisTypeFromClass = exports.polyfill = exports.identifyRedisType = exports.XSleepFor = exports.sleepImmediate = exports.sleepFor = exports.guid = exports.deterministicRandom = exports.deepCopy = exports.getSystemHealth = exports.hashOptions = void 0;
 const os_1 = __importDefault(require("os"));
 const crypto_1 = require("crypto");
 const nanoid_1 = require("nanoid");
@@ -239,3 +239,8 @@ function restoreHierarchy(obj) {
     return result;
 }
 exports.restoreHierarchy = restoreHierarchy;
+function isValidCron(cronExpression) {
+    const cronRegex = /^(\*|([0-5]?\d)) (\*|([01]?\d|2[0-3])) (\*|([12]?\d|3[01])) (\*|([1-9]|1[0-2])) (\*|([0-6](?:-[0-6])?(?:,[0-6])?))$/;
+    return cronRegex.test(cronExpression);
+}
+exports.isValidCron = isValidCron;

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.2.1",
+    "version": "0.2.3",
     "description": "Unbreakable Workflows",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -83,6 +83,7 @@
     "dependencies": {
         "@apidevtools/json-schema-ref-parser": "^10.1.0",
         "@opentelemetry/api": "^1.4.1",
+        "cron-parser": "^4.9.0",
         "js-yaml": "^4.1.0",
         "ms": "^2.1.3",
         "nanoid": "^3.3.6",

package/build/services/meshcall/index.js

@@ -10,6 +10,7 @@ const hotmesh_1 = require("../hotmesh");
 const enums_1 = require("../../modules/enums");
 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");
 class MeshCall {
     constructor() { }
@@ -34,7 +35,7 @@ class MeshCall {
         }
         return true;
     }
-    static async activateWorkflow(hotMesh, appId = key_1.HMNS, version = '1') {
+    static async activateWorkflow(hotMesh, appId = key_1.HMNS, version = factory_1.VERSION) {
         const app = await hotMesh.engine.store.getApp(appId);
         const appVersion = app?.version;
         if (appVersion === version && !app.active) {
@@ -140,10 +141,19 @@ class MeshCall {
                 namespace: params.namespace,
             });
             const TOPIC = `${params.namespace ?? key_1.HMNS}.cron`;
-            const interval = (0, ms_1.default)(params.options.interval) / 1000;
-            const delay = params.options.delay
+            let delay = params.options.delay
                 ? (0, ms_1.default)(params.options.delay) / 1000
                 : undefined;
+            let cron;
+            let interval = enums_1.HMSH_FIDELITY_SECONDS;
+            if ((0, utils_1.isValidCron)(params.options.interval)) {
+                cron = params.options.interval;
+                delay = Math.max(new cron_1.CronHandler().nextDelay(cron), 0);
+            }
+            else {
+                const seconds = (0, ms_1.default)(params.options.interval) / 1000;
+                interval = Math.max(seconds, enums_1.HMSH_FIDELITY_SECONDS);
+            }
             const maxCycles = params.options.maxCycles ?? 1000000;
             const hotMeshInstance = await MeshCall.getInstance(params.namespace, params.redis);
             await hotMeshInstance.pub(TOPIC, {
@@ -151,6 +161,7 @@ class MeshCall {
                 topic: params.topic,
                 args: params.args,
                 interval,
+                cron,
                 maxCycles,
                 delay,
             });

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

@@ -1,2 +1,2 @@
-export declare const VERSION = "1";
+export declare const VERSION = "2";
 export declare const getWorkflowYAML: (appId?: string, version?: string) => string;

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

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getWorkflowYAML = exports.VERSION = void 0;
 const key_1 = require("../../../modules/key");
-exports.VERSION = '1';
+exports.VERSION = '2';
 const getWorkflowYAML = (appId = key_1.HMNS, version = exports.VERSION) => {
     return `app:
   id: ${appId}
@@ -86,7 +86,10 @@ const getWorkflowYAML = (appId = key_1.HMNS, version = exports.VERSION) => {
               description: time in seconds to sleep before invoking the first cycle
             interval:
               type: number
-              description: time in seconds to sleep before the next cycle
+              description: time in seconds to sleep before the next cycle (also min interval in seconds if cron is provided)
+            cron:
+              type: string
+              description: cron expression to determine the next cycle (takes precedence over interval)
             topic:
               type: string
               description: topic assigned to locate the worker
@@ -148,7 +151,11 @@ const getWorkflowYAML = (appId = key_1.HMNS, version = exports.VERSION) => {
           ancestor: cycle_hook_cron
           input:
             maps:
-              sleepSeconds: '{trigger_cron.output.data.interval}'
+              sleepSeconds:
+                '@pipe':
+                  - ['{trigger_cron.output.data.cron}']
+                  - ['{@cron.nextDelay}', '{trigger_cron.output.data.interval}']
+                  - ['{@math.max}']
               iterationCount:
                 '@pipe':
                   - ['{cycle_hook_cron.output.data.iterationCount}', 1]

package/build/services/pipe/functions/cron.d.ts

@@ -0,0 +1,4 @@
+declare class CronHandler {
+    nextDelay(cronExpression: string): number;
+}
+export { CronHandler };

package/build/services/pipe/functions/cron.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CronHandler = void 0;
+const cron_parser_1 = require("cron-parser");
+const enums_1 = require("../../../modules/enums");
+const utils_1 = require("../../../modules/utils");
+class CronHandler {
+    nextDelay(cronExpression) {
+        try {
+            if (!(0, utils_1.isValidCron)(cronExpression)) {
+                return -1;
+            }
+            const interval = (0, cron_parser_1.parseExpression)(cronExpression, { utc: true });
+            const nextDate = interval.next().toDate();
+            const now = new Date();
+            const delay = (nextDate.getTime() - now.getTime()) / 1000;
+            if (delay <= 0) {
+                return -1;
+            }
+            if (delay < enums_1.HMSH_FIDELITY_SECONDS) {
+                return enums_1.HMSH_FIDELITY_SECONDS;
+            }
+            const iDelay = Math.round(delay);
+            return iDelay;
+        }
+        catch (error) {
+            console.error('Error calculating next cron job execution  delay:', error);
+            return -1;
+        }
+    }
+}
+exports.CronHandler = CronHandler;

package/build/services/pipe/functions/index.d.ts

@@ -1,6 +1,7 @@
 import { ArrayHandler } from './array';
 import { BitwiseHandler } from './bitwise';
 import { ConditionalHandler } from './conditional';
+import { CronHandler } from './cron';
 import { DateHandler } from './date';
 import { JsonHandler } from './json';
 import { LogicalHandler } from './logical';
@@ -14,6 +15,7 @@ declare const _default: {
     array: ArrayHandler;
     bitwise: BitwiseHandler;
     conditional: ConditionalHandler;
+    cron: CronHandler;
     date: DateHandler;
     json: JsonHandler;
     logical: LogicalHandler;

package/build/services/pipe/functions/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const array_1 = require("./array");
 const bitwise_1 = require("./bitwise");
 const conditional_1 = require("./conditional");
+const cron_1 = require("./cron");
 const date_1 = require("./date");
 const json_1 = require("./json");
 const logical_1 = require("./logical");
@@ -16,6 +17,7 @@ exports.default = {
     array: new array_1.ArrayHandler(),
     bitwise: new bitwise_1.BitwiseHandler(),
     conditional: new conditional_1.ConditionalHandler(),
+    cron: new cron_1.CronHandler(),
     date: new date_1.DateHandler(),
     json: new json_1.JsonHandler(),
     logical: new logical_1.LogicalHandler(),

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

@@ -26,6 +26,7 @@ declare class Router {
     innerPromiseResolve: (() => void) | null;
     isSleeping: boolean;
     sleepTimout: NodeJS.Timeout | null;
+    readonly: boolean;
     constructor(config: StreamConfig, stream: StreamService<RedisClient, RedisMulti>, store: StoreService<RedisClient, RedisMulti>, logger: ILogger);
     private resetThrottleState;
     createGroup(stream: string, group: string): Promise<void>;

package/build/services/router/index.js

@@ -26,6 +26,7 @@ class Router {
         this.reclaimDelay = config.reclaimDelay || enums_1.HMSH_XCLAIM_DELAY_MS;
         this.reclaimCount = config.reclaimCount || enums_1.HMSH_XCLAIM_COUNT;
         this.logger = logger;
+        this.readonly = config.readonly || false;
         this.resetThrottleState();
     }
     resetThrottleState() {
@@ -73,6 +74,8 @@ class Router {
         });
     }
     async consumeMessages(stream, group, consumer, callback) {
+        if (this.readonly)
+            return;
         this.logger.info(`router-stream-starting`, { group, consumer, stream });
         Router.instances.add(this);
         this.shouldConsume = true;

package/build/types/hotmesh.d.ts

@@ -50,6 +50,7 @@ type HotMeshEngine = {
     redis?: RedisConfig;
     reclaimDelay?: number;
     reclaimCount?: number;
+    readonly?: boolean;
 };
 type HotMeshWorker = {
     topic: string;

package/build/types/stream.d.ts

@@ -71,4 +71,5 @@ export type StreamConfig = {
     topic?: string;
     reclaimDelay?: number;
     reclaimCount?: number;
+    readonly?: boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Unbreakable Workflows",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -83,6 +83,7 @@
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^10.1.0",
     "@opentelemetry/api": "^1.4.1",
+    "cron-parser": "^4.9.0",
     "js-yaml": "^4.1.0",
     "ms": "^2.1.3",
     "nanoid": "^3.3.6",

package/types/hotmesh.ts

@@ -62,6 +62,7 @@ type HotMeshEngine = {
   redis?: RedisConfig;
   reclaimDelay?: number; //milliseconds
   reclaimCount?: number;
+  readonly?: boolean; //if true, the engine will not route stream messages
 };
 
 type HotMeshWorker = {

package/types/meshcall.ts

@@ -102,6 +102,7 @@ interface MeshCallCronOptions {
   /**
    * For example, `1 day`, `1 hour`. Fidelity is generally
    * within 5 seconds. Refer to the syntax for the `ms` NPM package.
+   * Standard cron syntax is also supported. (e.g. `0 0 * * *`)
    */
   interval: string;
   /**
@@ -112,6 +113,7 @@ interface MeshCallCronOptions {
    * Time in seconds to sleep before invoking the first cycle.
    * For example, `1 day`, `1 hour`. Fidelity is generally
    * within 5 seconds. Refer to the syntax for the `ms` NPM package.
+   * If the interval field uses standard cron syntax, this field is ignored.
    */
   delay?: string;
 }

package/types/stream.ts

@@ -138,4 +138,6 @@ export type StreamConfig = {
   reclaimDelay?: number;
   /** Maximum number of reclaims allowed, defaults to 3. Values greater throw an error */
   reclaimCount?: number;
+  /** if true, will not process stream messages; default true */
+  readonly?: boolean;
 };