@hotmeshio/hotmesh 0.14.2 → 0.14.4

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.14.2",
+    "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",
@@ -85,6 +86,7 @@
         "test:unit": "vitest run tests/unit"
     },
     "keywords": [
+        "Invisible Infrastructure",
         "Headless Orchestration",
         "Durable Workflows",
         "Data in Motion",

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/engine/init.js

@@ -30,7 +30,7 @@ async function initSearchChannel(instance, search, store) {
 }
 exports.initSearchChannel = initSearchChannel;
 async function initStoreChannel(instance, store) {
-    instance.store = await factory_2.StoreServiceFactory.init(store, instance.namespace, instance.appId, instance.logger);
+    instance.store = await factory_2.StoreServiceFactory.init(store, instance.namespace, instance.appId, instance.logger, instance.guid, 'engine');
 }
 exports.initStoreChannel = initStoreChannel;
 async function initSubChannel(instance, sub, store) {

package/build/services/engine/schema.js

@@ -16,7 +16,11 @@ const activities_1 = __importDefault(require("../activities"));
 async function initActivity(instance, topic, data = {}, context) {
     const [activityId, schema] = await getSchema(instance, topic);
     if (!schema) {
-        throw new Error(`Activity schema not found for "${activityId}" (topic: ${topic}) in app ${instance.appId}`);
+        const err = new Error(`Activity schema not found for "${activityId}" (topic: ${topic}) in app ${instance.appId}. ` +
+            `This is typically caused by a worker activity whose topic collides with the graph subscribes topic. ` +
+            `Redeploy with a distinct worker topic.`);
+        err.code = 598;
+        throw err;
     }
     const ActivityHandler = activities_1.default[schema.type];
     if (ActivityHandler) {

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