Run a Cron

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

    //cron.ts
    import { MeshCall } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    export const runMyCron = async (id: string, interval = '0 0 * * *'): Promise<boolean> => {
      return await MeshCall.cron({
        topic: 'my.cron.function',
        connection: {
          class: Postgres,
          options: {
            connectionString: 'postgresql://usr:pwd@localhost:5432/db'
          }
        },
        callback: async () => {
          //your code here...
        },
        options: { id, interval, maxCycles: 24 }
      });
    };

2. Call runMyCron at server startup (or call as needed to run multiple crons).

    //server.ts
    import { runMyCron } from './cron';
   
    runMyCron('myNightlyCron123');

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.

    import { MeshCall } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    MeshCall.interrupt({
      topic: 'my.cron.function',
      connection: {
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      },
      options: { id: 'myNightlyCron123' }
    });

Call a Function

Make interservice calls that behave like HTTP but without the setup and performance overhead. This example demonstrates how to connect and call a function.

1. Call MeshCall.connect and provide a topic to uniquely identify the function.

    //myFunctionWrapper.ts
    import { MeshCall, Types } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    export const connectMyFunction = async () => {
      return await MeshCall.connect({
        topic: 'my.demo.function',
        connection: {
          class: Postgres,
          options: {
            connectionString: 'postgresql://usr:pwd@localhost:5432/db'
          }
        },
        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.

    //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.

    import { MeshCall } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    const result = await MeshCall.exec({
      topic: 'my.demo.function',
      args: ['something'],
      connection: {
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      },
    }); //returns `{ hello: 'something'}`

Cache a Function

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.

    import { MeshCall } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    const result = await MeshCall.exec({
      topic: 'my.demo.function',
      args: ['anything'],
      connection: {
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      },
      options: { id: 'myid123', ttl: '15 minutes' },
    }); //returns `{ hello: 'anything'}`

2. Flush the cache at any time, using the same topic and cache id.

    import { MeshCall } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    await MeshCall.flush({
      topic: 'my.demo.function',
      connection: {
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      },
      options: { id: 'myid123' },
    });

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.

1. Start by defining activities. Note how each throws an error 50% of the time.

    //activities.ts
    export async function greet(name: string): Promise<string> {
      if (Math.random() > 0.5) throw new Error('Random error');
      return `Hello, ${name}!`;
    }
   
    export async function saludar(nombre: string): Promise<string> {
      if (Math.random() > 0.5) throw new Error('Random error');
      return `¡Hola, ${nombre}!`;
    }

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.

    //workflows.ts
    import { workflow } from '@hotmeshio/hotmesh';
    import * as activities from './activities';
   
    const { greet, saludar } = workflow
      .proxyActivities<typeof activities>({
        activities
      });
   
    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.

    //client.ts
    import { Client, HotMesh } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    async function run(): Promise<string> {
      const client = new Client({
        connection: {
          class: Postgres,
          options: {
            connectionString: 'postgresql://usr:pwd@localhost:5432/db'
          }
        }
      });
   
      const handle = await client.workflow.start<[string,string]>({
        args: ['HotMesh'],
        taskQueue: 'default',
        workflowName: 'example',
        workflowId: HotMesh.guid()
      });
   
      return await handle.result();
      //returns ['Hello HotMesh', '¡Hola, HotMesh!']
    }

4. Finally, create a worker and link the workflow function. Workers listen for tasks on their assigned task queue and invoke the workflow function each time they receive an event.

    //worker.ts
    import { worker } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
    import * as workflows from './workflows';
   
    async function run() {
      const worker = await Worker.create({
        connection: {
          class: Postgres,
          options: {
            connectionString: 'postgresql://usr:pwd@localhost:5432/db'
          }
        },
        taskQueue: 'default',
        workflow: workflows.example,
      });
   
      await worker.run();
    }

Wait for Signal

Pause a function and only awaken when a matching signal is received from the outide.

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.

    //waitForWorkflow.ts
    import { workflow } from '@hotmeshio/hotmesh';
   
    export async function waitForExample(): Promise<{hello: string}> {
      return await 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).

    //client.ts
    import { Client, HotMesh } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    async function run(): Promise<string> {
      const client = new Client({
        connection: {
          class: Postgres,
          options: {
            connectionString: 'postgresql://usr:pwd@localhost:5432/db'
          }
        }
      });
   
      //start a workflow; it will immediately pause
      await client.workflow.start({
        args: ['HotMesh'],
        taskQueue: 'default',
        workflowName: 'waitForExample',
        workflowId: 'myWorkflow123',
        await: false,
      });
    }

3. Create a worker and link the waitForExample workflow function.

    //worker.ts
    import { Worker } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
    import * as workflows from './waitForWorkflow';
   
    async function run() {
      const worker = await Worker.create({
        connection: {
          class: Postgres,
          options: {
            connectionString: 'postgresql://usr:pwd@localhost:5432/db'
          }
        },
        taskQueue: 'default',
        workflow: workflows.waitForExample,
      });
   
      await worker.run();
    }

4. Send a signal to awaken the paused function; await the function result.

    import { Client } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    const client = new Client({
      connection: {
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      }
    });
   
    //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',
      workflowId: 'myWorkflow123'
    });
   
    const result = await handle.result();
    //returns { hello: 'world' }

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.

    //waitForWorkflows.ts
    import { workflow } from '@hotmeshio/hotmesh';
   
    export async function waitForExample(): Promise<[boolean, number]> {
      const [s1, s2] = await Promise.all([
        workflow.waitFor<boolean>('my-sig-nal-1'),
        workflow.waitFor<number>('my-sig-nal-2')
      ]);
      //do something with the signal payloads (s1, s2)
      return [s1, s2];
    }

2. Send two signals to awaken the paused function.

    import { Client } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    const client = new Client({
      connection: {
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      }
    });
   
    //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',
      workflowId: 'myWorkflow123'
    });
   
    const result = await handle.result();
    //returns [true, 12345]

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 the backend.

1. Define the workflow logic. This one calls a legacy statusDiagnostic function once a week.

    //recurringWorkflow.ts
    import { workflow } from '@hotmeshio/hotmesh';
    import * as activities from './activities';
   
    const { statusDiagnostic } = workflow
      .proxyActivities<typeof activities>({
        activities
      });
   
    export async function recurringExample(someValue: number): Promise<void> {
      do {
        await statusDiagnostic(someValue);
      } while (await workflow.sleepFor('1 week'));
    }

2. Instance a HotMesh client and start a workflow. Assign a custom workflow ID (e.g., myRecurring123) if the workflow should be idempotent.

    //client.ts
    import { Client, HotMesh } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    async function run(): Promise<string> {
      const client = new Client({
        connection: {
          class: Postgres,
          options: {
            connectionString: 'postgresql://usr:pwd@localhost:5432/db'
          }
        }
      });
   
      //start a workflow; it will immediately pause
      await client.workflow.start({
        args: [55],
        taskQueue: 'default',
        workflowName: 'recurringExample',
        workflowId: 'myRecurring123',
        await: false,
      });
    }

3. Create a worker and link the recurringExample workflow function.

    //worker.ts
    import { Worker } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
    import * as workflows from './recurringWorkflow';
   
    async function run() {
      const worker = await Worker.create({
        connection: {
          class: Postgres,
          options: {
            connectionString: 'postgresql://usr:pwd@localhost:5432/db'
          }
        },
        taskQueue: 'default',
        workflow: workflows.recurringExample,
      });
   
      await worker.run();
    }

4. Cancel the recurring workflow (myRecurring123) by calling interrupt.

    import { Client } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    const client = new Client({
      connection: {
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      }
    });
   
    //get the workflow handle and interrupt it
    const handle = await client.getHandle({
      taskQueue: 'default',
      workflowId: 'myRecurring123'
    });
   
    const result = await handle.interrupt();

Workflow Data 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.

    //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 index upon server startup. This one initializes the 'user' index, 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.

    //server.ts
    import { MeshData } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
    import { schema } from './schema';
   
    const meshData = new MeshData({
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      },
      schema,
    );
    await meshData.createSearchIndex('user', { namespace: 'meshdata' });

Workflow Record Data

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.

    //connect.ts
    import { MeshData } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
    import { schema } from './schema';
   
    export const connectUserWorker = async (): Promise<void> => {
      const meshData = new MeshData({
        class: Postgres,
        options: {
            connectionString: 'postgresql://  usr:pwd@localhost:5432/db'
          }
        },
        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.

    //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.

    //exec.ts
    import { MeshData } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
   
    const meshData = new MeshData({
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      },
      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.

    import { newUser } from './exec';
    const response = await newUser('jim123', 'James');

Read Record Data

This example demonstrates how to read data fields directly from a workflow.

1. Read data fields directly from the jimbo123 'user' record.

    //read.ts
    import { MeshData } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
    import { schema } from './schema';
   
    const meshData = new MeshData({
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      },
      schema,
    );
   
    const data = await meshData.get(
      'user',
      'jimbo123',
      { 
        fields: ['id', 'name', 'timestamp', 'active'],
        namespace: 'meshdata'
      },
    );

Query Record Data

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 and SQL are currently 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).

    //read.ts
    import { MeshData } from '@hotmeshio/hotmesh';
    import { Client as Postgres } from 'pg';
    import { schema } from './schema';
   
    const meshData = new MeshData({
        class: Postgres,
        options: {
          connectionString: 'postgresql://usr:pwd@localhost:5432/db'
        }
      },
      schema,
    );
   
    const results = await meshData.findWhere('user', {
      query: [{ field: 'active', is: '=', value: 'yes' }],
      limit: { start: 0, size: 100 },
      return: ['id', 'name', 'timestamp', 'active']
    });

Connect Postgres Client

import { Client as PostgresClient } from 'pg';

//provide these credentials to HotMesh
const connection = {
  class: PostgresClient,
  options: {
    connectionString: 'postgresql://usr:pwd@localhost:5432/db'
  }
};

Connect Postgres Pool

Pool connections are recommended for high-throughput applications. The pool will manage connections and automatically handle connection pooling.

import { Pool as PostgresPool } from 'pg';

const PostgresPoolClient = new PostgresPool({
  connectionString: 'postgresql://usr:pwd@localhost:5432/db'
});

//provide these credentials to HotMesh
const connection = {
  class: PostgresPoolClient,
  options: {},
};

Redis/IORedis

import * as Redis from 'redis';
//OR `import Redis from 'ioredis';`

const connection = {
  class: Redis,
  options: {
    url: 'redis://:your_password@localhost:6379',
  }
};

NATS PubSub

Add NATS for improved PubSub support, including patterned subscriptions. Note the explicit channel subscription in the example below. The NATS provider supports version 2.0 of the NATS client (the latest version). See ./package.json for details.

import { Client as Postgres } from 'pg';
import { connect as NATS } from 'nats';

const connection = {
  store: {
    class: Postgres,
    options: {
      connectionString: 'postgresql://usr:pwd@localhost:5432/db',
    }
  },
  stream: {
    class: Postgres,
    options: {
      connectionString: 'postgresql://usr:pwd@localhost:5432/db',
    }
  },
  sub: {
    class: NATS,
    options: { servers: ['nats:4222'] }
  },
};