@expo/entity-database-adapter-knex 0.54.0 → 0.57.0

package/src/internal/__tests__/EntityKnexDataManager-test.ts

@@ -0,0 +1,378 @@
+import {
+  EntityMetricsLoadType,
+  EntityQueryContext,
+  IEntityMetricsAdapter,
+  NoOpEntityMetricsAdapter,
+} from '@expo/entity';
+import { StubQueryContextProvider } from '@expo/entity-testing-utils';
+import { describe, expect, it } from '@jest/globals';
+import {
+  anyNumber,
+  anyString,
+  anything,
+  deepEqual,
+  instance,
+  mock,
+  resetCalls,
+  verify,
+  when,
+} from 'ts-mockito';
+
+import { OrderByOrdering } from '../../BasePostgresEntityDatabaseAdapter';
+import { PaginationStrategy } from '../../PaginationStrategy';
+import { PostgresEntityDatabaseAdapter } from '../../PostgresEntityDatabaseAdapter';
+import {
+  TestEntity,
+  TestFields,
+  testEntityConfiguration,
+} from '../../__tests__/fixtures/TestEntity';
+import { EntityKnexDataManager } from '../EntityKnexDataManager';
+
+describe(EntityKnexDataManager, () => {
+  it('loads by field equality conjunction and does not cache', async () => {
+    const queryContext = instance(mock<EntityQueryContext>());
+    const databaseAdapterMock = mock<PostgresEntityDatabaseAdapter<TestFields, 'customIdField'>>(
+      PostgresEntityDatabaseAdapter,
+    );
+    when(
+      databaseAdapterMock.fetchManyByFieldEqualityConjunctionAsync(
+        queryContext,
+        anything(),
+        anything(),
+      ),
+    ).thenResolve([
+      {
+        customIdField: '1',
+        testIndexedField: 'unique1',
+        stringField: 'hello',
+        intField: 1,
+        dateField: new Date(),
+        nullableField: null,
+      },
+      {
+        customIdField: '2',
+        testIndexedField: 'unique2',
+        stringField: 'hello',
+        intField: 1,
+        dateField: new Date(),
+        nullableField: null,
+      },
+    ]);
+    const entityDataManager = new EntityKnexDataManager(
+      testEntityConfiguration,
+      instance(databaseAdapterMock),
+      new NoOpEntityMetricsAdapter(),
+      TestEntity.name,
+    );
+
+    const entityDatas = await entityDataManager.loadManyByFieldEqualityConjunctionAsync(
+      queryContext,
+      [
+        {
+          fieldName: 'stringField',
+          fieldValue: 'hello',
+        },
+        {
+          fieldName: 'intField',
+          fieldValue: 1,
+        },
+      ],
+      {},
+    );
+
+    expect(entityDatas).toHaveLength(2);
+
+    verify(
+      databaseAdapterMock.fetchManyByFieldEqualityConjunctionAsync(
+        queryContext,
+        anything(),
+        anything(),
+      ),
+    ).once();
+  });
+
+  describe('metrics', () => {
+    it('records metrics appropriately outside of transactions', async () => {
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
+      const queryContext = new StubQueryContextProvider().getQueryContext();
+
+      const databaseAdapterMock = mock<PostgresEntityDatabaseAdapter<TestFields, 'customIdField'>>(
+        PostgresEntityDatabaseAdapter,
+      );
+
+      when(
+        databaseAdapterMock.fetchManyByFieldEqualityConjunctionAsync(
+          anything(),
+          anything(),
+          anything(),
+        ),
+      ).thenResolve([
+        {
+          customIdField: '1',
+          testIndexedField: 'unique1',
+          stringField: 'hello',
+          intField: 1,
+          dateField: new Date(),
+          nullableField: null,
+        },
+      ]);
+      when(
+        databaseAdapterMock.fetchManyByRawWhereClauseAsync(
+          anything(),
+          anyString(),
+          anything(),
+          anything(),
+        ),
+      ).thenResolve([]);
+
+      const entityDataManager = new EntityKnexDataManager(
+        testEntityConfiguration,
+        instance(databaseAdapterMock),
+        metricsAdapter,
+        TestEntity.name,
+      );
+
+      await entityDataManager.loadManyByFieldEqualityConjunctionAsync(
+        queryContext,
+        [
+          {
+            fieldName: 'testIndexedField',
+            fieldValue: 'unique1',
+          },
+        ],
+        {},
+      );
+      verify(
+        metricsAdapterMock.logDataManagerLoadEvent(
+          deepEqual({
+            type: EntityMetricsLoadType.LOAD_MANY_EQUALITY_CONJUNCTION,
+            isInTransaction: false,
+            entityClassName: TestEntity.name,
+            duration: anyNumber(),
+            count: 1,
+          }),
+        ),
+      ).once();
+
+      resetCalls(metricsAdapterMock);
+
+      await entityDataManager.loadManyByRawWhereClauseAsync(queryContext, '', [], {});
+      verify(
+        metricsAdapterMock.logDataManagerLoadEvent(
+          deepEqual({
+            type: EntityMetricsLoadType.LOAD_MANY_RAW,
+            isInTransaction: false,
+            entityClassName: TestEntity.name,
+            duration: anyNumber(),
+            count: 0,
+          }),
+        ),
+      ).once();
+
+      verify(metricsAdapterMock.incrementDataManagerLoadCount(anything())).never();
+    });
+
+    it('records metrics appropriately inside of transactions', async () => {
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
+
+      const databaseAdapterMock = mock<PostgresEntityDatabaseAdapter<TestFields, 'customIdField'>>(
+        PostgresEntityDatabaseAdapter,
+      );
+
+      when(
+        databaseAdapterMock.fetchManyByFieldEqualityConjunctionAsync(
+          anything(),
+          anything(),
+          anything(),
+        ),
+      ).thenResolve([
+        {
+          customIdField: '1',
+          testIndexedField: 'unique1',
+          stringField: 'hello',
+          intField: 1,
+          dateField: new Date(),
+          nullableField: null,
+        },
+      ]);
+      when(
+        databaseAdapterMock.fetchManyByRawWhereClauseAsync(
+          anything(),
+          anyString(),
+          anything(),
+          anything(),
+        ),
+      ).thenResolve([]);
+
+      const entityDataManager = new EntityKnexDataManager(
+        testEntityConfiguration,
+        instance(databaseAdapterMock),
+        metricsAdapter,
+        TestEntity.name,
+      );
+
+      await new StubQueryContextProvider().runInTransactionAsync(async (queryContext) => {
+        await entityDataManager.loadManyByFieldEqualityConjunctionAsync(
+          queryContext,
+          [
+            {
+              fieldName: 'testIndexedField',
+              fieldValue: 'unique1',
+            },
+          ],
+          {},
+        );
+        verify(
+          metricsAdapterMock.logDataManagerLoadEvent(
+            deepEqual({
+              type: EntityMetricsLoadType.LOAD_MANY_EQUALITY_CONJUNCTION,
+              isInTransaction: true,
+              entityClassName: TestEntity.name,
+              duration: anyNumber(),
+              count: 1,
+            }),
+          ),
+        ).once();
+
+        resetCalls(metricsAdapterMock);
+
+        await entityDataManager.loadManyByRawWhereClauseAsync(queryContext, '', [], {});
+        verify(
+          metricsAdapterMock.logDataManagerLoadEvent(
+            deepEqual({
+              type: EntityMetricsLoadType.LOAD_MANY_RAW,
+              isInTransaction: true,
+              entityClassName: TestEntity.name,
+              duration: anyNumber(),
+              count: 0,
+            }),
+          ),
+        ).once();
+
+        verify(metricsAdapterMock.incrementDataManagerLoadCount(anything())).never();
+      });
+    });
+  });
+
+  describe('pagination', () => {
+    describe('max page size validation', () => {
+      it('should throw when first exceeds maxPageSize', async () => {
+        const queryContext = instance(mock<EntityQueryContext>());
+        const databaseAdapterMock = mock<
+          PostgresEntityDatabaseAdapter<TestFields, 'customIdField'>
+        >(PostgresEntityDatabaseAdapter);
+
+        // Configure the adapter to return a maxPageSize of 100
+        when(databaseAdapterMock.paginationMaxPageSize).thenReturn(100);
+
+        const entityDataManager = new EntityKnexDataManager(
+          testEntityConfiguration,
+          instance(databaseAdapterMock),
+          new NoOpEntityMetricsAdapter(),
+          TestEntity.name,
+        );
+
+        await expect(
+          entityDataManager.loadPageAsync(queryContext, {
+            first: 101,
+            pagination: {
+              strategy: PaginationStrategy.STANDARD,
+              orderBy: [{ fieldName: 'customIdField', order: OrderByOrdering.ASCENDING }],
+            },
+          }),
+        ).rejects.toThrow('first must not exceed maximum page size of 100');
+      });
+
+      it('should throw when last exceeds maxPageSize', async () => {
+        const queryContext = instance(mock<EntityQueryContext>());
+        const databaseAdapterMock = mock<
+          PostgresEntityDatabaseAdapter<TestFields, 'customIdField'>
+        >(PostgresEntityDatabaseAdapter);
+
+        // Configure the adapter to return a maxPageSize of 100
+        when(databaseAdapterMock.paginationMaxPageSize).thenReturn(100);
+
+        const entityDataManager = new EntityKnexDataManager(
+          testEntityConfiguration,
+          instance(databaseAdapterMock),
+          new NoOpEntityMetricsAdapter(),
+          TestEntity.name,
+        );
+
+        await expect(
+          entityDataManager.loadPageAsync(queryContext, {
+            last: 101,
+            pagination: {
+              strategy: PaginationStrategy.STANDARD,
+              orderBy: [{ fieldName: 'customIdField', order: OrderByOrdering.ASCENDING }],
+            },
+          }),
+        ).rejects.toThrow('last must not exceed maximum page size of 100');
+      });
+
+      it('should allow first/last within maxPageSize', async () => {
+        const queryContext = instance(mock<EntityQueryContext>());
+        const databaseAdapterMock = mock<
+          PostgresEntityDatabaseAdapter<TestFields, 'customIdField'>
+        >(PostgresEntityDatabaseAdapter);
+
+        // Configure the adapter to return a maxPageSize of 100
+        when(databaseAdapterMock.paginationMaxPageSize).thenReturn(100);
+        when(
+          databaseAdapterMock.fetchManyBySQLFragmentAsync(queryContext, anything(), anything()),
+        ).thenResolve([]);
+
+        const entityDataManager = new EntityKnexDataManager(
+          testEntityConfiguration,
+          instance(databaseAdapterMock),
+          new NoOpEntityMetricsAdapter(),
+          TestEntity.name,
+        );
+
+        // This should not throw
+        const result = await entityDataManager.loadPageAsync(queryContext, {
+          first: 100,
+          pagination: {
+            strategy: PaginationStrategy.STANDARD,
+            orderBy: [{ fieldName: 'customIdField', order: OrderByOrdering.ASCENDING }],
+          },
+        });
+
+        expect(result.edges).toEqual([]);
+      });
+
+      it('should allow pagination when maxPageSize is not configured', async () => {
+        const queryContext = instance(mock<EntityQueryContext>());
+        const databaseAdapterMock = mock<
+          PostgresEntityDatabaseAdapter<TestFields, 'customIdField'>
+        >(PostgresEntityDatabaseAdapter);
+
+        // Configure the adapter to return undefined for maxPageSize
+        when(databaseAdapterMock.paginationMaxPageSize).thenReturn(undefined);
+        when(
+          databaseAdapterMock.fetchManyBySQLFragmentAsync(queryContext, anything(), anything()),
+        ).thenResolve([]);
+
+        const entityDataManager = new EntityKnexDataManager(
+          testEntityConfiguration,
+          instance(databaseAdapterMock),
+          new NoOpEntityMetricsAdapter(),
+          TestEntity.name,
+        );
+
+        // This should not throw even with a large page size
+        const result = await entityDataManager.loadPageAsync(queryContext, {
+          first: 10000,
+          pagination: {
+            strategy: PaginationStrategy.STANDARD,
+            orderBy: [{ fieldName: 'customIdField', order: OrderByOrdering.ASCENDING }],
+          },
+        });
+
+        expect(result.edges).toEqual([]);
+      });
+    });
+  });
+});

package/src/internal/__tests__/weakMaps-test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { computeIfAbsentInWeakMap } from '../weakMaps';
+
+describe(computeIfAbsentInWeakMap, () => {
+  it('computes a value when absent', () => {
+    const map = new WeakMap<object, string>();
+    const key = {};
+    const blah = computeIfAbsentInWeakMap(map, key, () => 'world');
+    expect(blah).toEqual(map.get(key));
+  });
+
+  it('does not compute a value when already present', () => {
+    const map = new WeakMap<object, string>();
+    const key = {};
+    map.set(key, 'world');
+    let didCompute = false;
+    const blah = computeIfAbsentInWeakMap(map, key, () => {
+      didCompute = true;
+      return 'world2';
+    });
+    expect(blah).toEqual(map.get(key));
+    expect(didCompute).toBe(false);
+  });
+});

package/src/internal/getKnexDataManager.ts

@@ -0,0 +1,43 @@
+import { EntityDatabaseAdapter, EntityTableDataCoordinator } from '@expo/entity';
+import assert from 'assert';
+
+import { BasePostgresEntityDatabaseAdapter } from '../BasePostgresEntityDatabaseAdapter';
+import { EntityKnexDataManager } from './EntityKnexDataManager';
+import { computeIfAbsentInWeakMap } from './weakMaps';
+
+const knexDataManagerCache = new WeakMap<
+  EntityTableDataCoordinator<any, any>,
+  EntityKnexDataManager<any, any>
+>();
+
+export function getKnexDataManager<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+>(
+  tableDataCoordinator: EntityTableDataCoordinator<TFields, TIDField>,
+): EntityKnexDataManager<TFields, TIDField> {
+  return computeIfAbsentInWeakMap(
+    knexDataManagerCache,
+    tableDataCoordinator,
+    (coordinator) =>
+      new EntityKnexDataManager(
+        coordinator.entityConfiguration,
+        requireBasePostgresAdapter(coordinator.databaseAdapter),
+        coordinator.metricsAdapter,
+        coordinator.entityClassName,
+      ),
+  );
+}
+
+function requireBasePostgresAdapter<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+>(
+  databaseAdapter: EntityDatabaseAdapter<TFields, TIDField>,
+): BasePostgresEntityDatabaseAdapter<TFields, TIDField> {
+  assert(
+    databaseAdapter instanceof BasePostgresEntityDatabaseAdapter,
+    `Cannot create KnexDataManager for EntityTableDataCoordinator with non-Postgres database adapter.`,
+  );
+  return databaseAdapter;
+}

package/src/internal/getKnexEntityLoaderFactory.ts

@@ -0,0 +1,60 @@
+import {
+  EntityCompanion,
+  EntityPrivacyPolicy,
+  IEntityClass,
+  ReadonlyEntity,
+  ViewerContext,
+} from '@expo/entity';
+
+import { KnexEntityLoaderFactory } from '../KnexEntityLoaderFactory';
+import { getKnexDataManager } from './getKnexDataManager';
+import { computeIfAbsentInWeakMap } from './weakMaps';
+
+const knexEntityLoaderFactoryCache = new WeakMap<
+  EntityCompanion<any, any, any, any, any, any>,
+  KnexEntityLoaderFactory<any, any, any, any, any, any>
+>();
+
+export function getKnexEntityLoaderFactory<
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
+  TViewerContext extends ViewerContext,
+  TViewerContext2 extends TViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields = keyof TFields,
+>(
+  entityClass: IEntityClass<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  >,
+  viewerContext: TViewerContext2,
+): KnexEntityLoaderFactory<
+  TFields,
+  TIDField,
+  TViewerContext,
+  TEntity,
+  TPrivacyPolicy,
+  TSelectedFields
+> {
+  return computeIfAbsentInWeakMap(
+    knexEntityLoaderFactoryCache,
+    viewerContext.entityCompanionProvider.getCompanionForEntity(entityClass),
+    (companion) =>
+      new KnexEntityLoaderFactory(
+        companion,
+        getKnexDataManager(companion.tableDataCoordinator),
+        companion.metricsAdapter,
+      ),
+  );
+}

package/src/internal/utilityTypes.ts

@@ -0,0 +1,11 @@
+/* c8 ignore start - types only */
+
+export type NonNullableKeys<T> = {
+  [K in keyof T]: T[K] extends NonNullable<T[K]> ? K : never;
+}[keyof T];
+
+export type PickNonNullable<T> = Pick<T, NonNullableKeys<T>>;
+
+export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
+
+/* c8 ignore stop - types only */

package/src/internal/weakMaps.ts

@@ -0,0 +1,19 @@
+/**
+ * If the specified key is not already associated with a value in this weak map, computes
+ * its value using the given mapping function and enters it into this map.
+ *
+ * @param map - map from which to get the key's value or compute and associate
+ * @param key - key for which to get the value or with which the computed value is to be associated
+ * @param mappingFunction - function to compute a value for key
+ */
+export const computeIfAbsentInWeakMap = <K extends WeakKey, V>(
+  map: WeakMap<K, V>,
+  key: K,
+  mappingFunction: (key: K) => V,
+): V => {
+  if (!map.has(key)) {
+    const value = mappingFunction(key);
+    map.set(key, value);
+  }
+  return map.get(key)!;
+};

package/src/knexLoader.ts

@@ -0,0 +1,110 @@
+import {
+  EntityPrivacyPolicy,
+  EntityQueryContext,
+  IEntityClass,
+  ReadonlyEntity,
+  ViewerContext,
+} from '@expo/entity';
+
+import { AuthorizationResultBasedKnexEntityLoader } from './AuthorizationResultBasedKnexEntityLoader';
+import { EnforcingKnexEntityLoader } from './EnforcingKnexEntityLoader';
+import { getKnexEntityLoaderFactory } from './internal/getKnexEntityLoaderFactory';
+
+/**
+ * Vend knex loader for loading entities via non-data-loader methods in a given query context.
+ * @param entityClass - entity class to load
+ * @param viewerContext - viewer context of loading user
+ * @param queryContext - query context in which to perform the load
+ */
+export function knexLoader<
+  TMFields extends object,
+  TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
+  TMViewerContext extends ViewerContext,
+  TMViewerContext2 extends TMViewerContext,
+  TMEntity extends ReadonlyEntity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
+  TMPrivacyPolicy extends EntityPrivacyPolicy<
+    TMFields,
+    TMIDField,
+    TMViewerContext,
+    TMEntity,
+    TMSelectedFields
+  >,
+  TMSelectedFields extends keyof TMFields = keyof TMFields,
+>(
+  entityClass: IEntityClass<
+    TMFields,
+    TMIDField,
+    TMViewerContext,
+    TMEntity,
+    TMPrivacyPolicy,
+    TMSelectedFields
+  >,
+  viewerContext: TMViewerContext2,
+  queryContext: EntityQueryContext = viewerContext
+    .getViewerScopedEntityCompanionForClass(entityClass)
+    .getQueryContextProvider()
+    .getQueryContext(),
+): EnforcingKnexEntityLoader<
+  TMFields,
+  TMIDField,
+  TMViewerContext,
+  TMEntity,
+  TMPrivacyPolicy,
+  TMSelectedFields
+> {
+  return getKnexEntityLoaderFactory(entityClass, viewerContext).forLoadEnforcing(
+    viewerContext,
+    queryContext,
+    { previousValue: null, cascadingDeleteCause: null },
+  );
+}
+
+/**
+ * Vend knex loader for loading entities via non-data-loader methods in a given query context.
+ * Returns authorization results instead of throwing on authorization errors.
+ * @param entityClass - entity class to load
+ * @param viewerContext - viewer context of loading user
+ * @param queryContext - query context in which to perform the load
+ */
+export function knexLoaderWithAuthorizationResults<
+  TMFields extends object,
+  TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
+  TMViewerContext extends ViewerContext,
+  TMViewerContext2 extends TMViewerContext,
+  TMEntity extends ReadonlyEntity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
+  TMPrivacyPolicy extends EntityPrivacyPolicy<
+    TMFields,
+    TMIDField,
+    TMViewerContext,
+    TMEntity,
+    TMSelectedFields
+  >,
+  TMSelectedFields extends keyof TMFields = keyof TMFields,
+>(
+  entityClass: IEntityClass<
+    TMFields,
+    TMIDField,
+    TMViewerContext,
+    TMEntity,
+    TMPrivacyPolicy,
+    TMSelectedFields
+  >,
+  viewerContext: TMViewerContext2,
+  queryContext: EntityQueryContext = viewerContext
+    .getViewerScopedEntityCompanionForClass(entityClass)
+    .getQueryContextProvider()
+    .getQueryContext(),
+): AuthorizationResultBasedKnexEntityLoader<
+  TMFields,
+  TMIDField,
+  TMViewerContext,
+  TMEntity,
+  TMPrivacyPolicy,
+  TMSelectedFields
+> {
+  return getKnexEntityLoaderFactory(entityClass, viewerContext).forLoad(
+    viewerContext,
+    queryContext,
+    { previousValue: null, cascadingDeleteCause: null },
+  );
+}