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

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+# [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)
+
+
+### Bug Fixes
+
+* address PR review comments ([ae51b85](https://github.com/camunda/orchestration-cluster-api-js/commit/ae51b8534239de5bb0ca61c1897dfe89514a740d))
+* address PR review comments on job corrections ([3a82c3a](https://github.com/camunda/orchestration-cluster-api-js/commit/3a82c3a06e25f589ccc9638aba191affa8f25948))
+* address review comments on PR [#85](https://github.com/camunda/orchestration-cluster-api-js/issues/85) ([3d3a810](https://github.com/camunda/orchestration-cluster-api-js/commit/3d3a8109742e6b3fec2e17aecc729565da871ed9))
+* restore 'Later, on shutdown:' comment and fix test formatting ([aed9ba5](https://github.com/camunda/orchestration-cluster-api-js/commit/aed9ba5eb0ed5351da0c1c2a84cf3b40c88f63b5))
+
+
+### Features
+
+* support job corrections in worker job.complete() ([790e15d](https://github.com/camunda/orchestration-cluster-api-js/commit/790e15d675ef3fea09c47cb820a1bc960a075ff6))
+
 # [8.9.0-alpha.21](https://github.com/camunda/orchestration-cluster-api-js/compare/v8.9.0-alpha.20...v8.9.0-alpha.21) (2026-03-25)
 
 

package/README.md

@@ -503,7 +503,7 @@ const worker = client.createJobWorker({
     const vars = job.variables; // inferred from Input schema
     console.log(`Processing order: ${vars.orderId}`);
     // Do work...
-    return job.complete({ variables: { processed: true } });
+    return job.complete({ processed: true });
   },
 });
 
@@ -542,7 +542,7 @@ client.createJobWorker({
 
 Your `jobHandler` must ultimately invoke exactly one of:
 
-- `job.complete({ variables? })` OR `job.complete()`
+- `job.complete(variables?, result?)` OR `job.complete()`
 - `job.fail({ errorMessage, retries?, retryBackoff? })`
 - `job.cancelWorkflow({})` (cancels the process instance)
 - `job.error({ errorCode, errorMessage? })` (throws a business error)
@@ -569,9 +569,7 @@ Example patterns:
 
 ```ts
 // GOOD: explicit completion
-return job.complete({ variables: { processed: true } });
-
-// GOOD: No-arg completion example, sentinel stored for ultimate return
+return job.complete({ processed: true }); // sentinel stored for ultimate return
 const ack = await job.complete();
 // ...
 return ack;
@@ -584,6 +582,58 @@ const ack = await job.ignore();
 // No-arg completion example
 ```
 
+### 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 -->
+
+```ts
+import type { JobResult } from '@camunda8/orchestration-cluster-api';
+
+const worker = client.createJobWorker({
+  jobType: 'io.camunda:userTaskListener',
+  jobTimeoutMs: 30_000,
+  maxParallelJobs: 5,
+  jobHandler: async (job) => {
+    const result: JobResult = {
+      type: 'userTask',
+      corrections: {
+        assignee: 'corrected-user',
+        priority: 80,
+      },
+    };
+    return job.complete({}, result);
+  },
+});
+```
+
+To deny a task completion (reject the work):
+
+<!-- snippet:ReadmeJobCorrectionsDenial -->
+
+```ts
+return job.complete(
+  {},
+  {
+    type: 'userTask',
+    denied: true,
+    deniedReason: 'Insufficient documentation',
+  }
+);
+```
+
+| Correctable attribute | Type | Clear value |
+|---|---|---|
+| `assignee` | `string` | Empty string `""` |
+| `dueDate` | `string` (ISO 8601) | Empty string `""` |
+| `followUpDate` | `string` (ISO 8601) | Empty string `""` |
+| `candidateUsers` | `string[]` | Empty array `[]` |
+| `candidateGroups` | `string[]` | Empty array `[]` |
+| `priority` | `number` (0–100) | — |
+
+Omitting an attribute or passing `null` preserves the persisted value.
+
 ### Concurrency & Backpressure
 
 Set `maxParallelJobs` to the maximum number of jobs you want actively processing concurrently. The worker will long‑poll for up to the remaining capacity each cycle. Global backpressure (adaptive concurrency) still applies to the underlying REST calls; activation itself is a normal operation.
@@ -643,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:
@@ -652,7 +757,7 @@ Action methods return a unique symbol (not a string) to avoid accidental misuse
 ```ts
 import type { JobActionReceipt } from '@camunda8/orchestration-cluster-api';
 
-const receipt: JobActionReceipt = await job.complete({ variables: { processed: true } });
+const receipt: JobActionReceipt = await job.complete({ processed: true });
 ```
 
 If you ignore the return value you don’t need to import the symbol.
@@ -928,6 +1033,14 @@ Notes:
 
 @experimental - this feature is not guaranteed to be tested or stable.
 
+> **Peer dependency:** `fp-ts` is an optional peer dependency. If you use real `fp-ts` functions
+> (e.g. `pipe`, `TE.match`) alongside this subpath, install it separately:
+> ```sh
+> npm install fp-ts
+> ```
+> The `/fp` subpath works without `fp-ts` installed — it exposes structurally-compatible
+> `Either`/`TaskEither` shapes that interoperate with `fp-ts` but do not require it at runtime.
+
 The main entry stays minimal. To opt in to a TaskEither-style facade & helper combinators import from the dedicated subpath:
 
 ```ts
@@ -1392,7 +1505,7 @@ Inject a mock fetch:
 
 ```ts
 const client = createCamundaClient({
-  fetch: async (input, init) => new Response(JSON.stringify({ ok: true }), { status: 200 }),
+  fetch: async (_input, _init) => new Response(JSON.stringify({ ok: true }), { status: 200 }),
 });
 ```
 

package/dist/{chunk-2N2LUTZ2.js → chunk-KQ4UL2WX.js}

@@ -16,7 +16,7 @@ function createLogger(opts = {}) {
     return ORDER[currentLevel] >= ORDER[need];
   }
   function evalArgs(args) {
-    return args.map((a) => typeof a === "function" && a.length === 0 ? a() : a).flat();
+    return args.flatMap((a) => typeof a === "function" && a.length === 0 ? a() : a);
   }
   function emit(level, scope, rawArgs) {
     if (!isEnabled(level)) return;
@@ -44,7 +44,7 @@ function createLogger(opts = {}) {
     } else {
       const tag = `[camunda-sdk][${level}]${scope ? `[${scope}]` : ""}`;
       const method = level === "error" ? "error" : level === "warn" ? "warn" : "log";
-      console[method](tag, code + ":", msg, data ?? "");
+      console[method](tag, `${code}:`, msg, data ?? "");
     }
   }
   const make = (scope) => ({
@@ -74,4 +74,4 @@ function createLogger(opts = {}) {
 export {
   createLogger
 };
-//# sourceMappingURL=chunk-2N2LUTZ2.js.map
+//# sourceMappingURL=chunk-KQ4UL2WX.js.map

package/dist/chunk-KQ4UL2WX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/logger.ts"],"sourcesContent":["// Per-client logger (no global singleton). Construct via createLogger.\n\n// Added 'silly' for deep diagnostics (unsafe: logs HTTP bodies when enabled elsewhere)\nexport type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silly';\nexport interface LogEvent {\n  level: LogLevel;\n  scope: string;\n  ts: number;\n  args: any[];\n  code?: string;\n  data?: any;\n}\nexport type LogTransport = (e: LogEvent) => void;\nconst ORDER: Record<LogLevel, number> = {\n  silent: 0,\n  error: 1,\n  warn: 2,\n  info: 3,\n  debug: 4,\n  trace: 5,\n  silly: 6,\n};\n\nexport interface Logger {\n  level(): LogLevel;\n  setLevel(level: LogLevel): void; // internal use\n  setTransport(t?: LogTransport): void; // internal use\n  error(...a: any[]): void;\n  warn(...a: any[]): void;\n  info(...a: any[]): void;\n  debug(...a: any[]): void;\n  trace(...a: any[]): void;\n  silly(...a: any[]): void;\n  scope(child: string): Logger;\n  code(level: LogLevel, code: string, msg: string, data?: any): void;\n}\n\nexport interface CreateLoggerOptions {\n  level?: LogLevel;\n  transport?: LogTransport;\n  scope?: string;\n}\n\nexport function createLogger(opts: CreateLoggerOptions = {}): Logger {\n  let currentLevel: LogLevel = opts.level || 'error';\n  let transport: LogTransport | undefined = opts.transport;\n  const baseScope = opts.scope || '';\n\n  function isEnabled(need: LogLevel) {\n    return ORDER[currentLevel] >= ORDER[need];\n  }\n  function evalArgs(args: any[]): any[] {\n    // Support lazy function args: if an arg is a function with zero arity, call it.\n    return args.flatMap((a) => (typeof a === 'function' && a.length === 0 ? a() : a));\n  }\n  function emit(level: LogLevel, scope: string, rawArgs: any[]) {\n    if (!isEnabled(level)) return;\n    const args = evalArgs(rawArgs);\n    const evt: LogEvent = { level, scope, ts: Date.now(), args };\n    if (transport) {\n      try {\n        transport(evt);\n      } catch {\n        /* ignore transport errors */\n      }\n    } else {\n      const tag = `[camunda-sdk][${level}]${scope ? `[${scope}]` : ''}`;\n      const method = level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log';\n\n      console[method](tag, ...args);\n    }\n  }\n  function emitCode(level: LogLevel, scope: string, code: string, msg: string, data?: any) {\n    if (!isEnabled(level)) return;\n    const evt: LogEvent = { level, scope, ts: Date.now(), args: [msg], code, data };\n    if (transport) {\n      try {\n        transport(evt);\n      } catch {}\n    } else {\n      const tag = `[camunda-sdk][${level}]${scope ? `[${scope}]` : ''}`;\n      const method = level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log';\n\n      console[method](tag, `${code}:`, msg, data ?? '');\n    }\n  }\n  const make = (scope: string): Logger => ({\n    level: () => currentLevel,\n    setLevel(l: LogLevel) {\n      currentLevel = l;\n    },\n    setTransport(t?: LogTransport) {\n      transport = t;\n    },\n    error: (...a: any[]) => emit('error', scope, a),\n    warn: (...a: any[]) => emit('warn', scope, a),\n    info: (...a: any[]) => emit('info', scope, a),\n    debug: (...a: any[]) => emit('debug', scope, a),\n    trace: (...a: any[]) => emit('trace', scope, a),\n    silly: (...a: any[]) => emit('silly', scope, a),\n    scope(child: string) {\n      return make(scope ? `${scope}:${child}` : child);\n    },\n    code(l: LogLevel, code: string, msg: string, data?: any) {\n      emitCode(l, scope, code, msg, data);\n    },\n  });\n  return make(baseScope);\n}\n"],"mappings":";AAaA,IAAM,QAAkC;AAAA,EACtC,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AAAA,EACP,OAAO;AAAA,EACP,OAAO;AACT;AAsBO,SAAS,aAAa,OAA4B,CAAC,GAAW;AACnE,MAAI,eAAyB,KAAK,SAAS;AAC3C,MAAI,YAAsC,KAAK;AAC/C,QAAM,YAAY,KAAK,SAAS;AAEhC,WAAS,UAAU,MAAgB;AACjC,WAAO,MAAM,YAAY,KAAK,MAAM,IAAI;AAAA,EAC1C;AACA,WAAS,SAAS,MAAoB;AAEpC,WAAO,KAAK,QAAQ,CAAC,MAAO,OAAO,MAAM,cAAc,EAAE,WAAW,IAAI,EAAE,IAAI,CAAE;AAAA,EAClF;AACA,WAAS,KAAK,OAAiB,OAAe,SAAgB;AAC5D,QAAI,CAAC,UAAU,KAAK,EAAG;AACvB,UAAM,OAAO,SAAS,OAAO;AAC7B,UAAM,MAAgB,EAAE,OAAO,OAAO,IAAI,KAAK,IAAI,GAAG,KAAK;AAC3D,QAAI,WAAW;AACb,UAAI;AACF,kBAAU,GAAG;AAAA,MACf,QAAQ;AAAA,MAER;AAAA,IACF,OAAO;AACL,YAAM,MAAM,iBAAiB,KAAK,IAAI,QAAQ,IAAI,KAAK,MAAM,EAAE;AAC/D,YAAM,SAAS,UAAU,UAAU,UAAU,UAAU,SAAS,SAAS;AAEzE,cAAQ,MAAM,EAAE,KAAK,GAAG,IAAI;AAAA,IAC9B;AAAA,EACF;AACA,WAAS,SAAS,OAAiB,OAAe,MAAc,KAAa,MAAY;AACvF,QAAI,CAAC,UAAU,KAAK,EAAG;AACvB,UAAM,MAAgB,EAAE,OAAO,OAAO,IAAI,KAAK,IAAI,GAAG,MAAM,CAAC,GAAG,GAAG,MAAM,KAAK;AAC9E,QAAI,WAAW;AACb,UAAI;AACF,kBAAU,GAAG;AAAA,MACf,QAAQ;AAAA,MAAC;AAAA,IACX,OAAO;AACL,YAAM,MAAM,iBAAiB,KAAK,IAAI,QAAQ,IAAI,KAAK,MAAM,EAAE;AAC/D,YAAM,SAAS,UAAU,UAAU,UAAU,UAAU,SAAS,SAAS;AAEzE,cAAQ,MAAM,EAAE,KAAK,GAAG,IAAI,KAAK,KAAK,QAAQ,EAAE;AAAA,IAClD;AAAA,EACF;AACA,QAAM,OAAO,CAAC,WAA2B;AAAA,IACvC,OAAO,MAAM;AAAA,IACb,SAAS,GAAa;AACpB,qBAAe;AAAA,IACjB;AAAA,IACA,aAAa,GAAkB;AAC7B,kBAAY;AAAA,IACd;AAAA,IACA,OAAO,IAAI,MAAa,KAAK,SAAS,OAAO,CAAC;AAAA,IAC9C,MAAM,IAAI,MAAa,KAAK,QAAQ,OAAO,CAAC;AAAA,IAC5C,MAAM,IAAI,MAAa,KAAK,QAAQ,OAAO,CAAC;AAAA,IAC5C,OAAO,IAAI,MAAa,KAAK,SAAS,OAAO,CAAC;AAAA,IAC9C,OAAO,IAAI,MAAa,KAAK,SAAS,OAAO,CAAC;AAAA,IAC9C,OAAO,IAAI,MAAa,KAAK,SAAS,OAAO,CAAC;AAAA,IAC9C,MAAM,OAAe;AACnB,aAAO,KAAK,QAAQ,GAAG,KAAK,IAAI,KAAK,KAAK,KAAK;AAAA,IACjD;AAAA,IACA,KAAK,GAAa,MAAc,KAAa,MAAY;AACvD,eAAS,GAAG,OAAO,MAAM,KAAK,IAAI;AAAA,IACpC;AAAA,EACF;AACA,SAAO,KAAK,SAAS;AACvB;","names":[]}