@koine/api 2.0.0-beta.20 → 2.0.0-beta.201

package/types.d.ts

@@ -0,0 +1,313 @@
+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}}` ? {
+    [k in Param]: string | number;
+} : {};
+export declare namespace Api {
+    export type ClientOptions = {
+        /**
+         * Optionally override the `fetch` function
+         *
+         * @default fetch - The standard {@link fetch}
+         */
+        fetchFn?: typeof fetch;
+        /**
+         * 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;
+        /**
+         * Log level:
+         *
+         * - `0`: silent
+         * - `1`: ok/fail logging
+         *
+         * @default 0
+         */
+        log?: 0 | 1;
+    };
+    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>;
+    };
+    export type GetDataType<TEndpoints extends Endpoints, TEndpoint extends EndpointUrl<TEndpoints>, TMethod extends RequestMethod, TDataType extends keyof DataTypes<Uppercase<TMethod>>> = TEndpoints[TEndpoint][Uppercase<TMethod>] extends DataTypes<Uppercase<TMethod>> ? TEndpoints[TEndpoint][Uppercase<TMethod>][TDataType] : never;
+    export type EndpointOptions<TEndpoints extends Endpoints, TEndpoint extends EndpointUrl<TEndpoints>, TMethod extends RequestMethod> = RequestOptions<TEndpoints, TEndpoint, TMethod, GetDataType<TEndpoints, TEndpoint, TMethod, "json">, GetDataType<TEndpoints, TEndpoint, TMethod, "query">>;
+    export type EndpointResponseOk<TEndpoints extends Endpoints, TEndpoint extends EndpointUrl<TEndpoints>, TMethod extends RequestMethod> = GetDataType<TEndpoints, TEndpoint, TMethod, "ok">;
+    export type EndpointResponseFail<TEndpoints extends Endpoints, TEndpoint extends EndpointUrl<TEndpoints>, TMethod extends RequestMethod> = GetDataType<TEndpoints, TEndpoint, TMethod, "fail">;
+    type EndpointResult<TEndpoints extends Endpoints, TEndpoint extends EndpointUrl<TEndpoints>, TMethod extends RequestMethod> = Result<EndpointResponseOk<TEndpoints, TEndpoint, TMethod>, EndpointResponseFail<TEndpoints, TEndpoint, TMethod>>;
+    export type Endpoints = Record<string, Endpoint>;
+    type Endpoint = {
+        [TMethod in Uppercase<RequestMethod>]?: DataTypes<TMethod>;
+    };
+    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;
+    export type ResponseFail = unknown;
+    export type ResultOk<TResponse extends ResponseOk = ResponseOk> = {
+        status: _Response["status"];
+        msg: _Response["statusText"];
+        ok: true;
+        fail?: false;
+        data: TResponse;
+    };
+    export type ResultFail<TResponse extends ResponseFail = ResponseFail> = {
+        status: _Response["status"];
+        msg: Error["message"] | _Response["statusText"];
+        ok?: false;
+        fail: true;
+        data: TResponse;
+    };
+    export type Result<TResponseOk extends ResponseOk, TResponseFail extends ResponseFail> = {
+        status: _Response["status"];
+        msg: _Response["statusText"];
+        ok: true;
+        fail?: false;
+        data: TResponseOk;
+    } | {
+        status: _Response["status"];
+        msg: Error["message"] | _Response["statusText"];
+        ok?: false;
+        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,
+        RequestJson,
+        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"],
+        EndpointOptions<TEndpoints, TEndpoint, TMethod>["json"],
+        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>}`;
+    };
+    export type HooksMapsByName = {
+        [K in keyof HooksMaps as HooksMaps[K]]: K;
+    };
+    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>]: {
+                ok: GetDataType<TEndpoints, TEndpoint, TMethod, "ok">;
+                fail: GetDataType<TEndpoints, TEndpoint, TMethod, "fail">;
+            };
+        };
+    };
+    /**
+     * @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">;
+    };
+}
+export {};

package/types.esm.js

@@ -0,0 +1 @@
+