@data-client/rest 0.4.0 → 0.5.0

package/src/RestEndpoint.d.ts

@@ -5,7 +5,6 @@ import type {
   Schema,
   FetchFunction,
   ResolveType,
-  schema,
 } from '@data-client/endpoint';
 
 import type { ExtractCollection } from './extractCollection.js';
@@ -27,7 +26,9 @@ export interface RestInstanceBase<
     method?: string;
   } = { path: string },
 > extends EndpointInstanceInterface<F, S, M> {
+  /** @see https://resthooks.io/rest/api/RestEndpoint#body */
   readonly body?: 'body' extends keyof O ? O['body'] : any;
+  /** @see https://resthooks.io/rest/api/RestEndpoint#searchParams */
   readonly searchParams?: 'searchParams' extends keyof O
     ? O['searchParams']
     : // unknown is identity with '&' type operator
@@ -42,6 +43,7 @@ export interface RestInstanceBase<
    */
   readonly urlPrefix: string;
   readonly requestInit: RequestInit;
+  /** @see https://resthooks.io/rest/api/RestEndpoint#method */
   readonly method: (O & { method: string })['method'];
   readonly signal: AbortSignal | undefined;
 
@@ -72,10 +74,29 @@ export interface RestInstanceBase<
   //       this is just a hack to handle when no members of PartialRestGenerics are present
   //       Note: Using overloading (like paginated did) struggles because typescript does not have a clear way of distinguishing one
   //       should be used from the other (due to same problem with every member being partial)
+  /** Creates a child endpoint that inherits from this while overriding provided `options`.
+   * @see https://dataclient.io/rest/api/RestEndpoint#extend
+   */
   extend<E extends RestInstanceBase, O extends PartialRestGenerics | {}>(
     this: E,
     options: Readonly<RestEndpointExtendOptions<O, E, F> & O>,
   ): RestExtendedEndpoint<O, E>;
+}
+
+export interface RestInstance<
+  F extends FetchFunction = FetchFunction,
+  S extends Schema | undefined = any,
+  M extends true | undefined = true | undefined,
+  O extends {
+    path: string;
+    body?: any;
+    searchParams?: any;
+    method?: string;
+  } = { path: string },
+> extends RestInstanceBase<F, S, M, O> {
+  /** Endpoint to append the next page extending a list for pagination
+   * @see https://dataclient.io/rest/api/RestEndpoint#paginated
+   */
   paginated<
     E extends RestInstanceBase<FetchFunction, any, undefined>,
     A extends any[],
@@ -90,19 +111,9 @@ export interface RestInstanceBase<
     this: E,
     cursorField: C,
   ): PaginationFieldEndpoint<E, C>;
-}
-
-export interface RestInstance<
-  F extends FetchFunction = FetchFunction,
-  S extends Schema | undefined = any,
-  M extends true | undefined = true | undefined,
-  O extends {
-    path: string;
-    body?: any;
-    searchParams?: any;
-    method?: string;
-  } = { path: string },
-> extends RestInstanceBase<F, S, M, O> {
+  /** Endpoint that pushes (place at end) a newly created entity to this Collection
+   * @see https://dataclient.io/rest/api/RestEndpoint#push
+   */
   push: AddEndpoint<
     F,
     ExtractCollection<S>['push'],
@@ -113,6 +124,9 @@ export interface RestInstance<
         | FormData;
     }
   >;
+  /** Endpoint that unshifts (place at start) a newly created entity to this Collection
+   * @see https://dataclient.io/rest/api/RestEndpoint#unshift
+   */
   unshift: AddEndpoint<
     F,
     ExtractCollection<S>['unshift'],
@@ -123,6 +137,9 @@ export interface RestInstance<
         | FormData;
     }
   >;
+  /** Endpoint that assigns newly created entities to their respective keys in this Collection
+   * @see https://dataclient.io/rest/api/RestEndpoint#assign
+   */
   assign: AddEndpoint<
     F,
     ExtractCollection<S>,
@@ -309,7 +326,7 @@ export type AddEndpoint<
   >,
   S,
   true,
-  O & { method: 'POST' }
+  Omit<O, 'method'> & { method: 'POST' }
 >;
 
 type OptionsBodyDefault<O extends RestGenerics> = 'body' extends keyof O
@@ -598,5 +615,5 @@ export type MutateEndpoint<
   true,
   O['body'],
   any,
-  O & { body: any; method: 'POST' | 'PUT' | 'PATCH' }
+  O & { body: any; method: 'POST' | 'PUT' | 'PATCH' | 'DELETE' }
 >;