enhance: Use getEntities with abstract interface return value

Author: ntucker

.changeset/proud-taxes-bake.md

@@ -3,10 +3,22 @@
 '@data-client/endpoint': minor
 ---
 
-delegate.getEntity(key) -> delegate.forEntities(key, cb)
+delegate.getEntity(key) -> delegate.getEntities(this.key)
 
+Return value is a restricted interface with keys() and entries() iterator methods.
 This applies to both schema.queryKey and schema.normalize method delegates.
 
+```ts
+const entities = delegate.getEntities(key);
+
+// foreach on keys
+for (const key of entities.keys()) {}
+// Object.keys() (convert to array)
+return [...entities.keys()];
+// foreach on full entry
+for (const [key, entity] of entities.entries()) {}
+```
+
 #### Before
 
 ```ts
@@ -21,8 +33,10 @@ if (entities)
 #### After
 
 ```ts
-delegate.forEntities(this.key, ([collectionKey]) => {
-  if (!filterCollections(JSON.parse(collectionKey))) return;
-  delegate.mergeEntity(this, collectionKey, normalizedValue);
-});
+const entities = delegate.getEntities(this.key);
+if (entities)
+  for (const collectionKey of entities.keys()) {
+    if (!filterCollections(JSON.parse(collectionKey))) continue;
+    delegate.mergeEntity(this, collectionKey, normalizedValue);
+  }
 ```

packages/endpoint/src/interface.ts

@@ -127,15 +127,12 @@ export interface CheckLoop {
   (entityKey: string, pk: string, input: object): boolean;
 }
 
-/** Return all entity PKs for a given entity key or INVALID if no entity entries */
-export interface GetEntityKeys {
-  (key: string): string[] | symbol;
+/** Interface specification for entities state accessor */
+export interface EntitiesInterface {
+  keys(): IterableIterator<string>;
+  entries(): IterableIterator<[string, any]>;
 }
 
-/** Loop over all entities of a given key */
-export interface ForEntities {
-  (key: string, callbackfn: (value: [string, unknown]) => void): boolean;
-}
 /** Get normalized Entity from store */
 export interface GetEntity {
   (key: string, pk: string): any;
@@ -148,10 +145,8 @@ export interface GetIndex {
 
 /** Accessors to the currently processing state while building query */
 export interface IQueryDelegate {
-  /** Return all entity PKs for a given entity key or INVALID if no entity entries */
-  getEntityKeys: GetEntityKeys;
-  /** Loop over all entities of a given key */
-  forEntities: ForEntities;
+  /** Get all entities for a given schema key */
+  getEntities(key: string): EntitiesInterface | undefined;
   /** Gets any previously normalized entity from store */
   getEntity: GetEntity;
   /** Get PK using an Entity Index */
@@ -164,10 +159,8 @@ export interface IQueryDelegate {
 export interface INormalizeDelegate {
   /** Action meta-data for this normalize call */
   readonly meta: { fetchedAt: number; date: number; expiresAt: number };
-  /** Return all entity PKs for a given entity key or INVALID if no entity entries */
-  getEntityKeys: GetEntityKeys;
-  /** Loop over all entities of a given key */
-  forEntities: ForEntities;
+  /** Get all entities for a given schema key */
+  getEntities(key: string): EntitiesInterface | undefined;
   /** Gets any previously normalized entity from store */
   getEntity: GetEntity;
   /** Updates an entity using merge lifecycles when it has previously been set */

packages/endpoint/src/schemas/All.ts

@@ -1,6 +1,11 @@
 import ArraySchema from './Array.js';
 import { IQueryDelegate, Visit } from '../interface.js';
-import { EntityInterface, EntityMap, SchemaFunction } from '../schema.js';
+import {
+  Entity,
+  EntityInterface,
+  EntityMap,
+  SchemaFunction,
+} from '../schema.js';
 
 /**
  * Retrieves all entities in cache
@@ -26,23 +31,25 @@ export default class AllSchema<
 
   queryKey(args: any, unvisit: any, delegate: IQueryDelegate): any {
     if (this.isSingleSchema) {
-      return delegate.getEntityKeys(this.schema.key);
+      const entities = delegate.getEntities(this.schema.key);
+      if (!entities) return delegate.INVALID;
+      return [...entities.keys()];
     }
     let found = false;
     const list = Object.values(this.schema as Record<string, any>).flatMap(
       (schema: EntityInterface) => {
-        const entities: any[] = [];
-        if (
-          delegate.forEntities(schema.key, ([pk, entity]) => {
-            if (!entity) return;
-            entities.push({
-              id: schema.pk(entity, undefined, pk, []),
-              schema: this.getSchemaAttribute(entity, undefined, pk),
-            });
-          })
-        )
-          found = true;
-        return entities;
+        const entities = delegate.getEntities(schema.key);
+        if (!entities) return [];
+        found = true;
+        const normEntities: any[] = [];
+        for (const [key, entity] of entities.entries()) {
+          if (!entity) continue;
+          normEntities.push({
+            id: schema.pk(entity, undefined, key, []),
+            schema: this.getSchemaAttribute(entity, undefined, key),
+          });
+        }
+        return normEntities;
       },
     );
     // we need at least one table entry of the Union for this to count as Valid.

packages/endpoint/src/schemas/Collection.ts

@@ -326,13 +326,12 @@ function normalizeCreate(
   // parent is args when not nested
   const filterCollections = (this.createCollectionFilter as any)(...args);
   // add to any collections that match this
-  const keys = delegate.getEntityKeys(this.key);
-  if (typeof keys !== 'symbol') {
-    keys.forEach(collectionKey => {
-      if (!filterCollections(JSON.parse(collectionKey))) return;
+  const entities = delegate.getEntities(this.key);
+  if (entities)
+    for (const collectionKey of entities.keys()) {
+      if (!filterCollections(JSON.parse(collectionKey))) continue;
       delegate.mergeEntity(this, collectionKey, normalizedValue);
-    });
-  }
+    }
   return normalizedValue as any;
 }
 

packages/endpoint/src/schemas/__tests__/All.test.ts

@@ -204,17 +204,16 @@ describe.each([
       class Cat extends IDEntity {}
       (Cat as any).defaults;
       const catSchema = { results: new schema.All(Cat), nextPage: '' };
-      let state: State<unknown> = {
+      let state: State<unknown> = createInput({
         ...initialState,
         entities: {
           Cat: {
-            1: { id: '1', name: 'Milo' },
-            2: { id: '2', name: 'Jake' },
+            '1': { id: '1', name: 'Milo' },
+            '2': { id: '2', name: 'Jake' },
           },
         },
-        indexes: {},
-      };
-      const memo = new MemoCache();
+      }) as any;
+      const memo = new MemoCache(MyDelegate);
       const value = memo.query(catSchema, [], state).data;
 
       expect(createOutput(value).results?.length).toBe(2);
@@ -225,16 +224,27 @@ describe.each([
       );
       expect(value).toBe(value2);
 
-      state = {
-        ...state,
-        entities: {
-          ...state.entities,
-          Cat: {
-            ...state.entities.Cat,
-            3: { id: '3', name: 'Jelico' },
+      if (ImmDelegate === MyDelegate) {
+        state = {
+          ...state,
+          entities: (state.entities as any).setIn(['Cat', '3'], {
+            id: '3',
+            name: 'Jelico',
+          }),
+        } as any;
+      } else {
+        state = {
+          ...state,
+          entities: {
+            ...state.entities,
+            Cat: {
+              ...state.entities.Cat,
+              '3': { id: '3', name: 'Jelico' },
+            },
           },
-        },
-      };
+        } as any;
+      }
+
       const value3 = memo.query(catSchema, [], state).data;
       expect(createOutput(value3).results?.length).toBe(3);
       expect(createOutput(value3).results).toMatchSnapshot();

packages/endpoint/src/schemas/__tests__/Object.test.js

@@ -8,6 +8,7 @@ import { Temporal } from '@js-temporal/polyfill';
 import { IDEntity } from '__tests__/new';
 import { fromJS, Map } from 'immutable';
 
+import { fromJSEntities } from './denormalize';
 import { schema } from '../../';
 import Entity from '../Entity';
 
@@ -22,10 +23,6 @@ afterAll(() => {
   dateSpy.mockRestore();
 });
 
-function fromJSEntities(entities) {
-  return Map(entities).map(v => Map(v));
-}
-
 describe(`${schema.Object.name} normalization`, () => {
   test('normalizes an object', () => {
     class User extends IDEntity {}

packages/normalizr/src/delegate/BaseDelegate.ts

@@ -2,8 +2,8 @@ import { INVALID } from '../denormalize/symbol.js';
 import type {
   QueryPath,
   IndexPath,
-  EntitiesPath,
   IQueryDelegate,
+  EntitiesInterface,
 } from '../interface.js';
 import type { Dep } from '../memo/WeakDependencyMap.js';
 
@@ -17,19 +17,15 @@ export abstract class BaseDelegate {
     this.indexes = indexes;
   }
 
-  abstract forEntities(
-    key: string,
-    callbackfn: (value: [string, unknown]) => void,
-  ): boolean;
-
-  // we must expose the entities object to track in our WeakDependencyMap
-  // however, this should not be part of the public API
-  protected abstract getEntities(key: string): object | undefined;
-  abstract getEntityKeys(key: string): string[] | symbol;
+  abstract getEntities(key: string): EntitiesInterface | undefined;
   abstract getEntity(key: string, pk: string): object | undefined;
   abstract getIndex(...path: IndexPath): object | undefined;
   abstract getIndexEnd(entity: any, value: string): string | undefined;
+  // we must expose the entities object to track in our WeakDependencyMap
+  // however, this should not be part of the public API
+  protected abstract getEntitiesObject(key: string): object | undefined;
 
+  // only used in buildQueryKey
   tracked(
     schema: any,
   ): [delegate: IQueryDelegate, dependencies: Dep<QueryPath>[]] {
@@ -48,19 +44,10 @@ export abstract class BaseDelegate {
         dependencies.push({ path, entity });
         return entity;
       },
-      forEntities(
-        key: string,
-        callbackfn: (value: [string, any]) => void,
-      ): boolean {
-        const entity = base.getEntities(key);
-        // always push even if entity is undefined
-        dependencies.push({ path: [key], entity });
-        return base.forEntities(key, callbackfn);
-      },
-      getEntityKeys(key: string): string[] | symbol {
-        const entity = base.getEntities(key);
+      getEntities(key: string): EntitiesInterface | undefined {
+        const entity = base.getEntitiesObject(key);
         dependencies.push({ path: [key], entity });
-        return base.getEntityKeys(key);
+        return base.getEntities(key);
       },
     };
     return [delegate, dependencies];

packages/normalizr/src/delegate/Delegate.imm.ts

@@ -1,16 +1,8 @@
 import { BaseDelegate } from './BaseDelegate.js';
-import { INVALID } from '../denormalize/symbol.js';
+import { EntitiesInterface } from '../interface.js';
 
 export type ImmutableJSEntityTable = {
-  get(key: string):
-    | {
-        forEach(
-          sideEffect: (value: any, key: string, iter: any) => unknown,
-          context?: unknown,
-        ): number;
-        keySeq(): { toArray(): string[] };
-      }
-    | undefined;
+  get(key: string): EntitiesInterface | undefined;
   getIn(k: [key: string, pk: string]): { toJS(): any } | undefined;
   setIn(k: [key: string, pk: string], value: any);
 };
@@ -27,33 +19,13 @@ export class ImmDelegate extends BaseDelegate {
     super(state);
   }
 
-  forEntities(
-    key: string,
-    callbackfn: (value: [string, unknown]) => void,
-  ): boolean {
-    const entities = this.getEntities(key);
-    if (!entities) return false;
-    entities.forEach((entity: any, pk: string) => {
-      callbackfn([pk, entity]);
-    });
-    return true;
-  }
-
-  getEntityKeys(key: string): string[] | symbol {
-    const entities = this.getEntities(key);
-    if (entities === undefined) return INVALID;
-    return entities.keySeq().toArray();
+  // we must expose the entities object to track in our WeakDependencyMap
+  // however, this should not be part of the public API
+  protected getEntitiesObject(key: string): object | undefined {
+    return this.entities.get(key);
   }
 
-  protected getEntities(key: string):
-    | {
-        forEach(
-          sideEffect: (value: any, key: string, iter: any) => unknown,
-          context?: unknown,
-        ): number;
-        keySeq(): { toArray(): string[] };
-      }
-    | undefined {
+  getEntities(key: string): EntitiesInterface | undefined {
     return this.entities.get(key);
   }