@data-client/core 0.14.18 → 0.14.19

package/src/controller/Controller.ts

@@ -35,17 +35,23 @@ import {
 } from './actions/index.js';
 import ensurePojo from './ensurePojo.js';
 import type { EndpointUpdateFunction } from './types.js';
+import { ReduxMiddlewareAPI } from '../manager/applyManager.js';
+import type { GCInterface } from '../state/GCPolicy.js';
+import { ImmortalGCPolicy } from '../state/GCPolicy.js';
 import { initialState } from '../state/reducer/createReducer.js';
 import selectMeta from '../state/selectMeta.js';
-import type { ActionTypes, State } from '../types.js';
+import type { ActionTypes, Dispatch, State } from '../types.js';
 
 export type GenericDispatch = (value: any) => Promise<void>;
 export type DataClientDispatch = (value: ActionTypes) => Promise<void>;
 
-interface ConstructorProps<D extends GenericDispatch = DataClientDispatch> {
+export interface ControllerConstructorProps<
+  D extends GenericDispatch = DataClientDispatch,
+> {
   dispatch?: D;
   getState?: () => State<unknown>;
   memo?: Pick<MemoCache, 'denormalize' | 'query' | 'buildQueryKey'>;
+  gcPolicy?: GCInterface;
 }
 
 const unsetDispatch = (action: unknown): Promise<void> => {
@@ -65,6 +71,7 @@ const unsetState = (): State<unknown> => {
  * @see https://dataclient.io/docs/api/Controller
  */
 export default class Controller<
+  // NOTE: We template on entire dispatch, so we can be contravariant on ActionTypes
   D extends GenericDispatch = DataClientDispatch,
 > {
   /**
@@ -72,7 +79,7 @@ export default class Controller<
    *
    * @see https://dataclient.io/docs/api/Controller#dispatch
    */
-  declare readonly dispatch: D;
+  declare protected _dispatch: D;
   /**
    * Gets the latest state snapshot that is fully committed.
    *
@@ -80,7 +87,7 @@ export default class Controller<
    * This should *not* be used to render; instead useSuspense() or useCache()
    * @see https://dataclient.io/docs/api/Controller#getState
    */
-  declare readonly getState: () => State<unknown>;
+  declare getState: () => State<unknown>;
   /**
    * Singleton to maintain referential equality between calls
    */
@@ -89,14 +96,43 @@ export default class Controller<
     'denormalize' | 'query' | 'buildQueryKey'
   >;
 
+  /**
+   * Handles garbage collection
+   */
+  declare readonly gcPolicy: GCInterface;
+
   constructor({
     dispatch = unsetDispatch as any,
     getState = unsetState,
     memo = new MemoCache(),
-  }: ConstructorProps<D> = {}) {
-    this.dispatch = dispatch;
+    gcPolicy = new ImmortalGCPolicy(),
+  }: ControllerConstructorProps<D> = {}) {
+    this._dispatch = dispatch;
     this.getState = getState;
     this.memo = memo;
+    this.gcPolicy = gcPolicy;
+  }
+
+  // TODO: drop when drop support for destructuring (0.14 and below)
+  set dispatch(dispatch: D) {
+    /* istanbul ignore next */
+    this._dispatch = dispatch;
+  }
+
+  // TODO: drop when drop support for destructuring (0.14 and below)
+  get dispatch(): D {
+    return this._dispatch;
+  }
+
+  bindMiddleware({
+    dispatch,
+    getState,
+  }: {
+    dispatch: D;
+    getState: ReduxMiddlewareAPI['getState'];
+  }) {
+    this._dispatch = dispatch;
+    this.getState = getState;
   }
 
   /*************** Action Dispatchers ***************/
@@ -336,7 +372,7 @@ export default class Controller<
    * Gets a snapshot (https://dataclient.io/docs/api/Snapshot)
    * @see https://dataclient.io/docs/api/Controller#snapshot
    */
-  snapshot = (state: State<unknown>, fetchedAt?: number): SnapshotInterface => {
+  snapshot = (state: State<unknown>, fetchedAt?: number): Snapshot<unknown> => {
     return new Snapshot(this, state, fetchedAt);
   };
 
@@ -389,6 +425,7 @@ export default class Controller<
     data: DenormalizeNullable<E['schema']>;
     expiryStatus: ExpiryStatus;
     expiresAt: number;
+    countRef: () => () => void;
   };
 
   getResponse<
@@ -403,6 +440,7 @@ export default class Controller<
     data: DenormalizeNullable<E['schema']>;
     expiryStatus: ExpiryStatus;
     expiresAt: number;
+    countRef: () => () => void;
   };
 
   getResponse(
@@ -412,6 +450,51 @@ export default class Controller<
     data: unknown;
     expiryStatus: ExpiryStatus;
     expiresAt: number;
+    countRef: () => () => void;
+  } {
+    // TODO: breaking: only return data
+    return this.getResponseMeta(endpoint, ...rest);
+  }
+
+  /**
+   * Gets the (globally referentially stable) response for a given endpoint/args pair from state given.
+   * @see https://dataclient.io/docs/api/Controller#getResponseMeta
+   */
+  getResponseMeta<E extends EndpointInterface>(
+    endpoint: E,
+    ...rest:
+      | readonly [null, State<unknown>]
+      | readonly [...Parameters<E>, State<unknown>]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+    countRef: () => () => void;
+  };
+
+  getResponseMeta<
+    E extends Pick<EndpointInterface, 'key' | 'schema' | 'invalidIfStale'>,
+  >(
+    endpoint: E,
+    ...rest: readonly [
+      ...(readonly [...Parameters<E['key']>] | readonly [null]),
+      State<unknown>,
+    ]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+    countRef: () => () => void;
+  };
+
+  getResponseMeta(
+    endpoint: EndpointInterface,
+    ...rest: readonly [...unknown[], State<unknown>]
+  ): {
+    data: unknown;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+    countRef: () => () => void;
   } {
     const state = rest[rest.length - 1] as State<unknown>;
     // this is typescript generics breaking
@@ -446,12 +529,14 @@ export default class Controller<
         data: input as any,
         expiryStatus: ExpiryStatus.Valid,
         expiresAt: Infinity,
+        countRef: () => () => undefined,
       };
     }
 
     let isInvalid = false;
     if (shouldQuery) {
       isInvalid = !validateQueryKey(input);
+      // endpoint without entities
     } else if (!schema || !schemaHasEntity(schema)) {
       return {
         data: cacheEndpoints,
@@ -460,6 +545,7 @@ export default class Controller<
           : cacheEndpoints && !endpoint.invalidIfStale ? ExpiryStatus.Valid
           : ExpiryStatus.InvalidIfStale,
         expiresAt: expiresAt || 0,
+        countRef: this.gcPolicy.createCountRef({ key }),
       };
     }
 
@@ -477,6 +563,7 @@ export default class Controller<
 
     return this.getSchemaResponse(
       data,
+      key,
       paths,
       state.entityMeta,
       expiresAt,
@@ -505,8 +592,55 @@ export default class Controller<
     return this.memo.query(schema, args, state.entities as any, state.indexes);
   }
 
+  /**
+   * Queries the store for a Querable schema; providing related metadata
+   * @see https://dataclient.io/docs/api/Controller#getQueryMeta
+   */
+  getQueryMeta<S extends Queryable>(
+    schema: S,
+    ...rest: readonly [
+      ...SchemaArgs<S>,
+      Pick<State<unknown>, 'entities' | 'entityMeta'>,
+    ]
+  ): {
+    data: DenormalizeNullable<S> | undefined;
+    countRef: () => () => void;
+  } {
+    const state = rest[rest.length - 1] as State<any>;
+    // this is typescript generics breaking
+    const args: any = rest
+      .slice(0, rest.length - 1)
+      .map(ensurePojo) as SchemaArgs<S>;
+
+    // TODO: breaking: Switch back to this.memo.query(schema, args, state.entities as any, state.indexes) to do
+    // this logic
+    const input = this.memo.buildQueryKey(
+      schema,
+      args,
+      state.entities as any,
+      state.indexes,
+      JSON.stringify(args),
+    );
+
+    if (!input) {
+      return { data: undefined, countRef: () => () => undefined };
+    }
+
+    const { data, paths } = this.memo.denormalize(
+      schema,
+      input,
+      state.entities,
+      args,
+    );
+    return {
+      data: typeof data === 'symbol' ? undefined : (data as any),
+      countRef: this.gcPolicy.createCountRef({ paths }),
+    };
+  }
+
   private getSchemaResponse<T>(
     data: T,
+    key: string,
     paths: EntityPath[],
     entityMeta: State<unknown>['entityMeta'],
     expiresAt: number,
@@ -516,6 +650,7 @@ export default class Controller<
     data: T;
     expiryStatus: ExpiryStatus;
     expiresAt: number;
+    countRef: () => () => void;
   } {
     const invalidDenormalize = typeof data === 'symbol';
 
@@ -533,7 +668,12 @@ export default class Controller<
       : invalidDenormalize || invalidIfStale ? ExpiryStatus.InvalidIfStale
       : ExpiryStatus.Valid;
 
-    return { data, expiryStatus, expiresAt };
+    return {
+      data,
+      expiryStatus,
+      expiresAt,
+      countRef: this.gcPolicy.createCountRef({ key, paths }),
+    };
   }
 }
 
@@ -639,6 +779,49 @@ class Snapshot<T = unknown> implements SnapshotInterface {
     return this.controller.getResponse(endpoint, ...args, this.state);
   }
 
+  /** @see https://dataclient.io/docs/api/Snapshot#getResponseMeta */
+  getResponseMeta<E extends EndpointInterface>(
+    endpoint: E,
+    ...args: readonly [null]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  };
+
+  getResponseMeta<E extends EndpointInterface>(
+    endpoint: E,
+    ...args: readonly [...Parameters<E>]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  };
+
+  getResponseMeta<
+    E extends Pick<EndpointInterface, 'key' | 'schema' | 'invalidIfStale'>,
+  >(
+    endpoint: E,
+    ...args: readonly [...Parameters<E['key']>] | readonly [null]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  };
+
+  getResponseMeta<
+    E extends Pick<EndpointInterface, 'key' | 'schema' | 'invalidIfStale'>,
+  >(
+    endpoint: E,
+    ...args: readonly [...Parameters<E['key']>] | readonly [null]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  } {
+    return this.controller.getResponseMeta(endpoint, ...args, this.state);
+  }
+
   /** @see https://dataclient.io/docs/api/Snapshot#getError */
   getError<E extends EndpointInterface>(
     endpoint: E,
@@ -667,4 +850,18 @@ class Snapshot<T = unknown> implements SnapshotInterface {
   ): DenormalizeNullable<S> | undefined {
     return this.controller.get(schema, ...args, this.state);
   }
+
+  /**
+   * Queries the store for a Querable schema; providing related metadata
+   * @see https://dataclient.io/docs/api/Snapshot#getQueryMeta
+   */
+  getQueryMeta<S extends Queryable>(
+    schema: S,
+    ...args: SchemaArgs<S>
+  ): {
+    data: DenormalizeNullable<S> | undefined;
+    countRef: () => () => void;
+  } {
+    return this.controller.getQueryMeta(schema, ...args, this.state);
+  }
 }

package/src/controller/__tests__/Controller.ts

@@ -50,19 +50,21 @@ describe('Controller', () => {
         meta: {
           [fetchKey]: {
             date: Date.now(),
+            fetchedAt: Date.now(),
             expiresAt: Date.now() + 10000,
           },
         },
       };
       const getState = () => state;
+      const dispatch = jest.fn(() => Promise.resolve());
       const controller = new Controller({
-        dispatch: jest.fn(() => Promise.resolve()),
+        dispatch,
         getState,
       });
       const article = await controller.fetchIfStale(CoolerArticleResource.get, {
         id: payload.id,
       });
-      expect(controller.dispatch.mock.calls.length).toBe(0);
+      expect(dispatch.mock.calls.length).toBe(0);
       expect(article.title).toBe(payload.title);
     });
     it('should fetch if result stale', () => {
@@ -87,20 +89,22 @@ describe('Controller', () => {
         meta: {
           [fetchKey]: {
             date: 0,
+            fetchedAt: 0,
             expiresAt: 0,
           },
         },
       };
       const getState = () => state;
+      const dispatch = jest.fn(() => Promise.resolve());
       const controller = new Controller({
-        dispatch: jest.fn(() => Promise.resolve()),
+        dispatch,
         getState,
       });
       controller.fetchIfStale(CoolerArticleResource.get, {
         id: payload.id,
       });
 
-      expect(controller.dispatch.mock.calls.length).toBe(1);
+      expect(dispatch.mock.calls.length).toBe(1);
     });
   });
 });

package/src/controller/__tests__/__snapshots__/get.ts.snap

@@ -118,3 +118,10 @@ Tacos {
   "type": "foo",
 }
 `;
+
+exports[`Snapshot.getQueryMeta() query Entity based on pk 1`] = `
+Tacos {
+  "id": "1",
+  "type": "foo",
+}
+`;

package/src/controller/__tests__/__snapshots__/getResponse.ts.snap

@@ -33,3 +33,18 @@ exports[`Controller.getResponse() infers schema with extra members but not set 1
   },
 }
 `;
+
+exports[`Snapshot.getResponseMeta() denormalizes schema with extra members but not set 1`] = `
+{
+  "data": [
+    Tacos {
+      "id": "1",
+      "type": "foo",
+    },
+    Tacos {
+      "id": "2",
+      "type": "bar",
+    },
+  ],
+}
+`;

package/src/controller/__tests__/get.ts

@@ -3,24 +3,24 @@ import { Entity, schema } from '@data-client/endpoint';
 import { initialState } from '../../state/reducer/createReducer';
 import Controller from '../Controller';
 
-describe('Controller.get()', () => {
-  class Tacos extends Entity {
-    type = '';
-    id = '';
-  }
-  const TacoList = new schema.Collection([Tacos]);
-  const entities = {
-    Tacos: {
-      1: { id: '1', type: 'foo' },
-      2: { id: '2', type: 'bar' },
-    },
-    [TacoList.key]: {
-      [TacoList.pk(undefined, undefined, '', [{ type: 'foo' }])]: ['1'],
-      [TacoList.pk(undefined, undefined, '', [{ type: 'bar' }])]: ['2'],
-      [TacoList.pk(undefined, undefined, '', [])]: ['1', '2'],
-    },
-  };
+class Tacos extends Entity {
+  type = '';
+  id = '';
+}
+const TacoList = new schema.Collection([Tacos]);
+const entities = {
+  Tacos: {
+    1: { id: '1', type: 'foo' },
+    2: { id: '2', type: 'bar' },
+  },
+  [TacoList.key]: {
+    [TacoList.pk(undefined, undefined, '', [{ type: 'foo' }])]: ['1'],
+    [TacoList.pk(undefined, undefined, '', [{ type: 'bar' }])]: ['2'],
+    [TacoList.pk(undefined, undefined, '', [])]: ['1', '2'],
+  },
+};
 
+describe('Controller.get()', () => {
   it('query Entity based on pk', () => {
     const controller = new Controller();
     const state = {
@@ -273,3 +273,31 @@ describe('Controller.get()', () => {
     () => controller.get(queryPerson, { id: '1', doesnotexist: 5 }, state);
   });
 });
+
+describe('Snapshot.getQueryMeta()', () => {
+  it('query Entity based on pk', () => {
+    const controller = new Controller();
+    const state = {
+      ...initialState,
+      entities,
+    };
+    const snapshot = controller.snapshot(state);
+    const taco = snapshot.getQueryMeta(Tacos, { id: '1' }).data;
+    expect(taco).toBeDefined();
+    expect(taco).toBeInstanceOf(Tacos);
+    expect(taco).toMatchSnapshot();
+    const taco2 = snapshot.getQueryMeta(Tacos, { id: '2' }).data;
+    expect(taco2).toBeDefined();
+    expect(taco2).toBeInstanceOf(Tacos);
+    expect(taco2).not.toEqual(taco);
+    // should maintain referential equality
+    expect(taco).toBe(snapshot.getQueryMeta(Tacos, { id: '1' }).data);
+
+    // @ts-expect-error
+    () => snapshot.getQueryMeta(Tacos, { id: { bob: 5 } });
+    // @ts-expect-error
+    expect(snapshot.getQueryMeta(Tacos, 5).data).toBeUndefined();
+    // @ts-expect-error
+    () => snapshot.getQueryMeta(Tacos, { doesnotexist: 5 });
+  });
+});

package/src/controller/__tests__/getResponse.ts

@@ -174,3 +174,49 @@ describe('Controller.getResponse()', () => {
     expect(second.expiresAt).toBe(expiresAt);
   });
 });
+
+describe('Snapshot.getResponseMeta()', () => {
+  it('denormalizes schema with extra members but not set', () => {
+    const controller = new Contoller();
+    class Tacos extends Entity {
+      type = '';
+      id = '';
+    }
+    const ep = new Endpoint(() => Promise.resolve(), {
+      key() {
+        return 'mytest';
+      },
+      schema: {
+        data: [Tacos],
+        extra: '',
+        page: {
+          first: null,
+          second: undefined,
+          third: 0,
+          complex: { complex: true, next: false },
+        },
+      },
+    });
+    const entities = {
+      Tacos: {
+        1: { id: '1', type: 'foo' },
+        2: { id: '2', type: 'bar' },
+      },
+    };
+
+    const state = {
+      ...initialState,
+      entities,
+      endpoints: {
+        [ep.key()]: {
+          data: ['1', '2'],
+        },
+      },
+    };
+    const { data, expiryStatus } = controller
+      .snapshot(state)
+      .getResponseMeta(ep);
+    expect(expiryStatus).toBe(ExpiryStatus.Valid);
+    expect(data).toMatchSnapshot();
+  });
+});

package/src/index.ts

@@ -1,9 +1,3 @@
-Object.hasOwn =
-  Object.hasOwn ||
-  /* istanbul ignore next */ function hasOwn(it, key) {
-    return Object.prototype.hasOwnProperty.call(it, key);
-  };
-
 export * as __INTERNAL__ from './internal.js';
 export type {
   NetworkError,
@@ -29,11 +23,13 @@ export {
   default as NetworkManager,
   ResetError,
 } from './manager/NetworkManager.js';
+export * from './state/GCPolicy.js';
 export {
   default as createReducer,
   initialState,
 } from './state/reducer/createReducer.js';
 export { default as applyManager } from './manager/applyManager.js';
+export { default as initManager } from './manager/initManager.js';
 
 export { default as Controller } from './controller/Controller.js';
 export type {

package/src/manager/SubscriptionManager.ts

@@ -2,7 +2,6 @@ import { SUBSCRIBE, UNSUBSCRIBE } from '../actionTypes.js';
 import Controller from '../controller/Controller.js';
 import type {
   Manager,
-  MiddlewareAPI,
   Middleware,
   UnsubscribeAction,
   SubscribeAction,

package/src/manager/applyManager.ts

@@ -18,14 +18,13 @@ export default function applyManager(
   }
   return managers.map((manager, i) => {
     if (!manager.middleware) manager.middleware = manager.getMiddleware?.();
-    return ({ dispatch, getState }) => {
+    return (api: ReduxMiddlewareAPI) => {
       if (i === 0) {
-        (controller as any).dispatch = dispatch;
-        (controller as any).getState = getState;
+        controller.bindMiddleware(api);
       }
       // controller is a superset of the middleware API
       return (manager as Manager & { middleware: ReduxMiddleware }).middleware(
-        controller as Controller<any>,
+        controller as any,
       );
     };
   });

package/src/manager/initManager.ts

@@ -0,0 +1,21 @@
+import type Controller from '../controller/Controller.js';
+import { Manager, State } from '../types.js';
+
+export default function initManager(
+  managers: Manager[],
+  controller: Controller,
+  initialState: State<unknown>,
+) {
+  return () => {
+    managers.forEach(manager => {
+      manager.init?.(initialState);
+    });
+    controller.gcPolicy.init(controller);
+    return () => {
+      managers.forEach(manager => {
+        manager.cleanup();
+      });
+      controller.gcPolicy.cleanup();
+    };
+  };
+}