@decaf-ts/db-decorators 0.6.0 → 0.6.2

package/lib/esm/operations/decorators.d.ts

@@ -1,193 +1,199 @@
 import { IdOperationHandler, OperationHandler, StandardOperationHandler, UpdateOperationHandler } from "./types";
 import { OperationKeys } from "./constants";
 /**
- * @summary Defines a behaviour to set on the defined {@link DBOperations.CREATE_UPDATE}
- *
- * @param {OnOperationHandler<any>} handler The method called upon the operation
- * @param data
- * @param {any[]} [args] Arguments that will be passed in order to the handler method
- *
- * @see on
- *
+ * @description Decorator for handling create and update operations
+ * @summary Defines a behavior to execute during both create and update operations
+ * @template V - Type for metadata, defaults to object
+ * @param {StandardOperationHandler<any, any, V, any, any> | UpdateOperationHandler<any, any, V, any, any>} handler - The method called upon the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function onCreateUpdate
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function onCreateUpdate<V = object>(handler: StandardOperationHandler<any, any, V, any, any> | UpdateOperationHandler<any, any, V, any, any>, data?: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set on the defined {@link DBOperations.UPDATE}
- *
- * @param {OnOperationHandler<any>} handler The method called upon the operation
- * @param data
- * @param {any[]} [args] Arguments that will be passed in order to the handler method
- *
- * @see on
- *
+ * @description Decorator for handling update operations
+ * @summary Defines a behavior to execute during update operations
+ * @template V - Type for metadata, defaults to object
+ * @param {UpdateOperationHandler<any, any, V, any>} handler - The method called upon the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function onUpdate
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function onUpdate<V = object>(handler: UpdateOperationHandler<any, any, V, any>, data?: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set on the defined {@link DBOperations.CREATE}
- *
- * @param {OnOperationHandler<any>} handler The method called upon the operation
- * @param data
- *
- * @see on
- *
+ * @description Decorator for handling create operations
+ * @summary Defines a behavior to execute during create operations
+ * @template V - Type for metadata, defaults to object
+ * @param {StandardOperationHandler<any, any, V, any, any>} handler - The method called upon the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function onCreate
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function onCreate<V = object>(handler: StandardOperationHandler<any, any, V, any, any>, data?: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set on the defined {@link DBOperations.READ}
- *
- * @param {OnOperationHandler<any>} handler The method called upon the operation
- * @param data
- *
- * @see on
- *
+ * @description Decorator for handling read operations
+ * @summary Defines a behavior to execute during read operations
+ * @template V - Type for metadata, defaults to object
+ * @param {IdOperationHandler<any, any, V, any, any>} handler - The method called upon the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function onRead
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function onRead<V = object>(handler: IdOperationHandler<any, any, V, any, any>, data: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set on the defined {@link DBOperations.DELETE}
- *
- * @param {OnOperationHandler<any>} handler The method called upon the operation
- * @param data
- *
- * @see on
- *
+ * @description Decorator for handling delete operations
+ * @summary Defines a behavior to execute during delete operations
+ * @template V - Type for metadata, defaults to object
+ * @param {OperationHandler<any, any, V, any, any>} handler - The method called upon the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function onDelete
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function onDelete<V = object>(handler: OperationHandler<any, any, V, any, any>, data: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set on the defined {@link DBOperations.DELETE}
- *
- * @param {OnOperationHandler<any>} handler The method called upon the operation
- * @param data
- *
- * @see on
- *
+ * @description Decorator for handling all operation types
+ * @summary Defines a behavior to execute during any database operation
+ * @template V - Type for metadata, defaults to object
+ * @param {OperationHandler<any, any, V, any, any>} handler - The method called upon the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function onAny
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function onAny<V = object>(handler: OperationHandler<any, any, V, any, any>, data: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set on the defined {@link DBOperations}
- *
- * @param {OperationKeys[] | DBOperations} op One of {@link DBOperations}
- * @param {OnOperationHandler<any>} handler The method called upon the operation
- * @param data
- *
- * ex: handler(...args, ...props.map(p => target[p]))
- *
+ * @description Base decorator for handling database operations
+ * @summary Defines a behavior to execute during specified database operations
+ * @template V - Type for metadata, defaults to object
+ * @param {OperationKeys[] | DBOperations} [op=DBOperations.ALL] - One or more operation types to handle
+ * @param {OperationHandler<any, any, V, any, any>} handler - The method called upon the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function on
- *
- * @category Decorators
+ * @category Property Decorators
+ * @example
+ * // Example usage:
+ * class MyModel {
+ *   @on(DBOperations.CREATE, myHandler)
+ *   myProperty: string;
+ * }
  */
 export declare function on<V = object>(op: OperationKeys[] | undefined, handler: OperationHandler<any, any, V, any, any>, data?: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set after the defined {@link DBOperations.CREATE_UPDATE}
- *
- * @param {AfterOperationHandler<any>} handler The method called upon the operation
- * @param data
- *
- * @see after
- *
+ * @description Decorator for handling post-create and post-update operations
+ * @summary Defines a behavior to execute after both create and update operations
+ * @template V - Type for metadata, defaults to object
+ * @param {StandardOperationHandler<any, any, V, any, any> | UpdateOperationHandler<any, any, V, any, any>} handler - The method called after the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function afterCreateUpdate
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function afterCreateUpdate<V = object>(handler: StandardOperationHandler<any, any, V, any, any> | UpdateOperationHandler<any, any, V, any, any>, data: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set after the defined {@link DBOperations.UPDATE}
- *
- * @param {AfterOperationHandler<any>} handler The method called upon the operation
- * @param data
- *
- * @see after
- *
+ * @description Decorator for handling post-update operations
+ * @summary Defines a behavior to execute after update operations
+ * @template V - Type for metadata, defaults to object
+ * @param {UpdateOperationHandler<any, any, V, any, any>} handler - The method called after the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function afterUpdate
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function afterUpdate<V = object>(handler: UpdateOperationHandler<any, any, V, any, any>, data: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set after the defined {@link DBOperations.CREATE}
- *
- * @param {AfterOperationHandler<any>} handler The method called upon the operation
- * @param data
- *
- * @see after
- *
+ * @description Decorator for handling post-create operations
+ * @summary Defines a behavior to execute after create operations
+ * @template V - Type for metadata, defaults to object
+ * @param {StandardOperationHandler<any, any, V, any, any>} handler - The method called after the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function afterCreate
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function afterCreate<V = object>(handler: StandardOperationHandler<any, any, V, any, any>, data: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set after the defined {@link DBOperations.READ}
- *
- * @param {AfterOperationHandler<any>} handler The method called upon the operation
- * @param data
- * @param {any[]} [args] Arguments that will be passed in order to the handler method
- *
- * @see after
- *
+ * @description Decorator for handling post-read operations
+ * @summary Defines a behavior to execute after read operations
+ * @template V - Type for metadata, defaults to object
+ * @param {StandardOperationHandler<any, any, V, any, any>} handler - The method called after the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function afterRead
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function afterRead<V = object>(handler: StandardOperationHandler<any, any, V, any, any>, data?: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set after the defined {@link DBOperations.DELETE}
- *
- * @param {AfterOperationHandler<any>} handler The method called upon the operation
- * @param data
- * @param {any[]} [args] Arguments that will be passed in order to the handler method
- *
- * @see after
- *
+ * @description Decorator for handling post-delete operations
+ * @summary Defines a behavior to execute after delete operations
+ * @template V - Type for metadata, defaults to object
+ * @param {StandardOperationHandler<any, any, V, any, any>} handler - The method called after the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function afterDelete
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function afterDelete<V = object>(handler: StandardOperationHandler<any, any, V, any, any>, data?: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set after the defined {@link DBOperations.DELETE}
- *
- * @param {AfterOperationHandler<any>} handler The method called upon the operation
- * @param data
- * @param {any[]} [args] Arguments that will be passed in order to the handler method
- *
- * @see after
- *
+ * @description Decorator for handling post-operation for all operation types
+ * @summary Defines a behavior to execute after any database operation
+ * @template V - Type for metadata, defaults to object
+ * @param {StandardOperationHandler<any, any, V, any, any>} handler - The method called after the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function afterAny
- *
- * @category Decorators
+ * @category Property Decorators
  */
 export declare function afterAny<V = object>(handler: StandardOperationHandler<any, any, V, any, any>, data?: V): (target: object, propertyKey?: any) => void;
 /**
- * @summary Defines a behaviour to set on the defined {@link DBOperations}
- *
- * @param {OperationKeys[] | DBOperations} op One of {@link DBOperations}
- * @param {AfterOperationHandler<any>} handler The method called upon the operation
- *
- * ex: handler(...args, ...props.map(p => target[p]))
- *
- * @param data
- * @param args
+ * @description Base decorator for handling post-operation behaviors
+ * @summary Defines a behavior to execute after specified database operations
+ * @template V - Type for metadata, defaults to object
+ * @param {OperationKeys[] | DBOperations} [op=DBOperations.ALL] - One or more operation types to handle
+ * @param {OperationHandler<any, any, V, any, any>} handler - The method called after the operation
+ * @param {V} [data] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
  * @function after
- *
- * @category Decorators
+ * @category Property Decorators
+ * @example
+ * // Example usage:
+ * class MyModel {
+ *   @after(DBOperations.CREATE, myHandler)
+ *   myProperty: string;
+ * }
  */
 export declare function after<V = object>(op: OperationKeys[] | undefined, handler: OperationHandler<any, any, V, any, any>, data?: V): (target: object, propertyKey?: any) => void;
+/**
+ * @description Core decorator factory for operation handlers
+ * @summary Creates decorators that register handlers for database operations
+ * @template V - Type for metadata, defaults to object
+ * @param {OperationKeys.ON | OperationKeys.AFTER} baseOp - Whether the handler runs during or after the operation
+ * @param {OperationKeys[]} [operation=DBOperations.ALL] - The specific operations to handle
+ * @param {OperationHandler<any, any, V, any, any>} handler - The handler function to execute
+ * @param {V} [dataToAdd] - Optional metadata to pass to the handler
+ * @return {PropertyDecorator} A decorator that can be applied to class properties
+ * @function operation
+ * @category Property Decorators
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Decorator as @operation
+ *   participant Operations as Operations Registry
+ *   participant Handler
+ *
+ *   Client->>Decorator: Apply to property
+ *   Decorator->>Operations: Register handler
+ *   Decorator->>Decorator: Store metadata
+ *
+ *   Note over Client,Handler: Later, during operation execution
+ *   Client->>Operations: Execute operation
+ *   Operations->>Handler: Call registered handler
+ *   Handler-->>Operations: Return result
+ *   Operations-->>Client: Return final result
+ */
 export declare function operation<V = object>(baseOp: OperationKeys.ON | OperationKeys.AFTER, operation: OperationKeys[] | undefined, handler: OperationHandler<any, any, V, any, any>, dataToAdd?: V): (target: object, propertyKey?: any) => void;