@hotmeshio/hotmesh 0.0.24 → 0.0.25

package/README.md

@@ -3,10 +3,7 @@
 
 Elevate Redis from an in-memory data cache to a game-changing [service mesh](https://github.com/hotmeshio/sdk-typescript/blob/main/docs/faq.md#what-is-hotmesh). Turn your unpredictable functions into unbreakable workflows.
 
-## What is HotMesh?
-HotMesh is a wrapper for Redis that exposes a higher level set of domain constructs like ‘activities’, ‘workflows’, 'jobs', etc. Behind the scenes, it uses *Redis Data* (Hash, ZSet, and List); *Redis Streams* (XReadGroup, XAdd, XLen); and *Redis Publish/Subscribe*.
-
-The ultimate goal is to resurface Redis as a *Durable Service Mesh*, capable of running unbreakable workflows that span your microservices. The technical term for this type of durability is *Reentrant Process Engine*.
+HotMesh is a wrapper for Redis that exposes a higher level set of domain constructs like ‘activities’, ‘workflows’, 'jobs', etc. Behind the scenes, it uses *Redis Data* (Hash, ZSet, List); *Redis Streams* (XReadGroup, XAdd, XLen, etc); and *Redis Publish/Subscribe*.
 
 It's still Redis in the background, but the information flow is fundamentally different. Your functions no longer call Redis (e.g., to cache a document) and instead are called by Redis.
 
@@ -20,34 +17,32 @@ npm install @hotmeshio/hotmesh
 ## Design
 The HotMesh SDK is designed to keep your code front-and-center. Write code as you normally would, then use HotMesh to make it durable.
 
-1. Start with any ordinary class. Pay attention to unpredictable functions: those that execute slowly, cause problems at scale, or simply fail to return. *Note how the `saludar` function throws an error 50% of the time. This is exactly the type of function to fix.*
+1. Start with any ordinary class. Pay attention to unpredictable functions: those that execute slowly, cause problems at scale, or simply fail to return. *Note how the `flaky` function throws an error 50% of the time. This is exactly the type of function that can be fixed using HotMesh.*
     ```javascript
     //myworkflow.ts
 
     export class MyWorkflow {
 
-      //main method
       async run(name: string): Promise<string> {
-        const salud = await this.saludar(name);
+        const hi = await this.flaky(name);
         const hello = await this.greet(name);
-        return `${hello} ${salud}`;
+        return `${hi} ${hello}`;
       }
 
-      //this function only succeeds 50% of the time!
-      async saludar(nombre: string): Promise<string> {
+      //this function is unpredictable and will fail 50% of the time
+      async flaky(name: string): Promise<string> {
         if (Math.random() < 0.5) {
-          throw new Error('¡No hablo español!');
+          throw new Error('Ooops!');
         }
-        return `¡Hola, ${nombre}!`;
+        return `Hi, ${name}!`;
       }
 
-      //this function always succeeds
       async greet(name: string): Promise<string> {
         return `Hello, ${name}!`;
       }
     }
     ```
-2. Import `MeshOS` and subclass it as shown. Configure `host`, `port`, etc., and list those functions that should run durably like `run` and `saludar`. Your class is now a durable workflow! *Additional helper methods include `waitForSignal`, `signal`, `hook`, `sleep` (months, years, etc), `executeChild`, `startChild`, `get`, `set`, `incr` (increment), and `mult` (multiply).*
+2. Import `Redis` and `MeshOS` and configure host, port, etc. List those functions that Redis should govern as durable workflows (like `run` and `flaky`). And that's it! *Your functions don't actually change; rather, their governance does.*
     ```javascript
     //myworkflow.ts
 
@@ -63,40 +58,38 @@ The HotMesh SDK is designed to keep your code front-and-center. Write code as yo
       workflowFunctions = ['run'];
 
       //list functions to retry and cache
-      proxyFunctions = ['saludar'];
+      proxyFunctions = ['flaky'];
 
-      //main method (Redis will now govern its execution)
       async run(name: string): Promise<string> {
-        const salud = await this.saludar(name);
+        const hi = await this.flaky(name);
         const hello = await this.greet(name);
-        return `${hello} ${salud}`;
+        return `${hi} ${hello}`;
       }
 
-      //this function will now be retried until it succeeds;
-      async saludar(nombre: string): Promise<string> {
+      //this function is now durable and will be retried until it succeeds!
+      async flaky(name: string): Promise<string> {
         if (Math.random() < 0.5) {
-          throw new Error('¡No hablo español!');
+          throw new Error('Ooops!');
         }
-        return `¡Hola, ${nombre}!`;
+        return `Hi, ${name}!`;
       }
 
-      //this vanilla function is unchanged
       async greet(name: string): Promise<string> {
         return `Hello, ${name}!`;
       }
     }
     ```
-3. Invoke your class, providing a unique GUID (it's now a workflow and it's idempotent). Nothing changes from the outside, *but Redis now governs its end-to-end execution.* It's guaranteed to succeed and return regardless of catastrophic network failure. Redis will simply inflate like a balloon and deflate as things come back online.
+3. Invoke your class, providing a unique id (it's now an idempotent workflow and needs a GUID). Nothing changes from the outside, *but Redis now governs the end-to-end execution.* It's guaranteed to succeed and return regardless of  network or microservice failure. Redis will simply inflate like a balloon and deflate as your services come back online.
     ```javascript
     //mycaller.ts
 
-    //...import MyWorkflow, etc...
-
-    const workflow = new MyWorkflow('unique123', { await: true }); //await the response
+    const workflow = new MyWorkflow({ id: 'my123', await: true });
     const response = await workflow.run('John');
-    //Hello, John! ¡Hola, John!
+    //Hello, John! Hi, John!
     ```
 
+>NOTE: MeshOS provides a full suite of durable workflow methods for extending your functions, including: `waitForSignal`, `signal`, `hook`, `sleep` (months, years, etc), `executeChild`, `startChild`, `get`, `set`, `incr` (increment), and `mult` (multiply).
+
 ## Advanced Design
 HotMesh's TypeScript SDK is the easiest way to make your functions durable. But if you need full control over your function lifecycles (including high-volume, high-speed use cases), you can use HotMesh's underlying YAML models to optimize your durable workflows. The following model depicts a sequence of activities orchestrated by HotMesh. Any function you associate with a `topic` in your YAML definition is guaranteed to be durable.
 

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.0.24",
+    "version": "0.0.25",
     "description": "Unbreakable Workflows",
     "main": "build/index.js",
     "types": "build/index.d.ts",

package/build/services/durable/meshos.d.ts

@@ -1,12 +1,12 @@
 import { WorkflowHandleService } from './handle';
-import { FindOptions, MeshOSActivityOptions, MeshOSOptions, WorkflowSearchOptions } from '../../types/durable';
-import { RedisOptions, RedisClass } from '../../types/redis';
-import { StringAnyType } from '../../types';
 import { WorkflowService } from './workflow';
+import { FindOptions, MeshOSActivityOptions, MeshOSConfig, MeshOSOptions, MeshOSWorkerOptions, WorkflowSearchOptions } from '../../types/durable';
+import { RedisOptions, RedisClass } from '../../types/redis';
+import { StringAnyType } from '../../types/serializer';
 /**
  * The base class for running MeshOS workflows.
- * Extend and register subclass methods by name to
- * execute as durable workflows, backed by Redis.
+ * Extend this class, add your Redis config, and add functions to
+ * execute as durable `hooks`, `workflows`, and `activities`.
  */
 export declare class MeshOSService {
     /**
@@ -78,14 +78,18 @@ export declare class MeshOSService {
      */
     static createIndex(): Promise<void>;
     /**
-     * Initialize the worker(s) for the entity. This is a static
+     * stop the workers
+     * @returns {Promise<void>}
+     */
+    static stopWorkers(): Promise<void>;
+    /**
+     * Initializes the worker(s). This is a static
      * method that allows for optional task Queue targeting.
-     * NOTE: Allow List may be optionally used to only wrap
-     *       specific methods in this class.
-     * @param {string} taskQueue
-     * @param {string[]} allowList
+     * An `allowList` may be optionally provided to start
+     * specific `worker` and `hook` methods.
+     * @param {MeshOSWorkerOptions} [options]
      */
-    static startWorkers(taskQueue?: string, allowList?: Array<MeshOSOptions | string>): Promise<void>;
+    static startWorkers(options?: MeshOSWorkerOptions): Promise<void>;
     /**
      * executes the redis FT search query
      * @example '@_quantity:[89 89]'
@@ -104,5 +108,5 @@ export declare class MeshOSService {
      * Optionally include a target taskQueue to exec the
      * workflow's call on a specific worker queue.
      */
-    constructor(id?: string, options?: Record<string, any>);
+    constructor(id?: string | MeshOSConfig, options?: MeshOSConfig);
 }

package/build/services/durable/meshos.js

@@ -2,16 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MeshOSService = void 0;
 const nanoid_1 = require("nanoid");
+const _1 = require(".");
+const asyncLocalStorage_1 = require("./asyncLocalStorage");
 const client_1 = require("./client");
 const search_1 = require("./search");
 const worker_1 = require("./worker");
-const _1 = require(".");
-const asyncLocalStorage_1 = require("./asyncLocalStorage");
 const workflow_1 = require("./workflow");
+const stream_1 = require("../signaler/stream");
 /**
  * The base class for running MeshOS workflows.
- * Extend and register subclass methods by name to
- * execute as durable workflows, backed by Redis.
+ * Extend this class, add your Redis config, and add functions to
+ * execute as durable `hooks`, `workflows`, and `activities`.
  */
 class MeshOSService {
     static async getHotMeshClient(redisClass, redisOptions, namespace, taskQueue) {
@@ -42,14 +43,24 @@ class MeshOSService {
         search_1.Search.configureSearchIndex(hmClient, my.search);
     }
     /**
-     * Initialize the worker(s) for the entity. This is a static
+     * stop the workers
+     * @returns {Promise<void>}
+     */
+    static async stopWorkers() {
+        await _1.Durable.Client.shutdown();
+        await _1.Durable.Worker.shutdown();
+        await stream_1.StreamSignaler.stopConsuming();
+    }
+    /**
+     * Initializes the worker(s). This is a static
      * method that allows for optional task Queue targeting.
-     * NOTE: Allow List may be optionally used to only wrap
-     *       specific methods in this class.
-     * @param {string} taskQueue
-     * @param {string[]} allowList
+     * An `allowList` may be optionally provided to start
+     * specific `worker` and `hook` methods.
+     * @param {MeshOSWorkerOptions} [options]
      */
-    static async startWorkers(taskQueue, allowList = []) {
+    static async startWorkers(options) {
+        const taskQueue = options && options.taskQueue;
+        const allowList = options && options.allowList || [];
         const my = new this();
         //helper functions
         const resolveFunctionNames = (arr) => arr.map(item => typeof item === 'string' ? item : item.name);
@@ -74,8 +85,6 @@ class MeshOSService {
             const proxiedActivities = _1.Durable.workflow.proxyActivities({
                 activities: proxyActivities
             });
-            //WATCH!: unsure if this will pollute the scope; don't think
-            //      so as activity functions are terminal in the chain.
             Object.assign(my, proxiedActivities);
         }
         const functionsToIterate = allowList.length ? resolveFunctionNames(allowList) : resolveFunctionNames([...my.workflowFunctions, ...my.hookFunctions]);
@@ -224,7 +233,15 @@ class MeshOSService {
             password: '',
             db: 0,
         };
-        this.id = id;
+        if (typeof (id) === 'string') {
+            this.id = id;
+        }
+        else if (id?.id) {
+            this.id = id.id;
+            options = id;
+            id = undefined;
+        }
+        ;
         if (options?.taskQueue) {
             this.taskQueue = options.taskQueue;
         }

package/build/services/store/clients/redis.js

@@ -33,8 +33,7 @@ class RedisStoreService extends index_1.StoreService {
         };
     }
     getMulti() {
-        const multi = this.redisClient.MULTI();
-        return multi;
+        return this.redisClient.multi();
     }
     async exec(...args) {
         return await this.redisClient.sendCommand(args);

package/build/services/stream/clients/redis.js

@@ -13,7 +13,7 @@ class RedisStreamService extends index_1.StreamService {
         this.appId = appId;
     }
     getMulti() {
-        return this.redisClient.MULTI();
+        return this.redisClient.multi();
     }
     mintKey(type, params) {
         if (!this.namespace)

package/build/services/sub/clients/redis.js

@@ -13,7 +13,7 @@ class RedisSubService extends index_1.SubService {
         this.appId = appId;
     }
     getMulti() {
-        const multi = this.redisClient.MULTI();
+        const multi = this.redisClient.multi();
         return multi;
     }
     mintKey(type, params) {

package/build/types/durable.d.ts

@@ -59,15 +59,9 @@ type MeshOSClassConfig = {
     redisClass: RedisClass;
 };
 type MeshOSConfig = {
+    id?: string;
+    await?: boolean;
     taskQueue?: string;
-    index?: {
-        index: string;
-        prefix: string[];
-        schema: Record<string, {
-            type: 'TEXT' | 'NUMERIC' | 'TAG';
-            sortable: boolean;
-        }>;
-    };
 };
 type ConnectionConfig = {
     class: RedisClass;
@@ -102,6 +96,13 @@ type MeshOSActivityOptions = {
     name: string;
     options: ActivityConfig;
 };
+type MeshOSWorkerOptions = {
+    taskQueue?: string;
+    allowList?: Array<MeshOSOptions | string>;
+    logLevel?: string;
+    maxSystemRetries?: number;
+    backoffCoefficient?: number;
+};
 type WorkerOptions = {
     logLevel?: string;
     maxSystemRetries?: number;
@@ -125,4 +126,4 @@ type ActivityConfig = {
         maximumInterval: string;
     };
 };
-export { ActivityConfig, ActivityWorkflowDataType, ClientConfig, ContextType, ConnectionConfig, Connection, ProxyType, Registry, SignalOptions, FindOptions, HookOptions, MeshOSActivityOptions, MeshOSClassConfig, MeshOSConfig, MeshOSOptions, WorkerConfig, WorkflowConfig, WorkerOptions, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, };
+export { ActivityConfig, ActivityWorkflowDataType, ClientConfig, ContextType, ConnectionConfig, Connection, ProxyType, Registry, SignalOptions, FindOptions, HookOptions, MeshOSActivityOptions, MeshOSWorkerOptions, MeshOSClassConfig, MeshOSConfig, MeshOSOptions, WorkerConfig, WorkflowConfig, WorkerOptions, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, };

package/build/types/index.d.ts

@@ -3,7 +3,7 @@ export { App, AppVID, AppTransitions, AppSubscriptions } from './app';
 export { AsyncSignal } from './async';
 export { CacheMode } from './cache';
 export { CollationFaultType, CollationStage } from './collator';
-export { ActivityConfig, ActivityWorkflowDataType, ClientConfig, ContextType, ConnectionConfig, Connection, ProxyType, Registry, SignalOptions, FindOptions, HookOptions, MeshOSActivityOptions, MeshOSClassConfig, MeshOSConfig, MeshOSOptions, WorkflowConfig, WorkerConfig, WorkerOptions, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, } from './durable';
+export { ActivityConfig, ActivityWorkflowDataType, ClientConfig, ContextType, ConnectionConfig, Connection, ProxyType, Registry, SignalOptions, FindOptions, HookOptions, MeshOSActivityOptions, MeshOSWorkerOptions, MeshOSClassConfig, MeshOSConfig, MeshOSOptions, WorkflowConfig, WorkerConfig, WorkerOptions, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, } from './durable';
 export { HookCondition, HookConditions, HookGate, HookInterface, HookRule, HookRules, HookSignal } from './hook';
 export { RedisClientType as IORedisClientType, RedisMultiType as IORedisMultiType } from './ioredisclient';
 export { ILogger } from './logger';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "Unbreakable Workflows",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/services/durable/meshos.ts

@@ -1,20 +1,27 @@
 import { nanoid } from 'nanoid';
 
+import { Durable } from '.';
+import { asyncLocalStorage } from './asyncLocalStorage';
 import { ClientService as Client } from './client';
 import { WorkflowHandleService } from './handle';
 import { Search } from './search';
 import { WorkerService as Worker } from './worker';
-import { FindOptions, MeshOSActivityOptions, MeshOSOptions, WorkflowSearchOptions } from '../../types/durable';
-import { RedisOptions, RedisClass } from '../../types/redis';
-import { StringAnyType } from '../../types';
-import { Durable } from '.';
-import { asyncLocalStorage } from './asyncLocalStorage';
 import { WorkflowService } from './workflow';
+import { StreamSignaler } from '../signaler/stream';
+import {
+  FindOptions,
+  MeshOSActivityOptions,
+  MeshOSConfig,
+  MeshOSOptions,
+  MeshOSWorkerOptions,
+  WorkflowSearchOptions } from '../../types/durable';
+import { RedisOptions, RedisClass } from '../../types/redis';
+import { StringAnyType } from '../../types/serializer';
 
 /**
  * The base class for running MeshOS workflows.
- * Extend and register subclass methods by name to
- * execute as durable workflows, backed by Redis.
+ * Extend this class, add your Redis config, and add functions to
+ * execute as durable `hooks`, `workflows`, and `activities`.
  */
 
 export class MeshOSService {
@@ -122,14 +129,25 @@ export class MeshOSService {
   }
 
   /**
-   * Initialize the worker(s) for the entity. This is a static
+   * stop the workers
+   * @returns {Promise<void>}
+   */
+  static async stopWorkers(): Promise<void> {
+    await Durable.Client.shutdown();
+    await Durable.Worker.shutdown();
+    await StreamSignaler.stopConsuming();
+  }
+
+  /**
+   * Initializes the worker(s). This is a static
    * method that allows for optional task Queue targeting.
-   * NOTE: Allow List may be optionally used to only wrap
-   *       specific methods in this class. 
-   * @param {string} taskQueue 
-   * @param {string[]} allowList 
+   * An `allowList` may be optionally provided to start
+   * specific `worker` and `hook` methods. 
+   * @param {MeshOSWorkerOptions} [options]
    */
-  static async startWorkers(taskQueue?: string, allowList: Array<MeshOSOptions | string> = []) {
+  static async startWorkers(options?: MeshOSWorkerOptions) {
+    const taskQueue = options && options.taskQueue;
+    const allowList = options && options.allowList || [];
     const my = new this();
 
     //helper functions
@@ -156,8 +174,6 @@ export class MeshOSService {
       const proxiedActivities = Durable.workflow.proxyActivities({
         activities: proxyActivities
       });
-      //WATCH!: unsure if this will pollute the scope; don't think
-      //      so as activity functions are terminal in the chain.
       Object.assign(my, proxiedActivities);
     }
 
@@ -281,8 +297,14 @@ export class MeshOSService {
    * Optionally include a target taskQueue to exec the
    * workflow's call on a specific worker queue.
    */
-  constructor(id?: string, options?: Record<string, any>) {
-    this.id = id;
+  constructor(id?: string | MeshOSConfig, options?: MeshOSConfig) {
+    if (typeof(id) === 'string') {
+      this.id = id;
+    } else if (id?.id) {
+      this.id = id.id;
+      options = id;
+      id = undefined;
+    };
     if (options?.taskQueue) {
       this.taskQueue = options.taskQueue;
     } else if (!id && !options?.taskQueue) {

package/services/store/clients/redis.ts

@@ -46,8 +46,7 @@ class RedisStoreService extends StoreService<RedisClientType, RedisMultiType> {
   }
 
   getMulti(): RedisMultiType {
-    const multi = this.redisClient.MULTI();
-    return multi as unknown as RedisMultiType;
+    return this.redisClient.multi() as unknown as RedisMultiType;
   }
 
   async exec(...args: any[]): Promise<string|string[]|string[][]> {

package/services/stream/clients/redis.ts

@@ -21,7 +21,7 @@ class RedisStreamService extends StreamService<RedisClientType, RedisMultiType>
   }
 
   getMulti(): RedisMultiType {
-    return this.redisClient.MULTI() as unknown as RedisMultiType;
+    return this.redisClient.multi() as unknown as RedisMultiType;
   }
 
   mintKey(type: KeyType, params: KeyStoreParams): string {

package/services/sub/clients/redis.ts

@@ -21,7 +21,7 @@ class RedisSubService extends SubService<RedisClientType, RedisMultiType> {
   }
 
   getMulti(): RedisMultiType {
-    const multi = this.redisClient.MULTI();
+    const multi = this.redisClient.multi();
     return multi as unknown as RedisMultiType;
   }
 

package/types/durable.ts

@@ -65,12 +65,9 @@ type MeshOSClassConfig = {
 }
 
 type MeshOSConfig = {
-  taskQueue?: string;
-  index?: {
-    index: string;
-    prefix: string[];
-    schema: Record<string, {type: 'TEXT' | 'NUMERIC' | 'TAG', sortable: boolean}>;
-  };
+  id?: string; //guid for the workflow when instancing
+  await?: boolean; //default is false; must explicitly send true to await the final result
+  taskQueue?: string; //optional target queue isolate for the function
 }
 
 type ConnectionConfig = {
@@ -113,6 +110,14 @@ type MeshOSActivityOptions = {
   options: ActivityConfig;
 }
 
+type MeshOSWorkerOptions = {
+  taskQueue?: string; //change the default task queue
+  allowList?: Array<MeshOSOptions | string>; //limit which `hook` and `workflow` workers start
+  logLevel?: string; //debug, info, warn, error
+  maxSystemRetries?: number; //1-3 (10ms, 100ms, 1_000ms)
+  backoffCoefficient?: number; //2-10ish
+}
+
 type WorkerOptions = {
   logLevel?: string; //debug, info, warn, error
   maxSystemRetries?: number; //1-3 (10ms, 100ms, 1_000ms)
@@ -153,6 +158,7 @@ export {
   FindOptions,
   HookOptions,
   MeshOSActivityOptions,
+  MeshOSWorkerOptions,
   MeshOSClassConfig,
   MeshOSConfig,
   MeshOSOptions,

package/types/index.ts

@@ -40,6 +40,7 @@ export {
     FindOptions,
     HookOptions,
     MeshOSActivityOptions,
+    MeshOSWorkerOptions,
     MeshOSClassConfig,
     MeshOSConfig,
     MeshOSOptions,
@@ -49,7 +50,7 @@ export {
     WorkflowSearchOptions,
     WorkflowDataType,
     WorkflowOptions,
-  }from './durable'
+  } from './durable'
 export {
   HookCondition,
   HookConditions,