@decaf-ts/db-decorators 0.16.0 → 0.17.1

package/lib/types/model/decorators.d.ts

@@ -1,145 +0,0 @@
-import { Model } from "@decaf-ts/decorator-validation";
-import { IRepository } from "../interfaces/IRepository";
-import { CrudOperations, GroupSort } from "../operations";
-import { ContextOfRepository } from "../repository/index";
-export declare function generated(type?: string): (target: object, prop?: any) => void;
-/**
- * @description Hashes a property value during create or update operations
- * @summary Callback function used by the hash decorator to apply hashing to a property value
- * @template M - Type extending Model
- * @template R - Type extending IRepository
- * @template V - Type for metadata
- * @template F - Type extending RepositoryFlags
- * @template C - Type extending Context
- * @param {C} context - The operation context
- * @param {V} data - Metadata for the operation
- * @param key - The property key to hash
- * @param {M} model - The model being processed
- * @param {M} [oldModel] - The previous model state (for updates)
- * @return {void}
- * @function hashOnCreateUpdate
- * @memberOf module:db-decorators
- */
-export declare function hashOnCreateUpdate<M extends Model, R extends IRepository<M, any>, V extends object>(this: R, context: ContextOfRepository<R>, data: V, key: keyof M, model: M, oldModel?: M): void;
-/**
- * @description Creates a decorator that hashes a property value
- * @summary Decorator that automatically hashes a property value during create and update operations
- * @return {PropertyDecorator} A decorator that can be applied to class properties
- * @function hash
- * @category Property Decorators
- */
-export declare function hash(): (target: object, propertyKey?: string | symbol | unknown, descriptor?: PropertyDescriptor | number) => void;
-/**
- * @description Metadata for composed property decorators
- * @summary Configuration options for property composition from other properties
- * @typedef {Object} ComposedFromMetadata
- * @property {string[]} args - Property names to compose from
- * @property {string} separator - Character used to join the composed values
- * @property {boolean} hashResult - Whether to hash the composed result
- * @property {"keys"|"values"} type - Whether to use property keys or values
- * @property {string} [prefix] - Optional prefix to add to the composed value
- * @property {string} [suffix] - Optional suffix to add to the composed value
- * @memberOf module:db-decorators
- */
-export type ComposedFromMetadata = {
-    args: string[];
-    separator: string;
-    hashResult: boolean;
-    type: "keys" | "values";
-    prefix?: string;
-    suffix?: string;
-    filterEmpty: boolean | string[];
-};
-export declare function composeAttributeValue<M extends Model>(model: M, metadata: ComposedFromMetadata): any;
-/**
- * @description Composes a property value from other properties during create or update operations
- * @summary Callback function used by composed decorators to generate a property value from other properties
- * @template M - Type extending Model
- * @template R - Type extending IRepository
- * @template V - Type extending ComposedFromMetadata
- * @template F - Type extending RepositoryFlags
- * @template C - Type extending Context
- * @param {C} context - The operation context
- * @param {V} data - Metadata for the composition
- * @param key - The property key to set the composed value on
- * @param {M} model - The model being processed
- * @return {void}
- * @function composedFromCreateUpdate
- * @memberOf module:db-decorators
- */
-export declare function composedFromCreateUpdate<M extends Model, R extends IRepository<M, any>, V extends ComposedFromMetadata>(this: R, context: ContextOfRepository<R>, data: V, key: keyof M, model: M): void;
-/**
- * @description Creates a decorator that composes a property value from property keys
- * @summary Decorator that generates a property value by joining the names of other properties
- * @param {string[]} args - Property names to compose from
- * @param {string} [separator=DefaultSeparator] - Character used to join the property names
- * @param {boolean} [hash=false] - Whether to hash the composed result
- * @param {string} [prefix=""] - Optional prefix to add to the composed value
- * @param {string} [suffix=""] - Optional suffix to add to the composed value
- * @param {GroupSort} groupsort - GroupSort configuration
- * @return {PropertyDecorator} A decorator that can be applied to class properties
- * @function composedFromKeys
- * @category PropertyDecorators
- */
-export declare function composedFromKeys(args: string[], separator?: string, filterEmpty?: boolean | string[], hash?: boolean, prefix?: string, suffix?: string, groupsort?: GroupSort): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
-/**
- * @description Creates a decorator that composes a property value from property values
- * @summary Decorator that generates a property value by joining the values of other properties
- * @param {string[]} args - Property names whose values will be composed
- * @param {string} [separator=DefaultSeparator] - Character used to join the property values
- * @param {boolean} [hash=false] - Whether to hash the composed result
- * @param {string} [prefix=""] - Optional prefix to add to the composed value
- * @param {string} [suffix=""] - Optional suffix to add to the composed value
- * @param {GroupSort} groupsort - GroupSort configuration
- * @return {PropertyDecorator} A decorator that can be applied to class properties
- * @function composed
- * @category PropertyDecorators
- */
-export declare function composed(args: string[], separator?: string, filterEmpty?: boolean | string[], hash?: boolean, prefix?: string, suffix?: string, groupsort?: GroupSort): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
-/**
- * @description Creates a function that updates a version property during operations
- * @summary Factory function that generates a callback for incrementing version numbers
- * @param {CrudOperations} operation - The type of operation (CREATE or UPDATE)
- * @return {Function} A callback function that updates the version property
- * @template M - Type extending Model
- * @template R - Type extending IRepository
- * @template V - Type for metadata
- * @template F - Type extending RepositoryFlags
- * @template C - Type extending Context
- * @function versionCreateUpdate
- * @memberOf module:db-decorators
- * @mermaid
- * sequenceDiagram
- *   participant Caller
- *   participant versionCreateUpdate
- *
- *   Caller->>versionCreateUpdate: operation
- *   versionCreateUpdate-->>Caller: callback function
- *   Note over Caller,versionCreateUpdate: When callback is executed:
- *   Caller->>versionCreateUpdate: context, data, key, model
- *   alt operation is CREATE
- *     versionCreateUpdate->>versionCreateUpdate: set version to 1
- *   else operation is UPDATE
- *     versionCreateUpdate->>versionCreateUpdate: increment version
- *   else invalid operation
- *     versionCreateUpdate->>versionCreateUpdate: throw error
- *   end
- *   versionCreateUpdate-->>Caller: void
- */
-export declare function versionCreateUpdate(operation: CrudOperations): <M extends Model, R extends IRepository<M>, V extends object>(this: R, context: ContextOfRepository<R>, data: V, key: keyof M, model: M, oldModel?: M) => void;
-/**
- * @description Creates a decorator for versioning a property in a model
- * @summary This decorator applies multiple sub-decorators to handle version management during create and update operations
- * @return {PropertyDecorator} A composite decorator that sets the type to Number, manages version updates, and adds versioning metadata
- * @function version
- * @category PropertyDecorators
- */
-export declare function version(): (target: any, propertyKey?: any) => any;
-/**
- * @description Creates a decorator that marks a property as transient
- * @summary Decorator that indicates a property should not be persisted to the database
- * @return {PropertyDecorator} A decorator that can be applied to class properties
- * @function transient
- * @category PropertyDecorators
- */
-export declare function transient(): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;

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

@@ -1,9 +0,0 @@
-/**
- * @description Exports for the model module.
- * @summary This file exports all the necessary components for the model functionality, including constants, decorators, and the model itself.
- * @module db-decorators/model
- */
-export * from "./constants";
-export * from "./decorators";
-export * from "./model";
-export * from "./validation";

package/lib/types/model/model.d.ts

@@ -1,6 +0,0 @@
-import { ConditionalAsync, ModelErrorDefinition } from "@decaf-ts/decorator-validation";
-declare module "@decaf-ts/decorator-validation" {
-    interface Model<Async extends boolean = false> {
-        hasErrors(previousVersion?: Model | any, ...exclusions: any[]): ConditionalAsync<Async, ModelErrorDefinition | undefined>;
-    }
-}

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

@@ -1,57 +0,0 @@
-import { ConditionalAsync, Model, ModelConditionalAsync } from "@decaf-ts/decorator-validation";
-/**
- * @description
- * Retrieves validation decorator definitions from a model for update operations, including
- * support for special handling of list decorators.
- *
- * @summary
- * Iterates over the model's own enumerable properties and filters out those specified in the
- * `propsToIgnore` array. For each remaining property, retrieves validation decorators specific
- * to update operations using the `UpdateValidationKeys.REFLECT` key. Additionally, it explicitly
- * checks for and appends any `LIST` type decorators to ensure proper validation of collection types.
- *
- * @template M - A generic parameter extending the `Model` class, representing the model type being inspected.
- *
- * @param {M} model - The model instance whose properties are being inspected for update-related validations.
- * @param {string[]} propsToIgnore - A list of property names to exclude from the validation decorator retrieval process.
- *
- * @return {ValidationPropertyDecoratorDefinition[]} An array of validation decorator definitions, including both
- * update-specific and list-type decorators, excluding those for ignored properties.
- *
- * @function getValidatableUpdateProps
- */
-export declare function getValidatableUpdateProps<M extends Model>(model: M, propsToIgnore: string[]): any[];
-export declare function validateDecorator<M extends Model, Async extends boolean = false>(newModel: M, oldModel: M, prop: string, decorator: any, async?: Async): ConditionalAsync<Async, string | undefined>;
-export declare function validateDecorators<M extends Model, Async extends boolean = false>(newModel: M, oldModel: M, prop: string, decorators: any, async?: Async): ConditionalAsync<Async, Record<string, string>> | undefined;
-/**
- * @description Validates changes between two model versions
- * @summary Compares an old and new model version to validate update operations
- * @template M - Type extending Model
- * @param {M} oldModel - The original model version
- * @param {M} newModel - The updated model version
- * @param {boolean} async - A flag indicating whether validation should be asynchronous.
- * @param {...string[]} propsToIgnore - Properties to exclude from validation
- * @return {ModelErrorDefinition|undefined} Error definition if validation fails, undefined otherwise
- * @function validateCompare
- * @memberOf module:db-decorators
- * @mermaid
- * sequenceDiagram
- *   participant Caller
- *   participant validateCompare
- *   participant Reflection
- *   participant Validation
- *
- *   Caller->>validateCompare: oldModel, newModel, propsToIgnore
- *   validateCompare->>Reflection: get decorated properties
- *   Reflection-->>validateCompare: property decorators
- *   loop For each decorated property
- *     validateCompare->>Validation: get validator
- *     Validation-->>validateCompare: validator
- *     validateCompare->>validateCompare: validate property update
- *   end
- *   loop For nested models
- *     validateCompare->>validateCompare: validate nested models
- *   end
- *   validateCompare-->>Caller: validation errors or undefined
- */
-export declare function validateCompare<M extends Model<any>>(oldModel: M, newModel: M, async: boolean, ...propsToIgnore: string[]): ModelConditionalAsync<M>;

package/lib/types/operations/Operations.d.ts

@@ -1,80 +0,0 @@
-import { Model } from "@decaf-ts/decorator-validation";
-import { OperationHandler } from "./types";
-import { OperationKeys } from "./constants";
-import { IRepository } from "../interfaces";
-/**
- * @description Static utility class for database operation management
- * @summary Provides functionality for registering, retrieving, and managing database operation handlers
- * @class Operations
- * @template M - Model type
- * @template R - Repository type
- * @template V - Metadata type
- * @example
- * // Register a handler for a create operation
- * Operations.register(myHandler, OperationKeys.CREATE, targetModel, 'propertyName');
- *
- * // Get handlers for a specific operation
- * const handlers = Operations.get(targetModel.constructor.name, 'propertyName', 'onCreate');
- *
- * @mermaid
- * classDiagram
- *   class Operations {
- *     -registry: OperationsRegistry
- *     +getHandlerName(handler)
- *     +key(str)
- *     +get(targetName, propKey, operation)
- *     -getOpRegistry()
- *     +register(handler, operation, target, propKey)
- *   }
- *   Operations --> OperationsRegistry : uses
- */
-export declare class Operations {
-    private static registry;
-    private constructor();
-    /**
-     * @description Gets a unique name for an operation handler
-     * @summary Returns the name of the handler function or generates a hash if name is not available
-     * @param {OperationHandler<any, any, any>} handler - The handler function to get the name for
-     * @return {string} The name of the handler or a generated hash
-     */
-    static getHandlerName(handler: OperationHandler<any, any, any>): any;
-    /**
-     * @description Generates a reflection metadata key
-     * @summary Creates a fully qualified metadata key by prefixing with the reflection namespace
-     * @param {string} str - The operation key string to prefix
-     * @return {string} The fully qualified metadata key
-     */
-    static key(str: string): string;
-    /**
-     * @description Retrieves operation handlers for a specific target and operation
-     * @summary Gets registered handlers from the operations registry for a given target, property, and operation
-     * @template M - Model type extending Model
-     * @template R - Repository type extending IRepository
-     * @template V - Metadata type, defaults to object
-     * @template F - Repository flags extending RepositoryFlags
-     * @template C - Context type extending Context<F>
-     * @param {string | Record<string, any>} targetName - The target class name or object
-     * @param {string} propKey - The property key to get handlers for
-     * @param {string} operation - The operation key to get handlers for
-     * @return {any} The registered handlers for the specified target, property, and operation
-     */
-    static get<M extends Model, R extends IRepository<M, any>, V = object>(targetName: string | Record<string, any>, propKey: string, operation: string): OperationHandler<M, R, V>[] | undefined;
-    /**
-     * @description Gets or initializes the operations registry
-     * @summary Returns the existing registry or creates a new one if it doesn't exist
-     * @return {OperationsRegistry} The operations registry instance
-     * @private
-     */
-    private static getOpRegistry;
-    /**
-     * @description Registers an operation handler for a specific target and operation
-     * @summary Adds a handler to the operations registry for a given target, property, and operation
-     * @template V - Model type extending Model
-     * @param {OperationHandler<V, any, any>} handler - The handler function to register
-     * @param {OperationKeys} operation - The operation key to register the handler for
-     * @param {V} target - The target model instance
-     * @param {string | symbol} propKey - The property key to register the handler for
-     * @return {void}
-     */
-    static register<V extends Model>(handler: OperationHandler<V, any, any>, operation: OperationKeys, target: V, propKey: string | symbol): void;
-}

package/lib/types/operations/OperationsRegistry.d.ts

@@ -1,72 +0,0 @@
-import { OperationHandler } from "./types";
-import { OperationKeys } from "./constants";
-import { IRepository } from "../interfaces/IRepository";
-import { Model } from "@decaf-ts/decorator-validation";
-/**
- * @description Registry for database operation handlers
- * @summary Manages and stores operation handlers for different model properties and operations
- * @class OperationsRegistry
- * @template M - Model type
- * @template R - Repository type
- * @template V - Metadata type
- * @template F - Repository flags
- * @template C - Context type
- * @example
- * // Create a registry and register a handler
- * const registry = new OperationsRegistry();
- * registry.register(myHandler, OperationKeys.CREATE, targetModel, 'propertyName');
- *
- * // Get handlers for a specific operation
- * const handlers = registry.get(targetModel.constructor.name, 'propertyName', 'onCreate');
- *
- * @mermaid
- * classDiagram
- *   class OperationsRegistry {
- *     -cache: Record~string, Record~string|symbol, Record~string, Record~string, OperationHandler~~~~
- *     +get(target, propKey, operation, accum)
- *     +register(handler, operation, target, propKey)
- *   }
- */
-export declare class OperationsRegistry {
-    private readonly cache;
-    /**
-     * @description Retrieves operation handlers for a specific target and operation
-     * @summary Finds all registered handlers for a given target, property, and operation, including from parent classes
-     * @template M - Model type extending Model
-     * @template R - Repository type extending IRepository
-     * @template V - Metadata type
-     * @param {string | Record<string, any>} target - The target class name or object
-     * @param {string} propKey - The property key to get handlers for
-     * @param {string} operation - The operation key to get handlers for
-     * @param {OperationHandler[]} [accum] - Accumulator for recursive calls
-     * @return {OperationHandler[] | undefined} Array of handlers or undefined if none found
-     */
-    get<M extends Model, R extends IRepository<M, any>, V>(target: string | Record<string, any>, propKey: string, operation: string, accum?: OperationHandler<M, R, V>[]): OperationHandler<M, R, V>[] | undefined;
-    /**
-     * @description Registers an operation handler for a specific target and operation
-     * @summary Stores a handler in the registry for a given target, property, and operation
-     * @template M - Model type extending Model
-     * @template R - Repository type extending IRepository
-     * @template V - Metadata type
-     * @template F - Repository flags extending RepositoryFlags
-     * @template C - Context type extending Context<F>
-     * @param {OperationHandler} handler - The handler function to register
-     * @param {OperationKeys} operation - The operation key to register the handler for
-     * @param {M} target - The target model instance
-     * @param {string | symbol} propKey - The property key to register the handler for
-     * @return {void}
-     */
-    register<M extends Model, R extends IRepository<M, any>, V>(handler: OperationHandler<M, R, V>, operation: OperationKeys, target: M, propKey: string | symbol): void;
-    private resolveOwner;
-    private resolveTargetName;
-    private resolveFlavour;
-    private selectHandlers;
-    private firstBucket;
-    /**
-     * @description Gets a unique name for an operation handler
-     * @summary Returns the name of the handler function or generates a hash if name is not available
-     * @param {OperationHandler<any, any, any>} handler - The handler function to get the name for
-     * @return {string} The name of the handler or a generated hash
-     */
-    static getHandlerName(handler: OperationHandler<any, any, any>): any;
-}

package/lib/types/operations/constants.d.ts

@@ -1,106 +0,0 @@
-/**
- * @description Database operation key constants
- * @summary Enum defining CRUD operations and their lifecycle phases
- * @enum {string}
- * @readonly
- * @memberOf module:db-decorators
- */
-export declare enum OperationKeys {
-    REFLECT = "decaf.model.db.operations.",
-    CREATE = "create",
-    READ = "read",
-    UPDATE = "update",
-    DELETE = "delete",
-    ON = "on.",
-    AFTER = "after.",
-    BLOCK = "block"
-}
-/**
- * @description Database operation key naming constants
- * @summary Enum defining operations naming
- * @enum {string}
- * @readonly
- * @memberOf module:db-decorators
- */
-export declare enum ModelOperations {
-    OPERATIONS = "operations",
-    RELATIONS = "relations"
-}
-/**
- * @description Type for basic CRUD operations
- * @summary Union type of the four basic database operations: create, read, update, delete
- * @typedef {string} CrudOperations
- * @memberOf module:db-decorators
- */
-export type CrudOperations = OperationKeys.CREATE | OperationKeys.READ | OperationKeys.UPDATE | OperationKeys.DELETE;
-/**
- * @description Bulk database operation key constants
- * @summary Enum defining bulk CRUD operations for handling multiple records at once
- * @enum {string}
- * @readonly
- * @memberOf module:db-decorators
- */
-export declare enum BulkCrudOperationKeys {
-    CREATE_ALL = "createAll",
-    READ_ALL = "readAll",
-    UPDATE_ALL = "updateAll",
-    DELETE_ALL = "deleteAll"
-}
-export declare enum BulkOperationBlockTarget {
-    ALL = "bulkAll"
-}
-/**
- * @description Type for bulk CRUD operations
- * @summary Union type of the four bulk database operations for handling multiple records at once
- * @typedef {string} BulkCrudOperations
- * @memberOf module:db-decorators
- */
-export type BulkCrudOperations = BulkCrudOperationKeys.CREATE_ALL | BulkCrudOperationKeys.READ_ALL | BulkCrudOperationKeys.UPDATE_ALL | BulkCrudOperationKeys.DELETE_ALL;
-/**
- * @description Grouped CRUD operations for decorator mapping
- * @summary Maps out groups of CRUD operations for easier mapping of decorators
- * @const DBOperations
- * @memberOf module:db-decorators
- */
-export declare const DBOperations: Record<string, CrudOperations[]>;
-/**
- * @description Block target categories
- * @summary Indicates whether the block applies to CRUD ops, prepared statements, or query keys
- * @typedef {"crud" | "statement" | "query"} BlockOperationKind
- * @memberOf module:db-decorators
- */
-export type BlockOperationKind = "crud" | "statement" | "query" | "bulk";
-/**
- * @description Descriptor for a single blocked operation target
- * @summary Includes the target kind and identifier (CRUD operation, statement name, query key)
- * @typedef BlockOperationDescriptor
- * @property {"crud"} kind
- * @property {CrudOperations} value
- *
- * @property {"statement"} kind
- * @property {string} value
- *
- * @property {"query"} kind
- * @property {string} value
- * @memberOf module:db-decorators
- */
-export type BlockOperationDescriptor = {
-    kind: "crud";
-    value: CrudOperations;
-} | {
-    kind: "statement";
-    value: string;
-} | {
-    kind: "query";
-    value: string;
-} | {
-    kind: "bulk";
-    value: BulkCrudOperations | BulkOperationBlockTarget;
-};
-/**
- * @description Inputs accepted by @BlockOperations decorator
- * @summary Accepts either a CRUD operation, a descriptor, or an array of both
- * @typedef {CrudOperations | BlockOperationDescriptor | Array<CrudOperations | BlockOperationDescriptor>} BlockOperationsInput
- * @memberOf module:db-decorators
- */
-export type BlockOperationsInput = CrudOperations | BulkCrudOperations | BulkOperationBlockTarget | BlockOperationDescriptor | (CrudOperations | BulkCrudOperations | BulkOperationBlockTarget | BlockOperationDescriptor)[];