@camunda8/orchestration-cluster-api 8.9.0-alpha.22 → 8.9.0-alpha.23

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [8.9.0-alpha.23](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.22...v8.9.0-alpha.23) (2026-03-30)
+
+
+### Bug Fixes
+
+* address PR review comments ([fd357d5](https://github.com/camunda/orchestration-cluster-api-js/commit/fd357d5938dbb0e22d18711087b26560a802494c))
+* address PR review comments on heritable worker defaults ([efec39c](https://github.com/camunda/orchestration-cluster-api-js/commit/efec39c54c788f625f27f7be70c830321ff43ef6))
+* **config:** add signedInt schema type for CAMUNDA_WORKER_REQUEST_TIMEOUT ([9f9f794](https://github.com/camunda/orchestration-cluster-api-js/commit/9f9f7949e3b1cfcf90ab8abf723595276c41a18d))
+* **tests:** convert threaded handler fixtures to .js for Node 20 compat ([1e5f7b1](https://github.com/camunda/orchestration-cluster-api-js/commit/1e5f7b17931043adade84c7630264a1ed543cf2a))
+* **threadedJobWorker:** extract validated fields to fix TS strict null errors ([7097cbd](https://github.com/camunda/orchestration-cluster-api-js/commit/7097cbde12076b8ba0d35208cedf7ebe1c891493))
+* **threadPool:** don't pass TS strip flags to workers on Node < 22 ([dbf18d3](https://github.com/camunda/orchestration-cluster-api-js/commit/dbf18d3ab92ed1fd5fdf54988c1f613eaf7b09e3))
+* use number types for int config overrides in tests and examples ([f7bfa2f](https://github.com/camunda/orchestration-cluster-api-js/commit/f7bfa2f3d9be5152d4cf9a1ca6d0d4f8c117e14b))
+* wire README worker-defaults examples into snippet injection ([7759561](https://github.com/camunda/orchestration-cluster-api-js/commit/775956168f588dd02bf6e969ed641f3abb67e288))
+
+
+### Features
+
+* heritable worker defaults via CAMUNDA_WORKER_* env vars ([0311308](https://github.com/camunda/orchestration-cluster-api-js/commit/03113084fb15566bdf7d3bbb3d0d6e78ef582584))
+
 # [8.9.0-alpha.22](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.21...v8.9.0-alpha.22) (2026-03-30)
 
 

package/README.md

@@ -613,11 +613,14 @@ To deny a task completion (reject the work):
 <!-- snippet:ReadmeJobCorrectionsDenial -->
 
 ```ts
-return job.complete({}, {
-  type: 'userTask',
-  denied: true,
-  deniedReason: 'Insufficient documentation',
-});
+return job.complete(
+  {},
+  {
+    type: 'userTask',
+    denied: true,
+    deniedReason: 'Insufficient documentation',
+  }
+);
 ```
 
 | Correctable attribute | Type | Clear value |
@@ -690,6 +693,61 @@ client.createJobWorker({
 
 A value of `0` (the default) means no delay.
 
+### Heritable Worker Defaults
+
+When running many workers with the same base configuration, you can set global defaults via environment variables (or equivalent keys in `CamundaOptions.config`). These apply to every worker created by the client (both `createJobWorker` and `createThreadedJobWorker`) unless the individual worker config explicitly overrides them.
+
+| Environment Variable                       | Worker Config Field        | Type   |
+| ------------------------------------------ | -------------------------- | ------ |
+| `CAMUNDA_WORKER_TIMEOUT`                   | `jobTimeoutMs`             | number |
+| `CAMUNDA_WORKER_MAX_CONCURRENT_JOBS`       | `maxParallelJobs`          | number |
+| `CAMUNDA_WORKER_REQUEST_TIMEOUT`           | `pollTimeoutMs`            | number |
+| `CAMUNDA_WORKER_NAME`                      | `workerName`               | string |
+| `CAMUNDA_WORKER_STARTUP_JITTER_MAX_SECONDS`| `startupJitterMaxSeconds`  | number |
+
+**Precedence:** explicit worker config value > `CAMUNDA_WORKER_*` (from environment variables or `CamundaOptions.config` overrides) > hardcoded default (where applicable).
+
+Example — set defaults via environment:
+
+```bash
+export CAMUNDA_WORKER_TIMEOUT=30000
+export CAMUNDA_WORKER_MAX_CONCURRENT_JOBS=8
+export CAMUNDA_WORKER_NAME=order-service
+```
+
+<!-- snippet:ReadmeWorkerDefaultsEnv -->
+```ts
+// Workers inherit timeout, concurrency, and name from environment
+const w1 = client.createJobWorker({
+  jobType: 'validate-order',
+  jobHandler: async (job) => job.complete(),
+});
+
+const w2 = client.createJobWorker({
+  jobType: 'ship-order',
+  jobHandler: async (job) => job.complete(),
+});
+
+// Per-worker override: this worker uses 32 concurrent jobs instead of the global 8
+const w3 = client.createJobWorker({
+  jobType: 'bulk-import',
+  maxParallelJobs: 32,
+  jobHandler: async (job) => job.complete(),
+});
+```
+
+You can also pass defaults programmatically via the client constructor:
+
+<!-- snippet:ReadmeWorkerDefaultsClient -->
+```ts
+const client = createCamundaClient({
+  config: {
+    CAMUNDA_WORKER_TIMEOUT: 30000,
+    CAMUNDA_WORKER_MAX_CONCURRENT_JOBS: 8,
+  },
+});
+```
+
 ### Receipt Type (Unique Symbol)
 
 Action methods return a unique symbol (not a string) to avoid accidental misuse and allow internal metrics. If you store the receipt, annotate its type as `JobActionReceipt` to preserve uniqueness:

package/dist/{chunk-7IUDW222.js → chunk-W7A45XXW.js}

@@ -118,6 +118,8 @@ var DEFAULT_LONGPOLL_TIMEOUT = 0;
 var JobWorker = class {
   _client;
   _cfg;
+  _maxParallelJobs;
+  _jobTimeoutMs;
   _name;
   _activeJobs = 0;
   _stopped = false;
@@ -128,6 +130,18 @@ var JobWorker = class {
   constructor(client2, cfg) {
     this._client = client2;
     this._cfg = { pollIntervalMs: 1, autoStart: true, validateSchemas: false, ...cfg };
+    if (this._cfg.maxParallelJobs === void 0) {
+      throw new Error(
+        "maxParallelJobs is required: set it on JobWorkerConfig or via CAMUNDA_WORKER_MAX_CONCURRENT_JOBS (environment variable or CamundaOptions.config override)."
+      );
+    }
+    if (this._cfg.jobTimeoutMs === void 0) {
+      throw new Error(
+        "jobTimeoutMs is required: set it on JobWorkerConfig or via CAMUNDA_WORKER_TIMEOUT (environment variable or CamundaOptions.config override)."
+      );
+    }
+    this._maxParallelJobs = this._cfg.maxParallelJobs;
+    this._jobTimeoutMs = this._cfg.jobTimeoutMs;
     this._name = cfg.workerName || `worker-${cfg.jobType}-${++_workerCounter}`;
     this._log = this._client.logger().scope(`worker:${this._name}`);
     if (cfg.maxBackoffTimeMs !== void 0) {
@@ -222,11 +236,11 @@ var JobWorker = class {
   async _poll() {
     this._pollTimer = null;
     if (this._stopped) return;
-    if (this._activeJobs >= this._cfg.maxParallelJobs) {
+    if (this._activeJobs >= this._maxParallelJobs) {
       this._scheduleNext(this._cfg.pollIntervalMs);
       return;
     }
-    const batchSize = this._cfg.maxParallelJobs - this._activeJobs;
+    const batchSize = this._maxParallelJobs - this._activeJobs;
     if (batchSize <= 0) {
       this._scheduleNext(this._cfg.pollIntervalMs);
       return;
@@ -236,7 +250,7 @@ var JobWorker = class {
       worker: this._name,
       maxJobsToActivate: batchSize,
       requestTimeout: this._cfg.pollTimeoutMs ?? DEFAULT_LONGPOLL_TIMEOUT,
-      timeout: this._cfg.jobTimeoutMs,
+      timeout: this._jobTimeoutMs,
       // API expects `fetchVariable`; map from config `fetchVariables`
       ...this._cfg.fetchVariables && this._cfg.fetchVariables.length > 0 ? { fetchVariable: this._cfg.fetchVariables } : {}
     };
@@ -3651,6 +3665,27 @@ var SCHEMA = {
     type: "boolean",
     default: false,
     doc: "Alias for CAMUNDA_SUPPORT_LOG_ENABLED (deprecated)."
+  },
+  // Worker defaults (heritable to all workers created via createJobWorker/createThreadedJobWorker)
+  CAMUNDA_WORKER_TIMEOUT: {
+    type: "int",
+    doc: "Default job timeout in ms for all workers. Individual JobWorkerConfig.jobTimeoutMs overrides this."
+  },
+  CAMUNDA_WORKER_MAX_CONCURRENT_JOBS: {
+    type: "int",
+    doc: "Default max parallel jobs for all workers. Individual JobWorkerConfig.maxParallelJobs overrides this."
+  },
+  CAMUNDA_WORKER_REQUEST_TIMEOUT: {
+    type: "signedInt",
+    doc: "Default long-poll timeout in ms for all workers. Negative values cause activation to complete immediately when no jobs are available. Individual JobWorkerConfig.pollTimeoutMs overrides this."
+  },
+  CAMUNDA_WORKER_NAME: {
+    type: "string",
+    doc: "Default worker name for all workers. Individual JobWorkerConfig.workerName overrides this."
+  },
+  CAMUNDA_WORKER_STARTUP_JITTER_MAX_SECONDS: {
+    type: "int",
+    doc: "Default startup jitter in seconds for all workers. Individual JobWorkerConfig.startupJitterMaxSeconds overrides this."
   }
 };
 function isSecret(key) {
@@ -3714,6 +3749,17 @@ function parseInteger(raw, key, errors) {
   });
   return void 0;
 }
+function parseSignedInteger(raw, key, errors) {
+  const v = raw.trim();
+  if (v === "") return void 0;
+  if (/^-?[0-9]+$/.test(v)) return parseInt(v, 10);
+  errors.push({
+    code: "CONFIG_INVALID_INTEGER" /* CONFIG_INVALID_INTEGER */,
+    key,
+    message: `Invalid integer '${raw}'. Only base-10 integers (optionally negative) allowed.`
+  });
+  return void 0;
+}
 function parseValidation(raw, errors) {
   const val = raw.trim();
   if (val === "") return { req: "none", res: "none", raw: "req:none,res:none" };
@@ -3800,6 +3846,13 @@ function hydrateConfig(options = {}) {
       return parsed;
     };
   }
+  function signedIntParserFactory(key) {
+    return (v) => {
+      const parsed = parseSignedInteger(v, key, parseErrors);
+      if (parsed === void 0) return void 0;
+      return parsed;
+    };
+  }
   function enumParserFactory(key, choices) {
     const lowered = choices.map((c) => c.toLowerCase());
     const allLower = choices.every((c) => c === c.toLowerCase());
@@ -3835,6 +3888,10 @@ function hydrateConfig(options = {}) {
       const base = { parser: intParserFactory(k), ...baseOpt };
       if (entry.default !== void 0) base.default = entry.default;
       typedEnvSchema[k] = base;
+    } else if (entry.type === "signedInt") {
+      const base = { parser: signedIntParserFactory(k), ...baseOpt };
+      if (entry.default !== void 0) base.default = entry.default;
+      typedEnvSchema[k] = base;
     } else if (entry.type === "enum") {
       const base = { parser: enumParserFactory(k, entry.choices || []), ...baseOpt };
       if (entry.default !== void 0) base.default = entry.default;
@@ -4097,6 +4154,13 @@ function hydrateConfig(options = {}) {
       enabled: (rawMap.CAMUNDA_SUPPORT_LOG_ENABLED || "false").toString().toLowerCase() === "true",
       filePath: rawMap.CAMUNDA_SUPPORT_LOG_FILE_PATH || (typeof process !== "undefined" && typeof process.cwd === "function" ? path.join(process.cwd(), "camunda-support.log") : "camunda-support.log")
     },
+    workerDefaults: rawMap.CAMUNDA_WORKER_TIMEOUT || rawMap.CAMUNDA_WORKER_MAX_CONCURRENT_JOBS || rawMap.CAMUNDA_WORKER_REQUEST_TIMEOUT || rawMap.CAMUNDA_WORKER_NAME || rawMap.CAMUNDA_WORKER_STARTUP_JITTER_MAX_SECONDS ? {
+      jobTimeoutMs: rawMap.CAMUNDA_WORKER_TIMEOUT ? parseInt(rawMap.CAMUNDA_WORKER_TIMEOUT, 10) : void 0,
+      maxParallelJobs: rawMap.CAMUNDA_WORKER_MAX_CONCURRENT_JOBS ? parseInt(rawMap.CAMUNDA_WORKER_MAX_CONCURRENT_JOBS, 10) : void 0,
+      pollTimeoutMs: rawMap.CAMUNDA_WORKER_REQUEST_TIMEOUT ? parseInt(rawMap.CAMUNDA_WORKER_REQUEST_TIMEOUT, 10) : void 0,
+      workerName: rawMap.CAMUNDA_WORKER_NAME || void 0,
+      startupJitterMaxSeconds: rawMap.CAMUNDA_WORKER_STARTUP_JITTER_MAX_SECONDS ? parseInt(rawMap.CAMUNDA_WORKER_STARTUP_JITTER_MAX_SECONDS, 10) : void 0
+    } : void 0,
     __raw: { ...rawMap }
   };
   deepFreeze(config);
@@ -4343,7 +4407,7 @@ function installAuthInterceptor(client2, getStrategy, getAuthHeaders) {
 }
 
 // src/runtime/version.ts
-var packageVersion = "8.9.0-alpha.22";
+var packageVersion = "8.9.0-alpha.23";
 
 // src/runtime/supportLogger.ts
 var NoopSupportLogger = class {
@@ -5440,6 +5504,8 @@ var ThreadedJobWorker = class {
   _client;
   _pool;
   _cfg;
+  _maxParallelJobs;
+  _jobTimeoutMs;
   _name;
   _activeJobs = 0;
   _stopped = false;
@@ -5451,6 +5517,18 @@ var ThreadedJobWorker = class {
     this._client = client2;
     this._pool = pool;
     this._cfg = { pollIntervalMs: 1, autoStart: true, validateSchemas: false, ...cfg };
+    if (this._cfg.maxParallelJobs === void 0) {
+      throw new Error(
+        "maxParallelJobs is required: set it on ThreadedJobWorkerConfig or via CAMUNDA_WORKER_MAX_CONCURRENT_JOBS (environment variable or CamundaOptions.config override)."
+      );
+    }
+    if (this._cfg.jobTimeoutMs === void 0) {
+      throw new Error(
+        "jobTimeoutMs is required: set it on ThreadedJobWorkerConfig or via CAMUNDA_WORKER_TIMEOUT (environment variable or CamundaOptions.config override)."
+      );
+    }
+    this._maxParallelJobs = this._cfg.maxParallelJobs;
+    this._jobTimeoutMs = this._cfg.jobTimeoutMs;
     this._name = cfg.workerName || `threaded-worker-${cfg.jobType}-${++_workerCounter2}`;
     this._log = this._client.logger().scope(`worker:${this._name}`);
     this._pool.onThreadReady = () => this._drainQueue();
@@ -5633,11 +5711,11 @@ var ThreadedJobWorker = class {
     this._pollTimer = null;
     if (this._stopped) return;
     await this._pool.ready;
-    if (this._activeJobs >= this._cfg.maxParallelJobs) {
+    if (this._activeJobs >= this._maxParallelJobs) {
       this._scheduleNext(this._cfg.pollIntervalMs);
       return;
     }
-    const batchSize = this._cfg.maxParallelJobs - this._activeJobs;
+    const batchSize = this._maxParallelJobs - this._activeJobs;
     if (batchSize <= 0) {
       this._scheduleNext(this._cfg.pollIntervalMs);
       return;
@@ -5647,7 +5725,7 @@ var ThreadedJobWorker = class {
       worker: this._name,
       maxJobsToActivate: batchSize,
       requestTimeout: this._cfg.pollTimeoutMs ?? DEFAULT_LONGPOLL_TIMEOUT2,
-      timeout: this._cfg.jobTimeoutMs,
+      timeout: this._jobTimeoutMs,
       ...this._cfg.fetchVariables && this._cfg.fetchVariables.length > 0 ? { fetchVariable: this._cfg.fetchVariables } : {}
     };
     this._log.debug(() => ["activation.request", { batchSize }]);
@@ -5773,7 +5851,6 @@ var ThreadPool = class {
   _ready;
   _terminated = false;
   _entryPath = "";
-  _execArgv = [];
   _Worker;
   _onThreadReady;
   constructor(client2, size) {
@@ -5872,7 +5949,7 @@ var ThreadPool = class {
   }
   /** Create a single worker thread and wire up its event handlers. */
   _spawnWorker() {
-    const worker = new this._Worker(this._entryPath, { execArgv: this._execArgv });
+    const worker = new this._Worker(this._entryPath);
     const pw = { worker, busy: false, ready: false };
     worker.on("message", (msg) => {
       if (msg.type === "ready") {
@@ -5949,19 +6026,21 @@ var ThreadPool = class {
     const url = await import("url");
     const dir = typeof __dirname !== "undefined" ? __dirname : pathMod.dirname(url.fileURLToPath(import.meta.url));
     const jsPath = join(dir, "threadWorkerEntry.js");
-    const tsPath = join(dir, "threadWorkerEntry.ts");
-    const entryPath = fs.existsSync(jsPath) ? jsPath : tsPath;
-    const nodeMajor = parseInt(process.versions.node, 10);
-    this._execArgv = entryPath.endsWith(".ts") || nodeMajor >= 22 ? [
-      "--experimental-strip-types",
-      "--experimental-transform-types",
-      "--disable-warning=ExperimentalWarning"
-    ] : [];
-    this._entryPath = entryPath;
+    if (fs.existsSync(jsPath)) {
+      this._entryPath = jsPath;
+    } else {
+      const distPath = pathMod.resolve(dir, "..", "..", "dist", "threadWorkerEntry.js");
+      if (!fs.existsSync(distPath)) {
+        throw new Error(
+          `threadWorkerEntry.js not found at ${jsPath} or ${distPath}. Run "npm run build" first.`
+        );
+      }
+      this._entryPath = distPath;
+    }
     for (let i = 0; i < size; i++) {
       this._pool.push(this._spawnWorker());
     }
-    this._log.info(() => ["thread-pool.init", { size, entryPath }]);
+    this._log.info(() => ["thread-pool.init", { size, entryPath: this._entryPath }]);
   }
 };
 
@@ -16340,6 +16419,11 @@ var CamundaClient = class {
   // === AUTO-GENERATED CAMUNDA METHODS END ===
   /**
    * Create a job worker that activates and processes jobs of the given type.
+   *
+   * Worker configuration fields inherit global defaults resolved via the
+   * unified configuration (environment variables or equivalent `CAMUNDA_WORKER_*`
+   * keys provided via `CamundaOptions.config`) when not explicitly set on the
+   * config object.
    * @param cfg Worker configuration
    * @example Create a job worker
    * {@includeCode ../../examples/job.ts#CreateJobWorker}
@@ -16347,7 +16431,16 @@ var CamundaClient = class {
    * {@includeCode ../../examples/job.ts#JobWorkerWithErrorHandling}
    */
   createJobWorker(cfg) {
-    const worker = new JobWorker(this, cfg);
+    const defaults = this._config.workerDefaults;
+    const merged = defaults ? {
+      ...cfg,
+      jobTimeoutMs: cfg.jobTimeoutMs ?? defaults.jobTimeoutMs,
+      maxParallelJobs: cfg.maxParallelJobs ?? defaults.maxParallelJobs,
+      pollTimeoutMs: cfg.pollTimeoutMs ?? defaults.pollTimeoutMs,
+      workerName: cfg.workerName ?? defaults.workerName,
+      startupJitterMaxSeconds: cfg.startupJitterMaxSeconds ?? defaults.startupJitterMaxSeconds
+    } : cfg;
+    const worker = new JobWorker(this, merged);
     this._workers.push(worker);
     return worker;
   }
@@ -16359,6 +16452,11 @@ var CamundaClient = class {
    * This keeps the main event loop free for polling and I/O, dramatically improving
    * throughput for CPU-bound job handlers.
    *
+   * Worker configuration fields inherit global defaults resolved via the
+   * unified configuration (environment variables or equivalent `CAMUNDA_WORKER_*`
+   * keys provided via `CamundaOptions.config`) when not explicitly set on the
+   * config object.
+   *
    * @param cfg Threaded worker configuration
    * @example Create a threaded job worker
    * ```ts
@@ -16371,8 +16469,17 @@ var CamundaClient = class {
    * ```
    */
   createThreadedJobWorker(cfg) {
+    const defaults = this._config.workerDefaults;
+    const merged = defaults ? {
+      ...cfg,
+      jobTimeoutMs: cfg.jobTimeoutMs ?? defaults.jobTimeoutMs,
+      maxParallelJobs: cfg.maxParallelJobs ?? defaults.maxParallelJobs,
+      pollTimeoutMs: cfg.pollTimeoutMs ?? defaults.pollTimeoutMs,
+      workerName: cfg.workerName ?? defaults.workerName,
+      startupJitterMaxSeconds: cfg.startupJitterMaxSeconds ?? defaults.startupJitterMaxSeconds
+    } : cfg;
     const pool = this._getOrCreateThreadPool(cfg.threadPoolSize);
-    const worker = new ThreadedJobWorker(this, pool, cfg);
+    const worker = new ThreadedJobWorker(this, pool, merged);
     this._workers.push(worker);
     return worker;
   }
@@ -16568,4 +16675,4 @@ export {
   withTimeoutTE,
   eventuallyTE
 };
-//# sourceMappingURL=chunk-7IUDW222.js.map
+//# sourceMappingURL=chunk-W7A45XXW.js.map