@koine/api 2.0.0-beta.132 → 2.0.0-beta.134

package/ApiError.cjs.js

@@ -2,13 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-/**
- * 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
- *
- */class ApiError extends Error{constructor(r){super(`Request failed with ${r.status} ${r.msg}`),this.name="ApiError",Object.assign(this,r);}}
+class ApiError extends Error{constructor(r){super(`Request failed with ${r.status} ${r.msg}`),this.name="ApiError",Object.assign(this,r);}}
 
 exports.ApiError = ApiError;
 exports.default = ApiError;

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/ApiError.esm.js

@@ -1,9 +1,3 @@
-/**
- * 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
- *
- */class ApiError extends Error{constructor(r){super(`Request failed with ${r.status} ${r.msg}`),this.name="ApiError",Object.assign(this,r);}}
+class ApiError extends Error{constructor(r){super(`Request failed with ${r.status} ${r.msg}`),this.name="ApiError",Object.assign(this,r);}}
 
 export { ApiError, ApiError as default };

package/createApi.cjs.js

@@ -4,24 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var utils = require('@koine/utils');
 
-let o=["get","post","put","patch","delete"];/**
- * Create api client
- *
- * @param apiName Short name to use in debug logs
- * @param baseUrl Either relativ eor absolute, it must end without trailing slash
- */let createApi=(l,a,i)=>{let{headers:s={},request:n={},throwErr:p,timeout:c=1e4,processReq:u,processRes:f,processErr:d}=i||{};return o.reduce((o,i)=>(// @ts-expect-error FIXME: type
-    o[i]=async(o,h)=>{let $,m;let{request:w=n,headers:y=s,timeout:b=c,processReq:g,processRes:E=f,processErr:N=d,throwErr:k=p}=h||{},{params:A,json:C,query:j}=h||{},q=`${a}/${o+"".replace(/^\/*/,"")}`,v={method:i.toUpperCase(),...w,headers:{"content-type":"application/json",...y}};if(u){let e=u(i,q,j,C,A,v);q=e[0],j=e[1],C=e[2],A=e[3],v=e[4];}if(g){let e=g(i,q,j,C,A,v);q=e[0],j=e[1],C=e[2],A=e[3],v=e[4];}if(utils.isFullObject(A))for(let e in A)// TODO: not the greatest assertion...
-    q=q.replace(`{${e}}`,A[e]);let x=Number(b);C&&(v.body=JSON.stringify(C)),x>0&&(// TODO: combine multiple abort signals
-    // @see https://dev.to/rashidshamloo/adding-timeout-and-multiple-abort-signals-to-fetch-typescriptreact-33bb
-    $=new AbortController,m=setTimeout(()=>$.abort(),x),v.signal=$.signal),j&&// FIXME: ts-expect-error this assertion is not the best, but nevermind for now
-    (q+=utils.buildUrlQueryString(j));let O=null,R=null,T="";try{O=await fetch(q,v);}catch(e){T=utils.errorToString(e);}if(m&&clearTimeout(m),O)try{R=E?await E(O,h||{}):await O.json();}catch(e){T=utils.errorToString(e);}if(null===R&&(R=N?await N(T,h||{}):// this error should only happen on network errors or wrong API urls
-    // there is no specific HTTP error for this, we can consider these
-    // two statuses though:
-    // - [100 Continue](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/100)
-    // - [501 Not Implemented](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501)
-    {data:null,msg:T,status:100,fail:!0,ok:!1}),k&&R?.fail)// throw new ApiError<Failed>(result);
-    // I prefer to throw an object literal despite what eslint says
-    throw R;if("development"===process.env.NODE_ENV){let e=`${R?.status}: api[${l}] ${i.toUpperCase()} ${q}`;R?.ok?console.info(`🟢 ${e}`):console.info(`🔴 ${e}`);}return R},o),{})};
+let o=["get","post","put","patch","delete"];let createApi=(l,a,i)=>{let{headers:s={},request:n={},throwErr:p,timeout:c=1e4,processReq:u,processRes:f,processErr:d}=i||{};return o.reduce((o,i)=>(o[i]=async(o,h)=>{let $,m;let{request:w=n,headers:y=s,timeout:b=c,processReq:g,processRes:E=f,processErr:N=d,throwErr:k=p}=h||{},{params:A,json:C,query:j}=h||{},q=`${a}/${o+"".replace(/^\/*/,"")}`,v={method:i.toUpperCase(),...w,headers:{"content-type":"application/json",...y}};if(u){let e=u(i,q,j,C,A,v);q=e[0],j=e[1],C=e[2],A=e[3],v=e[4];}if(g){let e=g(i,q,j,C,A,v);q=e[0],j=e[1],C=e[2],A=e[3],v=e[4];}if(utils.isFullObject(A))for(let e in A)q=q.replace(`{${e}}`,A[e]);let x=Number(b);C&&(v.body=JSON.stringify(C)),x>0&&($=new AbortController,m=setTimeout(()=>$.abort(),x),v.signal=$.signal),j&&(q+=utils.buildUrlQueryString(j));let O=null,R=null,T="";try{O=await fetch(q,v);}catch(e){T=utils.errorToString(e);}if(m&&clearTimeout(m),O)try{R=E?await E(O,h||{}):await O.json();}catch(e){T=utils.errorToString(e);}if(null===R&&(R=N?await N(T,h||{}):{data:null,msg:T,status:100,fail:!0,ok:!1}),k&&R?.fail)throw R;if("development"===process.env.NODE_ENV){let e=`${R?.status}: api[${l}] ${i.toUpperCase()} ${q}`;R?.ok?console.info(`🟢 ${e}`):console.info(`🔴 ${e}`);}return R},o),{})};
 
 exports.createApi = createApi;
 exports.default = createApi;

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/createApi.esm.js

@@ -1,22 +1,5 @@
 import { isFullObject, buildUrlQueryString, errorToString } from '@koine/utils';
 
-let o=["get","post","put","patch","delete"];/**
- * Create api client
- *
- * @param apiName Short name to use in debug logs
- * @param baseUrl Either relativ eor absolute, it must end without trailing slash
- */let createApi=(l,a,i)=>{let{headers:s={},request:n={},throwErr:p,timeout:c=1e4,processReq:u,processRes:f,processErr:d}=i||{};return o.reduce((o,i)=>(// @ts-expect-error FIXME: type
-    o[i]=async(o,h)=>{let $,m;let{request:w=n,headers:y=s,timeout:b=c,processReq:g,processRes:E=f,processErr:N=d,throwErr:k=p}=h||{},{params:A,json:C,query:j}=h||{},q=`${a}/${o+"".replace(/^\/*/,"")}`,v={method:i.toUpperCase(),...w,headers:{"content-type":"application/json",...y}};if(u){let e=u(i,q,j,C,A,v);q=e[0],j=e[1],C=e[2],A=e[3],v=e[4];}if(g){let e=g(i,q,j,C,A,v);q=e[0],j=e[1],C=e[2],A=e[3],v=e[4];}if(isFullObject(A))for(let e in A)// TODO: not the greatest assertion...
-    q=q.replace(`{${e}}`,A[e]);let x=Number(b);C&&(v.body=JSON.stringify(C)),x>0&&(// TODO: combine multiple abort signals
-    // @see https://dev.to/rashidshamloo/adding-timeout-and-multiple-abort-signals-to-fetch-typescriptreact-33bb
-    $=new AbortController,m=setTimeout(()=>$.abort(),x),v.signal=$.signal),j&&// FIXME: ts-expect-error this assertion is not the best, but nevermind for now
-    (q+=buildUrlQueryString(j));let O=null,R=null,T="";try{O=await fetch(q,v);}catch(e){T=errorToString(e);}if(m&&clearTimeout(m),O)try{R=E?await E(O,h||{}):await O.json();}catch(e){T=errorToString(e);}if(null===R&&(R=N?await N(T,h||{}):// this error should only happen on network errors or wrong API urls
-    // there is no specific HTTP error for this, we can consider these
-    // two statuses though:
-    // - [100 Continue](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/100)
-    // - [501 Not Implemented](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501)
-    {data:null,msg:T,status:100,fail:!0,ok:!1}),k&&R?.fail)// throw new ApiError<Failed>(result);
-    // I prefer to throw an object literal despite what eslint says
-    throw R;if("development"===process.env.NODE_ENV){let e=`${R?.status}: api[${l}] ${i.toUpperCase()} ${q}`;R?.ok?console.info(`🟢 ${e}`):console.info(`🔴 ${e}`);}return R},o),{})};
+let o=["get","post","put","patch","delete"];let createApi=(l,a,i)=>{let{headers:s={},request:n={},throwErr:p,timeout:c=1e4,processReq:u,processRes:f,processErr:d}=i||{};return o.reduce((o,i)=>(o[i]=async(o,h)=>{let $,m;let{request:w=n,headers:y=s,timeout:b=c,processReq:g,processRes:E=f,processErr:N=d,throwErr:k=p}=h||{},{params:A,json:C,query:j}=h||{},q=`${a}/${o+"".replace(/^\/*/,"")}`,v={method:i.toUpperCase(),...w,headers:{"content-type":"application/json",...y}};if(u){let e=u(i,q,j,C,A,v);q=e[0],j=e[1],C=e[2],A=e[3],v=e[4];}if(g){let e=g(i,q,j,C,A,v);q=e[0],j=e[1],C=e[2],A=e[3],v=e[4];}if(isFullObject(A))for(let e in A)q=q.replace(`{${e}}`,A[e]);let x=Number(b);C&&(v.body=JSON.stringify(C)),x>0&&($=new AbortController,m=setTimeout(()=>$.abort(),x),v.signal=$.signal),j&&(q+=buildUrlQueryString(j));let O=null,R=null,T="";try{O=await fetch(q,v);}catch(e){T=errorToString(e);}if(m&&clearTimeout(m),O)try{R=E?await E(O,h||{}):await O.json();}catch(e){T=errorToString(e);}if(null===R&&(R=N?await N(T,h||{}):{data:null,msg:T,status:100,fail:!0,ok:!1}),k&&R?.fail)throw R;if("development"===process.env.NODE_ENV){let e=`${R?.status}: api[${l}] ${i.toUpperCase()} ${q}`;R?.ok?console.info(`🟢 ${e}`):console.info(`🔴 ${e}`);}return R},o),{})};
 
 export { createApi, createApi as default };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@koine/api",
   "sideEffects": false,
   "dependencies": {
-    "@koine/utils": "2.0.0-beta.132"
+    "@koine/utils": "2.0.0-beta.134"
   },
   "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.132"
+  "version": "2.0.0-beta.134"
 }

package/swr/createSwrApi.cjs.js

@@ -6,42 +6,7 @@ var e = require('swr');
 var utils = require('@koine/utils');
 var createApi = require('../createApi.cjs.js');
 
-/**
-   * 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
-   *//**
- * @private
- */let createUseApi=t=>(i,o,p)=>{// const fetcher = async (_endpoint: TEndpoint) => {
-    //   try {
-    //     const { ok, data } = await api.get(_endpoint, {
-    //         ...(options || {}),
-    //         throwErr: true,
-    //       });
-    //       if (ok) {
-    //         return data;
-    //       }
-    //       throw new Error() as unknown as Api.EndpointResponseFail<TEndpoints, TEndpoint, TMethod>;
-    //     } catch(e) {
-    //       throw new Error() as unknown as Api.EndpointResponseFail<TEndpoints, TEndpoint, TMethod>;;
-    //     }
-    //   };
-    // }
-    let a=async()=>{let{data:e}=await t.get(i,{...o||{},throwErr:!0});return e};// <Data = any, Error = any>(key: Key, config: SWRConfigurationExtended<Data, Error, Fetcher<Data>> | undefined): SWRResponse<Data, Error>;
-    return e(p?.when===!1||utils.isFunction(p?.when)&&p?.when()===!1?null:o?[i,o]:[i],a,p)};/**
- * It creates an api client extended with auto-generated SWR wrapper hooks
- */let createSwrApi=(...e)=>{let r=createApi.createApi(...e);return r.use=createUseApi(r),r};
+let createUseApi=t=>(i,o,p)=>{let a=async()=>{let{data:e}=await t.get(i,{...o||{},throwErr:!0});return e};return e(p?.when===!1||utils.isFunction(p?.when)&&p?.when()===!1?null:o?[i,o]:[i],a,p)};let createSwrApi=(...e)=>{let r=createApi.createApi(...e);return r.use=createUseApi(r),r};
 
 exports.createSwrApi = createSwrApi;
 exports.createUseApi = createUseApi;

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/createSwrApi.esm.js

@@ -2,41 +2,6 @@ import e from 'swr';
 import { isFunction } from '@koine/utils';
 import { createApi } from '../createApi.esm.js';
 
-/**
-   * 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
-   *//**
- * @private
- */let createUseApi=t=>(i,o,p)=>{// const fetcher = async (_endpoint: TEndpoint) => {
-    //   try {
-    //     const { ok, data } = await api.get(_endpoint, {
-    //         ...(options || {}),
-    //         throwErr: true,
-    //       });
-    //       if (ok) {
-    //         return data;
-    //       }
-    //       throw new Error() as unknown as Api.EndpointResponseFail<TEndpoints, TEndpoint, TMethod>;
-    //     } catch(e) {
-    //       throw new Error() as unknown as Api.EndpointResponseFail<TEndpoints, TEndpoint, TMethod>;;
-    //     }
-    //   };
-    // }
-    let a=async()=>{let{data:e}=await t.get(i,{...o||{},throwErr:!0});return e};// <Data = any, Error = any>(key: Key, config: SWRConfigurationExtended<Data, Error, Fetcher<Data>> | undefined): SWRResponse<Data, Error>;
-    return e(p?.when===!1||isFunction(p?.when)&&p?.when()===!1?null:o?[i,o]:[i],a,p)};/**
- * It creates an api client extended with auto-generated SWR wrapper hooks
- */let createSwrApi=(...e)=>{let r=createApi(...e);return r.use=createUseApi(r),r};
+let createUseApi=t=>(i,o,p)=>{let a=async()=>{let{data:e}=await t.get(i,{...o||{},throwErr:!0});return e};return e(p?.when===!1||isFunction(p?.when)&&p?.when()===!1?null:o?[i,o]:[i],a,p)};let createSwrApi=(...e)=>{let r=createApi(...e);return r.use=createUseApi(r),r};
 
 export { createSwrApi, createUseApi, createSwrApi as default };

package/swr-mutation/createSwrMutationApi.cjs.js

@@ -6,15 +6,7 @@ var r = require('swr/mutation');
 var createApi = require('../createApi.cjs.js');
 var createSwrApi = require('../swr/createSwrApi.cjs.js');
 
-let a=(t,e)=>(a,o,i)=>// config.fetcher = sender;
-        r(// @ts-expect-error FIXME: I can't get it...
-        o?[a,o]:a,async(// if the first argument is an array the second one are the base options
-        // defined when calling the usePost/Put/etc. hook, these will be overriden
-        // by the _options just here below
-        r,// these are the options arriving when calling `trigger({ json, query, etc... })
-        a)=>{let o=Array.isArray(r)?r[0]:r,i=Array.isArray(r)?r[1]:{},{ok:p,data:s}=await t[e](o,{...i,...a.arg||{},throwErr:!0});return s},i);/**
- * It creates an api client extended with auto-generated SWR wrapper hooks
- */let createSwrMutationApi=(...r)=>{let o=createApi.createApi(...r);return o.use=createSwrApi.createUseApi(o),["post","put","patch","delete"].forEach(r=>{o[`use${r.charAt(0).toUpperCase()+r.slice(1)}`]=a(o,r);}),o};
+let a=(t,e)=>(a,o,i)=>r(o?[a,o]:a,async(r,a)=>{let o=Array.isArray(r)?r[0]:r,i=Array.isArray(r)?r[1]:{},{ok:p,data:s}=await t[e](o,{...i,...a.arg||{},throwErr:!0});return s},i);let createSwrMutationApi=(...r)=>{let o=createApi.createApi(...r);return o.use=createSwrApi.createUseApi(o),["post","put","patch","delete"].forEach(r=>{o[`use${r.charAt(0).toUpperCase()+r.slice(1)}`]=a(o,r);}),o};
 
 exports.createSwrMutationApi = createSwrMutationApi;
 exports.default = createSwrMutationApi;

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/swr-mutation/createSwrMutationApi.esm.js

@@ -2,14 +2,6 @@ import r from 'swr/mutation';
 import { createApi } from '../createApi.esm.js';
 import { createUseApi } from '../swr/createSwrApi.esm.js';
 
-let a=(t,e)=>(a,o,i)=>// config.fetcher = sender;
-        r(// @ts-expect-error FIXME: I can't get it...
-        o?[a,o]:a,async(// if the first argument is an array the second one are the base options
-        // defined when calling the usePost/Put/etc. hook, these will be overriden
-        // by the _options just here below
-        r,// these are the options arriving when calling `trigger({ json, query, etc... })
-        a)=>{let o=Array.isArray(r)?r[0]:r,i=Array.isArray(r)?r[1]:{},{ok:p,data:s}=await t[e](o,{...i,...a.arg||{},throwErr:!0});return s},i);/**
- * It creates an api client extended with auto-generated SWR wrapper hooks
- */let createSwrMutationApi=(...r)=>{let o=createApi(...r);return o.use=createUseApi(o),["post","put","patch","delete"].forEach(r=>{o[`use${r.charAt(0).toUpperCase()+r.slice(1)}`]=a(o,r);}),o};
+let a=(t,e)=>(a,o,i)=>r(o?[a,o]:a,async(r,a)=>{let o=Array.isArray(r)?r[0]:r,i=Array.isArray(r)?r[1]:{},{ok:p,data:s}=await t[e](o,{...i,...a.arg||{},throwErr:!0});return s},i);let createSwrMutationApi=(...r)=>{let o=createApi(...r);return o.use=createUseApi(o),["post","put","patch","delete"].forEach(r=>{o[`use${r.charAt(0).toUpperCase()+r.slice(1)}`]=a(o,r);}),o};
 
 export { createSwrMutationApi, createSwrMutationApi as default };

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">;
     };