@decaf-ts/decorator-validation 1.20.0 → 1.21.1

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

@@ -1,86 +0,0 @@
-/**
- * @summary Reverses the process from {@link formatDate}
- *
- * @param {string} date the date string to be converted back into date
- * @param {string} format the date format
- * @return {Date} the date from the format or the standard new Date({@prop date}) if the string couldn't be parsed (are you sure the format matches the string?)
- *
- * @function dateFromFormat
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare function dateFromFormat(date: string, format: string): Date;
-/**
- * @description Binds a specific date format to a Date object's toString and toISOString methods using a Proxy
- * @summary Wraps a Date object in a Proxy to return a formatted string when toString or toISOString is called.
- * This function uses the Proxy API to intercept method calls and return the date formatted according
- * to the specified format string, while maintaining all other Date functionality.
- * The proxied Date maintains instanceof Date checks and behaves identically to a Date object.
- * @param {Date} [date] The Date object to modify
- * @param {string} [format] The format string to use for formatting the date
- * @return {Date|undefined} A proxied Date object or undefined if no date was provided
- * @function bindDateToString
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare function bindDateToString(date: Date | undefined, format: string): Date | undefined;
-/**
- * @description Safely checks if a value is a valid Date object
- * @summary A utility function that determines if a value is a valid Date object.
- * This function is more reliable than using instanceof Date as it also checks
- * that the date is not NaN, which can happen with invalid date strings.
- * @param {any} date The value to check
- * @return {boolean} True if the value is a valid Date object, false otherwise
- * @function isValidDate
- * @memberOf module:decorator-validation
- * @category Validation
- */
-export declare function isValidDate(date: any): boolean;
-/**
- * @summary Util function to pad numbers
- * @param {number} num
- *
- * @return {string}
- *
- * @function twoDigitPad
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare function twoDigitPad(num: number): string;
-/**
- * @summary Date Format Handling
- * @description Code from {@link https://stackoverflow.com/questions/3552461/how-to-format-a-javascript-date}
- *
- * <pre>
- *      Using similar formatting as Moment.js, Class DateTimeFormatter (Java), and Class SimpleDateFormat (Java),
- *      I implemented a comprehensive solution formatDate(date, patternStr) where the code is easy to read and modify.
- *      You can display date, time, AM/PM, etc.
- *
- *      Date and Time Patterns
- *      yy = 2-digit year; yyyy = full year
- *      M = digit month; MM = 2-digit month; MMM = short month name; MMMM = full month name
- *      EEEE = full weekday name; EEE = short weekday name
- *      d = digit day; dd = 2-digit day
- *      h = hours am/pm; hh = 2-digit hours am/pm; H = hours; HH = 2-digit hours
- *      m = minutes; mm = 2-digit minutes; aaa = AM/PM
- *      s = seconds; ss = 2-digit seconds
- *      S = miliseconds
- * </pre>
- *
- * @param {Date} date
- * @param {string} [patternStr] defaults to 'yyyy/MM/dd'
- * @return {string} the formatted date
- *
- * @function formatDate
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare function formatDate(date: Date, patternStr?: string): string;
-/**
- * @summary Parses a date from a specified format
- * @param {string} format
- * @param {string | Date | number} [v]
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare function parseDate(format: string, v?: string | Date | number): Date | undefined;

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

@@ -1,56 +0,0 @@
-/**
- * @description Enhanced algorithm for deep comparison of any two values with optional ignored properties
- * @summary Performs a deep equality check between two values, handling various types including primitives, objects, arrays, dates, and more
- * @param {unknown} a - First value to compare
- * @param {unknown} b - Second value to compare
- * @param {string[]} propsToIgnore - A list of property names to ignore during comparison
- * @return {boolean} Returns true if the values are deeply equal, false otherwise
- * @function isEqual
- * @mermaid
- * sequenceDiagram
- *   participant Caller
- *   participant isEqual
- *   participant Recursion
- *
- *   Caller->>isEqual: isEqual(a, b, propsToIgnore)
- *   Note over isEqual: Check simple cases (identity, null, primitives)
- *
- *   alt a === b
- *     isEqual-->>Caller: true (with special case for +0/-0)
- *   else a or b is null
- *     isEqual-->>Caller: a === b
- *   else different types
- *     isEqual-->>Caller: false
- *   else both NaN
- *     isEqual-->>Caller: true
- *   else primitive types
- *     isEqual-->>Caller: a === b
- *   else both Date objects
- *     isEqual-->>Caller: Compare timestamps
- *   else both RegExp objects
- *     isEqual-->>Caller: Compare string representations
- *   else both Error objects
- *     isEqual-->>Caller: Compare name and message
- *   else both Arrays
- *     Note over isEqual: Check length
- *     loop For each element
- *       isEqual->>Recursion: isEqual(a[i], b[i], propsToIgnore)
- *     end
- *   else both Maps or Sets
- *     Note over isEqual: Compare size and entries
- *   else both TypedArrays
- *     Note over isEqual: Compare byte by byte
- *   else both Objects
- *     Note over isEqual: Filter keys by propsToIgnore
- *     Note over isEqual: Compare key counts
- *     loop For each key
- *       isEqual->>Recursion: isEqual(a[key], b[key], propsToIgnore)
- *     end
- *     Note over isEqual: Check Symbol properties
- *     Note over isEqual: Compare prototypes
- *   end
- *
- *   isEqual-->>Caller: Comparison result
- * @memberOf module:decorator-validation
- */
-export declare function isEqual(a: unknown, b: unknown, ...propsToIgnore: string[]): boolean;

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

@@ -1,82 +0,0 @@
-/**
- * @summary Mimics Java's String's Hash implementation
- *
- * @param {string | number | symbol | Date} obj
- * @return {number} hash value of obj
- *
- * @function hashCode
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare function hashCode(obj: string | number | symbol | Date): string;
-/**
- * @summary Defines teh type for a Hashing function
- * @memberOf module:decorator-validation
- * @category Model
- */
-export type HashingFunction = (value: any, ...args: any[]) => string;
-/**
- * @summary Hashes an object by combining the hash of all its properties
- *
- * @param {Record<string, any>} obj
- * @return {string} the resulting hash
- *
- * @function hashObj
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare function hashObj(obj: Record<string, any> | any[]): string;
-export declare const DefaultHashingMethod = "default";
-/**
- * @description Manages hashing methods and provides a unified hashing interface
- * @summary A utility class that provides a registry for different hashing functions and methods to hash objects.
- * The class maintains a cache of registered hashing functions and allows setting a default hashing method.
- * It prevents direct instantiation and provides static methods for registration and hashing.
- *
- * @class Hashing
- * @category Model
- *
- * @example
- * ```typescript
- * // Register a custom hashing function
- * Hashing.register('md5', (obj) => createMD5Hash(obj), true);
- *
- * // Hash an object using default method
- * const hash1 = Hashing.hash(myObject);
- *
- * // Hash using specific method
- * const hash2 = Hashing.hash(myObject, 'md5');
- * ```
- */
-export declare class Hashing {
-    /**
-     * @description Current default hashing method identifier
-     * @private
-     */
-    private static current;
-    /**
-     * @description Cache of registered hashing functions
-     * @private
-     */
-    private static cache;
-    private constructor();
-    /**
-     * @description Retrieves a registered hashing function
-     * @summary Fetches a hashing function from the cache by its key. Throws an error if the method is not registered.
-     *
-     * @param {string} key - The identifier of the hashing function to retrieve
-     * @return {HashingFunction} The requested hashing function
-     * @private
-     */
-    private static get;
-    /**
-     * @description Registers a new hashing function
-     * @summary Adds a new hashing function to the registry. Optionally sets it as the default method.
-     * Throws an error if a method with the same key is already registered.
-     *
-     * @param {string} key - The identifier for the hashing function
-     */
-    static register(key: string, func: HashingFunction, setDefault?: boolean): void;
-    static hash(obj: any, method?: string, ...args: any[]): any;
-    static setDefault(method: string): void;
-}

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

@@ -1,11 +0,0 @@
-export * from "./constants";
-export * from "./DateBuilder";
-export * from "./dates";
-export * from "./equality";
-export * from "./hashing";
-export * from "./PathProxy";
-export * from "./registry";
-export * from "./serializers";
-export * from "./serialization";
-export * from "./strings";
-export * from "./types";

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

@@ -1,68 +0,0 @@
-import { Constructor } from "@decaf-ts/decoration";
-/**
- * @summary Basic interface for Registries
- *
- * @interface IRegistry
- *
- * @category Model
- */
-export interface IRegistry<T> {
-    /**
-     * @summary Registers an Object
-     *
-     * @param {T} obj
-     * @param {any[]} args
-     *
-     * @method
-     */
-    register(obj: T | any, ...args: any[]): void;
-    /**
-     * @summary Retrieves an Object if it can find it
-     *
-     * @param {any} key
-     * @param {any[]} args
-     * @return {T | undefined}
-     *
-     * @method
-     */
-    get(key: any, ...args: any[]): T | undefined;
-}
-/**
- * @summary Basic Builder Registry Interface
- *
- * @template T
- * @interface BuilderRegistry<T>
- *
- * @category Model
- */
-export interface BuilderRegistry<T> extends IRegistry<Constructor<T>> {
-    /**
-     * @summary Retrieves an Builder Object by name if it can
-     *
-     * @param {string} name
-     * @param {any[]} args
-     *
-     * @method
-     */
-    get(name: string, ...args: any[]): Constructor<T> | undefined;
-    /**
-     * @summary Registers a constructor by name
-     *
-     * @param {Constructor<T>} [constructor]
-     * @param {name} name
-     * @param {any[]} args
-     *
-     * @method
-     */
-    register(constructor: Constructor<T>, name?: string, ...args: any[]): void;
-    /**
-     * @summary Builds an Object by name
-     *
-     * @param {{}} obj
-     * @param {any[]} args
-     * @return T
-     *
-     * @method
-     */
-    build(obj: Record<string, any> | T, ...args: any[]): T;
-}

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

@@ -1,12 +0,0 @@
-import { Constructor } from "@decaf-ts/decoration";
-import { Serializer } from "./types";
-export declare class Serialization {
-    private static current;
-    private static cache;
-    private constructor();
-    private static get;
-    static register(key: string, func: Constructor<Serializer<any>>, setDefault?: boolean): void;
-    static serialize(obj: any, method?: string, ...args: any[]): any;
-    static deserialize(obj: string, method?: string, ...args: any[]): any;
-    static setDefault(method: string): void;
-}

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

@@ -1,41 +0,0 @@
-import { Serializer } from "./types";
-import { Model } from "../model/Model";
-/**
- * @summary Concrete implementation of a {@link Serializer} in JSON format
- * @description JS's native JSON.stringify (used here) is not deterministic
- * and therefore should not be used for hashing purposes
- *
- * To keep dependencies low, we will not implement this, but we recommend
- * implementing a similar {@link JSONSerializer} using 'deterministic-json' libraries
- *
- * @class JSONSerializer
- * @implements Serializer
- *
- * @category Model
- */
-export declare class JSONSerializer<T extends Model<boolean>> implements Serializer<T> {
-    constructor();
-    /**
-     * @summary prepares the model for serialization
-     * @description returns a shallow copy of the object, containing an enumerable {@link ModelKeys#ANCHOR} property
-     * so the object can be recognized upon deserialization
-     *
-     * @param {T} model
-     * @protected
-     */
-    protected preSerialize(model: T, ...args: any[]): Record<string, any>;
-    /**
-     * @summary Rebuilds a model from a serialization
-     * @param {string} str
-     *
-     * @throws {Error} If it fails to parse the string, or to build the model
-     */
-    deserialize(str: string, ...args: any[]): T;
-    /**
-     * @summary Serializes a model
-     * @param {T} model
-     *
-     * @throws {Error} if fails to serialize
-     */
-    serialize(model: T, ...args: any[]): string;
-}

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

@@ -1,25 +0,0 @@
-/**
- * @summary Util function to provide string format functionality similar to C#'s string.format
- *
- * @param {string} string
- * @param {Array<string | number>} [args] replacements made by order of appearance (replacement0 wil replace {0} and so on)
- * @return {string} formatted string
- *
- * @function stringFormat
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare function stringFormat(string: string, ...args: (string | number)[]): string;
-/**
- * @summary Util function to provide string format functionality similar to C#'s string.format
- * @description alias for {@link stringFormat}
- *
- * @param {string} string
- * @param {string} args replacements made by order of appearance (replacement0 wil replace {0} and so on)
- * @return {string} formatted string
- *
- * @function sf
- * @memberOf module:decorator-validation
- * @category Model
- */
-export declare const sf: typeof stringFormat;

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

@@ -1,35 +0,0 @@
-import { Model } from "../model";
-/**
- * @description Interface for serializing and deserializing model objects
- * @summary Defines the contract for classes that can convert model objects to and from string representations.
- * Serializers are used to persist models or transmit them over networks.
- *
- * @interface Serializer
- * @template T Type of model that can be serialized, must extend Model
- * @memberOf module:decorator-validation
- * @category Model
- */
-export interface Serializer<M extends Model> {
-    /**
-     * @description Converts a model object to a string representation
-     * @summary Serializes a model instance into a string format that can be stored or transmitted.
-     * Additional arguments can be provided to customize the serialization process.
-     *
-     * @param {T} model - The model instance to serialize
-     * @param {...any} args - Additional arguments for the serialization process
-     * @return {string} The serialized representation of the model
-     * @throws {Error} If the model cannot be serialized
-     */
-    serialize(model: M, ...args: any[]): string;
-    /**
-     * @description Reconstructs a model object from its string representation
-     * @summary Deserializes a string back into a model instance.
-     * Additional arguments can be provided to customize the deserialization process.
-     *
-     * @param {string} str - The serialized string to convert back to a model
-     * @param {...any} args - Additional arguments for the deserialization process
-     * @return {T} The reconstructed model instance
-     * @throws {Error} If the string cannot be deserialized into a valid model
-     */
-    deserialize(str: string, ...args: any[]): M;
-}

package/lib/types/validation/Validation.d.ts

@@ -1,53 +0,0 @@
-import { Validator } from "./Validators/Validator";
-import { IValidatorRegistry, ValidatorDefinition } from "./types";
-/**
- * @summary Static class acting as a namespace for the Validation
- *
- * @class Validation
- * @static
- *
- * @category Validation
- */
-export declare class Validation {
-    private static actingValidatorRegistry?;
-    private constructor();
-    /**
-     * @summary Defines the acting ValidatorRegistry
-     *
-     * @param {IValidatorRegistry} validatorRegistry the new implementation of the validator Registry
-     * @param {function(Validator): Validator} [migrationHandler] the method to map the validator if required;
-     */
-    static setRegistry(validatorRegistry: IValidatorRegistry<Validator>, migrationHandler?: (validator: Validator) => Validator): void;
-    /**
-     * @summary Returns the current ValidatorRegistry
-     *
-     * @return IValidatorRegistry, defaults to {@link ValidatorRegistry}
-     */
-    private static getRegistry;
-    /**
-     * @summary Retrieves a validator
-     *
-     * @param {string} validatorKey one of the {@link ValidationKeys}
-     * @return {Validator | undefined} the registered Validator or undefined if there is nono matching the provided key
-     */
-    static get<T extends Validator>(validatorKey: string): T | undefined;
-    /**
-     * @summary Registers the provided validators onto the registry
-     *
-     * @param {T[] | ValidatorDefinition[]} validator
-     */
-    static register<T extends Validator>(...validator: (ValidatorDefinition | T)[]): void;
-    /**
-     * @summary Builds the key to store as Metadata under Reflections
-     * @description concatenates {@link ValidationKeys#REFLECT} with the provided key
-     *
-     * @param {string} key
-     */
-    static key(key: string): string;
-    /**
-     * @summary Returns all registered validation keys
-     */
-    static keys(): string[];
-    static registerDecorator(key: string, decorator: (...args: any[]) => PropertyDecorator): void;
-    static decoratorFromKey(key: string): any;
-}

package/lib/types/validation/Validators/AsyncValidator.d.ts

@@ -1,72 +0,0 @@
-import type { ValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils";
-import { BaseValidator } from "./BaseValidator";
-/**
- * @description
- * Abstract class for defining asynchronous validators.
- *
- * This class extends the base `Validator` and enforces that any implementation
- * of `hasErrors` must be asynchronous, always returning a Promise.
- *
- * Use this when the validation process involves asynchronous operations,
- * such as API calls, database lookups, or time-based checks (e.g., timeouts).
- *
- * @example
- * ```typescript
- * // Example of an asynchronous validator that compares value against a timeout
- * class TimeoutValidator extends AsyncValidator<{ timeout?: number }> {
- *   constructor(message: string = "Validation failed due to timeout") {
- *     super(message);
- *   }
- *
- *   async hasErrors(value: number, options?: { timeout?: number }) {
- *     const delay = options?.timeout ?? 100;
- *
- *     // async call
- *     await new Promise(res => setTimeout(res, delay));
- *
- *     if (value > delay) {
- *       // Rejects the validation after waiting the delay if value is greater
- *       return Promise.resolve(this.getMessage());
- *     }
- *
- *     // Passes the validation after waiting the delay
- *     return Promise.resolve(undefined);
- *   }
- * }
- *
- * // Example usage:
- * const validator = new TimeoutValidator();
- *
- * async function runValidation() {
- *  const error = await validator.hasErrors(50, { timeout: 100 });
- *  if (error) {
- *    return console.error('Validation error:', error);
- *  }
- *  console.log('Value is valid');
- * }
- *
- * await runValidation();
- * ```
- *
- * - If `value > timeout`, the validator waits for the delay and then rejects with an error.
- * - If `value <= timeout`, the validator waits for the delay and resolves successfully with `undefined`.
- *
- * @see {@link Validator} For the base synchronous validator.
- */
-export declare abstract class AsyncValidator<V extends ValidatorOptions> extends BaseValidator<V, true> {
-    protected constructor(message?: string, ...acceptedTypes: string[]);
-    /**
-     * @description
-     * Asynchronously validates a value.
-     *
-     * @template V - Type of the option object that can be passed to the validator
-     * @param {any} value - The value to validate
-     * @param {V} [options] - Optional configuration options for customizing validation behavior
-     * @param {PathProxy<any>} proxy -
-     * @return Promise<string | undefined> Error message if validation fails, undefined if validation passes
-     *
-     * @see {@link Validator}
-     */
-    abstract hasErrors(value: any, options?: V, proxy?: PathProxy<any>): Promise<string | undefined>;
-}

package/lib/types/validation/Validators/BaseValidator.d.ts

@@ -1,118 +0,0 @@
-import { ValidatorOptions } from "../types";
-import type { PathProxy } from "../../utils";
-import type { ConditionalAsync } from "../../types";
-/**
- * @description Abstract base class for all validators in the validation framework.
- * @summary The BaseValidator class provides the foundation for all synchronous and asynchronous validator implementations.
- * It handles type checking, error message formatting, and defines the interface that all validators must implement.
- * This class is designed to be extended by specific validator classes that define their own validation logic.
- *
- * @template V - Validator options type
- * @template IsAsync - Whether the validator is async (true) or sync (false). Default `false`.
- *
- * @param {boolean} async - Defines if the validator is async (must match the subclass signature)
- * @param {string} message - Default error message to display when validation fails (defaults to {@link DEFAULT_ERROR_MESSAGES#DEFAULT})
- * @param {string[]} acceptedTypes - Type names that this validator accepts (used for runtime type checking)
- *
- * @class BaseValidator
- * @abstract
- *
- * @example
- * // Example of a synchronous validator
- * class SyncValidator extends BaseValidator<SomeOptions, false> {
- *   constructor() {
- *     super(false, "Sync validation failed", String.name);
- *   }
- *
- *   public hasErrors(value: any, options?: SomeOptions): string | undefined {
- *     if (typeof value !== "string") return this.getMessage(this.message);
- *     return undefined;
- *   }
- * }
- *
- * @example
- * // Example of an asynchronous custom validator
- * class AsyncValidator extends BaseValidator<SomeOptions, true> {
- *   constructor() {
- *     super(true, "Async validation failed", String.name);
- *   }
- *
- *   public async hasErrors(value: any, options?: SomeOptions): Promise<string | undefined> {
- *     const result = await someAsyncCheck(value);
- *     if (!result) return this.getMessage(this.message);
- *     return undefined;
- *   }
- * }
- *
- * @mermaid
- * sequenceDiagram
- *   participant C as Client
- *   participant V as Validator Subclass
- *   participant B as BaseValidator
- *
- *   C->>V: new CustomValidator(async, message)
- *   V->>B: super(async, message, acceptedTypes)
- *   B->>B: Store message, async flag, and accepted types
- *   B->>B: Optionally wrap hasErrors with type checking
- *   C->>V: hasErrors(value, options)
- *   alt value type not in acceptedTypes
- *     B-->>C: Type error message
- *   else value type is accepted
- *     V->>V: Custom validation logic
- *     V-->>C: Validation result
- *   end
- *
- * @category Validators
- */
-export declare abstract class BaseValidator<V extends ValidatorOptions = ValidatorOptions, Async extends boolean = false> {
-    readonly message: string;
-    readonly acceptedTypes?: string[];
-    readonly async?: Async;
-    protected constructor(async: Async, message?: string, ...acceptedTypes: string[]);
-    /**
-     * @description Formats an error message with optional arguments
-     * @summary Creates a formatted error message by replacing placeholders with provided arguments.
-     * This method uses the string formatting utility to generate consistent error messages
-     * across all validators.
-     *
-     * @param {string} message - The message template with placeholders
-     * @param {...any} args - Values to insert into the message template
-     * @return {string} The formatted error message
-     * @protected
-     */
-    protected getMessage(message: string, ...args: any[]): string;
-    /**
-     * @description Creates a type-checking wrapper around the hasErrors method
-     * @summary Wraps the hasErrors method with type validation logic to ensure that
-     * the value being validated is of an accepted type before performing specific validation.
-     * This method is called during construction if acceptedTypes are provided.
-     *
-     * @param {Function} unbound - The original hasErrors method to be wrapped
-     * @return {Function} A new function that performs type checking before calling the original method
-     * @private
-     */
-    private checkTypeAndHasErrors;
-    /**
-     * @description Validates a value against specific validation rules
-     * @summary Abstract method that must be implemented by all validator subclasses.
-     * This method contains the core validation logic that determines whether a value
-     * is valid according to the specific rules of the validator. If the value is valid,
-     * the method returns undefined; otherwise, it returns an error message.
-     *
-     * @template V - Type of the options object that can be passed to the validator
-     * @param {any} value - The value to validate
-     * @param {V} [options] - Optional configuration options for customizing validation behavior
-     * @param {PathProxy<any>} proxy -
-     * @return {string | undefined} Error message if validation fails, undefined if validation passes
-     *
-     * @abstract
-     *
-     * @see Model#validate
-     */
-    abstract hasErrors(value: any, options?: V, proxy?: PathProxy<any>): ConditionalAsync<Async, string | undefined>;
-    /**
-     * @summary Duck typing for Validators
-     * @param val
-     */
-    static isValidator(val: any): boolean;
-}