@camunda8/sdk 8.7.16 → 8.7.17

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [8.7.17](https://github.com/camunda/camunda-8-js-sdk/compare/v8.7.16...v8.7.17) (2025-06-18)
+
+
+### Bug Fixes
+
+* enhance async stack trace. fixes [#506](https://github.com/camunda/camunda-8-js-sdk/issues/506) ([c443ab2](https://github.com/camunda/camunda-8-js-sdk/commit/c443ab20c7aed9a2f4e0b80e0df4ec3e2be8b15c))
+
+
+### Features
+
+* implement QuerySubscription. fixes [#502](https://github.com/camunda/camunda-8-js-sdk/issues/502) ([a4bbd61](https://github.com/camunda/camunda-8-js-sdk/commit/a4bbd612e8c34112e9dfcd19e0b00a81e0c24e81))
+
 ## [8.7.16](https://github.com/camunda/camunda-8-js-sdk/compare/v8.7.15...v8.7.16) (2025-06-11)
 
 

package/README.md

@@ -113,7 +113,7 @@ Here is an example of specifying a different cache directory via the constructor
 import { Camunda8 } from '@camunda8/sdk'
 
 const c8 = new Camunda8({
-	CAMUNDA_TOKEN_CACHE_DIR: '/tmp/cache',
+  CAMUNDA_TOKEN_CACHE_DIR: '/tmp/cache',
 })
 ```
 
@@ -174,14 +174,14 @@ You can add arbitrary headers to all requests by implementing `IOAuthProvider`:
 import { Camunda8, Auth } from '@camunda8/sdk'
 
 class MyCustomAuthProvider implements Auth.IOAuthProvider {
-	async getToken(audience: string) {
-		// here we give a static example, but this class may read configuration,
-		// exchange credentials with an endpoint, manage token lifecycles, and so forth...
-		// Return an object which will be merged with the headers on the request
-		return {
-			'x-custom-auth-header': 'someCustomValue',
-		}
-	}
+  async getToken(audience: string) {
+    // here we give a static example, but this class may read configuration,
+    // exchange credentials with an endpoint, manage token lifecycles, and so forth...
+    // Return an object which will be merged with the headers on the request
+  return {
+    'x-custom-auth-header': 'someCustomValue',
+    }
+  }
 }
 
 const customAuthProvider = new MyCustomAuthProvider()
@@ -242,19 +242,19 @@ Here is an example of doing this via the constructor, rather than via the enviro
 import { Camunda8 } from '@camunda8/sdk'
 
 const c8 = new Camunda8({
-	ZEEBE_ADDRESS: 'localhost:26500',
-	ZEEBE_REST_ADDRESS: 'http://localhost:8080',
-	ZEEBE_CLIENT_ID: 'zeebe',
-	ZEEBE_CLIENT_SECRET: 'zecret',
-	CAMUNDA_OAUTH_STRATEGY: 'OAUTH',
-	CAMUNDA_OAUTH_URL:
-		'http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token',
-	CAMUNDA_TASKLIST_BASE_URL: 'http://localhost:8082',
-	CAMUNDA_OPERATE_BASE_URL: 'http://localhost:8081',
-	CAMUNDA_OPTIMIZE_BASE_URL: 'http://localhost:8083',
-	CAMUNDA_MODELER_BASE_URL: 'http://localhost:8070/api',
-	CAMUNDA_TENANT_ID: '', // We can override values in the env by passing an empty string value
-	CAMUNDA_SECURE_CONNECTION: false,
+  ZEEBE_ADDRESS: 'localhost:26500',
+  ZEEBE_REST_ADDRESS: 'http://localhost:8080',
+  ZEEBE_CLIENT_ID: 'zeebe',
+  ZEEBE_CLIENT_SECRET: 'zecret',
+  CAMUNDA_OAUTH_STRATEGY: 'OAUTH',
+  CAMUNDA_OAUTH_URL:
+    'http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token',
+  CAMUNDA_TASKLIST_BASE_URL: 'http://localhost:8082',
+  CAMUNDA_OPERATE_BASE_URL: 'http://localhost:8081',
+  CAMUNDA_OPTIMIZE_BASE_URL: 'http://localhost:8083',
+  CAMUNDA_MODELER_BASE_URL: 'http://localhost:8070/api',
+  CAMUNDA_TENANT_ID: '', // We can override values in the env by passing an empty string value
+  CAMUNDA_SECURE_CONNECTION: false,
 })
 ```
 
@@ -304,11 +304,106 @@ const logger = pino({ level }) // Logging level controlled via the logging libra
 
 logger.info('Pino logger created')
 const c8 = new Camunda8({
-	logger,
+  logger,
 })
 c8.log.info('Using pino logger')
 ```
 
+## Awaiting Asynchronous Query Data
+
+Camunda 8 uses an eventually-consistent data architecture. When you start a process instance, data related to this process instance is not immediately available in the datastore. This leads to data synchronisation issues you need to manage in your application. To aid you with this, the SDK provides a utility: `PollingOperation`. You can pass a query API operation to this utility with a polling interval and a timeout.
+
+The `PollingOperation` will execute the query repeatedly until the expected data is available in the data store, or the timeout is reached.
+
+The following example will return the query response for a newly-created process instance as soon as the element instance data is available:
+
+```typescript
+import { Camunda8, PollingOperation } from '@camunda8/sdk'
+
+const c8 = new Camunda8()
+
+const elementInstances = await PollingOperation({
+  operation: () =>
+  c8.searchElementInstances({
+    sort: [{ field: 'processInstanceKey' }],
+    filter: {
+      processInstanceKey: processInstance.processInstanceKey,
+      type: 'SERVICE_TASK',
+    },
+  }),
+  interval: 500,
+  timeout: 10000,
+})
+```
+
+By default, the `PollingOperation` waits for a query response from the Orchestration Cluster API that has one or more results in the `items` array. If you have a more specific predicate, or are using one of the v1 component APIs, you can pass in a custom predicate function.
+
+The following example waits for a process instance to be available to a query over the Operate API:
+
+```typescript
+import { Camunda8, PollingOperation } from '@camunda8/sdk'
+
+const c8 = new Camunda8()
+const c = c8.getOperateApiClient()
+
+const process = await PollingOperation({
+  operation: () => c.getProcessInstance(p.processInstanceKey),
+  predicate: (res) => res.key === p.processInstanceKey,
+  interval: 500,
+  timeout: 15000,
+})
+```
+## Subscribing to queries
+
+You can subscribe to queries using a `QuerySubscription`. This is an event emitter that emits a `data` event when new data is available. You pass a predicate function that takes a `previous` and `current` query result set. In this predicate function you can examine the two states to see whether or not to emit a data event, and also perform data-processing — for example, removing items that were emitted in the last update.
+
+Note that this is an experimental feature and may change in future releases. We are looking for feedback on this feature, please report issues in the GitHub repo or via a JIRA ticket if you have an account with Camunda.
+
+Here is an example of using `QuerySubscription`:
+
+```typescript
+import { Camunda8, QuerySubscription } from '@camunda8/sdk'
+
+const c8 = new Camunda8()
+
+const query = () =>
+ c8.searchProcessInstances({
+  filter: {
+    processDefinitionKey: key,
+    state: 'ACTIVE',
+  },
+  sort: [{ field: 'startDate', order: 'ASC' }],
+})
+
+const subscription = QuerySubscription({
+  query,
+  predicate: (previous, current) => {
+    // This is the default predicate, provided here as an example
+	const previousItems = (previous?.items ?? []) as Array<unknown>
+	const currentItems = current.items.filter(
+		(item) =>
+			!previousItems.some((prevItem) => isDeepStrictEqual(prevItem, item))
+	)
+	if (currentItems.length > 0) {
+		return {
+			...current,
+			items: currentItems,
+			page: { ...current.page, totalItems: currentItems.length },
+		}
+	}
+	return false // No new items, do not emit
+  },
+  interval: 5000,
+})
+
+subscription.on('data', data => {
+    // new process instances
+})
+//...
+subscription.cancel() // close subscription and free resources
+// You can also use subscription.pause() and subscription.resume() to pause and resume the subscription
+```
+
 ## Debugging
 
 The SDK uses the [`debug`](https://github.com/debug-js/debug) library to help you debug specific issues. This produces verbose, low-level output from specific components to the console.

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import * as Optimize from './optimize';
 import * as Tasklist from './tasklist';
 import * as Zeebe from './zeebe';
 export { PollingOperation } from './lib/PollingOperation';
+export { QuerySubscription } from './lib/QuerySubscription';
 export type { CamundaJobWorker } from './c8/lib/CamundaJobWorker';
 export { CamundaSDKConfiguration } from './lib';
 export { HTTPError } from './lib';

package/dist/index.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Zeebe = exports.Tasklist = exports.Optimize = exports.Operate = exports.Modeler = exports.CamundaRestClient = exports.Camunda8 = exports.Auth = exports.Admin = exports.Dto = exports.HTTPError = exports.CamundaSDKConfiguration = exports.PollingOperation = void 0;
+exports.Zeebe = exports.Tasklist = exports.Optimize = exports.Operate = exports.Modeler = exports.CamundaRestClient = exports.Camunda8 = exports.Auth = exports.Admin = exports.Dto = exports.HTTPError = exports.CamundaSDKConfiguration = exports.QuerySubscription = exports.PollingOperation = void 0;
 const Admin = __importStar(require("./admin"));
 exports.Admin = Admin;
 const c8_1 = require("./c8");
@@ -46,6 +46,8 @@ const Zeebe = __importStar(require("./zeebe"));
 exports.Zeebe = Zeebe;
 var PollingOperation_1 = require("./lib/PollingOperation");
 Object.defineProperty(exports, "PollingOperation", { enumerable: true, get: function () { return PollingOperation_1.PollingOperation; } });
+var QuerySubscription_1 = require("./lib/QuerySubscription");
+Object.defineProperty(exports, "QuerySubscription", { enumerable: true, get: function () { return QuerySubscription_1.QuerySubscription; } });
 CamundaSupportLogger_1.CamundaSupportLogger.getInstance();
 var lib_2 = require("./lib");
 Object.defineProperty(exports, "CamundaSDKConfiguration", { enumerable: true, get: function () { return lib_2.CamundaSDKConfiguration; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,+CAAgC;AAiD/B,sBAAK;AAhDN,6BAA+B;AAkD9B,yFAlDQ,aAAQ,OAkDR;AAjDT,kEAA8D;AAkD7D,kGAlDQ,qCAAiB,OAkDR;AAjDlB,+BAQc;AACd,qEAAiE;AACjE,mDAAoC;AAwCnC,0BAAO;AAvCR,8CAA+B;AAoC9B,oBAAI;AAnCL,mDAAoC;AAuCnC,0BAAO;AAtCR,qDAAsC;AAuCrC,4BAAQ;AAtCT,qDAAsC;AAuCrC,4BAAQ;AAtCT,+CAAgC;AAuC/B,sBAAK;AArCN,2DAAyD;AAAhD,oHAAA,gBAAgB,OAAA;AAIzB,2CAAoB,CAAC,WAAW,EAAE,CAAA;AAElC,6BAA+C;AAAtC,8GAAA,uBAAuB,OAAA;AAEhC,6BAAiC;AAAxB,gGAAA,SAAS,OAAA;AAElB;;;;;;;GAOG;AACU,QAAA,GAAG,GAAG;IAClB,QAAQ,EAAR,cAAQ;IACR,WAAW,EAAX,iBAAW;IACX,gBAAgB,EAAhB,sBAAgB;IAChB,WAAW,EAAX,iBAAW;IACX,gBAAgB,EAAhB,sBAAgB;IAChB,WAAW,EAAX,iBAAW;IACX,iBAAiB,EAAjB,uBAAiB;CACjB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,+CAAgC;AAkD/B,sBAAK;AAjDN,6BAA+B;AAmD9B,yFAnDQ,aAAQ,OAmDR;AAlDT,kEAA8D;AAmD7D,kGAnDQ,qCAAiB,OAmDR;AAlDlB,+BAQc;AACd,qEAAiE;AACjE,mDAAoC;AAyCnC,0BAAO;AAxCR,8CAA+B;AAqC9B,oBAAI;AApCL,mDAAoC;AAwCnC,0BAAO;AAvCR,qDAAsC;AAwCrC,4BAAQ;AAvCT,qDAAsC;AAwCrC,4BAAQ;AAvCT,+CAAgC;AAwC/B,sBAAK;AAtCN,2DAAyD;AAAhD,oHAAA,gBAAgB,OAAA;AACzB,6DAA2D;AAAlD,sHAAA,iBAAiB,OAAA;AAI1B,2CAAoB,CAAC,WAAW,EAAE,CAAA;AAElC,6BAA+C;AAAtC,8GAAA,uBAAuB,OAAA;AAEhC,6BAAiC;AAAxB,gGAAA,SAAS,OAAA;AAElB;;;;;;;GAOG;AACU,QAAA,GAAG,GAAG;IAClB,QAAQ,EAAR,cAAQ;IACR,WAAW,EAAX,iBAAW;IACX,gBAAgB,EAAhB,sBAAgB;IAChB,WAAW,EAAX,iBAAW;IACX,gBAAgB,EAAhB,sBAAgB;IAChB,WAAW,EAAX,iBAAW;IACX,iBAAiB,EAAjB,uBAAiB;CACjB,CAAA"}

package/dist/lib/AsyncTrace.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="node" />
+import { AsyncLocalStorage } from 'async_hooks';
+/**
+ * Capturing useful async stack traces is challenging with got.
+ * See here: https://github.com/sindresorhus/got/blob/main/documentation/async-stack-traces.md
+ * This function stores the call point from the application of got requests.
+ * This enables users to see where the error originated from.
+ * It uses the AsyncLocalStorage to store the creation stack trace.
+ * The stack trace is captured from the point where this function is called, allowing you to see where the async operation was initiated.
+ * See QuerySubscription.spec.ts for an example of how to use this function.
+ * @param fn The function to run within the async context. It can return a value or a Promise.
+ * @param errorTag A meaningful tag to identify the error context, which will be included in the stack trace.
+ * @returns
+ */
+export declare function runWithAsyncErrorContext<T>(fn: () => T | Promise<T>, errorTag: string): T | Promise<T>;
+/**
+ * This is the exported AsyncLocalStorage instance that holds the context for async operations.
+ * It is used in the GotHooks.ts to extract the stack trace of the async operation.
+ */
+export declare const asyncOperationContext: AsyncLocalStorage<{
+    creationStack: string;
+}>;

package/dist/lib/AsyncTrace.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asyncOperationContext = exports.runWithAsyncErrorContext = void 0;
+const async_hooks_1 = require("async_hooks");
+/**
+ * Capturing useful async stack traces is challenging with got.
+ * See here: https://github.com/sindresorhus/got/blob/main/documentation/async-stack-traces.md
+ * This function stores the call point from the application of got requests.
+ * This enables users to see where the error originated from.
+ * It uses the AsyncLocalStorage to store the creation stack trace.
+ * The stack trace is captured from the point where this function is called, allowing you to see where the async operation was initiated.
+ * See QuerySubscription.spec.ts for an example of how to use this function.
+ * @param fn The function to run within the async context. It can return a value or a Promise.
+ * @param errorTag A meaningful tag to identify the error context, which will be included in the stack trace.
+ * @returns
+ */
+function runWithAsyncErrorContext(fn, errorTag) {
+    return exports.asyncOperationContext.run(getAsyncStackTrace(errorTag), fn);
+}
+exports.runWithAsyncErrorContext = runWithAsyncErrorContext;
+/**
+ * This is the exported AsyncLocalStorage instance that holds the context for async operations.
+ * It is used in the GotHooks.ts to extract the stack trace of the async operation.
+ */
+exports.asyncOperationContext = new async_hooks_1.AsyncLocalStorage();
+function removeLeadingNewLines(str, errorTag) {
+    const parts = str.split('\n');
+    return [`${errorTag}:`, ...parts.slice(2)].join('\n');
+}
+function getAsyncStackTrace(errorTag) {
+    const creationStack = new Error(errorTag).stack?.replace(/^.*?\n/, '') || 'No stack available';
+    return { creationStack: removeLeadingNewLines(creationStack, errorTag) };
+}
+//# sourceMappingURL=AsyncTrace.js.map

package/dist/lib/AsyncTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncTrace.js","sourceRoot":"","sources":["../../src/lib/AsyncTrace.ts"],"names":[],"mappings":";;;AAAA,6CAA+C;AAE/C;;;;;;;;;;;GAWG;AACH,SAAgB,wBAAwB,CACvC,EAAwB,EACxB,QAAgB;IAEhB,OAAO,6BAAqB,CAAC,GAAG,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAA;AACnE,CAAC;AALD,4DAKC;AAED;;;GAGG;AACU,QAAA,qBAAqB,GAAG,IAAI,+BAAiB,EAEtD,CAAA;AAEJ,SAAS,qBAAqB,CAAC,GAAW,EAAE,QAAgB;IAC3D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC7B,OAAO,CAAC,GAAG,QAAQ,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACtD,CAAC;AAED,SAAS,kBAAkB,CAAC,QAAgB;IAC3C,MAAM,aAAa,GAClB,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,oBAAoB,CAAA;IACzE,OAAO,EAAE,aAAa,EAAE,qBAAqB,CAAC,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAA;AACzE,CAAC"}

package/dist/lib/GotHooks.d.ts

@@ -1,7 +1,8 @@
 import { BeforeErrorHook, HandlerFunction, Method } from 'got';
 import { CamundaPlatform8Configuration } from './Configuration';
 /**
- *
+ * Capturing useful async stack traces is challenging with got.
+ * See here: https://github.com/sindresorhus/got/blob/main/documentation/async-stack-traces.md
  * This function stores the call point from the application of got requests.
  * This enables users to see where the error originated from.
  */

package/dist/lib/GotHooks.js

@@ -3,11 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GotRetryConfig = exports.makeBeforeRetryHandlerFor401TokenRetry = exports.gotBeforeErrorHook = exports.beforeCallHook = void 0;
 /* eslint-disable @typescript-eslint/no-explicit-any */
 const got_1 = require("got");
+const AsyncTrace_1 = require("./AsyncTrace");
 const CamundaSupportLogger_1 = require("./CamundaSupportLogger");
 const GotErrors_1 = require("./GotErrors");
 const supportLogger = CamundaSupportLogger_1.CamundaSupportLogger.getInstance();
 /**
- *
+ * Capturing useful async stack traces is challenging with got.
+ * See here: https://github.com/sindresorhus/got/blob/main/documentation/async-stack-traces.md
  * This function stores the call point from the application of got requests.
  * This enables users to see where the error originated from.
  */
@@ -15,7 +17,13 @@ const beforeCallHook = (options, next) => {
     if (Object.isFrozen(options.context)) {
         options.context = { ...options.context, hasRetried: false };
     }
-    Error.captureStackTrace(options.context);
+    // If we stored the creation stack in the async context, we can use it to enhance the stack trace of the request.
+    const creationStack = AsyncTrace_1.asyncOperationContext.getStore()?.creationStack;
+    const obj = {};
+    Error.captureStackTrace(obj, exports.beforeCallHook);
+    options.context.stack = creationStack
+        ? `${creationStack}\n${obj.stack}`
+        : obj.stack;
     supportLogger.log(`Rest call:`);
     supportLogger.log(options);
     return next(options);
@@ -39,12 +47,12 @@ const gotBeforeErrorHook = (config) => (error) => {
             detail = details ?? '';
         }
         catch (e) {
-            ;
             error.statusCode = 0;
         }
     }
-    ;
-    error.source = error.options.context.stack.split('\n');
+    error.source = error.options.context.stack?.split('\n') ?? [
+        'No enhanced stack trace available',
+    ];
     error.message += ` (request to ${request?.options.url
         .href}). ${JSON.stringify(detail)}`;
     /** Hinting for error messages. See https://github.com/camunda/camunda-8-js-sdk/issues/456 */

package/dist/lib/GotHooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"GotHooks.js","sourceRoot":"","sources":["../../src/lib/GotHooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GotHooks.js","sourceRoot":"","sources":["../../src/lib/GotHooks.ts"],"names":[],"mappings":"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"}

package/dist/lib/PollingOperation.d.ts

@@ -1,12 +1,20 @@
-interface PollingOperationOptions<T> {
+interface PollingOperationOptionsBase<T> {
     operation: () => Promise<T>;
-    /** predicate to check if the result is valid */
-    predicate?: (result: T) => boolean;
     /** how often to poll in ms - defaults to 1000 */
     interval?: number;
     /** when to timeout - defaults to 30000 */
     timeout?: number;
 }
+interface PollingOperationOptionsWithPredicate<T> extends PollingOperationOptionsBase<T> {
+    /** predicate to check if the result is valid */
+    predicate: (result: T) => boolean;
+}
+interface PollingOperationOptionsWithoutPredicate<T extends {
+    items: Array<unknown>;
+}> extends PollingOperationOptionsBase<T> {
+    /** predicate to check if the result is valid - optional when T has items array */
+    predicate?: (result: T) => boolean;
+}
 /**
  * Poll for a result of an operation until it returns an awaited result or times out.
  * This is useful for operations that may take some time to complete, such as waiting for a process instance to finish or data to propagate to query indices.
@@ -14,8 +22,33 @@ interface PollingOperationOptions<T> {
  * @param options options for the polling operation
  * @returns either the result of the operation or an error if the operation times out. If results were returned, but the predicate was not met, a PredicateError is thrown.
  * Otherwise, the failure is propagated as an error.
+ * @example
+ * ```ts
+ * // Wait for a process instance to appear in the search results
+ * const elementInstances = await PollingOperation({
+ *   operation: () =>
+ *     c8.searchElementInstances({
+ *	     sort: [{ field: 'processInstanceKey' }],
+ *       filter: {
+ *         processInstanceKey: processInstance.processInstanceKey,
+ *         type: 'SERVICE_TASK',
+ *       },
+ *   }),
+ *   interval: 500,
+ *   timeout: 10000,
+ * })
+ *
+ * // If the operation does not return an object with an `items` array (ie: a v1 API), you need to provide a predicate function to check if the result is the awaited one.
+ * const process = await PollingOperation({
+ *   operation: () => c.getProcessInstance(p.processInstanceKey),
+ *   predicate: (res) => res.key === p.processInstanceKey,
+ *   interval: 500,
+ *   timeout: 15000,
+ * })
+ *```
  */
 export declare function PollingOperation<T extends {
     items: Array<unknown>;
-}>(options: PollingOperationOptions<T>): Promise<T>;
+}>(options: PollingOperationOptionsWithoutPredicate<T>): Promise<T>;
+export declare function PollingOperation<T>(options: PollingOperationOptionsWithPredicate<T>): Promise<T>;
 export {};

package/dist/lib/PollingOperation.js

@@ -16,24 +16,18 @@ class PredicateError extends Error {
         this.result = null;
     }
 }
-/**
- * Poll for a result of an operation until it returns an awaited result or times out.
- * This is useful for operations that may take some time to complete, such as waiting for a process instance to finish or data to propagate to query indices.
- * Takes an optional prediicate function to determine if the result is the awaited one. By default, it checks if the result is not null or undefined and has at least one item in the `items` array.
- * @param options options for the polling operation
- * @returns either the result of the operation or an error if the operation times out. If results were returned, but the predicate was not met, a PredicateError is thrown.
- * Otherwise, the failure is propagated as an error.
- */
 function PollingOperation(options) {
     const interval = options.interval || 1000;
     const timeout = options.timeout || 30000;
     const operation = options.operation;
+    // Use default predicate if no predicate provided, otherwise use provided predicate
     const predicate = options.predicate || defaultPredicate;
     return new Promise((resolve, reject) => {
         const startTime = Date.now();
         const poll = async () => {
             try {
                 const result = await operation();
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 if (!predicate(result)) {
                     const error = new PredicateError('Predicate did not match');
                     error.result = result;

package/dist/lib/PollingOperation.js.map

@@ -1 +1 @@
-{"version":3,"file":"PollingOperation.js","sourceRoot":"","sources":["../../src/lib/PollingOperation.ts"],"names":[],"mappings":";;;AAAA,SAAS,gBAAgB,CACxB,MAAS;IAET,OAAO,CACN,MAAM,KAAK,IAAI;QACf,MAAM,KAAK,SAAS;QACpB,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CACvB,CAAA;AACF,CAAC;AAYD,MAAM,cAAkB,SAAQ,KAAK;IAEpC,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,iDAAiD;QACjD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAA;QACrD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;IACnB,CAAC;CACD;AACD;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAC/B,OAAmC;IAEnC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAA;IACzC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAA;IACxC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,CAAA;IACvD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAE5B,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE;YACvB,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAA;gBAChC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxB,MAAM,KAAK,GAAG,IAAI,cAAc,CAAI,yBAAyB,CAAC,CAAA;oBAC9D,KAAK,CAAC,MAAM,GAAG,MAAM,CAAA;oBACrB,MAAM,KAAK,CAAA;gBACZ,CAAC;gBACD,OAAO,CAAC,MAAM,CAAC,CAAA;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;oBACtC,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;gBAC3B,CAAC;qBAAM,CAAC;oBACP,MAAM,CAAC,KAAK,CAAC,CAAA;gBACd,CAAC;YACF,CAAC;QACF,CAAC,CAAA;QAED,IAAI,EAAE,CAAA;IACP,CAAC,CAAC,CAAA;AACH,CAAC;AA9BD,4CA8BC"}
+{"version":3,"file":"PollingOperation.js","sourceRoot":"","sources":["../../src/lib/PollingOperation.ts"],"names":[],"mappings":";;;AAAA,SAAS,gBAAgB,CACxB,MAAS;IAET,OAAO,CACN,MAAM,KAAK,IAAI;QACf,MAAM,KAAK,SAAS;QACpB,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CACvB,CAAA;AACF,CAAC;AAsBD,MAAM,cAAkB,SAAQ,KAAK;IAEpC,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,iDAAiD;QACjD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAA;QACrD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;IACnB,CAAC;CACD;AAuCD,SAAgB,gBAAgB,CAC/B,OAEyE;IAEzE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAA;IACzC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAA;IACxC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;IACnC,mFAAmF;IACnF,MAAM,SAAS,GACd,OAAO,CAAC,SAAS,IAAK,gBAA2C,CAAA;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAE5B,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE;YACvB,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAA;gBAChC,8DAA8D;gBAC9D,IAAI,CAAC,SAAS,CAAC,MAAa,CAAC,EAAE,CAAC;oBAC/B,MAAM,KAAK,GAAG,IAAI,cAAc,CAAI,yBAAyB,CAAC,CAAA;oBAC9D,KAAK,CAAC,MAAM,GAAG,MAAM,CAAA;oBACrB,MAAM,KAAK,CAAA;gBACZ,CAAC;gBACD,OAAO,CAAC,MAAM,CAAC,CAAA;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;oBACtC,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;gBAC3B,CAAC;qBAAM,CAAC;oBACP,MAAM,CAAC,KAAK,CAAC,CAAA;gBACd,CAAC;YACF,CAAC;QACF,CAAC,CAAA;QAED,IAAI,EAAE,CAAA;IACP,CAAC,CAAC,CAAA;AACH,CAAC;AAnCD,4CAmCC"}

package/dist/lib/QuerySubscription.d.ts

@@ -0,0 +1,103 @@
+import TypedEmitter from 'typed-emitter';
+export declare function QuerySubscription<T>(options: QuerySubscriptionConstructorWithPredicate<T>): _QuerySubscription<T>;
+export declare function QuerySubscription<T>(options: QuerySubscriptionConstructorsWithoutPredicate<T & {
+    items: Array<unknown>;
+}>): _QuerySubscription<T>;
+type QuerySubscriptionReturnValue<T> = void | null | undefined | T | true | false;
+type QuerySubscriptionPredicate<T> = (previous: T | undefined, current: T) => QuerySubscriptionReturnValue<T> | Promise<QuerySubscriptionReturnValue<T>>;
+type QuerySubscriptionEvents<T> = {
+    update: (update: T) => void;
+};
+interface QuerySubscriptionConstructorBase<T> {
+    query: () => Promise<T>;
+    interval?: number;
+}
+interface QuerySubscriptionConstructorWithPredicate<T> extends QuerySubscriptionConstructorBase<T> {
+    predicate: QuerySubscriptionPredicate<T>;
+}
+interface QuerySubscriptionConstructorsWithoutPredicate<T extends {
+    items: Array<unknown>;
+}> extends QuerySubscriptionConstructorBase<T> {
+    /** predicate to check if the result is valid - optional when T has items array */
+    predicate?: QuerySubscriptionPredicate<T>;
+}
+/**
+ * @description QuerySubscription is a utility class that allows you to subscribe to a query and receive updates when the query result changes.
+ * It is useful for polling operations where you want to receive updates when the result of a query changes, such as when a process instance is created or updated.
+ * It uses a predicate function to determine whether to emit an update event. When using the Orchestration Cluster API, the default predicate checks if the result has new items compared to the previous state.
+ * The predicate function receives the previous state and the current state of the query result and should return a value that indicates whether to emit an update.
+ * If the predicate returns `true`, the current state is emitted. If it returns an object, that object is emitted as the update.
+ * If it returns `false`, no update is emitted.
+ * @experimental This is an experimental feature and may change in the future.
+ * It is not yet stable and may have breaking changes in future releases. We're still working on it, and we welcome feedback.
+ * Please use it with caution and be prepared for potential changes.
+ * @example
+ * ```ts
+ * const query = () =>
+ *   c8.searchProcessInstances({
+ *     filter: {
+ *     processDefinitionKey: key,
+ *     state: 'ACTIVE',
+ *   },
+ *   sort: [{ field: 'startDate', order: 'ASC' }],
+ * })
+ *
+ * const subscription = QuerySubscription({
+ *   query,
+ *   predicate: (previous, current) => { // This is the default predicate, shown here for clarity
+ *     const previousItems = (previous?.items ?? []) as Array<unknown>
+ *     const currentItems = current.items.filter(
+ *       (item) =>
+ *         !previousItems.some((prevItem) => isDeepStrictEqual(prevItem, item))
+ *     )
+ *     if (currentItems.length > 0) {
+ *       return {
+ *         ...current,
+ *         items: currentItems,
+ *         page: { ...current.page, totalItems: currentItems.length },
+ *       }
+ *     }
+ *     return false // No new items, do not emit
+ *   },
+ *   interval: 500,
+ * })
+ * subscription.on('update', (data) => {
+ *   console.log('Received new processes:', data.items)
+ * })
+ * // After some time
+ * subscription.stop() // Stop polling when no longer needed, you can also call `start()` to resume polling
+ * subscription.cancel() // Or cancel the subscription to free resources
+ * ```
+ * @see {@link PollingOperation} for a simpler polling operation that does a single query.
+ */
+declare class _QuerySubscription<T> {
+    private _query;
+    /** The current state of the query, used to compare with the next result */
+    private _state;
+    private _predicate;
+    private _pollHandle;
+    /** We prevent further polling while we are calculating the predicate */
+    private _predicateLock;
+    /** We prevent further polling while we are processing the current poll */
+    private _pollLock;
+    private _interval;
+    private emitter;
+    on: <E extends 'update'>(event: E, listener: QuerySubscriptionEvents<T>[E]) => TypedEmitter<QuerySubscriptionEvents<T>>;
+    off: <E extends 'update'>(event: E, listener: QuerySubscriptionEvents<T>[E]) => TypedEmitter<QuerySubscriptionEvents<T>>;
+    once: <E extends 'update'>(event: E, listener: QuerySubscriptionEvents<T>[E]) => TypedEmitter<QuerySubscriptionEvents<T>>;
+    private emit;
+    removeListener: <E extends 'update'>(event: E, listener: QuerySubscriptionEvents<T>[E]) => TypedEmitter<QuerySubscriptionEvents<T>>;
+    removeAllListeners: <E extends 'update'>(event?: E | undefined) => TypedEmitter<QuerySubscriptionEvents<T>>;
+    prependListener: <E extends 'update'>(event: E, listener: QuerySubscriptionEvents<T>[E]) => TypedEmitter<QuerySubscriptionEvents<T>>;
+    prependOnceListener: <E extends 'update'>(event: E, listener: QuerySubscriptionEvents<T>[E]) => TypedEmitter<QuerySubscriptionEvents<T>>;
+    listeners: <E extends 'update'>(event: E) => QuerySubscriptionEvents<T>[E][];
+    private _poll?;
+    constructor(options: QuerySubscriptionConstructorWithPredicate<T> | QuerySubscriptionConstructorsWithoutPredicate<T & {
+        items: Array<unknown>;
+    }>);
+    pause(): void;
+    cancel(): void;
+    resume(): void;
+    poll(): Promise<void>;
+}
+export {};

package/dist/lib/QuerySubscription.js

@@ -0,0 +1,179 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuerySubscription = void 0;
+const node_events_1 = __importDefault(require("node:events"));
+const node_util_1 = require("node:util");
+const AsyncTrace_1 = require("./AsyncTrace");
+function QuerySubscription(options) {
+    return new _QuerySubscription(options);
+}
+exports.QuerySubscription = QuerySubscription;
+/**
+ * @description The default predicate function for QuerySubscription.
+ * It checks if the current query result has new items compared to the previous state.
+ * If there are new items, it returns the current state with only the new items and updates the totalItems count.
+ * If there are no new items, it returns false, indicating that no update should be emitted.
+ * @param previous the previous state of the query result
+ * @param current the current state of the query result
+ * @returns - If there are new items, returns the current state with only the new items and updated totalItems count.
+ * - If there are no new items, returns false, indicating that no update should be emitted.
+ */
+function defaultPredicate(previous, current) {
+    const previousItems = (previous?.items ?? []);
+    const currentItems = current.items.filter((item) => !previousItems.some((prevItem) => (0, node_util_1.isDeepStrictEqual)(prevItem, item)));
+    if (currentItems.length > 0) {
+        return {
+            ...current,
+            items: currentItems,
+            page: { ...current.page, totalItems: currentItems.length },
+        };
+    }
+    return false; // No new items, do not emit
+}
+/**
+ * @description QuerySubscription is a utility class that allows you to subscribe to a query and receive updates when the query result changes.
+ * It is useful for polling operations where you want to receive updates when the result of a query changes, such as when a process instance is created or updated.
+ * It uses a predicate function to determine whether to emit an update event. When using the Orchestration Cluster API, the default predicate checks if the result has new items compared to the previous state.
+ * The predicate function receives the previous state and the current state of the query result and should return a value that indicates whether to emit an update.
+ * If the predicate returns `true`, the current state is emitted. If it returns an object, that object is emitted as the update.
+ * If it returns `false`, no update is emitted.
+ * @experimental This is an experimental feature and may change in the future.
+ * It is not yet stable and may have breaking changes in future releases. We're still working on it, and we welcome feedback.
+ * Please use it with caution and be prepared for potential changes.
+ * @example
+ * ```ts
+ * const query = () =>
+ *   c8.searchProcessInstances({
+ *     filter: {
+ *     processDefinitionKey: key,
+ *     state: 'ACTIVE',
+ *   },
+ *   sort: [{ field: 'startDate', order: 'ASC' }],
+ * })
+ *
+ * const subscription = QuerySubscription({
+ *   query,
+ *   predicate: (previous, current) => { // This is the default predicate, shown here for clarity
+ *     const previousItems = (previous?.items ?? []) as Array<unknown>
+ *     const currentItems = current.items.filter(
+ *       (item) =>
+ *         !previousItems.some((prevItem) => isDeepStrictEqual(prevItem, item))
+ *     )
+ *     if (currentItems.length > 0) {
+ *       return {
+ *         ...current,
+ *         items: currentItems,
+ *         page: { ...current.page, totalItems: currentItems.length },
+ *       }
+ *     }
+ *     return false // No new items, do not emit
+ *   },
+ *   interval: 500,
+ * })
+ * subscription.on('update', (data) => {
+ *   console.log('Received new processes:', data.items)
+ * })
+ * // After some time
+ * subscription.stop() // Stop polling when no longer needed, you can also call `start()` to resume polling
+ * subscription.cancel() // Or cancel the subscription to free resources
+ * ```
+ * @see {@link PollingOperation} for a simpler polling operation that does a single query.
+ */
+class _QuerySubscription {
+    constructor(options) {
+        /** The current state of the query, used to compare with the next result */
+        this._state = undefined;
+        this._pollHandle = null;
+        /** We prevent further polling while we are calculating the predicate */
+        this._predicateLock = false;
+        /** We prevent further polling while we are processing the current poll */
+        this._pollLock = false;
+        this._query = options.query;
+        if ('predicate' in options && options.predicate) {
+            this._predicate = options.predicate;
+        }
+        else {
+            // Use type assertion to handle the default predicate
+            this._predicate = defaultPredicate;
+        }
+        this._interval = options.interval || 1000;
+        this.resume();
+        this.emitter = new node_events_1.default();
+        // Delegate all EventEmitter methods to the internal emitter
+        this.on = this.emitter.on.bind(this.emitter);
+        this.off = this.emitter.off.bind(this.emitter);
+        this.once = this.emitter.once.bind(this.emitter);
+        this.emit = this.emitter.emit.bind(this.emitter);
+        this.removeListener = this.emitter.removeListener.bind(this.emitter);
+        this.removeAllListeners = this.emitter.removeAllListeners.bind(this.emitter);
+        this.prependListener = this.emitter.prependListener.bind(this.emitter);
+        this.prependOnceListener = this.emitter.prependOnceListener.bind(this.emitter);
+        this.listeners = this.emitter.listeners.bind(this.emitter);
+    }
+    pause() {
+        if (!this._pollHandle) {
+            return;
+        }
+        clearInterval(this._pollHandle);
+        this._pollHandle = null;
+        this._pollLock = false;
+    }
+    cancel() {
+        this.pause();
+        this._state = undefined;
+        this._poll = undefined;
+        this._predicateLock = false;
+        this._pollLock = false;
+        this.removeAllListeners();
+    }
+    resume() {
+        if (this._pollHandle) {
+            return;
+        }
+        this._pollHandle = setInterval(() => (0, AsyncTrace_1.runWithAsyncErrorContext)(this.poll.bind(this), 'QuerySubscription'), this._interval);
+    }
+    async poll() {
+        if (this._pollLock ||
+            this._predicateLock ||
+            this.listeners('update').length === 0) {
+            return;
+        }
+        this._pollLock = true;
+        try {
+            this._poll = this._query();
+            const current = await this._poll;
+            if (this._state) {
+                // If we have a previous state, check if it is the same as the current one
+                if ((0, node_util_1.isDeepStrictEqual)(this._state, current)) {
+                    // If the state is the same, we don't need to emit an update
+                    this._pollLock = false;
+                    return;
+                }
+            }
+            this._predicateLock = true;
+            const diff = await this._predicate(this._state, current);
+            this._state = current;
+            if (diff) {
+                if (diff === true) {
+                    this.emit('update', current);
+                }
+                else {
+                    this.emit('update', diff);
+                }
+            }
+        }
+        catch (error) {
+            ;
+            error.message = `QuerySubscription: ${error.message}`;
+            throw error;
+        }
+        finally {
+            this._predicateLock = false;
+            this._pollLock = false;
+        }
+    }
+}
+//# sourceMappingURL=QuerySubscription.js.map

package/dist/lib/QuerySubscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuerySubscription.js","sourceRoot":"","sources":["../../src/lib/QuerySubscription.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@camunda8/sdk",
-	"version": "8.7.16",
+	"version": "8.7.17",
 	"description": "",
 	"main": "dist/index.js",
 	"scripts": {
@@ -15,10 +15,10 @@
 		"sm:stop8.8": "docker compose --env-file docker/8.8/.env -f docker/8.8/docker-compose-multitenancy.yaml down",
 		"sm:start8.8": "docker compose --env-file docker/8.8/.env -f docker/8.8/docker-compose-multitenancy.yaml up -d && docker/suppress-es-deprecation.sh",
 		"test": "cross-env CAMUNDA_UNIT_TEST=true jest '\\.unit\\.' -u --detectOpenHandles --runInBand --testPathIgnorePatterns integration --testPathIgnorePatterns local-integration --testPathIgnorePatterns disconnection --testPathIgnorePatterns multitenancy --testPathIgnorePatterns __tests__/config",
-		"test:integration": "jest --runInBand --testPathIgnorePatterns disconnection --testPathIgnorePatterns '\\.unit\\.' --testPathIgnorePatterns __tests__/config --testPathIgnorePatterns multitenancy --testPathIgnorePatterns __tests__/8.8 --testPathIgnorePatterns 8.7-sm-only --detectOpenHandles --verbose true -u",
+		"test:integration": "jest --testPathIgnorePatterns disconnection --testPathIgnorePatterns '\\.unit\\.' --testPathIgnorePatterns __tests__/config --testPathIgnorePatterns multitenancy --testPathIgnorePatterns __tests__/8.8 --testPathIgnorePatterns 8.7-sm-only --detectOpenHandles --verbose true -u",
 		"test:integration8.8": "jest --runInBand --testPathIgnorePatterns admin --testPathIgnorePatterns disconnection --testPathIgnorePatterns '\\.unit\\.' --testPathIgnorePatterns __tests__/config --testPathIgnorePatterns multitenancy --testPathIgnorePatterns 8.7-sm-only --detectOpenHandles --verbose true -u",
-		"test:multitenancy": "jest --runInBand --testPathIgnorePatterns disconnection --testPathIgnorePatterns admin --testPathIgnorePatterns '\\.unit\\.' --testPathIgnorePatterns __tests__/config --testPathIgnorePatterns __tests__/8.8 - --detectOpenHandles --verbose true -u",
-		"test:multitenancy8.8": "jest --runInBand --testPathIgnorePatterns disconnection --testPathIgnorePatterns admin --testPathIgnorePatterns '\\.unit\\.' --testPathIgnorePatterns __tests__/config - --detectOpenHandles --verbose true -u",
+		"test:multitenancy": "jest --testPathIgnorePatterns disconnection --testPathIgnorePatterns admin --testPathIgnorePatterns '\\.unit\\.' --testPathIgnorePatterns __tests__/config --testPathIgnorePatterns __tests__/8.8 - --detectOpenHandles --verbose true -u",
+		"test:multitenancy8.8": "jest --testPathIgnorePatterns disconnection --testPathIgnorePatterns admin --testPathIgnorePatterns '\\.unit\\.' --testPathIgnorePatterns __tests__/config - --detectOpenHandles --verbose true -u",
 		"test:local": "jest --runInBand --verbose true --detectOpenHandles local-integration -u",
 		"test:local-integration": "jest --runInBand --detectOpenHandles --verbose --testPathIgnorePatterns disconnection --testPathIgnorePatterns '\\.unit\\.' --testPathIgnorePatterns admin --testPathIgnorePatterns multitenancy --testPathIgnorePatterns __tests__/8.8 --testPathIgnorePatterns __tests__/config -u",
 		"test:docker": "jest --runInBand --testPathIgnorePatterns disconnection --testPathIgnorePatterns __tests__/config local-integration --detectOpenHandles --verbose true",