enhance: Add docstrings to Collection methods

reactive · May 13, 2024 · 19832bc · 19832bc
1 parent 398ad22
commit 19832bc
Show file tree

Hide file tree

Showing 8 changed files with 249 additions and 5 deletions.
diff --git a/.changeset/polite-eggs-notice.md b/.changeset/polite-eggs-notice.md
@@ -0,0 +1,7 @@
+---
+"@data-client/endpoint": patch
+"@data-client/graphql": patch
+"@data-client/rest": patch
+---
+
+Add docstrings to Collection methods
diff --git a/packages/endpoint/src/schemaTypes.ts b/packages/endpoint/src/schemaTypes.ts
@@ -30,6 +30,10 @@ export interface CollectionInterface<
   Args extends any[] = any[],
   Parent = any,
 > {
+  /** Constructs a custom creation schema for this collection
+   *
+   * @see https://dataclient.io/rest/api/Collection#addWith
+   */
   addWith<P extends any[] = Args>(
     merge: (existing: any, incoming: any) => any,
     createCollectionFilter?: (
@@ -41,6 +45,17 @@ export interface CollectionInterface<
 
   readonly schema: S;
   readonly key: string;
+
+  /**
+   * A unique identifier for each Collection
+   *
+   * Calls argsKey or nestKey depending on which are specified, and then serializes the result for the pk string.
+   *
+   * @param [parent] When normalizing, the object which included the entity
+   * @param [key] When normalizing, the key where this entity was found
+   * @param [args] ...args sent to Endpoint
+   * @see https://dataclient.io/docs/api/Collection#pk
+   */
   pk(value: any, parent: any, key: string, args: any[]): string;
   normalize(
     input: any,
@@ -53,7 +68,17 @@ export interface CollectionInterface<
     args: any,
   ): string;
 
+  /** Creates new instance copying over defined values of arguments
+   *
+   * @see https://dataclient.io/docs/api/Collection#merge
+   */
   merge(existing: any, incoming: any): any;
+
+  /** Determines the order of incoming Collection vs Collection already in store
+   *
+   * @see https://dataclient.io/docs/api/Collection#shouldReorder
+   * @returns true if incoming Collection should be first argument of merge()
+   */
   shouldReorder(
     existingMeta: {
       date: number;
@@ -67,6 +92,10 @@ export interface CollectionInterface<
     incoming: any,
   ): boolean;
 
+  /** Run when an existing Collection is found in the store
+   *
+   * @see https://dataclient.io/docs/api/schema.Entity#mergeWithStore
+   */
   mergeWithStore(
     existingMeta: {
       date: number;
@@ -99,6 +128,10 @@ export interface CollectionInterface<
     fetchedAt: number;
   };
 
+  /** Builds a key access the Collection without endpoint results
+   *
+   * @see https://dataclient.io/rest/api/Collection#queryKey
+   */
   queryKey(
     args: Args,
     queryKey: unknown,

diff --git a/packages/endpoint/src/schemas/Collection.ts b/packages/endpoint/src/schemas/Collection.ts
@@ -250,19 +250,35 @@ export type CollectionOptions<
   Parent = any,
 > = (
   | {
+      /** Defines lookups for Collections nested in other schemas.
+       *
+       * @see https://dataclient.io/rest/api/Collection#nestKey
+       */
       nestKey?: (parent: Parent, key: string) => Record<string, any>;
     }
   | {
+      /** Defines lookups top-level Collections using ...args.
+       *
+       * @see https://dataclient.io/rest/api/Collection#argsKey
+       */
       argsKey?: (...args: Args) => Record<string, any>;
     }
 ) &
   (
     | {
+        /** Sets a default createCollectionFilter for addWith(), push, unshift, and assign.
+         *
+         * @see https://dataclient.io/rest/api/Collection#createcollectionfilter
+         */
         createCollectionFilter?: (
           ...args: Args
         ) => (collectionKey: Record<string, string>) => boolean;
       }
     | {
+        /** Test to determine which arg keys should **not** be used for filtering results.
+         *
+         * @see https://dataclient.io/rest/api/Collection#nonfilterargumentkeys
+         */
         nonFilterArgumentKeys?: ((key: string) => boolean) | string[] | RegExp;
       }
   );

diff --git a/packages/endpoint/src/schemas/EntitySchema.ts b/packages/endpoint/src/schemas/EntitySchema.ts
@@ -554,7 +554,7 @@ export interface IEntityClass<TBase extends Constructor = any> {
     existing: any,
     incoming: any,
   ): boolean;
-  /** Determines the order of incoming entity vs entity already in store\
+  /** Determines the order of incoming entity vs entity already in store
    *
    * @see https://dataclient.io/docs/api/schema.Entity#shouldReorder
    * @returns true if incoming entity should be first argument of merge()

diff --git a/website/src/components/Playground/editor-types/@data-client/endpoint.d.ts b/website/src/components/Playground/editor-types/@data-client/endpoint.d.ts
@@ -331,7 +331,7 @@ interface IEntityClass<TBase extends Constructor = any> {
         date: number;
         fetchedAt: number;
     }, existing: any, incoming: any): boolean;
-    /** Determines the order of incoming entity vs entity already in store\
+    /** Determines the order of incoming entity vs entity already in store
      *
      * @see https://dataclient.io/docs/api/schema.Entity#shouldReorder
      * @returns true if incoming entity should be first argument of merge()
@@ -473,12 +473,28 @@ declare class Query<S extends Queryable, P extends (entries: Denormalize<S>, ...
 type ProcessParameters<P, S extends Queryable> = P extends (entries: any, ...args: infer Par) => any ? Par extends [] ? SchemaArgs<S> : Par & SchemaArgs<S> : SchemaArgs<S>;
 
 type CollectionOptions<Args extends any[] = [] | [urlParams: Record<string, any>] | [urlParams: Record<string, any>, body: any], Parent = any> = ({
+    /** Defines lookups for Collections nested in other schemas.
+     *
+     * @see https://dataclient.io/rest/api/Collection#nestKey
+     */
     nestKey?: (parent: Parent, key: string) => Record<string, any>;
 } | {
+    /** Defines lookups top-level Collections using ...args.
+     *
+     * @see https://dataclient.io/rest/api/Collection#argsKey
+     */
     argsKey?: (...args: Args) => Record<string, any>;
 }) & ({
+    /** Sets a default createCollectionFilter for addWith(), push, unshift, and assign.
+     *
+     * @see https://dataclient.io/rest/api/Collection#createcollectionfilter
+     */
     createCollectionFilter?: (...args: Args) => (collectionKey: Record<string, string>) => boolean;
 } | {
+    /** Test to determine which arg keys should **not** be used for filtering results.
+     *
+     * @see https://dataclient.io/rest/api/Collection#nonfilterargumentkeys
+     */
     nonFilterArgumentKeys?: ((key: string) => boolean) | string[] | RegExp;
 });
 
@@ -487,20 +503,47 @@ type CollectionArrayAdder$1<S extends PolymorphicInterface> = S extends ({
     schema: infer T;
 }) ? T : never;
 interface CollectionInterface<S extends PolymorphicInterface = any, Args extends any[] = any[], Parent = any> {
+    /** Constructs a custom creation schema for this collection
+     *
+     * @see https://dataclient.io/rest/api/Collection#addWith
+     */
     addWith<P extends any[] = Args>(merge: (existing: any, incoming: any) => any, createCollectionFilter?: (...args: P) => (collectionKey: Record<string, string>) => boolean): Collection<S, P>;
     readonly cacheWith: object;
     readonly schema: S;
     readonly key: string;
+    /**
+     * A unique identifier for each Collection
+     *
+     * Calls argsKey or nestKey depending on which are specified, and then serializes the result for the pk string.
+     *
+     * @param [parent] When normalizing, the object which included the entity
+     * @param [key] When normalizing, the key where this entity was found
+     * @param [args] ...args sent to Endpoint
+     * @see https://dataclient.io/docs/api/Collection#pk
+     */
     pk(value: any, parent: any, key: string, args: any[]): string;
     normalize(input: any, parent: Parent, key: string, visit: (...args: any) => any, addEntity: (...args: any) => any, visitedEntities: Record<string, any>, storeEntities: any, args: any): string;
+    /** Creates new instance copying over defined values of arguments
+     *
+     * @see https://dataclient.io/docs/api/Collection#merge
+     */
     merge(existing: any, incoming: any): any;
+    /** Determines the order of incoming Collection vs Collection already in store
+     *
+     * @see https://dataclient.io/docs/api/Collection#shouldReorder
+     * @returns true if incoming Collection should be first argument of merge()
+     */
     shouldReorder(existingMeta: {
         date: number;
         fetchedAt: number;
     }, incomingMeta: {
         date: number;
         fetchedAt: number;
     }, existing: any, incoming: any): boolean;
+    /** Run when an existing Collection is found in the store
+     *
+     * @see https://dataclient.io/docs/api/schema.Entity#mergeWithStore
+     */
     mergeWithStore(existingMeta: {
         date: number;
         fetchedAt: number;
@@ -521,6 +564,10 @@ interface CollectionInterface<S extends PolymorphicInterface = any, Args extends
         date: number;
         fetchedAt: number;
     };
+    /** Builds a key access the Collection without endpoint results
+     *
+     * @see https://dataclient.io/rest/api/Collection#queryKey
+     */
     queryKey(args: Args, queryKey: unknown, getEntity: unknown, getIndex: unknown): any;
     createIfValid: (value: any) => any | undefined;
     denormalize(input: any, args: readonly any[], unvisit: (input: any, schema: any) => any): ReturnType<S['denormalize']>;

diff --git a/website/src/components/Playground/editor-types/@data-client/graphql.d.ts b/website/src/components/Playground/editor-types/@data-client/graphql.d.ts
@@ -331,7 +331,7 @@ interface IEntityClass<TBase extends Constructor = any> {
         date: number;
         fetchedAt: number;
     }, existing: any, incoming: any): boolean;
-    /** Determines the order of incoming entity vs entity already in store\
+    /** Determines the order of incoming entity vs entity already in store
      *
      * @see https://dataclient.io/docs/api/schema.Entity#shouldReorder
      * @returns true if incoming entity should be first argument of merge()
@@ -473,12 +473,28 @@ declare class Query<S extends Queryable, P extends (entries: Denormalize<S>, ...
 type ProcessParameters<P, S extends Queryable> = P extends (entries: any, ...args: infer Par) => any ? Par extends [] ? SchemaArgs<S> : Par & SchemaArgs<S> : SchemaArgs<S>;
 
 type CollectionOptions<Args extends any[] = [] | [urlParams: Record<string, any>] | [urlParams: Record<string, any>, body: any], Parent = any> = ({
+    /** Defines lookups for Collections nested in other schemas.
+     *
+     * @see https://dataclient.io/rest/api/Collection#nestKey
+     */
     nestKey?: (parent: Parent, key: string) => Record<string, any>;
 } | {
+    /** Defines lookups top-level Collections using ...args.
+     *
+     * @see https://dataclient.io/rest/api/Collection#argsKey
+     */
     argsKey?: (...args: Args) => Record<string, any>;
 }) & ({
+    /** Sets a default createCollectionFilter for addWith(), push, unshift, and assign.
+     *
+     * @see https://dataclient.io/rest/api/Collection#createcollectionfilter
+     */
     createCollectionFilter?: (...args: Args) => (collectionKey: Record<string, string>) => boolean;
 } | {
+    /** Test to determine which arg keys should **not** be used for filtering results.
+     *
+     * @see https://dataclient.io/rest/api/Collection#nonfilterargumentkeys
+     */
     nonFilterArgumentKeys?: ((key: string) => boolean) | string[] | RegExp;
 });
 
@@ -487,20 +503,47 @@ type CollectionArrayAdder$1<S extends PolymorphicInterface> = S extends ({
     schema: infer T;
 }) ? T : never;
 interface CollectionInterface<S extends PolymorphicInterface = any, Args extends any[] = any[], Parent = any> {
+    /** Constructs a custom creation schema for this collection
+     *
+     * @see https://dataclient.io/rest/api/Collection#addWith
+     */
     addWith<P extends any[] = Args>(merge: (existing: any, incoming: any) => any, createCollectionFilter?: (...args: P) => (collectionKey: Record<string, string>) => boolean): Collection<S, P>;
     readonly cacheWith: object;
     readonly schema: S;
     readonly key: string;
+    /**
+     * A unique identifier for each Collection
+     *
+     * Calls argsKey or nestKey depending on which are specified, and then serializes the result for the pk string.
+     *
+     * @param [parent] When normalizing, the object which included the entity
+     * @param [key] When normalizing, the key where this entity was found
+     * @param [args] ...args sent to Endpoint
+     * @see https://dataclient.io/docs/api/Collection#pk
+     */
     pk(value: any, parent: any, key: string, args: any[]): string;
     normalize(input: any, parent: Parent, key: string, visit: (...args: any) => any, addEntity: (...args: any) => any, visitedEntities: Record<string, any>, storeEntities: any, args: any): string;
+    /** Creates new instance copying over defined values of arguments
+     *
+     * @see https://dataclient.io/docs/api/Collection#merge
+     */
     merge(existing: any, incoming: any): any;
+    /** Determines the order of incoming Collection vs Collection already in store
+     *
+     * @see https://dataclient.io/docs/api/Collection#shouldReorder
+     * @returns true if incoming Collection should be first argument of merge()
+     */
     shouldReorder(existingMeta: {
         date: number;
         fetchedAt: number;
     }, incomingMeta: {
         date: number;
         fetchedAt: number;
     }, existing: any, incoming: any): boolean;
+    /** Run when an existing Collection is found in the store
+     *
+     * @see https://dataclient.io/docs/api/schema.Entity#mergeWithStore
+     */
     mergeWithStore(existingMeta: {
         date: number;
         fetchedAt: number;
@@ -521,6 +564,10 @@ interface CollectionInterface<S extends PolymorphicInterface = any, Args extends
         date: number;
         fetchedAt: number;
     };
+    /** Builds a key access the Collection without endpoint results
+     *
+     * @see https://dataclient.io/rest/api/Collection#queryKey
+     */
     queryKey(args: Args, queryKey: unknown, getEntity: unknown, getIndex: unknown): any;
     createIfValid: (value: any) => any | undefined;
     denormalize(input: any, args: readonly any[], unvisit: (input: any, schema: any) => any): ReturnType<S['denormalize']>;