@decaf-ts/db-decorators 0.12.0 → 0.14.0

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

@@ -0,0 +1,72 @@
+import { OperationHandler } from "./types.cjs";
+import { OperationKeys } from "./constants.cjs";
+import { IRepository } from "../interfaces/IRepository.cjs";
+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/OperationsRegistry.d.mts

@@ -0,0 +1,72 @@
+import { OperationHandler } from "./types.js";
+import { OperationKeys } from "./constants.js";
+import { IRepository } from "../interfaces/IRepository.js";
+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.cts

@@ -0,0 +1,106 @@
+/**
+ * @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)[];

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

@@ -0,0 +1,106 @@
+/**
+ * @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)[];