enhance: Add docstrings to schema constructors

.changeset/funny-games-exercise.md

@@ -0,0 +1,6 @@
+---
+"@data-client/endpoint": patch
+"@data-client/rest": patch
+---
+
+Improve readability of Collection generics by naming DefaultArgs

.changeset/tasty-mugs-vanish.md

@@ -0,0 +1,6 @@
+---
+"@data-client/endpoint": patch
+"@data-client/rest": patch
+---
+
+Add docstrings to schema constructors

packages/endpoint/src/endpointTypes.ts

@@ -146,6 +146,10 @@ export interface EndpointInstanceInterface<
 }
 
 export interface EndpointConstructor {
+  /**
+   * Defines an async data source.
+   * @see https://dataclient.io/docs/api/Endpoint
+   */
   new <
     F extends (
       this: EndpointInstance<FetchFunction> & E,
@@ -163,6 +167,10 @@ export interface EndpointConstructor {
 }
 
 export interface ExtendableEndpointConstructor {
+  /**
+   * Defines an async data source.
+   * @see https://dataclient.io/docs/api/Endpoint
+   */
   new <
     F extends (
       this: EndpointInstanceInterface<FetchFunction> & E,

packages/endpoint/src/index.ts

@@ -13,7 +13,7 @@ export type {
 export * as schema from './schema.js';
 // Without this we get 'cannot be named without a reference to' for createResource()....why is this?
 // Clue 1) It only happens with types mentioned in return types of other types
-export type { Array, Invalidate, Collection } from './schema.js';
+export type { Array, Invalidate, Collection, DefaultArgs } from './schema.js';
 export { default as Entity } from './schemas/Entity.js';
 export { default as validateRequired } from './validateRequired.js';
 export { INVALID } from './special.js';

packages/endpoint/src/schema.d.ts

@@ -32,6 +32,7 @@ import { default as Invalidate } from './schemas/Invalidate.js';
 import { default as Query } from './schemas/Query.js';
 import type {
   CollectionConstructor,
+  DefaultArgs,
   SchemaAttributeFunction,
   SchemaFunction,
   UnionResult,
@@ -50,6 +51,10 @@ export * from './schemaTypes.js';
  * @see https://dataclient.io/rest/api/Array
  */
 export class Array<S extends Schema = Schema> implements SchemaClass {
+  /**
+   * Represents arrays
+   * @see https://dataclient.io/rest/api/Array
+   */
   constructor(
     definition: S,
     schemaAttribute?: S extends EntityMap<infer T> ?
@@ -96,12 +101,17 @@ export class Array<S extends Schema = Schema> implements SchemaClass {
 /**
  * Retrieves all entities in cache
  *
- * @see https://dataclient.io/rest/api/AllSchema
+ * @see https://dataclient.io/rest/api/All
  */
 export class All<
   S extends EntityMap | EntityInterface = EntityMap | EntityInterface,
 > implements SchemaClass
 {
+  /**
+   * Retrieves all entities in cache
+   *
+   * @see https://dataclient.io/rest/api/All
+   */
   constructor(
     definition: S,
     schemaAttribute?: S extends EntityMap<infer T> ?
@@ -153,6 +163,10 @@ export class All<
 export class Object<O extends Record<string, any> = Record<string, Schema>>
   implements SchemaClass
 {
+  /**
+   * Represents objects with statically known members
+   * @see https://dataclient.io/rest/api/Object
+   */
   constructor(definition: O);
   define(definition: Schema): void;
   readonly schema: O;
@@ -206,7 +220,15 @@ type UnionSchemaToArgs<
   : SchemaAttribute extends (value: infer Args, ...rest: any) => unknown ? Args
   : never;
 
+/**
+ * Represents polymorphic values.
+ * @see https://dataclient.io/rest/api/Union
+ */
 export interface UnionConstructor {
+  /**
+   * Represents polymorphic values.
+   * @see https://dataclient.io/rest/api/Union
+   */
   new <
     Choices extends EntityMap,
     SchemaAttribute extends
@@ -291,6 +313,10 @@ export declare class Union<
  * @see https://dataclient.io/rest/api/Values
  */
 export class Values<Choices extends Schema = any> implements SchemaClass {
+  /**
+   * Represents variably sized objects
+   * @see https://dataclient.io/rest/api/Values
+   */
   constructor(
     definition: Choices,
     schemaAttribute?: Choices extends EntityMap<infer T> ?
@@ -374,10 +400,7 @@ export declare let CollectionRoot: CollectionConstructor;
  */
 export declare class Collection<
   S extends any[] | PolymorphicInterface = any,
-  Args extends any[] =
-    | []
-    | [urlParams: Record<string, any>]
-    | [urlParams: Record<string, any>, body: any],
+  Args extends any[] = DefaultArgs,
   Parent = any,
 > extends CollectionRoot<S, Args, Parent> {}
 

packages/endpoint/src/schemaTypes.ts

@@ -168,10 +168,7 @@ export interface CollectionInterface<
 }
 export type CollectionFromSchema<
   S extends any[] | PolymorphicInterface = any,
-  Args extends any[] =
-    | []
-    | [urlParams: Record<string, any>]
-    | [urlParams: Record<string, any>, body: any],
+  Args extends any[] = DefaultArgs,
   Parent = any,
 > = CollectionInterface<
   S extends any[] ? schema.Array<S[number]> : S,
@@ -180,12 +177,13 @@ export type CollectionFromSchema<
 >;
 
 export interface CollectionConstructor {
+  /**
+   * Entities but for Arrays instead of classes
+   * @see https://dataclient.io/rest/api/Collection
+   */
   new <
     S extends SchemaSimple[] | PolymorphicInterface = any,
-    Args extends any[] =
-      | []
-      | [urlParams: Record<string, any>]
-      | [urlParams: Record<string, any>, body: any],
+    Args extends any[] = DefaultArgs,
     Parent = any,
   >(
     schema: S,
@@ -210,3 +208,7 @@ export type UnionResult<Choices extends EntityMap> = {
   id: string;
   schema: keyof Choices;
 };
+export type DefaultArgs =
+  | []
+  | [urlParams: Record<string, any>]
+  | [urlParams: Record<string, any>, body: any];

packages/endpoint/src/schemas/Collection.ts

@@ -2,6 +2,7 @@ import { consistentSerialize } from './consistentSerialize.js';
 import { CREATE } from './special.js';
 import { GetEntity, PolymorphicInterface } from '../interface.js';
 import { Values, Array as ArraySchema } from '../schema.js';
+import type { DefaultArgs } from '../schemaTypes.js';
 
 const pushMerge = (existing: any, incoming: any) => {
   return [...existing, ...incoming];
@@ -21,10 +22,7 @@ const createValue = (value: any) => ({ ...value });
  */
 export default class CollectionSchema<
   S extends PolymorphicInterface = any,
-  Args extends any[] =
-    | []
-    | [urlParams: Record<string, any>]
-    | [urlParams: Record<string, any>, body: any],
+  Args extends any[] = DefaultArgs,
   Parent = any,
 > {
   protected declare nestKey: (parent: any, key: string) => Record<string, any>;
@@ -243,10 +241,7 @@ export default class CollectionSchema<
 }
 
 export type CollectionOptions<
-  Args extends any[] =
-    | []
-    | [urlParams: Record<string, any>]
-    | [urlParams: Record<string, any>, body: any],
+  Args extends any[] = DefaultArgs,
   Parent = any,
 > = (
   | {

packages/endpoint/src/schemas/EntitySchema.ts

@@ -53,6 +53,10 @@ export interface RequiredPKOptions<TInstance extends {}>
     | keyof TInstance;
 }
 
+/**
+ * Represents data that should be deduped by specifying a primary key.
+ * @see https://dataclient.io/rest/api/schema.Entity
+ */
 export default function EntitySchema<TBase extends Constructor>(
   Base: TBase,
   options: EntityOptions<InstanceType<TBase>> = {},

packages/endpoint/src/schemas/Invalidate.ts

@@ -18,6 +18,13 @@ export default class Invalidate<
 {
   protected declare _entity: E;
 
+  /**
+   * Marks entity as Invalid.
+   *
+   * This triggers suspense for all endpoints requiring it.
+   * Optional (like variable sized Array and Values) will simply remove the item.
+   * @see https://dataclient.io/rest/api/Invalidate
+   */
   constructor(entity: E) {
     if (process.env.NODE_ENV !== 'production' && !entity) {
       throw new Error('Expected option "entity" not found on DeleteSchema.');

packages/endpoint/src/schemas/Query.ts

@@ -4,12 +4,7 @@ import type {
   Queryable,
   SchemaSimple,
 } from '../interface.js';
-import type {
-  Denormalize,
-  DenormalizeNullable,
-  NormalizeNullable,
-  SchemaArgs,
-} from '../normal.js';
+import type { Denormalize, NormalizeNullable, SchemaArgs } from '../normal.js';
 
 /**
  * Programmatic cache reading
@@ -24,6 +19,11 @@ export default class Query<
   declare schema: S;
   declare process: P;
 
+  /**
+   * Programmatic cache reading
+   *
+   * @see https://dataclient.io/rest/api/Query
+   */
   constructor(schema: S, process: P) {
     this.schema = schema;
     this.process = process;

packages/rest/src/RestEndpointTypes.ts

@@ -477,6 +477,10 @@ export interface RestEndpoint<O extends RestGenerics = any>
   > {}
 
 export interface RestEndpointConstructor {
+  /** Simplifies endpoint definitions that follow REST patterns
+   *
+   * @see https://dataclient.io/rest/api/RestEndpoint
+   */
   new <O extends RestGenerics = any>({
     method,
     sideEffect,

packages/rest/src/__tests__/createResource.test.ts

@@ -1,4 +1,5 @@
 import { Entity, PolymorphicInterface, schema } from '@data-client/endpoint';
+import type { DefaultArgs } from '@data-client/endpoint';
 import {
   CacheProvider,
   useCache,
@@ -1169,10 +1170,7 @@ describe('createResource()', () => {
     it('should warn when mis-capitalizing options', () => {
       class MyCollection<
         S extends any[] | PolymorphicInterface = any,
-        Args extends any[] =
-          | []
-          | [urlParams: Record<string, any>]
-          | [urlParams: Record<string, any>, body: any],
+        Args extends any[] = DefaultArgs,
         Parent = any,
       > extends schema.Collection<S, Args, Parent> {
         // getList.push should add to Collections regardless of its 'orderBy' argument