@adonis-agora/durable 0.38.3 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @adonis-agora/durable
 
+## 0.39.0
+
+### Minor Changes
+
+- [#140](https://github.com/DavideCarvalho/adonis-agora-durable/pull/140) [`5c57004`](https://github.com/DavideCarvalho/adonis-agora-durable/commit/5c570047165530c6b7bbe4c868d747e4405da49d) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - **Breaking:** run listings are paged with `page`/`size` instead of `limit`/`offset`, and paging is now 1-BASED.
+  
+  Every `@adonis-agora/*` library now exposes the same offset-pagination interface as `@adonis-agora/filter` (`FilterInput.page`/`.size`, resolved to its `ResolvedPagination { page, size }`): a **1-based** page number defaulting to `1`, and a page size. One query-string builder, one mental model, whether the listing behind it is a Lucid model or this engine's run store. Defaults and caps are unchanged — the dashboard listing still defaults to 50 rows and still caps at 200; only the spelling and the base moved.
+  
+  The 0-based offset has not disappeared, it has become internal: `runPageWindow(query)` (newly exported) resolves a `RunQuery`'s `page`/`size` into the `{ limit, offset }` a store actually spends, and it is the one place that arithmetic lives. Custom `StateStore` implementations should call it rather than compute an offset by hand; the conformance kit asserts the resulting semantics (notably that **no `size` means no bound** — a store must not invent a default window).
+  
+  What changed, concretely:
+  
+  - `RunQuery.limit`/`.offset` → `RunQuery.page`/`.size`. This is also the cross-pod wire shape, so a `listRuns` gateway request between a proxy pod and a store pod carries `size` where it carried `limit` (the golden wire fixtures moved with it — polyglot SDKs asserting those bytes need the same rename).
+  - `GET /durable/api/runs` parses `?page=&size=` and answers `{ runs, meta: { page, size, count }, statuses }`. The pagination envelope key is **`meta`** — the name AdonisJS/Lucid's own `.paginate()` uses, and where `@adonis-agora/filter`'s offset path lands, so every `@adonis-agora/*` listing spells it the same (it also spares you `body.page.page`). It replaces the previous `limit`/`offset` echo; read the window off `body.meta`. `limit`/`offset` query params are now ignored like any other unknown flat param, so a stale client gets an unpaged first page rather than a `400`.
+  - The console's client (`durableClient.runsPage`, `RunPageOptions`, `runQueryString`) sends `page`/`size` and pages the runs list 1-based; `RunsPage` carries that window as `.meta`.
+  
+  Deliberately NOT renamed: `GET /durable/api/runs/values` keeps `limit`/`offset`. That endpoint is filter's own group-by-count aggregation (`groupByCount[limit]`/`groupByCount[offset]`, `GroupByCountFromRequestOptions`), not a run listing — `limit`/`offset` IS the aligned spelling there, and respelling it would diverge from the lib rather than match it. The ace `durable:runs --limit` flag also keeps its name: it is a row cap with no page companion, and it maps to `size` internally.
+  
+  Migration — the offset you were sending is `(page - 1) * size`:
+  
+  ```ts
+  // before
+  await engine.listRuns({ workflow: 'checkout', limit: 25, offset: 50 })
+  // after — third page of 25
+  await engine.listRuns({ workflow: 'checkout', page: 3, size: 25 })
+  ```
+  
+  ```
+  # before
+  GET /durable/api/runs?status=failed&limit=25&offset=50
+  # after
+  GET /durable/api/runs?status=failed&page=3&size=25
+  ```
+  
+  ```ts
+  // reading the window back off a /runs response
+  - const { limit, offset } = body.page
+  + const { page, size, count } = body.meta
+  ```
+  
+  ```ts
+  // a store adapter's listRuns
+  - if (query.limit !== undefined) q.limit(query.limit)
+  - if (query.offset !== undefined) q.offset(query.offset)
+  + const { limit, offset } = runPageWindow(query)
+  + if (limit !== undefined) q.limit(limit)
+  + if (offset > 0) q.offset(offset)
+  ```
+
+### Patch Changes
+
+- [#138](https://github.com/DavideCarvalho/adonis-agora-durable/pull/138) [`4916be2`](https://github.com/DavideCarvalho/adonis-agora-durable/commit/4916be2b7129d6bceba2e7d2fc9c302b00d2c283) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Routine dependency refresh.
+  
+  `@adonis-agora/durable`'s optional `vitest` peer now accepts `^5.0.0` too (`^3.0.0 || ^4.0.0 || ^5.0.0`). The testing kit is exercised against vitest 5 in CI and the range only widens, so nothing that resolved before stops resolving. The package's stale `zod` devDependency (`3.25.76`) is realigned with the `zod@4.5.4` it already declares — and pnpm already resolved — as a runtime dependency; no published dependency range changes.
+  
+  `@adonis-agora/durable-eslint-plugin` picks up `@typescript-eslint/utils@8.69.0`.
+
 ## 0.38.3
 
 ### Patch Changes