@hotmeshio/hotmesh 0.1.15 → 0.1.16

package/README.md

@@ -1,37 +1,187 @@
 # HotMesh
 ![beta release](https://img.shields.io/badge/release-beta-blue.svg)
 
-HotMesh transforms Redis into an Orchestration Engine.
-
-*Write functions in your own style, and let Redis govern their execution, reliably and durably.*
+**HotMesh** transforms **Redis** into indispensable **Middleware**. Connect **anything** to **everything**.
 
 ## Install
-[![npm version](https://badge.fury.io/js/%40hotmeshio%2Fhotmesh.svg)](https://badge.fury.io/js/%40hotmeshio%2Fhotmesh)
-
 ```sh
 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/)
+
+## MeshCall
+The **MeshCall** module connects and exposes your functions as idempotent endpoints.
+
+<details style="padding: .5em">
+  <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 fails silently if a workflow is already running with the same `id`.*
+  
+  Optionally set `maxCycles` or `maxDuration` to limit the number of cycles.
+
+1. Define the cron function.
+    ```typescript
+    //cron.ts
+    import { MeshCall } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+
+    export const runMyCron = (id: string, interval = '1 day') => {
+      MeshCall.cron({
+        topic: 'my.cron.function',
+        redis: {
+          class: Redis,
+          options: { url: 'redis://:key_admin@redis:6379' }
+        },
+        callback: async () => {
+          //your code here...
+        },
+        options: { id, interval }
+      });
+    };
+    ```
+
+2. Call `runMyCron` at server startup (or call as needed to run multiple crons).
+    ```typescript
+    //server.ts
+    import { runMyCron } from './cron';
+    runMyCron('myDailyCron123');
+    ```
+</details>
+
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Interrupt a cron job</summary>
+
+  ### Interrupt a Cron
+  This example demonstrates how to cancel a running cron job.
+
+1. Use the same `id` and `topic` that were used to create the cron to cancel it.
+    ```typescript
+    import { MeshCall } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+
+    MeshCall.interrupt({
+      topic: 'my.cron.function',
+      redis: {
+        class: Redis,
+        options: { url: 'redis://:key_admin@redis:6379' }
+      },
+      options: { id: 'myDailyCron123' }
+    });
+    ```
+</details>
+
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Call any function in any service</summary>
+
+  ### Call a Function
+  Make blazing fast interservice calls that return in milliseconds without the overhead of HTTP.
+
+1. Call `MeshCall.connect` and provide a `topic` to uniquely identify the function.
+
+    ```typescript
+    //myFunctionWrapper.ts
+    import { MeshCall, Types } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
 
-## Understanding HotMesh
-HotMesh inverts the relationship to Redis: those functions that once used Redis as a cache, are instead *cached and governed* by Redis. Consider the following. It's a typical microservices network, with a tangled mess of services and functions. There's important business logic in there (functions *A*, *B* and *C* are critical), but it's hard to find and access.
+    export const connectMyFunction = () => {
+      MeshCall.connect({
+        topic: 'my.demo.function',
+        redis: {
+          class: Redis,
+          options: { url: 'redis://:key_admin@redis:6379' }
+        },
+        callback: async (input: string) => {
+          //your code goes here; response must be JSON serializable
+          return { hello: input }
+        },
+      });
+    };
+      ```
+
+2. Call `connectMyFunction` at server startup to connect your function to the mesh.
+
+    ```typescript
+    //server.ts
+    import { connectMyFunction } from './myFunctionWrapper';
+    connectMyFunction();
+    ```
+
+3. Call your function from anywhere on the network (or even from the same service). Send any payload as long as it's JSON serializable.
+
+    ```typescript
+    import { MeshCall } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+
+    const result = await MeshCall.exec({
+      topic: 'my.demo.function',
+      args: ['something'],
+      redis: {
+        class: Redis,
+        options: { url: 'redis://:key_admin@redis:6379' }
+      },
+    }); //returns `{ hello: 'something'}`
+    ```
+</details>
 
-<img src="./docs/img/operational_data_layer.png" alt="A Tangled Microservices Network with 3 valuable functions buried within" style="max-width:100%;width:600px;">
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Call and <b>cache</b> a function</summary>
+
+  ### Cache a Function
+  Redis is great for unburdening stressed services. This solution builds upon the previous example, caching the response. The linked function will only be re/called when the cached result expires. Everything remains the same, except the caller which specifies an `id` and `ttl`.
+
+1. Make the call from another service (or even the same service). Include an `id` and `ttl` to cache the result for the specified duration.
+
+    ```typescript
+    import { MeshCall } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+
+    const result = await MeshCall.exec({
+      topic: 'my.demo.function',
+      args: ['anything'],
+      redis: {
+        class: Redis,
+        options: { url: 'redis://:key_admin@redis:6379' }
+      },
+      options: { id: 'myid123', ttl: '15 minutes' },
+    }); //returns `{ hello: 'anything'}`
+    ```
+
+2. Flush the cache at any time, using the same `topic` and cache `id`.
+
+    ```typescript
+    import { MeshCall } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+
+    await MeshCall.flush({
+      topic: 'my.demo.function',
+      redis: {
+        class: Redis,
+        options: { url: 'redis://:key_admin@redis:6379' }
+      },
+      options: { id: 'myid123' },
+    });
+    ```
+</details>
 
-HotMesh creates an *ad hoc*, Redis-backed network of functions and organizes them into a unified service mesh. *Any service with access to Redis can join in the network, bypassing the legacy clutter.*
+## MeshFlow
+The **MeshFlow** module is a drop-in replacement for [Temporal.io](https://temporal.io). If you need to orchestrate your functions as durable workflows, MeshFlow combines the popular Temporal SDK with Redis' *in-memory execution speed*.
 
-## Design
-HotMesh uses your existing Redis installation. If you already have an instance available, you have all the infrastructure you'll ever need.
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Orchestrate unpredictable activities</summary>
 
-### Design | Pluck
-The simplest way to get started is to use the [HotMesh Pluck](https://github.com/hotmeshio/pluck-typescript) package. It's designed for usability, and is backed by the HotMesh system if you need advanced features. It includes a detailed [SDK](https://hotmeshio.github.io/pluck-typescript/) and a wide variety of examples.
+### Proxy Activities
+When an endpoint is unpredictable, use `proxyActivities`. HotMesh will retry as necessary until the call succeeds. This example demonstrates a workflow that greets a user in both English and Spanish. Even though both activities throw random errors, the workflow always returns a successful result.
 
-### Design | Durable
-HotMesh's *Durable* module is a TypeScript Library modeled after Temporal.io. If you're familiar with their SDK, the principles are the same.
+1. Start by defining **activities**. Note how each throws an error 50% of the time.
 
-1. Start by defining **activities**. Activities 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. *Note how the `saludar` example throws an error 50% of the time. It doesn't matter how unpredictable your functions are, HotMesh will retry as necessary until they succeed.*
-    ```javascript
+    ```typescript
     //activities.ts
     export async function greet(name: string): Promise<string> {
+      if (Math.random() > 0.5) throw new Error('Random error');
       return `Hello, ${name}!`;
     }
 
@@ -40,62 +190,67 @@ HotMesh's *Durable* module is a TypeScript Library modeled after Temporal.io. If
       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
+
+2. Define the **workflow** logic. Include conditional branching, loops, etc to control activity execution. It's vanilla JavaScript written in your own coding style. The only requirement is to use `proxyActivities`, ensuring your activities are executed with HotMesh's durability wrapper.
+
+    ```typescript
     //workflows.ts
-    import { Durable } from '@hotmeshio/hotmesh';
+    import { MeshFlow } from '@hotmeshio/hotmesh';
     import * as activities from './activities';
 
-    const { greet, saludar } = Durable.workflow
+    const { greet, saludar } = MeshFlow.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);
-      }
+    export async function example(name: string): Promise<[string, string]> {
+      return Promise.all([
+        greet(name),
+        saludar(name)
+      ]);
     }
     ```
+
 3. Instance a HotMesh **client** to invoke the workflow.
-    ```javascript
+
+    ```typescript
     //client.ts
-    import { Durable, HotMesh } from '@hotmeshio/hotmesh';
-    import Redis from 'ioredis'; //OR `import * as Redis from 'redis';`
+    import { MeshFlow, HotMesh } from '@hotmeshio/hotmesh';
+    import Redis from 'ioredis';
 
     async function run(): Promise<string> {
-      const client = new Durable.Client({
+      const client = new MeshFlow.Client({
         connection: {
           class: Redis,
-          options: { host: 'localhost', port: 6379 }
+          options: { host: 'redis', port: 6379 }
         }
       });
 
-      const handle = await client.workflow.start({
-        args: ['HotMesh', 'es'],
+      const handle = await client.workflow.start<[string,string]>({
+        args: ['HotMesh'],
         taskQueue: 'default',
         workflowName: 'example',
         workflowId: HotMesh.guid()
       });
 
       return await handle.result();
-      //returns '¡Hola, HotMesh!'
+      //returns ['Hello HotMesh', '¡Hola, HotMesh!']
     }
     ```
-4. Finally, create a **worker** and link your workflow function. Workers listen for tasks on their assigned Redis stream and invoke your workflow function each time they receive an event.
-    ```javascript
+
+4. Finally, create a **worker** and link the workflow function. Workers listen for tasks on their assigned Redis stream and invoke the workflow function each time they receive an event.
+
+    ```typescript
     //worker.ts
-    import { Durable } from '@hotmeshio/hotmesh';
+    import { MeshFlow } from '@hotmeshio/hotmesh';
     import Redis from 'ioredis';
     import * as workflows from './workflows';
 
     async function run() {
-      const worker = await Durable.Worker.create({
+      const worker = await MeshFlow.Worker.create({
         connection: {
           class: Redis,
-          options: { host: 'localhost', port: 6379 },
+          options: { host: 'redis', port: 6379 },
         },
         taskQueue: 'default',
         workflow: workflows.example,
@@ -104,222 +259,481 @@ HotMesh's *Durable* module is a TypeScript Library modeled after Temporal.io. If
       await worker.run();
     }
     ```
+</details>
+
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Pause and wait for a signal</summary>
 
-#### Workflow Extensions
-Externalizing state fundamentally changes the execution profile for your functions, allowing you to design long-running, durable workflows. The `Durable` base class (shown in the examples above) provides additional methods for solving the most common state management challenges.
+### Wait for Signal
+Pause a function and only awaken when a matching signal is received from the outide.
 
- - `waitFor` Pause your function using your chosen signal key, and only awaken when the signal is received from the outide. Use a standard `Promise` to collate and cache the signals and only awaken your function once all signals have arrived.
-    ```javascript
-    const { waitFor } = Durable.workflow;
-    const [a, b] = await Promise.all([
-      waitFor<{payload: string}>('sig1'),
-      waitFor<number>('sig2')
-    ]);
+1. Define the **workflow** logic. This one waits for the `my-sig-nal` signal, returning the signal payload (`{ hello: 'world' }`) when it eventually arrives. Interleave additional logic to meet your use case.
+
+    ```typescript
+    //waitForWorkflow.ts
+    import { MeshFlow } from '@hotmeshio/hotmesh';
+
+    export async function waitForExample(): Promise<{hello: string}> {
+      return await MeshFlow.workflow.waitFor<{hello: string}>('my-sig-nal');
+      //continue processing, use the payload, etc...
+    }
+    ```
+
+2. Instance a HotMesh **client** and start a workflow. Use a custom workflow ID (`myWorkflow123`).
+
+    ```typescript
+    //client.ts
+    import { MeshFlow, HotMesh } from '@hotmeshio/hotmesh';
+    import Redis from 'ioredis';
+
+    async function run(): Promise<string> {
+      const client = new MeshFlow.Client({
+        connection: {
+          class: Redis,
+          options: { host: 'redis', port: 6379 }
+        }
+      });
+
+      //start a workflow; it will immediately pause
+      await client.workflow.start({
+        args: ['HotMesh'],
+        taskQueue: 'default',
+        workflowName: 'waitForExample',
+        workflowId: 'myWorkflow123',
+        await: false,
+      });
+    }
     ```
- - `signal` Send a signal (and payload) to a paused function awaiting the signal. Signals may also be sent from the outside to awaken a paused function.
-    ```javascript
-    await Durable.workflow.signal('sig1', {payload: 'hi!'});
+
+3. Create a **worker** and link the `waitForExample` workflow function.
+
+    ```typescript
+    //worker.ts
+    import { MeshFlow } from '@hotmeshio/hotmesh';
+    import Redis from 'ioredis';
+    import * as workflows from './waitForWorkflow';
+
+    async function run() {
+      const worker = await MeshFlow.Worker.create({
+        connection: {
+          class: Redis,
+          options: { host: 'redis', port: 6379 },
+        },
+        taskQueue: 'default',
+        workflow: workflows.waitForExample,
+      });
+
+      await worker.run();
+    }
     ```
- - `hook` Redis governance converts your functions into 're-entrant processes'. Optionally use the *hook* method to spawn parallel execution threads to augment a running workflow.
-    ```javascript
-    await Durable.workflow.hook({
-      workflowName: 'newsletter',
+
+4. Send a signal to awaken the paused function; await the function result.
+
+    ```typescript
+    import { MeshFlow } from '@hotmeshio/hotmesh';
+    import * as Redis from Redis;
+
+    const client = new MeshFlow.Client({
+      connection: {
+        class: Redis,
+        options: { host: 'redis', port: 6379 }
+      }
+    });
+
+    //awaken the function by sending a signal
+    await client.signal('my-sig-nal', { hello: 'world' });
+
+    //get the workflow handle and await the result
+    const handle = await client.getHandle({
       taskQueue: 'default',
-      args: []
+      workflowId: 'myWorkflow123'
     });
+    
+    const result = await handle.result();
+    //returns { hello: 'world' }
     ```
- - `sleepFor` Pause function execution for a ridiculous amount of time (months, years, etc). There's no risk of information loss, as Redis governs function state. When your function awakens, function state is efficiently (and automatically) restored and your function will resume right where it left off.
-    ```javascript
-    await Durable.workflow.sleepFor('1 month');
-    ```
- - `random` Generate a deterministic random number that can be used in a reentrant process workflow (replaces `Math.random()`).
-    ```javascript
-    const random = await Durable.workflow.random();
+</details>
+
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Wait for multiple signals (collation)</summary>
+
+### Collate Multiple Signals
+Use a standard `Promise` to collate and cache multiple signals. HotMesh will only awaken once **all** signals have arrived. HotMesh will track up to 25 concurrent signals.
+
+1. Update the **workflow** logic to await two signals using a promise: `my-sig-nal-1` and `my-sig-nal-2`. Add additional logic to meet your use case.
+
+    ```typescript
+    //waitForWorkflows.ts
+    import { MeshFlow } from '@hotmeshio/hotmesh';
+
+    export async function waitForExample(): Promise<[boolean, number]> {
+      const [s1, s2] = await Promise.all([
+        Meshflow.workflow.waitFor<boolean>('my-sig-nal-1'),
+        Meshflow.workflow.waitFor<number>('my-sig-nal-2')
+      ]);
+      //do something with the signal payloads (s1, s2)
+      return [s1, s2];
+    }
     ```
- - `execChild` Call another durable function and await the response. *Design sophisticated, multi-process solutions by leveraging this command.*
-    ```javascript
-    const jobResponse = await Durable.workflow.execChild({
-      workflowName: 'newsletter',
-      taskQueue: 'default',
-      args: [{ id, user_id, etc }],
+
+2. Send **two** signals to awaken the paused function.
+
+    ```typescript
+    import { MeshFlow } from '@hotmeshio/hotmesh';
+    import * as Redis from Redis;
+
+    const client = new MeshFlow.Client({
+      connection: {
+        class: Redis,
+        options: { host: 'redis', port: 6379 }
+      }
     });
-    ```
- - `startChild` Call another durable function, but do not await the response.
-    ```javascript
-    const jobId = await Durable.workflow.startChild({
-      workflowName: 'newsletter',
+
+    //send 2 signals to awaken the function; order is unimportant
+    await client.signal('my-sig-nal-2', 12345);
+    await client.signal('my-sig-nal-1', true);
+
+    //get the workflow handle and await the collated result
+    const handle = await client.getHandle({
       taskQueue: 'default',
-      args: [{ id, user_id, etc }],
+      workflowId: 'myWorkflow123'
     });
+    
+    const result = await handle.result();
+    //returns [true, 12345]
     ```
- - `getContext` Get the current workflow context (workflowId, replay history, replay index, etc).
-    ```javascript
-    const context = await Durable.workflow.getContext();
-    ```
- - `search` Instance a search session
-    ```javascript
-    const search = await Durable.workflow.search();
-    ```
-    - `set` Set one or more name/value pairs
-      ```javascript
-      await search.set('name1', 'value1', 'name2', 'value2');
-      ```
-    - `get` Get a single value by name
-      ```javascript
-      const value = await search.get('name');
-      ```
-    - `mget` Get multiple values by name
-      ```javascript
-      const [val1, val2] = await search.mget('name1', 'name2');
-      ```
-    - `del` Delete one or more entries by name and return the number deleted
-      ```javascript
-      const count = await search.del('name1', 'name2');
-      ```
-    - `incr` Increment (or decrement) a number
-      ```javascript
-      const value = await search.incr('name', 12);
-      ```
-    - `mult` Multiply a number
-      ```javascript
-      const value = await search.mult('name', 12);
-      ```
+</details>
 
-Refer to the [hotmeshio/samples-javascript](https://github.com/hotmeshio/samples-javascript) repo for usage examples.
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Create a recurring, cyclical workflow</summary>
 
-### Design | Advanced
-The *Pluck* and *Durable* modules are the easiest way to use HotMesh. 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.
-
-```yaml
-app:
-  id: sandbox
-  version: '1'
-  graphs:
-    - subscribes: sandbox.work.do
-      publishes: sandbox.work.done
-
-      activities:
-        gateway:
-          type: trigger
-        servicec:
-          type: worker
-          topic: sandbox.work.do.servicec
-        serviced:
-          type: worker
-          topic: sandbox.work.do.serviced
-        sforcecloud:
-          type: worker
-          topic: sandbox.work.do.sforcecloud
-
-      transitions:
-        gateway:
-          - to: servicec
-        servicec:
-          - to: serviced
-        serviced:
-          - to: sforcecloud
-```
+### Cyclical Workflow
+This example calls an activity and then sleeps for a week. It runs indefinitely until it's manually stopped. It takes advantage of durable execution and can safely sleep for months or years.
+
+>Container restarts have no impact on actively executing workflows as all state is retained in Redis.
 
-### Initialize
-Provide your chosen Redis instance and configuration options to start a HotMesh Client. *HotMesh supports both `ioredis` and `redis` clients interchangeably.*
+1. Define the **workflow** logic. This one calls a legacy `statusDiagnostic` function once a week.
 
-```javascript
-import { HotMesh } from '@hotmeshio/hotmesh';
-import Redis from 'ioredis'; //OR `import * as Redis from 'redis';`
+    ```typescript
+    //recurringWorkflow.ts
+    import { MeshFlow } from '@hotmeshio/hotmesh';
+    import * as activities from './activities';
+
+    const { statusDiagnostic } = MeshFlow.workflow
+      .proxyActivities<typeof activities>({
+        activities
+      });
 
-const hotMesh = await HotMesh.init({
-  appId: 'sandbox',
-  engine: {
-    redis: {
-      class: Redis,
-      options: { host, port, password, db } //per your chosen Redis client
+    export async function recurringExample(someValue: number): Promise<void> {
+      do {
+        await statusDiagnostic(someValue);
+      } while (await MeshFlow.workflow.sleepFor('1 week'));
     }
-  }
-});
-```
+    ```
 
-A HotMesh Client can be used to trigger worfkows and subscribe to results.
+2. Instance a HotMesh **client** and start a workflow. Assign a custom workflow ID (e.g., `myRecurring123`) if the workflow should be idempotent.
 
-### Trigger a Workflow
-Call `pub` to initiate a workflow. This function returns a job ID that allows you to monitor the progress of the workflow.
+    ```typescript
+    //client.ts
+    import { MeshFlow, HotMesh } from '@hotmeshio/hotmesh';
+    import Redis from 'ioredis';
 
-```javascript
-const topic = 'sandbox.work.do';
-const payload = { };
-const jobId = await hotMesh.pub(topic, payload);
-```
+    async function run(): Promise<string> {
+      const client = new MeshFlow.Client({
+        connection: {
+          class: Redis,
+          options: { host: 'redis', port: 6379 }
+        }
+      });
 
-### Subscribe to Events
-Call `psub` (patterned subscription) to subscribe to all workflow results for a given topic.
+      //start a workflow; it will immediately pause
+      await client.workflow.start({
+        args: [55],
+        taskQueue: 'default',
+        workflowName: 'recurringExample',
+        workflowId: 'myRecurring123',
+        await: false,
+      });
+    }
+    ```
 
-```javascript
-await hotMesh.psub('sandbox.work.done.*', (topic, jobOutput) => {
-  // use jobOutput.data
-});
-```
+3. Create a **worker** and link the `recurringExample` workflow function.
 
-### Trigger and Wait
-Call `pubsub` to start a workflow and *wait for the response*. HotMesh establishes a one-time subscription and delivers the job result once the workflow concludes.
+    ```typescript
+    //worker.ts
+    import { MeshFlow } from '@hotmeshio/hotmesh';
+    import Redis from 'ioredis';
+    import * as workflows from './recurringWorkflow';
 
-```javascript
-const jobOutput = await hotMesh.pubsub(topic, payload);
-```
+    async function run() {
+      const worker = await MeshFlow.Worker.create({
+        connection: {
+          class: Redis,
+          options: { host: 'redis', port: 6379 },
+        },
+        taskQueue: 'default',
+        workflow: workflows.recurringExample,
+      });
 
->The `pubsub` method is a convenience function that merges pub and sub into a single call. Opt for HotMesh's queue-driven engine over fragile HTTP requests to develop resilient solutions.
+      await worker.run();
+    }
+    ```
 
-### Link Worker Functions
-Link worker functions to a topic of your choice. When a workflow activity in the YAML definition with a corresponding topic runs, HotMesh will invoke your function, retrying as configured until it succeeds.
+4. Cancel the recurring workflow (`myRecurring123`) by calling `interrupt`.
 
-```javascript
-import { HotMesh } from '@hotmeshio/hotmesh';
-import Redis from 'ioredis';
+    ```typescript
+    import { MeshFlow } from '@hotmeshio/hotmesh';
+    import * as Redis from Redis;
 
-const hotMesh = await HotMesh.init({
-  appId: 'sandbox',
-  workers: [
-    { 
-      topic: 'sandbox.work.do.servicec',
-      redis: {
+    const client = new MeshFlow.Client({
+      connection: {
         class: Redis,
-        options: { host, port, password, db }
-      }
-      callback: async (data: StreamData) => {
-        return {
-          metadata: { ...data.metadata },
-          data: { }
-        };
+        options: { host: 'redis', port: 6379 }
       }
+    });
+
+    //get the workflow handle and interrupt it
+    const handle = await client.getHandle({
+      taskQueue: 'default',
+      workflowId: 'myRecurring123'
+    });
+    
+    const result = await handle.interrupt();
+    ```
+</details>
+
+## MeshData
+The **MeshData** service extends the **MeshFlow** service, combining data record concepts and transactional workflow principles into a single *Operational Data Layer*. 
+
+Deployments with the Redis `FT.SEARCH` module enabled can use the **MeshData** module to merge [OLTP](https://en.wikipedia.org/wiki/Online_transaction_processing) and [OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) operations into a hybrid transactional/analytics ([HTAP](https://en.wikipedia.org/wiki/Hybrid_transactional/analytical_processing)) system.
+
+>For those Redis deployments without the `FT.SEARCH` module, it's still useful to define a workflow schema. The MeshData class provides convenience methods for reading and writing hash field data to a workflow record (e.g., `get`, `del`, and `incr`).*
+
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Create a search index</summary>
+
+### Schemas and Indexes
+
+This example demonstrates how to define a schema and deploy an index for a 'user' entity type.
+
+1. Define the **schema** for the `user` entity. This one includes the 3 formats supported by the FT.SEARCH module: `TEXT`, `TAG` and `NUMERIC`.
+
+    ```typescript
+    //schema.ts
+    export const schema: Types.WorkflowSearchOptions = {
+      schema: {
+        id: { type: 'TAG', sortable: false },
+        first: { type: 'TEXT', sortable: false, nostem: true },
+        active: { type: 'TAG', sortable: false },
+        created: { type: 'NUMERIC', sortable: true },
+      },
+      index: 'user',
+      prefix: ['user'],
+    };
+    ```
+
+2. Create the Redis index upon server startup. This one initializes the 'user' index in Redis, using the schema defined in the previous step. It's OK to call `createSearchIndex` multiple times; it will only create the index if it doesn't already exist.
+
+    ```typescript
+    //server.ts
+    import { MeshData } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+    import { schema } from './schema';
+
+    const meshData = new MeshData(
+      Redis,
+      { url: 'redis://:key_admin@redis:6379' },
+      schema,
+    );
+    await meshData.createSearchIndex('user', { namespace: 'meshdata' });
+    ```
+</details>
+
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Create an indexed, searchable record</summary>
+
+### Searchable Workflow
+This example demonstrates how to create a 'user' workflow backed by the searchable schema from the prior example.
+
+1. Call MeshData `connect` to initialize a 'user' entity *worker*. It references a target worker function which will run the workflow. Data fields that are documented in the schema (like `active`) will be automatically indexed when set on the workflow record.
+
+    ```typescript
+    //connect.ts
+    import { MeshData } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+    import { schema } from './schema';
+
+    export const connectUserWorker = async (): Promise<void> => {
+      const meshData = new MeshData(
+        Redis,
+        { url: 'redis://:key_admin@redis:6379' },
+        schema,
+      );
+    
+      await meshData.connect({
+        entity: 'user',
+        target: async function(name: string): Promise<string> {
+          //add custom, searchable data (`active`) and return
+          const search = await MeshData.workflow.search();
+          await search.set('active', 'yes');
+          return `Welcome, ${name}.`;
+        },
+        options: { namespace: 'meshdata' },
+      });
     }
-  ]
-};
-```
+    ```
+
+2. Wire up the worker at server startup, so it's ready to process incoming requests.
 
-### Observability
-Workflows and activities are run according to the rules you define, offering [Graph-Oriented](https://github.com/hotmeshio/sdk-typescript/tree/main/docs/system_lifecycle.md#telemetry) telemetry insights into your legacy function executions.
+    ```typescript
+    //server.ts
+    import { connectUserWorker } from './connect';
+    await connectUserWorker();
+    ```
+
+3. Call MeshData `exec` to create a 'user' workflow. Searchable data can be set throughout the workflow's lifecycle. This one initializes the workflow with 3 data fields: `id`, `name` and `timestamp`. *An additional data field (`active`) is set within the workflow function in order to demonstrate both mechanisms for reading/writing data to a workflow.*
+  
+    ```typescript
+    //exec.ts
+    import { MeshData } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+
+    const meshData = new MeshData(
+      Redis,
+      { url: 'redis://:key_admin@redis:6379' },
+      schema,
+    );
+
+    export const newUser = async (id: string, name: string): Promise<string> => {
+      const response = await meshData.exec({
+        entity: 'user',
+        args: [name],
+        options: {
+          ttl: 'infinity',
+          id,
+          search: {
+            data: { id, name, timestamp: Date.now() }
+          },
+          namespace: 'meshdata',
+        },
+      });
+      return response;
+    };
+    ```
+
+4. Call the `newUser` function to create a searchable 'user' record.
+
+    ```typescript
+    import { newUser } from './exec';
+    const response = await newUser('jim123', 'James');
+    ```
+</details>
+
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Fetch record data</summary>
+
+### Workflow Record Fields
+This example demonstrates how to read data fields directly from a workflow.
+
+1. Read data fields directly from the *jimbo123* 'user' record.
+
+    ```typescript
+    //read.ts
+    import { MeshData } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+    import { schema } from './schema';
+
+    const meshData = new MeshData(
+      Redis,
+      { url: 'redis://:key_admin@redis:6379' },
+      schema,
+    );
+
+    const data = await meshData.get(
+      'user',
+      'jimbo123',
+      { 
+        fields: ['id', 'name', 'timestamp', 'active'],
+        namespace: 'meshdata'
+      },
+    );
+    ```
+</details> 
+
+<details style="padding: .5em">
+  <summary style="font-size:1.25em;">Search record data</summary>
+
+### Searchable Workflow
+This example demonstrates how to search for those workflows where a given condition exists in the data. This one searches for active users. *NOTE: The native Redis FT.SEARCH syntax is supported. The JSON abstraction shown here is a convenience method for straight-forward, one-dimensional queries.*
+
+1. Search for active users (where the value of the `active` field is `yes`).
+
+    ```typescript
+    //read.ts
+    import { MeshData } from '@hotmeshio/hotmesh';
+    import * as Redis from 'redis';
+    import { schema } from './schema';
+
+    const meshData = new MeshData(
+      Redis,
+      { url: 'redis://:key_admin@redis:6379' },
+      schema,
+    );
 
-## FAQ
+    const results = await meshData.findWhere('user', {
+      query: [{ field: 'active', is: '=', value: 'yes' }],
+      limit: { start: 0, size: 100 },
+      return: ['id', 'name', 'timestamp', 'active']
+    });
+    ```
+</details> 
+
+## Visualize | OpenTelemetry
+HotMesh's telemetry output provides unmatched insight into long-running, multi-service transactions. Add your Honeycomb credentials to any project using HotMesh and HotMesh will emit the full *OpenTelemetry* execution tree organized as a DAG.
+
+<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.
+
+<img src="./docs/img/visualize/hotmesh_dashboard.png" alt="HotMesh Dashboard" style="width:600px;max-width:600px;">
+
+## Visualize | RedisInsight
+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.
+### 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
+### 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
 [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
+### 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
+### 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
+### 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
+### 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
+### 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-javascript](https://github.com/hotmeshio/samples-javascript) repo for usage examples.