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

package/src/__tests__/fixtures/StubPostgresDatabaseAdapter.ts

@@ -0,0 +1,302 @@
+import {
+  computeIfAbsent,
+  EntityConfiguration,
+  FieldTransformerMap,
+  getDatabaseFieldForEntityField,
+  IntField,
+  mapMap,
+  StringField,
+  transformFieldsToDatabaseObject,
+} from '@expo/entity';
+import invariant from 'invariant';
+import { v7 as uuidv7 } from 'uuid';
+
+import {
+  BasePostgresEntityDatabaseAdapter,
+  NullsOrdering,
+  OrderByOrdering,
+  TableFieldMultiValueEqualityCondition,
+  TableFieldSingleValueEqualityCondition,
+  TableOrderByClause,
+  TableQuerySelectionModifiers,
+} from '../../BasePostgresEntityDatabaseAdapter';
+import { SQLFragment } from '../../SQLOperator';
+
+export class StubPostgresDatabaseAdapter<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> extends BasePostgresEntityDatabaseAdapter<TFields, TIDField> {
+  constructor(
+    private readonly entityConfiguration2: EntityConfiguration<TFields, TIDField>,
+    private readonly dataStore: Map<string, Readonly<{ [key: string]: any }>[]>,
+  ) {
+    super(entityConfiguration2);
+  }
+
+  public static convertFieldObjectsToDataStore<
+    TFields extends Record<string, any>,
+    TIDField extends keyof TFields,
+  >(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
+    dataStore: Map<string, Readonly<TFields>[]>,
+  ): Map<string, Readonly<{ [key: string]: any }>[]> {
+    return mapMap(dataStore, (objectsForTable) =>
+      objectsForTable.map((objectForTable) =>
+        transformFieldsToDatabaseObject(entityConfiguration, new Map(), objectForTable),
+      ),
+    );
+  }
+
+  public getObjectCollectionForTable(tableName: string): { [key: string]: any }[] {
+    return computeIfAbsent(this.dataStore, tableName, () => []);
+  }
+
+  protected getFieldTransformerMap(): FieldTransformerMap {
+    return new Map();
+  }
+
+  private static uniqBy<T>(a: T[], keyExtractor: (k: T) => string): T[] {
+    const seen = new Set();
+    return a.filter((item) => {
+      const k = keyExtractor(item);
+      if (seen.has(k)) {
+        return false;
+      }
+      seen.add(k);
+      return true;
+    });
+  }
+
+  protected async fetchManyWhereInternalAsync(
+    _queryInterface: any,
+    tableName: string,
+    tableColumns: readonly string[],
+    tableTuples: (readonly any[])[],
+  ): Promise<object[]> {
+    const objectCollection = this.getObjectCollectionForTable(tableName);
+    const results = StubPostgresDatabaseAdapter.uniqBy(tableTuples, (tuple) =>
+      tuple.join(':'),
+    ).reduce(
+      (acc, tableTuple) => {
+        return acc.concat(
+          objectCollection.filter((obj) => {
+            return tableColumns.every((tableColumn, index) => {
+              return obj[tableColumn] === tableTuple[index];
+            });
+          }),
+        );
+      },
+      [] as { [key: string]: any }[],
+    );
+    return [...results];
+  }
+
+  protected async fetchOneWhereInternalAsync(
+    queryInterface: any,
+    tableName: string,
+    tableColumns: readonly string[],
+    tableTuple: readonly any[],
+  ): Promise<object | null> {
+    const results = await this.fetchManyWhereInternalAsync(
+      queryInterface,
+      tableName,
+      tableColumns,
+      [tableTuple],
+    );
+    return results[0] ?? null;
+  }
+
+  private static compareByOrderBys<TFields extends Record<string, any>>(
+    orderBys: TableOrderByClause<TFields>[],
+    objectA: { [key: string]: any },
+    objectB: { [key: string]: any },
+  ): 0 | 1 | -1 {
+    if (orderBys.length === 0) {
+      return 0;
+    }
+
+    const currentOrderBy = orderBys[0]!;
+    if (!('columnName' in currentOrderBy)) {
+      throw new Error('SQL fragment order by not supported for StubDatabaseAdapter');
+    }
+    const aField = objectA[currentOrderBy.columnName];
+    const bField = objectB[currentOrderBy.columnName];
+
+    // Determine effective nulls ordering:
+    // - If explicitly set, use that
+    // - Otherwise use PostgreSQL defaults: NULLS LAST for ASC, NULLS FIRST for DESC
+    const nullsFirst =
+      currentOrderBy.nulls !== undefined
+        ? currentOrderBy.nulls === NullsOrdering.FIRST
+        : currentOrderBy.order === OrderByOrdering.DESCENDING;
+
+    if (aField === null && bField === null) {
+      return this.compareByOrderBys(orderBys.slice(1), objectA, objectB);
+    } else if (aField === null) {
+      return nullsFirst ? -1 : 1;
+    } else if (bField === null) {
+      return nullsFirst ? 1 : -1;
+    }
+
+    switch (currentOrderBy.order) {
+      case OrderByOrdering.DESCENDING: {
+        return aField > bField
+          ? -1
+          : aField < bField
+            ? 1
+            : this.compareByOrderBys(orderBys.slice(1), objectA, objectB);
+      }
+      case OrderByOrdering.ASCENDING: {
+        return bField > aField
+          ? -1
+          : bField < aField
+            ? 1
+            : this.compareByOrderBys(orderBys.slice(1), objectA, objectB);
+      }
+    }
+  }
+
+  protected async fetchManyByFieldEqualityConjunctionInternalAsync(
+    _queryInterface: any,
+    tableName: string,
+    tableFieldSingleValueEqualityOperands: TableFieldSingleValueEqualityCondition[],
+    tableFieldMultiValueEqualityOperands: TableFieldMultiValueEqualityCondition[],
+    querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
+  ): Promise<object[]> {
+    let filteredObjects = this.getObjectCollectionForTable(tableName);
+    for (const { tableField, tableValue } of tableFieldSingleValueEqualityOperands) {
+      filteredObjects = filteredObjects.filter((obj) => obj[tableField] === tableValue);
+    }
+
+    for (const { tableField, tableValues } of tableFieldMultiValueEqualityOperands) {
+      filteredObjects = filteredObjects.filter((obj) => tableValues.includes(obj[tableField]));
+    }
+
+    const orderBy = querySelectionModifiers.orderBy;
+    if (orderBy !== undefined) {
+      filteredObjects = filteredObjects.sort((a, b) =>
+        StubPostgresDatabaseAdapter.compareByOrderBys(orderBy, a, b),
+      );
+    }
+
+    const offset = querySelectionModifiers.offset;
+    if (offset !== undefined) {
+      filteredObjects = filteredObjects.slice(offset);
+    }
+
+    const limit = querySelectionModifiers.limit;
+    if (limit !== undefined) {
+      filteredObjects = filteredObjects.slice(0, 0 + limit);
+    }
+
+    return filteredObjects;
+  }
+
+  protected fetchManyByRawWhereClauseInternalAsync(
+    _queryInterface: any,
+    _tableName: string,
+    _rawWhereClause: string,
+    _bindings: object | any[],
+    _querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
+  ): Promise<object[]> {
+    throw new Error('Raw WHERE clauses not supported for StubDatabaseAdapter');
+  }
+
+  protected fetchManyBySQLFragmentInternalAsync(
+    _queryInterface: any,
+    _tableName: string,
+    _sqlFragment: SQLFragment<TFields>,
+    _querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
+  ): Promise<object[]> {
+    throw new Error('SQL fragments not supported for StubDatabaseAdapter');
+  }
+
+  private generateRandomID(): any {
+    const idSchemaField = this.entityConfiguration2.schema.get(this.entityConfiguration2.idField);
+    invariant(
+      idSchemaField,
+      `No schema field found for ${String(this.entityConfiguration2.idField)}`,
+    );
+    if (idSchemaField instanceof StringField) {
+      return uuidv7();
+    } else if (idSchemaField instanceof IntField) {
+      return Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);
+    } else {
+      throw new Error(
+        `Unsupported ID type for StubPostgresDatabaseAdapter: ${idSchemaField.constructor.name}`,
+      );
+    }
+  }
+
+  protected async insertInternalAsync(
+    _queryInterface: any,
+    tableName: string,
+    object: object,
+  ): Promise<object[]> {
+    const objectCollection = this.getObjectCollectionForTable(tableName);
+
+    const idField = getDatabaseFieldForEntityField(
+      this.entityConfiguration2,
+      this.entityConfiguration2.idField,
+    );
+    const objectToInsert = {
+      [idField]: this.generateRandomID(),
+      ...object,
+    };
+    objectCollection.push(objectToInsert);
+    return [objectToInsert];
+  }
+
+  protected async updateInternalAsync(
+    _queryInterface: any,
+    tableName: string,
+    tableIdField: string,
+    id: any,
+    object: object,
+  ): Promise<object[]> {
+    // SQL does not support empty updates, mirror behavior here for better test simulation
+    if (Object.keys(object).length === 0) {
+      throw new Error(`Empty update (${tableIdField} = ${id})`);
+    }
+
+    const objectCollection = this.getObjectCollectionForTable(tableName);
+
+    const objectIndex = objectCollection.findIndex((obj) => {
+      return obj[tableIdField] === id;
+    });
+
+    // SQL updates to a nonexistent row succeed but affect 0 rows,
+    // mirror that behavior here for better test simulation
+    if (objectIndex < 0) {
+      return [];
+    }
+
+    objectCollection[objectIndex] = {
+      ...objectCollection[objectIndex],
+      ...object,
+    };
+    return [objectCollection[objectIndex]];
+  }
+
+  protected async deleteInternalAsync(
+    _queryInterface: any,
+    tableName: string,
+    tableIdField: string,
+    id: any,
+  ): Promise<number> {
+    const objectCollection = this.getObjectCollectionForTable(tableName);
+
+    const objectIndex = objectCollection.findIndex((obj) => {
+      return obj[tableIdField] === id;
+    });
+
+    // SQL deletes to a nonexistent row succeed and affect 0 rows,
+    // mirror that behavior here for better test simulation
+    if (objectIndex < 0) {
+      return 0;
+    }
+
+    objectCollection.splice(objectIndex, 1);
+    return 1;
+  }
+}

package/src/__tests__/fixtures/StubPostgresDatabaseAdapterProvider.ts

@@ -0,0 +1,17 @@
+import {
+  EntityConfiguration,
+  EntityDatabaseAdapter,
+  IEntityDatabaseAdapterProvider,
+} from '@expo/entity';
+
+import { StubPostgresDatabaseAdapter } from './StubPostgresDatabaseAdapter';
+
+export class StubPostgresDatabaseAdapterProvider implements IEntityDatabaseAdapterProvider {
+  private readonly objectCollection = new Map();
+
+  getDatabaseAdapter<TFields extends Record<string, any>, TIDField extends keyof TFields>(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
+  ): EntityDatabaseAdapter<TFields, TIDField> {
+    return new StubPostgresDatabaseAdapter(entityConfiguration, this.objectCollection);
+  }
+}

package/src/__tests__/fixtures/TestEntity.ts

@@ -0,0 +1,131 @@
+import {
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  DateField,
+  IntField,
+  StringField,
+  UUIDField,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  AlwaysAllowPrivacyPolicyRule,
+} from '@expo/entity';
+import { result, Result } from '@expo/results';
+
+import { PostgresEntity } from '../../PostgresEntity';
+
+export type TestFields = {
+  customIdField: string;
+  testIndexedField: string;
+  stringField: string;
+  intField: number;
+  dateField: Date;
+  nullableField: string | null;
+};
+
+export const testEntityConfiguration = new EntityConfiguration<TestFields, 'customIdField'>({
+  idField: 'customIdField',
+  tableName: 'test_entity_should_not_write_to_db',
+  schema: {
+    customIdField: new UUIDField({
+      columnName: 'custom_id',
+      cache: true,
+    }),
+    testIndexedField: new StringField({
+      columnName: 'test_index',
+      cache: true,
+    }),
+    stringField: new StringField({
+      columnName: 'string_field',
+    }),
+    intField: new IntField({
+      columnName: 'number_field',
+    }),
+    dateField: new DateField({
+      columnName: 'date_field',
+    }),
+    nullableField: new StringField({
+      columnName: 'nullable_field',
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+  compositeFieldDefinitions: [
+    { compositeField: ['stringField', 'intField'], cache: false },
+    { compositeField: ['stringField', 'testIndexedField'], cache: true },
+    { compositeField: ['nullableField', 'testIndexedField'], cache: true },
+  ],
+});
+
+export class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  TestFields,
+  'customIdField',
+  ViewerContext,
+  TestEntity
+> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<TestFields, 'customIdField', ViewerContext, TestEntity>(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<TestFields, 'customIdField', ViewerContext, TestEntity>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<TestFields, 'customIdField', ViewerContext, TestEntity>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<TestFields, 'customIdField', ViewerContext, TestEntity>(),
+  ];
+}
+
+export class TestEntity extends PostgresEntity<TestFields, 'customIdField', ViewerContext> {
+  static defineCompanionDefinition(): EntityCompanionDefinition<
+    TestFields,
+    'customIdField',
+    ViewerContext,
+    TestEntity,
+    TestEntityPrivacyPolicy
+  > {
+    return {
+      entityClass: TestEntity,
+      entityConfiguration: testEntityConfiguration,
+      privacyPolicyClass: TestEntityPrivacyPolicy,
+    };
+  }
+
+  getBlah(): string {
+    return 'Hello World!';
+  }
+
+  static async helloAsync(
+    viewerContext: ViewerContext,
+    testValue: string,
+  ): Promise<Result<TestEntity>> {
+    const fields = {
+      customIdField: testValue,
+      testIndexedField: 'hello',
+      stringField: 'hello',
+      intField: 1,
+      dateField: new Date(),
+      nullableField: null,
+    };
+    return result(
+      new TestEntity({
+        viewerContext,
+        id: testValue,
+        databaseFields: fields,
+        selectedFields: fields,
+      }),
+    );
+  }
+
+  static async returnErrorAsync(_viewerContext: ViewerContext): Promise<Result<TestEntity>> {
+    return result(new Error('return entity'));
+  }
+
+  static async throwErrorAsync(_viewerContext: ViewerContext): Promise<Result<TestEntity>> {
+    throw new Error('threw entity');
+  }
+
+  static async nonResultAsync(_viewerContext: ViewerContext, testValue: string): Promise<string> {
+    return testValue;
+  }
+}

package/src/__tests__/fixtures/TestPaginationEntity.ts

@@ -0,0 +1,107 @@
+import {
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  EntityPrivacyPolicyEvaluationContext,
+  EntityQueryContext,
+  UUIDField,
+  StringField,
+  DateField,
+  IntField,
+  RuleEvaluationResult,
+} from '@expo/entity';
+
+import { PostgresEntity } from '../../PostgresEntity';
+
+export interface TestPaginationFields {
+  id: string;
+  name: string;
+  status: string;
+  createdAt: Date;
+  score: number;
+}
+
+export const testPaginationEntityConfiguration = new EntityConfiguration<
+  TestPaginationFields,
+  'id'
+>({
+  idField: 'id',
+  tableName: 'test_pagination_entities',
+  schema: {
+    id: new UUIDField({
+      columnName: 'id',
+      cache: true,
+    }),
+    name: new StringField({
+      columnName: 'name',
+    }),
+    status: new StringField({
+      columnName: 'status',
+    }),
+    createdAt: new DateField({
+      columnName: 'created_at',
+    }),
+    score: new IntField({
+      columnName: 'score',
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+/**
+ * Privacy policy that conditionally fails authorization based on the 'status' field.
+ * Entities with status 'unauthorized' will fail authorization.
+ */
+export class TestPaginationPrivacyPolicy extends EntityPrivacyPolicy<
+  TestPaginationFields,
+  'id',
+  ViewerContext,
+  TestPaginationEntity
+> {
+  protected override readonly readRules = [
+    {
+      async evaluateAsync(
+        _viewerContext: ViewerContext,
+        _queryContext: EntityQueryContext,
+        _evaluationContext: EntityPrivacyPolicyEvaluationContext<
+          TestPaginationFields,
+          'id',
+          ViewerContext,
+          TestPaginationEntity
+        >,
+        entity: TestPaginationEntity,
+      ): Promise<RuleEvaluationResult> {
+        // Fail authorization for entities with status 'unauthorized'
+        return entity.getField('status') === 'unauthorized'
+          ? RuleEvaluationResult.DENY
+          : RuleEvaluationResult.ALLOW;
+      },
+    },
+  ];
+
+  protected override readonly createRules = [];
+  protected override readonly updateRules = [];
+  protected override readonly deleteRules = [];
+}
+
+export class TestPaginationEntity extends PostgresEntity<
+  TestPaginationFields,
+  'id',
+  ViewerContext
+> {
+  static defineCompanionDefinition(): EntityCompanionDefinition<
+    TestPaginationFields,
+    'id',
+    ViewerContext,
+    TestPaginationEntity,
+    TestPaginationPrivacyPolicy
+  > {
+    return {
+      entityClass: TestPaginationEntity,
+      entityConfiguration: testPaginationEntityConfiguration,
+      privacyPolicyClass: TestPaginationPrivacyPolicy,
+    };
+  }
+}

package/src/__tests__/fixtures/createUnitTestPostgresEntityCompanionProvider.ts

@@ -0,0 +1,42 @@
+import {
+  EntityCompanionProvider,
+  IEntityMetricsAdapter,
+  NoOpEntityMetricsAdapter,
+} from '@expo/entity';
+import {
+  InMemoryFullCacheStubCacheAdapterProvider,
+  StubQueryContextProvider,
+} from '@expo/entity-testing-utils';
+
+import { StubPostgresDatabaseAdapterProvider } from './StubPostgresDatabaseAdapterProvider';
+
+const queryContextProvider = new StubQueryContextProvider();
+
+/**
+ * Entity companion provider for use in knex unit tests. All database and cache implementations
+ * are replaced with in-memory simulations.
+ */
+export const createUnitTestPostgresEntityCompanionProvider = (
+  metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter(),
+): EntityCompanionProvider => {
+  return new EntityCompanionProvider(
+    metricsAdapter,
+    new Map([
+      [
+        'postgres',
+        {
+          adapterProvider: new StubPostgresDatabaseAdapterProvider(),
+          queryContextProvider,
+        },
+      ],
+    ]),
+    new Map([
+      [
+        'redis',
+        {
+          cacheAdapterProvider: new InMemoryFullCacheStubCacheAdapterProvider(),
+        },
+      ],
+    ]),
+  );
+};

package/src/index.ts

@@ -4,8 +4,23 @@
  * @module @expo/entity-database-adapter-knex
  */
 
+export * from './AuthorizationResultBasedKnexEntityLoader';
+export * from './BasePostgresEntityDatabaseAdapter';
+export * from './BaseSQLQueryBuilder';
+export * from './EnforcingKnexEntityLoader';
 export * from './EntityFields';
+export * from './KnexEntityLoaderFactory';
+export * from './knexLoader';
+export * from './PaginationStrategy';
+export * from './PostgresEntity';
 export * from './PostgresEntityDatabaseAdapter';
 export * from './PostgresEntityDatabaseAdapterProvider';
 export * from './PostgresEntityQueryContextProvider';
+export * from './ReadonlyPostgresEntity';
+export * from './SQLOperator';
 export * from './errors/wrapNativePostgresCallAsync';
+export * from './internal/EntityKnexDataManager';
+export * from './internal/getKnexDataManager';
+export * from './internal/getKnexEntityLoaderFactory';
+export * from './internal/utilityTypes';
+export * from './internal/weakMaps';