@hotmeshio/hotmesh 0.14.3 → 0.14.4

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.14.3",
+    "version": "0.14.4",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -14,8 +14,8 @@
         "obfuscate": "ts-node scripts/obfuscate.ts",
         "clean-build": "npm run clean && npm run build",
         "clean-build-obfuscate": "npm run clean-build && npm run obfuscate",
-        "docs": "typedoc",
-        "docs:clean": "rimraf ./docs/hotmesh && typedoc",
+        "docs": "typedoc && cp -R docs/hotmesh/* docs/ && rm -rf docs/hotmesh",
+        "docs:clean": "rimraf ./docs/hotmesh && typedoc && cp -R docs/hotmesh/* docs/ && rm -rf docs/hotmesh",
         "lint": "eslint . --ext .ts",
         "lint:fix": "eslint . --fix --ext .ts",
         "start": "ts-node src/index.ts",
@@ -47,6 +47,7 @@
         "test:durable:retrypolicy": "vitest run tests/durable/retry-policy",
         "test:durable:sleep": "vitest run tests/durable/sleep/postgres.test.ts",
         "test:durable:signal": "vitest run tests/durable/signal/postgres.test.ts",
+        "test:durable:readonly": "docker compose --profile readonly up -d --build && docker compose exec hotmesh-readonly npx vitest run --config tests/durable/readonly/vitest.config.mts",
         "test:durable:unknown": "vitest run tests/durable/unknown/postgres.test.ts",
         "test:durable:exporter": "HMSH_LOGLEVEL=info vitest run tests/durable/exporter",
         "test:durable:exporter:debug": "EXPORT_DEBUG=1 HMSH_LOGLEVEL=error vitest run tests/durable/basic/postgres.test.ts",

package/build/services/durable/worker.js

@@ -516,10 +516,12 @@ class WorkerService {
         if (WorkerService.instances.has(targetTopic)) {
             return await WorkerService.instances.get(targetTopic);
         }
+        const readonly = providerConfig.readonly ?? false;
         const workerEntry = {
             topic: activityTopic,
             connection: providerConfig,
             callback: this.wrapActivityFunctions().bind(this),
+            readonly,
         };
         if (config.workerCredentials) {
             workerEntry.workerCredentials = config.workerCredentials;
@@ -644,10 +646,12 @@ class WorkerService {
         const targetNamespace = config?.namespace ?? factory_1.APP_ID;
         const optionsHash = WorkerService.hashOptions(config?.connection);
         const targetTopic = `${optionsHash}.${targetNamespace}.${workflowTopic}`;
+        const readonly = providerConfig.readonly ?? false;
         const workerEntry = {
             topic: taskQueue,
             workflowName: workflowFunctionName,
             connection: providerConfig,
+            readonly,
             callback: this.wrapWorkflowFunction(workflowFunction, workflowTopic, workflowFunctionName, config).bind(this),
         };
         if (config.workerCredentials) {

package/build/services/mapper/index.d.ts

@@ -1,10 +1,42 @@
 import { JobState } from '../../types/job';
 import { TransitionRule } from '../../types/transition';
 import { StreamCode } from '../../types';
+/**
+ * Evaluates and transforms data-mapping rules against live job state.
+ *
+ * @remarks
+ * MapperService is the bridge between a workflow's declarative mapping
+ * rules (including `@pipe` expressions) and the runtime job data. It
+ * recursively walks a rule tree, delegating leaf-level resolution to
+ * the {@link Pipe} engine. Static helpers such as {@link evaluate}
+ * also power transition-condition checks during workflow execution.
+ *
+ * @example
+ * ```typescript
+ * const mapper = new MapperService(
+ *   { greeting: '{data.name}', score: { '@pipe': [['{data.x}', '{data.y}'], ['{@math.add}']] } },
+ *   jobState,
+ * );
+ * const result = mapper.mapRules();
+ * // => { greeting: 'Alice', score: 7 }
+ * ```
+ */
 declare class MapperService {
     private rules;
     private data;
+    /**
+     * @param rules - The mapping rule tree to evaluate. May contain
+     *   literal values, `{data.*}` references, or nested `@pipe` objects.
+     * @param data  - The current {@link JobState} used to resolve references.
+     */
     constructor(rules: Record<string, unknown>, data: JobState);
+    /**
+     * Recursively resolves every rule in the tree against the current job
+     * state and returns a fully-evaluated copy.
+     *
+     * @returns A plain object mirroring the rule structure with all
+     *   expressions replaced by their resolved values.
+     */
     mapRules(): Record<string, unknown>;
     private traverseRules;
     /**
@@ -20,8 +52,31 @@ declare class MapperService {
      */
     private resolve;
     /**
-     * Evaluates a transition rule against the current job state and incoming Stream message
-     * to determine which (if any) transition should be taken.
+     * Evaluates a transition rule against the current job state and an
+     * incoming Stream message code to decide whether the transition fires.
+     *
+     * @remarks
+     * Supports both simple boolean rules (`true` / `false`) and compound
+     * match rules with optional AND / OR gating. When the rule includes
+     * a `match` array, each entry's `actual` expression is resolved via
+     * {@link Pipe.resolve} and compared to the `expected` value.
+     *
+     * @param transitionRule - A boolean shorthand or a {@link TransitionRule}
+     *   containing `code`, optional `gate`, and optional `match` conditions.
+     * @param context - The current {@link JobState} used to resolve
+     *   `actual` expressions inside match entries.
+     * @param code - The {@link StreamCode} returned by the preceding
+     *   activity (e.g. `200`).
+     * @returns `true` if the transition should be taken, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * const shouldTransition = MapperService.evaluate(
+     *   { code: 200, match: [{ expected: true, actual: '{data.isReady}' }] },
+     *   jobState,
+     *   200,
+     * );
+     * ```
      */
     static evaluate(transitionRule: TransitionRule | boolean, context: JobState, code: StreamCode): boolean;
 }

package/build/services/mapper/index.js

@@ -2,11 +2,43 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MapperService = void 0;
 const pipe_1 = require("../pipe");
+/**
+ * Evaluates and transforms data-mapping rules against live job state.
+ *
+ * @remarks
+ * MapperService is the bridge between a workflow's declarative mapping
+ * rules (including `@pipe` expressions) and the runtime job data. It
+ * recursively walks a rule tree, delegating leaf-level resolution to
+ * the {@link Pipe} engine. Static helpers such as {@link evaluate}
+ * also power transition-condition checks during workflow execution.
+ *
+ * @example
+ * ```typescript
+ * const mapper = new MapperService(
+ *   { greeting: '{data.name}', score: { '@pipe': [['{data.x}', '{data.y}'], ['{@math.add}']] } },
+ *   jobState,
+ * );
+ * const result = mapper.mapRules();
+ * // => { greeting: 'Alice', score: 7 }
+ * ```
+ */
 class MapperService {
+    /**
+     * @param rules - The mapping rule tree to evaluate. May contain
+     *   literal values, `{data.*}` references, or nested `@pipe` objects.
+     * @param data  - The current {@link JobState} used to resolve references.
+     */
     constructor(rules, data) {
         this.rules = rules;
         this.data = data;
     }
+    /**
+     * Recursively resolves every rule in the tree against the current job
+     * state and returns a fully-evaluated copy.
+     *
+     * @returns A plain object mirroring the rule structure with all
+     *   expressions replaced by their resolved values.
+     */
     mapRules() {
         return this.traverseRules(this.rules);
     }
@@ -46,8 +78,31 @@ class MapperService {
         return pipe.process();
     }
     /**
-     * Evaluates a transition rule against the current job state and incoming Stream message
-     * to determine which (if any) transition should be taken.
+     * Evaluates a transition rule against the current job state and an
+     * incoming Stream message code to decide whether the transition fires.
+     *
+     * @remarks
+     * Supports both simple boolean rules (`true` / `false`) and compound
+     * match rules with optional AND / OR gating. When the rule includes
+     * a `match` array, each entry's `actual` expression is resolved via
+     * {@link Pipe.resolve} and compared to the `expected` value.
+     *
+     * @param transitionRule - A boolean shorthand or a {@link TransitionRule}
+     *   containing `code`, optional `gate`, and optional `match` conditions.
+     * @param context - The current {@link JobState} used to resolve
+     *   `actual` expressions inside match entries.
+     * @param code - The {@link StreamCode} returned by the preceding
+     *   activity (e.g. `200`).
+     * @returns `true` if the transition should be taken, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * const shouldTransition = MapperService.evaluate(
+     *   { code: 200, match: [{ expected: true, actual: '{data.isReady}' }] },
+     *   jobState,
+     *   200,
+     * );
+     * ```
      */
     static evaluate(transitionRule, context, code) {
         if (typeof transitionRule === 'boolean') {

package/build/services/pipe/index.d.ts

@@ -1,44 +1,478 @@
 import { JobState, JobData } from '../../types/job';
 import { PipeContext, PipeItem, PipeItems, Pipe as PipeType } from '../../types/pipe';
+/**
+ * A functional data-transformation pipeline that resolves expressions
+ * row-by-row against live job data.
+ *
+ * @remarks
+ * ## Overview
+ *
+ * Pipe is the engine behind HotMesh's `@pipe` syntax — a uniform,
+ * functional approach to data mapping and transformation. Every
+ * ECMAScript operation is expressed as a **function with inputs**,
+ * eliminating the syntactic variability of the language (ternaries,
+ * property access, instance methods) in favor of a single,
+ * composable pattern.
+ *
+ * ## Postfix notation (Reverse Polish Notation)
+ *
+ * If you've used an RPN calculator, `@pipe` will feel familiar.
+ * Operands come first, then the operator consumes them:
+ *
+ * ```
+ * RPN:   4  4  +   →  8
+ *
+ * @pipe:
+ *   - [4, 4]           ← operands
+ *   - ["{@math.add}"]  ← operator  →  8
+ * ```
+ *
+ * That's the entire model. Operands are pushed, an operator pops
+ * them, and the result becomes an operand for the next row.
+ *
+ * ## How it works — row by row
+ *
+ * A pipe is an ordered array of **rows**. Each row is an array of
+ * **cells**. The key rule: **every resolved value on a row flows
+ * into cell 0 of the next row** (the operator). The operator
+ * consumes all upstream operands, resolves to a new value, and
+ * that result *becomes an operand*. Any remaining cells on the
+ * same row are resolved independently and appended as additional
+ * operands. Then the cycle repeats.
+ *
+ * ```
+ * @pipe:
+ *   ┌──────────────────────────────────────┐
+ *   │ Row 0: [operand, operand, operand]   │  ← resolve all cells
+ *   │            │        │        │       │
+ *   │            └────────┼────────┘       │
+ *   │                     │                │
+ *   ├─────────────────────┼────────────────┤
+ *   │                     ▼                │
+ *   │ Row 1: [  OPERATOR  , operand]       │  ← ALL operands from Row 0
+ *   │         ▲ receives all ▲             │     flow into cell 0;
+ *   │         │ from above   │             │     result becomes operand;
+ *   │         └──────────────┘             │     remaining cells resolve
+ *   │              │            │          │
+ *   │              └────────────┘          │
+ *   │                     │                │
+ *   ├─────────────────────┼────────────────┤
+ *   │                     ▼                │
+ *   │ Row 2: [  OPERATOR  , operand]       │  ← same pattern repeats
+ *   └──────────────────────────────────────┘
+ *       ▼
+ *   final value = cell 0 of last row
+ * ```
+ *
+ * Step by step:
+ *
+ * 1. **Row 0** — Every cell is resolved independently (static
+ *    literals, `{data.*}` references, or nullary functions like
+ *    `{@date.now}`). The resolved values are all **operands**.
+ * 2. **Row 1** — Cell 0 is the **operator** (`{@domain.method}`).
+ *    It receives *all* operands from Row 0 as its arguments and
+ *    produces a result. That result replaces cell 0 — it is now
+ *    an operand. Any remaining cells (cell 1, 2, ...) on this row
+ *    are resolved independently and become additional operands.
+ * 3. **Row 2** — Cell 0 is the next operator. It receives *all*
+ *    operands from Row 1 (the prior result + any extra cells).
+ *    The cycle repeats.
+ * 4. **Return** — The first cell of the final row is the result.
+ *
+ * When an additional cell on an operator row needs computed (not
+ * just a static value or simple reference), use a **nested
+ * `@pipe`** (sub-pipe) to resolve it. See Example 4 below.
+ *
+ * ## Three types of cell values
+ *
+ * | Type | Syntax | Example |
+ * |------|--------|---------|
+ * | **Static** | literal | `42`, `"hello"`, `true` |
+ * | **Dynamic** | `{path}` | `{a.output.data.name}` |
+ * | **Function** | `{@domain.method}` | `{@string.concat}`, `{@math.add}` |
+ *
+ * ## Available function domains
+ *
+ * - **array** — `get`, `length`, `join`, `concat`, `push`, `indexOf`, ...
+ * - **bitwise** — `and`, `or`, `xor`, `not`, ...
+ * - **conditional** — `ternary`, `equality`, `nullish`, ...
+ * - **cron** — `nextDelay`
+ * - **date** — `now`, `toLocaleString`, `yyyymmdd`, ...
+ * - **json** — `parse`, `stringify`
+ * - **logical** — `and`, `or`, `not`
+ * - **math** — `add`, `multiply`, `pow`, `max`, `min`, `abs`, ...
+ * - **number** — `isEven`, `isOdd`, `gte`, `lte`, ...
+ * - **object** — `create`, `get`, `set`, `keys`, ...
+ * - **string** — `concat`, `split`, `charAt`, `toLowerCase`, `includes`, ...
+ * - **symbol**
+ * - **unary**
+ *
+ * ---
+ *
+ * ## Example 1 — Simple field mapping (YAML)
+ *
+ * Most fields need only a one-to-one reference. Curly braces pull
+ * values from upstream activity outputs:
+ *
+ * ```yaml
+ * # Map fields from activities a and b into a new shape
+ * maps:
+ *   first: "{a.output.data.first_name}"
+ *   last:  "{a.output.data.last_name}"
+ *   email: "{b.output.data.email}"
+ *   age:   "{b.output.data.age}"
+ *   company: "ACME Corp"        # static string
+ *   bonus:   500                 # static number
+ * ```
+ *
+ * The equivalent JavaScript object passed to the mapper:
+ *
+ * ```typescript
+ * const rules = {
+ *   first: '{a.output.data.first_name}',
+ *   last:  '{a.output.data.last_name}',
+ *   email: '{b.output.data.email}',
+ *   age:   '{b.output.data.age}',
+ *   company: 'ACME Corp',
+ *   bonus:   500,
+ * };
+ * ```
+ *
+ * ## Example 2 — String transformation (YAML → JS)
+ *
+ * Build a `user_name` like `jdoe` from "John Doe". Follow the
+ * RPN flow — operands feed into the operator on the next row,
+ * the result becomes an operand, extra cells append more operands:
+ *
+ * ```yaml
+ * user_name:
+ *   "@pipe":
+ *     - ["{a.output.data.first_name}", 0]
+ *     - ["{@string.charAt}", "{a.output.data.last_name}"]
+ *     - ["{@string.concat}"]
+ *     - ["{@string.toLowerCase}"]
+ * ```
+ *
+ * ```typescript
+ * // Identical logic in JavaScript
+ * const rules = {
+ *   user_name: {
+ *     '@pipe': [
+ *       ['{a.output.data.first_name}', 0],
+ *       ['{@string.charAt}', '{a.output.data.last_name}'],
+ *       ['{@string.concat}'],
+ *       ['{@string.toLowerCase}'],
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * RPN trace (given first_name="John", last_name="Doe"):
+ *
+ * ```
+ * Row 0: ["John", 0]            ← two operands
+ * Row 1: charAt("John", 0)="J"  ← operator consumes both → result "J"
+ *         then resolve "Doe"    ← extra cell → operands are ["J", "Doe"]
+ * Row 2: concat("J", "Doe")     ← operator → result "JDoe"
+ *                                  operands are ["JDoe"]
+ * Row 3: toLowerCase("JDoe")    ← operator → result "jdoe"
+ * ```
+ *
+ * ## Example 3 — Conditional logic (YAML → JS)
+ *
+ * Classify an employee as "Senior" or "Junior" based on age:
+ *
+ * ```yaml
+ * status:
+ *   "@pipe":
+ *     - ["{b.output.data.age}", 40]
+ *     - ["{@number.gte}", "Senior", "Junior"]
+ *     - ["{@conditional.ternary}"]
+ * ```
+ *
+ * ```typescript
+ * const rules = {
+ *   status: {
+ *     '@pipe': [
+ *       ['{b.output.data.age}', 40],
+ *       ['{@number.gte}', 'Senior', 'Junior'],
+ *       ['{@conditional.ternary}'],
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * RPN trace (given age=30):
+ *
+ * ```
+ * Row 0: [30, 40]                          ← two operands
+ * Row 1: gte(30, 40)=false                 ← operator consumes both → false
+ *         resolve "Senior", "Junior"       ← extra cells → [false, "Senior", "Junior"]
+ * Row 2: ternary(false, "Senior", "Junior") ← operator → "Junior"
+ * ```
+ *
+ * ## Example 4 — Nested pipes (fan-out / fan-in)
+ *
+ * Extract initials from a full name. Each nested `@pipe` runs
+ * independently (fan-out), then the first standard row after them
+ * receives all sub-pipe results as inputs (fan-in):
+ *
+ * ```yaml
+ * initials:
+ *   "@pipe":
+ *     - ["{a.output.data.full_name}", " "]
+ *     - "@pipe":                           # fan-out: first initial
+ *       - ["{@string.split}", 0]
+ *       - ["{@array.get}", 0]
+ *       - ["{@string.charAt}"]
+ *     - "@pipe":                           # fan-out: last initial
+ *       - ["{@string.split}", 1]
+ *       - ["{@array.get}", 0]
+ *       - ["{@string.charAt}"]
+ *     - ["{@string.concat}"]              # fan-in: combine both
+ * ```
+ *
+ * ```typescript
+ * const rules = {
+ *   initials: {
+ *     '@pipe': [
+ *       ['{a.output.data.full_name}', ' '],
+ *       { '@pipe': [['{@string.split}', 0], ['{@array.get}', 0], ['{@string.charAt}']] },
+ *       { '@pipe': [['{@string.split}', 1], ['{@array.get}', 0], ['{@string.charAt}']] },
+ *       ['{@string.concat}'],
+ *     ],
+ *   },
+ * };
+ * // "Luke Birdeau" → split → ["Luke","Birdeau"]
+ * //   sub-pipe 1: get(0) → "Luke" → charAt(0) → "L"
+ * //   sub-pipe 2: get(1) → "Birdeau" → charAt(0) → "B"
+ * // fan-in: concat("L", "B") → "LB"
+ * ```
+ *
+ * ## Example 5 — Reduce (iterate and accumulate)
+ *
+ * Transform an array of `{ full_name }` objects into
+ * `{ first, last }` pairs using `@reduce`. Context variables
+ * `{$item}`, `{$key}`, `{$index}`, `{$input}`, and `{$output}`
+ * are available inside the reducer body:
+ *
+ * ```typescript
+ * const jobData = {
+ *   a: { output: { data: [
+ *     { full_name: 'Luke Birdeau' },
+ *     { full_name: 'John Doe' },
+ *   ]}}
+ * };
+ *
+ * const rules = [
+ *   ['{a.output.data}', []],         // input array + initial accumulator
+ *   { '@reduce': [
+ *     { '@pipe': [['{$output}']] },  // carry forward accumulator
+ *     { '@pipe': [
+ *       { '@pipe': [['first']] },
+ *       { '@pipe': [
+ *         ['{$item.full_name}', ' '],
+ *         ['{@string.split}', 0],
+ *         ['{@array.get}'],
+ *       ]},
+ *       { '@pipe': [['last']] },
+ *       { '@pipe': [
+ *         ['{$item.full_name}', ' '],
+ *         ['{@string.split}', 1],
+ *         ['{@array.get}'],
+ *       ]},
+ *       ['{@object.create}'],
+ *     ]},
+ *     ['{@array.push}'],
+ *   ]},
+ * ];
+ * // => [{ first: 'Luke', last: 'Birdeau' }, { first: 'John', last: 'Doe' }]
+ * ```
+ *
+ * ## Example 6 — Transition conditions
+ *
+ * Pipes power conditional transitions between workflow activities.
+ * In YAML, a transition fires only when the `@pipe` resolves to the
+ * `expected` value:
+ *
+ * ```yaml
+ * transitions:
+ *   t1:
+ *     - to: a1
+ *       conditions:
+ *         match:
+ *           - expected: false
+ *             actual:
+ *               "@pipe":
+ *                 - ["{t1.output.data.a}", "goodbye"]
+ *                 - ["{@conditional.equality}"]
+ * ```
+ *
+ * ## Example 7 — Inline YAML with HotMesh.deploy
+ *
+ * HotMesh ships with an inline YAML parser, so a complete
+ * workflow with data mapping can be deployed in a single call:
+ *
+ * ```typescript
+ * await hotMesh.deploy(`
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: order.process
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *         a1:
+ *           type: worker
+ *           topic: inventory.check
+ *           input:
+ *             maps:
+ *               itemId: "{t1.output.data.itemId}"
+ *           output:
+ *             schema:
+ *               type: object
+ *           job:
+ *             maps:
+ *               result: "{$self.output.data.available}"
+ *       transitions:
+ *         t1:
+ *           - to: a1
+ * `);
+ *
+ * await hotMesh.activate('1');
+ * const response = await hotMesh.pubsub('order.process', { itemId: 'sku-42' });
+ * ```
+ */
 declare class Pipe {
     rules: PipeType;
     jobData: JobData;
     context: PipeContext;
+    /**
+     * @param rules   - The ordered row array defining the pipeline.
+     * @param jobData - The current job data used to resolve `{data.*}`
+     *   and `{activity.*}` references.
+     * @param context - Optional iteration context (`$item`, `$key`,
+     *   `$output`, etc.) supplied during `@reduce` execution.
+     */
     constructor(rules: PipeType, jobData: JobData, context?: PipeContext);
     private isPipeType;
     private isreduceType;
+    /**
+     * Returns `true` if the value is a `@pipe` object (i.e. `{ '@pipe': [...] }`).
+     *
+     * @param obj - The value to test.
+     */
     static isPipeObject(obj: {
         [key: string]: unknown;
     } | PipeItem): boolean;
+    /**
+     * One-shot convenience method that resolves a single value or
+     * `@pipe` expression against the given context.
+     *
+     * @param unresolved - A literal value, a `{data.*}` reference string,
+     *   or a `@pipe` object.
+     * @param context - Partial {@link JobState} used for resolution.
+     * @returns The fully resolved value.
+     *
+     * @example
+     * ```typescript
+     * Pipe.resolve('{data.user.email}', jobState);
+     * Pipe.resolve({ '@pipe': [['{data.a}', '{data.b}'], ['{@math.multiply}']] }, jobState);
+     * ```
+     */
     static resolve(unresolved: {
         [key: string]: unknown;
     } | PipeItem, context: Partial<JobState>): any;
     /**
-     * loop through each PipeItem row in this Pipe, resolving and transforming line by line
-     * @returns {any} the result of the pipe
+     * Executes the pipeline row-by-row, resolving and transforming
+     * until the final value is produced.
+     *
+     * @remarks
+     * Row 0 is resolved independently (values only). Each subsequent
+     * row feeds the prior row's resolved output as arguments to the
+     * function named in cell 0. Nested `@pipe` rows are queued
+     * (fan-out) and collected into the next standard row (fan-in).
+     * `@reduce` rows iterate over the prior row's array output.
+     *
+     * @param resolved - Optional pre-resolved seed values (used
+     *   internally by `reduce` to inject the accumulator).
+     * @returns The first cell of the final resolved row.
+     *
+     * @example
+     * ```typescript
+     * // Split a full name and grab the first element
+     * const pipe = new Pipe(
+     *   [['{a.output.data.full_name}', ' '], ['{@string.split}', 0], ['{@array.get}']],
+     *   { a: { output: { data: { full_name: 'Luke Birdeau' } } } },
+     * );
+     * pipe.process(); // => 'Luke'
+     * ```
      */
     process(resolved?: unknown[] | null): any;
     cloneUnknown<T>(value: T): T;
     /**
-     * Transforms iterable `input` into a single value. Vars $output, $item, $key
-     * and $input are available. The final statement in the iterator (the reduction)
-     * is assumed to be the return value. A default $output object may be provided
-     * to the iterator by placing the the second cell of the preceding row. Otherwise,
-     * construct the object during first run and ensure it is the first cell of the
-     * last row of the iterator, so it is returned as the $output for the next cycle
-     * @param {unknown[]} input
-     * @returns {unknown}
+     * Iterates over an array or object and accumulates a result,
+     * similar to `Array.prototype.reduce`.
+     *
+     * @remarks
+     * Inside the reducer body the following context variables are
+     * available as cell references:
+     *
+     * | Variable | Description |
+     * |----------|-------------|
+     * | `{$input}` | The full input collection |
+     * | `{$output}` | The current accumulator |
+     * | `{$item}` | The current element |
+     * | `{$key}` | The current key (string for objects, index string for arrays) |
+     * | `{$index}` | The current numeric index |
+     *
+     * The preceding row supplies `[inputCollection, initialAccumulator]`.
+     * If no initial accumulator is provided, it defaults to `null`.
+     *
+     * @param input - A two-element array: `[collection, initialAccumulator]`.
+     * @returns The final accumulated value, wrapped in an array.
      * @private
      */
     reduce(input: Array<unknown[]>): unknown;
     private processRow;
+    /**
+     * Looks up a domain function by its `{@domain.method}` name string
+     * and returns the callable.
+     *
+     * @param functionName - A string like `{@math.add}` or `{@string.concat}`.
+     * @returns The resolved function reference.
+     * @throws If the domain or method is not registered.
+     */
     static resolveFunction(functionName: string): any;
+    /**
+     * Resolves every cell in a single row independently — each cell
+     * is evaluated for function calls, context variables, or mappable
+     * references.
+     *
+     * @param cells - The array of {@link PipeItems} to resolve.
+     * @returns An array of resolved values, one per input cell.
+     */
     processCells(cells: PipeItems): unknown[];
     private isFunction;
     private isContextVariable;
     private isMappable;
+    /**
+     * Resolves a single cell value by detecting its type — function
+     * call (`{@domain.fn}`), context variable (`{$item}`, `{$key}`,
+     * etc.), mappable reference (`{data.*}`), or literal.
+     *
+     * @param currentCell - The cell to resolve.
+     * @returns The resolved runtime value.
+     */
     resolveCellValue(currentCell: PipeItem): unknown;
     private getNestedProperty;
+    /**
+     * Resolves a `{data.*}` or `{activity.*}` reference by walking
+     * the dot-delimited path into {@link jobData}.
+     *
+     * @param currentCell - The mappable reference string (e.g. `{data.user.name}`).
+     */
     resolveMappableValue(currentCell: string): unknown;
     resolveContextValue(currentCell: string): unknown;
     resolveContextTerm(currentCell: string): string;

package/build/services/pipe/index.js

@@ -5,7 +5,358 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Pipe = void 0;
 const functions_1 = __importDefault(require("./functions"));
+/**
+ * A functional data-transformation pipeline that resolves expressions
+ * row-by-row against live job data.
+ *
+ * @remarks
+ * ## Overview
+ *
+ * Pipe is the engine behind HotMesh's `@pipe` syntax — a uniform,
+ * functional approach to data mapping and transformation. Every
+ * ECMAScript operation is expressed as a **function with inputs**,
+ * eliminating the syntactic variability of the language (ternaries,
+ * property access, instance methods) in favor of a single,
+ * composable pattern.
+ *
+ * ## Postfix notation (Reverse Polish Notation)
+ *
+ * If you've used an RPN calculator, `@pipe` will feel familiar.
+ * Operands come first, then the operator consumes them:
+ *
+ * ```
+ * RPN:   4  4  +   →  8
+ *
+ * @pipe:
+ *   - [4, 4]           ← operands
+ *   - ["{@math.add}"]  ← operator  →  8
+ * ```
+ *
+ * That's the entire model. Operands are pushed, an operator pops
+ * them, and the result becomes an operand for the next row.
+ *
+ * ## How it works — row by row
+ *
+ * A pipe is an ordered array of **rows**. Each row is an array of
+ * **cells**. The key rule: **every resolved value on a row flows
+ * into cell 0 of the next row** (the operator). The operator
+ * consumes all upstream operands, resolves to a new value, and
+ * that result *becomes an operand*. Any remaining cells on the
+ * same row are resolved independently and appended as additional
+ * operands. Then the cycle repeats.
+ *
+ * ```
+ * @pipe:
+ *   ┌──────────────────────────────────────┐
+ *   │ Row 0: [operand, operand, operand]   │  ← resolve all cells
+ *   │            │        │        │       │
+ *   │            └────────┼────────┘       │
+ *   │                     │                │
+ *   ├─────────────────────┼────────────────┤
+ *   │                     ▼                │
+ *   │ Row 1: [  OPERATOR  , operand]       │  ← ALL operands from Row 0
+ *   │         ▲ receives all ▲             │     flow into cell 0;
+ *   │         │ from above   │             │     result becomes operand;
+ *   │         └──────────────┘             │     remaining cells resolve
+ *   │              │            │          │
+ *   │              └────────────┘          │
+ *   │                     │                │
+ *   ├─────────────────────┼────────────────┤
+ *   │                     ▼                │
+ *   │ Row 2: [  OPERATOR  , operand]       │  ← same pattern repeats
+ *   └──────────────────────────────────────┘
+ *       ▼
+ *   final value = cell 0 of last row
+ * ```
+ *
+ * Step by step:
+ *
+ * 1. **Row 0** — Every cell is resolved independently (static
+ *    literals, `{data.*}` references, or nullary functions like
+ *    `{@date.now}`). The resolved values are all **operands**.
+ * 2. **Row 1** — Cell 0 is the **operator** (`{@domain.method}`).
+ *    It receives *all* operands from Row 0 as its arguments and
+ *    produces a result. That result replaces cell 0 — it is now
+ *    an operand. Any remaining cells (cell 1, 2, ...) on this row
+ *    are resolved independently and become additional operands.
+ * 3. **Row 2** — Cell 0 is the next operator. It receives *all*
+ *    operands from Row 1 (the prior result + any extra cells).
+ *    The cycle repeats.
+ * 4. **Return** — The first cell of the final row is the result.
+ *
+ * When an additional cell on an operator row needs computed (not
+ * just a static value or simple reference), use a **nested
+ * `@pipe`** (sub-pipe) to resolve it. See Example 4 below.
+ *
+ * ## Three types of cell values
+ *
+ * | Type | Syntax | Example |
+ * |------|--------|---------|
+ * | **Static** | literal | `42`, `"hello"`, `true` |
+ * | **Dynamic** | `{path}` | `{a.output.data.name}` |
+ * | **Function** | `{@domain.method}` | `{@string.concat}`, `{@math.add}` |
+ *
+ * ## Available function domains
+ *
+ * - **array** — `get`, `length`, `join`, `concat`, `push`, `indexOf`, ...
+ * - **bitwise** — `and`, `or`, `xor`, `not`, ...
+ * - **conditional** — `ternary`, `equality`, `nullish`, ...
+ * - **cron** — `nextDelay`
+ * - **date** — `now`, `toLocaleString`, `yyyymmdd`, ...
+ * - **json** — `parse`, `stringify`
+ * - **logical** — `and`, `or`, `not`
+ * - **math** — `add`, `multiply`, `pow`, `max`, `min`, `abs`, ...
+ * - **number** — `isEven`, `isOdd`, `gte`, `lte`, ...
+ * - **object** — `create`, `get`, `set`, `keys`, ...
+ * - **string** — `concat`, `split`, `charAt`, `toLowerCase`, `includes`, ...
+ * - **symbol**
+ * - **unary**
+ *
+ * ---
+ *
+ * ## Example 1 — Simple field mapping (YAML)
+ *
+ * Most fields need only a one-to-one reference. Curly braces pull
+ * values from upstream activity outputs:
+ *
+ * ```yaml
+ * # Map fields from activities a and b into a new shape
+ * maps:
+ *   first: "{a.output.data.first_name}"
+ *   last:  "{a.output.data.last_name}"
+ *   email: "{b.output.data.email}"
+ *   age:   "{b.output.data.age}"
+ *   company: "ACME Corp"        # static string
+ *   bonus:   500                 # static number
+ * ```
+ *
+ * The equivalent JavaScript object passed to the mapper:
+ *
+ * ```typescript
+ * const rules = {
+ *   first: '{a.output.data.first_name}',
+ *   last:  '{a.output.data.last_name}',
+ *   email: '{b.output.data.email}',
+ *   age:   '{b.output.data.age}',
+ *   company: 'ACME Corp',
+ *   bonus:   500,
+ * };
+ * ```
+ *
+ * ## Example 2 — String transformation (YAML → JS)
+ *
+ * Build a `user_name` like `jdoe` from "John Doe". Follow the
+ * RPN flow — operands feed into the operator on the next row,
+ * the result becomes an operand, extra cells append more operands:
+ *
+ * ```yaml
+ * user_name:
+ *   "@pipe":
+ *     - ["{a.output.data.first_name}", 0]
+ *     - ["{@string.charAt}", "{a.output.data.last_name}"]
+ *     - ["{@string.concat}"]
+ *     - ["{@string.toLowerCase}"]
+ * ```
+ *
+ * ```typescript
+ * // Identical logic in JavaScript
+ * const rules = {
+ *   user_name: {
+ *     '@pipe': [
+ *       ['{a.output.data.first_name}', 0],
+ *       ['{@string.charAt}', '{a.output.data.last_name}'],
+ *       ['{@string.concat}'],
+ *       ['{@string.toLowerCase}'],
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * RPN trace (given first_name="John", last_name="Doe"):
+ *
+ * ```
+ * Row 0: ["John", 0]            ← two operands
+ * Row 1: charAt("John", 0)="J"  ← operator consumes both → result "J"
+ *         then resolve "Doe"    ← extra cell → operands are ["J", "Doe"]
+ * Row 2: concat("J", "Doe")     ← operator → result "JDoe"
+ *                                  operands are ["JDoe"]
+ * Row 3: toLowerCase("JDoe")    ← operator → result "jdoe"
+ * ```
+ *
+ * ## Example 3 — Conditional logic (YAML → JS)
+ *
+ * Classify an employee as "Senior" or "Junior" based on age:
+ *
+ * ```yaml
+ * status:
+ *   "@pipe":
+ *     - ["{b.output.data.age}", 40]
+ *     - ["{@number.gte}", "Senior", "Junior"]
+ *     - ["{@conditional.ternary}"]
+ * ```
+ *
+ * ```typescript
+ * const rules = {
+ *   status: {
+ *     '@pipe': [
+ *       ['{b.output.data.age}', 40],
+ *       ['{@number.gte}', 'Senior', 'Junior'],
+ *       ['{@conditional.ternary}'],
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * RPN trace (given age=30):
+ *
+ * ```
+ * Row 0: [30, 40]                          ← two operands
+ * Row 1: gte(30, 40)=false                 ← operator consumes both → false
+ *         resolve "Senior", "Junior"       ← extra cells → [false, "Senior", "Junior"]
+ * Row 2: ternary(false, "Senior", "Junior") ← operator → "Junior"
+ * ```
+ *
+ * ## Example 4 — Nested pipes (fan-out / fan-in)
+ *
+ * Extract initials from a full name. Each nested `@pipe` runs
+ * independently (fan-out), then the first standard row after them
+ * receives all sub-pipe results as inputs (fan-in):
+ *
+ * ```yaml
+ * initials:
+ *   "@pipe":
+ *     - ["{a.output.data.full_name}", " "]
+ *     - "@pipe":                           # fan-out: first initial
+ *       - ["{@string.split}", 0]
+ *       - ["{@array.get}", 0]
+ *       - ["{@string.charAt}"]
+ *     - "@pipe":                           # fan-out: last initial
+ *       - ["{@string.split}", 1]
+ *       - ["{@array.get}", 0]
+ *       - ["{@string.charAt}"]
+ *     - ["{@string.concat}"]              # fan-in: combine both
+ * ```
+ *
+ * ```typescript
+ * const rules = {
+ *   initials: {
+ *     '@pipe': [
+ *       ['{a.output.data.full_name}', ' '],
+ *       { '@pipe': [['{@string.split}', 0], ['{@array.get}', 0], ['{@string.charAt}']] },
+ *       { '@pipe': [['{@string.split}', 1], ['{@array.get}', 0], ['{@string.charAt}']] },
+ *       ['{@string.concat}'],
+ *     ],
+ *   },
+ * };
+ * // "Luke Birdeau" → split → ["Luke","Birdeau"]
+ * //   sub-pipe 1: get(0) → "Luke" → charAt(0) → "L"
+ * //   sub-pipe 2: get(1) → "Birdeau" → charAt(0) → "B"
+ * // fan-in: concat("L", "B") → "LB"
+ * ```
+ *
+ * ## Example 5 — Reduce (iterate and accumulate)
+ *
+ * Transform an array of `{ full_name }` objects into
+ * `{ first, last }` pairs using `@reduce`. Context variables
+ * `{$item}`, `{$key}`, `{$index}`, `{$input}`, and `{$output}`
+ * are available inside the reducer body:
+ *
+ * ```typescript
+ * const jobData = {
+ *   a: { output: { data: [
+ *     { full_name: 'Luke Birdeau' },
+ *     { full_name: 'John Doe' },
+ *   ]}}
+ * };
+ *
+ * const rules = [
+ *   ['{a.output.data}', []],         // input array + initial accumulator
+ *   { '@reduce': [
+ *     { '@pipe': [['{$output}']] },  // carry forward accumulator
+ *     { '@pipe': [
+ *       { '@pipe': [['first']] },
+ *       { '@pipe': [
+ *         ['{$item.full_name}', ' '],
+ *         ['{@string.split}', 0],
+ *         ['{@array.get}'],
+ *       ]},
+ *       { '@pipe': [['last']] },
+ *       { '@pipe': [
+ *         ['{$item.full_name}', ' '],
+ *         ['{@string.split}', 1],
+ *         ['{@array.get}'],
+ *       ]},
+ *       ['{@object.create}'],
+ *     ]},
+ *     ['{@array.push}'],
+ *   ]},
+ * ];
+ * // => [{ first: 'Luke', last: 'Birdeau' }, { first: 'John', last: 'Doe' }]
+ * ```
+ *
+ * ## Example 6 — Transition conditions
+ *
+ * Pipes power conditional transitions between workflow activities.
+ * In YAML, a transition fires only when the `@pipe` resolves to the
+ * `expected` value:
+ *
+ * ```yaml
+ * transitions:
+ *   t1:
+ *     - to: a1
+ *       conditions:
+ *         match:
+ *           - expected: false
+ *             actual:
+ *               "@pipe":
+ *                 - ["{t1.output.data.a}", "goodbye"]
+ *                 - ["{@conditional.equality}"]
+ * ```
+ *
+ * ## Example 7 — Inline YAML with HotMesh.deploy
+ *
+ * HotMesh ships with an inline YAML parser, so a complete
+ * workflow with data mapping can be deployed in a single call:
+ *
+ * ```typescript
+ * await hotMesh.deploy(`
+ * app:
+ *   id: myapp
+ *   version: '1'
+ *   graphs:
+ *     - subscribes: order.process
+ *       activities:
+ *         t1:
+ *           type: trigger
+ *         a1:
+ *           type: worker
+ *           topic: inventory.check
+ *           input:
+ *             maps:
+ *               itemId: "{t1.output.data.itemId}"
+ *           output:
+ *             schema:
+ *               type: object
+ *           job:
+ *             maps:
+ *               result: "{$self.output.data.available}"
+ *       transitions:
+ *         t1:
+ *           - to: a1
+ * `);
+ *
+ * await hotMesh.activate('1');
+ * const response = await hotMesh.pubsub('order.process', { itemId: 'sku-42' });
+ * ```
+ */
 class Pipe {
+    /**
+     * @param rules   - The ordered row array defining the pipeline.
+     * @param jobData - The current job data used to resolve `{data.*}`
+     *   and `{activity.*}` references.
+     * @param context - Optional iteration context (`$item`, `$key`,
+     *   `$output`, etc.) supplied during `@reduce` execution.
+     */
     constructor(rules, jobData, context) {
         this.rules = rules;
         this.jobData = jobData;
@@ -17,12 +368,32 @@ class Pipe {
     isreduceType(currentRow) {
         return !Array.isArray(currentRow) && '@reduce' in currentRow;
     }
+    /**
+     * Returns `true` if the value is a `@pipe` object (i.e. `{ '@pipe': [...] }`).
+     *
+     * @param obj - The value to test.
+     */
     static isPipeObject(obj) {
         return (typeof obj === 'object' &&
             obj !== null &&
             !Array.isArray(obj) &&
             '@pipe' in obj);
     }
+    /**
+     * One-shot convenience method that resolves a single value or
+     * `@pipe` expression against the given context.
+     *
+     * @param unresolved - A literal value, a `{data.*}` reference string,
+     *   or a `@pipe` object.
+     * @param context - Partial {@link JobState} used for resolution.
+     * @returns The fully resolved value.
+     *
+     * @example
+     * ```typescript
+     * Pipe.resolve('{data.user.email}', jobState);
+     * Pipe.resolve({ '@pipe': [['{data.a}', '{data.b}'], ['{@math.multiply}']] }, jobState);
+     * ```
+     */
     static resolve(unresolved, context) {
         let pipe;
         if (Pipe.isPipeObject(unresolved)) {
@@ -34,8 +405,29 @@ class Pipe {
         return pipe.process();
     }
     /**
-     * loop through each PipeItem row in this Pipe, resolving and transforming line by line
-     * @returns {any} the result of the pipe
+     * Executes the pipeline row-by-row, resolving and transforming
+     * until the final value is produced.
+     *
+     * @remarks
+     * Row 0 is resolved independently (values only). Each subsequent
+     * row feeds the prior row's resolved output as arguments to the
+     * function named in cell 0. Nested `@pipe` rows are queued
+     * (fan-out) and collected into the next standard row (fan-in).
+     * `@reduce` rows iterate over the prior row's array output.
+     *
+     * @param resolved - Optional pre-resolved seed values (used
+     *   internally by `reduce` to inject the accumulator).
+     * @returns The first cell of the final resolved row.
+     *
+     * @example
+     * ```typescript
+     * // Split a full name and grab the first element
+     * const pipe = new Pipe(
+     *   [['{a.output.data.full_name}', ' '], ['{@string.split}', 0], ['{@array.get}']],
+     *   { a: { output: { data: { full_name: 'Luke Birdeau' } } } },
+     * );
+     * pipe.process(); // => 'Luke'
+     * ```
      */
     process(resolved = null) {
         let index = 0;
@@ -74,14 +466,26 @@ class Pipe {
         return clonedObj;
     }
     /**
-     * Transforms iterable `input` into a single value. Vars $output, $item, $key
-     * and $input are available. The final statement in the iterator (the reduction)
-     * is assumed to be the return value. A default $output object may be provided
-     * to the iterator by placing the the second cell of the preceding row. Otherwise,
-     * construct the object during first run and ensure it is the first cell of the
-     * last row of the iterator, so it is returned as the $output for the next cycle
-     * @param {unknown[]} input
-     * @returns {unknown}
+     * Iterates over an array or object and accumulates a result,
+     * similar to `Array.prototype.reduce`.
+     *
+     * @remarks
+     * Inside the reducer body the following context variables are
+     * available as cell references:
+     *
+     * | Variable | Description |
+     * |----------|-------------|
+     * | `{$input}` | The full input collection |
+     * | `{$output}` | The current accumulator |
+     * | `{$item}` | The current element |
+     * | `{$key}` | The current key (string for objects, index string for arrays) |
+     * | `{$index}` | The current numeric index |
+     *
+     * The preceding row supplies `[inputCollection, initialAccumulator]`.
+     * If no initial accumulator is provided, it defaults to `null`.
+     *
+     * @param input - A two-element array: `[collection, initialAccumulator]`.
+     * @returns The final accumulated value, wrapped in an array.
      * @private
      */
     reduce(input) {
@@ -152,6 +556,14 @@ class Pipe {
             }
         }
     }
+    /**
+     * Looks up a domain function by its `{@domain.method}` name string
+     * and returns the callable.
+     *
+     * @param functionName - A string like `{@math.add}` or `{@string.concat}`.
+     * @returns The resolved function reference.
+     * @throws If the domain or method is not registered.
+     */
     static resolveFunction(functionName) {
         let [prefix, suffix] = functionName.split('.');
         prefix = prefix.substring(2);
@@ -165,6 +577,14 @@ class Pipe {
         }
         return domain[suffix];
     }
+    /**
+     * Resolves every cell in a single row independently — each cell
+     * is evaluated for function calls, context variables, or mappable
+     * references.
+     *
+     * @param cells - The array of {@link PipeItems} to resolve.
+     * @returns An array of resolved values, one per input cell.
+     */
     processCells(cells) {
         const resolved = [];
         if (Array.isArray(cells)) {
@@ -193,6 +613,14 @@ class Pipe {
             currentCell.startsWith('{') &&
             currentCell.endsWith('}'));
     }
+    /**
+     * Resolves a single cell value by detecting its type — function
+     * call (`{@domain.fn}`), context variable (`{$item}`, `{$key}`,
+     * etc.), mappable reference (`{data.*}`), or literal.
+     *
+     * @param currentCell - The cell to resolve.
+     * @returns The resolved runtime value.
+     */
     resolveCellValue(currentCell) {
         if (this.isFunction(currentCell)) {
             const fn = Pipe.resolveFunction(currentCell);
@@ -221,6 +649,12 @@ class Pipe {
         }
         return current;
     }
+    /**
+     * Resolves a `{data.*}` or `{activity.*}` reference by walking
+     * the dot-delimited path into {@link jobData}.
+     *
+     * @param currentCell - The mappable reference string (e.g. `{data.user.name}`).
+     */
     resolveMappableValue(currentCell) {
         const term = this.resolveMapTerm(currentCell);
         return this.getNestedProperty(this.jobData, term);

package/build/services/stream/registry.d.ts

@@ -23,6 +23,7 @@ declare class StreamConsumerRegistry {
     }, logger: ILogger, config?: {
         reclaimDelay?: number;
         reclaimCount?: number;
+        readonly?: boolean;
         retry?: any;
     }): Promise<void>;
     /**

package/build/services/stream/registry.js

@@ -29,6 +29,7 @@ class StreamConsumerRegistry {
                 topic: taskQueue,
                 reclaimDelay: config?.reclaimDelay,
                 reclaimCount: config?.reclaimCount,
+                readonly: config?.readonly || false,
                 throttle,
                 retry: config?.retry,
             }, stream, logger);
@@ -39,14 +40,17 @@ class StreamConsumerRegistry {
                 logger,
             };
             StreamConsumerRegistry.workerConsumers.set(key, entry);
-            // Create the dispatch callback that routes by workflow_name
-            const dispatchCallback = StreamConsumerRegistry.createWorkerDispatcher(key);
-            // Start consuming from the task queue stream
-            const streamKey = stream.mintKey(key_1.KeyType.STREAMS, {
-                appId,
-                topic: taskQueue,
-            });
-            router.consumeMessages(streamKey, 'WORKER', guid, dispatchCallback);
+            // Only start consuming if not readonly
+            if (!config?.readonly) {
+                // Create the dispatch callback that routes by workflow_name
+                const dispatchCallback = StreamConsumerRegistry.createWorkerDispatcher(key);
+                // Start consuming from the task queue stream
+                const streamKey = stream.mintKey(key_1.KeyType.STREAMS, {
+                    appId,
+                    topic: taskQueue,
+                });
+                router.consumeMessages(streamKey, 'WORKER', guid, dispatchCallback);
+            }
         }
         // Register the callback for this workflow name
         entry.callbacks.set(workflowName, callback);

package/build/services/worker/index.js

@@ -51,6 +51,7 @@ class WorkerService {
                     await registry_1.StreamConsumerRegistry.registerWorker(namespace, appId, guid, worker.topic, worker.workflowName, worker.callback, service.stream, service.store, logger, {
                         reclaimDelay: worker.reclaimDelay,
                         reclaimCount: worker.reclaimCount,
+                        readonly: worker.readonly,
                         retry: worker.retry,
                     });
                     // Still need a router for publishing responses back to engine
@@ -114,6 +115,7 @@ class WorkerService {
             reclaimDelay: worker.reclaimDelay,
             reclaimCount: worker.reclaimCount,
             throttle,
+            readonly: worker.readonly || false,
             retry: worker.retry,
         }, this.stream, logger);
     }

package/build/types/hotmesh.d.ts

@@ -284,6 +284,14 @@ type HotMeshWorker = {
         user: string;
         password: string;
     };
+    /**
+     * If true, the worker's router will not consume messages from the
+     * stream. The worker can still publish responses but will never
+     * dequeue or process messages. This is inherited from the
+     * connection's `readonly` flag by the Durable layer.
+     * @default false
+     */
+    readonly?: boolean;
 };
 type HotMeshConfig = {
     appId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -14,8 +14,8 @@
     "obfuscate": "ts-node scripts/obfuscate.ts",
     "clean-build": "npm run clean && npm run build",
     "clean-build-obfuscate": "npm run clean-build && npm run obfuscate",
-    "docs": "typedoc",
-    "docs:clean": "rimraf ./docs/hotmesh && typedoc",
+    "docs": "typedoc && cp -R docs/hotmesh/* docs/ && rm -rf docs/hotmesh",
+    "docs:clean": "rimraf ./docs/hotmesh && typedoc && cp -R docs/hotmesh/* docs/ && rm -rf docs/hotmesh",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --fix --ext .ts",
     "start": "ts-node src/index.ts",
@@ -47,6 +47,7 @@
     "test:durable:retrypolicy": "vitest run tests/durable/retry-policy",
     "test:durable:sleep": "vitest run tests/durable/sleep/postgres.test.ts",
     "test:durable:signal": "vitest run tests/durable/signal/postgres.test.ts",
+    "test:durable:readonly": "docker compose --profile readonly up -d --build && docker compose exec hotmesh-readonly npx vitest run --config tests/durable/readonly/vitest.config.mts",
     "test:durable:unknown": "vitest run tests/durable/unknown/postgres.test.ts",
     "test:durable:exporter": "HMSH_LOGLEVEL=info vitest run tests/durable/exporter",
     "test:durable:exporter:debug": "EXPORT_DEBUG=1 HMSH_LOGLEVEL=error vitest run tests/durable/basic/postgres.test.ts",

package/vitest.config.mts

@@ -5,7 +5,7 @@ export default defineConfig({
     globals: true,
     environment: 'node',
     include: ['tests/**/*.test.ts'],
-    exclude: ['node_modules', 'build', 'config'],
+    exclude: ['node_modules', 'build', 'config', 'tests/durable/readonly/**'],
     testTimeout: 60_000,
     hookTimeout: 120_000,
     fileParallelism: false,