@expo/entity 0.38.0 → 0.40.0

package/build/utils/testing/StubQueryContextProvider.js

@@ -3,7 +3,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StubQueryContextProvider = void 0;
 const EntityQueryContextProvider_1 = __importDefault(require("../../EntityQueryContextProvider"));
 class StubQueryContextProvider extends EntityQueryContextProvider_1.default {
     getQueryInterface() {
@@ -16,6 +15,5 @@ class StubQueryContextProvider extends EntityQueryContextProvider_1.default {
         return (transactionScope) => Promise.resolve(transactionScope({}));
     }
 }
-exports.StubQueryContextProvider = StubQueryContextProvider;
-exports.default = new StubQueryContextProvider();
+exports.default = StubQueryContextProvider;
 //# sourceMappingURL=StubQueryContextProvider.js.map

package/build/utils/testing/StubQueryContextProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"StubQueryContextProvider.js","sourceRoot":"","sources":["../../../src/utils/testing/StubQueryContextProvider.ts"],"names":[],"mappings":";;;;;;AACA,kGAA0E;AAE1E,MAAa,wBAAyB,SAAQ,oCAA0B;IAC5D,iBAAiB;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAES,uBAAuB,CAC/B,kBAAsC;QAEtC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;IAES,6BAA6B,CACrC,oBAAyB;QAEzB,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;CACF;AAhBD,4DAgBC;AAED,kBAAe,IAAI,wBAAwB,EAAE,CAAC"}
+{"version":3,"file":"StubQueryContextProvider.js","sourceRoot":"","sources":["../../../src/utils/testing/StubQueryContextProvider.ts"],"names":[],"mappings":";;;;;AACA,kGAA0E;AAE1E,MAAqB,wBAAyB,SAAQ,oCAA0B;IACpE,iBAAiB;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAES,uBAAuB,CAC/B,kBAAsC;QAEtC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;IAES,6BAA6B,CACrC,oBAAyB;QAEzB,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;CACF;AAhBD,2CAgBC"}

package/build/utils/testing/createUnitTestEntityCompanionProvider.js

@@ -9,6 +9,7 @@ const StubDatabaseAdapterProvider_1 = __importDefault(require("./StubDatabaseAda
 const StubQueryContextProvider_1 = __importDefault(require("./StubQueryContextProvider"));
 const EntityCompanionProvider_1 = __importDefault(require("../../EntityCompanionProvider"));
 const NoOpEntityMetricsAdapter_1 = __importDefault(require("../../metrics/NoOpEntityMetricsAdapter"));
+const queryContextProvider = new StubQueryContextProvider_1.default();
 /**
  * Entity companion provider for use in unit tests. All database and cache implementations
  * are replaced with in-memory simulations.
@@ -19,7 +20,7 @@ const createUnitTestEntityCompanionProvider = (metricsAdapter = new NoOpEntityMe
             'postgres',
             {
                 adapterProvider: new StubDatabaseAdapterProvider_1.default(),
-                queryContextProvider: StubQueryContextProvider_1.default,
+                queryContextProvider,
             },
         ],
     ]), new Map([

package/build/utils/testing/createUnitTestEntityCompanionProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"createUnitTestEntityCompanionProvider.js","sourceRoot":"","sources":["../../../src/utils/testing/createUnitTestEntityCompanionProvider.ts"],"names":[],"mappings":";;;;;;AAAA,yDAA+E;AAC/E,gGAAwE;AACxE,0FAAkE;AAClE,4FAAoE;AAEpE,sGAA8E;AAE9E;;;GAGG;AACI,MAAM,qCAAqC,GAAG,CACnD,iBAAwC,IAAI,kCAAwB,EAAE,EAC7C,EAAE;IAC3B,OAAO,IAAI,iCAAuB,CAChC,cAAc,EACd,IAAI,GAAG,CAAC;QACN;YACE,UAAU;YACV;gBACE,eAAe,EAAE,IAAI,qCAA2B,EAAE;gBAClD,oBAAoB,EAAE,kCAAwB;aAC/C;SACF;KACF,CAAC,EACF,IAAI,GAAG,CAAC;QACN;YACE,OAAO;YACP;gBACE,oBAAoB,EAAE,IAAI,4DAAyC,EAAE;aACtE;SACF;KACF,CAAC,CACH,CAAC;AACJ,CAAC,CAAC;AAvBW,QAAA,qCAAqC,yCAuBhD"}
+{"version":3,"file":"createUnitTestEntityCompanionProvider.js","sourceRoot":"","sources":["../../../src/utils/testing/createUnitTestEntityCompanionProvider.ts"],"names":[],"mappings":";;;;;;AAAA,yDAA+E;AAC/E,gGAAwE;AACxE,0FAAkE;AAClE,4FAAoE;AAEpE,sGAA8E;AAE9E,MAAM,oBAAoB,GAAG,IAAI,kCAAwB,EAAE,CAAC;AAE5D;;;GAGG;AACI,MAAM,qCAAqC,GAAG,CACnD,iBAAwC,IAAI,kCAAwB,EAAE,EAC7C,EAAE;IAC3B,OAAO,IAAI,iCAAuB,CAChC,cAAc,EACd,IAAI,GAAG,CAAC;QACN;YACE,UAAU;YACV;gBACE,eAAe,EAAE,IAAI,qCAA2B,EAAE;gBAClD,oBAAoB;aACrB;SACF;KACF,CAAC,EACF,IAAI,GAAG,CAAC;QACN;YACE,OAAO;YACP;gBACE,oBAAoB,EAAE,IAAI,4DAAyC,EAAE;aACtE;SACF;KACF,CAAC,CACH,CAAC;AACJ,CAAC,CAAC;AAvBW,QAAA,qCAAqC,yCAuBhD"}

package/build/utils/testing/describeFieldTestCase.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = describeFieldTestCase;
 function describeFieldTestCase(fieldDefinition, validValues, invalidValues) {
     describe(fieldDefinition.constructor.name, () => {
         if (validValues.length > 0) {
@@ -14,5 +15,4 @@ function describeFieldTestCase(fieldDefinition, validValues, invalidValues) {
         }
     });
 }
-exports.default = describeFieldTestCase;
 //# sourceMappingURL=describeFieldTestCase.js.map

package/build/utils/testing/describeFieldTestCase.js.map

@@ -1 +1 @@
-{"version":3,"file":"describeFieldTestCase.js","sourceRoot":"","sources":["../../../src/utils/testing/describeFieldTestCase.ts"],"names":[],"mappings":";;AAEA,SAAwB,qBAAqB,CAC3C,eAAyC,EACzC,WAAgB,EAChB,aAAoB;IAEpB,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE;QAC9C,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC/E,MAAM,CAAC,eAAe,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC/D,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE;gBACnF,MAAM,CAAC,eAAe,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAChE,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAlBD,wCAkBC"}
+{"version":3,"file":"describeFieldTestCase.js","sourceRoot":"","sources":["../../../src/utils/testing/describeFieldTestCase.ts"],"names":[],"mappings":";;AAEA,wCAkBC;AAlBD,SAAwB,qBAAqB,CAC3C,eAAyC,EACzC,WAAgB,EAChB,aAAoB;IAEpB,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE;QAC9C,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC/E,MAAM,CAAC,eAAe,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC/D,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE;gBACnF,MAAM,CAAC,eAAe,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAChE,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "A privacy-first data model",
   "files": [
     "build",
@@ -16,7 +16,7 @@
     "test": "jest --rootDir . --config ../../resources/jest.config.js",
     "integration": "../../resources/run-with-docker yarn integration-no-setup",
     "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir . --runInBand --passWithNoTests",
-    "barrelsby": "barrelsby --config ../../.barrelsby.json"
+    "ctix": "ctix build --config ../../.ctirc && ../../resources/prepend-barrel.sh '@expo/entity'"
   },
   "engines": {
     "node": ">=16"
@@ -34,5 +34,21 @@
     "uuid": "^8.3.0",
     "uuidv7": "^1.0.0"
   },
-  "gitHead": "d7cc0c23b983eccca9ca4e7ca620a5aaef6846c4"
+  "devDependencies": {
+    "@types/invariant": "^2.2.37",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.1",
+    "@types/uuid": "^8.3.0",
+    "ctix": "^2.7.0",
+    "eslint": "^8.57.1",
+    "eslint-config-universe": "^14.0.0",
+    "eslint-plugin-tsdoc": "^0.3.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.3.3",
+    "prettier-plugin-organize-imports": "^4.1.0",
+    "ts-jest": "^29.2.5",
+    "ts-mockito": "^2.6.1",
+    "typescript": "^5.7.3"
+  },
+  "gitHead": "74c396255c8177a87cf80da2608072f5989dd519"
 }

package/src/AuthorizationResultBasedEntityAssociationLoader.ts

@@ -0,0 +1,492 @@
+import { Result, result } from '@expo/results';
+
+import { IEntityClass } from './Entity';
+import EntityPrivacyPolicy from './EntityPrivacyPolicy';
+import { EntityQueryContext } from './EntityQueryContext';
+import ReadonlyEntity from './ReadonlyEntity';
+import ViewerContext from './ViewerContext';
+
+/**
+ * An association loader is a set of convenience methods for loading entities
+ * associated with an entity. In relational databases, these entities are often referenced
+ * by foreign keys.
+ */
+export default class AuthorizationResultBasedEntityAssociationLoader<
+  TFields extends object,
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields,
+> {
+  constructor(
+    private readonly entity: TEntity,
+    private readonly queryContext: EntityQueryContext,
+  ) {}
+
+  /**
+   * Load an associated entity identified by a field value of this entity. In a relational database,
+   * the field in this entity is a foreign key to the ID of the associated entity.
+   * @param fieldIdentifyingAssociatedEntity - field of this entity containing the ID of the associated entity
+   * @param associatedEntityClass - class of the associated entity
+   */
+  async loadAssociatedEntityAsync<
+    TIdentifyingField extends keyof Pick<TFields, TSelectedFields>,
+    TAssociatedFields extends object,
+    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedEntity extends ReadonlyEntity<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields,
+  >(
+    fieldIdentifyingAssociatedEntity: TIdentifyingField,
+    associatedEntityClass: IEntityClass<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedPrivacyPolicy,
+      TAssociatedSelectedFields
+    >,
+  ): Promise<
+    Result<null extends TFields[TIdentifyingField] ? TAssociatedEntity | null : TAssociatedEntity>
+  > {
+    const associatedEntityID = this.entity.getField(fieldIdentifyingAssociatedEntity);
+    if (!associatedEntityID) {
+      return result(null) as Result<
+        null extends TFields[TIdentifyingField] ? TAssociatedEntity | null : TAssociatedEntity
+      >;
+    }
+
+    const loader = this.entity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(associatedEntityClass)
+      .getLoaderFactory()
+      .forLoad(this.queryContext, { previousValue: null, cascadingDeleteCause: null });
+
+    return (await loader.loadByIDAsync(associatedEntityID as unknown as TAssociatedID)) as Result<
+      null extends TFields[TIdentifyingField] ? TAssociatedEntity | null : TAssociatedEntity
+    >;
+  }
+
+  /**
+   * Load many entities associated with this entity, often referred to as entites belonging
+   * to this entity. In a relational database, the field in the foreign entity is a
+   * foreign key to the ID of this entity. Also commonly referred to as a has many relationship,
+   * where this entity has many associated entities.
+   * @param associatedEntityClass - class of the associated entities
+   * @param associatedEntityFieldContainingThisID - field of associated entity which contains the ID of this entity
+   */
+  async loadManyAssociatedEntitiesAsync<
+    TAssociatedFields extends object,
+    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedEntity extends ReadonlyEntity<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields,
+  >(
+    associatedEntityClass: IEntityClass<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedPrivacyPolicy,
+      TAssociatedSelectedFields
+    >,
+    associatedEntityFieldContainingThisID: keyof Pick<TAssociatedFields, TAssociatedSelectedFields>,
+  ): Promise<readonly Result<TAssociatedEntity>[]> {
+    const thisID = this.entity.getID();
+    const loader = this.entity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(associatedEntityClass)
+      .getLoaderFactory()
+      .forLoad(this.queryContext, { previousValue: null, cascadingDeleteCause: null });
+    return await loader.loadManyByFieldEqualingAsync(
+      associatedEntityFieldContainingThisID,
+      thisID as any,
+    );
+  }
+
+  /**
+   * Load an associated entity identified by a field value of this entity. In a relational database,
+   * the field in this entity is a foreign key to a unique field of the associated entity.
+   * @param fieldIdentifyingAssociatedEntity - field of this entity containing the value with which to look up associated entity
+   * @param associatedEntityClass - class of the associated entity
+   * @param associatedEntityLookupByField - field of associated entity with which to look up the associated entity
+   */
+  async loadAssociatedEntityByFieldEqualingAsync<
+    TAssociatedFields extends object,
+    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedEntity extends ReadonlyEntity<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields,
+  >(
+    fieldIdentifyingAssociatedEntity: keyof Pick<TFields, TSelectedFields>,
+    associatedEntityClass: IEntityClass<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedPrivacyPolicy,
+      TAssociatedSelectedFields
+    >,
+    associatedEntityLookupByField: keyof Pick<TAssociatedFields, TAssociatedSelectedFields>,
+  ): Promise<Result<TAssociatedEntity> | null> {
+    const associatedFieldValue = this.entity.getField(fieldIdentifyingAssociatedEntity);
+    if (!associatedFieldValue) {
+      return null;
+    }
+    const loader = this.entity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(associatedEntityClass)
+      .getLoaderFactory()
+      .forLoad(this.queryContext, { previousValue: null, cascadingDeleteCause: null });
+    return await loader.loadByFieldEqualingAsync(
+      associatedEntityLookupByField,
+      associatedFieldValue as any,
+    );
+  }
+
+  /**
+   * Load many associated entities identified by a field value of this entity. In a relational database,
+   * the field in this entity refers to a field of the associated entity.
+   * @param fieldIdentifyingAssociatedEntity - field of this entity containing the value with which to look up associated entities
+   * @param associatedEntityClass - class of the associated entities
+   * @param associatedEntityLookupByField - field of associated entities with which to look up the associated entities
+   */
+  async loadManyAssociatedEntitiesByFieldEqualingAsync<
+    TAssociatedFields extends object,
+    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedEntity extends ReadonlyEntity<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields,
+  >(
+    fieldIdentifyingAssociatedEntity: keyof Pick<TFields, TSelectedFields>,
+    associatedEntityClass: IEntityClass<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedPrivacyPolicy,
+      TAssociatedSelectedFields
+    >,
+    associatedEntityLookupByField: keyof Pick<TAssociatedFields, TAssociatedSelectedFields>,
+  ): Promise<readonly Result<TAssociatedEntity>[]> {
+    const associatedFieldValue = this.entity.getField(fieldIdentifyingAssociatedEntity);
+    if (!associatedFieldValue) {
+      return [];
+    }
+
+    const loader = this.entity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(associatedEntityClass)
+      .getLoaderFactory()
+      .forLoad(this.queryContext, { previousValue: null, cascadingDeleteCause: null });
+    return await loader.loadManyByFieldEqualingAsync(
+      associatedEntityLookupByField,
+      associatedFieldValue as any,
+    );
+  }
+
+  /**
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
+   * fold step, load an associated entity identified by a field value of the current fold value.
+   * @param loadDirectives - associated entity load directives instructing each step of the folds
+   */
+  async loadAssociatedEntityThroughAsync<
+    TFields2 extends object,
+    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
+    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TPrivacyPolicy2 extends EntityPrivacyPolicy<
+      TFields2,
+      TID2,
+      TViewerContext,
+      TEntity2,
+      TSelectedFields2
+    >,
+    TSelectedFields2 extends keyof TFields2 = keyof TFields2,
+  >(
+    loadDirectives: [
+      EntityLoadThroughDirective<
+        TViewerContext,
+        TFields,
+        TFields2,
+        TID2,
+        TEntity2,
+        TPrivacyPolicy2,
+        TSelectedFields,
+        TSelectedFields2
+      >,
+    ],
+  ): Promise<Result<TEntity2> | null>;
+
+  /**
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
+   * fold step, load an associated entity identified by a field value of the current fold value.
+   * @param loadDirectives - associated entity load directives instructing each step of the folds
+   */
+  async loadAssociatedEntityThroughAsync<
+    TFields2 extends object,
+    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
+    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TPrivacyPolicy2 extends EntityPrivacyPolicy<
+      TFields2,
+      TID2,
+      TViewerContext,
+      TEntity2,
+      TSelectedFields2
+    >,
+    TFields3 extends object,
+    TID3 extends NonNullable<TFields3[TSelectedFields3]>,
+    TEntity3 extends ReadonlyEntity<TFields3, TID3, TViewerContext, TSelectedFields3>,
+    TPrivacyPolicy3 extends EntityPrivacyPolicy<
+      TFields3,
+      TID3,
+      TViewerContext,
+      TEntity3,
+      TSelectedFields3
+    >,
+    TSelectedFields2 extends keyof TFields2 = keyof TFields2,
+    TSelectedFields3 extends keyof TFields3 = keyof TFields3,
+  >(
+    loadDirectives: [
+      EntityLoadThroughDirective<
+        TViewerContext,
+        TFields,
+        TFields2,
+        TID2,
+        TEntity2,
+        TPrivacyPolicy2,
+        TSelectedFields,
+        TSelectedFields2
+      >,
+      EntityLoadThroughDirective<
+        TViewerContext,
+        TFields2,
+        TFields3,
+        TID3,
+        TEntity3,
+        TPrivacyPolicy3,
+        TSelectedFields2,
+        TSelectedFields3
+      >,
+    ],
+  ): Promise<Result<TEntity3> | null>;
+
+  /**
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
+   * fold step, load an associated entity identified by a field value of the current fold value.
+   * @param loadDirectives - associated entity load directives instructing each step of the folds
+   */
+  async loadAssociatedEntityThroughAsync<
+    TFields2 extends object,
+    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
+    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TPrivacyPolicy2 extends EntityPrivacyPolicy<
+      TFields2,
+      TID2,
+      TViewerContext,
+      TEntity2,
+      TSelectedFields2
+    >,
+    TFields3 extends object,
+    TID3 extends NonNullable<TFields3[TSelectedFields3]>,
+    TEntity3 extends ReadonlyEntity<TFields3, TID3, TViewerContext, TSelectedFields3>,
+    TPrivacyPolicy3 extends EntityPrivacyPolicy<
+      TFields3,
+      TID3,
+      TViewerContext,
+      TEntity3,
+      TSelectedFields3
+    >,
+    TFields4 extends object,
+    TID4 extends NonNullable<TFields4[TSelectedFields4]>,
+    TEntity4 extends ReadonlyEntity<TFields4, TID4, TViewerContext, TSelectedFields4>,
+    TPrivacyPolicy4 extends EntityPrivacyPolicy<
+      TFields4,
+      TID4,
+      TViewerContext,
+      TEntity4,
+      TSelectedFields4
+    >,
+    TSelectedFields2 extends keyof TFields2 = keyof TFields2,
+    TSelectedFields3 extends keyof TFields3 = keyof TFields3,
+    TSelectedFields4 extends keyof TFields4 = keyof TFields4,
+  >(
+    loadDirectives: [
+      EntityLoadThroughDirective<
+        TViewerContext,
+        TFields,
+        TFields2,
+        TID2,
+        TEntity2,
+        TPrivacyPolicy2,
+        TSelectedFields,
+        TSelectedFields2
+      >,
+      EntityLoadThroughDirective<
+        TViewerContext,
+        TFields2,
+        TFields3,
+        TID3,
+        TEntity3,
+        TPrivacyPolicy3,
+        TSelectedFields2,
+        TSelectedFields3
+      >,
+      EntityLoadThroughDirective<
+        TViewerContext,
+        TFields3,
+        TFields4,
+        TID4,
+        TEntity4,
+        TPrivacyPolicy4,
+        TSelectedFields3,
+        TSelectedFields4
+      >,
+    ],
+  ): Promise<Result<TEntity4> | null>;
+
+  /**
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
+   * fold step, load an associated entity identified by a field value of the current fold value.
+   * @param loadDirectives - associated entity load directives instructing each step of the folds
+   */
+  async loadAssociatedEntityThroughAsync(
+    loadDirectives: EntityLoadThroughDirective<TViewerContext, any, any, any, any, any, any, any>[],
+  ): Promise<Result<ReadonlyEntity<any, any, any, any>> | null>;
+
+  async loadAssociatedEntityThroughAsync(
+    loadDirectives: EntityLoadThroughDirective<TViewerContext, any, any, any, any, any, any, any>[],
+  ): Promise<Result<ReadonlyEntity<any, any, any, any>> | null> {
+    let currentEntity: ReadonlyEntity<any, any, any, any> = this.entity;
+    for (const loadDirective of loadDirectives) {
+      const {
+        associatedEntityClass,
+        fieldIdentifyingAssociatedEntity,
+        associatedEntityLookupByField,
+      } = loadDirective;
+      let associatedEntityResult: Result<ReadonlyEntity<any, any, any, any>> | null;
+      if (associatedEntityLookupByField) {
+        associatedEntityResult = await currentEntity
+          .associationLoader(this.queryContext)
+          .withAuthorizationResults()
+          .loadAssociatedEntityByFieldEqualingAsync(
+            fieldIdentifyingAssociatedEntity,
+            associatedEntityClass,
+            associatedEntityLookupByField,
+          );
+      } else {
+        const associatedEntityResultLocal = await currentEntity
+          .associationLoader(this.queryContext)
+          .withAuthorizationResults()
+          .loadAssociatedEntityAsync(fieldIdentifyingAssociatedEntity, associatedEntityClass);
+
+        if (associatedEntityResultLocal.ok && associatedEntityResultLocal.value === null) {
+          associatedEntityResult = null;
+        } else {
+          associatedEntityResult = associatedEntityResultLocal;
+        }
+      }
+
+      if (!associatedEntityResult) {
+        return null;
+      }
+
+      if (!associatedEntityResult.ok) {
+        return result(associatedEntityResult.reason);
+      }
+      currentEntity = associatedEntityResult.value;
+    }
+    return result(currentEntity);
+  }
+}
+
+/**
+ * Instruction for each step of a load-associated-through method.
+ */
+export interface EntityLoadThroughDirective<
+  TViewerContext extends ViewerContext,
+  TFields,
+  TAssociatedFields extends object,
+  TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+  TAssociatedEntity extends ReadonlyEntity<
+    TAssociatedFields,
+    TAssociatedID,
+    TViewerContext,
+    TAssociatedSelectedFields
+  >,
+  TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
+    TAssociatedFields,
+    TAssociatedID,
+    TViewerContext,
+    TAssociatedEntity,
+    TAssociatedSelectedFields
+  >,
+  TSelectedFields extends keyof TFields = keyof TFields,
+  TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields,
+> {
+  /**
+   * Class of entity to load at this step.
+   */
+  associatedEntityClass: IEntityClass<
+    TAssociatedFields,
+    TAssociatedID,
+    TViewerContext,
+    TAssociatedEntity,
+    TAssociatedPrivacyPolicy,
+    TAssociatedSelectedFields
+  >;
+
+  /**
+   * Field of the current entity with which to load an instance of associatedEntityClass.
+   */
+  fieldIdentifyingAssociatedEntity: keyof Pick<TFields, TSelectedFields>;
+
+  /**
+   * Field by which to load the instance of associatedEntityClass. If not provided, the
+   * associatedEntityClass instance is fetched by its ID.
+   */
+  associatedEntityLookupByField?: keyof Pick<TAssociatedFields, TAssociatedSelectedFields>;
+}

package/src/AuthorizationResultBasedEntityLoader.ts

@@ -54,7 +54,7 @@ export default class AuthorizationResultBasedEntityLoader<
     >,
     private readonly dataManager: EntityDataManager<TFields>,
     protected readonly metricsAdapter: IEntityMetricsAdapter,
-    private readonly utils: EntityLoaderUtils<
+    public readonly utils: EntityLoaderUtils<
       TFields,
       TID,
       TViewerContext,
@@ -102,7 +102,7 @@ export default class AuthorizationResultBasedEntityLoader<
       entityResultsForFieldValue !== undefined,
       `${fieldValue} should be guaranteed to be present in returned map of entities`,
     );
-    return entityResultsForFieldValue!;
+    return entityResultsForFieldValue;
   }
 
   /**