@expo/entity-testing-utils 0.41.0

package/src/StubQueryContextProvider.ts

@@ -0,0 +1,19 @@
+import { TransactionConfig, EntityQueryContextProvider } from '@expo/entity';
+
+export default class StubQueryContextProvider extends EntityQueryContextProvider {
+  protected getQueryInterface(): any {
+    return {};
+  }
+
+  protected createTransactionRunner<T>(
+    _transactionConfig?: TransactionConfig,
+  ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T> {
+    return (transactionScope) => Promise.resolve(transactionScope({}));
+  }
+
+  protected createNestedTransactionRunner<T>(
+    _outerQueryInterface: any,
+  ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T> {
+    return (transactionScope) => Promise.resolve(transactionScope({}));
+  }
+}

package/src/TSMockitoExtensions.ts

@@ -0,0 +1,69 @@
+import {
+  SerializableKeyMap,
+  CompositeFieldHolder,
+  CompositeFieldValueHolder,
+  SingleFieldHolder,
+  SingleFieldValueHolder,
+} from '@expo/entity';
+import isEqualWith from 'lodash/isEqualWith';
+import { Matcher } from 'ts-mockito/lib/matcher/type/Matcher';
+
+export function isEqualWithEntityAware(expected: any, actual: any): boolean {
+  return isEqualWith(expected, actual, (expected: any, actual: any): boolean | undefined => {
+    if (expected instanceof Matcher) {
+      return expected.match(actual);
+    }
+
+    if (expected instanceof SingleFieldHolder && actual instanceof SingleFieldHolder) {
+      return expected.fieldName === actual.fieldName;
+    }
+
+    if (expected instanceof SingleFieldValueHolder && actual instanceof SingleFieldValueHolder) {
+      return expected.fieldValue === actual.fieldValue;
+    }
+
+    if (expected instanceof CompositeFieldHolder && actual instanceof CompositeFieldHolder) {
+      return expected.serialize() === actual.serialize();
+    }
+
+    if (
+      expected instanceof CompositeFieldValueHolder &&
+      actual instanceof CompositeFieldValueHolder
+    ) {
+      return expected.serialize() === actual.serialize();
+    }
+
+    if (expected instanceof SerializableKeyMap && actual instanceof SerializableKeyMap) {
+      for (const [key, value] of expected.entries()) {
+        if (!actual.has(key) || !isEqualWith(value, actual.get(key))) {
+          return false;
+        }
+      }
+      return true;
+    }
+
+    return undefined;
+  });
+}
+
+export class DeepEqualEntityAwareMatcher<T> extends Matcher {
+  constructor(private readonly expectedValue: T) {
+    super();
+  }
+
+  public override match(value: any): boolean {
+    return isEqualWithEntityAware(this.expectedValue, value);
+  }
+
+  public override toString(): string {
+    if (this.expectedValue instanceof Array) {
+      return `deepEqualEntityAware([${this.expectedValue}])`;
+    } else {
+      return `deepEqualEntityAware(${this.expectedValue})`;
+    }
+  }
+}
+
+export function deepEqualEntityAware<T>(expectedValue: T): T {
+  return new DeepEqualEntityAwareMatcher(expectedValue) as any;
+}

package/src/__testfixtures__/DateIDTestEntity.ts

@@ -0,0 +1,62 @@
+import {
+  Entity,
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  DateField,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  AlwaysAllowPrivacyPolicyRule,
+} from '@expo/entity';
+
+export type DateIDTestFields = {
+  id: Date;
+};
+
+export const dateIDTestEntityConfiguration = new EntityConfiguration<DateIDTestFields, 'id'>({
+  idField: 'id',
+  tableName: 'simple_test_entity_should_not_write_to_db',
+  schema: {
+    id: new DateField({
+      columnName: 'custom_id',
+      cache: true,
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+export class DateIDTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  DateIDTestFields,
+  'id',
+  ViewerContext,
+  DateIDTestEntity
+> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<DateIDTestFields, 'id', ViewerContext, DateIDTestEntity>(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<DateIDTestFields, 'id', ViewerContext, DateIDTestEntity>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<DateIDTestFields, 'id', ViewerContext, DateIDTestEntity>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<DateIDTestFields, 'id', ViewerContext, DateIDTestEntity>(),
+  ];
+}
+
+export default class DateIDTestEntity extends Entity<DateIDTestFields, 'id', ViewerContext> {
+  static defineCompanionDefinition(): EntityCompanionDefinition<
+    DateIDTestFields,
+    'id',
+    ViewerContext,
+    DateIDTestEntity,
+    DateIDTestEntityPrivacyPolicy
+  > {
+    return {
+      entityClass: DateIDTestEntity,
+      entityConfiguration: dateIDTestEntityConfiguration,
+      privacyPolicyClass: DateIDTestEntityPrivacyPolicy,
+    };
+  }
+}

package/src/__testfixtures__/SimpleTestEntity.ts

@@ -0,0 +1,95 @@
+import {
+  Entity,
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  AlwaysAllowPrivacyPolicyRule,
+  UUIDField,
+} from '@expo/entity';
+
+export type SimpleTestFields = {
+  id: string;
+};
+
+export type SimpleTestFieldSelection = keyof SimpleTestFields;
+
+export const simpleTestEntityConfiguration = new EntityConfiguration<SimpleTestFields, 'id'>({
+  idField: 'id',
+  tableName: 'simple_test_entity_should_not_write_to_db',
+  schema: {
+    id: new UUIDField({
+      columnName: 'custom_id',
+      cache: true,
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+export class SimpleTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  SimpleTestFields,
+  'id',
+  ViewerContext,
+  SimpleTestEntity,
+  SimpleTestFieldSelection
+> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      SimpleTestFields,
+      'id',
+      ViewerContext,
+      SimpleTestEntity,
+      SimpleTestFieldSelection
+    >(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      SimpleTestFields,
+      'id',
+      ViewerContext,
+      SimpleTestEntity,
+      SimpleTestFieldSelection
+    >(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      SimpleTestFields,
+      'id',
+      ViewerContext,
+      SimpleTestEntity,
+      SimpleTestFieldSelection
+    >(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      SimpleTestFields,
+      'id',
+      ViewerContext,
+      SimpleTestEntity,
+      SimpleTestFieldSelection
+    >(),
+  ];
+}
+
+export default class SimpleTestEntity extends Entity<
+  SimpleTestFields,
+  'id',
+  ViewerContext,
+  SimpleTestFieldSelection
+> {
+  static defineCompanionDefinition(): EntityCompanionDefinition<
+    SimpleTestFields,
+    'id',
+    ViewerContext,
+    SimpleTestEntity,
+    SimpleTestEntityPrivacyPolicy,
+    SimpleTestFieldSelection
+  > {
+    return {
+      entityClass: SimpleTestEntity,
+      entityConfiguration: simpleTestEntityConfiguration,
+      privacyPolicyClass: SimpleTestEntityPrivacyPolicy,
+    };
+  }
+}

package/src/__testfixtures__/TestEntity.ts

@@ -0,0 +1,130 @@
+import {
+  Entity,
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  DateField,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  AlwaysAllowPrivacyPolicyRule,
+  UUIDField,
+  StringField,
+  IntField,
+} from '@expo/entity';
+import { result, Result } from '@expo/results';
+
+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 default class TestEntity extends Entity<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/__testfixtures__/TestEntityNumberKey.ts

@@ -0,0 +1,62 @@
+import {
+  Entity,
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  IntField,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  AlwaysAllowPrivacyPolicyRule,
+} from '@expo/entity';
+
+export type NumberKeyFields = {
+  id: number;
+};
+
+export const numberKeyEntityConfiguration = new EntityConfiguration<NumberKeyFields, 'id'>({
+  idField: 'id',
+  tableName: 'simple_test_entity_should_not_write_to_db',
+  schema: {
+    id: new IntField({
+      columnName: 'custom_id',
+      cache: false,
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+export class NumberKeyPrivacyPolicy extends EntityPrivacyPolicy<
+  NumberKeyFields,
+  'id',
+  ViewerContext,
+  NumberKeyEntity
+> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<NumberKeyFields, 'id', ViewerContext, NumberKeyEntity>(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<NumberKeyFields, 'id', ViewerContext, NumberKeyEntity>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<NumberKeyFields, 'id', ViewerContext, NumberKeyEntity>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<NumberKeyFields, 'id', ViewerContext, NumberKeyEntity>(),
+  ];
+}
+
+export default class NumberKeyEntity extends Entity<NumberKeyFields, 'id', ViewerContext> {
+  static defineCompanionDefinition(): EntityCompanionDefinition<
+    NumberKeyFields,
+    'id',
+    ViewerContext,
+    NumberKeyEntity,
+    NumberKeyPrivacyPolicy
+  > {
+    return {
+      entityClass: NumberKeyEntity,
+      entityConfiguration: numberKeyEntityConfiguration,
+      privacyPolicyClass: NumberKeyPrivacyPolicy,
+    };
+  }
+}

package/src/__tests__/FileConsistentcyWithEntity-test.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+
+it.each([
+  'createUnitTestEntityCompanionProvider',
+  'describeFieldTestCase',
+  'PrivacyPolicyRuleTestUtils',
+  'StubCacheAdapter',
+  'StubDatabaseAdapter',
+  'StubDatabaseAdapterProvider',
+  'StubQueryContextProvider',
+  'TSMockitoExtensions',
+])('$localPath the same as in @expo/entity', async (fileName) => {
+  // There isn't a great way to have TSMockitoExtensions in a shared package since it circularly depends on entity itself,
+  // and entity would want to use it for testing. Therefore, we duplicate it and ensure it stays in sync.
+
+  const fileContentsFromEntity = await readFile(
+    path.resolve(__dirname, `../../../entity/src/utils/__testfixtures__/${fileName}.ts`),
+    'utf-8',
+  );
+  const fileContentsFromEntityTestingUtils = await readFile(
+    path.resolve(__dirname, `../${fileName}.ts`),
+    'utf-8',
+  );
+
+  const trimmedFiles = [fileContentsFromEntity, fileContentsFromEntityTestingUtils].map((file) =>
+    file.substring(file.indexOf('export')),
+  );
+
+  expect(trimmedFiles[0]?.length).toBeGreaterThan(0);
+  expect(trimmedFiles[0]).toEqual(trimmedFiles[1]);
+});

package/src/__tests__/PrivacyPolicyRuleTestUtils-test.ts

@@ -0,0 +1,44 @@
+import {
+  EntityPrivacyPolicyEvaluationContext,
+  EntityQueryContext,
+  ViewerContext,
+  AlwaysAllowPrivacyPolicyRule,
+  AlwaysDenyPrivacyPolicyRule,
+} from '@expo/entity';
+import { anything, instance, mock } from 'ts-mockito';
+
+import { describePrivacyPolicyRuleWithAsyncTestCase } from '../PrivacyPolicyRuleTestUtils';
+
+describe(describePrivacyPolicyRuleWithAsyncTestCase, () => {
+  describe('default args do not execute', () => {
+    describePrivacyPolicyRuleWithAsyncTestCase(new AlwaysAllowPrivacyPolicyRule(), {
+      allowCases: new Map([
+        [
+          'case',
+          async () => ({
+            viewerContext: instance(mock(ViewerContext)),
+            queryContext: instance(mock(EntityQueryContext)),
+            evaluationContext:
+              instance(mock<EntityPrivacyPolicyEvaluationContext<any, any, any, any, any>>()),
+            entity: anything(),
+          }),
+        ],
+      ]),
+    });
+
+    describePrivacyPolicyRuleWithAsyncTestCase(new AlwaysDenyPrivacyPolicyRule(), {
+      denyCases: new Map([
+        [
+          'case',
+          async () => ({
+            viewerContext: instance(mock(ViewerContext)),
+            queryContext: instance(mock(EntityQueryContext)),
+            evaluationContext:
+              instance(mock<EntityPrivacyPolicyEvaluationContext<any, any, any, any, any>>()),
+            entity: anything(),
+          }),
+        ],
+      ]),
+    });
+  });
+});

package/src/__tests__/StubCacheAdapter-test.ts

@@ -0,0 +1,134 @@
+import {
+  CompositeFieldHolder,
+  CompositeFieldValueHolder,
+  CompositeFieldValueHolderMap,
+  SingleFieldHolder,
+  SingleFieldValueHolder,
+  SingleFieldValueHolderMap,
+  CacheStatus,
+} from '@expo/entity';
+
+import {
+  InMemoryFullCacheStubCacheAdapterProvider,
+  InMemoryFullCacheStubCacheAdapter,
+  NoCacheStubCacheAdapter,
+} from '../StubCacheAdapter';
+import { testEntityConfiguration, TestFields } from '../__testfixtures__/TestEntity';
+
+describe(NoCacheStubCacheAdapter, () => {
+  describe('loadManyAsync', () => {
+    it('should return a map of CacheLoadResult with status CacheStatus.MISS for all single values', async () => {
+      const adapter = new NoCacheStubCacheAdapter<TestFields, 'customIdField'>();
+      const result = await adapter.loadManyAsync(new SingleFieldHolder('stringField'), [
+        new SingleFieldValueHolder('huh'),
+      ]);
+      expect(result).toEqual(
+        new SingleFieldValueHolderMap(
+          new Map([[new SingleFieldValueHolder('huh'), { status: CacheStatus.MISS }]]),
+        ),
+      );
+    });
+
+    it('should return a map of CacheLoadResult with status CacheStatus.MISS for all composite values', async () => {
+      const adapter = new NoCacheStubCacheAdapter<TestFields, 'customIdField'>();
+      const result = await adapter.loadManyAsync(
+        new CompositeFieldHolder<TestFields, 'customIdField'>(['stringField', 'intField']),
+        [new CompositeFieldValueHolder({ stringField: 'huh', intField: 42 })],
+      );
+      expect(result).toEqual(
+        new CompositeFieldValueHolderMap(
+          new Map([
+            [
+              new CompositeFieldValueHolder({ stringField: 'huh', intField: 42 }),
+              { status: CacheStatus.MISS },
+            ],
+          ]),
+        ),
+      );
+    });
+  });
+});
+
+describe(InMemoryFullCacheStubCacheAdapter, () => {
+  it('correctly functions', async () => {
+    const adapter = new InMemoryFullCacheStubCacheAdapterProvider().getCacheAdapter(
+      testEntityConfiguration,
+    );
+    const result = await adapter.loadManyAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    expect(result).toEqual(
+      new SingleFieldValueHolderMap(
+        new Map([[new SingleFieldValueHolder('huh'), { status: CacheStatus.MISS }]]),
+      ),
+    );
+
+    await adapter.cacheManyAsync(new SingleFieldHolder('stringField'), new Map());
+    const result2 = await adapter.loadManyAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    expect(result2).toEqual(
+      new SingleFieldValueHolderMap(
+        new Map([[new SingleFieldValueHolder('huh'), { status: CacheStatus.MISS }]]),
+      ),
+    );
+
+    const fields = {
+      stringField: 'huh',
+      customIdField: 'id1',
+      testIndexedField: 'wat',
+      intField: 3,
+      dateField: new Date(),
+      nullableField: null,
+    };
+
+    await adapter.cacheManyAsync(
+      new SingleFieldHolder('stringField'),
+      new Map([[new SingleFieldValueHolder('huh'), fields]]),
+    );
+    const result3 = await adapter.loadManyAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    expect(result3).toEqual(
+      new SingleFieldValueHolderMap(
+        new Map([[new SingleFieldValueHolder('huh'), { status: CacheStatus.HIT, item: fields }]]),
+      ),
+    );
+
+    await adapter.invalidateManyAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    const result4 = await adapter.loadManyAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    expect(result4).toEqual(
+      new SingleFieldValueHolderMap(
+        new Map([[new SingleFieldValueHolder('huh'), { status: CacheStatus.MISS }]]),
+      ),
+    );
+
+    await adapter.cacheDBMissesAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    const result5 = await adapter.loadManyAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    expect(result5).toEqual(
+      new SingleFieldValueHolderMap(
+        new Map([[new SingleFieldValueHolder('huh'), { status: CacheStatus.NEGATIVE }]]),
+      ),
+    );
+
+    await adapter.invalidateManyAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    const result6 = await adapter.loadManyAsync(new SingleFieldHolder('stringField'), [
+      new SingleFieldValueHolder('huh'),
+    ]);
+    expect(result6).toEqual(
+      new SingleFieldValueHolderMap(
+        new Map([[new SingleFieldValueHolder('huh'), { status: CacheStatus.MISS }]]),
+      ),
+    );
+  });
+});