feat: add entityField SQL helper

[wschurman]

Why

Asked claude to do an API usability review and it noted that forcing the user to context-switch between entity fields and database fields for SQLFragments was an unfortunate pattern.

How

This PR provides a SQLFragment helper, entityField<TFields>('fieldName') which does the conversion for the user so they don't need to look up the underlying database field.

Secondarily, this provides type safety to ensure SQLFragments for one entity aren't used for SQLFragments of another entity (unless types overlap via shared config).

Test Plan

Add feature and tests and examples.

[wschurman]

• feat: add entityField SQL helper #481 : 2 dependent PRs (#482 , #485 ) 👈 (View in Graphite)
• chore: raw -> unsafeRaw #480
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (beda973) to head (79dad31).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main      #481    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          110       110            
  Lines        16228     16365   +137     
  Branches      1464      1472     +8     
==========================================
+ Hits         16228     16365   +137     

Flag	Coverage Δ
integration	24.63% <71.95%> (+0.32%)	⬆️
unittest	94.85% <86.71%> (-0.04%)	⬇️

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

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ide]

Discussion: I think it's good to have type checking and assistance so the programmer provides the right parameters - in this case, database column names.

However, I don't like that entityField causes the programmer to mix two different abstraction layers in the same call. They are working at the SQL abstraction layer when using these Knex loader methods, and my gut feeling is it's unexpected to see field names from the Entity abstraction layer interpolated with the SQL layer.

Again, open to discussion, maybe I am overthinking things, maybe ORMs do it this way.

[wschurman]

It's a good observation. When using SQLFragments for where or orderBy, one is already using a mixture of the two at the loader callsite:

await PostgresTestEntity.knexLoader(vc1)
  .loadManyBySQL(sql`${entityField('bigintField')} LIKE ${'OrderTest%'}`) // nice to have the ability to see that these fields are the same
  .orderBy('bigintField', OrderByOrdering.ASCENDING) // this is an entity field
  .limit(2)
  .offset(1)
  .executeAsync();

versus

await PostgresTestEntity.knexLoader(vc1)
  .loadManyBySQL(sql`${identifier('bigint_field')} LIKE ${'OrderTest%'}`) // this is valid too, but now it is different than the order by
  .orderBy('bigintField', OrderByOrdering.ASCENDING)
  .limit(2)
  .offset(1)
  .executeAsync();

The nice thing about the new helper is that it's totally optional, so consumers can use it if they prefer the first version but don't need to.

[wschurman]

Merge activity

• Feb 27, 11:40 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Feb 27, 11:41 PM UTC: Graphite rebased this pull request as part of a merge.
• Feb 27, 11:44 PM UTC: @wschurman merged this pull request with Graphite.