@zajno/common 2.5.0 → 2.6.0

package/types/api/endpoint.d.ts

@@ -1,38 +1,47 @@
-import { AnyObject } from '../types/index.js';
 import { Path } from '../structures/path/index.js';
 import { EndpointMethods } from './methods.js';
-import { IEndpointInfo } from './endpoint.types.js';
+import type { IEndpointInfo } from './endpoint.types.js';
+/** @import { buildApiCaller } from "./call" */
+/** Not an ideal way to merge type because overlapping fields will be incorrectly overridden.
+ *
+ * Extractor types works okay unless there're no overlapping fields when extending endpoint type.
+ *
+ * That's a trade-off, because in case of `Omit` usage extractor type are still okay but chaining like with `asForm()` is broken. */
+type Merge<T, K> = K & T;
 export type { IEndpointInfo };
-export declare class ApiEndpoint<TIn extends object | null, TOut, TPath extends readonly string[], TQuery extends object, TErrors, THeaders> implements IEndpointInfo, IEndpointInfo.IIn<TIn>, IEndpointInfo.IOut<TOut>, IEndpointInfo.IPath<TPath>, IEndpointInfo.IQuery<TQuery>, IEndpointInfo.IErrors<TErrors>, IEndpointInfo.IHeaders<THeaders> {
-    method: EndpointMethods;
-    path: Path.SwitchBuilder<TPath>;
-    isForm?: boolean;
-    displayName?: string;
-    in?: TIn;
-    out?: TOut;
-    queryKeys?: (string & keyof TQuery)[];
-    queryTemplate?: TQuery;
-    errorProcessor?: (err: TErrors) => void;
-    headers?: THeaders;
-    get pathBuilder(): Path.IBuilder;
-    static construct<TIn extends object | null, TOut>(method?: EndpointMethods, displayName?: string): ApiEndpoint<TIn, TOut, readonly [], object, any, AnyObject>;
-    /** Creates an instance and applies 'GET' method for it. */
-    static get<TOut>(displayName?: string): ApiEndpoint<null, TOut, readonly [], object, any, AnyObject>;
-    /** Creates an instance and applies 'POST' method for it. */
-    static post<TIn extends object | null, TOut = void>(displayName?: string): ApiEndpoint<TIn, TOut, readonly [], object, any, AnyObject>;
-    /** Creates an instance and applies 'DELETE' method for it. */
-    static delete<TOut>(displayName?: string): ApiEndpoint<null, TOut, readonly [], object, any, AnyObject>;
+/**
+ * Defines REST API endpoint.
+ *
+ * Endpoint object can be used in a caller method (see {@link buildApiCaller}) to make a request.
+ *
+ * Basic definition {@link IEndpointInfo} which can be extended with additional properties and chaining mutation methods, see {@link IEndpointInfo.IForm} for example.
+*/
+export interface ApiEndpoint extends IEndpointInfo {
+    /** Applies specified HTTP method */
+    withMethod(method: EndpointMethods): this;
+    /** Applies GET HTTP method and specifies output type */
+    get<TOut>(): Merge<this, IEndpointInfo.IOut<TOut>>;
+    /** Applies PUT HTTP method and specifies input and output types */
+    put<TIn extends object | null, TOut>(): Merge<this, IEndpointInfo.IIn<TIn> & IEndpointInfo.IOut<TOut>>;
+    /** Applies POST HTTP method and specifies input and output types */
+    post<TIn extends object | null, TOut>(): Merge<this, IEndpointInfo.IIn<TIn> & IEndpointInfo.IOut<TOut>>;
+    /** Applies DELETE HTTP method and specifies output type */
+    delete<TOut>(): Merge<this, IEndpointInfo.IOut<TOut>>;
     /** Applies a type based on {@link Path.IBuilder} type by accepting arguments for {@link Path.construct} function */
-    withPath<P extends Path.BaseInput[]>(...path: P): ApiEndpoint<TIn, TOut, Path.ExtractArgs<Path.CombineBuilders<P>>, TQuery, TErrors, THeaders>;
+    withPath<P extends Path.BaseInput[]>(...path: P): Merge<this, IEndpointInfo.IPath<Path.ExtractArgs<Path.CombineBuilders<P>>>>;
     /** Applies query type and also store query keys to make api caller be able to distinguish which keys should be ejected from request body. */
-    withQuery<TQ extends object>(...queryKeys: (string & keyof TQ)[]): ApiEndpoint<TIn, TOut, TPath, TQ, TErrors, THeaders>;
+    withQuery<TQ extends object>(...queryKeys: (string & keyof TQ)[]): Merge<this, IEndpointInfo.IQuery<TQ>>;
     /** Applies error type, optionally stores error processor. */
-    withErrors<TErr>(errorProcessor?: (err: TErr) => void): ApiEndpoint<TIn, TOut, TPath, TQuery, TErr, THeaders>;
+    withErrors<TErr>(errorProcessor?: (err: TErr) => void): Merge<this, IEndpointInfo.IErrors<TErr>>;
     /** Applies headers type. */
-    withHeaders<THeads>(_headersMarker?: THeads): ApiEndpoint<TIn, TOut, TPath, TQuery, TErrors, THeads>;
-    /** Marks this instance as one has to be sent as form.
-     *
-     * TODO: introduce more content types support.
-     */
-    asForm(): this;
+    withHeaders<THeads>(_headersMarker?: THeads): Merge<this, IEndpointInfo.IHeaders<THeads>>;
+}
+export declare namespace ApiEndpoint {
+    function isEndpoint(obj: any): obj is ApiEndpoint;
+    interface IBuilder<T extends ApiEndpoint = ApiEndpoint> {
+        (displayName?: string): T;
+        extend<TExt>(extender: (base: T) => T & TExt): IBuilder<T & TExt>;
+    }
+    type IBuilderExtender<T> = <TBase extends ApiEndpoint>(base: TBase) => TBase & T;
+    const create: IBuilder<ApiEndpoint>;
 }

package/types/api/endpoint.types.d.ts

@@ -1,22 +1,32 @@
-import { Path } from '../structures/path/index.js';
-import { AnyObject, Coalesce, EmptyObjectNullable } from '../types/misc.js';
-import { EndpointMethods } from './methods.js';
-export interface IEndpointInfo {
-    readonly method: EndpointMethods;
-    readonly isForm?: boolean;
-    readonly pathBuilder: Path.IBuilder;
-    readonly displayName?: string;
-    readonly errorProcessor?: (err?: any) => void;
-    readonly queryKeys?: string[];
+import type { Path } from '../structures/path/index.js';
+import type { AnyObject, Coalesce, EmptyObjectNullable } from '../types/misc.js';
+import type { EndpointMethods } from './methods.js';
+/**
+ * Definition of an abstract REST API endpoint.
+ */
+export interface IEndpointInfo extends IEndpointInfo.Base, IEndpointInfo.IPath<readonly string[]>, IEndpointInfo.IErrors<any>, IEndpointInfo.IQuery<AnyObject> {
 }
 export declare namespace IEndpointInfo {
+    export type Base = {
+        /** HTTP method of the endpoint, defaults to `GET`. See {@link EndpointMethods}  */
+        readonly method: EndpointMethods;
+        /** Optional display name, for logging purposes. */
+        readonly displayName?: string;
+    };
     export interface IIn<TIn extends object | null> {
+        /** Marker for defining input type. */
         readonly in?: TIn;
     }
-    export class IOut<TOut> {
+    export interface IOut<TOut> {
+        /** Marker for defining output type. */
         readonly out?: TOut;
     }
     export interface IPath<TPath extends readonly string[]> {
+        /**
+         * Endpoint path, which can be static (just a string) or parametrized.
+         *
+         * See {@link Path}
+         */
         readonly path: Path.SwitchBuilder<TPath>;
     }
     export type QueryKeysType = boolean | string | string[] | number | number[];
@@ -24,13 +34,14 @@ export declare namespace IEndpointInfo {
     export interface IQuery<TQuery extends object> {
         /** actual query keys to be used in argument object parsing */
         readonly queryKeys?: (string & keyof TQuery)[];
-        /** dummy marker object for better type determining */
+        /** Marker type for defining query shape. */
         readonly queryTemplate?: TQuery;
     }
     export interface IErrors<TErrors> {
         readonly errorProcessor?: (err: TErrors) => void;
     }
     export interface IHeaders<THeaders> {
+        /** Marker type for defining endpoint extra headers. */
         readonly headers?: THeaders;
     }
     type Any = AnyObject;

package/types/api/error.d.ts

@@ -1,4 +1,5 @@
 import { StatusCodes } from './statusCodes.js';
+/** Base DTO for getting a error response */
 export type ApiErrorResponse<TCause = never, TErrors = number | string> = {
     code?: TErrors;
     message?: string;
@@ -8,6 +9,7 @@ export type ApiErrorResponse<TCause = never, TErrors = number | string> = {
 export declare namespace ApiErrorResponse {
     function create<TCause = never, TErrors = number | string>(code: TErrors, message?: string, cause?: TCause): ApiErrorResponse<TCause, TErrors>;
 }
+/** An Error to be thrown as an API error, and be caught */
 export declare class ApiError<TCause = unknown, TCodes extends number = StatusCodes, TErrors extends number | string = number | string> extends Error {
     readonly status: TCodes;
     readonly code: TErrors;

package/types/api/extensions/contentType.d.ts

@@ -0,0 +1,22 @@
+import type { ApiEndpoint, IEndpointInfo } from '../endpoint.js';
+/**
+ * Request Content-Type extension for endpoint.
+ *
+ */
+export interface IEndpointInputContentType {
+    /** Returns if endpoint is marked as form. */
+    readonly contentType?: string;
+    /** Marks this endpoint with Content-Type header to be set as 'application/x-www-form-urlencoded'. */
+    asUrlEncoded(): this;
+    /** Marks this endpoint with Content-Type header to be set as 'multipart/form-data'. */
+    asMultipartForm(): this;
+    /** Marks this endpoint with Content-Type header to be set as 'application/json'. */
+    asJson(): this;
+    /** Marks this endpoint with Content-Type header to be set as passed value. */
+    withContentType(contentType: string): this;
+}
+export declare namespace IEndpointInputContentType {
+    const extender: ApiEndpoint.IBuilderExtender<IEndpointInputContentType>;
+    function guard(api: IEndpointInfo): api is (IEndpointInfo & IEndpointInputContentType);
+    function tryApplyContentType(api: IEndpointInfo, headers: Record<string, string>): void;
+}

package/types/api/extensions/index.d.ts

@@ -0,0 +1,2 @@
+export * from './contentType.js';
+export * from './validation.js';

package/types/api/extensions/validation.d.ts

@@ -0,0 +1,12 @@
+import type { ApiEndpoint } from '../endpoint.js';
+import type { IEndpointInfo } from '../endpoint.types.js';
+export interface IEndpointInputValidation {
+    readonly validate?: IEndpointInputValidation.Validator<IEndpointInfo.ExtractIn<this>>;
+    withValidation(validator: IEndpointInputValidation.Validator<IEndpointInfo.ExtractIn<this>>): this;
+}
+export declare namespace IEndpointInputValidation {
+    type Validator<TIn> = (input: TIn) => Promise<void> | void;
+    const extender: ApiEndpoint.IBuilderExtender<IEndpointInputValidation>;
+    function guard(api: IEndpointInfo): api is (IEndpointInfo & IEndpointInputValidation);
+    function tryValidate(api: IEndpointInfo, input: IEndpointInfo.ExtractIn<IEndpointInfo>): void | Promise<void>;
+}

package/types/api/helpers.d.ts

@@ -4,6 +4,6 @@ export declare const DefaultSettings: {
     basePrefix: string;
 };
 export declare function setDefaults(settings: Partial<typeof DefaultSettings>): void;
-export declare function getPath<T extends IEndpointInfo>(endpoint: T, pathArgs: IEndpointInfo.ExtractPath<T>, prefix?: string | boolean): string;
+export declare function getPath<T extends IEndpointInfo.IPath<K>, K extends readonly string[]>(endpoint: T, pathArgs: IEndpointInfo.ExtractPath<T>, prefix?: string | boolean): string;
 export declare function getTemplate<T extends IEndpointInfo>(endpoint: T, prefix?: string | boolean): string;
 export declare function getFormattedDisplayName(endpoint: IEndpointInfo): string;

package/types/api/logging.d.ts

@@ -1,4 +1,10 @@
-import { Nullable } from '../types/index.js';
+import { ILogger } from '../logger/abstractions.js';
+import type { Nullable } from '../types/index.js';
+import type { RequestConfigDetails } from './call.js';
+/** Describes the way a request is logged.
+ *
+ * Useful for granular control over logging, especially in production.
+*/
 export type LogTypes<TIn = any, TOut = any> = boolean | 'full' | LogTypes.Dir | {
     req?: boolean | LogTypes.LogFn<TIn>;
     res?: boolean | LogTypes.LogFn<TOut>;
@@ -6,8 +12,28 @@ export type LogTypes<TIn = any, TOut = any> = boolean | 'full' | LogTypes.Dir |
 export declare namespace LogTypes {
     type Dir = 'req' | 'res';
     type LogFn<T = any> = (data: T) => void | string | any[];
+    /**
+     * Get the enabled state of a log type.
+     * @param type Log type to check.
+     * @param dir Direction of log, either request or response.
+    */
     function getIsEnabled<T = unknown>(type: Nullable<LogTypes>, dir: Dir): {
         enabled: boolean;
         formatter?: Nullable<(data: T) => unknown>;
     };
+    /**
+     * An example implementation for logging logic (overload for a request with no data).
+     *
+     * See the other overload for more details.
+    */
+    function logCall(logger: ILogger, cfg: RequestConfigDetails, dir: 'req'): void;
+    /**
+     * An example implementation for logging logic (overload for a request with data).
+     *
+     * * Skips logging if the request is a GET and has no data.
+     * * Checks if logging is enabled for the given direction.
+     * * Formats the data if a custom formatter is provided.
+     * * Logs the data via specified logger.
+    */
+    function logCall(logger: ILogger, cfg: RequestConfigDetails, dir: 'res', data: unknown): void;
 }