@koine/api 2.0.0-beta.131 → 2.0.0-beta.133

package/ApiError.d.ts

@@ -1,4 +1,11 @@
 import type { Api } from "./types";
+/**
+ * Custom `ApiError` class extending `Error` to throw in failed response.
+ *
+ * @see https://eslint.org/docs/rules/no-throw-literal
+ * @see https://github.com/sindresorhus/ky/blob/main/source/errors/HTTPError.ts
+ *
+ */
 export declare class ApiError<TResponseFail extends Api.ResponseFail = unknown> extends Error {
     constructor(result: Api.ResultFail<TResponseFail>);
 }

package/createApi.d.ts

@@ -1,3 +1,9 @@
 import type { Api } from "./types";
+/**
+ * Create api client
+ *
+ * @param apiName Short name to use in debug logs
+ * @param baseUrl Either relativ eor absolute, it must end without trailing slash
+ */
 export declare let createApi: <TEndpoints extends Api.Endpoints>(apiName: string, baseUrl: string, options?: Api.ClientOptions) => Api.Client<TEndpoints>;
 export default createApi;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@koine/api",
   "sideEffects": false,
   "dependencies": {
-    "@koine/utils": "2.0.0-beta.131"
+    "@koine/utils": "2.0.0-beta.133"
   },
   "exports": {
     "./swr/createSwrApi": {
@@ -88,5 +88,5 @@
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
   "types": "./index.esm.d.ts",
-  "version": "2.0.0-beta.131"
+  "version": "2.0.0-beta.133"
 }

package/swr/createSwrApi.d.ts

@@ -1,9 +1,31 @@
 import { type BareFetcher, type SWRConfiguration, type SWRResponse } from "swr";
 import type { Api } from "../types";
 type SWRConfigurationExtended<Data = any, Error = any, Fn extends BareFetcher<any> = BareFetcher<any>> = SWRConfiguration<Data, Error, Fn> & {
+    /**
+     * Conditional fetching as option
+     *
+     * Moving this to an option allows us to keep the endpoints typed dictionary,
+     * e.g. we can write:
+     *
+     * ```js
+     * const { data, mutate } = myApi.use("User/{id}",
+     *  { params: { id: aVariableMaybeContainingAnId || "" }, },
+     *  { when: !!aVariableMaybeContainingAnId }
+     * );
+     *
+     * // we still have typed `data`, `mutate`
+     * ```
+     * @see https://swr.vercel.app/docs/conditional-fetching
+     */
     when?: boolean | (() => boolean);
 };
+/**
+ * @private
+ */
 export declare let createUseApi: <TEndpoints extends Api.Endpoints>(api: Api.Client<TEndpoints>) => <TEndpoint extends Api.EndpointUrl<TEndpoints>>(endpoint: TEndpoint, options?: Api.EndpointOptions<TEndpoints, TEndpoint, "get">, config?: SWRConfigurationExtended<Api.EndpointResponseOk<TEndpoints, TEndpoint, "get">, Api.EndpointResponseFail<TEndpoints, TEndpoint, "get">>) => SWRResponse<Api.EndpointResponseOk<TEndpoints, TEndpoint, "get">, Api.EndpointResponseFail<TEndpoints, TEndpoint, "get">>;
+/**
+ * It creates an api client extended with auto-generated SWR wrapper hooks
+ */
 export declare let createSwrApi: <TEndpoints extends Api.Endpoints>(apiName: string, baseUrl: string, options?: Api.ClientOptions | undefined) => Api.Client<TEndpoints> & {
     use: ReturnType<typeof createUseApi<TEndpoints>>;
 };

package/swr-mutation/createSwrMutationApi.d.ts

@@ -4,6 +4,9 @@ import type { Api } from "../types";
 type MutationRequestMethod = Exclude<Api.RequestMethod, "get">;
 type MutationHookName = Exclude<keyof Api.HooksMapsByName, "use">;
 type KoineApiMethodHookSWR<THookName extends MutationHookName, TEndpoints extends Api.Endpoints> = <TEndpoint extends Api.EndpointUrl<TEndpoints>, TMethod extends MutationRequestMethod = Api.HooksMapsByName[THookName]>(endpoint: TEndpoint, options?: Api.EndpointOptions<TEndpoints, TEndpoint, TMethod>, config?: SWRMutationConfiguration<Api.EndpointResponseOk<TEndpoints, TEndpoint, TMethod>, Api.EndpointResponseFail<TEndpoints, TEndpoint, TMethod>, TEndpoint, Api.EndpointOptions<TEndpoints, TEndpoint, TMethod>>) => SWRMutationResponse<Api.EndpointResponseOk<TEndpoints, TEndpoint, TMethod>, Api.EndpointResponseFail<TEndpoints, TEndpoint, TMethod>, TEndpoint, Api.EndpointOptions<TEndpoints, TEndpoint, TMethod>>;
+/**
+ * It creates an api client extended with auto-generated SWR wrapper hooks
+ */
 export declare let createSwrMutationApi: <TEndpoints extends Api.Endpoints>(apiName: string, baseUrl: string, options?: Api.ClientOptions | undefined) => Api.Client<TEndpoints> & {
     usePost: KoineApiMethodHookSWR<"usePost", TEndpoints>;
     usePut: KoineApiMethodHookSWR<"usePut", TEndpoints>;

package/types.d.ts

@@ -1,4 +1,7 @@
 type _Response = Response;
+/**
+ * @borrows [awesome-template-literal-types](https://github.com/ghoullier/awesome-template-literal-types#router-params-parsing)
+ */
 type ExtractEndpointParams<T extends string> = string | number extends T ? Record<string, string> : T extends `${infer _Start}{${infer Param}}${infer Rest}` ? {
     [k in Param | keyof ExtractEndpointParams<Rest>]: string | number;
 } : T extends `${infer _Start}{${infer Param}}` ? {
@@ -6,15 +9,60 @@ type ExtractEndpointParams<T extends string> = string | number extends T ? Recor
 } : {};
 export declare namespace Api {
     export type ClientOptions = {
+        /**
+         * Headers will be merged with
+         * ```
+         * { "content-type": "application/json" }
+         * ```
+         *
+         * @default {}
+         */
         headers?: RequestInit["headers"];
+        /**
+         * Basic request options to supply to `fetch`
+         *
+         * @see RequestInit
+         *
+         * @default {}
+         */
         request?: Omit<RequestInit, "body" | "headers" | "method">;
+        /**
+         * Flag to throw error within the catch block, by default we return a
+         * normalised error result {@link ResultFail}
+         *
+         * @default false
+         */
         throwErr?: boolean;
+        /**
+         * Timeout in `ms`, if `falsy` there is no timeout
+         *
+         * @default 10000
+         */
         timeout?: number | false | null;
+        /**
+         * Process request before actual http call
+         *
+         * @default undefined
+         */
         processReq?: RequestProcessor;
+        /**
+         * Process ok/failed response just after http response
+         *
+         * @default undefined
+         */
         processRes?: ResponseProcessorRes;
+        /**
+         * Process maybe-thrown error originated either from `fetch` function
+         * invokation or from its `response.json()` parsing
+         *
+         * @default undefined
+         */
         processErr?: ResponseProcessorErr;
     };
     type ClientMethod<TMethod extends RequestMethod, TEndpoints extends Endpoints> = <TEndpoint extends EndpointUrl<TEndpoints>, TOptions extends EndpointOptions<TEndpoints, TEndpoint, TMethod>, TOk extends ResponseOk = EndpointResponseOk<TEndpoints, TEndpoint, TMethod>, TFail extends ResponseFail = EndpointResponseFail<TEndpoints, TEndpoint, TMethod>>(endpoint: TEndpoint, options?: TOptions) => Promise<EndpointResult<TEndpoints, TEndpoint, TMethod>>;
+    /**
+     * The `api` interface generated by `createApi`
+     */
     export type Client<TEndpoints extends Endpoints> = {
         [TMethod in RequestMethod]: ClientMethod<TMethod, TEndpoints>;
     };
@@ -29,19 +77,51 @@ export declare namespace Api {
     };
     export type EndpointUrl<TEndpoints extends Endpoints> = Extract<keyof TEndpoints, string>;
     type DataTypes<TMethod extends Uppercase<RequestMethod>> = {
+        /**
+         * The request body of a non-GET request
+         */
         json?: RequestJson;
+        /**
+         * The parameters to encode in the URL of the request
+         */
         query?: RequestQuery;
+        /**
+         * The JSON response data returned by the request in case of success
+         */
         ok?: null | unknown;
+        /**
+         * The shape of the error data returned by the request in case of
+         * failure
+         */
         fail?: null | unknown;
     };
     export type RequestMethod = "get" | "post" | "put" | "patch" | "delete";
     type RequestJson = unknown;
     type RequestQuery = unknown;
     type RequestParams = unknown;
+    /**
+     * Request options
+     *
+     * `ClientOptions` can be overriden here at the single request level.
+     */
     type RequestOptions<TEndpoints extends Endpoints, TEndpoint extends EndpointUrl<TEndpoints>, TMethod extends RequestMethod, TJson extends RequestJson, TQuery extends RequestQuery> = Omit<ClientOptions, "processReq"> & {
         processReq?: EndpointRequestProcessor<TEndpoints, TEndpoint, TMethod>;
+        /**
+         * A dictionary to dynamically interpolate endpoint url params, e.g.:
+         *
+         * ```js
+         * myapi.get("user/{id}", { params: { id: "12" }})
+         * ```
+         * results in a call to the endpoint `"user/12"`
+         */
         params?: ExtractEndpointParams<TEndpoint>;
+        /**
+         * Query parameters will be serialized into a string and appended to the URL
+         */
         query?: TQuery;
+        /**
+         * JSON request body
+         */
         json?: TJson;
     };
     export type ResponseOk = unknown;
@@ -73,6 +153,10 @@ export declare namespace Api {
         fail: true;
         data: TResponseFail;
     };
+    /**
+     * The request processor at the client level, this is meant to apply global
+     * transformations to all endpoints requests
+     */
     export type RequestProcessor = (method: RequestMethod, url: string, query: any, json: any, params: any, requestInit: RequestInit) => [
         string,
         RequestQuery,
@@ -80,6 +164,13 @@ export declare namespace Api {
         RequestParams,
         RequestInit
     ];
+    /**
+     * The request processor at the request level, this is meant to apply
+     * transformations to a single endpoint request. Request processor applied at
+     * the whole client level is still applied just before this one, hence one
+     * might set some global processing and override it or undo it at the single
+     * request level.
+     */
     export type EndpointRequestProcessor<TEndpoints extends Endpoints, TEndpoint extends EndpointUrl<TEndpoints>, TMethod extends RequestMethod> = (method: TMethod, url: string, query: EndpointOptions<TEndpoints, TEndpoint, TMethod>["query"], json: EndpointOptions<TEndpoints, TEndpoint, TMethod>["json"], params: EndpointOptions<TEndpoints, TEndpoint, TMethod>["params"], requestInit: RequestInit) => [
         string,
         EndpointOptions<TEndpoints, TEndpoint, TMethod>["query"],
@@ -87,8 +178,23 @@ export declare namespace Api {
         EndpointOptions<TEndpoints, TEndpoint, TMethod>["params"],
         RequestInit
     ];
+    /**
+     * The ok/fail response processor at the request level, this is meant to apply
+     * transformations to a single or all endpoint responses
+     */
     type ResponseProcessorRes = <TResponseOk extends ResponseOk = ResponseOk, TResponseFail extends ResponseFail = ResponseFail>(response: _Response, options: any) => Promise<Result<TResponseOk, TResponseFail>>;
+    /**
+     * The error response processor at the request level, this is meant to apply
+     * transformations to a single or all endpoint responses
+     */
     type ResponseProcessorErr = <TResponseOk extends ResponseOk = ResponseOk, TResponseFail extends ResponseFail = ResponseFail>(msg: string, options: any) => Promise<Result<TResponseOk, TResponseFail>>;
+    /**
+     * Api hooks map for `react`, each request method has its own `use{Method}`
+     * hook.
+     *
+     * These hooks are implemented with different libraries or, in the future as
+     * standalone hooks, see SWR ones to start with.
+     */
     type HooksMaps = {
         [TMethod in RequestMethod]: `use${TMethod extends "get" ? "" : Capitalize<TMethod>}`;
     };
@@ -97,7 +203,33 @@ export declare namespace Api {
     };
     export {};
 }
+/**
+ * To generate all available helpers use in your `API` types:
+ *
+ * @example
+ * ```ts
+ * type Response = Api.Generate.ResponseHelpers<Endpoints>;
+ * type Request = Api.Generate.RequestHelpers<Endpoints>;
+ * type Get = Api.Generate.GetHelpers<Endpoints>;
+ * type Post = Api.Generate.PostHelpers<Endpoints>;
+ * ```
+ */
 export declare namespace Api.Generate {
+    /**
+     * @example
+     * ```ts
+     * // define the type on your `API` types:
+     * type Result = Api.Generate.ResultShortcuts<Endpoints>;
+     *
+     * // consume the type wherever in your app:
+     * type MyResult = API.Result["get"]["my/endpoint"];
+     *
+     * MyResult["ok"];
+     * ^
+     * MyResult["fail"];
+     * ^
+     * ```
+     */
     type ResultShortcuts<TEndpoints extends Endpoints> = {
         [TMethod in RequestMethod]: {
             [TEndpoint in Extract<keyof TEndpoints, string>]: {
@@ -106,19 +238,59 @@ export declare namespace Api.Generate {
             };
         };
     };
+    /**
+     * @example
+     * ```ts
+     * // define the type on your `API` types:
+     * type Response = Api.Generate.ResponseShortcuts<Endpoints>;
+     *
+     * // consume the type wherever in your app:
+     * type MyData = API.Response["get"]["my/endpoint"];
+     * ```
+     */
     type ResponseShortcuts<TEndpoints extends Endpoints> = {
         [TMethod in RequestMethod]: {
             [TEndpoint in Extract<keyof TEndpoints, string>]: GetDataType<TEndpoints, TEndpoint, TMethod, "ok">;
         };
     };
+    /**
+     * @example
+     * ```ts
+     * // define the type on your `API` types:
+     * type Request = Api.Generate.RequestShortcuts<Endpoints>;
+     *
+     * // consume the type wherever in your app:
+     * type MyData = API.Request["get"]["my/endpoint"];
+     * ```
+     */
     type RequestShortcuts<TEndpoints extends Endpoints> = {
         [TMethod in RequestMethod]: {
             [TEndpoint in Extract<keyof TEndpoints, string>]: TMethod extends "get" ? GetDataType<TEndpoints, TEndpoint, TMethod, "query"> : GetDataType<TEndpoints, TEndpoint, TMethod, "json">;
         };
     };
+    /**
+     * @example
+     * ```ts
+     * // define the type on your `API` types:
+     * type Get = Api.Generate.ResponseShortcuts<Endpoints>;
+     *
+     * // consume the type wherever in your app:
+     * type MyData = API.Get["my/endpoint"];
+     * ```
+     */
     type GetShortcuts<TEndpoints extends Endpoints> = {
         [TEndpoint in Extract<keyof TEndpoints, string>]: GetDataType<TEndpoints, TEndpoint, "get", "ok">;
     };
+    /**
+     * @example
+     * ```ts
+     * // define the type on your `API` types:
+     * type Post = Api.Generate.ResponseShortcuts<Endpoints>;
+     *
+     * // consume the type wherever in your app:
+     * type MyData = API.Post["my/endpoint"];
+     * ```
+     */
     type PostShortcuts<TEndpoints extends Endpoints> = {
         [TEndpoint in Extract<keyof TEndpoints, string>]: GetDataType<TEndpoints, TEndpoint, "post", "ok">;
     };