feat: add sort shorthand for sorting by property name

[aleclarson]

Tip

The owner of this PR can publish a preview release by commenting /publish in this PR. Afterwards, anyone can try it out by running pnpm add radashi@pr<PR_NUMBER>.

Description

sort(array, 'key')
// ^ identical to…
sort(array, obj => obj.key)

The property name may be a string, number, or symbol.

This PR will affect the following functions:

• sort
• alphabetical
• min
• max

Depends on #34, #35, #43

Checklist

• Changes are covered by tests if behavior has been changed or added
• Tests have 100% coverage
• If code changes were made, the documentation (in the /docs directory) has been updated

Resolves

[Minhir]

I'm not sure if leftValue > rightValue ? 1 : leftValue < rightValue ? -1 : 0 is a good comparator for strings. We can use localCompare or not provide a default comparator for strings at all.

[aleclarson]

The default comparator is intended to be both minimal and flexible (support comparing any two Comparable values). If only strings are being compared, the caller can opt-in to localeCompare like alphabetical is doing.

I suppose we could include a warning about this behavior in the function's description.

[Minhir]

It's possible to use undefined as an object key. Yes, such code is very weird, but it's still possible. So returning identity function here could be a surprising behavior.

[aleclarson]

Sure, we could document this behavior.

Property names are assumed to be strings, numbers, or symbols.