supabase / supabase-flutter / 38740500642

92%

Build Type

push

github

Committed by web-flow

Commit Message

feat(postgrest)!: order and limit inside a to-many embed on the typed surface (#1960)

## Summary

The typed `order()` had no way to address an embed, and the typed
`limit()` and `range()` still took an untyped `String? referencedTable`.
Sorting the rows inside a to-many embed was therefore impossible on the
typed surface, so `limit(1, referencedTable: 'books')` trimmed an
unsorted embed and returned an arbitrary row.

This adds `embedded()` to the typed transform builder, following the
scope Swift shipped in supabase/supabase-swift#1458:

```dart
await client
    .table(Authors.table)
    .selectOnly([Authors.name, Authors.books.select([Books.title])])
    .embedded(
      Authors.books,
      (books) => books.order(Books.createdAt.desc()).limit(1),
    );
// select=name,books(title)&books.order=created_at.desc&books.limit=1
```

- `embedded()` takes a `PostgrestToManyRelation<Row, Target>`. The
callback receives a `PostgrestEmbeddedScope<Target>`, so ordering by a
column of another table does not compile.
- The scope offers `order`, `limit`, `range` and `embedded`. Nested
scopes render dotted paths, such as `books.reviews.limit=3`.
- An aliased embed is addressed by its alias.
- Repeated scopes of one embed append their sort keys, and the last
limit or range wins.
- Scopes also apply to the rows a mutation returns.

## Breaking

The typed `limit()` and `range()` no longer take `referencedTable`. The
typed surface is experimental, so the change is covered in the "Moving
from `from()` to the typed table API" section of `MIGRATION.md` and not
as its own breaking section.

## Out of scope

Filtering inside an embed and the `requiring` (`!inner`) counterpart
will ship together in a follow-up. An embedded filter without
`requiring` silently keeps every parent row.

## Other changes

- `PostgrestTableRequest` is now `@internal`. It was already hidden from
the package export, and the annotation keeps its fields out of the
compliance symbol check.
- Removed ... (continued)

Coverage Stats

47 of 47 new or added lines in 5 files covered. (100.0%)

62 existing lines in 6 files now uncovered.

10066 of 10910 relevant lines covered (92.26%)

5.36 hits per line