@hotmeshio/hotmesh 0.14.3 → 0.14.5

package/build/modules/enums.d.ts

@@ -55,6 +55,12 @@ export declare const HMSH_TELEMETRY: "debug" | "info";
  * Default cleanup time for signal in the db when its associated job is completed.
  */
 export declare const HMSH_SIGNAL_EXPIRE = 3600;
+/**
+ * Default TTL for pending signals (signals that arrived before the hook registered).
+ * The signaler can override this via the `$expire` field in the signal data
+ * using a natural-language duration (e.g., '1h', '24h').
+ */
+export declare const HMSH_PENDING_SIGNAL_EXPIRE = 600;
 export declare const HMSH_CODE_SUCCESS = 200;
 export declare const HMSH_CODE_PENDING = 202;
 export declare const HMSH_CODE_NOTFOUND = 404;

package/build/modules/enums.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HMSH_GUID_SIZE = exports.HMSH_ROUTER_SCOUT_INTERVAL_MS = exports.HMSH_ROUTER_SCOUT_INTERVAL_SECONDS = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
-exports.HMSH_ROUTER_POLL_FALLBACK_INTERVAL = exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = void 0;
+exports.HMSH_ROUTER_SCOUT_INTERVAL_MS = exports.HMSH_ROUTER_SCOUT_INTERVAL_SECONDS = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_PENDING_SIGNAL_EXPIRE = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
+exports.HMSH_ROUTER_POLL_FALLBACK_INTERVAL = exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = void 0;
 /**
  * Determines the log level for the application. The default is 'info'.
  */
@@ -58,6 +58,12 @@ exports.HMSH_TELEMETRY = process.env.HMSH_TELEMETRY || 'info';
  * Default cleanup time for signal in the db when its associated job is completed.
  */
 exports.HMSH_SIGNAL_EXPIRE = 3600; //seconds
+/**
+ * Default TTL for pending signals (signals that arrived before the hook registered).
+ * The signaler can override this via the `$expire` field in the signal data
+ * using a natural-language duration (e.g., '1h', '24h').
+ */
+exports.HMSH_PENDING_SIGNAL_EXPIRE = 600; //seconds (10 minutes)
 // HOTMESH STATUS CODES
 exports.HMSH_CODE_SUCCESS = 200;
 exports.HMSH_CODE_PENDING = 202;

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.14.3",
+    "version": "0.14.5",
     "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/activities/hook.d.ts

@@ -152,9 +152,18 @@ declare class Hook extends Activity {
     isConfiguredAsHook(): boolean;
     doesHook(): boolean;
     doHook(telemetry: TelemetryService): Promise<void>;
+    /**
+     * Re-publishes a pending signal as a WEBHOOK stream message so the
+     * normal leg2 dispatch path processes it. Called when leg1's
+     * setHookSignal atomically detected and consumed a pending signal.
+     */
+    private redeliverPendingSignal;
     doPassThrough(telemetry: TelemetryService): Promise<void>;
     getHookRule(topic: string): Promise<HookRule | undefined>;
-    registerHook(transaction?: ProviderTransaction): Promise<string | void>;
+    registerHook(transaction?: ProviderTransaction): Promise<{
+        jobId?: string;
+        pending?: string;
+    } | void>;
     processWebHookEvent(status?: StreamStatus, code?: StreamCode): Promise<JobStatus | void>;
     processTimeHookEvent(jobId: string): Promise<JobStatus | void>;
 }

package/build/services/activities/hook.js

@@ -6,6 +6,7 @@ const pipe_1 = require("../pipe");
 const task_1 = require("../task");
 const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
+const utils_1 = require("../../modules/utils");
 const activity_1 = require("./activity");
 /**
  * A versatile pause/resume activity that supports three distinct patterns:
@@ -203,7 +204,7 @@ class Hook extends activity_1.Activity {
     }
     async doHook(telemetry) {
         const transaction = this.store.transact();
-        await this.registerHook(transaction);
+        const hookResult = await this.registerHook(transaction);
         this.mapOutputData();
         this.mapJobData();
         await this.setState(transaction);
@@ -211,6 +212,38 @@ class Hook extends activity_1.Activity {
         await this.setStatus(0, transaction);
         await transaction.exec();
         telemetry.mapActivityAttributes();
+        //if a pending signal was detected (signal arrived before hook
+        //registered), re-publish the WEBHOOK so leg2 processes it
+        //now that the hook signal is committed and state is saved
+        if (hookResult && hookResult.pending) {
+            await this.redeliverPendingSignal(hookResult.pending);
+        }
+    }
+    /**
+     * Re-publishes a pending signal as a WEBHOOK stream message so the
+     * normal leg2 dispatch path processes it. Called when leg1's
+     * setHookSignal atomically detected and consumed a pending signal.
+     */
+    async redeliverPendingSignal(pendingJson) {
+        const data = JSON.parse(pendingJson);
+        const hookRule = await this.getHookRule(this.config.hook.topic);
+        this.logger.warn('hook-pending-signal-redelivery', {
+            topic: this.config.hook.topic,
+            aid: hookRule?.to || this.metadata.aid,
+            jid: this.context.metadata.jid,
+        });
+        const streamData = {
+            type: stream_1.StreamDataType.WEBHOOK,
+            status: stream_1.StreamStatus.SUCCESS,
+            code: 200,
+            metadata: {
+                guid: (0, utils_1.guid)(),
+                aid: hookRule?.to || this.metadata.aid,
+                topic: this.config.hook.topic,
+            },
+            data,
+        };
+        await this.engine.router?.publishMessage(null, streamData);
     }
     async doPassThrough(telemetry) {
         this.adjacencyList = await this.filterAdjacent();
@@ -225,19 +258,25 @@ class Hook extends activity_1.Activity {
         return rules?.[topic]?.[0];
     }
     async registerHook(transaction) {
-        let result;
+        let jobId;
+        let pending;
         if (this.config.hook?.topic) {
-            result = await this.engine.taskService.registerWebHook(this.config.hook.topic, this.context, this.resolveDad(), this.context.metadata.expire, transaction);
+            //hook signal is set standalone (not in the transaction) so the
+            //single CTE query can atomically detect a pending signal collision
+            const hookResult = await this.engine.taskService.registerWebHook(this.config.hook.topic, this.context, this.resolveDad(), this.context.metadata.expire);
+            jobId = hookResult.jobId;
+            pending = hookResult.pending;
         }
         if (this.config.sleep) {
             const duration = pipe_1.Pipe.resolve(this.config.sleep, this.context);
             if (!isNaN(duration) && Number(duration) > 0) {
                 await this.engine.taskService.registerTimeHook(this.context.metadata.jid, this.context.metadata.gid, `${this.metadata.aid}${this.metadata.dad || ''}`, 'sleep', duration, this.metadata.dad || '', transaction);
-                if (!result)
-                    result = this.context.metadata.jid;
+                if (!jobId)
+                    jobId = this.context.metadata.jid;
             }
         }
-        return result;
+        if (jobId)
+            return { jobId, pending };
     }
     async processWebHookEvent(status = stream_1.StreamStatus.SUCCESS, code = 200) {
         this.logger.debug('hook-process-web-hook-event', {

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

@@ -14,6 +14,7 @@ import { PostgresClientType } from '../../types/postgres';
  * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `status`, `other`) that are only needed during workflow execution |
  * | `{appId}.engine_streams` | Processed engine stream messages with `expired_at` set |
  * | `{appId}.worker_streams` | Processed worker stream messages with `expired_at` set |
+ * | `{appId}.signal_registry` | Consumed hook signals and stale pending signals with `expiry` set |
  *
  * The `DBA` service addresses this with two methods:
  *

package/build/services/dba/index.js

@@ -17,6 +17,7 @@ const postgres_1 = require("../connector/providers/postgres");
  * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `status`, `other`) that are only needed during workflow execution |
  * | `{appId}.engine_streams` | Processed engine stream messages with `expired_at` set |
  * | `{appId}.worker_streams` | Processed worker stream messages with `expired_at` set |
+ * | `{appId}.signal_registry` | Consumed hook signals and stale pending signals with `expiry` set |
  *
  * The `DBA` service addresses this with two methods:
  *
@@ -186,7 +187,8 @@ class DBA {
         prune_engine_streams BOOLEAN DEFAULT NULL,
         prune_worker_streams BOOLEAN DEFAULT NULL,
         engine_streams_retention INTERVAL DEFAULT NULL,
-        worker_streams_retention INTERVAL DEFAULT NULL
+        worker_streams_retention INTERVAL DEFAULT NULL,
+        prune_signals BOOLEAN DEFAULT TRUE
       )
       RETURNS TABLE(
         deleted_jobs BIGINT,
@@ -195,7 +197,8 @@ class DBA {
         deleted_worker_streams BIGINT,
         stripped_attributes BIGINT,
         deleted_transient BIGINT,
-        marked_pruned BIGINT
+        marked_pruned BIGINT,
+        deleted_signals BIGINT
       )
       LANGUAGE plpgsql
       AS $$
@@ -206,6 +209,7 @@ class DBA {
         v_stripped_attributes BIGINT := 0;
         v_deleted_transient BIGINT := 0;
         v_marked_pruned BIGINT := 0;
+        v_deleted_signals BIGINT := 0;
         v_do_engine BOOLEAN;
         v_do_worker BOOLEAN;
         v_engine_retention INTERVAL;
@@ -287,6 +291,15 @@ class DBA {
           GET DIAGNOSTICS v_marked_pruned = ROW_COUNT;
         END IF;
 
+        -- 6. Hard-delete expired signal_registry rows.
+        --    Includes consumed hook signals and stale pending signals.
+        IF prune_signals THEN
+          DELETE FROM ${schema}.signal_registry
+          WHERE expiry IS NOT NULL
+            AND expiry <= NOW();
+          GET DIAGNOSTICS v_deleted_signals = ROW_COUNT;
+        END IF;
+
         deleted_jobs := v_deleted_jobs;
         deleted_streams := v_deleted_engine_streams + v_deleted_worker_streams;
         deleted_engine_streams := v_deleted_engine_streams;
@@ -294,6 +307,7 @@ class DBA {
         stripped_attributes := v_stripped_attributes;
         deleted_transient := v_deleted_transient;
         marked_pruned := v_marked_pruned;
+        deleted_signals := v_deleted_signals;
         RETURN NEXT;
       END;
       $$;
@@ -391,12 +405,14 @@ class DBA {
         const workerStreams = options.workerStreams ?? null;
         const engineStreamsExpire = options.engineStreamsExpire ?? null;
         const workerStreamsExpire = options.workerStreamsExpire ?? null;
+        const signals = options.signals ?? true;
         await DBA.deploy(options.connection, options.appId);
         const { client, release } = await DBA.getClient(options.connection);
         try {
-            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean, $8::boolean, $9::boolean, $10::interval, $11::interval)`, [
+            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean, $8::boolean, $9::boolean, $10::interval, $11::interval, $12::boolean)`, [
                 expire, jobs, streams, attributes, entities, pruneTransient, keepHmark,
                 engineStreams, workerStreams, engineStreamsExpire, workerStreamsExpire,
+                signals,
             ]);
             const row = result.rows[0];
             return {
@@ -407,6 +423,7 @@ class DBA {
                 attributes: Number(row.stripped_attributes),
                 transient: Number(row.deleted_transient),
                 marked: Number(row.marked_pruned),
+                signals: Number(row.deleted_signals),
             };
         }
         finally {

package/build/services/durable/client.js

@@ -156,11 +156,21 @@ class ClientService {
                 return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, jobId);
             },
             /**
-             * Sends a message payload to a running workflow that is paused and awaiting the signal
+             * Sends a message payload to a running workflow that is paused and awaiting the signal.
+             *
+             * If the signal arrives before the workflow has registered its hook
+             * (race condition under load), it is buffered as a pending signal
+             * for up to `expire` (default 10 minutes). Use a longer duration
+             * when signaling "early on purpose" (e.g., depositing a payload
+             * hours before the workflow starts).
              */
-            signal: async (signalId, data, namespace) => {
+            signal: async (signalId, data, namespace, expire) => {
                 const topic = `${namespace ?? factory_1.APP_ID}.wfs.signal`;
-                return await (await this.getHotMeshClient(topic, namespace)).signal(topic, { id: signalId, data });
+                return await (await this.getHotMeshClient(topic, namespace)).signal(topic, {
+                    id: signalId,
+                    data,
+                    ...(expire ? { $expire: expire } : {}),
+                });
             },
             /**
              * Spawns an a new, isolated execution cycle within the same job.

package/build/services/durable/handle.d.ts

@@ -57,10 +57,17 @@ export declare class WorkflowHandleService {
      * on `Durable.workflow.condition(signalId)`, it resumes with the
      * provided data.
      *
+     * If the signal arrives before the workflow has registered its hook
+     * (race condition under load), it is buffered as a pending signal
+     * for up to `expire` (default 10 minutes). Use a longer duration
+     * when signaling "early on purpose" (e.g., depositing a payload
+     * hours before the workflow starts).
+     *
      * @param signalId - Matches the `signalId` passed to `condition()`.
      * @param data - Payload delivered to the waiting workflow.
+     * @param expire - Optional pending signal TTL (e.g., '1h', '30d'). Default '10m'.
      */
-    signal(signalId: string, data: Record<any, any>): Promise<void>;
+    signal(signalId: string, data: Record<any, any>, expire?: string): Promise<void>;
     /**
      * Returns the current workflow state. For a completed workflow this
      * is the final output; for a running workflow it reflects the latest

package/build/services/durable/handle.js

@@ -58,13 +58,21 @@ class WorkflowHandleService {
      * on `Durable.workflow.condition(signalId)`, it resumes with the
      * provided data.
      *
+     * If the signal arrives before the workflow has registered its hook
+     * (race condition under load), it is buffered as a pending signal
+     * for up to `expire` (default 10 minutes). Use a longer duration
+     * when signaling "early on purpose" (e.g., depositing a payload
+     * hours before the workflow starts).
+     *
      * @param signalId - Matches the `signalId` passed to `condition()`.
      * @param data - Payload delivered to the waiting workflow.
+     * @param expire - Optional pending signal TTL (e.g., '1h', '30d'). Default '10m'.
      */
-    async signal(signalId, data) {
+    async signal(signalId, data, expire) {
         await this.hotMesh.signal(`${this.hotMesh.appId}.wfs.signal`, {
             id: signalId,
             data,
+            ...(expire ? { $expire: expire } : {}),
         });
     }
     /**

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/durable/workflow/signal.d.ts

@@ -55,4 +55,4 @@
  * @param {Record<any, any>} data - The payload to deliver to the waiting workflow.
  * @returns {Promise<string>} The resulting hook/stream ID.
  */
-export declare function signal(signalId: string, data: Record<any, any>): Promise<string>;
+export declare function signal(signalId: string, data: Record<any, any>, expire?: string): Promise<string>;

package/build/services/durable/workflow/signal.js

@@ -60,7 +60,7 @@ const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
  * @param {Record<any, any>} data - The payload to deliver to the waiting workflow.
  * @returns {Promise<string>} The resulting hook/stream ID.
  */
-async function signal(signalId, data) {
+async function signal(signalId, data, expire) {
     const store = common_1.asyncLocalStorage.getStore();
     const workflowTopic = store.get('workflowTopic');
     const connection = store.get('connection');
@@ -73,6 +73,7 @@ async function signal(signalId, data) {
         return await hotMeshClient.signal(`${namespace}.wfs.signal`, {
             id: signalId,
             data,
+            ...(expire ? { $expire: expire } : {}),
         });
     }
 }

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') {