supabase / supabase-flutter / 29156955642

87%

push

github

feat(storage): add listPaginated for cursor-based file listing (#1579)

## Summary

Adds `StorageFileApi.listPaginated`, backed by the storage
`object/list-v2/{bucketId}` endpoint, supporting cursor-based pagination
and hierarchical (delimiter) listing.

New API, using descriptive Dart names rather than the supabase-js
`listV2`/`SearchV2*` naming:
- `listPaginated({PaginatedSearchOptions options})` returns
`PaginatedListResult`
- `PaginatedSearchOptions` (limit, prefix, cursor, withDelimiter,
sortBy)
- `PaginatedListResult` (hasNext, folders, objects, nextCursor)
- `PaginatedFile`, `PaginatedFolder`
- `FileSort` (column, order), where `column` and `order` are the enums
`FileSortColumn` and `FileSortOrder`

**Outcome:** implemented
**Reference:** supabase-js `StorageFileApi.listV2` (`object/list-v2`)
**Compliance matrix:** `storage.file_buckets.list_files_paginated` ->
implemented

## Notes
- Idiomatic Dart rather than a transliteration of the JS shape:
descriptive type names (`Paginated*`) instead of the `V2` suffix, and
enhanced enums `FileSortColumn` and `FileSortOrder` for the sort options
instead of raw strings, matching the existing
`BucketSortColumn`/`BucketSortOrder` pattern.
- `withDelimiter` is camelCase on the Dart side and mapped to the
`with_delimiter` wire key; `FileSortColumn` is serialized via
`snakeCase` (for example `createdAt` becomes `created_at`) and
`FileSortOrder` via its `asc`/`desc` value.
- Unit tests cover the paginated result parsing (options body, folders
and objects, cursor) and the empty-body default.
- All new public symbols are registered under the capability.

## Stacking
Second of three stacked PRs. Base: #1578 (cacheNonce). Review and merge
#1578 first.

44 of 44 new or added lines in 2 files covered. (100.0%)

4714 of 5408 relevant lines covered (87.17%)

4.03 hits per line