tspace-spear/dist/lib/core/decorators/context.d.ts

tspace-spear is a lightweight, high-performance API framework for Node.js that leverages the native HTTP server and supports uWebSockets.js (C++) for maximum speed and efficiency.

import { type T } from '../types';
type ClassConstructor<T = any> = new (...args: any[]) => T;
type ZodSchemaLike = {
    parse: (input: unknown) => any;
    parseAsync: (input: unknown) => Promise<any>;
    safeParseAsync: (input: unknown) => Promise<{
        success: boolean;
        data?: any;
        error?: any;
    }>;
    safeParse: (input: unknown) => {
        success: boolean;
        data?: any;
        error?: any;
    };
};
type Target = "params" | "query" | "body" | "files";
export declare function createDtoDecorator(validator: (ctx: T.Context) => void | Promise<void>, onError?: (ctx: T.Context, error: any) => any): MethodDecorator;
export declare function createContextDecorator(hook: (ctx: T.Context, next: T.NextFunction, meta: {
    target: any;
    key: string | symbol;
    descriptor: PropertyDescriptor;
}) => any | Promise<any>): MethodDecorator;
/**
 * Extract specific fields from `ctx.body`.
 *
 * This decorator filters the request body and keeps only the
 * specified keys. The filtered result replaces `ctx.body`
 * before the controller method is executed.
 *
 * @example
 * ```ts
 * @Body('email', 'password')
 * async login(ctx: T.Context) {
 *   // ctx.body = { email: "...", password: "..." }
 * }
 * ```
 *
 * @param {...string} keys - Body field names to extract.
 * @returns {MethodDecorator}
 */
export declare const Body: (...keys: string[]) => MethodDecorator;
/**
 * Extract specific uploaded files from `ctx.files`.
 *
 * Filters uploaded files and keeps only the specified
 * file field names before executing the controller method.
 *
 * @example
 * ```ts
 * \@Files('avatar', 'resume')
 * async upload(ctx: T.Context) {
 *   // ctx.files = { avatar: File, resume: File }
 * }
 * ```
 *
 * @param {...string} keys - File field names to extract.
 * @returns {MethodDecorator}
 */
export declare const Files: (...keys: string[]) => MethodDecorator;
/**
 * Extract specific route parameters from `ctx.params`.
 *
 * Filters route parameters and keeps only the specified
 * parameter names.
 *
 * @example
 * ```ts
 * \@Params('id')
 * async getUser(ctx: T.Context) {
 *   // ctx.params = { id: "123" }
 * }
 * ```
 *
 * @param {...string} keys - Route parameter names to extract.
 * @returns {MethodDecorator}
 */
export declare const Params: (...keys: string[]) => MethodDecorator;
/**
 * Extract specific query parameters from `ctx.query`.
 *
 * Filters query parameters and keeps only the specified
 * query keys.
 *
 * @example
 * ```ts
 * \@Query('page', 'limit')
 * async listUsers(ctx: T.Context) {
 *   // ctx.query = { page: "1", limit: "10" }
 * }
 * ```
 *
 * @param {...string} keys - Query parameter names to extract.
 * @returns {MethodDecorator}
 */
export declare const Query: (...keys: string[]) => MethodDecorator;
/**
 * Extract specific cookies from `ctx.cookies`.
 *
 * Filters cookies and keeps only the specified cookie keys
 * before executing the controller method.
 *
 * @example
 * ```ts
 * \@Cookies('token')
 * async profile(ctx: T.Context) {
 *   // ctx.cookies = { token: "..." }
 * }
 * ```
 *
 * @param {...string} keys - Cookie names to extract.
 * @returns {MethodDecorator}
 */
export declare const Cookies: (...keys: string[]) => MethodDecorator;
/**
 * Validates required fields from a request target.
 *
 * @param keys - List of required field names.
 * @param options - Validation options.
 * @property options.target - Request source to validate. defaults to `"body"`.
 *
 * @property options.required - Enables required-value validation.
 *
 * - `true`
 *   - Rejects `null`
 *   - Rejects empty strings (`""`)
 *
 * - `object`
 *   - Allows customizing required rules.
 *
 * @property options.required.allowNull - Allow `null` values. Default: `false`
 *
 * @property options.required.allowEmptyString - Allow empty string values. Default: `false`
 * @returns {MethodDecorator}
 *
 * @throws {Object} Throws a validation error object when
 * one or more required fields are missing.
 *
 * @example
 * ```ts
 * \@Validate(["email", "password"], {
 *   required: {
 *     allowEmptyString : true,
 *     allowNull        : false
 *   }
 * });
 * ```
 *
 * @example
 * ```ts
 * \@Validate(["id"], { target: "query" });
 * ```
 */
export declare const Validate: (keys: string[], { target, required }?: {
    target?: Target;
    required?: boolean | {
        allowNull?: boolean;
        allowEmptyString?: boolean;
    };
}) => MethodDecorator;
/**
 * Validate request using either
 * `class-validator` or `zod`.
 *
 * Please install the required validation library before using this decorator.
 * @install
 * npm install class-validator class-transformer
 *
 * npm install zod
 *
 * @example
 * // class-validator (default)
 * \@ValidateDto(UserDto)
 *
 * @example
 * // explicit class-validator
 * \@ValidateDto(UserDto, {
 *   adaptor: "class-validator"
 * })
 *
 * @example
 * // zod
 * \@ValidateDto(UserSchema, {
 *   adaptor: "zod"
 * })
 *
 * @param schema
 * Validation schema/class.
 *
 * - `class-validator`:
 *   Must be a class constructor.
 *
 * - `zod`:
 *   Must be a schema containing `.safeParseAsync()`.
 *
 * @param {Object} options Validation options.
 *
 * @property options.adaptor Validation adaptor. default "class-validator"
 * @property options.message Validation error message.
 * @property options.status Validation error status code.
 * @property options.target Request target to validate. default "body"
 *
 * @returns MethodDecorator
 */
export declare function ValidateDto(schema: ZodSchemaLike, options: {
    adaptor: "zod";
    message?: string;
    status?: 400 | 422 | 500;
    target?: Target;
}): MethodDecorator;
export declare function ValidateDto(schema: ClassConstructor, options?: {
    adaptor: "class-validator";
    message?: string;
    status?: 400 | 422 | 500;
    target?: Target;
}): MethodDecorator;
export {};