fix(NODE-7643): preserve $meta direction in [field, direction] sort pair

[spokodev]

Description

Sorting by $meta is rejected in the [field, direction] pair form of sort. The type-legal input

cursor.sort(['score', { $meta: 'textScore' }])

throws:

MongoInvalidArgumentError: Invalid sort direction: [{"$meta":"textScore"}]

The equivalent object form { score: { $meta: 'textScore' } } and the deep form [['score', { $meta: 'textScore' }]] both work, so the three shapes the API accepts behave inconsistently.

Root cause

In src/sort.ts, pairToMap calls prepareDirection([v[1]]), wrapping the direction in an array, unlike every sibling converter which passes the raw value. A scalar direction coincidentally survives the array to string coercion ([-1] -> "-1"), but a $meta object does not (isMeta returns false for an array), so it is rejected.

This is a regression from #2788 (NODE-3174), which replaced pairToObject with pairToMap and wrapped the direction in an array. With src/sort.ts from just before #2788, the pair form returns { score: { $meta: 'textScore' } }.

Fix

-  return new Map([[`${v[0]}`, prepareDirection([v[1]])]]);
+  return new Map([[`${v[0]}`, prepareDirection(v[1])]]);

Test

Added test/unit/sort.test.ts (no test/unit file covered formatSort before). The $meta pair case fails unpatched with the error above and passes after; the scalar-direction pair cases pass throughout, showing the fix is scoped. Full test/unit suite stays green.

Also added an integration test in test/integration/crud/find.test.ts: a text index on title, a $text search with the score projected, sorted with ['score', { $meta: 'textScore' }]. It fails unpatched with the same error and passes after.

Release Highlight

Sorting by $meta with a [field, direction] pair now works

Previously, passing a $meta sort direction in the [field, direction] form, for example cursor.sort(['score', { $meta: 'textScore' }]), threw MongoInvalidArgumentError: Invalid sort direction. The object form ({ score: { $meta: 'textScore' } }) and the nested array form ([['score', { $meta: 'textScore' }]]) already worked, so the same sort was accepted or rejected depending on how it was written. All three forms now behave the same.

Thanks to @spokodev for the fix!

Double check the following

• Lint is passing (npm run check:lint)
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[johnmtll]

Thank you for taking the time to fill out this detailed PR! This PR will be tracked by NODE-7643 and will be prioritized in the next triage session.

[spokodev]

@johnmtll, thank you for landing #4989 on 2 October. This one is now rebased onto main (it was 50 commits behind) and its unit tests pass, 3 of 3. With the src/sort.ts change reverted, the $meta case fails.

The bug is one line in pairToMap: it wraps the direction in an array before calling prepareDirection, so isMeta never sees the { $meta: 'textScore' } object and formatSort(['score', { $meta: 'textScore' }]) throws Invalid sort direction.

Should I add integration coverage here too, as on #4989? Evergreen will need authorizing on the new head.

[tadjik1]

Hi @spokodev, thanks a lot for the PR! Yes, can you please add integration tests for the fix?
You would need to create a text index, insert few documents with different content relevant to specific queries (I usually use movie names, but it's up to you). And then query by $text with score projection and sorting.

[spokodev]

Thanks, @tadjik1. Added an integration test in abf28d6, next to the existing text search sort test in test/integration/crud/find.test.ts. It creates a text index on title, inserts five documents, runs a $text search for godfather harlem with the score projected, sorts with ['score', { $meta: 'textScore' }], and checks the order of the four matches.

Their scores are 1.5, 1, 0.75 and 2/3, so the expected order has no ties. On the old src/sort.ts the test fails with Invalid sort direction: [{"$meta":"textScore"}].

I ran it against a local standalone mongod 8.0.32: all of find.test.ts passes, with 45 passing and 2 pending.

I also corrected the PR description. The array wrapping came from #2788, not from #2573: with src/sort.ts from just before #2788, formatSort(['score', { $meta: 'textScore' }]) returns { score: { $meta: 'textScore' } }, and from #2788 on it throws.

[tadjik1]

Great one, thanks @spokodev! 👍