@decaf-ts/decorator-validation 1.15.0 → 1.16.0

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

@@ -0,0 +1,68 @@
+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/registry.d.mts

@@ -0,0 +1,68 @@
+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.cts

@@ -0,0 +1,12 @@
+import { Constructor } from "@decaf-ts/decoration";
+import { Serializer } from "./types.cjs";
+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/serialization.d.mts

@@ -0,0 +1,12 @@
+import { Constructor } from "@decaf-ts/decoration";
+import { Serializer } from "./types.js";
+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.cts

@@ -0,0 +1,41 @@
+import { Serializer } from "./types.cjs";
+import { Model } from "../model/Model.cjs";
+/**
+ * @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/serializers.d.mts

@@ -0,0 +1,41 @@
+import { Serializer } from "./types.js";
+import { Model } from "../model/Model.js";
+/**
+ * @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.cts

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

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

@@ -0,0 +1,35 @@
+import { Model } from "../model/index.cjs";
+/**
+ * @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/utils/types.d.mts

@@ -0,0 +1,35 @@
+import { Model } from "../model/index.js";
+/**
+ * @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.cts

@@ -0,0 +1,53 @@
+import { Validator } from "./Validators/Validator.cjs";
+import { IValidatorRegistry, ValidatorDefinition } from "./types.cjs";
+/**
+ * @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/Validation.d.mts

@@ -0,0 +1,53 @@
+import { Validator } from "./Validators/Validator.js";
+import { IValidatorRegistry, ValidatorDefinition } from "./types.js";
+/**
+ * @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.cts

@@ -0,0 +1,72 @@
+import type { ValidatorOptions } from "../types.cjs";
+import type { PathProxy } from "../../utils/index.cjs";
+import { BaseValidator } from "./BaseValidator.cjs";
+/**
+ * @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/AsyncValidator.d.mts

@@ -0,0 +1,72 @@
+import type { ValidatorOptions } from "../types.js";
+import type { PathProxy } from "../../utils/index.js";
+import { BaseValidator } from "./BaseValidator.js";
+/**
+ * @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>;
+}