@tsed/core 8.18.2 → 8.19.1

package/lib/esm/decorators/storeFn.js

@@ -1,9 +1,13 @@
 import { Store } from "../types/Store.js";
 /**
- * Create a store correctly configured from the parameters given by the decorator.
- * The `fn` can return a decorator that will be initialized with the parameters (target, propertyKey, descriptor).
- * @param {(store: Store, parameters: DecoratorParameters) => void} fn
- * @returns {Function}
+ * Creates a decorator factory that initializes a Store from decorator parameters and invokes a callback.
+ *
+ * The callback receives both the Store instance and the original decorator parameters.
+ * If the callback returns a function, that function is invoked with the same decorator parameters.
+ *
+ * @public
+ * @since v7.0.0
+ * @see Store
  */
 export function StoreFn(fn) {
     return (...parameters) => {

package/lib/esm/decorators/storeMerge.js

@@ -1,4 +1,14 @@
 import { StoreFn } from "./storeFn.js";
+/**
+ * Creates a decorator that merges a key-value pair into the target's Store metadata.
+ *
+ * Uses {@link Store.merge} internally to deep-merge the provided value with existing metadata.
+ *
+ * @public
+ * @since v7.0.0
+ * @see StoreFn
+ * @see Store
+ */
 export function StoreMerge(key, value) {
     return StoreFn((store) => {
         store.merge(key, value);

package/lib/esm/decorators/storeSet.js

@@ -1,4 +1,14 @@
 import { StoreFn } from "./storeFn.js";
+/**
+ * Creates a decorator that sets a key-value pair in the target's Store metadata.
+ *
+ * Uses {@link Store.set} internally to directly set the provided value (no merging).
+ *
+ * @public
+ * @since v7.0.0
+ * @see StoreFn
+ * @see Store
+ */
 export function StoreSet(key, value) {
     return StoreFn((store) => {
         store.set(key, value);

package/lib/esm/errors/UnsupportedDecoratorType.js

@@ -1,6 +1,14 @@
 import { classOf } from "../utils/classOf.js";
 import { decoratorTypeOf } from "../utils/decoratorTypeOf.js";
 import { nameOf } from "../utils/nameOf.js";
+/**
+ * Error thrown when a decorator is used in an unsupported location or context.
+ *
+ * Provides a descriptive message indicating where the decorator was applied and why it's invalid.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export class UnsupportedDecoratorType extends Error {
     constructor(decorator, args) {
         super(UnsupportedDecoratorType.buildMessage(decorator, args));

package/lib/esm/types/DecoratorTypes.js

@@ -1,11 +1,27 @@
+/**
+ * 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 var DecoratorTypes;
 (function (DecoratorTypes) {
+    /** Decorator applied to an instance parameter */
     DecoratorTypes["PARAM"] = "parameter";
+    /** Decorator applied to a constructor parameter */
     DecoratorTypes["PARAM_CTOR"] = "parameter.constructor";
+    /** Decorator applied to a static method parameter */
     DecoratorTypes["PARAM_STC"] = "parameter.static";
+    /** Decorator applied to an instance property */
     DecoratorTypes["PROP"] = "property";
+    /** Decorator applied to a static property */
     DecoratorTypes["PROP_STC"] = "property.static";
+    /** Decorator applied to an instance method */
     DecoratorTypes["METHOD"] = "method";
+    /** Decorator applied to a static method */
     DecoratorTypes["METHOD_STC"] = "method.static";
+    /** Decorator applied to a class */
     DecoratorTypes["CLASS"] = "class";
 })(DecoratorTypes || (DecoratorTypes = {}));

package/lib/esm/types/Env.js

@@ -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 var Env;
 (function (Env) {
@@ -8,8 +13,9 @@ export var Env;
     Env["TEST"] = "test";
 })(Env || (Env = {}));
 /**
- * Fallback
- * @type {Env}
+ * Compatibility alias. Prefer using `Env` directly.
+ *
+ * @deprecated Use `Env` directly.
  */
 // tslint:disable-next-line: variable-name
 export const EnvTypes = Env;

package/lib/esm/types/Metadata.js

@@ -25,6 +25,15 @@ const DESIGN_RETURN_TYPE = "design:returntype";
  */
 const PROPERTIES = new Map();
 /**
+ * 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 class Metadata {

package/lib/esm/types/Store.js

@@ -7,18 +7,22 @@ import { nameOf } from "../utils/nameOf.js";
 import { DecoratorTypes } from "./DecoratorTypes.js";
 import { Metadata } from "./Metadata.js";
 /**
+ * Metadata key used to reference the class-level store.
  * @ignore
  */
 export const CLASS_STORE = "tsed:class:store";
 /**
+ * Metadata key used to reference the method-level store.
  * @ignore
  */
 export const METHOD_STORE = "tsed:method:store";
 /**
+ * Metadata key used to reference the property-level store.
  * @ignore
  */
 export const PROPERTY_STORE = "tsed:property:store";
 /**
+ * Metadata key used to reference the parameter-level store.
  * @ignore
  */
 export const PARAM_STORE = "tsed:param:store";
@@ -59,6 +63,16 @@ function defineStore(args) {
             return storeGet(CLASS_STORE, target);
     }
 }
+/**
+ * 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 class Store {
     constructor() {
         this._entries = new Map();

package/lib/esm/types/Type.js

@@ -1,5 +1,7 @@
 /**
- * An example of a `Type` is `MyCustomComponent` filters, which in JavaScript is represented by
- * the `MyCustomComponent` constructor function.
+ * 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 const Type = Function;

package/lib/esm/utils/AnyToPromise.js

@@ -11,6 +11,11 @@ function isResponse(obj) {
 /**
  * @ignore
  */
+/**
+ * Represents the lifecycle state of an `AnyToPromise` operation.
+ *
+ * @public
+ */
 export var AnyToPromiseStatus;
 (function (AnyToPromiseStatus) {
     AnyToPromiseStatus["PENDING"] = "PENDING";
@@ -18,12 +23,27 @@ export var AnyToPromiseStatus;
     AnyToPromiseStatus["RESOLVED"] = "RESOLVED";
     AnyToPromiseStatus["REJECTED"] = "REJECTED";
 })(AnyToPromiseStatus || (AnyToPromiseStatus = {}));
+/**
+ * Describes the high-level response kind produced by `AnyToPromise`.
+ *
+ * @public
+ */
 export var AnyToPromiseResponseTypes;
 (function (AnyToPromiseResponseTypes) {
     AnyToPromiseResponseTypes["STREAM"] = "STREAM";
     AnyToPromiseResponseTypes["BUFFER"] = "BUFFER";
     AnyToPromiseResponseTypes["DATA"] = "DATA";
 })(AnyToPromiseResponseTypes || (AnyToPromiseResponseTypes = {}));
+/**
+ * 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 class AnyToPromise {
     #resolves;
     #rejects;

package/lib/esm/utils/ancestorOf.js

@@ -1,6 +1,23 @@
+/**
+ * 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 function ancestorOf(target) {
     return target && Object.getPrototypeOf(target);
 }
+/**
+ * Returns the inherited class (ancestor) of the given target.
+ *
+ * An alias for {@link ancestorOf}.
+ *
+ * @public
+ * @since v7.0.0
+ * @see ancestorOf
+ */
 export function getInheritedClass(target) {
     return ancestorOf(target);
 }

package/lib/esm/utils/ancestorsOf.js

@@ -2,9 +2,15 @@ import { getInheritedClass } from "./ancestorOf.js";
 import { classOf } from "./classOf.js";
 import { nameOf } from "./nameOf.js";
 /**
+ * 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 function ancestorsOf(target) {
     const classes = [];

package/lib/esm/utils/catchError.js

@@ -1,3 +1,9 @@
+/**
+ * Executes a callback and returns any thrown error, or undefined if no error occurred.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export function catchError(cb) {
     try {
         cb();
@@ -6,6 +12,12 @@ export function catchError(cb) {
         return er;
     }
 }
+/**
+ * Executes an async callback and returns any thrown error, or undefined if no error occurred.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export async function catchAsyncError(cb) {
     try {
         await cb();

package/lib/esm/utils/classOf.js

@@ -1,16 +1,23 @@
 /**
- * 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 function getClass(target) {
     return target.prototype ? target : target.constructor;
 }
 /**
- * Get the provide constructor if target is an instance.
- * @param target
- * @returns {*}
- * @alias getClass
+ * Alias of `getClass`.
+ * @see getClass
  */
 export function classOf(target) {
     return getClass(target);

package/lib/esm/utils/cleanObject.js

@@ -1,8 +1,12 @@
 import { isProtectedKey } from "./isProtectedKey.js";
 /**
- * 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 function cleanObject(obj, ignore = []) {
     return Object.entries(obj).reduce((obj, [key, value]) => {

package/lib/esm/utils/constructorOf.js

@@ -1,13 +1,24 @@
 /**
- * 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 function getConstructor(target) {
     return typeof target === "function" ? target : target.constructor;
 }
 /**
- * Get the class constructor
- * @param target
+ * Alias of `getConstructor`.
+ * @see getConstructor
  */
 export function constructorOf(target) {
     return getConstructor(target);

package/lib/esm/utils/createInstance.js

@@ -1,4 +1,15 @@
 import { classOf } from "./classOf.js";
+/**
+ * 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 function createInstance(obj) {
     return obj ? (classOf(obj) !== Object ? Object.create(obj) : {}) : {};
 }

package/lib/esm/utils/decorateMethodsOf.js

@@ -3,6 +3,17 @@ import { classOf } from "./classOf.js";
 import { descriptorOf } from "./descriptorOf.js";
 import { methodsOf } from "./methodsOf.js";
 import { prototypeOf } from "./prototypeOf.js";
+/**
+ * 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 function decorateMethodsOf(klass, decorator) {
     methodsOf(klass).forEach(({ target, propertyKey }) => {
         const proto = prototypeOf(klass);

package/lib/esm/utils/decoratorArgs.js

@@ -1,4 +1,14 @@
 import { descriptorOf } from "./descriptorOf.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 function decoratorArgs(target, propertyKey) {
     return [target, propertyKey, descriptorOf(target, propertyKey)];
 }

package/lib/esm/utils/decoratorTypeOf.js

@@ -1,12 +1,22 @@
 import { DecoratorTypes } from "../types/DecoratorTypes.js";
 import { classOf } from "./classOf.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 function decoratorTypeOf(args) {
     const [target, propertyKey, descriptor] = args;
     const staticType = (type) => {
         return target !== classOf(target) ? type : `${type}.static`;
     };
     if (typeof descriptor === "number") {
-        return propertyKey ? staticType("parameter") : "parameter.constructor";
+        return propertyKey ? staticType("parameter") : DecoratorTypes.PARAM_CTOR;
     }
     if (descriptor && descriptor.value) {
         return staticType("method");

package/lib/esm/utils/deepClone.js

@@ -7,9 +7,13 @@ import { isRegExp } from "./isRegExp.js";
 import { isSymbol } from "./isSymbol.js";
 const isBasicType = (source) => isNil(source) || isPrimitive(source) || isSymbol(source) || isFunction(source);
 /**
- * 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 const deepClone = (source, stack = new WeakMap()) => {
     // provides an early exit for simple cases

package/lib/esm/utils/deepMerge.js

@@ -3,6 +3,12 @@ import { isFunction } from "./isFunction.js";
 import { isPrimitive } from "./isPrimitive.js";
 import { isSymbol } from "./isSymbol.js";
 import { objectKeys } from "./objectKeys.js";
+/**
+ * Creates a merge reducer using a custom comparator function.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export function mergeReducerBuilder(cb) {
     return (collection, value, options) => {
         const index = collection.findIndex((item) => cb(item, value));
@@ -29,6 +35,15 @@ function shouldReturnObj(obj, source) {
 function shouldReturnSource(obj, source) {
     return obj === undefined || obj === null || (obj === "" && source !== "");
 }
+/**
+ * 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 function deepMerge(source, obj, options = {}) {
     if (shouldReturnSource(obj, source)) {
         return source;

package/lib/esm/utils/descriptorOf.js

@@ -1,12 +1,23 @@
 /**
- * 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 function descriptorOf(target, propertyKey) {
     return Reflect.getOwnPropertyDescriptor((target && target.prototype) || target, propertyKey);
 }
+/**
+ * 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 function isMethodDescriptor(target, propertyKey) {
     return descriptorOf(target, propertyKey)?.value;
 }

package/lib/esm/utils/getClassOrSymbol.js

@@ -1,5 +1,13 @@
 import { classOf } from "./classOf.js";
 import { isClass } from "./isClass.js";
+/**
+ * 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 function getClassOrSymbol(target) {
     return isClass(target) ? classOf(target) : target;
 }

package/lib/esm/utils/getConstructorArgNames.js

@@ -1,4 +1,14 @@
 import { toStringConstructor } from "./toStringConstructor.js";
+/**
+ * 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 function getConstructorArgNames(target) {
     return toStringConstructor(target)
         .split("constructor(")[1]

package/lib/esm/utils/getRandomId.js

@@ -1,3 +1,11 @@
+/**
+ * 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 function getRandomId() {
     return `e${Math.random().toString(36).substring(7)}`;
 }

package/lib/esm/utils/hasJsonMethod.js

@@ -1,3 +1,9 @@
+/**
+ * Checks whether an object has a toJSON method.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export function hasJsonMethod(obj) {
     return obj && typeof obj.toJSON === "function";
 }

package/lib/esm/utils/http/getHostInfoFromPort.js

@@ -1,3 +1,12 @@
+/**
+ * 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 function getHostInfoFromPort(protocol, addressPort) {
     let address = "0.0.0.0";
     let port = addressPort;

package/lib/esm/utils/inheritedDescriptorOf.js

@@ -1,4 +1,10 @@
 import { ancestorsOf } from "./ancestorsOf.js";
+/**
+ * Retrieves the property descriptor for a given property key from the target's inheritance chain.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export function inheritedDescriptorOf(target, propertyKey) {
     for (const klass of ancestorsOf(target)) {
         const descriptor = Object.getOwnPropertyDescriptor((klass && klass.prototype) || klass, propertyKey);

package/lib/esm/utils/isArray.js

@@ -1,16 +1,17 @@
 /**
- * Return true if value is an array
- * @param target
- * @returns {boolean}
+ * Checks if a value is an array.
+ *
+ * @public
+ * @since v7.0.0
  */
 export function isArray(target) {
     return Array.isArray(target);
 }
 /**
- * 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 function isArrayOrArrayClass(target) {
     return target === Array || isArray(target);

package/lib/esm/utils/isArrowFn.js

@@ -1,4 +1,10 @@
 import { isFunction } from "./isFunction.js";
+/**
+ * Checks if a value is an arrow function by verifying it has no prototype property.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export function isArrowFn(target) {
     return target && isFunction(target) && !target.prototype;
 }

package/lib/esm/utils/isBoolean.js

@@ -1,11 +1,18 @@
 /**
+ * Checks if a value is a boolean primitive.
  *
- * @param target
- * @returns {boolean}
+ * @public
+ * @since v7.0.0
  */
 export function isBoolean(target) {
     return typeof target === "boolean" || target instanceof Boolean || target === Boolean;
 }
+/**
+ * Checks if a value is a boolean primitive, Boolean object, or the Boolean constructor.
+ *
+ * @public
+ * @since v7.0.0
+ */
 export function isBooleanOrBooleanClass(target) {
     return typeof target === "boolean" || target instanceof Boolean || target === Boolean;
 }