@decaf-ts/db-decorators 0.11.0 → 0.13.0

package/lib/types/repository/types.d.cts

@@ -0,0 +1,62 @@
+import { Context } from "./Context.cjs";
+import { ExtendedMetadata, Model } from "@decaf-ts/decorator-validation";
+import { OperationKeys } from "../operations/index.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+import { Logger } from "@decaf-ts/logging";
+import { IRepository } from "../interfaces/index.cjs";
+/**
+ * @description Type utility for ensuring model extension.
+ * @summary A conditional type that ensures a type extends the Model class.
+ * If the type extends Model, it returns the type; otherwise, it returns never.
+ * @template M - The type to check, defaults to Model
+ * @typedef {M extends Model ? M : never} ModelExtension
+ * @memberOf module:db-decorators
+ */
+export type ModelExtension<M extends Model = Model> = M extends Model ? M : never;
+export type ContextFlags<LOG extends Logger> = {
+    logger: LOG;
+    timestamp: Date;
+};
+/**
+ * @description Configuration flags for repository operations.
+ * @summary Defines the configuration options that control repository behavior during operations.
+ * These flags manage context relationships, validation behavior, operation metadata, and error handling.
+ * @interface RepositoryFlags
+ * @property {Context} [parentContext] - The parent context for hierarchical operations
+ * @property {Context[]} [childContexts] - Child contexts spawned from this context
+ * @property {any[]} [callArgs] - Arguments passed to the operation
+ * @property {string[]} ignoredValidationProperties - Properties to exclude from validation
+ * @property affectedTables - Tables or models affected by the operation
+ * @property {boolean} writeOperation - Whether the operation modifies data
+ * @property {Date} timestamp - When the operation was initiated
+ * @property {OperationKeys} [operation] - The type of operation being performed
+ * @property {boolean} breakOnHandlerError - Whether to stop processing on handler errors
+ * @property {boolean} rebuildWithTransient - Whether to include transient properties when rebuilding models
+ * @memberOf module:db-decorators
+ */
+export interface RepositoryFlags<LOG extends Logger = Logger> extends ContextFlags<LOG> {
+    parentContext?: Context<any>;
+    childContexts?: Context<any>[];
+    callArgs?: any[];
+    ignoredValidationProperties: string[];
+    affectedTables: (string | Constructor<ModelExtension>)[] | string | Constructor<ModelExtension>;
+    writeOperation: boolean;
+    operation?: OperationKeys;
+    breakOnHandlerError: boolean;
+    rebuildWithTransient: boolean;
+    ignoreValidation: boolean;
+    ignoreHandlers: boolean | string | RegExp;
+    ignoreDevSafeGuards: boolean;
+    mergeForUpdate: boolean;
+    applyUpdateValidation: boolean;
+    correlationId?: string;
+    allowGenerationOverride: boolean;
+}
+export type LoggerOfFlags<R extends ContextFlags<any>> = R extends ContextFlags<infer L> ? L : never;
+export type FlagsOfContext<C extends Context<any>> = C extends Context<infer F> ? F : never;
+export type LoggerOfContext<C extends Context<any>> = LoggerOfFlags<FlagsOfContext<C>>;
+export type ContextOfRepository<R extends IRepository<any, any>> = R extends IRepository<any, infer C> ? C : never;
+export type LoggerOfRepository<R extends IRepository<any, any>> = LoggerOfContext<ContextOfRepository<R>>;
+export type FlagsOfRepository<R extends IRepository<any, any>> = R extends IRepository<any, infer C> ? FlagsOfContext<C> : never;
+export type PrimaryKeyType = string | number | bigint;
+export type InferredPrimaryKeyType<M extends Model> = ExtendedMetadata<M>;

package/lib/types/repository/types.d.mts

@@ -0,0 +1,62 @@
+import { Context } from "./Context.js";
+import { ExtendedMetadata, Model } from "@decaf-ts/decorator-validation";
+import { OperationKeys } from "../operations/index.js";
+import { Constructor } from "@decaf-ts/decoration";
+import { Logger } from "@decaf-ts/logging";
+import { IRepository } from "../interfaces/index.js";
+/**
+ * @description Type utility for ensuring model extension.
+ * @summary A conditional type that ensures a type extends the Model class.
+ * If the type extends Model, it returns the type; otherwise, it returns never.
+ * @template M - The type to check, defaults to Model
+ * @typedef {M extends Model ? M : never} ModelExtension
+ * @memberOf module:db-decorators
+ */
+export type ModelExtension<M extends Model = Model> = M extends Model ? M : never;
+export type ContextFlags<LOG extends Logger> = {
+    logger: LOG;
+    timestamp: Date;
+};
+/**
+ * @description Configuration flags for repository operations.
+ * @summary Defines the configuration options that control repository behavior during operations.
+ * These flags manage context relationships, validation behavior, operation metadata, and error handling.
+ * @interface RepositoryFlags
+ * @property {Context} [parentContext] - The parent context for hierarchical operations
+ * @property {Context[]} [childContexts] - Child contexts spawned from this context
+ * @property {any[]} [callArgs] - Arguments passed to the operation
+ * @property {string[]} ignoredValidationProperties - Properties to exclude from validation
+ * @property affectedTables - Tables or models affected by the operation
+ * @property {boolean} writeOperation - Whether the operation modifies data
+ * @property {Date} timestamp - When the operation was initiated
+ * @property {OperationKeys} [operation] - The type of operation being performed
+ * @property {boolean} breakOnHandlerError - Whether to stop processing on handler errors
+ * @property {boolean} rebuildWithTransient - Whether to include transient properties when rebuilding models
+ * @memberOf module:db-decorators
+ */
+export interface RepositoryFlags<LOG extends Logger = Logger> extends ContextFlags<LOG> {
+    parentContext?: Context<any>;
+    childContexts?: Context<any>[];
+    callArgs?: any[];
+    ignoredValidationProperties: string[];
+    affectedTables: (string | Constructor<ModelExtension>)[] | string | Constructor<ModelExtension>;
+    writeOperation: boolean;
+    operation?: OperationKeys;
+    breakOnHandlerError: boolean;
+    rebuildWithTransient: boolean;
+    ignoreValidation: boolean;
+    ignoreHandlers: boolean | string | RegExp;
+    ignoreDevSafeGuards: boolean;
+    mergeForUpdate: boolean;
+    applyUpdateValidation: boolean;
+    correlationId?: string;
+    allowGenerationOverride: boolean;
+}
+export type LoggerOfFlags<R extends ContextFlags<any>> = R extends ContextFlags<infer L> ? L : never;
+export type FlagsOfContext<C extends Context<any>> = C extends Context<infer F> ? F : never;
+export type LoggerOfContext<C extends Context<any>> = LoggerOfFlags<FlagsOfContext<C>>;
+export type ContextOfRepository<R extends IRepository<any, any>> = R extends IRepository<any, infer C> ? C : never;
+export type LoggerOfRepository<R extends IRepository<any, any>> = LoggerOfContext<ContextOfRepository<R>>;
+export type FlagsOfRepository<R extends IRepository<any, any>> = R extends IRepository<any, infer C> ? FlagsOfContext<C> : never;
+export type PrimaryKeyType = string | number | bigint;
+export type InferredPrimaryKeyType<M extends Model> = ExtendedMetadata<M>;

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

@@ -0,0 +1,34 @@
+import { IRepository } from "../interfaces/IRepository.cjs";
+import { Model, ModelErrorDefinition } from "@decaf-ts/decorator-validation";
+import { Context } from "./Context.cjs";
+import { ContextOfRepository } from "./types.cjs";
+export type ContextArgs<C extends Context<any>> = {
+    context: C;
+    args: [...any[], C];
+};
+export declare function reduceErrorsToPrint(errors: (ModelErrorDefinition | undefined)[]): string | undefined;
+/**
+ *
+ * @param {IRepository<T>} repo
+ * @param context
+ * @param {T} model
+ * @param operation
+ * @param prefix
+ *
+ * @param oldModel
+ * @function enforceDBPropertyDecoratorsAsync
+ *
+ * @memberOf db-decorators.utils
+ */
+export declare function enforceDBDecorators<M extends Model<true | false>, R extends IRepository<M, any>, V extends object = object>(repo: R, context: ContextOfRepository<R>, model: M, operation: string, prefix: string, oldModel?: M): Promise<void>;
+/**
+ * Specific for DB Decorators
+ * @param {T} model
+ * @param {string} operation CRUD {@link OperationKeys}
+ * @param {string} [extraPrefix]
+ *
+ * @function getDbPropertyDecorators
+ *
+ * @memberOf db-decorators.utils
+ */
+export declare function getDbDecorators<T extends Model>(model: T, operation: string, extraPrefix?: string): Record<string, DecoratorMetadata[]> | undefined;

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

@@ -0,0 +1,34 @@
+import { IRepository } from "../interfaces/IRepository.js";
+import { Model, ModelErrorDefinition } from "@decaf-ts/decorator-validation";
+import { Context } from "./Context.js";
+import { ContextOfRepository } from "./types.js";
+export type ContextArgs<C extends Context<any>> = {
+    context: C;
+    args: [...any[], C];
+};
+export declare function reduceErrorsToPrint(errors: (ModelErrorDefinition | undefined)[]): string | undefined;
+/**
+ *
+ * @param {IRepository<T>} repo
+ * @param context
+ * @param {T} model
+ * @param operation
+ * @param prefix
+ *
+ * @param oldModel
+ * @function enforceDBPropertyDecoratorsAsync
+ *
+ * @memberOf db-decorators.utils
+ */
+export declare function enforceDBDecorators<M extends Model<true | false>, R extends IRepository<M, any>, V extends object = object>(repo: R, context: ContextOfRepository<R>, model: M, operation: string, prefix: string, oldModel?: M): Promise<void>;
+/**
+ * Specific for DB Decorators
+ * @param {T} model
+ * @param {string} operation CRUD {@link OperationKeys}
+ * @param {string} [extraPrefix]
+ *
+ * @function getDbPropertyDecorators
+ *
+ * @memberOf db-decorators.utils
+ */
+export declare function getDbDecorators<T extends Model>(model: T, operation: string, extraPrefix?: string): Record<string, DecoratorMetadata[]> | undefined;

package/lib/types/repository/wrappers.d.cts

@@ -0,0 +1,39 @@
+/**
+ * @summary Util method to change a method of an object prefixing it with another
+ * @param {any} obj The Base Object
+ * @param {Function} after The original method
+ * @param {Function} prefix The Prefix method. The output will be used as arguments in the original method
+ * @param {string} [afterName] When the after function anme cannot be extracted, pass it here
+ *
+ * @function prefixMethod
+ *
+ * @memberOf module:db-decorators
+ */
+export declare function prefixMethod(obj: any, after: (...args: any[]) => any, prefix: (...args: any[]) => any, afterName?: string): void;
+/**
+ * @summary Util method to change a method of an object suffixing it with another
+ * @param {any} obj The Base Object
+ * @param {Function} before The original method
+ * @param {Function} suffix The Prefix method. The output will be used as arguments in the original method
+ * @param {string} [beforeName] When the after function anme cannot be extracted, pass it here
+ *
+ * @function suffixMethod
+ *
+ * @memberOf module:db-decorators.Repository
+ */
+export declare function suffixMethod(obj: any, before: (...args: any[]) => any, suffix: (...args: any[]) => any, beforeName?: string): void;
+/**
+ * @summary Util method to wrap a method of an object with additional logic
+ *
+ * @param {any} obj The Base Object
+ * @param {Function} before the method to be prefixed
+ * @param {Function} method the method to be wrapped
+ * @param {Function} after The method to be suffixed
+ * @param {string} [methodName] When the after function anme cannot be extracted, pass it here
+ *
+ * @function wrapMethodWithContext
+ *
+ * @memberOf module:db-decorators
+ */
+export declare function wrapMethodWithContext(obj: any, before: (...args: any[]) => any, method: (...args: any[]) => any, after: (...args: any[]) => any, methodName?: string): void;
+export declare function wrapMethodWithContextForUpdate(obj: any, before: (...args: any[]) => any, method: (...args: any[]) => any, after: (...args: any[]) => any, methodName?: string): void;

package/lib/types/repository/wrappers.d.mts

@@ -0,0 +1,39 @@
+/**
+ * @summary Util method to change a method of an object prefixing it with another
+ * @param {any} obj The Base Object
+ * @param {Function} after The original method
+ * @param {Function} prefix The Prefix method. The output will be used as arguments in the original method
+ * @param {string} [afterName] When the after function anme cannot be extracted, pass it here
+ *
+ * @function prefixMethod
+ *
+ * @memberOf module:db-decorators
+ */
+export declare function prefixMethod(obj: any, after: (...args: any[]) => any, prefix: (...args: any[]) => any, afterName?: string): void;
+/**
+ * @summary Util method to change a method of an object suffixing it with another
+ * @param {any} obj The Base Object
+ * @param {Function} before The original method
+ * @param {Function} suffix The Prefix method. The output will be used as arguments in the original method
+ * @param {string} [beforeName] When the after function anme cannot be extracted, pass it here
+ *
+ * @function suffixMethod
+ *
+ * @memberOf module:db-decorators.Repository
+ */
+export declare function suffixMethod(obj: any, before: (...args: any[]) => any, suffix: (...args: any[]) => any, beforeName?: string): void;
+/**
+ * @summary Util method to wrap a method of an object with additional logic
+ *
+ * @param {any} obj The Base Object
+ * @param {Function} before the method to be prefixed
+ * @param {Function} method the method to be wrapped
+ * @param {Function} after The method to be suffixed
+ * @param {string} [methodName] When the after function anme cannot be extracted, pass it here
+ *
+ * @function wrapMethodWithContext
+ *
+ * @memberOf module:db-decorators
+ */
+export declare function wrapMethodWithContext(obj: any, before: (...args: any[]) => any, method: (...args: any[]) => any, after: (...args: any[]) => any, methodName?: string): void;
+export declare function wrapMethodWithContextForUpdate(obj: any, before: (...args: any[]) => any, method: (...args: any[]) => any, after: (...args: any[]) => any, methodName?: string): void;

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

@@ -0,0 +1,45 @@
+/**
+ * @description Collection of default error messages used by validators.
+ * @summary Holds the default error messages for various validation scenarios including ID validation, readonly properties, and timestamps.
+ * @typedef {Object} ErrorMessages
+ * @property {Object} ID - Error messages for ID validation
+ * @property {string} ID.INVALID - Error message when an ID is invalid
+ * @property {string} ID.REQUIRED - Error message when an ID is missing
+ * @property {Object} READONLY - Error messages for readonly properties
+ * @property {string} READONLY.INVALID - Error message when attempting to update a readonly property
+ * @property {Object} TIMESTAMP - Error messages for timestamp validation
+ * @property {string} TIMESTAMP.REQUIRED - Error message when a timestamp is missing
+ * @property {string} TIMESTAMP.DATE - Error message when a timestamp is not a valid date
+ * @property {string} TIMESTAMP.INVALID - Error message when a timestamp is not increasing
+ * @const DEFAULT_ERROR_MESSAGES
+ * @memberOf module:validation
+ */
+export declare const DEFAULT_ERROR_MESSAGES: {
+    ID: {
+        INVALID: string;
+        REQUIRED: string;
+    };
+    READONLY: {
+        INVALID: string;
+    };
+    TIMESTAMP: {
+        REQUIRED: string;
+        DATE: string;
+        INVALID: string;
+    };
+};
+/**
+ * @description Constants used for reflection-based validation during update operations.
+ * @summary Keys used for storing and retrieving validation metadata on model properties during update operations.
+ * @typedef {Object} ValidationKeys
+ * @property {string} REFLECT - Base reflection key prefix for update validation
+ * @property {string} TIMESTAMP - Key for timestamp validation
+ * @property {string} READONLY - Key for readonly property validation
+ * @const UpdateValidationKeys
+ * @memberOf module:validation
+ */
+export declare const UpdateValidationKeys: {
+    REFLECT: string;
+    TIMESTAMP: string;
+    READONLY: string;
+};

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

@@ -0,0 +1,45 @@
+/**
+ * @description Collection of default error messages used by validators.
+ * @summary Holds the default error messages for various validation scenarios including ID validation, readonly properties, and timestamps.
+ * @typedef {Object} ErrorMessages
+ * @property {Object} ID - Error messages for ID validation
+ * @property {string} ID.INVALID - Error message when an ID is invalid
+ * @property {string} ID.REQUIRED - Error message when an ID is missing
+ * @property {Object} READONLY - Error messages for readonly properties
+ * @property {string} READONLY.INVALID - Error message when attempting to update a readonly property
+ * @property {Object} TIMESTAMP - Error messages for timestamp validation
+ * @property {string} TIMESTAMP.REQUIRED - Error message when a timestamp is missing
+ * @property {string} TIMESTAMP.DATE - Error message when a timestamp is not a valid date
+ * @property {string} TIMESTAMP.INVALID - Error message when a timestamp is not increasing
+ * @const DEFAULT_ERROR_MESSAGES
+ * @memberOf module:validation
+ */
+export declare const DEFAULT_ERROR_MESSAGES: {
+    ID: {
+        INVALID: string;
+        REQUIRED: string;
+    };
+    READONLY: {
+        INVALID: string;
+    };
+    TIMESTAMP: {
+        REQUIRED: string;
+        DATE: string;
+        INVALID: string;
+    };
+};
+/**
+ * @description Constants used for reflection-based validation during update operations.
+ * @summary Keys used for storing and retrieving validation metadata on model properties during update operations.
+ * @typedef {Object} ValidationKeys
+ * @property {string} REFLECT - Base reflection key prefix for update validation
+ * @property {string} TIMESTAMP - Key for timestamp validation
+ * @property {string} READONLY - Key for readonly property validation
+ * @const UpdateValidationKeys
+ * @memberOf module:validation
+ */
+export declare const UpdateValidationKeys: {
+    REFLECT: string;
+    TIMESTAMP: string;
+    READONLY: string;
+};

package/lib/types/validation/decorators.d.cts

@@ -0,0 +1,143 @@
+import "./validation";
+import { Model, Serializer } from "@decaf-ts/decorator-validation";
+import { OperationKeys } from "../operations/constants.cjs";
+import { IRepository } from "../interfaces/IRepository.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+import { ContextOfRepository } from "../repository/index.cjs";
+/**
+ * @description Prevents a property from being modified after initial creation.
+ * @summary Marks the property as readonly, causing validation errors if attempts are made to modify it during updates.
+ * @param {string} [message] - The error message to display when validation fails. Defaults to {@link DEFAULT_ERROR_MESSAGES.READONLY.INVALID}
+ * @return {PropertyDecorator} A decorator function that can be applied to class properties
+ * @function readonly
+ * @category Property Decorators
+ */
+export declare function readonly(message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
+/**
+ * @description Handler function that sets a timestamp property to the current timestamp.
+ * @summary Updates a model property with the current timestamp from the repository context.
+ * @template M - The model type extending Model
+ * @template R - The repository type extending IRepository
+ * @template V - The data type for the operation
+ * @template F - The repository flags type
+ * @template C - The context type
+ * @param {C} context - The repository context containing the current timestamp
+ * @param {V} data - The data being processed
+ * @param key - The property key to update
+ * @param {M} model - The model instance being updated
+ * @return {Promise<void>} A promise that resolves when the timestamp has been set
+ * @function timestampHandler
+ */
+export declare function timestampHandler<M extends Model, R extends IRepository<M, any>, V>(this: R, context: ContextOfRepository<R>, data: V, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Automatically manages timestamp properties for tracking creation and update times.
+ * @summary Marks the property as a timestamp, making it required and ensuring it's a valid date. The property will be automatically updated with the current timestamp during specified operations.
+ *
+ * Date Format:
+ *
+ * <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 {OperationKeys[]} operation - The operations to act on. Defaults to {@link DBOperations.CREATE_UPDATE}
+ * @param {string} [format] - The timestamp format. Defaults to {@link DEFAULT_TIMESTAMP_FORMAT}
+ * @return {PropertyDecorator} A decorator function that can be applied to class properties
+ * @function timestamp
+ * @category Property Decorators
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant M as Model
+ *   participant T as TimestampDecorator
+ *   participant V as Validator
+ *
+ *   C->>M: Create/Update model
+ *   M->>T: Process timestamp property
+ *   T->>M: Apply required validation
+ *   T->>M: Apply date format validation
+ *
+ *   alt Update operation
+ *     T->>V: Register timestamp validator
+ *     V->>M: Validate timestamp is newer
+ *   end
+ *
+ *   T->>M: Set current timestamp
+ *   M->>C: Return updated model
+ */
+export declare function timestamp(operation?: OperationKeys[], format?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
+/**
+ * @description Handler function that serializes a property to JSON string during create and update operations.
+ * @summary Converts a complex object property to a JSON string before storing it in the database.
+ * @template M - The model type extending Model
+ * @template R - The repository type extending IRepository
+ * @template V - The data type for the operation
+ * @template F - The repository flags type
+ * @template C - The context type
+ * @param {C} context - The repository context
+ * @param {V} data - The data being processed
+ * @param key - The property key to serialize
+ * @param {M} model - The model instance being processed
+ * @return {Promise<void>} A promise that resolves when the property has been serialized
+ * @function serializeOnCreateUpdate
+ */
+export declare function serializeOnCreateUpdate<M extends Model, R extends IRepository<M, any>>(this: R, context: ContextOfRepository<R>, data: {
+    serializer?: Constructor<Serializer<M>>;
+}, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Handler function that deserializes a property from JSON string after database operations.
+ * @summary Converts a JSON string property back to its original complex object form after retrieving it from the database.
+ * @template M - The model type extending Model
+ * @template R - The repository type extending IRepository
+ * @template V - The data type for the operation
+ * @template F - The repository flags type
+ * @template C - The context type
+ * @param {C} context - The repository context
+ * @param {V} data - The data being processed
+ * @param key - The property key to deserialize
+ * @param {M} model - The model instance being processed
+ * @return {Promise<void>} A promise that resolves when the property has been deserialized
+ * @function serializeAfterAll
+ */
+export declare function serializeAfterAll<M extends Model, R extends IRepository<M, any>>(this: R, context: ContextOfRepository<R>, data: {
+    serializer?: Constructor<Serializer<M>>;
+}, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Enables automatic JSON serialization and deserialization for complex object properties.
+ * @summary Decorator that automatically converts complex objects to JSON strings before storing in the database and back to objects when retrieving them.
+ * @return {PropertyDecorator} A decorator function that can be applied to class properties
+ * @function serialize
+ * @category Property Decorators
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant M as Model
+ *   participant S as SerializeDecorator
+ *   participant DB as Database
+ *
+ *   Note over C,DB: Create/Update Flow
+ *   C->>M: Set complex object property
+ *   M->>S: Process property (create/update)
+ *   S->>M: Convert to JSON string
+ *   M->>DB: Store serialized data
+ *
+ *   Note over C,DB: Retrieval Flow
+ *   C->>M: Request model
+ *   M->>DB: Fetch data
+ *   DB->>M: Return with serialized property
+ *   M->>S: Process property (after all ops)
+ *   S->>M: Parse JSON back to object
+ *   M->>C: Return model with deserialized property
+ */
+export declare function serialize(serializer?: Constructor<Serializer<any>>): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor | number) => void;

package/lib/types/validation/decorators.d.mts

@@ -0,0 +1,143 @@
+import "./validation";
+import { Model, Serializer } from "@decaf-ts/decorator-validation";
+import { OperationKeys } from "../operations/constants.js";
+import { IRepository } from "../interfaces/IRepository.js";
+import { Constructor } from "@decaf-ts/decoration";
+import { ContextOfRepository } from "../repository/index.js";
+/**
+ * @description Prevents a property from being modified after initial creation.
+ * @summary Marks the property as readonly, causing validation errors if attempts are made to modify it during updates.
+ * @param {string} [message] - The error message to display when validation fails. Defaults to {@link DEFAULT_ERROR_MESSAGES.READONLY.INVALID}
+ * @return {PropertyDecorator} A decorator function that can be applied to class properties
+ * @function readonly
+ * @category Property Decorators
+ */
+export declare function readonly(message?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
+/**
+ * @description Handler function that sets a timestamp property to the current timestamp.
+ * @summary Updates a model property with the current timestamp from the repository context.
+ * @template M - The model type extending Model
+ * @template R - The repository type extending IRepository
+ * @template V - The data type for the operation
+ * @template F - The repository flags type
+ * @template C - The context type
+ * @param {C} context - The repository context containing the current timestamp
+ * @param {V} data - The data being processed
+ * @param key - The property key to update
+ * @param {M} model - The model instance being updated
+ * @return {Promise<void>} A promise that resolves when the timestamp has been set
+ * @function timestampHandler
+ */
+export declare function timestampHandler<M extends Model, R extends IRepository<M, any>, V>(this: R, context: ContextOfRepository<R>, data: V, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Automatically manages timestamp properties for tracking creation and update times.
+ * @summary Marks the property as a timestamp, making it required and ensuring it's a valid date. The property will be automatically updated with the current timestamp during specified operations.
+ *
+ * Date Format:
+ *
+ * <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 {OperationKeys[]} operation - The operations to act on. Defaults to {@link DBOperations.CREATE_UPDATE}
+ * @param {string} [format] - The timestamp format. Defaults to {@link DEFAULT_TIMESTAMP_FORMAT}
+ * @return {PropertyDecorator} A decorator function that can be applied to class properties
+ * @function timestamp
+ * @category Property Decorators
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant M as Model
+ *   participant T as TimestampDecorator
+ *   participant V as Validator
+ *
+ *   C->>M: Create/Update model
+ *   M->>T: Process timestamp property
+ *   T->>M: Apply required validation
+ *   T->>M: Apply date format validation
+ *
+ *   alt Update operation
+ *     T->>V: Register timestamp validator
+ *     V->>M: Validate timestamp is newer
+ *   end
+ *
+ *   T->>M: Set current timestamp
+ *   M->>C: Return updated model
+ */
+export declare function timestamp(operation?: OperationKeys[], format?: string): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
+/**
+ * @description Handler function that serializes a property to JSON string during create and update operations.
+ * @summary Converts a complex object property to a JSON string before storing it in the database.
+ * @template M - The model type extending Model
+ * @template R - The repository type extending IRepository
+ * @template V - The data type for the operation
+ * @template F - The repository flags type
+ * @template C - The context type
+ * @param {C} context - The repository context
+ * @param {V} data - The data being processed
+ * @param key - The property key to serialize
+ * @param {M} model - The model instance being processed
+ * @return {Promise<void>} A promise that resolves when the property has been serialized
+ * @function serializeOnCreateUpdate
+ */
+export declare function serializeOnCreateUpdate<M extends Model, R extends IRepository<M, any>>(this: R, context: ContextOfRepository<R>, data: {
+    serializer?: Constructor<Serializer<M>>;
+}, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Handler function that deserializes a property from JSON string after database operations.
+ * @summary Converts a JSON string property back to its original complex object form after retrieving it from the database.
+ * @template M - The model type extending Model
+ * @template R - The repository type extending IRepository
+ * @template V - The data type for the operation
+ * @template F - The repository flags type
+ * @template C - The context type
+ * @param {C} context - The repository context
+ * @param {V} data - The data being processed
+ * @param key - The property key to deserialize
+ * @param {M} model - The model instance being processed
+ * @return {Promise<void>} A promise that resolves when the property has been deserialized
+ * @function serializeAfterAll
+ */
+export declare function serializeAfterAll<M extends Model, R extends IRepository<M, any>>(this: R, context: ContextOfRepository<R>, data: {
+    serializer?: Constructor<Serializer<M>>;
+}, key: keyof M, model: M): Promise<void>;
+/**
+ * @description Enables automatic JSON serialization and deserialization for complex object properties.
+ * @summary Decorator that automatically converts complex objects to JSON strings before storing in the database and back to objects when retrieving them.
+ * @return {PropertyDecorator} A decorator function that can be applied to class properties
+ * @function serialize
+ * @category Property Decorators
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant M as Model
+ *   participant S as SerializeDecorator
+ *   participant DB as Database
+ *
+ *   Note over C,DB: Create/Update Flow
+ *   C->>M: Set complex object property
+ *   M->>S: Process property (create/update)
+ *   S->>M: Convert to JSON string
+ *   M->>DB: Store serialized data
+ *
+ *   Note over C,DB: Retrieval Flow
+ *   C->>M: Request model
+ *   M->>DB: Fetch data
+ *   DB->>M: Return with serialized property
+ *   M->>S: Process property (after all ops)
+ *   S->>M: Parse JSON back to object
+ *   M->>C: Return model with deserialized property
+ */
+export declare function serialize(serializer?: Constructor<Serializer<any>>): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor | number) => void;

package/lib/types/validation/index.d.cts

@@ -0,0 +1,4 @@
+export * from "./validators/index.cjs";
+export * from "./constants.cjs";
+export * from "./decorators.cjs";
+export * from "./validation.cjs";

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

@@ -0,0 +1,4 @@
+export * from "./validators/index.js";
+export * from "./constants.js";
+export * from "./decorators.js";
+export * from "./validation.js";