@hotmeshio/hotmesh 0.0.9 → 0.0.10

package/README.md

@@ -1,7 +1,7 @@
 # HotMesh
 ![alpha release](https://img.shields.io/badge/release-alpha-yellow)
 
-Elevate Redis from an in-memory data store to a game-changing **service mesh**, delivering *durable* workflows without the overhead of a dedicated control plane. With HotMesh, you can keep your code at the forefront, utilizing [Redis infrastructure](https://github.com/hotmeshio/sdk-typescript/blob/main/docs/faq.md#what-is-hotmesh) you already trust and own.
+Elevate Redis from an in-memory data store 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.
 
 ## Install
 [![npm version](https://badge.fury.io/js/%40hotmeshio%2Fhotmesh.svg)](https://badge.fury.io/js/%40hotmeshio%2Fhotmesh)
@@ -11,85 +11,91 @@ npm install @hotmeshio/hotmesh
 ```
 
 ## Design
-HotMesh's TypeScript SDK is modeled after Temporal IO's developer-friendly approach. Design and deploy durable workflows using your preferred coding style. Write your functions as you normally would, then use the HotMesh to make them durable. Temporal's [hello-world tutorial](https://github.com/temporalio/samples-typescript/tree/main/hello-world/src), for example, requires few changes beyond importing the HotMesh SDK.
+The HotMesh SDK is designed to keep your code front-and-center. Write functions as you normally would, then use the HotMesh to make them durable.
 
->Start by defining activities. These are the functions that will be invoked by your workflow. They can be written in any style, using any framework, and can even be legacy functions you've already written. The only requirement is that they return a Promise.
+1. Start by defining **activities**. Activities are those functions that will be invoked by your workflow. They are commonly used to read and write to databases and invoke external services. They can be written in any style, using any framework, and can even be legacy functions you've already written. The only requirement is that they return a Promise.
+    ```javascript
+    //activities.ts
 
-**./activities.ts**
-```javascript
-export async function greet(name: string): Promise<string> {
-  return `Hello, ${name}!`;
-}
-```
-
->Next, define your workflow. Include conditional logic, loops, etc. It's vanilla code written in your own coding style--just make sure to call `proxyActivities` to run your activities durably.
-
-**./workflows.ts**
-```javascript
-import { Durable } from '@hotmeshio/hotmesh';
-import * as activities from './activities';
-
-const { greet } = Durable.workflow
-  .proxyActivities<typeof activities>({
-    activities
-  });
-
-export async function example(name: string): Promise<string> {
-  return await greet(name);
-}
-```
-
->Finally, create a worker and client. The *client* triggers workflows, while the *worker* runs them, retrying as necessary until the workflow succeeds--all without the need for complicated retry logic.
-
-**./client.ts**
-```javascript
-import { Durable } from '@hotmeshio/hotmesh';
-import Redis from 'ioredis'; //OR `import * as Redis from 'redis';`
-import { v4 as uuidv4 } from 'uuid';
-
-async function run() {
-  const connection = await Durable.Connection.connect({
-    class: Redis,
-    options: { host: 'localhost', port: 6379 }
-  });
-
-  const client = new Durable.Client({
-    connection
-  });
-
-  const handle = await client.workflow.start({
-    args: ['HotMesh'],
-    taskQueue: 'hello-world',
-    workflowName: 'example',
-    workflowId: 'workflow-' + uuidv4()
-  });
-
-  console.log(await handle.result());
-}
-```
+    export async function greet(name: string): Promise<string> {
+      return `Hello, ${name}!`;
+    }
 
-**./worker.ts**
-```javascript
-import { Durable } from '@hotmeshio/hotmesh';
-import Redis from 'ioredis';
-import * as workflows from './workflows';
-
-async function run() {
-  const connection = await Durable.NativeConnection.connect({
-    class: Redis,
-    options: { host: 'localhost', port: 6379 },
-  });
-  const worker = await Durable.Worker.create({
-    connection,
-    namespace: 'default',
-    taskQueue: 'hello-world',
-    workflow: workflows.example,
-  });
-  await worker.run();
-}
-```
+    export async function saludar(nombre: string): Promise<string> {
+      return `¡Hola, ${nombre}!`;
+    }
+    ```
+2. Define your **workflow** logic. Include conditional branching, loops, etc to control activity execution. It's vanilla code written in your own coding style. The only requirement is to use `proxyActivities`, ensuring your activities are executed with HotMesh's durability guarantee.
+    ```javascript
+    //workflows.ts
+
+    import { Durable } from '@hotmeshio/hotmesh';
+    import * as activities from './activities';
+
+    const { greet, saludar } = Durable.workflow
+      .proxyActivities<typeof activities>({
+        activities
+      });
+
+    export async function example(name: string, lang: string): Promise<string> {
+      if (lang === 'es') {
+        return await saludar(name);
+      } else {
+        return await greet(name);
+      }
+    }
+    ```
+
+3. Although you could call your workflow directly (it's just a vanilla function), it's only durable when invoked and orchestrated via HotMesh. By using a HotMesh **client** to send the request, the function is guaranteed to return a result.
+    ```javascript
+    //client.ts
+
+    import { Durable } from '@hotmeshio/hotmesh';
+    import Redis from 'ioredis'; //OR `import * as Redis from 'redis';`
+    import { v4 as uuidv4 } from 'uuid';
+
+    async function run(): Promise<string> {
+      const client = new Durable.Client({
+        connection: {
+          class: Redis,
+          options: { host: 'localhost', port: 6379 }
+        }
+      });
+
+      const handle = await client.workflow.start({
+        args: ['HotMesh', 'es'],
+        taskQueue: 'hello-world',
+        workflowName: 'example',
+        workflowId: uuidv4()
+      });
+
+      return await handle.result();
+      //returns '¡Hola, HotMesh!'
+    }
+    ```
+
+4. The last step is to create a **worker** that executes the workflow. Workers listen for tasks on their assigned channel, executing their assigned workflow function until it succeeds.
+    ```javascript
+    //worker.ts
+
+    import { Durable } from '@hotmeshio/hotmesh';
+    import Redis from 'ioredis';
+    import * as workflows from './workflows';
+
+    async function run() {
+      const worker = await Durable.Worker.create({
+        connection: {
+          class: Redis,
+          options: { host: 'localhost', port: 6379 },
+        },
+        taskQueue: 'hello-world',
+        workflow: workflows.example,
+      });
+      await worker.run();
+    }
+    ```
 
->HotMesh delivers durable function execution using a [distributed service mesh](https://github.com/hotmeshio/sdk-typescript/blob/main/docs/distributed_orchestration.md). The design delivers durable workflows without the cost and complexity of a centralized service mesh/control plane. Refer to the [hotmeshio/samples-typescript](https://github.com/hotmeshio/samples-typescript) Git Repo for a range of examples, including nested workflows.
+>HotMesh delivers durable workflows without the cost and complexity of a centralized service mesh. Refer to the [samples-typescript](https://github.com/hotmeshio/samples-typescript) Git Repo for a range of examples, including compositional workflows (where one workflow calls another) and remote execution (where calls are brokered across microservices).
 
 ## 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/modules/key.d.ts

@@ -25,7 +25,7 @@
  * hmsh:<appid>:sym:keys:<activityid|$subscribes> ->  {hash}    list of symbols based upon schema enums (initially) and adaptively optimized (later) during runtime; if '$subscribes' is used as the activityid, it is a top-level `job` symbol set (for job keys)
  * hmsh:<appid>:sym:vals: ->                          {hash}    list of symbols for job values across all app versions
  */
-declare const PSNS = "hmsh";
+declare const HMNS = "hmsh";
 declare enum KeyType {
     APP = 0,
     ENGINE_ID = 1,
@@ -72,4 +72,4 @@ declare class KeyService {
      */
     static mintKey(namespace: string, keyType: KeyType, params: KeyStoreParams): string;
 }
-export { KeyService, KeyType, KeyStoreParams, PSNS };
+export { KeyService, KeyType, KeyStoreParams, HMNS };

package/build/modules/key.js

@@ -27,10 +27,10 @@
  * hmsh:<appid>:sym:vals: ->                          {hash}    list of symbols for job values across all app versions
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PSNS = exports.KeyType = exports.KeyService = void 0;
+exports.HMNS = exports.KeyType = exports.KeyService = void 0;
 //default namespace for hotmesh
-const PSNS = "hmsh";
-exports.PSNS = PSNS;
+const HMNS = "hmsh";
+exports.HMNS = HMNS;
 //these are the entity types that are stored in the key/value store
 var KeyType;
 (function (KeyType) {

package/build/package.json

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

package/build/services/durable/native.js

@@ -22,7 +22,6 @@ async function run() {
   });
   const worker = await Worker.create({
     connection,
-    namespace: 'default',
     taskQueue: 'hello-world',
     workflow: workflows.example,
     activities,

package/build/services/durable/worker.js

@@ -26,7 +26,6 @@ async function run() {
   });
   const worker = await Worker.create({
     connection,
-    namespace: 'default',
     taskQueue: 'hello-world',
     workflow: workflows.example,
     activities,

package/build/services/hotmesh/index.js

@@ -17,7 +17,7 @@ class HotMeshService {
     }
     verifyAndSetNamespace(namespace) {
         if (!namespace) {
-            this.namespace = key_1.PSNS;
+            this.namespace = key_1.HMNS;
         }
         else if (!namespace.match(/^[A-Za-z0-9-]+$/)) {
             throw new Error(`config.namespace [${namespace}] is invalid`);

package/build/services/store/index.js

@@ -58,7 +58,7 @@ class StoreService {
         };
         this.redisClient = redisClient;
     }
-    async init(namespace = key_1.PSNS, appId, logger) {
+    async init(namespace = key_1.HMNS, appId, logger) {
         this.namespace = namespace;
         this.appId = appId;
         this.logger = logger;
@@ -111,7 +111,7 @@ class StoreService {
             if (bCreate) {
                 const packageJson = await Promise.resolve().then(() => __importStar(require('../../package.json')));
                 const version = packageJson['version'] || '0.0.0';
-                settings = { namespace: key_1.PSNS, version };
+                settings = { namespace: key_1.HMNS, version };
                 await this.setSettings(settings);
                 return settings;
             }

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

@@ -7,7 +7,7 @@ class IORedisStreamService extends index_1.StreamService {
     constructor(redisClient) {
         super(redisClient);
     }
-    async init(namespace = key_1.PSNS, appId, logger) {
+    async init(namespace = key_1.HMNS, appId, logger) {
         this.namespace = namespace;
         this.logger = logger;
         this.appId = appId;

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

@@ -7,7 +7,7 @@ class RedisStreamService extends index_1.StreamService {
     constructor(redisClient) {
         super(redisClient);
     }
-    async init(namespace = key_1.PSNS, appId, logger) {
+    async init(namespace = key_1.HMNS, appId, logger) {
         this.namespace = namespace;
         this.logger = logger;
         this.appId = appId;

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

@@ -7,7 +7,7 @@ class IORedisSubService extends index_1.SubService {
     constructor(redisClient) {
         super(redisClient);
     }
-    async init(namespace = key_1.PSNS, appId, engineId, logger) {
+    async init(namespace = key_1.HMNS, appId, engineId, logger) {
         this.namespace = namespace;
         this.logger = logger;
         this.appId = appId;

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

@@ -7,7 +7,7 @@ class RedisSubService extends index_1.SubService {
     constructor(redisClient) {
         super(redisClient);
     }
-    async init(namespace = key_1.PSNS, appId, engineId, logger) {
+    async init(namespace = key_1.HMNS, appId, engineId, logger) {
         this.namespace = namespace;
         this.logger = logger;
         this.appId = appId;

package/build/types/durable.d.ts

@@ -32,7 +32,7 @@ type Registry = {
 };
 type WorkerConfig = {
     connection: Connection;
-    namespace: string;
+    namespace?: string;
     taskQueue: string;
     workflow: Function;
 };

package/modules/key.ts

@@ -27,7 +27,7 @@
  */
 
 //default namespace for hotmesh
-const PSNS = "hmsh";
+const HMNS = "hmsh";
 
 //these are the entity types that are stored in the key/value store
 enum KeyType {
@@ -126,4 +126,4 @@ class KeyService {
   }
 }
 
-export { KeyService, KeyType, KeyStoreParams, PSNS };
+export { KeyService, KeyType, KeyStoreParams, HMNS };

package/package.json

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

package/services/durable/native.ts

@@ -21,7 +21,6 @@ async function run() {
   });
   const worker = await Worker.create({
     connection,
-    namespace: 'default',
     taskQueue: 'hello-world',
     workflow: workflows.example,
     activities,

package/services/durable/worker.ts

@@ -25,7 +25,6 @@ async function run() {
   });
   const worker = await Worker.create({
     connection,
-    namespace: 'default',
     taskQueue: 'hello-world',
     workflow: workflows.example,
     activities,

package/services/hotmesh/index.ts

@@ -1,5 +1,5 @@
 import { v4 as uuidv4 } from 'uuid';
-import { PSNS } from '../../modules/key';
+import { HMNS } from '../../modules/key';
 import { EngineService } from '../engine';
 import { LoggerService, ILogger } from '../logger';
 import { StreamSignaler } from '../signaler/stream';
@@ -33,7 +33,7 @@ class HotMeshService {
 
   verifyAndSetNamespace(namespace?: string) {
     if (!namespace) {
-      this.namespace = PSNS;
+      this.namespace = HMNS;
     } else if (!namespace.match(/^[A-Za-z0-9-]+$/)) {
       throw new Error(`config.namespace [${namespace}] is invalid`);
     } else {

package/services/store/index.ts

@@ -2,7 +2,7 @@ import {
   KeyService,
   KeyStoreParams,
   KeyType, 
-  PSNS} from '../../modules/key';
+  HMNS} from '../../modules/key';
 import { ILogger } from '../logger';
 import { MDATA_SYMBOLS, SerializerService as Serializer } from '../serializer';
 import { Cache } from './cache';
@@ -119,7 +119,7 @@ abstract class StoreService<T, U extends AbstractRedisClient> {
     this.redisClient = redisClient;
   }
 
-  async init(namespace = PSNS, appId: string, logger: ILogger): Promise<HotMeshApps> {
+  async init(namespace = HMNS, appId: string, logger: ILogger): Promise<HotMeshApps> {
     this.namespace = namespace;
     this.appId = appId;
     this.logger = logger;
@@ -178,7 +178,7 @@ abstract class StoreService<T, U extends AbstractRedisClient> {
       if (bCreate) {
         const packageJson = await import('../../package.json');
         const version: string = packageJson['version'] || '0.0.0';
-        settings = { namespace: PSNS, version } as HotMeshSettings;
+        settings = { namespace: HMNS, version } as HotMeshSettings;
         await this.setSettings(settings);
         return settings;
       }

package/services/stream/clients/ioredis.ts

@@ -1,4 +1,4 @@
-import { KeyService, KeyStoreParams, KeyType, PSNS } from '../../../modules/key';
+import { KeyService, KeyStoreParams, KeyType, HMNS } from '../../../modules/key';
 import { ILogger } from '../../logger';
 import { StreamService } from '../index';
 import { RedisClientType, RedisMultiType } from '../../../types/ioredisclient';
@@ -14,7 +14,7 @@ class IORedisStreamService extends StreamService<RedisClientType, RedisMultiType
     super(redisClient);
   }
 
-  async init(namespace = PSNS, appId: string, logger: ILogger): Promise<void> {
+  async init(namespace = HMNS, appId: string, logger: ILogger): Promise<void> {
     this.namespace = namespace;
     this.logger = logger;
     this.appId = appId;

package/services/stream/clients/redis.ts

@@ -1,4 +1,4 @@
-import { KeyService, KeyStoreParams, KeyType, PSNS } from '../../../modules/key';
+import { KeyService, KeyStoreParams, KeyType, HMNS } from '../../../modules/key';
 import { ILogger } from '../../logger';
 import { StreamService } from '../index';
 import { RedisClientType, RedisMultiType } from '../../../types/redisclient';
@@ -14,7 +14,7 @@ class RedisStreamService extends StreamService<RedisClientType, RedisMultiType>
     super(redisClient);
   }
 
-  async init(namespace = PSNS, appId: string, logger: ILogger): Promise<void> {
+  async init(namespace = HMNS, appId: string, logger: ILogger): Promise<void> {
     this.namespace = namespace;
     this.logger = logger;
     this.appId = appId;

package/services/sub/clients/ioredis.ts

@@ -1,4 +1,4 @@
-import { KeyService, KeyStoreParams, KeyType, PSNS } from '../../../modules/key';
+import { KeyService, KeyStoreParams, KeyType, HMNS } from '../../../modules/key';
 import { ILogger } from '../../logger';
 import { SubService } from '../index';
 import { RedisClientType, RedisMultiType } from '../../../types/ioredisclient';
@@ -14,7 +14,7 @@ class IORedisSubService extends SubService<RedisClientType, RedisMultiType> {
     super(redisClient);
   }
 
-  async init(namespace = PSNS, appId: string, engineId: string, logger: ILogger): Promise<void> {
+  async init(namespace = HMNS, appId: string, engineId: string, logger: ILogger): Promise<void> {
     this.namespace = namespace;
     this.logger = logger;
     this.appId = appId;

package/services/sub/clients/redis.ts

@@ -1,4 +1,4 @@
-import { KeyService, KeyStoreParams, KeyType, PSNS } from '../../../modules/key';
+import { KeyService, KeyStoreParams, KeyType, HMNS } from '../../../modules/key';
 import { ILogger } from '../../logger';
 import { SubService } from '../index';
 import { RedisClientType, RedisMultiType } from '../../../types/redisclient';
@@ -14,7 +14,7 @@ class RedisSubService extends SubService<RedisClientType, RedisMultiType> {
     super(redisClient);
   }
 
-  async init(namespace = PSNS, appId: string, engineId: string, logger: ILogger): Promise<void> {
+  async init(namespace = HMNS, appId: string, engineId: string, logger: ILogger): Promise<void> {
     this.namespace = namespace;
     this.logger = logger;
     this.appId = appId;

package/types/durable.ts

@@ -39,7 +39,7 @@ type Registry  = {
 
 type WorkerConfig = {
   connection: Connection;
-  namespace: string; //`appid` in the YAML (e.g, 'default')
+  namespace?: string; //`appid` in the YAML (e.g, 'default')
   taskQueue: string; //`subscribes` in the YAML (e.g, 'hello-world')
   workflow: Function //target function to run
 }