supabase / supabase-flutter / 31095684885

89%

push

github

fix!: make order() default to ascending (#1658)

Closes #1638

## What kind of change does this PR introduce?

Breaking change.

## What is the current behavior?

`order()` defaults `ascending` to `false` in two places, so omitting the
parameter sorts descending:

- `PostgrestTransformBuilder.order()`
- `SupabaseStreamBuilder.order()`

`.order('created_at')` therefore returns newest rows first, which
disagrees with SQL's `ORDER BY` (defaults to `ASC`) and with
`postgrest-js` (`{ ascending = true }`). The failure is silent: the
query succeeds, the row count and types are right, only the order is
wrong.

The default was never chosen for Dart. `postgrest-dart` `7a8f8b7`
(2020-09-10) ported the first `order()` from the pre-TypeScript
`postgrest-js`, which then had `order(columnName, ascending = false,
nullsFirst = false)`. `postgrest-js` `2960d09` moved to `{ ascending =
true }` ten days later and Dart never followed. #1637 documented the
current behavior in the meantime.

Two examples in this repository were already wrong because of it, which
is the clearest evidence that the default surprises people:

- `examples/realtime_room/lib/room_repository.dart` says "SELECT the
existing messages once, oldest first" and returned them newest first.
- `examples/database_crud/lib/tasks_repository.dart` says "ordered
alphabetically by name" and returned projects in reverse alphabetical
order.

Both are now correct without touching their query code.

## What is the new behavior?

- `PostgrestTransformBuilder.order()`: `bool ascending = true`.
- `SupabaseStreamBuilder.order()`: `bool ascending = true`, so
`.stream()` and `.select()` agree on what an unqualified `.order()`
means.
- Doc comments on both state the default and drop the note about
diverging from SQL and `postgrest-js`, since there is no longer a
divergence.

`nullsFirst` is unchanged at `false`. That already matched
`postgrest-js` and PostgREST.

## Migration

`MIGRATION.md` gets an `order() now sorts ascen... (continued)

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

5618 of 6451 relevant lines covered (87.09%)

4.05 hits per line