Class HotMesh

A distributed service mesh that turns Postgres into a durable workflow orchestration engine. Every HotMesh.init() call creates a point of presence — an engine, a quorum member, and zero or more workers — that collaborates with its peers through Postgres LISTEN/NOTIFY to form a self-coordinating mesh with no external dependencies.

Service Mesh Architecture

Each HotMesh instance joins a quorum — a real-time pub/sub channel backed by Postgres LISTEN/NOTIFY. The quorum is the mesh's nervous system: version activations, throttle commands, roll calls, and custom user messages all propagate instantly to every connected engine and worker across all processes and servers.

Quick Start

import { HotMesh } from '@hotmeshio/hotmesh';
import { Client as Postgres } from 'pg';

const hotMesh = await HotMesh.init({
  appId: 'myapp',
  engine: {
    connection: {
      class: Postgres,
      options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
    },
  },
  workers: [{
    topic: 'order.process',
    connection: {
      class: Postgres,
      options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
    },
    callback: async (data) => ({
      metadata: { ...data.metadata },
      data: { orderId: data.data.id, status: 'fulfilled' },
    }),
  }],
});

// Deploy a YAML workflow graph
await hotMesh.deploy(`
app:
  id: myapp
  version: '1'
  graphs:
    - subscribes: order.placed
      publishes: order.fulfilled
      expire: 600

      activities:
        t1:
          type: trigger
        process:
          type: worker
          topic: order.process
          input:
            schema:
              type: object
              properties:
                id: { type: string }
            maps:
              id: '{t1.output.data.id}'
      transitions:
        t1:
          - to: process
`);

await hotMesh.activate('1');

// Fire-and-forget
const jobId = await hotMesh.pub('order.placed', { id: 'ORD-123' });

// Request/response (blocks until workflow completes)
const result = await hotMesh.pubsub('order.placed', { id: 'ORD-456' });

Lifecycle

init — Create an engine + workers; join the quorum.
deploy — Upload a YAML graph to Postgres (inactive).
activate — Coordinate the quorum to switch to the new version.
pub / pubsub — Trigger workflow execution.
stop — Leave the quorum and release connections.

Higher-Level Modules

For most use cases, prefer the higher-level wrappers:

Durable — Durable workflow functions with replay and retry.
Virtual — Virtual network functions and idempotent RPC.

See

https://hotmeshio.github.io/sdk-typescript/ - API reference

Properties

appId

appId: string

guid

guid: string

logger

logger: ILogger

namespace

namespace: string

`Static`disconnecting

disconnecting: boolean = false

`Static`listWorkerRoles

listWorkerRoles: ((config: {
connection: ProviderConfig | ProvidersConfig;
namespace?: string;
}) => Promise<WorkerCredentialInfo[]>) = WorkerCredentials.listWorkerRoles

List all provisioned secured worker roles.

Type declaration

- (config): Promise<WorkerCredentialInfo[]>
- List all provisioned worker roles for a namespace.
  Parameters
  - config: {
    connection: ProviderConfig | ProvidersConfig;
    namespace?: string;
    }
    - connection: ProviderConfig | ProvidersConfig
    - Optionalnamespace?: string
  Returns Promise<WorkerCredentialInfo[]>

`Static`provisionWorkerRole

provisionWorkerRole: ((config: {
    connection: ProviderConfig | ProvidersConfig;
    namespace?: string;
    password?: string;
    streamNames: string[];
}) => Promise<WorkerCredential>) = WorkerCredentials.provisionWorkerRole

Provision a scoped Postgres role for a worker. The role can only dequeue, ack, and respond on its assigned stream names via stored procedures — zero direct table access.

Type declaration

- (config): Promise<WorkerCredential>
- Provision a scoped Postgres role for a worker router.
  
  The role can only dequeue/ack/respond on the specified stream names via SECURITY DEFINER stored procedures — it has zero direct table access.
  Parameters
  - config: {
        connection: ProviderConfig | ProvidersConfig;
        namespace?: string;
        password?: string;
        streamNames: string[];
    }
    - connection: ProviderConfig | ProvidersConfig
    - Optionalnamespace?: string
    - Optionalpassword?: string
    - streamNames: string[]
  Returns Promise<WorkerCredential>

`Static`revokeWorkerRole

revokeWorkerRole: ((config: {
    connection: ProviderConfig | ProvidersConfig;
    namespace?: string;
    roleName: string;
}) => Promise<void>) = WorkerCredentials.revokeWorkerRole

Revoke a secured worker role (disables login).

Type declaration

- (config): Promise<void>
- Revoke a worker role by disabling login. The role is not dropped, preserving the audit trail in the worker_credentials table.
  Parameters
  - config: {
        connection: ProviderConfig | ProvidersConfig;
        namespace?: string;
        roleName: string;
    }
    - connection: ProviderConfig | ProvidersConfig
    - Optionalnamespace?: string
    - roleName: string
  Returns Promise<void>

`Static`rotateWorkerPassword

rotateWorkerPassword: ((config: {
    connection: ProviderConfig | ProvidersConfig;
    namespace?: string;
    newPassword?: string;
    roleName: string;
}) => Promise<{
    password: string;
}>) = WorkerCredentials.rotateWorkerPassword

Rotate a secured worker role's password.

Type declaration

- (config): Promise<{
  password: string;
  }>
- Rotate the password for an existing worker role.
  Parameters
  - config: {
        connection: ProviderConfig | ProvidersConfig;
        namespace?: string;
        newPassword?: string;
        roleName: string;
    }
    - connection: ProviderConfig | ProvidersConfig
    - Optionalnamespace?: string
    - OptionalnewPassword?: string
    - roleName: string
  Returns Promise<{
  password: string;
  }>

Methods

activate

activate(version, delay?): Promise<boolean>
Activates a previously deployed version across all connected instances. The quorum coordinates a synchronized version switch so every engine and worker transitions together.
Parameters
- version: string
  The version string to activate (must match a deployed graph).
- Optionaldelay: number
  Optional delay in ms before activation takes effect.
Returns Promise<boolean>
- Defined in services/hotmesh/index.ts:386

cancel

cancel(jobId): Promise<void>
Requests cooperative cancellation of a running job. Sets a durable cancel flag; the workflow detects it at its next durable operation and throws CancelledFailure, which can be caught for cleanup.
Parameters
- jobId: string
  The job/workflow ID.
Returns Promise<void>
- Defined in services/hotmesh/index.ts:487

deploy

deploy(pathOrYAML): Promise<HotMeshManifest>
Deploys a YAML workflow graph to Postgres. The graph is stored but remains inactive until activate is called.
Parameters
- pathOrYAML: string
  A file path or raw YAML string defining the workflow graph.
Returns Promise<HotMeshManifest>
The parsed manifest with version and graph metadata.
- Defined in services/hotmesh/index.ts:374

export

export(jobId, options?): Promise<JobExport>
Exports the full job state (data, metadata, activity results) as a structured JSON object.
Parameters
- jobId: string
  The job/workflow ID.
- options: ExportOptions = {}
  Export options (e.g., include activity details).
Returns Promise<JobExport>
- Defined in services/hotmesh/index.ts:399

getQueryState

getQueryState(jobId, fields): Promise<StringAnyType>
Returns specific searchable fields from a job's HASH record.
Parameters
- jobId: string
  The job/workflow ID.
- fields: string[]
  The field names to retrieve.
Returns Promise<StringAnyType>
- Defined in services/hotmesh/index.ts:442

getRaw

getRaw(jobId): Promise<StringStringType>
Returns all raw key-value pairs from a job's HASH record in Postgres. Useful for debugging or low-level inspection.
Parameters
- jobId: string
Returns Promise<StringStringType>
- Defined in services/hotmesh/index.ts:407

getState

getState(topic, jobId): Promise<JobOutput>
Returns the structured job state (data + metadata). For a completed job this is the final output; for a running job it reflects the latest persisted state.
Parameters
- topic: string
  The workflow topic.
- jobId: string
  The job/workflow ID.
Returns Promise<JobOutput>
- Defined in services/hotmesh/index.ts:432

getStatus

getStatus(jobId): Promise<number>
Returns the numeric status code for a job: 0 = completed, positive = still running, negative = interrupted/errored.
Parameters
- jobId: string
Returns Promise<number>
- Defined in services/hotmesh/index.ts:420

interrupt

interrupt(topic, jobId, options?): Promise<string>
Immediately terminates a running job. The job is marked as interrupted and its HASH is expired. Unlike cancel, this does not give the workflow a chance to run cleanup code.
Parameters
- topic: string
  The workflow topic.
- jobId: string
  The job/workflow ID.
- options: JobInterruptOptions = {}
  Optional interrupt configuration.
Returns Promise<string>
- Defined in services/hotmesh/index.ts:472

psub

psub(wild, callback): Promise<void>
Subscribes to workflow emissions matching a wildcard pattern.
Parameters
- wild: string
  The wildcard pattern (e.g., 'order.*').
- callback: JobMessageCallback
  Invoked with each matching emission.
Returns Promise<void>
- Defined in services/hotmesh/index.ts:267

pub

pub(topic, data?, context?, extended?): Promise<string>
Publishes a message to a workflow topic, starting a new job. Returns the job ID immediately (fire-and-forget).
Parameters
- topic: string
  The workflow topic (must match a deployed graph's subscribes).
- data: JobData = {}
  Input data for the workflow.
- Optionalcontext: JobState
- Optionalextended: ExtensionType
Returns Promise<string>
The new job ID.
- Defined in services/hotmesh/index.ts:235

pubQuorum

pubQuorum(quorumMessage): Promise<boolean>
Publishes a custom message to every instance via the quorum channel. Register a listener with subQuorum to receive these messages.
Parameters
- quorumMessage: QuorumMessage
Returns Promise<boolean>
- Defined in services/hotmesh/index.ts:341

pubsub

pubsub(topic, data?, context?, timeout?): Promise<JobOutput>
Publishes a message and blocks until the workflow completes, returning the final job output. Combines pub + sub into a single request/response call.
Parameters
- topic: string
  The workflow topic.
- data: JobData = {}
  Input data for the workflow.
- Optionalcontext: JobState
  Optional job state context.
- Optionaltimeout: number
  Optional timeout in milliseconds.
Returns Promise<JobOutput>
The completed job output.
- Defined in services/hotmesh/index.ts:289

punsub

punsub(wild): Promise<void>
Unsubscribes from a wildcard pattern previously registered with psub.
Parameters
- wild: string
Returns Promise<void>
- Defined in services/hotmesh/index.ts:274

rollCall

rollCall(delay?): Promise<QuorumProfile[]>
Broadcasts a PING to all connected engines and workers via LISTEN/NOTIFY and collects their profiles. Returns one QuorumProfile per responding instance, including cumulative message counts, error_count, stream_depth, throttle state, and host-level system health (memory/CPU).

Use this for health checks, topology discovery, and throughput monitoring across the mesh.
Parameters
- Optionaldelay: number
  Time in ms to wait for PONG responses (default: quorum config).
Returns Promise<QuorumProfile[]>
One profile per responding engine/worker instance.
- Defined in services/hotmesh/index.ts:322

scrub

scrub(jobId): Promise<void>
Immediately deletes a completed job's HASH record from Postgres.
Parameters
- jobId: string
Returns Promise<void>
- Defined in services/hotmesh/index.ts:494

signal

signal(topic, data, status?, code?): Promise<string>
Sends a signal to a paused workflow, delivering data and resuming execution. Pairs with condition() in the Durable workflow API.
Parameters
- topic: string
  The signal topic.
- data: JobData
  Signal payload.
- Optionalstatus: StreamStatus
- Optionalcode: number
Returns Promise<string>
- Defined in services/hotmesh/index.ts:505

stop

stop(): void
Stops this specific HotMesh instance — leaves the quorum and stops all workers. Does not affect other instances in the process.

Returns void
- Defined in services/hotmesh/index.ts:541

sub

sub(topic, callback): Promise<void>
Subscribes to all output and interim emissions from a workflow topic.
Parameters
- topic: string
  The topic to subscribe to.
- callback: JobMessageCallback
  Invoked with each job output or interim emission.
Returns Promise<void>
- Defined in services/hotmesh/index.ts:250

subQuorum

subQuorum(callback): Promise<void>
Subscribes to the quorum channel to receive system messages (version activations, throttle commands, roll calls) and custom user messages.
Parameters
- callback: QuorumMessageCallback
Returns Promise<void>
- Defined in services/hotmesh/index.ts:349

throttle

throttle(options): Promise<boolean>
Broadcasts a throttle command to all instances. Use to slow down or pause message consumption across the mesh.
Parameters
- options: ThrottleOptions
  Throttle rate in ms (0 = no throttle, -1 = pause indefinitely). Optionally scope by guid (single instance) or topic (single worker).
Returns Promise<boolean>
- Defined in services/hotmesh/index.ts:333

unsub

unsub(topic): Promise<void>
Unsubscribes from a workflow topic previously registered with sub.
Parameters
- topic: string
Returns Promise<void>
- Defined in services/hotmesh/index.ts:257

unsubQuorum

unsubQuorum(callback): Promise<void>
Unsubscribes a callback previously registered with subQuorum.
Parameters
- callback: QuorumMessageCallback
Returns Promise<void>
- Defined in services/hotmesh/index.ts:356

`Static`guid

guid(): string
Generates a unique ID using the same nanoid generator used internally by HotMesh for job IDs and GUIDs.

Returns string
- Defined in services/hotmesh/index.ts:221

`Static`init

init(config): Promise<HotMesh>
Create a HotMesh instance with an engine and optional workers.

The engine manages workflow state in Postgres. Workers are callback functions that consume messages from Postgres streams — they can run on the same process or on entirely separate servers.
Parameters
- config: HotMeshConfig
  Engine connection, worker definitions, app ID, and options.
Returns Promise<HotMesh>
A running HotMesh instance joined to the quorum.
- Defined in services/hotmesh/index.ts:200

`Static`registerCodec

registerCodec(codec): void
Register a global payload codec for encoding/decoding serialized object data at rest. Once registered, all object values flowing through the serializer are stored as /b{encoded} instead of /s{json}. Use this for encryption, compression, or custom encoding.

The codec is global — it applies to all HotMesh and Durable instances in the process. Pass null to remove a previously registered codec.

Constraints: The codec must be synchronous and its output must be a valid UTF-8 string. Use base64 encoding for binary output.
Parameters
- codec: PayloadCodec
Returns void
Example
```
import { HotMesh } from '@hotmeshio/hotmesh';

HotMesh.registerCodec({
  encode(json) { return Buffer.from(json).toString('base64'); },
  decode(encoded) { return Buffer.from(encoded, 'base64').toString('utf8'); },
});
```
- Defined in services/hotmesh/index.ts:581

`Static`stop

stop(): Promise<void>
Stops all HotMesh instances in the current process.

Returns Promise<void>
- Defined in services/hotmesh/index.ts:529

Class HotMesh

Service Mesh Architecture

Quick Start

Lifecycle

Higher-Level Modules

See

Index

Properties

Methods

Properties

appId

guid

logger

namespace

Staticdisconnecting

StaticlistWorkerRoles

Type declaration

Parameters

connection: ProviderConfig | ProvidersConfig

Optionalnamespace?: string

Returns Promise<WorkerCredentialInfo[]>

StaticprovisionWorkerRole

Type declaration

Parameters

connection: ProviderConfig | ProvidersConfig

Optionalnamespace?: string

Optionalpassword?: string

streamNames: string[]

Returns Promise<WorkerCredential>

StaticrevokeWorkerRole

Type declaration

Parameters

connection: ProviderConfig | ProvidersConfig

Optionalnamespace?: string

roleName: string

Returns Promise<void>

StaticrotateWorkerPassword

Type declaration

Parameters

connection: ProviderConfig | ProvidersConfig

Optionalnamespace?: string

OptionalnewPassword?: string

roleName: string

Returns Promise<{ password: string; }>

Methods

activate

Parameters

Returns Promise<boolean>

cancel

Parameters

Returns Promise<void>

deploy

Parameters

Returns Promise<HotMeshManifest>

export

Parameters

Returns Promise<JobExport>

getQueryState

Parameters

Returns Promise<StringAnyType>

getRaw

Parameters

Returns Promise<StringStringType>

getState

Parameters

Returns Promise<JobOutput>

getStatus

Parameters

Returns Promise<number>

interrupt

Parameters

Returns Promise<string>

psub

Parameters

Returns Promise<void>

pub

Parameters

Returns Promise<string>

pubQuorum

Parameters

`Static`disconnecting

`Static`listWorkerRoles

`Optional`namespace?: string

`Static`provisionWorkerRole

`Optional`namespace?: string

`Optional`password?: string

`Static`revokeWorkerRole

`Optional`namespace?: string

`Static`rotateWorkerPassword

`Optional`namespace?: string

`Optional`newPassword?: string

Returns Promise<{
password: string;
}>

`Static`guid

`Static`init

`Static`registerCodec

`Static`stop