@hotmeshio/hotmesh 0.2.2 → 0.2.3

package/README.md

@@ -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>

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.2",
+    "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.2",
+  "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;
 };