@tsed/core 8.18.2 → 8.19.0

package/lib/types/types/DecoratorParameters.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Raw parameters passed by the TypeScript runtime to any decorator
+ * (class, property, method or parameter).
+ *
+ * The tuple contains:
+ * - the target (class `prototype` for instance members or the constructor for static members),
+ * - the key (`string | symbol`) of the decorated member,
+ * - the parameter index (number) or the `PropertyDescriptor` depending on the decorator type.
+ *
+ * @example
+ * ```ts
+ * function MyDecorator(...args: DecoratorParameters) {}
+ * ```
+ * @public
+ */
 export type DecoratorParameters = [any, string | symbol, number | PropertyDescriptor];
+/**
+ * Specialized variant for method decorators where the third element
+ * is always a `PropertyDescriptor`.
+ *
+ * @public
+ */
 export type DecoratorMethodParameters = [any, string | symbol, PropertyDescriptor];
 export type StaticMethodDecorator = <TFunction extends Function, T>(target: TFunction, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;

package/lib/types/types/DecoratorTypes.d.ts

@@ -1,10 +1,26 @@
+/**
+ * Normalized decorator kinds recognized by Ts.ED.
+ *
+ * This enum helps identify, at runtime, the element a decorator applies to
+ * (parameter, property, method, class, and static/constructor variants).
+ *
+ * @public
+ */
 export declare enum DecoratorTypes {
+    /** Decorator applied to an instance parameter */
     PARAM = "parameter",
+    /** Decorator applied to a constructor parameter */
     PARAM_CTOR = "parameter.constructor",
+    /** Decorator applied to a static method parameter */
     PARAM_STC = "parameter.static",
+    /** Decorator applied to an instance property */
     PROP = "property",
+    /** Decorator applied to a static property */
     PROP_STC = "property.static",
+    /** Decorator applied to an instance method */
     METHOD = "method",
+    /** Decorator applied to a static method */
     METHOD_STC = "method.static",
+    /** Decorator applied to a class */
     CLASS = "class"
 }

package/lib/types/types/Env.d.ts

@@ -1,5 +1,10 @@
 /**
+ * Represents the current application runtime environment.
  *
+ * Used by Ts.ED to adapt behaviors (logging, error verbosity, defaults, etc.)
+ * depending on the environment.
+ *
+ * @public
  */
 export declare enum Env {
     PROD = "production",
@@ -7,7 +12,8 @@ export declare enum Env {
     TEST = "test"
 }
 /**
- * Fallback
- * @type {Env}
+ * Compatibility alias. Prefer using `Env` directly.
+ *
+ * @deprecated Use `Env` directly.
  */
 export declare const EnvTypes: typeof Env;

package/lib/types/types/Metadata.d.ts

@@ -1,5 +1,14 @@
 import "reflect-metadata";
 /**
+ * Static helper around `reflect-metadata` to read and write metadata on classes,
+ * methods, properties and parameters.
+ *
+ * This is the single entry point used across Ts.ED core to interact with
+ * design-time type information (e.g. param types, return types) and custom
+ * metadata keys. Only the exported class symbol is documented here per the
+ * symbols-only rule; individual members are intentionally not described.
+ *
+ * @public
  * @stable
  */
 export declare class Metadata {

package/lib/types/types/MetadataTypes.d.ts

@@ -1,5 +1,17 @@
 import type { Type } from "./Type.js";
+/**
+ * Modèle générique décrivant les types associés à une valeur de métadonnée.
+ *
+ * Permet d'indiquer le type de l'élément (`type`) et, le cas échéant, le type
+ * de la collection qui le contient (`collectionType`).
+ *
+ * @typeParam T Type de l'élément.
+ * @typeParam C Type de la collection si applicable (ex: `Array<T>`, `Set<T>`).
+ * @public
+ */
 export interface MetadataTypes<T = any, C = any> {
+    /** Type de l'élément (constructeur ou instance). */
     type?: Type<T> | T;
+    /** Type de la collection (constructeur ou instance) si applicable. */
     collectionType?: Type<C> | C;
 }

package/lib/types/types/Relation.d.ts

@@ -1 +1,9 @@
+/**
+ * Type marker for expressing a relationship between models/DTOs.
+ *
+ * In some contexts, `Relation<T>` is used to indicate that a property represents a related entity of type `T`. It is a transparent alias for `T`, primarily serving documentation and intent.
+ *
+ * @typeParam Resource Type
+ * @public
+ */
 export type Relation<T> = T;

package/lib/types/types/Store.d.ts

@@ -1,20 +1,34 @@
 import type { Type } from "./Type.js";
 /**
+ * Metadata key used to reference the class-level store.
  * @ignore
  */
 export declare const CLASS_STORE = "tsed:class:store";
 /**
+ * Metadata key used to reference the method-level store.
  * @ignore
  */
 export declare const METHOD_STORE = "tsed:method:store";
 /**
+ * Metadata key used to reference the property-level store.
  * @ignore
  */
 export declare const PROPERTY_STORE = "tsed:property:store";
 /**
+ * Metadata key used to reference the parameter-level store.
  * @ignore
  */
 export declare const PARAM_STORE = "tsed:param:store";
+/**
+ * Lightweight key/value registry used to attach and retrieve metadata at
+ * class, method, property, and parameter levels.
+ *
+ * The `Store` is used internally by decorators and utilities to group
+ * metadata by symbol. Only the exported class is documented per the
+ * symbols-only rule; members are intentionally not described here.
+ *
+ * @public
+ */
 export declare class Store {
     private _entries;
     /**

package/lib/types/types/Type.d.ts

@@ -1,14 +1,24 @@
 /**
- * An example of a `Type` is `MyCustomComponent` filters, which in JavaScript is represented by
- * the `MyCustomComponent` constructor function.
- */
-/**
+ * Represents a class constructor `new (...args) => T`.
  *
+ * In Ts.ED, `Type<T>` is used to type class references (controllers, services, models, etc.) where a constructor is expected.
+ *
+ * @typeParam T Type of the instance created by the constructor.
+ * @public
  */
 export interface Type<T = any> extends Function {
     new (...args: any[]): T;
 }
+/**
+ * Alias of the JavaScript base constructor, used to preserve
+ * compatibility with certain inference contexts.
+ *
+ * @deprecated Avoid using this constant directly; prefer the `Type<T>` type.
+ */
 export declare const Type: FunctionConstructor;
+/**
+ * Describes an abstract type (abstract class), useful for declaring dependencies that should not be instantiated directly.
+ */
 export interface AbstractType<T> extends Function {
     prototype: T;
 }

package/lib/types/types/ValueOf.d.ts

@@ -1 +1,11 @@
+/**
+ * Type utilitaire qui produit l'union de toutes les valeurs d'un type objet `T`.
+ *
+ * @example
+ * ```ts
+ * type T = {a: 1; b: 2};
+ * type V = ValueOf<T>; // 1 | 2
+ * ```
+ * @public
+ */
 export type ValueOf<T> = T[keyof T];

package/lib/types/utils/AnyToPromise.d.ts

@@ -1,17 +1,35 @@
 /**
  * @ignore
  */
+/**
+ * Represents the lifecycle state of an `AnyToPromise` operation.
+ *
+ * @public
+ */
 export declare enum AnyToPromiseStatus {
     PENDING = "PENDING",
     CANCELED = "CANCELED",
     RESOLVED = "RESOLVED",
     REJECTED = "REJECTED"
 }
+/**
+ * Describes the high-level response kind produced by `AnyToPromise`.
+ *
+ * @public
+ */
 export declare enum AnyToPromiseResponseTypes {
     STREAM = "STREAM",
     BUFFER = "BUFFER",
     DATA = "DATA"
 }
+/**
+ * Result shape returned by `AnyToPromise` when resolved.
+ *
+ * Only the symbol itself is documented per the symbols-only rule (member fields are self-explanatory).
+ *
+ * @typeParam T Type of the `data` field.
+ * @public
+ */
 export interface AnyPromiseResult<T = any> {
     state: AnyToPromiseStatus;
     type: AnyToPromiseResponseTypes;
@@ -19,6 +37,16 @@ export interface AnyPromiseResult<T = any> {
     headers?: Record<string, any>;
     data: T;
 }
+/**
+ * Utility that normalizes various async-like values (Promise, Observable, Stream, plain value)
+ * into a single Promise-based flow with a consistent result shape.
+ *
+ * This class is used internally to handle controller/middleware outputs, but can be
+ * reused anywhere a unified async handling is desired.
+ *
+ * @typeParam T Type of the resulting payload.
+ * @public
+ */
 export declare class AnyToPromise<T = any> {
     #private;
     status: AnyToPromiseStatus;

package/lib/types/utils/ancestorOf.d.ts

@@ -1,2 +1,19 @@
+/**
+ * Returns the immediate prototype (ancestor) of the given target.
+ *
+ * Internally uses `Object.getPrototypeOf` to retrieve the prototype chain ancestor.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function ancestorOf(target: any): any;
+/**
+ * Returns the inherited class (ancestor) of the given target.
+ *
+ * An alias for {@link ancestorOf}.
+ *
+ * @public
+ * @since v7.0.0
+ * @see ancestorOf
+ */
 export declare function getInheritedClass(target: any): any;

package/lib/types/utils/ancestorsOf.d.ts

@@ -1,6 +1,12 @@
 /**
+ * Returns all ancestor classes in the prototype chain of the target.
  *
- * @param target
- * @returns {Array}
+ * Traverses the prototype chain from the target's class up to the root,
+ * returning an array of all named constructor functions encountered.
+ *
+ * @public
+ * @since v7.0.0
+ * @see classOf
+ * @see getInheritedClass
  */
 export declare function ancestorsOf(target: any): any[];

package/lib/types/utils/catchError.d.ts

@@ -1,2 +1,14 @@
+/**
+ * Executes a callback and returns any thrown error, or undefined if no error occurred.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function catchError<T extends Error>(cb: Function): T | undefined;
+/**
+ * Executes an async callback and returns any thrown error, or undefined if no error occurred.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function catchAsyncError<T extends Error>(cb: Function): Promise<T | undefined>;

package/lib/types/utils/classOf.d.ts

@@ -1,13 +1,20 @@
 /**
- * Get the provide constructor if target is an instance.
- * @param target
- * @returns {*}
+ * Returns the constructor of a target. If `target` is already a class
+ * (constructor function), it is returned as is; if it is an instance,
+ * its constructor is returned.
+ *
+ * @param target Instance or constructor.
+ * @returns The constructor associated with the target.
+ * @example
+ * ```ts
+ * class A {}
+ * getClass(A) === A; // true
+ * getClass(new A()) === A; // true
+ * ```
  */
 export declare function getClass(target: any): any;
 /**
- * Get the provide constructor if target is an instance.
- * @param target
- * @returns {*}
- * @alias getClass
+ * Alias of `getClass`.
+ * @see getClass
  */
 export declare function classOf(target: any): any;

package/lib/types/utils/cleanObject.d.ts

@@ -1,6 +1,10 @@
 /**
- * Remove undefined value
- * @param obj
- * @param ignore
+ * Returns a copy of an object with undefined values, protected keys, and ignored keys removed.
+ *
+ * Filters out entries that are undefined, match protected key patterns, or are in the ignore list.
+ *
+ * @public
+ * @since v7.0.0
+ * @see isProtectedKey
  */
 export declare function cleanObject(obj: Record<string, unknown>, ignore?: string[]): any;

package/lib/types/utils/constructorOf.d.ts

@@ -1,11 +1,22 @@
 import type { Type } from "../types/Type.js";
 /**
- * Get the class constructor
- * @param target
+ * Get the class constructor from a class or an instance.
+ *
+ * If `target` is already a constructor, it is returned as-is; otherwise the
+ * constructor of the instance is returned.
+ *
+ * @param target A class constructor or an instance.
+ * @returns The class constructor function.
+ * @example
+ * ```ts
+ * class A {}
+ * getConstructor(A) === A; // true
+ * getConstructor(new A()) === A; // true
+ * ```
  */
 export declare function getConstructor(target: any): Type<any>;
 /**
- * Get the class constructor
- * @param target
+ * Alias of `getConstructor`.
+ * @see getConstructor
  */
 export declare function constructorOf(target: any): Type<any>;

package/lib/types/utils/createInstance.d.ts

@@ -1 +1,12 @@
+/**
+ * Creates a lightweight object instance that inherits from the provided value's prototype.
+ *
+ * If the input is a class or instance whose constructor is not Object, this function
+ * returns `Object.create(obj)` to preserve the prototype chain without invoking the constructor.
+ * Otherwise, it returns a plain empty object.
+ *
+ * @public
+ * @since v7.0.0
+ * @see classOf
+ */
 export declare function createInstance(obj: any): any;

package/lib/types/utils/decorateMethodsOf.d.ts

@@ -1 +1,12 @@
+/**
+ * Applies a decorator to all methods of a class, copying inherited methods if necessary.
+ *
+ * For each method, if inherited from a parent class, it first copies the method to the target class
+ * and merges its Store metadata, then applies the decorator.
+ *
+ * @public
+ * @since v7.0.0
+ * @see methodsOf
+ * @see Store
+ */
 export declare function decorateMethodsOf(klass: any, decorator: any): void;

package/lib/types/utils/decoratorArgs.d.ts

@@ -1,2 +1,12 @@
 import { DecoratorParameters } from "../types/DecoratorParameters.js";
+/**
+ * Constructs decorator parameters (target, propertyKey, descriptor) for a given class member.
+ *
+ * Retrieves the property descriptor and returns a tuple compatible with decorator signatures.
+ *
+ * @public
+ * @since v7.0.0
+ * @see DecoratorParameters
+ * @see descriptorOf
+ */
 export declare function decoratorArgs(target: any, propertyKey: string): DecoratorParameters;

package/lib/types/utils/decoratorTypeOf.d.ts

@@ -1,2 +1,12 @@
 import { DecoratorTypes } from "../types/DecoratorTypes.js";
+/**
+ * Determines the decorator type from decorator parameters.
+ *
+ * Analyzes the target, propertyKey, and descriptor to classify the decorator as
+ * class, method, property, parameter, or their static variants.
+ *
+ * @public
+ * @since v7.0.0
+ * @see DecoratorTypes
+ */
 export declare function decoratorTypeOf(args: any[]): DecoratorTypes;

package/lib/types/utils/deepClone.d.ts

@@ -1,6 +1,10 @@
 /**
- * Return a cloned value
- * @param source
- * @param stack
+ * Creates a deep clone of the provided value, preserving prototype chains and handling circular references.
+ *
+ * Supports primitives, dates, regular expressions, typed arrays, buffers, maps, sets, and plain objects.
+ * Uses a WeakMap to track and handle circular references correctly.
+ *
+ * @public
+ * @since v7.0.0
  */
 export declare const deepClone: (source: any, stack?: WeakMap<WeakKey, any>) => any;

package/lib/types/utils/deepMerge.d.ts

@@ -1,10 +1,40 @@
+/**
+ * Callback type for custom array merge reducers.
+ * @public
+ * @since v7.0.0
+ */
 export type DeepMergeReducerCB = (collection: any[], value: any, options?: DeepMergeOptions) => any;
+/**
+ * Callback type for comparing array items during merge.
+ * @public
+ * @since v7.0.0
+ */
 export type DeepMergeComparatorCB = (item: any, ref: any) => boolean;
+/**
+ * Configuration options for deep merge operations.
+ * @public
+ * @since v7.0.0
+ */
 export interface DeepMergeOptions {
     reducers?: Record<string, DeepMergeReducerCB>;
     parentKey?: string;
     cleanUndefinedProps?: boolean;
     alter?: (key: string, value: any) => any;
 }
+/**
+ * Creates a merge reducer using a custom comparator function.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function mergeReducerBuilder(cb: DeepMergeComparatorCB): (collection: any[], value: any, options: DeepMergeOptions) => any[];
+/**
+ * Deeply merges two values, combining objects recursively and handling arrays with custom reducers.
+ *
+ * Supports primitives, arrays, and objects. Can clean undefined properties and apply custom transformations.
+ *
+ * @public
+ * @since v7.0.0
+ * @see DeepMergeOptions
+ */
 export declare function deepMerge<T = any, C = any>(source: T & any, obj: C & any, options?: DeepMergeOptions): (T & C) | undefined | null;

package/lib/types/utils/descriptorOf.d.ts

@@ -1,8 +1,19 @@
 /**
- * Return the descriptor for a given class and propertyKey
- * @param target
- * @param {string} propertyKey
- * @returns {PropertyDescriptor}
+ * Retrieves the property descriptor for a given class and property key.
+ *
+ * Checks both the target and its prototype for the property descriptor.
+ *
+ * @public
+ * @since v7.0.0
  */
 export declare function descriptorOf(target: any, propertyKey: string | symbol): PropertyDescriptor;
+/**
+ * Checks whether a property descriptor represents a method.
+ *
+ * Returns true if the descriptor has a value property (indicating a method).
+ *
+ * @public
+ * @since v7.0.0
+ * @see descriptorOf
+ */
 export declare function isMethodDescriptor(target: any, propertyKey: string | symbol): any;

package/lib/types/utils/getClassOrSymbol.d.ts

@@ -1 +1,9 @@
+/**
+ * Retourne le constructeur de classe lorsque `target` est une classe/instance,
+ * sinon retourne la valeur telle quelle (utile pour les `symbol`).
+ *
+ * @param target Valeur potentiellement typée classe, instance, ou symbole.
+ * @returns Le constructeur de la classe ou la valeur originale si ce n'est pas une classe.
+ * @public
+ */
 export declare function getClassOrSymbol(target: any): any;

package/lib/types/utils/getConstructorArgNames.d.ts

@@ -1 +1,11 @@
+/**
+ * Extracts constructor parameter names from a class constructor.
+ *
+ * Parses the constructor's string representation to retrieve parameter names.
+ * Returns an array of trimmed, non-empty parameter names.
+ *
+ * @public
+ * @since v7.0.0
+ * @see toStringConstructor
+ */
 export declare function getConstructorArgNames(target: any): string[];

package/lib/types/utils/getRandomId.d.ts

@@ -1 +1,9 @@
+/**
+ * Generates a random identifier string starting with 'e'.
+ *
+ * Uses base-36 encoding of a random number to create a unique identifier.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function getRandomId(): string;

package/lib/types/utils/getValue.d.ts

@@ -1,32 +1,13 @@
 /**
- * Get value from scope
- * @param {string} expression
- * @param scope
- * @returns {any}
+ * Retrieves a value from an object using a dot-separated path expression.
+ *
+ * Supports flexible argument order (scope-first or expression-first), optional default values,
+ * and custom path separators. Can navigate nested objects and call .get() methods when available.
+ *
+ * @public
+ * @since v7.0.0
  */
 export declare function getValue<T = any>(scope: any, expression: string | undefined): T | undefined;
-/**
- * Get value from scope
- * @param {string} expression
- * @param scope
- * @param defaultValue
- * @param separator
- * @returns {any}
- */
 export declare function getValue<T = any>(scope: any, expression: string | undefined, defaultValue: T, separator?: string): T;
-/**
- * Get value from scope
- * @param {string} expression
- * @param scope
- * @returns {any}
- */
 export declare function getValue<T = any>(expression: string | undefined, scope: any): T | undefined;
-/**
- * Get value from scope
- * @param {string} expression
- * @param scope
- * @param defaultValue
- * @param separator
- * @returns {any}
- */
 export declare function getValue<T = any>(expression: string | undefined, scope: any, defaultValue: T, separator?: string): T;

package/lib/types/utils/hasJsonMethod.d.ts

@@ -1 +1,7 @@
+/**
+ * Checks whether an object has a toJSON method.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function hasJsonMethod(obj: any): any;

package/lib/types/utils/http/getHostInfoFromPort.d.ts

@@ -1,7 +1,22 @@
+/**
+ * Parses an address-port combination and returns host information with protocol.
+ *
+ * Accepts either a numeric port or a string in the format "address:port".
+ * Returns an object with protocol, address, port, and a toString method for URL formatting.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function getHostInfoFromPort(protocol: string, addressPort: any): {
     protocol: string;
     address: string;
     port: number;
     toString(): string;
 };
+/**
+ * Type alias for the return value of {@link getHostInfoFromPort}.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export type ReturnHostInfoFromPort = ReturnType<typeof getHostInfoFromPort>;

package/lib/types/utils/inheritedDescriptorOf.d.ts

@@ -1 +1,7 @@
+/**
+ * Retrieves the property descriptor for a given property key from the target's inheritance chain.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function inheritedDescriptorOf(target: any, propertyKey: string): PropertyDescriptor | undefined;

package/lib/types/utils/isArray.d.ts

@@ -1,13 +1,14 @@
 /**
- * Return true if value is an array
- * @param target
- * @returns {boolean}
+ * Checks if a value is an array.
+ *
+ * @public
+ * @since v7.0.0
  */
 export declare function isArray<T = any>(target: unknown): target is T[];
 /**
- * Return true if the clazz is an array.
- * @param target
- * @returns {boolean}
- * @ignore
+ * Checks if a value is the Array constructor or an array instance.
+ *
+ * @public
+ * @since v7.0.0
  */
 export declare function isArrayOrArrayClass<T = any>(target: unknown): target is T[];

package/lib/types/utils/isArrowFn.d.ts

@@ -1 +1,7 @@
+/**
+ * Checks if a value is an arrow function by verifying it has no prototype property.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export declare function isArrowFn(target: any): target is Function;