@decaf-ts/decorator-validation/lib/utils/Decoration.d.ts

simple decorator based validation engine

import { DecorationBuilderBuild, DecorationBuilderEnd, DecorationBuilderMid, DecorationBuilderStart, FlavourResolver, IDecorationBuilder } from "./types";
export type DecoratorTypes = ClassDecorator | PropertyDecorator | MethodDecorator;
export type DecoratorFactory = (...args: any[]) => DecoratorTypes;
export type DecoratorFactoryArgs = {
    decorator: DecoratorFactory;
    args?: any[];
    transform?: (args: any[]) => any[];
};
export type DecoratorData = DecoratorTypes | DecoratorFactoryArgs;
/**
 * @description A decorator management class that handles flavoured decorators
 * @summary The Decoration class provides a builder pattern for creating and managing decorators with different flavours.
 * It supports registering, extending, and applying decorators with context-aware flavour resolution.
 * The class implements a fluent interface for defining, extending, and applying decorators with different flavours,
 * allowing for framework-specific decorator implementations while maintaining a consistent API.
 * @template T Type of the decorator (ClassDecorator | PropertyDecorator | MethodDecorator)
 * @param {string} [flavour] Optional flavour parameter for the decorator context
 * @class
 * @category Model
 * @example
 * ```typescript
 * // Create a new decoration for 'component' with default flavour
 * const componentDecorator = new Decoration()
 *   .for('component')
 *   .define(customComponentDecorator);
 *
 * // Create a flavoured decoration
 * const vueComponent = new Decoration('vue')
 *   .for('component')
 *   .define(vueComponentDecorator);
 *
 * // Apply the decoration
 * @componentDecorator
 * class MyComponent {}
 * ```
 * @mermaid
 * sequenceDiagram
 *   participant C as Client
 *   participant D as Decoration
 *   participant R as FlavourResolver
 *   participant F as DecoratorFactory
 *
 *   C->>D: new Decoration(flavour)
 *   C->>D: for(key)
 *   C->>D: define(decorators)
 *   D->>D: register(key, flavour, decorators)
 *   D->>F: decoratorFactory(key, flavour)
 *   F->>R: resolve(target)
 *   R-->>F: resolved flavour
 *   F->>F: apply decorators
 *   F-->>C: decorated target
 */
export declare class Decoration implements IDecorationBuilder {
    private flavour;
    /**
     * @description Static map of registered decorators
     * @summary Stores all registered decorators organized by key and flavour
     */
    private static decorators;
    /**
     * @description Function to resolve flavour from a target
     * @summary Resolver function that determines the appropriate flavour for a given target
     */
    private static flavourResolver;
    /**
     * @description Set of decorators for the current context
     */
    private decorators?;
    /**
     * @description Set of additional decorators
     */
    private extras?;
    /**
     * @description Current decorator key
     */
    private key?;
    constructor(flavour?: string);
    /**
     * @description Sets the key for the decoration builder
     * @summary Initializes a new decoration chain with the specified key
     * @param {string} key The identifier for the decorator
     * @return {DecorationBuilderMid} Builder instance for method chaining
     */
    for(key: string): DecorationBuilderMid;
    /**
     * @description Adds decorators to the current context
     * @summary Internal method to add decorators with addon support
     * @param {boolean} [addon=false] Whether the decorators are addons
     * @param decorators Array of decorators
     * @return {this} Current instance for chaining
     */
    private decorate;
    /**
     * @description Defines the base decorators
     * @summary Sets the primary decorators for the current context
     * @param decorators Decorators to define
     * @return Builder instance for finishing the chain
     */
    define(...decorators: DecoratorData[]): DecorationBuilderEnd & DecorationBuilderBuild;
    /**
     * @description Extends existing decorators
     * @summary Adds additional decorators to the current context
     * @param decorators Additional decorators
     * @return {DecorationBuilderBuild} Builder instance for building the decorator
     */
    extend(...decorators: DecoratorData[]): DecorationBuilderBuild;
    protected decoratorFactory(key: string, f?: string): (target: object, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => {
        target: object;
        propertyKey: any;
        descriptor: TypedPropertyDescriptor<any> | undefined;
    };
    /**
     * @description Creates the final decorator function
     * @summary Builds and returns the decorator factory function
     * @return {function(any, any?, TypedPropertyDescriptor?): any} The generated decorator function
     */
    apply(): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
    /**
     * @description Registers decorators for a specific key and flavour
     * @summary Internal method to store decorators in the static registry
     * @param {string} key Decorator key
     * @param {string} flavour Decorator flavour
     * @param [decorators] Primary decorators
     * @param [extras] Additional decorators
     */
    private static register;
    /**
     * @description Sets the global flavour resolver
     * @summary Configures the function used to determine decorator flavours
     * @param {FlavourResolver} resolver Function to resolve flavours
     */
    static setFlavourResolver(resolver: FlavourResolver): void;
    static for(key: string): DecorationBuilderMid;
    static flavouredAs(flavour: string): DecorationBuilderStart;
}