feat: Use Querable schemas in useCache()

docs/core/shared/_schema_table.mdx

@@ -1,10 +1,11 @@
-| Schema                             | Description                                                                  | Data Type                                                                                                                                                                                            | Mutable | Has A           |
-| ---------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- |
-| [Entity](/rest/api/Entity)         | single _unique_ object                                                       | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                                    | ✅      |                 |
-| [Object](/rest/api/Object)         | statically known keys                                                        | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                                    | 🛑      |                 |
-| [Array](/rest/api/Array)           | lists of any size                                                            | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)                                                                                                      | 🛑      |                 |
-| [Values](/rest/api/Values)         | maps of any size                                                    | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                                    | 🛑      |                 |
-| [All](/rest/api/All)               | list of all entities of a kind                                               | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)                                                                                                      | 🛑      | Entity          |
-| [Collection](/rest/api/Collection) | enables adding new items                                                     | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) or [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | ✅      | Array or Values |
-| [Union](/rest/api/Union)           | one of many different types (`A \| B`)                                       | Polymorphic [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                        | ✅      | Entity          |
-| [Invalidate](/rest/api/Invalidate) | [remove an entity](../concepts/expiry-policy.md#any-endpoint-with-an-entity) | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                                    | ✅      | Entity          |
+| Schema                             | Description                                                                  | Data Type                                                                                                                                                                                            | Mutable | Queryable | Of A      |
+| ---------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------- | --------- |
+| [Entity](/rest/api/Entity)         | single _unique_ object                                                       | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                                    | ✅      | ✅        |           |
+| [Object](/rest/api/Object)         | statically known keys                                                        | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                                    | 🛑      | 🛑        |           |
+| [Array](/rest/api/Array)           | lists of any size                                                            | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)                                                                                                      | 🛑      | 🛑        |           |
+| [Values](/rest/api/Values)         | maps of any size                                                             | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                                    | 🛑      | 🛑        |           |
+| [All](/rest/api/All)               | list of all entities of a kind                                               | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)                                                                                                      | 🛑      | ✅        |           |
+| [Collection](/rest/api/Collection) | enables adding new items                                                     | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) or [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | ✅      | ✅        |           |
+| [Query](/rest/api/Query)           | memoized custom transforms                                                   | any                                                                                                                                                                                                  | 🛑      | ✅        | Queryable |
+| [Union](/rest/api/Union)           | one of many different types (`A \| B`)                                       | Polymorphic [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                        | ✅      | ✅        | Entity    |
+| [Invalidate](/rest/api/Invalidate) | [remove an entity](../concepts/expiry-policy.md#any-endpoint-with-an-entity) | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)                                                                                                    | ✅      | 🛑        | Entity    |

packages/endpoint/src-4.0-types/schemas/EntityFields.d.ts

@@ -0,0 +1,4 @@
+/** Attempts to infer reasonable input type to construct an Entity */
+export type EntityFields<U> = {
+  readonly [K in keyof U]?: U[K];
+};

packages/endpoint/src/index.ts

@@ -34,7 +34,7 @@ export type {
   NormalizeNullable,
   Denormalize,
   DenormalizeNullable,
-  SchemaToArgs,
+  SchemaArgs,
 } from './normal.js';
 export type {
   EndpointExtraOptions,

packages/endpoint/src/interface.ts

@@ -10,6 +10,16 @@ export type Schema =
   | SchemaSimple
   | Serializable;
 
+export type Queryable = {
+  infer(
+    args: readonly any[],
+    indexes: NormalizedIndex,
+    recurse: (...args: any) => any,
+    entities: EntityTable,
+    // Must be non-void
+  ): {};
+};
+
 export type Serializable<
   T extends { toJSON(): string } = { toJSON(): string },
 > = (value: any) => T;
@@ -23,23 +33,26 @@ export interface SchemaSimple<T = any, Args extends any[] = any[]> {
     addEntity: (...args: any) => any,
     visitedEntities: Record<string, any>,
     storeEntities: any,
-    args: Args,
+    args: any[],
   ): any;
   denormalize(
     input: {},
     args: readonly any[],
     unvisit: (input: any, schema: any) => any,
   ): T;
   infer(
-    args: readonly any[],
+    args: Args,
     indexes: NormalizedIndex,
     recurse: (...args: any) => any,
     entities: EntityTable,
   ): any;
 }
 
-export interface SchemaClass<T = any, N = T | undefined>
-  extends SchemaSimple<T> {
+export interface SchemaClass<
+  T = any,
+  N = T | undefined,
+  Args extends any[] = any[],
+> extends SchemaSimple<T, Args> {
   // this is not an actual member, but is needed for the recursive NormalizeNullable<> type algo
   _normalizeNullable(): any;
   // this is not an actual member, but is needed for the recursive DenormalizeNullable<> type algo
@@ -69,7 +82,8 @@ export interface EntityInterface<T = any> extends SchemaSimple {
 }
 
 /** Represents Array or Values */
-export interface PolymorphicInterface<T = any> extends SchemaSimple<T> {
+export interface PolymorphicInterface<T = any, Args extends any[] = any[]>
+  extends SchemaSimple<T, Args> {
   readonly schema: any;
   // this is not an actual member, but is needed for the recursive NormalizeNullable<> type algo
   _normalizeNullable(): any;

packages/endpoint/src/normal.ts

@@ -3,7 +3,9 @@ import type {
   Serializable,
   EntityInterface,
   NormalizedIndex,
+  Queryable,
 } from './interface.js';
+import { EntityFields } from './schemas/EntityFields.js';
 
 // TypeScript <4.2 InstanceType<> does not work on abstract classes
 export type AbstractInstanceType<T> =
@@ -117,33 +119,17 @@ export interface EntityMap<T = any> {
   readonly [k: string]: EntityInterface<T>;
 }
 
-export type SchemaToArgs<
-  S extends {
-    normalize(
-      input: any,
-      parent: any,
-      key: any,
-      visit: (...args: any) => any,
-      addEntity: (...args: any) => any,
-      visitedEntities: Record<string, any>,
-      storeEntities: any,
-      args: any,
-    ): any;
-  },
-> =
-  S extends (
+export type SchemaArgs<S extends Queryable> =
+  S extends EntityInterface<infer U> ? EntityFields<U>
+  : S extends (
     {
-      normalize(
-        input: any,
-        parent: any,
-        key: any,
-        visit: (...args: any) => any,
-        addEntity: (...args: any) => any,
-        visitedEntities: Record<string, any>,
-        storeEntities: any,
+      infer(
         args: infer Args,
+        indexes: any,
+        recurse: (...args: any) => any,
+        entities: any,
       ): any;
     }
   ) ?
     Args
-  : never;
+  : [];

packages/endpoint/src/queryEndpoint.ts

@@ -3,15 +3,15 @@ import type {
   NormalizedIndex,
   SchemaSimple,
 } from './interface.js';
-import type { Denormalize, SchemaToArgs } from './normal.js';
+import type { Denormalize, SchemaArgs } from './normal.js';
 
 /**
  * Programmatic cache reading
  * @see https://dataclient.io/rest/api/Query
  */
 export class Query<
   S extends SchemaSimple,
-  P extends SchemaToArgs<S> = SchemaToArgs<S>,
+  P extends SchemaArgs<S> = SchemaArgs<S>,
   R = Denormalize<S>,
 > {
   declare schema: QuerySchema<S, R>;

packages/endpoint/src/schema.d.ts

@@ -18,6 +18,7 @@ import type {
   NormalizedNullableObject,
   EntityMap,
 } from './normal.js';
+import { EntityFields } from './schemas/EntityFields.js';
 import {
   EntityOptions,
   IEntityClass,
@@ -66,7 +67,7 @@ export class Array<S extends Schema = Schema> implements SchemaClass {
     addEntity: (...args: any) => any,
     visitedEntities: Record<string, any>,
     storeEntities: any,
-    args?: any[],
+    args: any[],
   ): (S extends EntityMap ? UnionResult<S> : Normalize<S>)[];
 
   _normalizeNullable():
@@ -88,7 +89,7 @@ export class Array<S extends Schema = Schema> implements SchemaClass {
     indexes: NormalizedIndex,
     recurse: (...args: any) => any,
     entities: any,
-  ): any;
+  ): undefined;
 }
 
 /**
@@ -136,7 +137,7 @@ export class All<
   ): (S extends EntityMap<infer T> ? T : Denormalize<S>)[];
 
   infer(
-    args: readonly any[],
+    args: [],
     indexes: NormalizedIndex,
     recurse: (...args: any) => any,
     entities: EntityTable,
@@ -222,7 +223,7 @@ export class Union<Choices extends EntityMap = any> implements SchemaClass {
   ): AbstractInstanceType<Choices[keyof Choices]>;
 
   infer(
-    args: readonly any[],
+    args: [EntityFields<AbstractInstanceType<Choices[keyof Choices]>>],
     indexes: NormalizedIndex,
     recurse: (...args: any) => any,
     entities: any,
@@ -293,7 +294,7 @@ export class Values<Choices extends Schema = any> implements SchemaClass {
     indexes: NormalizedIndex,
     recurse: (...args: any) => any,
     entities: any,
-  ): any;
+  ): undefined;
 }
 
 export type CollectionArrayAdder<S extends PolymorphicInterface> =

packages/endpoint/src/schemaTypes.ts

@@ -50,7 +50,7 @@ export interface CollectionInterface<
     addEntity: (...args: any) => any,
     visitedEntities: Record<string, any>,
     storeEntities: any,
-    args: Args,
+    args: any,
   ): string;
 
   merge(existing: any, incoming: any): any;
@@ -99,12 +99,7 @@ export interface CollectionInterface<
     fetchedAt: number;
   };
 
-  infer(
-    args: unknown,
-    indexes: unknown,
-    recurse: unknown,
-    entities: unknown,
-  ): any;
+  infer(args: Args, indexes: unknown, recurse: unknown, entities: unknown): any;
 
   createIfValid: (value: any) => any | undefined;
   denormalize(

packages/endpoint/src/schemas/Collection.ts

@@ -155,7 +155,7 @@ export default class CollectionSchema<
     addEntity: (...args: any) => any,
     visitedEntities: Record<string, any>,
     storeEntities: any,
-    args: Args,
+    args: any,
   ): string {
     const normalizedValue = this.schema.normalize(
       input,
@@ -218,7 +218,7 @@ export default class CollectionSchema<
 
   // >>>>>>>>>>>>>>DENORMALIZE<<<<<<<<<<<<<<
 
-  infer(args: any, indexes: unknown, recurse: unknown, entities: any): any {
+  infer(args: Args, indexes: unknown, recurse: unknown, entities: any): any {
     if (this.argsKey) {
       const id = this.pk(undefined, undefined, '', args);
       if (entities[this.key]?.[id]) return id;

packages/endpoint/src/schemas/EntityFields.ts

@@ -0,0 +1,5 @@
+/** Attempts to infer reasonable input type to construct an Entity */
+export type EntityFields<U> = {
+  readonly [K in keyof U as U[K] extends (...args: any) => any ? never
+  : K]?: U[K];
+};

packages/endpoint/src/schemas/Invalidate.ts

@@ -98,7 +98,7 @@ export default class Invalidate<
 
   /** /End Normalize lifecycles **/
 
-  infer(args: any, indexes: any, recurse: any): any {
+  infer(args: any, indexes: any, recurse: any): undefined {
     return undefined;
   }
 

packages/normalizr/src/EntityFields.ts

@@ -0,0 +1,5 @@
+/** Attempts to infer reasonable input type to construct an Entity */
+export type EntityFields<U> = {
+  readonly [K in keyof U as U[K] extends (...args: any) => any ? never
+  : K]?: U[K];
+};

packages/normalizr/src/index.ts

@@ -20,6 +20,7 @@ export type {
   DenormalizeNullable,
   Normalize,
   NormalizeNullable,
+  SchemaArgs,
 } from './types.js';
 export * from './endpoint/types.js';
 export * from './interface.js';

packages/normalizr/src/interface.ts

@@ -6,36 +6,49 @@ export type Schema =
   | SchemaSimple
   | Serializable;
 
+export type Queryable = {
+  infer(
+    args: readonly any[],
+    indexes: NormalizedIndex,
+    recurse: (...args: any) => any,
+    entities: EntityTable,
+    // Must be non-void
+  ): {};
+};
+
 export type Serializable<
   T extends { toJSON(): string } = { toJSON(): string },
 > = (value: any) => T;
 
-export interface SchemaSimple<T = any> {
+export interface SchemaSimple<T = any, Args extends any[] = any[]> {
   normalize(
     input: any,
     parent: any,
     key: any,
     visit: (...args: any) => any,
     addEntity: (...args: any) => any,
     visitedEntities: Record<string, any>,
-    storeEntities?: any,
-    args?: any[],
+    storeEntities: any,
+    args: any[],
   ): any;
   denormalize(
     input: {},
-    args: any,
+    args: readonly any[],
     unvisit: (input: any, schema: any) => any,
   ): T;
   infer(
-    args: readonly any[],
+    args: Args,
     indexes: NormalizedIndex,
     recurse: (...args: any) => any,
     entities: EntityTable,
   ): any;
 }
 
-export interface SchemaClass<T = any, N = T | undefined>
-  extends SchemaSimple<T> {
+export interface SchemaClass<
+  T = any,
+  N = T | undefined,
+  Args extends any[] = any[],
+> extends SchemaSimple<T, Args> {
   // this is not an actual member, but is needed for the recursive NormalizeNullable<> type algo
   _normalizeNullable(): any;
   // this is not an actual member, but is needed for the recursive DenormalizeNullable<> type algo

packages/normalizr/src/types.ts

@@ -1,9 +1,10 @@
+import { EntityFields } from './EntityFields.js';
 import type {
   Schema,
   Serializable,
   EntityInterface,
   NormalizedIndex,
-  SchemaClass,
+  Queryable,
 } from './interface.js';
 import type WeakEntityMap from './WeakEntityMap.js';
 
@@ -132,3 +133,18 @@ export type NormalizedSchema<E, R> = {
 };
 
 export type EntityMap<T = any> = Record<string, EntityInterface<T>>;
+
+export type SchemaArgs<S extends Queryable> =
+  S extends EntityInterface<infer U> ? EntityFields<U>
+  : S extends (
+    {
+      infer(
+        args: infer Args,
+        indexes: any,
+        recurse: (...args: any) => any,
+        entities: any,
+      ): any;
+    }
+  ) ?
+    Args
+  : [];