feat: add loadManyByIDsNullableAsync loader method

packages/entity/src/EnforcingEntityLoader.ts

@@ -114,6 +114,15 @@ export default class EnforcingEntityLoader<
     return mapMap(entityResults, (result) => result.enforceValue());
   }
 
+  /**
+   * Enforcing version of entity loader method by the same name.
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
+   */
+  async loadManyByIDsNullableAsync(ids: readonly TID[]): Promise<ReadonlyMap<TID, TEntity | null>> {
+    const entityResults = await this.entityLoader.loadManyByIDsNullableAsync(ids);
+    return mapMap(entityResults, (result) => result?.enforceValue() ?? null);
+  }
+
   /**
    * Enforcing version of entity loader method by the same name.
    * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities

packages/entity/src/EntityLoader.ts

@@ -185,6 +185,23 @@
     });
   }
 
+  /**
+   * Loads many entities for a list of IDs, returning null for any IDs that are non-existent.
+   * @param ids - IDs of the entities to load
+   * @returns map from ID to nullable corresponding entity result, where result error can be UnauthorizedError or EntityNotFoundError.
+   */
+  async loadManyByIDsNullableAsync(
+    ids: readonly TID[]
+  ): Promise<ReadonlyMap<TID, Result<TEntity> | null>> {
+    const entityResults = (await this.loadManyByFieldEqualingManyAsync(
+      this.entityConfiguration.idField as TSelectedFields,
+      ids
+    )) as ReadonlyMap<TID, readonly Result<TEntity>[]>;
+    return mapMap(entityResults, (entityResultsForId) => {
+      return entityResultsForId[0] ?? null;
+    });
+  }
+
   /**
    * Loads the first entity matching the selection constructed from the conjunction of specified
    * operands, or null if no matching entity exists. Entities loaded using this method are not

packages/entity/src/__tests__/EnforcingEntityLoader-test.ts

@@ -222,6 +222,49 @@ describe(EnforcingEntityLoader, () => {
     });
   });
 
+  describe('loadManyByIDsNullableAsync', () => {
+    it('throws when result is unsuccessful even when there is a null result', async () => {
+      const entityLoaderMock = mock<EntityLoader<any, any, any, any, any, any>>(EntityLoader);
+      const rejection = new Error();
+      when(entityLoaderMock.loadManyByIDsNullableAsync(anything())).thenResolve(
+        new Map(
+          Object.entries({
+            hello: result(rejection),
+            world: null,
+          })
+        )
+      );
+      const entityLoader = instance(entityLoaderMock);
+      const enforcingEntityLoader = new EnforcingEntityLoader(entityLoader);
+      await expect(enforcingEntityLoader.loadManyByIDsNullableAsync(anything())).rejects.toThrow(
+        rejection
+      );
+    });
+
+    it('returns value when result is successful', async () => {
+      const entityLoaderMock = mock<EntityLoader<any, any, any, any, any, any>>(EntityLoader);
+      const resolved = {};
+      when(entityLoaderMock.loadManyByIDsNullableAsync(anything())).thenResolve(
+        new Map(
+          Object.entries({
+            hello: result(resolved),
+            world: null,
+          })
+        )
+      );
+      const entityLoader = instance(entityLoaderMock);
+      const enforcingEntityLoader = new EnforcingEntityLoader(entityLoader);
+      await expect(enforcingEntityLoader.loadManyByIDsNullableAsync(anything())).resolves.toEqual(
+        new Map(
+          Object.entries({
+            hello: resolved,
+            world: null,
+          })
+        )
+      );
+    });
+  });
+
   describe('loadFirstByFieldEqualityConjunction', () => {
     it('throws when result is unsuccessful', async () => {
       const entityLoaderMock = mock<EntityLoader<any, any, any, any, any, any>>(EntityLoader);

packages/entity/src/__tests__/EntityLoader-test.ts

@@ -538,7 +538,11 @@ describe(EntityLoader, () => {
     await expect(entityLoader.loadByIDAsync(loadByValue)).rejects.toEqual(error);
     await expect(entityLoader.enforcing().loadByIDAsync(loadByValue)).rejects.toEqual(error);
     await expect(entityLoader.loadManyByIDsAsync([loadByValue])).rejects.toEqual(error);
-    await expect(entityLoader.loadManyByIDsAsync([loadByValue])).rejects.toEqual(error);
+    await expect(entityLoader.enforcing().loadManyByIDsAsync([loadByValue])).rejects.toEqual(error);
+    await expect(entityLoader.loadManyByIDsNullableAsync([loadByValue])).rejects.toEqual(error);
+    await expect(
+      entityLoader.enforcing().loadManyByIDsNullableAsync([loadByValue])
+    ).rejects.toEqual(error);
     await expect(
       entityLoader.loadManyByFieldEqualingAsync('customIdField', loadByValue)
     ).rejects.toEqual(error);