@decaf-ts/decorator-validation 1.6.5 → 1.7.0

package/lib/constants/index.cjs

@@ -15,4 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./validation.cjs"), exports);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvY29uc3RhbnRzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSwrQ0FBNkIiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgKiBmcm9tIFwiLi92YWxpZGF0aW9uXCI7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvY29uc3RhbnRzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSxtREFBNkIiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgKiBmcm9tIFwiLi92YWxpZGF0aW9uXCI7XG4iXX0=

package/lib/esm/index.d.ts

@@ -1,43 +1,11 @@
 /**
  * @module decorator-validation
+ * @description TypeScript decorator-based validation library
+ * @summary This module provides a comprehensive validation framework using TypeScript decorators.
+ * It exposes utility functions, validation decorators, and model-related functionality for
+ * implementing type-safe, declarative validation in TypeScript applications.
  */
-/**
- * @summary Model definition functionality
- * @description defines the base class and related functionality
- *
- * @namespace Model
- * @memberOf module:decorator-validation
- */
-/**
- * @summary Holds all the supported decorators
- * @namespace Decorators
- * @memberOf module:decorator-validation
- */
-/**
- * @summary Validation related functionality
- * @description Defines the Model validation apis and base classes for validators
- *
- * @namespace Validation
- * @memberOf module:decorator-validation
- */
-/**
- * @namespace Dates
- * @memberOf module:decorator-validation
- */
-/**
- * @namespace Hashing
- * @memberOf module:decorator-validation
- */
-/**
- * @namespace Serialization
- * @memberOf module:decorator-validation
- */
-/**
- * @namespace Format
- * @memberOf module:decorator-validation
- */
-export * from "./constants";
 export * from "./utils";
 export * from "./validation";
 export * from "./model";
-export declare const VERSION = "1.6.5";
+export declare const VERSION = "1.7.0";

package/lib/esm/index.js

@@ -1,44 +1,12 @@
 /**
  * @module decorator-validation
+ * @description TypeScript decorator-based validation library
+ * @summary This module provides a comprehensive validation framework using TypeScript decorators.
+ * It exposes utility functions, validation decorators, and model-related functionality for
+ * implementing type-safe, declarative validation in TypeScript applications.
  */
-/**
- * @summary Model definition functionality
- * @description defines the base class and related functionality
- *
- * @namespace Model
- * @memberOf module:decorator-validation
- */
-/**
- * @summary Holds all the supported decorators
- * @namespace Decorators
- * @memberOf module:decorator-validation
- */
-/**
- * @summary Validation related functionality
- * @description Defines the Model validation apis and base classes for validators
- *
- * @namespace Validation
- * @memberOf module:decorator-validation
- */
-/**
- * @namespace Dates
- * @memberOf module:decorator-validation
- */
-/**
- * @namespace Hashing
- * @memberOf module:decorator-validation
- */
-/**
- * @namespace Serialization
- * @memberOf module:decorator-validation
- */
-/**
- * @namespace Format
- * @memberOf module:decorator-validation
- */
-export * from "./constants";
 export * from "./utils";
 export * from "./validation";
 export * from "./model";
-export const VERSION = "1.6.5";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7O0dBRUc7QUFFSDs7Ozs7O0dBTUc7QUFFSDs7OztHQUlHO0FBRUg7Ozs7OztHQU1HO0FBRUg7OztHQUdHO0FBRUg7OztHQUdHO0FBRUg7OztHQUdHO0FBRUg7OztHQUdHO0FBRUgsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxTQUFTLENBQUM7QUFDeEIsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxTQUFTLENBQUM7QUFFeEIsTUFBTSxDQUFDLE1BQU0sT0FBTyxHQUFHLGFBQWEsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQG1vZHVsZSBkZWNvcmF0b3ItdmFsaWRhdGlvblxuICovXG5cbi8qKlxuICogQHN1bW1hcnkgTW9kZWwgZGVmaW5pdGlvbiBmdW5jdGlvbmFsaXR5XG4gKiBAZGVzY3JpcHRpb24gZGVmaW5lcyB0aGUgYmFzZSBjbGFzcyBhbmQgcmVsYXRlZCBmdW5jdGlvbmFsaXR5XG4gKlxuICogQG5hbWVzcGFjZSBNb2RlbFxuICogQG1lbWJlck9mIG1vZHVsZTpkZWNvcmF0b3ItdmFsaWRhdGlvblxuICovXG5cbi8qKlxuICogQHN1bW1hcnkgSG9sZHMgYWxsIHRoZSBzdXBwb3J0ZWQgZGVjb3JhdG9yc1xuICogQG5hbWVzcGFjZSBEZWNvcmF0b3JzXG4gKiBAbWVtYmVyT2YgbW9kdWxlOmRlY29yYXRvci12YWxpZGF0aW9uXG4gKi9cblxuLyoqXG4gKiBAc3VtbWFyeSBWYWxpZGF0aW9uIHJlbGF0ZWQgZnVuY3Rpb25hbGl0eVxuICogQGRlc2NyaXB0aW9uIERlZmluZXMgdGhlIE1vZGVsIHZhbGlkYXRpb24gYXBpcyBhbmQgYmFzZSBjbGFzc2VzIGZvciB2YWxpZGF0b3JzXG4gKlxuICogQG5hbWVzcGFjZSBWYWxpZGF0aW9uXG4gKiBAbWVtYmVyT2YgbW9kdWxlOmRlY29yYXRvci12YWxpZGF0aW9uXG4gKi9cblxuLyoqXG4gKiBAbmFtZXNwYWNlIERhdGVzXG4gKiBAbWVtYmVyT2YgbW9kdWxlOmRlY29yYXRvci12YWxpZGF0aW9uXG4gKi9cblxuLyoqXG4gKiBAbmFtZXNwYWNlIEhhc2hpbmdcbiAqIEBtZW1iZXJPZiBtb2R1bGU6ZGVjb3JhdG9yLXZhbGlkYXRpb25cbiAqL1xuXG4vKipcbiAqIEBuYW1lc3BhY2UgU2VyaWFsaXphdGlvblxuICogQG1lbWJlck9mIG1vZHVsZTpkZWNvcmF0b3ItdmFsaWRhdGlvblxuICovXG5cbi8qKlxuICogQG5hbWVzcGFjZSBGb3JtYXRcbiAqIEBtZW1iZXJPZiBtb2R1bGU6ZGVjb3JhdG9yLXZhbGlkYXRpb25cbiAqL1xuXG5leHBvcnQgKiBmcm9tIFwiLi9jb25zdGFudHNcIjtcbmV4cG9ydCAqIGZyb20gXCIuL3V0aWxzXCI7XG5leHBvcnQgKiBmcm9tIFwiLi92YWxpZGF0aW9uXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9tb2RlbFwiO1xuXG5leHBvcnQgY29uc3QgVkVSU0lPTiA9IFwiIyNWRVJTSU9OIyNcIjtcbiJdfQ==
+export const VERSION = "1.7.0";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7OztHQU1HO0FBQ0gsY0FBYyxTQUFTLENBQUM7QUFDeEIsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxTQUFTLENBQUM7QUFFeEIsTUFBTSxDQUFDLE1BQU0sT0FBTyxHQUFHLGFBQWEsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQG1vZHVsZSBkZWNvcmF0b3ItdmFsaWRhdGlvblxuICogQGRlc2NyaXB0aW9uIFR5cGVTY3JpcHQgZGVjb3JhdG9yLWJhc2VkIHZhbGlkYXRpb24gbGlicmFyeVxuICogQHN1bW1hcnkgVGhpcyBtb2R1bGUgcHJvdmlkZXMgYSBjb21wcmVoZW5zaXZlIHZhbGlkYXRpb24gZnJhbWV3b3JrIHVzaW5nIFR5cGVTY3JpcHQgZGVjb3JhdG9ycy5cbiAqIEl0IGV4cG9zZXMgdXRpbGl0eSBmdW5jdGlvbnMsIHZhbGlkYXRpb24gZGVjb3JhdG9ycywgYW5kIG1vZGVsLXJlbGF0ZWQgZnVuY3Rpb25hbGl0eSBmb3JcbiAqIGltcGxlbWVudGluZyB0eXBlLXNhZmUsIGRlY2xhcmF0aXZlIHZhbGlkYXRpb24gaW4gVHlwZVNjcmlwdCBhcHBsaWNhdGlvbnMuXG4gKi9cbmV4cG9ydCAqIGZyb20gXCIuL3V0aWxzXCI7XG5leHBvcnQgKiBmcm9tIFwiLi92YWxpZGF0aW9uXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9tb2RlbFwiO1xuXG5leHBvcnQgY29uc3QgVkVSU0lPTiA9IFwiIyNWRVJTSU9OIyNcIjtcbiJdfQ==

package/lib/esm/model/Model.d.ts

@@ -1,71 +1,108 @@
 import { BuilderRegistry } from "../utils/registry";
 import { ModelErrorDefinition } from "./ModelErrorDefinition";
 import { Comparable, Constructor, Hashable, ModelArg, ModelBuilderFunction, ModelConstructor, Serializable, Validatable } from "./types";
-export declare function isPropertyModel<M extends Model>(target: M, attribute: string): boolean | string | undefined;
 /**
- * @summary For Serialization/deserialization purposes.
- * @description Reads the {@link ModelKeys.ANCHOR} property of a {@link Model} to discover the class to instantiate
- *
- * @function isModel
- * @memberOf module:decorator-validation.Validation
- * @category Validation
- */
-export declare function isModel(target: Record<string, any>): boolean;
-/**
- * @summary ModelRegistry Interface
+ * @description Registry type for storing and retrieving model constructors
+ * @summary The ModelRegistry type defines a registry for model constructors that extends
+ * the BuilderRegistry interface. It provides a standardized way to register, retrieve,
+ * and build model instances, enabling the model system to work with different types of models.
  *
  * @interface ModelRegistry
- * @extends BuilderRegistry<Model>
- *
+ * @template T Type of model that can be registered, must extend Model
+ * @extends BuilderRegistry<T>
+ * @memberOf module:decorator-validation
  * @category Model
  */
 export type ModelRegistry<T extends Model> = BuilderRegistry<T>;
 /**
- * @summary Util class to enable serialization and correct rebuilding
+ * @description Registry manager for model constructors that enables serialization and rebuilding
+ * @summary The ModelRegistryManager implements the ModelRegistry interface and provides
+ * functionality for registering, retrieving, and building model instances. It maintains
+ * a cache of model constructors indexed by name, allowing for efficient lookup and instantiation.
+ * This class is essential for the serialization and deserialization of model objects.
  *
- * @param {string} anchorKey defaults to {@link ModelKeys.ANCHOR}. The property name where the registered class name is stored;
- * @param {function(Record<string, any>): boolean} [testFunction] method to test if the provided object is a Model Object. defaults to {@link isModel}
+ * @param {function(Record<string, any>): boolean} [testFunction] - Function to test if an object is a model, defaults to {@link Model#isModel}
  *
  * @class ModelRegistryManager
- * @implements ModelRegistry
- *
+ * @template M Type of model that can be registered, must extend Model
+ * @implements ModelRegistry<M>
  * @category Model
+ *
+ * @example
+ * ```typescript
+ * // Create a model registry
+ * const registry = new ModelRegistryManager();
+ *
+ * // Register a model class
+ * registry.register(User);
+ *
+ * // Retrieve a model constructor by name
+ * const UserClass = registry.get("User");
+ *
+ * // Build a model instance from a plain object
+ * const userData = { name: "John", age: 30 };
+ * const user = registry.build(userData, "User");
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant R as ModelRegistryManager
+ *   participant M as Model Class
+ *
+ *   C->>R: new ModelRegistryManager(testFunction)
+ *   C->>R: register(ModelClass)
+ *   R->>R: Store in cache
+ *   C->>R: get("ModelName")
+ *   R-->>C: ModelClass constructor
+ *   C->>R: build(data, "ModelName")
+ *   R->>R: Get constructor from cache
+ *   R->>M: new ModelClass(data)
+ *   M-->>R: Model instance
+ *   R-->>C: Model instance
  */
-export declare class ModelRegistryManager<T extends Model> implements ModelRegistry<T> {
+export declare class ModelRegistryManager<M extends Model> implements ModelRegistry<M> {
     private cache;
     private readonly testFunction;
     constructor(testFunction?: (obj: Record<string, any>) => boolean);
     /**
-     * @summary register new Models
-     * @param {any} constructor
-     * @param {string} [name] when not defined, the name of the constructor will be used
+     * @description Registers a model constructor with the registry
+     * @summary Adds a model constructor to the registry cache, making it available for
+     * later retrieval and instantiation. If no name is provided, the constructor's name
+     * property is used as the key in the registry.
+     *
+     * @param {ModelConstructor<M>} constructor - The model constructor to register
+     * @param {string} [name] - Optional name to register the constructor under, defaults to constructor.name
+     * @return {void}
+     * @throws {Error} If the constructor is not a function
      */
-    register(constructor: ModelConstructor<T>, name?: string): void;
+    register(constructor: ModelConstructor<M>, name?: string): void;
     /**
      * @summary Gets a registered Model {@link ModelConstructor}
      * @param {string} name
      */
-    get(name: string): ModelConstructor<T> | undefined;
+    get(name: string): ModelConstructor<M> | undefined;
     /**
      * @param {Record<string, any>} obj
      * @param {string} [clazz] when provided, it will attempt to find the matching constructor
      *
      * @throws Error If clazz is not found, or obj is not a {@link Model} meaning it has no {@link ModelKeys.ANCHOR} property
      */
-    build(obj?: Record<string, any>, clazz?: string): T;
+    build(obj?: Record<string, any>, clazz?: string): M;
 }
 /**
  * @summary Bulk Registers Models
  * @description Useful when using bundlers that might not evaluate all the code at once
  *
- * @param {Array<Constructor<T>> | Array<{name: string, constructor: Constructor<T>}>} [models]
+ * @template M extends Model
+ * @param {Array<Constructor<M>> | Array<{name: string, constructor: Constructor<M>}>} [models]
  *
- * @memberOf module:decorator-validation.Model
+ * @memberOf module:decorator-validation
  * @category Model
  */
-export declare function bulkModelRegister<T extends Model>(...models: (Constructor<T> | {
+export declare function bulkModelRegister<M extends Model>(...models: (Constructor<M> | {
     name: string;
-    constructor: Constructor<T>;
+    constructor: Constructor<M>;
 })[]): void;
 /**
  * @summary Abstract class representing a Validatable Model object
@@ -75,9 +112,10 @@ export declare function bulkModelRegister<T extends Model>(...models: (Construct
  *  - Have all their required properties marked with '!';
  *  - Have all their optional properties marked as '?':
  *
- * @param {Model | {}} model base object from which to populate properties from
+ * @param {ModelArg<Model>} model base object from which to populate properties from
  *
  * @class Model
+ * @category Model
  * @abstract
  * @implements Validatable
  * @implements Serializable
@@ -189,16 +227,50 @@ export declare abstract class Model implements Validatable, Serializable, Hashab
      * @see ModelRegistry
      */
     static build<T extends Model>(obj?: Record<string, any>, clazz?: string): T;
-    static getMetadata<V extends Model>(model: V): any;
+    static getMetadata<M extends Model>(model: M): any;
     static getAttributes<V extends Model>(model: Constructor<V> | V): string[];
-    static equals<V extends Model>(obj1: V, obj2: V, ...exceptions: any[]): boolean;
-    static hasErrors<V extends Model>(model: V, ...propsToIgnore: string[]): ModelErrorDefinition | undefined;
-    static serialize<V extends Model>(model: V): any;
-    static hash<V extends Model>(model: V): any;
+    static equals<M extends Model>(obj1: M, obj2: M, ...exceptions: any[]): boolean;
+    static hasErrors<M extends Model>(model: M, ...propsToIgnore: string[]): ModelErrorDefinition | undefined;
+    static serialize<M extends Model>(model: M): any;
+    static hash<M extends Model>(model: M): any;
     /**
      * @summary Builds the key to store as Metadata under Reflections
      * @description concatenates {@link ModelKeys#REFLECT} with the provided key
      * @param {string} str
      */
     static key(str: string): string;
+    /**
+     * @description Determines if an object is a model instance or has model metadata
+     * @summary Checks whether a given object is either an instance of the Model class or
+     * has model metadata attached to it. This function is essential for serialization and
+     * deserialization processes, as it helps identify model objects that need special handling.
+     * It safely handles potential errors during metadata retrieval.
+     *
+     * @param {Record<string, any>} target - The object to check
+     * @return {boolean} True if the object is a model instance or has model metadata, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Check if an object is a model
+     * const user = new User({ name: "John" });
+     * const isUserModel = isModel(user); // true
+     *
+     * // Check a plain object
+     * const plainObject = { name: "John" };
+     * const isPlainObjectModel = isModel(plainObject); // false
+     * ```
+     */
+    static isModel(target: Record<string, any>): boolean;
+    /**
+     * @description Checks if a property of a model is itself a model or has a model type
+     * @summary Determines whether a specific property of a model instance is either a model instance
+     * or has a type that is registered as a model. This function is used for model serialization
+     * and deserialization to properly handle nested models.
+     * @template M extends {@link Model}
+     * @param {M} target - The model instance to check
+     * @param {string} attribute - The property name to check
+     * @return {boolean | string | undefined} Returns true if the property is a model instance,
+     * the model name if the property has a model type, or undefined if not a model
+     */
+    static isPropertyModel<M extends Model>(target: M, attribute: string): boolean | string | undefined;
 }