feat: add orderByRaw to loadManyByRawWhereClauseAsync

[FiberJW]

Why

To achieve the sort I want for Expo apps (ORDER BY GREATEST(display_name, SPLIT_PART(full_name, '/', 2)) ASC), Entity needs a raw order clause option.

How

I added an orderByRaw property to the querySelectionModifiers for loadManyByRawWhereClauseAsync and updated all of the downstream types and call sites accordingly.

Test Plan

The added integration test and Typescript checks should pass.

[linear]

ENG-5915 Add `orderByRaw` option to Entity query selection modifiers

[codecov]

Codecov Report

Merging #185 (d5bd112) into main (af81981) will increase coverage by 0.01%.
The diff coverage is 92.85%.

@@            Coverage Diff             @@
##             main     #185      +/-   ##
==========================================
+ Coverage   96.27%   96.29%   +0.01%     
==========================================
  Files          80       80              
  Lines        2015     2023       +8     
  Branches      244      245       +1     
==========================================
+ Hits         1940     1948       +8     
  Misses         75       75              

Flag	Coverage Δ
integration	96.29% <92.85%> (+0.01%)	⬆️
unittest	96.29% <92.85%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
packages/entity/src/EntityLoader.ts	89.36% <0.00%> (ø)
...-adapter-knex/src/PostgresEntityDatabaseAdapter.ts	100.00% <100.00%> (ø)
packages/entity/src/EnforcingEntityLoader.ts	100.00% <100.00%> (ø)
packages/entity/src/EntityDatabaseAdapter.ts	100.00% <100.00%> (ø)
packages/entity/src/internal/EntityDataManager.ts	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[wschurman]

Looks good! Just a few things to add:

• In StubDatabaseAdapter, we should throw an exception in fetchManyByFieldEqualityConjunctionInternalAsync if orderByRaw is specified. Same change should be applied to InMemoryDatabaseAdapter.

One larger question: Do you think this makes more sense to limit this arg to loadManyByRawWhereClauseAsync? Having it present in loadManyByFieldEqualityConjunctionAsync creates a situation where we can't simulate a query in memory (see note above about adding the throws) where up until now we could. My gut says that so far we've used loadManyByRawWhereClauseAsync as the escape hatch for needing to do special SQL things in the database adapters, so it might make more sense for this to just be available in that method (especially because we can't simulate it in the in-memory database adapters mentioned above). That being said, I think your particular use case used loadManyByFieldEqualityConjunctionAsync so maybe not?

[FiberJW]

I think it makes sense to limit this arg to loadManyByRawWhereClauseAsync.

Which of the following do you think is the better approach:

• error out in loadManyByFieldEqualityConjunctionAsync when orderByRaw is provided in querySelectionModifiers
• add a new orderByRaw param to loadManyByRawWhereClauseAsync after querySelectionModifiers
• extend the querySelectionModifiers type like this PR does, but only in the loadManyByRawWhereClauseAsync codepath (QuerySelectionModifiers<TFields> & { orderByRaw?: string })

[wschurman]

• extend the querySelectionModifiers type like this PR does, but only in the loadManyByRawWhereClauseAsync codepath (QuerySelectionModifiers<TFields> & { orderByRaw?: string })

I like this option.

[wschurman]

Looks a lot better. Probably worth create a new set of types that extends the query modifiers type that includes the new param. This way the internal and external types of the library match and are named. I tried it in 3d2d189 (commit on top of yours) to be sure and it seemed to work (feel free to use all or none of that commit).

[wschurman]

(don't worry about diff target codecov percentage)

[wschurman]

Ping me when you land this and I'll create a new release of these and upgrade them in www.