@decaf-ts/db-decorators 0.15.0 → 0.17.0

package/lib/types/repository/types.d.ts

@@ -1,62 +0,0 @@
-import { Context } from "./Context";
-import { ExtendedMetadata, Model } from "@decaf-ts/decorator-validation";
-import { OperationKeys } from "../operations";
-import { Constructor } from "@decaf-ts/decoration";
-import { Logger } from "@decaf-ts/logging";
-import { IRepository } from "../interfaces/index";
-/**
- * @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.ts

@@ -1,34 +0,0 @@
-import { IRepository } from "../interfaces/IRepository";
-import { Model, ModelErrorDefinition } from "@decaf-ts/decorator-validation";
-import { Context } from "./Context";
-import { ContextOfRepository } from "./types";
-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.ts

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

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

@@ -1,143 +0,0 @@
-import "./validation";
-import { Model, Serializer } from "@decaf-ts/decorator-validation";
-import { OperationKeys } from "../operations/constants";
-import { IRepository } from "../interfaces/IRepository";
-import { Constructor } from "@decaf-ts/decoration";
-import { ContextOfRepository } from "../repository/index";
-/**
- * @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.ts

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

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

@@ -1,41 +0,0 @@
-import { Validator, ValidatorDefinition, IValidatorRegistry } from "@decaf-ts/decorator-validation";
-declare module "@decaf-ts/decorator-validation" {
-    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;
-        static updateKey(key: string): string;
-    }
-}

package/lib/types/validation/validators/ReadOnlyValidator.d.ts

@@ -1,47 +0,0 @@
-import { Validator } from "@decaf-ts/decorator-validation";
-/**
- * @description A validator that ensures properties marked as readonly cannot be modified during updates.
- * @summary Validator for the {@link readonly} decorator that checks if a value has been changed during an update operation. It compares the new value with the old value and returns an error message if they are not equal.
- * @param {any} value - The value to be validated
- * @param {any} oldValue - The previous value to compare against
- * @param {string} [message] - Optional custom error message
- * @class ReadOnlyValidator
- * @example
- * // Using ReadOnlyValidator with a readonly property
- * class User {
- *   @readonly()
- *   id: string;
- *
- *   name: string;
- *
- *   constructor(id: string, name: string) {
- *     this.id = id;
- *     this.name = name;
- *   }
- * }
- *
- * // This will trigger validation error when trying to update
- * const user = new User('123', 'John');
- * user.id = '456'; // Will be prevented by ReadOnlyValidator
- * @category Validators
- */
-export declare class ReadOnlyValidator extends Validator {
-    constructor();
-    /**
-     * @description Implementation of the base validator's hasErrors method.
-     * @summary This method is required by the Validator interface but not used in this validator as validation only happens during updates.
-     * @param {any} value - The value to validate
-     * @param {any[]} args - Additional arguments
-     * @return {string | undefined} Always returns undefined as this validator only works during updates
-     */
-    hasErrors(value: any, ...args: any[]): string | undefined;
-    /**
-     * @description Checks if a value has been modified during an update operation.
-     * @summary Validates a value has not changed by comparing it with the previous value using deep equality.
-     * @param {any} value - The new value to validate
-     * @param {any} oldValue - The original value to compare against
-     * @param {string} [message] - Optional custom error message to override the default
-     * @return {string | undefined} An error message if validation fails, undefined otherwise
-     */
-    updateHasErrors(value: any, oldValue: any, message?: string): string | undefined;
-}

package/lib/types/validation/validators/TimestampValidator.d.ts

@@ -1,48 +0,0 @@
-import { Validator } from "@decaf-ts/decorator-validation";
-/**
- * @description A validator that ensures timestamp values are only updated with newer timestamps.
- * @summary Validates the update of a timestamp by comparing the new timestamp with the old one, ensuring the new timestamp is more recent.
- * @param {Date|string|number} value - The timestamp value to validate
- * @param {Date|string|number} oldValue - The previous timestamp to compare against
- * @param {string} [message] - Optional custom error message
- * @class TimestampValidator
- * @example
- * // Using TimestampValidator with a timestamp property
- * class Document {
- *   @timestamp()
- *   updatedAt: Date;
- *
- *   title: string;
- *
- *   constructor(title: string) {
- *     this.title = title;
- *     this.updatedAt = new Date();
- *   }
- * }
- *
- * // This will trigger validation error when trying to update with an older timestamp
- * const doc = new Document('My Document');
- * const oldDate = new Date(2020, 0, 1);
- * doc.updatedAt = oldDate; // Will be prevented by TimestampValidator
- * @category Validators
- */
-export declare class TimestampValidator extends Validator {
-    constructor();
-    /**
-     * @description Implementation of the base validator's hasErrors method.
-     * @summary This method is required by the Validator interface but not used in this validator as validation only happens during updates.
-     * @param {any} value - The timestamp value to validate
-     * @param {any[]} args - Additional arguments
-     * @return {string | undefined} Always returns undefined as this validator only works during updates
-     */
-    hasErrors(value: any, ...args: any[]): string | undefined;
-    /**
-     * @description Validates that a timestamp is newer than its previous value.
-     * @summary Checks if a timestamp has been updated with a more recent value by converting both values to Date objects and comparing them.
-     * @param {Date|string|number} value - The new timestamp value to validate
-     * @param {Date|string|number} oldValue - The original timestamp to compare against
-     * @param {string} [message] - Optional custom error message to override the default
-     * @return {string | undefined} An error message if validation fails (new timestamp is not newer), undefined otherwise
-     */
-    updateHasErrors(value: Date | string | number, oldValue: Date | string | number, message?: string): string | undefined;
-}

package/lib/types/validation/validators/UpdateValidator.d.ts

@@ -1,40 +0,0 @@
-import { Validator } from "@decaf-ts/decorator-validation";
-/**
- * @description Abstract base class for validators that compare new values with old values during updates.
- * @summary Base class for an Update validator that provides a framework for implementing validation logic that compares a new value with its previous state.
- * @param {string} [message] - Error message. Defaults to {@link DecoratorMessages#DEFAULT}
- * @param {string[]} [acceptedTypes] - The accepted value types by the decorator
- * @class UpdateValidator
- * @example
- * // Extending UpdateValidator to create a custom validator
- * class MyCustomValidator extends UpdateValidator {
- *   constructor() {
- *     super("Custom validation failed");
- *   }
- *
- *   public updateHasErrors(value: any, oldValue: any): string | undefined {
- *     // Custom validation logic
- *     if (value === oldValue) {
- *       return this.message;
- *     }
- *     return undefined;
- *   }
- *
- *   hasErrors(value: any): string | undefined {
- *     return undefined; // Not used for update validators
- *   }
- * }
- * @category Validators
- */
-export declare abstract class UpdateValidator extends Validator {
-    protected constructor(message?: string, ...acceptedTypes: string[]);
-    /**
-     * @description Abstract method that must be implemented by subclasses to perform update validation.
-     * @summary Validates a value by comparing it to its old version to determine if the update is valid.
-     * @param {any} value - The new value to validate
-     * @param {any} oldValue - The previous value to compare against
-     * @param {any[]} args - Additional arguments that may be needed for validation
-     * @return {string | undefined} An error message if validation fails, undefined if validation passes
-     */
-    abstract updateHasErrors(value: any, oldValue: any, ...args: any[]): string | undefined;
-}

package/lib/types/validation/validators/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./ReadOnlyValidator";
-export * from "./TimestampValidator";
-export * from "./UpdateValidator";