docs(postgrest): document that order() defaults to descending

[giovanirasia]

What kind of change does this PR introduce?

Documentation.

What is the current behavior?

order() declares bool ascending = false, so a call that omits the parameter
returns rows in descending order. The doc comment never states this. It only
says:

When [ascending] is true, the result will be in ascending order.

Both examples in the doc comment then pass ascending: false explicitly, which
suggests the opposite — that the parameter has to be passed to get descending
order, and that omitting it yields ascending.

This is easy to get wrong, because the default is inverted relative to two things
a developer is likely to expect:

• SQL's ORDER BY, which defaults to ASC
• postgrest-js, where order() destructures { ascending = true }

The failure is silent: the query succeeds and returns data, just in the wrong
order. In my case it survived unit tests and only surfaced when a historical
backfill read a series inverted.

There is also a small rendering bug in the same doc comment — the first code
fence is closed with four backticks instead of three, which breaks the block in
generated dartdoc.

What is the new behavior?

• The doc comment states the defaults for ascending and nullsFirst
  explicitly, and notes the divergence from SQL and postgrest-js.
• The first example now omits ascending, showing the actual default; a second
  example shows how to request ascending order.
• The stray fourth backtick is fixed.

Doc comment only — no behavioural change. Changing the default itself would be
breaking and is deliberately not proposed here.

Additional context

Happy to open a follow-up for the equivalent JSDoc in postgrest-js, which
likewise does not state its default. Let me know if that would be useful.

Summary by CodeRabbit

• Documentation
  • Clarified that descending order and nulls-last behavior are the defaults for ordering.
  • Added examples demonstrating how to explicitly request ascending order.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a6a832dc-34a7-4677-8fab-b136b9a86c9a

📥 Commits

Reviewing files that changed from the base of the PR and between 6979093 and 5f64d35.

📒 Files selected for processing (1)

• packages/postgrest/lib/src/postgrest_transform_builder.dart

---

📝 Walkthrough

Walkthrough

The order documentation now states that descending order and nulls-last behavior are defaults. It also explains differences from SQL and postgrest-js and adds examples for default descending and explicit ascending ordering.

Changes

Order documentation

Layer / File(s)	Summary
Document order defaults packages/postgrest/lib/src/postgrest_transform_builder.dart	The order documentation describes default descending and nulls-last behavior, differences from SQL and postgrest-js, and ascending-order examples.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested reviewers: spydon

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation change for order()'s descending default.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[spydon]

Thanks, we'll change the default of this in v3 (the default was changed in the js SDK a few years ago)