feat!: Move knex-specific loader methods to knexLoader (#407)

# Why

This is a long stack, but the goal is to make a place to put postgres-specific loading logic to avoid polluting the core dataloader-based library with logic specific to knex/postgres. And potentially even postgres-specific mutation logic but that's way down the road.

The best place for this stuff is in the `entity-database-adapter-knex` library. Therefore, the strategy is (in PR order):
1. Move existing knex/postgres-specific loader methods to a new loader, `knexLoader`. I'm also open to calling this a "Postgres Loader" since the `entity-database-adapter-knex` package already uses postgres-specific queries (and more are added here since this stack eventually produces raw queries) within knex even though technically knex is database agnostic.
1. Move knex-specific logic out of EntityDataManager, move it to its own EntityKnexDataManager.
1. Move these two now-separated pieces into the `entity-database-adapter-knex` package. This requires creating a "plugin" system for database adapters, where when they are included their methods are added to the prototype so that seamless loading continues to work.
1. Add a codemod for these three pieces.
1. Add the first new feature to entity loading, load by tagged template string, which creates a better/safer way to express raw queries for loading entities.

Future other things that could be added here (after thorough thought on authorization) are:
- Pagination
- Create, update, delete by tagged template string
- Batch creation
- Upsert (maybe)

# For Reviewers

The most critical things to assess are:
- "install" method in #410
- sql tagged template API usability in #414

# How

This is part 1. It refactors the loaders by moving `loadManyByFieldEqualityConjunctionAsync`, `loadFirstByFieldEqualityConjunctionAsync`, and `loadManyByRawWhereClauseAsync` to a separate loader.

The new pattern for these is:
```
await PostgresTestEntity.knexLoader(vc1).loadManyByRawWhereClauseAsync(...)
```

# Test Plan

This has full coverage in new tests.

Author: wschurman

packages/entity-database-adapter-knex/src/__integration-tests__/PostgresEntityIntegration-test.ts

@@ -390,7 +390,9 @@ describe('postgres entity integration', () => {
           .createAsync(),
       );
 
-      const results = await PostgresTestEntity.loader(vc1).loadManyByFieldEqualityConjunctionAsync([
+      const results = await PostgresTestEntity.knexLoader(
+        vc1,
+      ).loadManyByFieldEqualityConjunctionAsync([
         {
           fieldName: 'hasACat',
           fieldValue: false,
@@ -403,9 +405,11 @@ describe('postgres entity integration', () => {
 
       expect(results).toHaveLength(2);
 
-      const results2 = await PostgresTestEntity.loader(vc1).loadManyByFieldEqualityConjunctionAsync(
-        [{ fieldName: 'hasADog', fieldValues: [true, false] }],
-      );
+      const results2 = await PostgresTestEntity.knexLoader(
+        vc1,
+      ).loadManyByFieldEqualityConjunctionAsync([
+        { fieldName: 'hasADog', fieldValues: [true, false] },
+      ]);
       expect(results2).toHaveLength(3);
     });
 
@@ -424,19 +428,18 @@ describe('postgres entity integration', () => {
         PostgresTestEntity.creatorWithAuthorizationResults(vc1).setField('name', 'c').createAsync(),
       );
 
-      const results = await PostgresTestEntity.loader(vc1).loadManyByFieldEqualityConjunctionAsync(
-        [],
-        {
-          limit: 2,
-          offset: 1,
-          orderBy: [
-            {
-              fieldName: 'name',
-              order: OrderByOrdering.DESCENDING,
-            },
-          ],
-        },
-      );
+      const results = await PostgresTestEntity.knexLoader(
+        vc1,
+      ).loadManyByFieldEqualityConjunctionAsync([], {
+        limit: 2,
+        offset: 1,
+        orderBy: [
+          {
+            fieldName: 'name',
+            order: OrderByOrdering.DESCENDING,
+          },
+        ],
+      });
       expect(results).toHaveLength(2);
       expect(results.map((e) => e.getField('name'))).toEqual(['b', 'a']);
     });
@@ -468,13 +471,15 @@ describe('postgres entity integration', () => {
           .createAsync(),
       );
 
-      const results = await PostgresTestEntity.loader(vc1).loadManyByFieldEqualityConjunctionAsync([
-        { fieldName: 'name', fieldValue: null },
-      ]);
+      const results = await PostgresTestEntity.knexLoader(
+        vc1,
+      ).loadManyByFieldEqualityConjunctionAsync([{ fieldName: 'name', fieldValue: null }]);
       expect(results).toHaveLength(2);
       expect(results[0]!.getField('name')).toBeNull();
 
-      const results2 = await PostgresTestEntity.loader(vc1).loadManyByFieldEqualityConjunctionAsync(
+      const results2 = await PostgresTestEntity.knexLoader(
+        vc1,
+      ).loadManyByFieldEqualityConjunctionAsync(
         [
           { fieldName: 'name', fieldValues: ['a', null] },
           { fieldName: 'hasADog', fieldValue: true },
@@ -504,7 +509,7 @@ describe('postgres entity integration', () => {
           .createAsync(),
       );
 
-      const results = await PostgresTestEntity.loader(vc1).loadManyByRawWhereClauseAsync(
+      const results = await PostgresTestEntity.knexLoader(vc1).loadManyByRawWhereClauseAsync(
         'name = ?',
         ['hello'],
       );
@@ -523,7 +528,7 @@ describe('postgres entity integration', () => {
       );
 
       await expect(
-        PostgresTestEntity.loader(vc1).loadManyByRawWhereClauseAsync('invalid_column = ?', [
+        PostgresTestEntity.knexLoader(vc1).loadManyByRawWhereClauseAsync('invalid_column = ?', [
           'hello',
         ]),
       ).rejects.toThrow();
@@ -553,7 +558,7 @@ describe('postgres entity integration', () => {
           .createAsync(),
       );
 
-      const results = await PostgresTestEntity.loader(vc1).loadManyByRawWhereClauseAsync(
+      const results = await PostgresTestEntity.knexLoader(vc1).loadManyByRawWhereClauseAsync(
         'has_a_dog = ?',
         [true],
         {
@@ -571,7 +576,7 @@ describe('postgres entity integration', () => {
       expect(results).toHaveLength(2);
       expect(results.map((e) => e.getField('name'))).toEqual(['b', 'c']);
 
-      const resultsMultipleOrderBy = await PostgresTestEntity.loader(
+      const resultsMultipleOrderBy = await PostgresTestEntity.knexLoader(
         vc1,
       ).loadManyByRawWhereClauseAsync('has_a_dog = ?', [true], {
         orderBy: [
@@ -589,13 +594,11 @@ describe('postgres entity integration', () => {
       expect(resultsMultipleOrderBy).toHaveLength(3);
       expect(resultsMultipleOrderBy.map((e) => e.getField('name'))).toEqual(['c', 'b', 'a']);
 
-      const resultsOrderByRaw = await PostgresTestEntity.loader(vc1).loadManyByRawWhereClauseAsync(
-        'has_a_dog = ?',
-        [true],
-        {
-          orderByRaw: 'has_a_dog ASC, name DESC',
-        },
-      );
+      const resultsOrderByRaw = await PostgresTestEntity.knexLoader(
+        vc1,
+      ).loadManyByRawWhereClauseAsync('has_a_dog = ?', [true], {
+        orderByRaw: 'has_a_dog ASC, name DESC',
+      });
 
       expect(resultsOrderByRaw).toHaveLength(3);
       expect(resultsOrderByRaw.map((e) => e.getField('name'))).toEqual(['c', 'b', 'a']);

packages/entity-secondary-cache-local-memory/src/__tests__/LocalMemorySecondaryEntityCache-test.ts

@@ -173,7 +173,7 @@ class TestSecondaryLocalMemoryCacheLoader extends EntitySecondaryCacheLoader<
       }
       return nullthrows(
         (
-          await this.entityLoader.loadManyByFieldEqualityConjunctionAsync([
+          await this.knexEntityLoader.loadManyByFieldEqualityConjunctionAsync([
             { fieldName: 'id', fieldValue: loadParams.id },
           ])
         )[0],
@@ -198,6 +198,7 @@ describe(LocalMemorySecondaryEntityCache, () => {
         createTTLCache<LocalMemoryTestEntityFields>(),
       ),
       LocalMemoryTestEntity.loaderWithAuthorizationResults(viewerContext),
+      LocalMemoryTestEntity.knexLoaderWithAuthorizationResults(viewerContext),
     );
 
     const loadParams = { id: createdEntity.getID() };
@@ -234,6 +235,7 @@ describe(LocalMemorySecondaryEntityCache, () => {
         createTTLCache<LocalMemoryTestEntityFields>(),
       ),
       LocalMemoryTestEntity.loaderWithAuthorizationResults(viewerContext),
+      LocalMemoryTestEntity.knexLoaderWithAuthorizationResults(viewerContext),
     );
 
     const loadParams = { id: FAKE_ID };

packages/entity-secondary-cache-redis/src/__integration-tests__/RedisSecondaryEntityCache-integration-test.ts

@@ -45,7 +45,7 @@ class TestSecondaryRedisCacheLoader extends EntitySecondaryCacheLoader<
       }
       return nullthrows(
         (
-          await this.entityLoader.loadManyByFieldEqualityConjunctionAsync([
+          await this.knexEntityLoader.loadManyByFieldEqualityConjunctionAsync([
             { fieldName: 'id', fieldValue: loadParams.id },
           ])
         )[0],
@@ -98,6 +98,7 @@ describe(RedisSecondaryEntityCache, () => {
         (loadParams) => `test-key-${loadParams.id}`,
       ),
       RedisTestEntity.loaderWithAuthorizationResults(viewerContext),
+      RedisTestEntity.knexLoaderWithAuthorizationResults(viewerContext),
     );
 
     const loadParams = { id: createdEntity.getID() };
@@ -137,6 +138,7 @@ describe(RedisSecondaryEntityCache, () => {
         (loadParams) => `test-key-${loadParams.id}`,
       ),
       RedisTestEntity.loaderWithAuthorizationResults(viewerContext),
+      RedisTestEntity.knexLoaderWithAuthorizationResults(viewerContext),
     );
 
     const loadParams = { id: FAKE_ID };

packages/entity/src/AuthorizationResultBasedEntityLoader.ts

@@ -8,18 +8,11 @@ import {
   EntityCompositeFieldValue,
   EntityConfiguration,
 } from './EntityConfiguration';
-import {
-  FieldEqualityCondition,
-  isSingleValueFieldEqualityCondition,
-  QuerySelectionModifiers,
-  QuerySelectionModifiersWithOrderByRaw,
-} from './EntityDatabaseAdapter';
 import { EntityLoaderUtils } from './EntityLoaderUtils';
 import { EntityPrivacyPolicy } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import { ReadonlyEntity } from './ReadonlyEntity';
 import { ViewerContext } from './ViewerContext';
-import { EntityInvalidFieldValueError } from './errors/EntityInvalidFieldValueError';
 import { EntityNotFoundError } from './errors/EntityNotFoundError';
 import { CompositeFieldHolder, CompositeFieldValueHolder } from './internal/CompositeFieldHolder';
 import { CompositeFieldValueMap } from './internal/CompositeFieldValueMap';
@@ -265,87 +258,14 @@ export class AuthorizationResultBasedEntityLoader<
     });
   }
 
-  /**
-   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
-   * @returns the first entity results that matches the query, where result error can be
-   *  UnauthorizedError
-   */
-  async loadFirstByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
-    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
-    querySelectionModifiers: Omit<QuerySelectionModifiers<TFields>, 'limit'> &
-      Required<Pick<QuerySelectionModifiers<TFields>, 'orderBy'>>,
-  ): Promise<Result<TEntity> | null> {
-    const results = await this.loadManyByFieldEqualityConjunctionAsync(fieldEqualityOperands, {
-      ...querySelectionModifiers,
-      limit: 1,
-    });
-    return results[0] ?? null;
-  }
-
-  /**
-   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
-   * @returns array of entity results that match the query, where result error can be UnauthorizedError
-   */
-  async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
-    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
-    querySelectionModifiers: QuerySelectionModifiers<TFields> = {},
-  ): Promise<readonly Result<TEntity>[]> {
-    for (const fieldEqualityOperand of fieldEqualityOperands) {
-      const fieldValues = isSingleValueFieldEqualityCondition(fieldEqualityOperand)
-        ? [fieldEqualityOperand.fieldValue]
-        : fieldEqualityOperand.fieldValues;
-      this.validateFieldAndValues(fieldEqualityOperand.fieldName, fieldValues);
-    }
-
-    const fieldObjects = await this.dataManager.loadManyByFieldEqualityConjunctionAsync(
-      this.queryContext,
-      fieldEqualityOperands,
-      querySelectionModifiers,
-    );
-    return await this.utils.constructAndAuthorizeEntitiesArrayAsync(fieldObjects);
-  }
-
-  /**
-   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
-   * @returns array of entity results that match the query, where result error can be UnauthorizedError
-   * @throws Error when rawWhereClause or bindings are invalid
-   */
-  async loadManyByRawWhereClauseAsync(
-    rawWhereClause: string,
-    bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {},
-  ): Promise<readonly Result<TEntity>[]> {
-    const fieldObjects = await this.dataManager.loadManyByRawWhereClauseAsync(
-      this.queryContext,
-      rawWhereClause,
-      bindings,
-      querySelectionModifiers,
-    );
-    return await this.utils.constructAndAuthorizeEntitiesArrayAsync(fieldObjects);
-  }
-
-  private validateFieldAndValues<N extends keyof Pick<TFields, TSelectedFields>>(
-    fieldName: N,
-    fieldValues: readonly TFields[N][],
-  ): void {
-    const fieldDefinition = this.entityConfiguration.schema.get(fieldName);
-    invariant(fieldDefinition, `must have field definition for field = ${String(fieldName)}`);
-    for (const fieldValue of fieldValues) {
-      const isInputValid = fieldDefinition.validateInputValue(fieldValue);
-      if (!isInputValid) {
-        throw new EntityInvalidFieldValueError(this.entityClass, fieldName, fieldValue);
-      }
-    }
-  }
-
   private validateFieldAndValuesAndConvertToHolders<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[],
   ): {
     loadKey: SingleFieldHolder<TFields, TIDField, N>;
     loadValues: readonly SingleFieldValueHolder<TFields, N>[];
   } {
-    this.validateFieldAndValues(fieldName, fieldValues);
+    this.utils.validateFieldAndValues(fieldName, fieldValues);
 
     return {
       loadKey: new SingleFieldHolder<TFields, TIDField, N>(fieldName),
@@ -388,7 +308,7 @@ export class AuthorizationResultBasedEntityLoader<
       );
       for (const field of compositeField) {
         const fieldValue = compositeFieldValueHolder.compositeFieldValue[field];
-        this.validateFieldAndValues(field, [fieldValue]);
+        this.utils.validateFieldAndValues(field, [fieldValue]);
       }
     }