supabase / supabase-flutter / 38390096271

92%

push

github

feat(auth): add a lazy Stream<User> paginator over admin listUsers (#1954)

`admin.listUsers()` returns one page and a `nextPage` cursor, so every
caller writes the same loop to walk the pages. `admin.listAllUsers()`
does it for them:

```dart
await for (final user in supabase.auth.admin.listAllUsers(perPage: 100)) {
  print(user.email);
}
```

It is an `async*` stream that follows `nextPage` from the `Link` header.
The next page is only requested once the previous one has been consumed,
so `break`, `take()` or `first` stop at the page the caller stopped on.
It ends at an empty page, which GoTrue only returns past the end of the
list, so a cancelled stream never starts another request without first
reaching a `yield`.

As a safeguard against a misbehaving server, the stream ends when a
`next` link does not point past the current page. The dartdoc notes that
pages are offsets, so a user created or deleted while the stream is read
can be emitted twice or skipped.

The `listUsers` dartdoc and the `MIGRATION.md` section on `listUsers()`
pagination now point to it in place of the manual loop. The symbol is
registered under the existing `auth.admin.list_users` capability, as the
Swift paginator is in supabase/supabase-swift#1352.

Linear: SDK-2134


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added a way to stream all users from the admin user list, fetching
pages in order as needed.
* **Documentation**
* Updated pagination guidance to explain how to find the next page and
how to iterate through all users.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

6 of 6 new or added lines in 1 file covered. (100.0%)

9514 of 10389 relevant lines covered (91.58%)

5.29 hits per line