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

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+# [8.9.0-alpha.24](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.23...v8.9.0-alpha.24) (2026-03-30)
+
+
+### Bug Fixes
+
+* harden README code injection ([4745468](https://github.com/camunda/orchestration-cluster-api-js/commit/47454684f052027e1449367204e7097b2b26f271)), closes [#87](https://github.com/camunda/orchestration-cluster-api-js/issues/87)
+
+# [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

@@ -54,7 +54,7 @@ In the vast majority of use-cases, this will not be an issue; but you should be
 
 Keep configuration out of application code. Let the factory read `CAMUNDA_*` variables from the environment (12‑factor style). This makes rotation, secret management, and environment promotion safer & simpler.
 
-<!-- snippet:ReadmeDefaultImport+ReadmeQuickStart -->
+<!-- snippet-source: examples/readme-imports.txt,examples/readme.ts | regions: ReadmeDefaultImport+ReadmeQuickStart -->
 
 ```ts
 import createCamundaClient from '@camunda8/orchestration-cluster-api';
@@ -96,7 +96,7 @@ CAMUNDA_SDK_HTTP_RETRY_MAX_DELAY_MS=2000  # optional: cap (ms)
 
 Use only when you must supply or mutate configuration dynamically (e.g. multi‑tenant routing, tests, ephemeral preview environments) or in the browser. Keys mirror their `CAMUNDA_*` env names.
 
-<!-- snippet:ReadmeOverrides -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeOverrides -->
 
 ```ts
 const camunda = createCamundaClient({
@@ -113,7 +113,7 @@ const camunda = createCamundaClient({
 
 Inject a custom `fetch` to add tracing, mock responses, instrumentation, circuit breakers, etc.
 
-<!-- snippet:ReadmeCustomFetch -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeCustomFetch -->
 
 ```ts
 const camunda = createCamundaClient({
@@ -166,7 +166,7 @@ Every API method accepts an optional trailing `options` parameter that lets you
 
 ### Disable Retry for a Single Call
 
-<!-- snippet:ReadmeDisableRetry -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeDisableRetry -->
 
 ```ts
 // This call will not retry on transient errors
@@ -177,7 +177,7 @@ await camunda.completeJob({ jobKey }, { retry: false });
 
 Pass a partial `HttpRetryPolicy` to override individual fields. Unspecified fields inherit from the global configuration.
 
-<!-- snippet:ReadmeRetryOverride -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeRetryOverride -->
 
 ```ts
 // More aggressive retry for this operation only
@@ -224,6 +224,7 @@ Set `CAMUNDA_SDK_HTTP_RETRY_MAX_ATTEMPTS=1` so the SDK does only the initial att
 
 ### Minimal Example (Single Operation)
 
+<!-- snippet-exempt: uses external cockatiel library -->
 ```ts
 import { createCamundaClient } from '@camunda8/orchestration-cluster-api';
 import { retry, ExponentialBackoff, handleAll } from 'cockatiel';
@@ -252,6 +253,7 @@ console.log(topo.brokers?.length);
 
 ### Bulk Wrapping All Operations
 
+<!-- snippet-exempt: uses external cockatiel library -->
 ```ts
 import { createCamundaClient } from '@camunda8/orchestration-cluster-api';
 import { retry, ExponentialBackoff, handleAll } from 'cockatiel';
@@ -330,6 +332,7 @@ Refer to `./docs/CONFIG_REFERENCE.md` for the full list of related environment v
 
 Retry only network errors + 429/503, plus optionally 500 on safe GET endpoints you mark:
 
+<!-- snippet-exempt: uses external cockatiel library -->
 ```ts
 import { retry, ExponentialBackoff, handleWhen } from 'cockatiel';
 
@@ -474,7 +477,7 @@ The SDK provides a lightweight polling job worker for service task job types usi
 
 ### Minimal Example
 
-<!-- snippet:ReadmeJobWorkerImport+ReadmeJobWorkerMinimal -->
+<!-- snippet-source: examples/readme-imports.txt,examples/readme.ts | regions: ReadmeJobWorkerImport+ReadmeJobWorkerMinimal -->
 
 ```ts
 import createCamundaClient from '@camunda8/orchestration-cluster-api';
@@ -521,7 +524,7 @@ TypeScript inference:
 
 - When you provide `inputSchema`, the type of `fetchVariables` is constrained to the keys of the inferred `variables` type from that schema. Example:
 
-<!-- snippet:ReadmeJobWorkerInference -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeJobWorkerInference -->
 
 ```ts
 const Input = z.object({ orderId: z.string(), amount: z.number() });
@@ -567,26 +570,25 @@ Recommended usage:
 
 Example patterns:
 
+<!-- snippet-source: examples/readme.ts | regions: ReadmeJobCompletionPatterns -->
 ```ts
 // GOOD: explicit completion
-return job.complete({ processed: true }); // sentinel stored for ultimate return
+return job.complete({ variables: { processed: true } });
+
+// GOOD: No-arg completion example, sentinel stored for ultimate return
 const ack = await job.complete();
 // ...
 return ack;
 
 // GOOD: explicit ignore
-const ack = await job.ignore();
-```
-
-```ts
-// No-arg completion example
+const ack2 = await job.ignore();
 ```
 
 ### Job Corrections (User Task Listeners)
 
 When a job worker handles a [user task listener](https://docs.camunda.io/docs/components/concepts/user-task-listeners/), it can correct task properties (assignee, due date, candidate groups, etc.) by passing a `result` to `job.complete()`:
 
-<!-- snippet:ReadmeJobCorrectionsImport+ReadmeJobCorrections -->
+<!-- snippet-source: examples/readme-imports.txt,examples/readme.ts | regions: ReadmeJobCorrectionsImport+ReadmeJobCorrections -->
 
 ```ts
 import type { JobResult } from '@camunda8/orchestration-cluster-api';
@@ -610,14 +612,17 @@ const worker = client.createJobWorker({
 
 To deny a task completion (reject the work):
 
-<!-- snippet:ReadmeJobCorrectionsDenial -->
+<!-- snippet-source: examples/readme.ts | regions: 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 |
@@ -647,7 +652,7 @@ If `validateSchemas` is true:
 
 Use `await worker.stopGracefully({ waitUpToMs?, checkIntervalMs? })` to drain without force‑cancelling the current activation request.
 
-<!-- snippet:ReadmeJobWorkerGraceful -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeJobWorkerGraceful -->
 
 ```ts
 // Attempt graceful drain for up to 8 seconds
@@ -676,7 +681,7 @@ You can register multiple workers on a single client instance—one per job type
 
 When deploying multiple application instances simultaneously (e.g. a rolling restart or scale-up), all workers start polling at the same time and can saturate the server with activation requests. Set `startupJitterMaxSeconds` to spread out the initial poll across a random window:
 
-<!-- snippet:ReadmeJobWorkerJitter -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeJobWorkerJitter -->
 
 ```ts
 client.createJobWorker({
@@ -690,11 +695,66 @@ 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-source: examples/readme.ts | regions: 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-source: examples/readme.ts | regions: 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:
 
-<!-- snippet:ReadmeReceiptImport+ReadmeReceipt -->
+<!-- snippet-source: examples/readme-imports.txt,examples/readme.ts | regions: ReadmeReceiptImport+ReadmeReceipt -->
 
 ```ts
 import type { JobActionReceipt } from '@camunda8/orchestration-cluster-api';
@@ -732,14 +792,14 @@ This reverts to only per‑request retry for transient errors (no global gating)
 
 Call `client.getBackpressureState()` to obtain:
 
+<!-- snippet-source: examples/readme.ts | regions: ReadmeBackpressureState -->
 ```ts
-{
-  severity: 'healthy' | 'soft' | 'severe';
-  consecutive: number; // consecutive backpressure signals observed
-  permitsMax: number | null; // current concurrency cap (null => unlimited/not engaged)
-  permitsCurrent: number; // currently acquired permits
-  waiters: number; // queued operations waiting for a permit
-}
+const state = client.getBackpressureState();
+// state.severity: 'healthy' | 'soft' | 'severe'
+// state.consecutive: number — consecutive backpressure signals observed
+// state.permitsMax: number | null — current concurrency cap (null => unlimited/not engaged)
+// state.permitsCurrent: number — currently acquired permits
+// state.waiters: number — queued operations waiting for a permit
 ```
 
 ### Threaded Job Workers (Node.js Only)
@@ -758,6 +818,7 @@ If your handler is mostly I/O-bound (HTTP calls, database queries), the standard
 
 The handler must be a **separate file** (not an inline function) that exports a default async function:
 
+<!-- snippet-exempt: pseudo-code referencing heavyComputation which cannot be type-checked -->
 ```ts
 // my-handler.ts (or my-handler.js)
 import type { ThreadedJobHandler } from '@camunda8/orchestration-cluster-api';
@@ -780,7 +841,7 @@ The handler receives two arguments:
 
 #### Minimal example
 
-<!-- snippet:ReadmeThreadedWorkerImport+ReadmeThreadedWorker -->
+<!-- snippet-source: examples/readme-imports.txt,examples/readme.ts | regions: ReadmeThreadedWorkerImport+ReadmeThreadedWorker -->
 
 ```ts
 import createCamundaClient from '@camunda8/orchestration-cluster-api';
@@ -812,19 +873,24 @@ Other familiar options: `jobType`, `maxParallelJobs`, `jobTimeoutMs`, `pollInter
 
 Threaded workers integrate with the same lifecycle as regular workers:
 
+<!-- snippet-source: examples/readme.ts | regions: ReadmeThreadedLifecycle -->
 ```ts
 // Returned by getWorkers()
 const allWorkers = client.getWorkers();
 
 // Stopped by stopAllWorkers()
 client.stopAllWorkers();
+```
 
+<!-- snippet-source: examples/readme.ts | regions: ReadmeThreadedGraceful -->
+```ts
 // Graceful shutdown (waits for in-flight jobs to finish)
 const { timedOut, remainingJobs } = await worker.stopGracefully({ waitUpToMs: 10_000 });
 ```
 
 #### Pool stats
 
+<!-- snippet-source: examples/readme.ts | regions: ReadmePoolStats -->
 ```ts
 worker.poolSize; // number of threads
 worker.busyThreads; // threads currently processing a job
@@ -932,7 +998,7 @@ If both cert & key are available an https.Agent is attached to all outbound call
 
 Import branded key helpers directly:
 
-<!-- snippet:ReadmeBrandedKeysImport+ReadmeBrandedKeys -->
+<!-- snippet-source: examples/readme-imports.txt,examples/readme.ts | regions: ReadmeBrandedKeysImport+ReadmeBrandedKeys -->
 
 ```ts
 import { ProcessDefinitionKey, ProcessInstanceKey } from '@camunda8/orchestration-cluster-api';
@@ -948,7 +1014,7 @@ They are zero‑cost runtime strings with compile‑time separation.
 
 All methods return a `CancelablePromise<T>`:
 
-<!-- snippet:ReadmeCancelable -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeCancelable -->
 
 ```ts
 const p = camunda.searchProcessInstances(
@@ -985,6 +1051,7 @@ Notes:
 
 The main entry stays minimal. To opt in to a TaskEither-style facade & helper combinators import from the dedicated subpath:
 
+<!-- snippet-exempt: uses SDK /fp subpath not available in examples project -->
 ```ts
 import {
   createCamundaFpClient,
@@ -992,7 +1059,7 @@ import {
   withTimeoutTE,
   eventuallyTE,
   isLeft,
-} from '@camunda8/orchestration-cluster/fp';
+} from '@camunda8/orchestration-cluster-api/fp';
 
 const fp = createCamundaFpClient();
 const deployTE = fp.deployResourcesFromFiles(['./bpmn/process.bpmn']);
@@ -1060,7 +1127,7 @@ Use this to understand convergence speed and data shape evolution during tests o
 
 ### Example
 
-<!-- snippet:ReadmeEventualConsistency -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeEventualConsistency -->
 
 ```ts
 const jobs = await camunda.searchJobs(
@@ -1084,7 +1151,7 @@ On timeout an `EventualConsistencyTimeoutError` includes diagnostic fields: `{ a
 
 Per‑client logger; no global singleton. The level defaults from `CAMUNDA_SDK_LOG_LEVEL` (default `error`).
 
-<!-- snippet:ReadmeLogging -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeLogging -->
 
 ```ts
 const client = createCamundaClient({
@@ -1137,9 +1204,10 @@ Provide a `transport` function to forward structured `LogEvent` objects into any
 
 #### Pino
 
+<!-- snippet-exempt: uses external pino dependency -->
 ```ts
 import pino from 'pino';
-import createCamundaClient from '@camunda8/orchestration-cluster';
+import createCamundaClient from '@camunda8/orchestration-cluster-api';
 
 const p = pino();
 const client = createCamundaClient({
@@ -1155,9 +1223,10 @@ const client = createCamundaClient({
 
 #### Winston
 
+<!-- snippet-exempt: uses external winston dependency -->
 ```ts
 import winston from 'winston';
-import createCamundaClient from '@camunda8/orchestration-cluster';
+import createCamundaClient from '@camunda8/orchestration-cluster-api';
 
 const w = winston.createLogger({ transports: [new winston.transports.Console()] });
 const client = createCamundaClient({
@@ -1180,9 +1249,10 @@ const client = createCamundaClient({
 
 #### loglevel
 
+<!-- snippet-exempt: uses external loglevel dependency -->
 ```ts
 import log from 'loglevel';
-import createCamundaClient from '@camunda8/orchestration-cluster';
+import createCamundaClient from '@camunda8/orchestration-cluster-api';
 
 log.setLevel('info'); // host app level
 const client = createCamundaClient({
@@ -1223,7 +1293,7 @@ May throw:
 
 All SDK-thrown operational errors normalize to a discriminated union (`SdkError`) when they originate from HTTP, network, auth, or validation layers. Use the guard `isSdkError` to narrow inside a catch:
 
-<!-- snippet:ReadmeErrorHandlingImport+ReadmeErrorHandling -->
+<!-- snippet-source: examples/readme-imports.txt,examples/readme.ts | regions: ReadmeErrorHandlingImport+ReadmeErrorHandling -->
 
 ```ts
 import { createCamundaClient, isSdkError } from '@camunda8/orchestration-cluster-api';
@@ -1273,7 +1343,7 @@ _Note that this feature is experimental and subject to change._
 
 If you prefer FP‑style explicit error handling instead of exceptions, use the result client wrapper:
 
-<!-- snippet:ReadmeResultClientImport+ReadmeResultClient -->
+<!-- snippet-source: examples/readme-imports.txt,examples/readme.ts | regions: ReadmeResultClientImport+ReadmeResultClient -->
 
 ```ts
 import { createCamundaResultClient, isOk } from '@camunda8/orchestration-cluster-api';
@@ -1295,8 +1365,9 @@ API surface differences:
 
 Helpers:
 
+<!-- snippet-exempt: one-liner import example -->
 ```ts
-import { isOk, isErr } from '@camunda8/orchestration-cluster';
+import { isOk, isErr } from '@camunda8/orchestration-cluster-api';
 ```
 
 When to use:
@@ -1311,8 +1382,9 @@ _Note that this feature is experimental and subject to change._
 
 For projects using `fp-ts`, wrap the throwing client in a lazy `TaskEither` facade:
 
+<!-- snippet-exempt: requires external fp-ts dependency -->
 ```ts
-import { createCamundaFpClient } from '@camunda8/orchestration-cluster';
+import { createCamundaFpClient } from '@camunda8/orchestration-cluster-api/fp';
 import { pipe } from 'fp-ts/function';
 import * as TE from 'fp-ts/TaskEither';
 
@@ -1360,7 +1432,7 @@ The deployment endpoint requires each resource to have a filename (extension use
 
 ### Browser
 
-<!-- snippet:ReadmeDeployBrowser -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeDeployBrowser -->
 
 ```ts
 const bpmnXml = `<definitions id="process" xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL">...</definitions>`;
@@ -1371,6 +1443,7 @@ console.log(result.deployments.length);
 
 From an existing Blob:
 
+<!-- snippet-exempt: uses hypothetical getBlob() function -->
 ```ts
 const blob: Blob = getBlob();
 const file = new File([blob], 'model.bpmn');
@@ -1381,7 +1454,7 @@ await camunda.createDeployment({ resources: [file] });
 
 Use the built-in helper `deployResourcesFromFiles(...)` to read local files and create `File` objects automatically. It returns the enriched `ExtendedDeploymentResult` (adds typed arrays: `processes`, `decisions`, `decisionRequirements`, `forms`, `resources`).
 
-<!-- snippet:ReadmeDeployNode -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeDeployNode -->
 
 ```ts
 const result = await camunda.deployResourcesFromFiles([
@@ -1396,12 +1469,14 @@ console.log(result.decisions.length);
 
 With explicit tenant (overriding tenant from configuration):
 
+<!-- snippet-exempt: small variant of injected deploy example above -->
 ```ts
 await camunda.deployResourcesFromFiles(['./bpmn/order-process.bpmn'], { tenantId: 'tenant-a' });
 ```
 
 Error handling:
 
+<!-- snippet-exempt: small variant of injected deploy example above -->
 ```ts
 try {
   await camunda.deployResourcesFromFiles([]); // throws (empty array)
@@ -1412,6 +1487,7 @@ try {
 
 Manual construction alternative (if you need custom logic):
 
+<!-- snippet-exempt: alternative construction pattern using node:buffer -->
 ```ts
 import { File } from 'node:buffer';
 const bpmnXml =
@@ -1433,7 +1509,7 @@ Empty arrays are rejected. Always use correct extensions so the server can class
 
 Create isolated clients per test file:
 
-<!-- snippet:ReadmeTestingClient -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeTestingClient -->
 
 ```ts
 const client = createCamundaClient({
@@ -1443,7 +1519,7 @@ const client = createCamundaClient({
 
 Inject a mock fetch:
 
-<!-- snippet:ReadmeTestingMock -->
+<!-- snippet-source: examples/readme.ts | regions: ReadmeTestingMock -->
 
 ```ts
 const client = createCamundaClient({