feat: useQuery

examples/benchmark/core.js

@@ -6,6 +6,7 @@ import {
   Endpoint,
   Entity,
   normalize,
+  WeakEntityMap,
 } from './dist/index.js';
 import { printStatus } from './printStatus.js';
 import {
@@ -113,6 +114,9 @@ export default function addReducerSuite(suite) {
         controller.globalCache = {
           entities: {},
           results: {},
+          queries: new Map(),
+          inputEndpointCache: {},
+          infer: new WeakEntityMap(),
         };
         return controller.getResponse(getProject, cachedState);
       })

packages/core/src/controller/Controller.ts

@@ -1,9 +1,11 @@
 import type {
   ErrorTypes,
   SnapshotInterface,
-  DenormalizeCache,
   Schema,
   Denormalize,
+  Queryable,
+  SchemaArgs,
+  ResultCache,
 } from '@data-client/normalizr';
 import {
   WeakEntityMap,
@@ -33,7 +35,7 @@ import ensurePojo from './ensurePojo.js';
 import type { EndpointUpdateFunction } from './types.js';
 import { initialState } from '../state/reducer/createReducer.js';
 import selectMeta from '../state/selectMeta.js';
-import type { ActionTypes, State } from '../types.js';
+import type { ActionTypes, State, DenormalizeCache } from '../types.js';
 
 export type GenericDispatch = (value: any) => Promise<void>;
 export type DataClientDispatch = (value: ActionTypes) => Promise<void>;
@@ -85,6 +87,9 @@ export default class Controller<
     globalCache = {
       entities: {},
       results: {},
+      queries: new Map(),
+      inputEndpointCache: {},
+      infer: new WeakEntityMap(),
     },
   }: ConstructorProps<D> = {}) {
     this.dispatch = dispatch;
@@ -335,21 +340,42 @@ export default class Controller<
    * Gets the (globally referentially stable) response for a given endpoint/args pair from state given.
    * @see https://dataclient.io/docs/api/Controller#getResponse
    */
-  getResponse = <
+  getResponse<E extends EndpointInterface>(
+    endpoint: E,
+    ...rest: readonly [null, State<unknown>]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  };
+
+  getResponse<E extends EndpointInterface>(
+    endpoint: E,
+    ...rest: readonly [...Parameters<E>, State<unknown>]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  };
+
+  getResponse<
     E extends Pick<EndpointInterface, 'key' | 'schema' | 'invalidIfStale'>,
-    Args extends readonly [...Parameters<E['key']>] | readonly [null],
   >(
     endpoint: E,
-    ...rest: [...Args, State<unknown>]
+    ...rest: readonly [
+      ...(readonly [...Parameters<E['key']>] | readonly [null]),
+      State<unknown>,
+    ]
   ): {
     data: DenormalizeNullable<E['schema']>;
     expiryStatus: ExpiryStatus;
     expiresAt: number;
-  } => {
+  } {
     const state = rest[rest.length - 1] as State<unknown>;
     // this is typescript generics breaking
     const args: any = rest
       .slice(0, rest.length - 1)
+      // handle FormData
       .map(ensurePojo) as Parameters<E['key']>;
     const isActive = args.length !== 1 || args[0] !== null;
     const key = isActive ? endpoint.key(...args) : '';
@@ -360,17 +386,25 @@ export default class Controller<
 
     let invalidResults = false;
     let results;
+    let resultCache: ResultCache;
     if (cacheResults === undefined && endpoint.schema !== undefined) {
-      results = inferResults(
-        endpoint.schema,
-        args,
-        state.indexes,
-        state.entities,
-      );
+      if (!this.globalCache.inputEndpointCache[key])
+        this.globalCache.inputEndpointCache[key] = inferResults(
+          endpoint.schema,
+          args,
+          state.indexes,
+          state.entities,
+        );
+      results = this.globalCache.inputEndpointCache[key];
+
       invalidResults = !validateInference(results);
       if (!expiresAt && invalidResults) expiresAt = 1;
+      resultCache = this.globalCache.infer;
     } else {
       results = cacheResults;
+      if (!this.globalCache.results[key])
+        this.globalCache.results[key] = new WeakEntityMap();
+      resultCache = this.globalCache.results[key];
     }
 
     if (!isActive) {
@@ -396,19 +430,89 @@ export default class Controller<
       };
     }
 
-    if (!this.globalCache.results[key])
-      this.globalCache.results[key] = new WeakEntityMap();
+    return this.getSchemaResponse(
+      results,
+      schema as Exclude<E['schema'], undefined>,
+      args,
+      state,
+      expiresAt,
+      resultCache,
+      endpoint.invalidIfStale || invalidResults,
+      meta,
+    );
+  }
 
+  /**
+   * Queries the store for a Querable schema
+   * @see https://dataclient.io/docs/api/Controller#query
+   */
+  query<S extends Queryable>(
+    schema: S,
+    ...rest: readonly [
+      ...SchemaArgs<S>,
+      Pick<State<unknown>, 'entities' | 'entityMeta'>,
+    ]
+  ): DenormalizeNullable<S> | undefined {
+    const state = rest[rest.length - 1] as State<unknown>;
+    // this is typescript generics breaking
+    const args: any = rest
+      .slice(0, rest.length - 1)
+      .map(ensurePojo) as SchemaArgs<S>;
+
+    // MEMOIZE inferResults - vary on schema + args
+    // NOTE: different orders can result in cache busting here; but since it's just a perf penalty we will allow for now
+    const key = JSON.stringify(args);
+    if (!this.globalCache.queries.has(schema)) {
+      this.globalCache.queries.set(schema, {});
+    }
+    const querySchemaCache = this.globalCache.queries.get(schema) as {
+      [key: string]: unknown;
+    };
+    if (!querySchemaCache[key])
+      querySchemaCache[key] = inferResults(
+        schema,
+        args,
+        state.indexes,
+        state.entities,
+      );
+    const results = querySchemaCache[key];
+    // END BLOCK
+
+    const data = denormalizeCached(
+      results,
+      schema,
+      state.entities,
+      this.globalCache.entities,
+      this.globalCache.infer,
+      args,
+    ).data;
+    return typeof data === 'symbol' ? undefined : (data as any);
+  }
+
+  private getSchemaResponse<S extends Schema>(
+    input: any,
+    schema: S,
+    args: any,
+    state: State<unknown>,
+    expiresAt: number,
+    resultCache: ResultCache,
+    invalidIfStale: boolean,
+    meta: { error?: unknown; invalidated?: unknown } = {},
+  ): {
+    data: DenormalizeNullable<S>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  } {
     // second argument is false if any entities are missing
     // eslint-disable-next-line prefer-const
     const { data, paths } = denormalizeCached(
-      results,
+      input,
       schema,
       state.entities,
       this.globalCache.entities,
-      this.globalCache.results[key],
+      resultCache,
       args,
-    ) as { data: DenormalizeNullable<E['schema']>; paths: Path[] };
+    ) as { data: DenormalizeNullable<S>; paths: Path[] };
     const invalidDenormalize = typeof data === 'symbol';
 
     // fallback to entity expiry time
@@ -422,12 +526,11 @@ export default class Controller<
     const expiryStatus =
       meta?.invalidated || (invalidDenormalize && !meta?.error) ?
         ExpiryStatus.Invalid
-      : invalidDenormalize || endpoint.invalidIfStale || invalidResults ?
-        ExpiryStatus.InvalidIfStale
+      : invalidDenormalize || invalidIfStale ? ExpiryStatus.InvalidIfStale
       : ExpiryStatus.Valid;
 
     return { data, expiryStatus, expiresAt };
-  };
+  }
 }
 
 // benchmark: https://www.measurethat.net/Benchmarks/Show/24691/0/min-reducer-vs-imperative-with-paths
@@ -487,19 +590,38 @@ class Snapshot<T = unknown> implements SnapshotInterface {
 
   /*************** Data Access ***************/
   /** @see https://dataclient.io/docs/api/Snapshot#getResponse */
-  getResponse = <
+  getResponse<E extends EndpointInterface>(
+    endpoint: E,
+    ...args: readonly [null]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  };
+
+  getResponse<E extends EndpointInterface>(
+    endpoint: E,
+    ...args: readonly [...Parameters<E>]
+  ): {
+    data: DenormalizeNullable<E['schema']>;
+    expiryStatus: ExpiryStatus;
+    expiresAt: number;
+  };
+
+  getResponse<
     E extends Pick<EndpointInterface, 'key' | 'schema' | 'invalidIfStale'>,
-    Args extends readonly [...Parameters<E['key']>],
   >(
     endpoint: E,
-    ...args: Args
+    ...args: readonly [...Parameters<E['key']>] | readonly [null]
   ): {
     data: DenormalizeNullable<E['schema']>;
     expiryStatus: ExpiryStatus;
     expiresAt: number;
-  } => {
+  } {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
     return this.controller.getResponse(endpoint, ...args, this.state);
-  };
+  }
 
   /** @see https://dataclient.io/docs/api/Snapshot#getError */
   getError = <
@@ -511,4 +633,15 @@ class Snapshot<T = unknown> implements SnapshotInterface {
   ): ErrorTypes | undefined => {
     return this.controller.getError(endpoint, ...args, this.state);
   };
+
+  /**
+   * Queries the store for a Querable schema
+   * @see https://dataclient.io/docs/api/Snapshot#query
+   */
+  query<S extends Queryable>(
+    schema: S,
+    ...args: SchemaArgs<S>
+  ): DenormalizeNullable<S> | undefined {
+    return this.controller.query(schema, ...args, this.state);
+  }
 }

packages/core/src/index.ts

@@ -13,13 +13,16 @@ export type {
   EndpointInterface,
   EntityInterface,
   ResolveType,
-  DenormalizeCache,
+  EntityCache,
+  ResultCache,
   DenormalizeNullable,
   Denormalize,
   Normalize,
   NormalizeNullable,
   FetchFunction,
   EndpointExtraOptions,
+  Queryable,
+  SchemaArgs,
 } from '@data-client/normalizr';
 export { ExpiryStatus } from '@data-client/normalizr';
 export {

packages/core/src/types.ts

@@ -2,6 +2,9 @@ import { NormalizedIndex } from '@data-client/normalizr';
 import type {
   UpdateFunction,
   AbstractInstanceType,
+  EntityCache,
+  ResultCache,
+  Queryable,
 } from '@data-client/normalizr';
 import type { ErrorTypes } from '@data-client/normalizr';
 
@@ -44,6 +47,24 @@ export interface State<T> {
   readonly lastReset: number;
 }
 
+export interface DenormalizeCache {
+  entities: EntityCache;
+  results: {
+    [key: string]: ResultCache;
+  };
+  infer: ResultCache;
+
+  inputEndpointCache: {
+    [key: string]: unknown;
+  };
+  queries: Map<
+    Queryable,
+    {
+      [key: string]: unknown;
+    }
+  >;
+}
+
 export * from './actions.js';
 
 export interface Manager<Actions = ActionTypes> {

packages/endpoint/src/queryEndpoint.ts

@@ -1,6 +1,7 @@
 import type {
   EntityTable,
   NormalizedIndex,
+  Queryable,
   SchemaSimple,
 } from './interface.js';
 import type { Denormalize, SchemaArgs } from './normal.js';
@@ -10,7 +11,7 @@ import type { Denormalize, SchemaArgs } from './normal.js';
  * @see https://dataclient.io/rest/api/Query
  */
 export class Query<
-  S extends SchemaSimple,
+  S extends Queryable,
   P extends SchemaArgs<S> = SchemaArgs<S>,
   R = Denormalize<S>,
 > {
@@ -30,7 +31,7 @@ export class Query<
     return `QUERY ${JSON.stringify(args)}`;
   }
 
-  protected createQuerySchema(schema: SchemaSimple) {
+  protected createQuerySchema(schema: S) {
     const query = Object.create(schema);
     query.denormalize = (input: any, args: P, unvisit: any) => {
       const value = unvisit(input, schema);
@@ -44,7 +45,7 @@ export class Query<
       args: any,
       indexes: any,
       recurse: (
-        schema: SchemaSimple,
+        schema: any,
         args: any[],
         indexes: NormalizedIndex,
         entities: EntityTable,