You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/content/docs/developer-guides/migration-guide.md
+97Lines changed: 97 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,103 @@ If you are coming from an earlier version of any of the Synapse packages, you wi
9
9
10
10
---
11
11
12
+
## Unreleased
13
+
14
+
### Action: Migrate paginated reads to cursors and pages
15
+
16
+
Paginated actions in `@filoz/synapse-core` now share a bounded cursor interface:
17
+
18
+
```ts
19
+
typePaginationOptions= {
20
+
cursor?:bigint
21
+
limit?:bigint
22
+
}
23
+
24
+
typePage<T> = {
25
+
items:T[]
26
+
nextCursor?:bigint
27
+
}
28
+
```
29
+
30
+
Replace contract-specific `offset`, `hasMore`, and array result handling with `cursor`, `items`, and `nextCursor`. Treat `nextCursor` as opaque and pass it back unchanged. Omitting `limit` uses a bounded default; `limit:0n` is now rejected instead of meaning “fetch everything.”
31
+
32
+
```ts
33
+
// before
34
+
const dataSets =awaitgetClientDataSets(client, {
35
+
address,
36
+
offset: 0n,
37
+
limit: 0n,
38
+
})
39
+
40
+
// after: read one page
41
+
const page =awaitgetClientDataSets(client, {
42
+
address,
43
+
limit: 100n,
44
+
})
45
+
console.log(page.items)
46
+
47
+
const nextPage =page.nextCursor===undefined
48
+
?undefined
49
+
:awaitgetClientDataSets(client, {
50
+
address,
51
+
cursor: page.nextCursor,
52
+
limit: 100n,
53
+
})
54
+
```
55
+
56
+
Use the generic `paginate()` generator to traverse every page or accumulate all items:
This result change applies to paginated payment rails, FWSS client data sets and approved providers, PDP pieces and CID matches, and service-provider registry queries. Payment rail pages additionally include `total`.
74
+
75
+
The `WarmStorageService.getClientDataSets()` and `getClientDataSetIds()` methods in `@filoz/synapse-sdk` expose the same page interface. Higher-level SDK methods whose names promise all results, such as provider listing and rail listing methods, continue to return complete arrays and paginate internally.
76
+
77
+
### Action: Replace `getActivePieces` with `getActivePiecesByCursor`
78
+
79
+
The offset-based `getActivePieces` action was removed. Use piece-ID cursor pagination instead:
`findPieceIdsByCid`, `getPieces`, and `getPiecesWithMetadata` also return pages and accept `cursor` rather than `startPieceId` or `offset` at the action level.
104
+
105
+
Raw `*Call` helpers in `@filoz/synapse-core` remain ABI-oriented: provide their required contract-facing `offset` or `startPieceId` and `limit` fields explicitly when constructing multicalls.
106
+
107
+
---
108
+
12
109
## 1.0.0
13
110
14
111
### Action: Replace `terminateDataSet` with `terminateService`
The `@filoz/synapse-core/chains` subpath exports chain definitions with all contract addresses pre-configured for Filecoin Mainnet (`mainnet`) and Filecoin testnet (`calibration`) networks.
70
70
71
+
## Pagination
72
+
73
+
Collection actions in Synapse Core return one bounded page at a time. They share the same options and result shapes:
74
+
75
+
```ts
76
+
typePaginationOptions= {
77
+
cursor?:bigint
78
+
limit?:bigint
79
+
}
80
+
81
+
typePage<T> = {
82
+
items:T[]
83
+
nextCursor?:bigint
84
+
}
85
+
```
86
+
87
+
Some actions also return a `total` alongside the page. A cursor is an opaque continuation value: pass the returned `nextCursor` back as `cursor` without calculating or incrementing it yourself. An omitted `limit` uses the action's bounded default, while an explicit limit must be greater than `0n`.
Use `paginate()` when you want to traverse every page. It follows `nextCursor`, yields individual items, and rejects a repeated or non-advancing cursor. A normal `break` exits the `for await` loop, closes the generator, and prevents any further page requests.
The exported `*Call` helpers remain literal ABI adapters for multicalls. They use contract-facing fields such as `offset` or `startPieceId` and require an explicit `limit`; cursor translation and default limits are handled by the corresponding action.
143
+
71
144
## Payments
72
145
73
146
Query account balances, deposit funds, manage operator approvals, and settle payment rails on the Filecoin Pay contract.
0 commit comments