@decaf-ts/decorator-validation 1.15.0 → 1.17.0

package/lib/types/utils/PathProxy.d.cts

@@ -0,0 +1,43 @@
+/**
+ * Proxy object that provides path-based access to nested properties
+ * @template T - The type of the target object being proxied
+ */
+export type PathProxy<T> = T & {
+    getValueFromPath: (path: string, fallback?: any) => any;
+};
+/**
+ * Standard path resolution utility for accessing nested object properties.
+ * Provides consistent dot-notation access to both parent and child properties
+ * across complex object structures.
+ *
+ * - Dot-notation path resolution ('object.child.property')
+ * - Parent traversal using '../' notation
+ * - Configurable property access behavior
+ * - Null/undefined safety checks
+ */
+export declare class PathProxyEngine {
+    /**
+     * Creates a path-aware proxy for the target object
+     * @template T - The type of the target object
+     * @param {T} rootTarget - The target object to proxy
+     * @param opts - Configuration options
+     * @param opts.getValue - Custom function to get property value
+     * @param opts.getParent - Custom function to get parent object
+     * @param opts.ignoreUndefined - Whether to ignore undefined values in paths
+     * @param opts.ignoreNull - Whether to ignore null values in paths
+     * @returns A proxy object with path access capabilities
+     */
+    static create<T extends object>(rootTarget: T, opts?: {
+        getValue?: (target: T, prop: string) => any;
+        getParent?: (target: T) => any;
+        ignoreUndefined: boolean;
+        ignoreNull: boolean;
+    }): PathProxy<T>;
+    /**
+     * Parses a path string into individual components
+     * @param path - The path string to parse (e.g., "user.address.city")
+     * @returns An array of path components
+     * @throws Error if the path is invalid
+     */
+    private static parsePath;
+}

package/lib/types/utils/PathProxy.d.mts

@@ -0,0 +1,43 @@
+/**
+ * Proxy object that provides path-based access to nested properties
+ * @template T - The type of the target object being proxied
+ */
+export type PathProxy<T> = T & {
+    getValueFromPath: (path: string, fallback?: any) => any;
+};
+/**
+ * Standard path resolution utility for accessing nested object properties.
+ * Provides consistent dot-notation access to both parent and child properties
+ * across complex object structures.
+ *
+ * - Dot-notation path resolution ('object.child.property')
+ * - Parent traversal using '../' notation
+ * - Configurable property access behavior
+ * - Null/undefined safety checks
+ */
+export declare class PathProxyEngine {
+    /**
+     * Creates a path-aware proxy for the target object
+     * @template T - The type of the target object
+     * @param {T} rootTarget - The target object to proxy
+     * @param opts - Configuration options
+     * @param opts.getValue - Custom function to get property value
+     * @param opts.getParent - Custom function to get parent object
+     * @param opts.ignoreUndefined - Whether to ignore undefined values in paths
+     * @param opts.ignoreNull - Whether to ignore null values in paths
+     * @returns A proxy object with path access capabilities
+     */
+    static create<T extends object>(rootTarget: T, opts?: {
+        getValue?: (target: T, prop: string) => any;
+        getParent?: (target: T) => any;
+        ignoreUndefined: boolean;
+        ignoreNull: boolean;
+    }): PathProxy<T>;
+    /**
+     * Parses a path string into individual components
+     * @param path - The path string to parse (e.g., "user.address.city")
+     * @returns An array of path components
+     * @throws Error if the path is invalid
+     */
+    private static parsePath;
+}

package/lib/types/utils/constants.d.cts

@@ -0,0 +1,32 @@
+/**
+ * @description Enum containing metadata keys used for reflection in the model system
+ * @summary Defines the various Model keys used for reflection and metadata storage.
+ * These keys are used throughout the library to store and retrieve metadata about models,
+ * their properties, and their behavior.
+ *
+ * @property {string} TYPE - Key for storing design type information
+ * @property {string} MODEL - Key for identifying model metadata
+ * @property {string} ANCHOR - Anchor key that serves as a ghost property in the model
+ * @property {string} CONSTRUCTION - Key for storing construction information
+ * @property {string} ATTRIBUTE - Key for storing attribute metadata
+ * @property {string} HASHING - Key for storing hashing configuration
+ * @property {string} SERIALIZATION - Key for storing serialization configuration
+ *
+ * @enum {string}
+ * @readonly
+ * @memberOf module:decorator-validation
+ * @category Model
+ */
+export declare enum ModelKeys {
+    DESCRIPTION = "description",
+    TYPE = "design:type",
+    MODEL = "model",
+    ANCHOR = "__model",
+    CONSTRUCTION = "constructed-by",
+    ATTRIBUTE = "__attributes",
+    HASHING = "hashing",
+    SERIALIZATION = "serialization",
+    DECORATORS = "decorators",
+    CONSTRUCTOR = "__original"
+}
+export declare const DefaultSerializationMethod = "json";

package/lib/types/utils/constants.d.mts

@@ -0,0 +1,32 @@
+/**
+ * @description Enum containing metadata keys used for reflection in the model system
+ * @summary Defines the various Model keys used for reflection and metadata storage.
+ * These keys are used throughout the library to store and retrieve metadata about models,
+ * their properties, and their behavior.
+ *
+ * @property {string} TYPE - Key for storing design type information
+ * @property {string} MODEL - Key for identifying model metadata
+ * @property {string} ANCHOR - Anchor key that serves as a ghost property in the model
+ * @property {string} CONSTRUCTION - Key for storing construction information
+ * @property {string} ATTRIBUTE - Key for storing attribute metadata
+ * @property {string} HASHING - Key for storing hashing configuration
+ * @property {string} SERIALIZATION - Key for storing serialization configuration
+ *
+ * @enum {string}
+ * @readonly
+ * @memberOf module:decorator-validation
+ * @category Model
+ */
+export declare enum ModelKeys {
+    DESCRIPTION = "description",
+    TYPE = "design:type",
+    MODEL = "model",
+    ANCHOR = "__model",
+    CONSTRUCTION = "constructed-by",
+    ATTRIBUTE = "__attributes",
+    HASHING = "hashing",
+    SERIALIZATION = "serialization",
+    DECORATORS = "decorators",
+    CONSTRUCTOR = "__original"
+}
+export declare const DefaultSerializationMethod = "json";

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

@@ -0,0 +1,86 @@
+/**
+ * @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/dates.d.mts

@@ -0,0 +1,86 @@
+/**
+ * @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.cts

@@ -0,0 +1,56 @@
+/**
+ * @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/equality.d.mts

@@ -0,0 +1,56 @@
+/**
+ * @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.cts

@@ -0,0 +1,82 @@
+/**
+ * @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/hashing.d.mts

@@ -0,0 +1,82 @@
+/**
+ * @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.cts

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

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

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