add ascending to IterableExtension.sortedBy

[arthurbcd]

sortedBy is one of the best extensions of this package.

It allows us to easily sort, but we can't set if the order comparaison is ascending/descending, it always defaults to "natural ordering".

This PR simplifies this process so we can simply decide it based on the added ascending parameter in the sortedBy extension.

  List<T> sortedBy<K extends Comparable<K>>(
    K Function(T element) keyOf, {
    bool ascending = true,
  })

This is useful, because without it, we would have to do additional operations bringing either more boilerplate or additional computations. By adding this named boolean we can make it straightforward.

For many developers, especially those who might not be as familiar with comparators and more advanced functional programming concepts, having a straightforward boolean parameter makes the API more accessible and user-friendly.

The boolean ascending is a natural state. It’s a common need to toggle sort order, and doing so with a single extension method and a simple parameter makes the code more readable and maintainable. Adopting this familiar pattern in sortedBy makes it feel more intuitive and consistent, making the intent of the code clearer.

Flutter itself uses this pattern for sorting, as we can see in flutter/lib/src/material/data_table.dart:

/// Signature for [DataColumn.onSort] callback.
typedef DataColumnSortCallback = void Function(int columnIndex, bool ascending);

I find this extension incredibly useful and have always relied on a version of it. I dedicated time to updating it for the community because I believe it addresses a fundamental and widely shared need across projects.

Thank you for taking the time to review this PR—I hope it proves valuable!

Added tests ✅
Retrocompatible ✅
Not a breaking change ✅

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[natebosch]

My initial inclination is to not add this - I don't think we have a similar argument in other sorting methods, we instead expect callers to arrange an appropriate compare callback.

Here I think it's better to ask users to call sortedByCompare for this use case.

cc @lrhn WDYT?

[natebosch]

At the risk of premature optimization, I think we should keep this as a static tear-off instead of a new lambda on every use. If we decide to go forward with this change I think something like

final compare = ascending ? compareComparable : compareComparableDescending;

int compareComparableDescending<T extends Comparable<T>>(T a, T b) => b.compareTo(a);

[lrhn]

If it's typed, it's a new closure on every use anyway, because generic instantiation also causes a new closure.
That said: I don't want to do the branch on every comparison, so something like what @natebosch says is better.

[lrhn]

I think it's an OK feature.
I would reverse the parameter name (to make he default value false) and give every sorting function the same treatment (if possible).

[lrhn]

I think I would prefer to name it descending, so the default is false.
Just because it's usually best to have "nothing" mean false.
Then it feels like you are opting in to the non-default behavior. Using ascending: false feels ... conflicted. You are opting out of the default behavior, but that doesn't directly say what it opts in to.

[lrhn]

If it's typed, it's a new closure on every use anyway, because generic instantiation also causes a new closure.
That said: I don't want to do the branch on every comparison, so something like what @natebosch says is better.

[lrhn]

The sorted function should get the same behavior. Really, every sort function should behave the same way if at all possible.
(It's probably impossible because there is some sort([int Function(T, T) compare]) somewhere which prevents a named parameter.)