@camunda8/orchestration-cluster-api 10.0.0-alpha.38 → 10.0.0-alpha.39

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [10.0.0-alpha.39](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.38...v10.0.0-alpha.39) (2026-08-27)
+
+
+### Bug Fixes
+
+* **effect:** keep .paginate on the Effect client, as Streams ([#468](https://github.com/camunda/orchestration-cluster-api-js/issues/468)) ([b61cfbe](https://github.com/camunda/orchestration-cluster-api-js/commit/b61cfbe1b324b0a97bb1a77858c53c4de7156e37))
+
 # [10.0.0-alpha.38](https://github.com/camunda/orchestration-cluster-api-js/compare/v10.0.0-alpha.37...v10.0.0-alpha.38) (2026-08-27)
 
 

package/README.md

@@ -1269,7 +1269,7 @@ first-class [Effect](https://effect.website) surface — a client whose every me
 > resolution — set `"moduleResolution": "bundler"` (or `"node16"`/`"nodenext"`) in your
 > `tsconfig.json`. The Promise-first `.` entry is unaffected.
 
-<!-- snippet-exempt: uses SDK /effect subpath + optional effect peer not available in examples project -->
+<!-- snippet-source: examples/effect.ts,examples/readme-imports.txt | regions: ReadmeEffectClientImport+ReadmeEffectClient -->
 ```ts
 import { Effect } from 'effect';
 import {
@@ -1326,10 +1326,44 @@ Exports available from `.../effect`:
   the Effect `Clock`, timing out to `EventualConsistencyTimeout`).
 - Dependency injection: `CamundaEffect` (`Context.Service`) + `layer(options?)` (`Layer`) so worker /
   orchestration code composes via `Layer` and swaps a test double trivially.
+- Pagination: `.paginate(body, opts?)` on every `search*` method, returning an `EffectPaginator`
+  (`pages()` / `items()` → `Stream`, `toArray()` → `Effect`). See below.
 
 **Clock-class win:** `eventually` / `withTimeout` run on the Effect `Clock`, so `TestClock.adjust`
 advances eventual/timeout deterministically in tests — no real-clock burn.
 
+### Paginated Search as a `Stream`
+
+Every `search*` operation on the Effect client carries the same `.paginate` helper the
+Promise client installs, re-expressed in Effect terms: `pages()` and `items()` are
+`Stream`s and `toArray()` is an `Effect`. Pages are fetched lazily as they are pulled,
+and interrupting the fiber cancels the in-flight page request.
+
+<!-- snippet-source: examples/effect.ts,examples/readme-imports.txt | regions: ReadmeEffectPaginateImport+ReadmeEffectPaginate -->
+```ts
+import { Effect, Stream } from 'effect';
+import { createCamundaEffectClient } from '@camunda8/orchestration-cluster-api/effect';
+
+const camunda = createCamundaEffectClient();
+
+// Walk every ACTIVE process instance, 100 per request, without ever holding more
+// than one page in memory. `Stream.take` stops pulling — and so stops fetching.
+const activeKeys = await Effect.runPromise(
+  camunda.searchProcessInstances
+    .paginate({ filter: { state: 'ACTIVE' }, page: { limit: 100 } })
+    .items()
+    .pipe(
+      Stream.map((instance) => instance.processInstanceKey),
+      Stream.take(500),
+      Stream.runCollect
+    )
+);
+```
+
+Options: `maxPages` (safety cap), `mode` (`auto` | `cursor` | `offset`), and `consistency`
+(forwarded to the first page only — once paging is under way an empty page is
+end-of-results, not a stale read).
+
 ### Effect Job Workers
 
 The same subpath also exposes an **Effect-native job worker** — the long-running
@@ -1340,7 +1374,7 @@ and a `TerminalJobError` becomes `throwJobError` (caught by a BPMN error boundar
 uncaught). Success completes the job with the returned variables. It composes over the same
 activation/backpressure runtime the Promise worker uses — it does not reimplement activation.
 
-<!-- snippet-exempt: uses SDK /effect subpath + optional effect peer not available in examples project -->
+<!-- snippet-source: examples/effect.ts,examples/readme-imports.txt | regions: ReadmeEffectWorkerImport+ReadmeEffectWorker -->
 ```ts
 import { Effect, Schedule } from 'effect';
 import {
@@ -1352,8 +1386,12 @@ import {
 
 const program = Effect.gen(function* () {
   // Forked into the current Scope: interrupted (with a best-effort lease release) when
-  // the scope closes.
-  yield* createCamundaEffectWorker<{ ok: boolean }>({
+  // the scope closes. Let both type parameters infer — supplying only the completion-
+  // variable type (`createCamundaEffectWorker<{ ok: boolean }>(…)`) makes TypeScript
+  // fall back to the *default* for the handler's requirements (`R = never`) rather
+  // than inferring it, so a handler with dependencies would stop compiling. See
+  // "Injecting Services into a Handler".
+  yield* createCamundaEffectWorker({
     type: 'payment-processing',
     maxJobsToActivate: 10, // activation batch size
     concurrency: 10, // max jobs handled in parallel (backpressure)
@@ -1371,7 +1409,10 @@ const program = Effect.gen(function* () {
         if (yield* isServiceDown()) {
           // Retryable → failJob(retries - 1) with a re-activation backoff.
           return yield* Effect.fail(
-            new RetryableJobError({ message: 'downstream unavailable', retryBackoff: '5 seconds' })
+            new RetryableJobError({
+              message: 'downstream unavailable',
+              retryBackoff: '5 seconds',
+            })
           );
         }
         return { ok: true }; // success → completeJob(variables)
@@ -1402,6 +1443,85 @@ Worker exports from `.../effect`:
 `Clock`, so `TestClock.adjust` bounds activation/retry timing in virtual time — the whole loop is
 deterministic in tests, with no real-clock burn.
 
+### Injecting Services into a Handler
+
+A handler is `(job) => Effect.Effect<A, JobError, R>`, and `R` — whatever services the handler
+depends on — is threaded out through `createCamundaEffectWorker` / `workerLayer` into the worker's
+own requirements. So a handler's dependencies are provided, and swapped for mocks, exactly like
+any other `Layer`.
+
+<!-- snippet-source: examples/effect.ts,examples/readme-imports.txt | regions: ReadmeEffectWorkerServicesImport+ReadmeEffectWorkerServices -->
+```ts
+import { Context, Effect, Layer } from 'effect';
+import {
+  CamundaEffect,
+  type CamundaEffectClient,
+  layer,
+  workerLayer,
+} from '@camunda8/orchestration-cluster-api/effect';
+
+// A service the handler depends on. Nothing about it is Camunda-specific — it is an
+// ordinary Effect service.
+class PaymentGateway extends Context.Service<
+  PaymentGateway,
+  { readonly charge: (amount: number) => Effect.Effect<string> }
+>()('PaymentGateway') {}
+
+// The handler's requirements flow out through the worker's own requirements, so the
+// worker layer asks for `PaymentGateway` just like it asks for the Camunda client.
+const paymentWorker = workerLayer({
+  type: 'payment-processing',
+  handler: (job) =>
+    Effect.gen(function* () {
+      const gateway = yield* PaymentGateway;
+      return { receipt: yield* gateway.charge(Number(job.variables.amount)) };
+    }),
+});
+// paymentWorker: Layer<never, never, CamundaEffect | PaymentGateway>
+
+// Production: the real gateway and a real client.
+const liveWorker = paymentWorker.pipe(
+  Layer.provide(
+    Layer.succeed(PaymentGateway, {
+      charge: (amount) => Effect.succeed(`live-receipt-${amount}`),
+    })
+  ),
+  Layer.provide(layer())
+);
+
+// Tests: the same worker with *both* dependencies swapped. `CamundaEffect` is a service
+// too, so the broker is mocked exactly like the gateway — the worker runs end-to-end
+// with neither a payment provider nor a broker.
+const fakeClient = {
+  activateJobs: () => Effect.succeed({ jobs: [] }),
+  completeJob: () => Effect.void,
+  failJob: () => Effect.void,
+  throwJobError: () => Effect.void,
+} as unknown as CamundaEffectClient;
+
+const mockedWorker = paymentWorker.pipe(
+  Layer.provide(Layer.succeed(PaymentGateway, { charge: () => Effect.succeed('mock-receipt') })),
+  Layer.provide(Layer.succeed(CamundaEffect, fakeClient))
+);
+```
+
+`Layer.succeed(CamundaEffect, fakeClient)` is what the SDK's own worker tests use; see
+[tests/effect-worker-di.test.ts](tests/effect-worker-di.test.ts) for worked examples that mock both
+dependencies and drive the loop to a `completeJob` / `failJob` under `TestClock`.
+
+> **Gotcha — let both type parameters infer.** `createCamundaEffectWorker<A, R>` has `R = never`
+> as its default, and TypeScript does not infer a type parameter when only *some* are supplied.
+> So `createCamundaEffectWorker<{ ok: boolean }>({ ... })` pins `R` to `never`, and a handler with
+> dependencies fails to compile with an error pointing at the handler rather than at the missing
+> type argument:
+>
+> ```
+> Type 'PaymentGateway' is not assignable to type 'never'.
+> ```
+>
+> Omit both — `A` is inferred from the handler's success value — or supply both
+> (`createCamundaEffectWorker<{ receipt: string }, PaymentGateway>({ ... })`).
+
 ## Eventual Consistency Polling
 
 Some endpoints accept consistency management options. Pass a `consistency` block (where supported) with `waitUpToMs` and optional `pollIntervalMs` (default 500). If the condition is not met within timeout an `EventualConsistencyTimeoutError` is thrown.