@zajno/common 2.6.6 → 2.7.0

package/types/api/call.config.d.ts

@@ -0,0 +1,25 @@
+import { AnyObject } from '../types/misc.js';
+import type { EndpointCallArgs, IRequestConfig, IRequestMeta, RequestExtra } from './call.types.js';
+import { EndpointsPathsConfig } from './config.js';
+import type { IEndpointInfo } from './endpoint.types.js';
+import type { LogTypes } from './logging.js';
+export declare function createConfig<T extends IEndpointInfo, TExtra extends object = Record<string, any>>(endpointsConfig: EndpointsPathsConfig, api: T, data?: EndpointCallArgs<T> | null, extra?: RequestExtra<T> & TExtra): {
+    config: IRequestConfig<T, IEndpointInfo.ExtractIn<T, object>, TExtra>;
+    resultInput: NonNullable<EndpointCallArgs<T>> | null | undefined;
+    pathInputs: Record<string, string | number>;
+    queryInputs: AnyObject;
+};
+/**
+ * Request meta wrapped in a class for:
+ *
+ * - not being a plain object
+ * - being able to extend it in the future with helpful methods
+ */
+export declare class RequestMeta<T extends IEndpointInfo, TExtra extends object = Record<string, any>> implements IRequestMeta<T, TExtra> {
+    readonly api: T;
+    readonly pathsConfig: EndpointsPathsConfig;
+    readonly log: LogTypes;
+    readonly noLoader: boolean;
+    readonly extra: TExtra;
+    constructor(api: T, pathsConfig?: EndpointsPathsConfig, log?: LogTypes, noLoader?: boolean, extra?: TExtra);
+}

package/types/api/call.types.d.ts

@@ -1,53 +1,56 @@
 import type { AnyObject } from '../types/misc.js';
+import { EndpointsPathsConfig, type IEndpointsPathsConfig } from './config.js';
 import type { IEndpointInfo } from './endpoint.types.js';
 import type { LogTypes } from './logging.js';
 import type { EndpointMethods } from './methods.js';
+import type { CallerHooks } from './hooks.js';
 /** Request options to be used by call implementation (e.g. interceptor). Passed as separate object argument to the call method.  */
 export type RequestExtra<T> = {
     headers?: IEndpointInfo.ExtractHeaders<T>;
     log?: LogTypes<IEndpointInfo.ExtractIn<T>, IEndpointInfo.ExtractOut<T>>;
     noLoader?: boolean;
 };
-export type RequestConfig<TIn> = {
-    method: EndpointMethods | string & Record<never, never>;
+/** axios/fetch compatible interface for data passed as request config */
+export interface IRequestRawConfig<TIn> {
+    method: EndpointMethods;
     url: string;
     data: TIn | null | undefined;
     headers: AnyObject;
-};
+}
+export interface IRequestMeta<T extends IEndpointInfo, TExtra extends object> {
+    readonly api: T;
+    readonly pathsConfig: EndpointsPathsConfig;
+    readonly log: LogTypes;
+    readonly noLoader: boolean;
+    readonly extra: TExtra;
+}
 /** Compiled request config object passed to `request` implementation */
-export type RequestConfigDetails<T extends IEndpointInfo = IEndpointInfo, TIn = IEndpointInfo.ExtractIn<T>, TExtra extends object = Record<string, any>> = RequestConfig<TIn> & {
-    _api: T;
-    _noLoader?: boolean;
-    _log?: LogTypes;
-    /** Additional data passed to the request implementation */
-    _extra?: TExtra;
+export interface IRequestConfig<T extends IEndpointInfo = IEndpointInfo, TIn = IEndpointInfo.ExtractIn<T>, TExtra extends object = Record<string, any>> extends IRequestRawConfig<TIn> {
+    /**
+     * Extends raw config with additional details.
+     * */
+    readonly _meta: IRequestMeta<T, TExtra>;
+}
+export type CallerResponse<TOut> = {
+    data: TOut;
 };
 export type CallerOptions<TExtra extends object = Record<string, any>> = {
     /** Request implementation */
-    request: <TIn, TOut>(config: RequestConfigDetails<IEndpointInfo, TIn, TExtra>) => Promise<{
-        data: TOut;
-    }>;
-    hooks?: {
-        /**
-         * Called before config is created, to validate result input data.
-         * May throw to abort request. Use for input validation if needed.
-         */
-        beforeConfig?: <T extends IEndpointInfo = IEndpointInfo>(api: T, body: IEndpointInfo.ExtractIn<T, object>, pathParams: IEndpointInfo.ExtractPath<T, object>, queryParams: IEndpointInfo.ExtractQuery<T, object>) => Promise<void> | void;
-        /**
-         * Called before request is sent.
-         * The config can be mutated or returned as updated object – in the latter case it will be merged into original config via `Object.assign`.
-         * This is useful for adding headers or modifying request data.
-         */
-        beforeRequest?: <T extends IEndpointInfo = IEndpointInfo, TIn = IEndpointInfo.ExtractIn<T>, TExtra extends object = Record<string, any>>(config: RequestConfigDetails<T, TIn, TExtra>) => Promise<void> | void | Promise<RequestConfigDetails<T, TIn, TExtra>> | RequestConfigDetails<T, TIn, TExtra>;
-    };
+    request: <TIn, TOut>(config: IRequestConfig<IEndpointInfo, TIn, TExtra>) => Promise<CallerResponse<TOut>>;
+    /** Endpoints paths config */
+    config?: IEndpointsPathsConfig;
+    /** Optional hooks for pre- or post-processing request */
+    hooks?: CallerHooks<TExtra> | CallerHooks<TExtra>[];
 };
 type CombineInputs<T extends IEndpointInfo> = IEndpointInfo.ExtractIn<T, object> & IEndpointInfo.ExtractPath<T, object> & IEndpointInfo.ExtractQuery<T, object>;
 export type EndpointCallArgs<T extends IEndpointInfo> = object extends CombineInputs<T> ? (null | undefined | object) : CombineInputs<T>;
 type CallerParams<T extends IEndpointInfo, TExtra extends object> = object extends CombineInputs<T> ? [data?: EndpointCallArgs<T>, extra?: RequestExtra<T> & TExtra] : [data: EndpointCallArgs<T>, extra?: RequestExtra<T> & TExtra];
 export interface GenericApiCaller<TExtra extends object = Record<string, any>> {
     <T extends IEndpointInfo>(api: T, ...[data, extra]: CallerParams<T, TExtra>): Promise<IEndpointInfo.ExtractOut<T>>;
+    readonly config: EndpointsPathsConfig;
 }
 export interface ApiCaller<TEndpoint extends IEndpointInfo, TExtra extends object = Record<string, any>> {
     (...[data, extra]: CallerParams<TEndpoint, TExtra>): Promise<IEndpointInfo.ExtractOut<TEndpoint>>;
+    readonly config: EndpointsPathsConfig;
 }
 export {};

package/types/api/config.d.ts

@@ -0,0 +1,23 @@
+import { Path } from '../structures/path/index.js';
+import type { Nullable } from '../types/misc.js';
+import type { IEndpointInfo } from './endpoint.js';
+export interface IEndpointsPathsConfig {
+    /** Prefix for template args, defaults to `:` */
+    readonly templateArgPrefix: Path.TemplateTransform;
+    /** Base prefix for path, defaults to `/` */
+    readonly basePrefix: string;
+}
+type PrefixOptions = string | boolean;
+export declare class EndpointsPathsConfig implements IEndpointsPathsConfig {
+    readonly templateArgPrefix: Path.TemplateTransform;
+    readonly basePrefix: string;
+    constructor(settings?: IEndpointsPathsConfig);
+    getPath<T extends IEndpointInfo.Base & IEndpointInfo.IPathAbstract>(endpoint: T, pathArgs: IEndpointInfo.ExtractPath<T>, prefix?: PrefixOptions): string;
+    getTemplate<T extends IEndpointInfo>(endpoint: T, prefix?: PrefixOptions): string;
+    getFormattedDisplayName(endpoint: IEndpointInfo): string;
+    getEndpointsEqual(a: Nullable<IEndpointInfo>, b: Nullable<IEndpointInfo>): boolean;
+    private getPrefix;
+}
+/** @deprecated Be careful with using this shared instance. Don't be lazy and create your own! */
+export declare const DefaultSettings: EndpointsPathsConfig;
+export {};

package/types/api/endpoint.d.ts

@@ -29,6 +29,8 @@ export interface ApiEndpoint extends IEndpointInfo.Base {
     withErrors<TErr>(errorProcessor?: (err: TErr) => void): this & IEndpointInfo.IErrors<TErr>;
     /** Applies headers type. */
     withHeaders<THeads>(_headersMarker?: THeads): this & IEndpointInfo.IHeaders<THeads>;
+    /** Helper chain method for finalizing the type. Can make some runtime optimizations as well. */
+    finalize(): IEndpointInfo.Finalized<this>;
 }
 export declare namespace ApiEndpoint {
     function isEndpoint(obj: any): obj is IEndpointInfo;

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

@@ -1,5 +1,6 @@
 import type { Path } from '../structures/path/index.js';
-import type { AnyObject, Coalesce, EmptyObjectNullable } from '../types/misc.js';
+import { RemoveFunctionFields } from '../types/functions.js';
+import type { AnyObject, Coalesce, EmptyObjectNullable, Expand } from '../types/misc.js';
 import type { EndpointMethods } from './methods.js';
 /**
  * Definition of an abstract REST API endpoint.
@@ -61,5 +62,7 @@ export declare namespace IEndpointInfo {
     export type ExtractOut<T> = T extends IOut<infer TOut> ? TOut : never;
     export type ExtractErrors<T> = T extends IErrors<infer TErrors> ? TErrors : Any;
     export type ExtractHeaders<T> = T extends IHeaders<infer THeaders> ? THeaders : Any;
+    type MergeOmit<T, K> = Omit<T, keyof K> & K;
+    export type Finalized<T extends Base> = Expand<Readonly<RemoveFunctionFields<MergeOmit<T, IIn<ExtractIn<T, object | null>>> & MergeOmit<T, IOut<ExtractOut<T>>> & MergeOmit<T, IPath<T extends IPath<infer TPath> ? TPath : Path.IBuilder>> & MergeOmit<T, IQuery<ExtractQuery<T, object>>> & MergeOmit<T, IErrors<ExtractErrors<T>>> & MergeOmit<T, IHeaders<ExtractHeaders<T>>>>>>;
     export {};
 }

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

@@ -1,22 +1,24 @@
 import type { ApiEndpoint, IEndpointInfo } from '../endpoint.js';
+import { CallerHooks } from '../hooks.js';
 /**
  * Request Content-Type extension for endpoint.
  *
  */
 export interface IEndpointInputContentType {
-    /** Returns if endpoint is marked as form. */
+    /** Endpoint request content-type, if was specified. */
     readonly contentType?: string;
-    /** Marks this endpoint with Content-Type header to be set as 'application/x-www-form-urlencoded'. */
+    /** Marks this endpoint with Content-Type request 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'. */
+    /** Marks this endpoint with Content-Type request header to be set as 'multipart/form-data'. */
     asMultipartForm(): this;
-    /** Marks this endpoint with Content-Type header to be set as 'application/json'. */
+    /** Marks this endpoint with Content-Type request header to be set as 'application/json'. */
     asJson(): this;
-    /** Marks this endpoint with Content-Type header to be set as passed value. */
+    /** Marks this endpoint with Content-Type request 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;
+    function createHooks(): CallerHooks<object>;
 }

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

@@ -0,0 +1,16 @@
+import type { ApiEndpoint, IEndpointInfo } from '../endpoint.js';
+import { CallerHooks } from '../hooks.js';
+/**
+ * Caller hooks on endpoint level.
+ */
+export interface IEndpointHooks {
+    /** Endpoint hooks object, used during request. */
+    readonly hooks?: CallerHooks;
+    /** Adds caller hooks to this endpoint */
+    withHooks(hooks: CallerHooks): this;
+}
+export declare namespace IEndpointHooks {
+    const extender: ApiEndpoint.IBuilderExtender<IEndpointHooks>;
+    function guard(api: IEndpointInfo): api is (IEndpointInfo & IEndpointHooks);
+    function createHooks(): CallerHooks;
+}

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

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

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

@@ -1,6 +1,7 @@
 import { AnyObject } from '../../types/misc.js';
 import type { ApiEndpoint } from '../endpoint.js';
 import type { IEndpointInfo } from '../endpoint.types.js';
+import { CallerHooks } from '../hooks.js';
 export interface IEndpointInputValidation {
     readonly validate?: IEndpointInputValidation.Validator<IEndpointInfo.ExtractIn<this, AnyObject>>;
     withValidation(validator: IEndpointInputValidation.Validator<IEndpointInfo.ExtractIn<this>>): this;
@@ -10,4 +11,5 @@ export declare namespace IEndpointInputValidation {
     const extender: ApiEndpoint.IBuilderExtender<IEndpointInputValidation>;
     function guard(api: IEndpointInfo): api is (IEndpointInfo & IEndpointInputValidation);
     function tryValidate(api: IEndpointInfo, input: AnyObject): void | Promise<void>;
+    function createHooks(): CallerHooks<object>;
 }

package/types/api/hooks.d.ts

@@ -0,0 +1,27 @@
+import type { Nullable } from '../types/misc.js';
+import type { CallerResponse, IRequestConfig } from './call.types.js';
+import type { IEndpointInfo } from './endpoint.types.js';
+export type CallerHooks<TExtra extends object = object> = {
+    /**
+    * Called before config is created, to validate result input data.
+    * May throw to abort request. Use for input validation if needed.
+    * Objects are cloned to avoid mutation.
+    */
+    beforeConfig?: <T extends IEndpointInfo = IEndpointInfo>(api: T, body: IEndpointInfo.ExtractIn<T, object>, pathParams: IEndpointInfo.ExtractPath<T, object>, queryParams: IEndpointInfo.ExtractQuery<T, object>) => CallerHooks.HookReturnType;
+    /**
+     * Called before request is sent.
+     * The config can be mutated or returned as updated object – in the latter case it will be merged into original config via `Object.assign`.
+     * This is useful for adding headers or modifying request data.
+     */
+    beforeRequest?: <T extends IEndpointInfo = IEndpointInfo, TIn = IEndpointInfo.ExtractIn<T>>(config: IRequestConfig<T, TIn, TExtra>) => CallerHooks.HookReturnType<void | IRequestConfig<T, TIn, TExtra>>;
+    /**
+     * Called after response is receieved.
+     * The config can be mutated or returned as updated object – in the latter case it will be merged into original config via `Object.assign`.
+     * This is useful for adding headers or modifying request data.
+     */
+    afterResponse?: <T extends IEndpointInfo = IEndpointInfo, TIn = IEndpointInfo.ExtractIn<T>, TOut = IEndpointInfo.ExtractOut<T>, TResponse extends CallerResponse<TOut> = CallerResponse<TOut>>(config: IRequestConfig<T, TIn, TExtra>, response: TResponse) => CallerHooks.HookReturnType<void | TResponse>;
+};
+export declare namespace CallerHooks {
+    type HookReturnType<T = void> = T | Promise<T>;
+    function merge<TExtra extends object>(items: Nullable<CallerHooks<TExtra> | CallerHooks<TExtra>[]>): CallerHooks<TExtra>;
+}

package/types/api/index.d.ts

@@ -1,9 +1,7 @@
-export type { ProcessingFn } from './processor.js';
 export { ApiEndpoint } from './endpoint.js';
 export type * from './endpoint.types.js';
 export { EndpointMethods } from './methods.js';
-export * from './helpers.js';
+export * from './config.js';
 export { buildApiCaller } from './call.js';
 export { buildApi, createEndpointCallable } from './builder.js';
-export { registerPostProcessor, registerPreProcessor } from './register.js';
 export { LogTypes } from './logging.js';

package/types/api/interceptor.d.ts

@@ -0,0 +1,14 @@
+import { type IEvent } from '../observing/event.js';
+import type { CallerHooks } from './hooks.js';
+export type Interceptors<TExtra extends object = object> = {
+    [K in keyof CallerHooks<TExtra> as `intercept${Capitalize<K>}`]-?: IEvent<Parameters<NonNullable<CallerHooks<TExtra>[K]>>>;
+};
+/**
+ * Experimental. Creates linked caller hooks and interception events.
+ *
+ * Use hooks to recieve events and events to subscribe to them externally.
+ */
+export declare function createInterceptor<TExtra extends object = object>(): {
+    hooks: CallerHooks<TExtra>;
+    events: Interceptors<TExtra>;
+};

package/types/api/logging.d.ts

@@ -1,6 +1,6 @@
 import { ILogger } from '../logger/abstractions.js';
 import type { Nullable } from '../types/index.js';
-import type { RequestConfigDetails } from './call.js';
+import type { IRequestConfig } from './call.js';
 /** Describes the way a request is logged.
  *
  * Useful for granular control over logging, especially in production.
@@ -26,7 +26,7 @@ export declare namespace LogTypes {
      *
      * See the other overload for more details.
     */
-    function logCall(logger: ILogger, cfg: RequestConfigDetails, dir: 'req'): void;
+    function logCall(logger: ILogger, cfg: IRequestConfig, dir: 'req'): void;
     /**
      * An example implementation for logging logic (overload for a request with data).
      *
@@ -35,5 +35,5 @@ export declare namespace LogTypes {
      * * 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;
+    function logCall(logger: ILogger, cfg: IRequestConfig, dir: 'res', data: unknown): void;
 }

package/types/functions/assert.d.ts

@@ -1,2 +1,6 @@
 import { Getter } from '../types/index.js';
-export declare function assert(condition: boolean, error: Getter<string | Error>, objectToLog?: Getter<any>): asserts condition;
+import { ILogger } from '../logger/abstractions.js';
+type AssertFn = (condition: boolean, error: Getter<string | Error>, objectToLog?: Getter<any>) => asserts condition;
+export declare function createAssert(logger: ILogger): AssertFn;
+export declare const assert: AssertFn;
+export {};

package/types/functions/throttle.d.ts

@@ -1,4 +1,4 @@
-import { ILogger } from '../logger/index.js';
+import { ILogger } from '../logger/shared.js';
 /** Runs a callback after a timeout, ignoring all consecutive calls until the first is processed.  */
 export declare class ThrottleAction<T = any> {
     timeout: number;

package/types/logger/index.d.ts

@@ -1,13 +1,13 @@
 import { ILogger, LoggerFunction } from './abstractions.js';
 import { ConsoleLogger } from './console.js';
 import { batchLoggers } from './batch.js';
-import { LoggerModes } from './manager.js';
-export type { ILogger, LoggerFunction };
+import { LoggerModes, LoggersManager } from './manager.js';
+export type { ILogger, LoggerFunction, LoggerModes };
 export { NamedLogger } from './named.js';
 export { ConsoleLogger, batchLoggers };
-export declare function createLogger(name: string | undefined, mode?: undefined | LoggerModes): ILogger;
-export declare function detachLogger(instance: ILogger, terminate?: boolean): boolean;
-export declare function setMode(mode: LoggerModes | null | undefined): void;
-export declare function getMode(): LoggerModes;
-declare const logger: ILogger;
-export default logger;
+export { LoggersManager };
+/** Shared logger instance used internally in this library.
+ *
+ * For internal default loggers to be enabled and working, don't forget to set the mode to this instance.
+*/
+export * as SharedLogger from './shared.js';

package/types/logger/manager.d.ts

@@ -19,4 +19,11 @@ export declare class LoggersManager {
     detach(instance: ILogger, terminate?: boolean): boolean;
     private _findInstance;
     private _createImplementation;
+    expose(): {
+        createLogger: (name: string | undefined, mode?: undefined | LoggerModes) => ILogger;
+        detachLogger: (instance: ILogger, terminate?: boolean) => boolean;
+        setMode: (mode: LoggerModes | null | undefined) => void;
+        getMode: () => LoggerModes;
+        logger: ILogger;
+    };
 }

package/types/logger/shared.d.ts

@@ -0,0 +1,15 @@
+import { ILogger } from './abstractions.js';
+import { LoggerModes } from './manager.js';
+export type { ILogger, LoggerModes };
+/** @deprecated Uses shared `LoggersManager` instance, it's better to create your own. */
+export declare const createLogger: (name: string | undefined, mode?: undefined | LoggerModes) => ILogger;
+/** @deprecated Uses shared `LoggersManager` instance, it's better to create your own. */
+export declare const detachLogger: (instance: ILogger, terminate?: boolean) => boolean;
+/** @deprecated Uses shared `LoggersManager` instance, it's better to create your own. */
+export declare const setMode: (mode: LoggerModes | null | undefined) => void;
+/** @deprecated Uses shared `LoggersManager` instance, it's better to create your own. */
+export declare const getMode: () => LoggerModes;
+/** @deprecated Uses shared `LoggersManager` instance, it's better to create your own. */
+declare const logger: ILogger;
+/** @deprecated Uses shared `LoggersManager` instance, it's better to create your own. */
+export default logger;

package/types/models/LogicModel.d.ts

@@ -1,7 +1,7 @@
 import { ExclusiveLoadingError, LoadingModel } from './Loading.js';
 import { Getter } from '../types/index.js';
 import { PromiseExtended } from '../structures/promiseExtended.js';
-import { ILogger } from '../logger/index.js';
+import { ILogger } from '../logger/shared.js';
 export type ActionRunOptions = {
     /** Action name, required for logging and joining. */
     name?: string;

package/types/observing/event.d.ts

@@ -1,5 +1,5 @@
 import type { Predicate } from '../types/index.js';
-import { ILogger } from '../logger/index.js';
+import { ILogger } from '../logger/shared.js';
 export type EventHandler<T = any> = (data?: T) => void | Promise<void>;
 type Unsubscribe = () => void;
 export interface IEvent<T = any> {

package/types/observing/progressTracker.d.ts

@@ -1,4 +1,4 @@
-import { ILogger } from '../logger/index.js';
+import { type ILogger } from '../logger/shared.js';
 export declare class ProgressTracker {
     readonly log: boolean | ILogger;
     private readonly _firstTimestamp;

package/types/structures/path/builder.d.ts

@@ -1,8 +1,9 @@
-import { BaseInput, CombineBuilders, StaticBuilder, SwitchBuilder } from './types.js';
-export * from './types.js';
+import { BaseInput, CombineBuilders, SwitchBuilder } from './types.js';
+export type * from './types.js';
+export type { TemplateTransform } from './types.helpers.js';
 /** Tagged template literal to create a path builder */
 export declare function build<TArgs extends string[]>(strings: TemplateStringsArray, ...params: TArgs): SwitchBuilder<TArgs>;
-export declare const Empty: StaticBuilder;
+export declare const Empty: import("./types.js").StaticBuilder;
 /**
  * For input, use any amount of arguments, each one can be:
  *
@@ -12,4 +13,4 @@ export declare const Empty: StaticBuilder;
  *   - manually implementing `Builder<string[]>`
  *   - another `construct` call
 */
-export declare function construct<TArr extends BaseInput[]>(...inputs: TArr): CombineBuilders<TArr>;
+export declare function construct<TArr extends BaseInput[]>(...inputsRaw: TArr): CombineBuilders<TArr>;

package/types/structures/path/builder.helpers.d.ts

@@ -0,0 +1,8 @@
+import type { BaseInput, Builder, StaticBuilder, StaticInput } from './types.js';
+export declare const staticFactory: (strings: readonly string[]) => StaticBuilder;
+export declare function constructStatic(input: StaticInput): StaticBuilder & {
+    asOptional?(): never;
+};
+export declare function constructDynamic(strings: TemplateStringsArray, ...paramsRaw: string[]): StaticBuilder | Builder<readonly string[]>;
+export declare function guardIsStatic(value: any): value is StaticInput;
+export declare function normalizeInput(inputs: BaseInput[]): BaseInput[];

package/types/structures/path/types.d.ts

@@ -1,14 +1,15 @@
-import type { EmptyObject, LengthArray, Nullable } from '../../types/misc.js';
+import type { EmptyObject, Expand, IsNever, LengthArray, Nullable } from '../../types/misc.js';
+import type { ArgValue, IsOptional, ReadonlyArrayNormalized, TemplateTransform, ToOptionalArray, ToRequired, ToRequiredArray, TransformMap } from './types.helpers.js';
 import type { CombineOptions } from './utils.js';
-export type ArgValue = string | number;
-export type ObjectBuilderArgs<TArgs extends string, TOptional = false, TFallback = EmptyObject> = string extends TArgs ? TFallback : true extends TOptional ? MakeOptional<Record<TArgs, ArgValue>> : Record<TArgs, ArgValue>;
-export type BuilderArgs<TArgs extends string, L extends number = number> = LengthArray<ArgValue, L> | Record<TArgs, ArgValue>;
-export type TemplatePrefixing = Nullable<string | ((key: string, index: number) => string)>;
-type MakeOptional<T> = {
-    [P in keyof T]?: Nullable<T[P]>;
-};
+export type ObjectBuilderArgs<TArgs extends string, TFallback = EmptyObject> = string extends TArgs ? TFallback : ArgRecord<TArgs>;
+export type BuilderArgs<TArgs extends string, L extends number = number> = LengthArray<ArgValue | null, L> | ArgRecord<TArgs>;
+export type ArgRecord<T extends string> = Expand<{
+    [K in T as true extends IsOptional<K> ? never : K]: ArgValue;
+} & {
+    [K in T as true extends IsOptional<K> ? ToRequired<K> : never]?: ArgValue | null;
+}>;
 /** Internal, Don't use it directly */
-interface BaseBuilder<A extends readonly string[], B, P = TemplatePrefixing> {
+interface BaseBuilder<A extends readonly string[], B> {
     /**
      * Builds the path using provided args.
      *
@@ -20,14 +21,15 @@ interface BaseBuilder<A extends readonly string[], B, P = TemplatePrefixing> {
     /**
      * Template builder that will build the path using args names but also can:
      * - keep args as they were in the template
-     * - add a prefix for each key in case `prefix` is provided as string
-     * - format each key in case `prefix` is provided as function
+     * - add a prefix for each key in case `transform` is provided as string
+     * - format each key in case `transform` is provided as function
+     * - append prefix/suffix/optional suffix for each key in case `transform` is provided as object
      *
      * For now it's recommended to cache the result, internally it doesn't care about it.
      */
-    template: (prefix?: P, options?: CombineOptions) => string;
+    template: (transform?: Nullable<TemplateTransform>, options?: CombineOptions) => string;
     /** args as they were in the template */
-    readonly args: A;
+    readonly args: ReadonlyArrayNormalized<ToRequiredArray<A>>;
     /**
      * Types helper method to easily cast all kinds of builders to generic IBuilder or others.
      * It just always returns the passed object, so it's the implementation's responsibility to ensure the compatibility.
@@ -44,29 +46,32 @@ interface BaseBuilder<A extends readonly string[], B, P = TemplatePrefixing> {
     /** Allows to specify **template** transformation per key for the current builder instance. */
     withTemplateTransform: (transforms: TransformMap<A>) => this;
 }
-export type TransformMap<A extends readonly string[]> = {
-    [K in A[number]]?: (v: ArgValue) => string;
-};
 type EmptyBuilderArgs = [] | Record<PropertyKey, never>;
-type ReadonlyArr<TArr extends ReadonlyArray<any>> = TArr extends ReadonlyArray<infer T> ? ReadonlyArray<T> : never;
-export interface Builder<TArgs extends readonly string[], TOptional = false> extends BaseBuilder<ReadonlyArr<TArgs>, true extends TOptional ? MakeOptional<BuilderArgs<TArgs[number], TArgs['length']>> : BuilderArgs<TArgs[number], TArgs['length']>> {
+export interface Builder<TArgs extends readonly string[]> extends BaseBuilder<ReadonlyArrayNormalized<TArgs>, BuilderArgs<TArgs[number], TArgs['length']>> {
     /** Marks input type for `build` to be `Partial`, so any/all arguments can be omitted.
      *
      * **Limitation**: will convert to optional ALL parameters if >=2 Builders combined via CombineBuilders
     */
-    asOptional(): Builder<TArgs, true>;
+    asOptional(): Builder<ToOptionalArray<TArgs>>;
 }
 export interface StaticBuilder extends BaseBuilder<readonly [], EmptyBuilderArgs> {
 }
 export interface IBuilder extends BaseBuilder<readonly string[], any> {
 }
 export type StaticInput = string | readonly string[];
-export type BaseInput = StaticInput | BaseBuilder<any, any, any>;
-export type Output<TInput> = TInput extends StaticBuilder ? StaticBuilder : (TInput extends Builder<infer TArgs, infer TOptional> ? Builder<TArgs, TOptional> : StaticBuilder);
-export type SwitchBuilder<TArg extends readonly string[]> = [TArg] extends [never] ? StaticBuilder : ([] extends TArg ? StaticBuilder : (readonly string[] extends TArg ? IBuilder : Builder<TArg>));
-export type ExtractArgs<T> = T extends Builder<infer TArgs> ? TArgs : readonly string[];
-export type ExtractObjectArgs<T, F = EmptyObject> = T extends Builder<infer TArgs, infer O> ? ObjectBuilderArgs<TArgs[number], O, F> : F;
-type LogicalOr<O1, O2> = true extends O1 ? true : true extends O2 ? true : false;
-type CombineTwo<T1 extends BaseInput, T2 extends BaseInput> = Output<T1> extends StaticBuilder ? Output<T2> : (Output<T2> extends StaticBuilder ? Output<T1> : (Output<T1> extends Builder<infer Arr1, infer O1> ? (Output<T2> extends Builder<infer Arr2, infer O2> ? Builder<[...Arr1, ...Arr2], LogicalOr<O1, O2>> : never) : never));
-export type CombineBuilders<T extends readonly BaseInput[]> = T extends readonly [infer T1 extends BaseInput, infer T2 extends BaseInput, ...infer Rest] ? (CombineTwo<T1, T2> extends infer C extends BaseBuilder<any, any, any> & BaseInput ? (Rest extends readonly BaseInput[] ? CombineBuilders<readonly [C, ...Rest]> : never) : never) : (T extends readonly [infer T1] ? Output<T1> : StaticBuilder);
+export type BaseInput = StaticInput | BaseBuilder<any, any>;
+export type SwitchBuilder<TArg extends readonly string[]> = IsNever<TArg, StaticBuilder, [
+] extends TArg ? StaticBuilder : (readonly string[] extends TArg ? IBuilder : Builder<TArg>)>;
+export type ExtractArgs<T> = T extends Builder<infer TArgs> ? ToRequiredArray<TArgs> : readonly string[];
+export type ExtractObjectArgs<T, F = EmptyObject> = T extends Builder<infer TArgs> ? ObjectBuilderArgs<TArgs[number], F> : F;
+/** Normalizes builder, makes sure dynamic args are inferrable. If input is not a builder (i.e. StaticInput), return StaticBuilder */
+type Output<TInput> = TInput extends StaticBuilder ? StaticBuilder : (TInput extends Builder<infer TArgs> ? Builder<TArgs> : (TInput extends StaticInput ? DynamicStringToBuilder<TInput> : StaticBuilder));
+/** Turns two inputs into one builder, merging static and dynamic args */
+type CombineTwo<T1 extends BaseInput, T2 extends BaseInput> = Output<T1> extends StaticBuilder ? Output<T2> : (Output<T2> extends StaticBuilder ? Output<T1> : (Output<T1> extends Builder<infer Arr1> ? (Output<T2> extends Builder<infer Arr2> ? Builder<[...Arr1, ...Arr2]> : never) : never));
+export type CombineBuilders<T extends readonly BaseInput[]> = T extends readonly [infer T1 extends BaseInput, infer T2 extends BaseInput, ...infer Rest] ? (CombineTwo<T1, T2> extends infer C extends BaseBuilder<infer _A extends readonly string[], any> & BaseInput ? (Rest extends readonly BaseInput[] ? CombineBuilders<readonly [C, ...Rest]> : never) : never) : (T extends readonly [infer T1] ? Output<T1> : StaticBuilder);
+type Splitter<T extends string> = T extends `${infer Head extends string}/${infer Rest}` ? [Head, ...Splitter<Rest>] : [T];
+type ExtractDynamic<T extends string> = T extends `:${infer Arg}` ? [Arg] : T;
+type SkipStaticParts<T extends readonly string[]> = T extends readonly [infer Head extends string, ...infer Rest extends readonly string[]] ? ExtractDynamic<Head> extends [infer Arg] ? [Arg, ...SkipStaticParts<Rest>] : SkipStaticParts<Rest> : [];
+type ExtractDynamicParts<T extends StaticInput> = T extends readonly string[] ? SkipStaticParts<T> : (T extends string ? SkipStaticParts<Splitter<T>> : []);
+type DynamicStringToBuilder<T extends StaticInput> = [] extends ExtractDynamicParts<T> ? StaticBuilder : Builder<ExtractDynamicParts<T>>;
 export {};

package/types/structures/path/types.helpers.d.ts

@@ -0,0 +1,23 @@
+export type IsOptional<T extends string> = T extends `${string}?` ? true : false;
+export type ToOptional<T extends string> = T extends `${infer Arg}?` ? `${Arg}?` : `${T}?`;
+export type ToOptionalArray<T extends readonly string[]> = T extends readonly [infer Head extends string, ...infer Rest extends readonly string[]] ? [ToOptional<Head>, ...ToOptionalArray<Rest>] : [];
+export type ToRequired<T extends string> = T extends `${infer Arg}?` ? Arg : T;
+export type ToRequiredArray<T extends readonly string[]> = T extends readonly [infer Head extends string, ...infer Rest extends readonly string[]] ? [ToRequired<Head>, ...ToRequiredArray<Rest>] : T;
+export type ReadonlyArrayNormalized<TArr extends ReadonlyArray<unknown>> = TArr extends ReadonlyArray<infer T> ? ReadonlyArray<T> : never;
+export type ArgValue = string | number | boolean;
+export type ArgumentInfo = {
+    raw: string;
+    name: string;
+    index: number;
+    isOptional: boolean;
+};
+export type TemplateTransformOptions = {
+    prefix: string;
+    suffix: string;
+    optionalSuffix: string;
+};
+export type TransformFunction<TValue extends ArgValue = ArgValue> = (value: TValue, info: ArgumentInfo) => string;
+export type TemplateTransform = string | Partial<TemplateTransformOptions> | TransformFunction<string>;
+export type TransformMap<A extends readonly string[]> = {
+    [K in A[number]]?: TransformFunction;
+};

package/types/structures/promiseCache.d.ts

@@ -1,4 +1,4 @@
-import { ILogger } from '../logger/index.js';
+import { ILogger } from '../logger/shared.js';
 import { IMapModel, IValueModel } from '../models/types.js';
 export type DeferredGetter<T> = {
     readonly current: T | null | undefined;

package/types/types/misc.d.ts

@@ -36,3 +36,7 @@ export type PickNullable<T, K extends keyof T> = {
 export type EmptyObjectNullable = (EmptyObject | null | undefined);
 export type IsNever<T, Y, N> = [T] extends [never] ? Y : N;
 export type Coalesce<T, TReplace = EmptyObjectNullable> = [T] extends [never] | [null] | [undefined] ? TReplace : T;
+/** Intellisense helper to show type unions/intersections as a whole type */
+export type Expand<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;

package/cjs/api/helpers.js

@@ -1,32 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultSettings = void 0;
-exports.setDefaults = setDefaults;
-exports.getPath = getPath;
-exports.getTemplate = getTemplate;
-exports.getFormattedDisplayName = getFormattedDisplayName;
-const index_js_1 = require("../structures/path/index.js");
-exports.DefaultSettings = {
-    templateArgPrefix: ':',
-    basePrefix: '/',
-};
-function setDefaults(settings) {
-    Object.assign(exports.DefaultSettings, settings);
-}
-const getPrefix = (prefix) => typeof prefix === 'string' ? prefix : (prefix ? exports.DefaultSettings.basePrefix : false);
-function getPath(endpoint, pathArgs, prefix = true) {
-    const path = endpoint.path ?? index_js_1.Path.Empty;
-    return path.build(pathArgs || undefined, { addStart: getPrefix(prefix) });
-}
-function getTemplate(endpoint, prefix = true) {
-    const path = endpoint.path ?? index_js_1.Path.Empty;
-    return path.template(exports.DefaultSettings.templateArgPrefix, { addStart: getPrefix(prefix) });
-}
-function getFormattedDisplayName(endpoint) {
-    const template = getTemplate(endpoint);
-    const prefix = endpoint.displayName
-        ? `[${endpoint.displayName}] `
-        : '';
-    return prefix + template;
-}
-//# sourceMappingURL=helpers.js.map

package/cjs/api/helpers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/api/helpers.ts"],"names":[],"mappings":";;;AAQA,kCAEC;AAKD,0BAQC;AAED,kCAIC;AAED,0DAMC;AArCD,0DAAmD;AAGtC,QAAA,eAAe,GAAG;IAC3B,iBAAiB,EAAE,GAAoC;IACvD,UAAU,EAAE,GAAG;CAClB,CAAC;AAEF,SAAgB,WAAW,CAAC,QAAyC;IACjE,MAAM,CAAC,MAAM,CAAC,uBAAe,EAAE,QAAQ,CAAC,CAAC;AAC7C,CAAC;AAGD,MAAM,SAAS,GAAG,CAAC,MAAqB,EAAE,EAAE,CAAC,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,uBAAe,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAEjI,SAAgB,OAAO,CACnB,QAAW,EACX,QAAsC,EACtC,SAA2B,IAAI;IAE/B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,IAAK,eAAI,CAAC,KAAuB,CAAC;IAE5D,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,SAAS,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,SAAgB,WAAW,CAA0B,QAAW,EAAE,SAA2B,IAAI;IAC7F,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,IAAK,eAAI,CAAC,KAAuB,CAAC;IAE5D,OAAO,IAAI,CAAC,QAAQ,CAAC,uBAAe,CAAC,iBAAiB,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAC7F,CAAC;AAED,SAAgB,uBAAuB,CAAC,QAAuB;IAC3D,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW;QAC/B,CAAC,CAAC,IAAI,QAAQ,CAAC,WAAW,IAAI;QAC9B,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,MAAM,GAAG,QAAQ,CAAC;AAC7B,CAAC"}