@buenojs/bueno 0.8.10 → 0.8.11

package/dist/modules/pipes.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Pipes System
+ *
+ * Pipes run after guards in the request pipeline and can transform/validate
+ * data before it reaches the handler.
+ *
+ * Execution Order:
+ * Incoming Request → Guards → Pipes → Handler
+ *
+ * Pipes can:
+ * - Transform data (e.g., string to number)
+ * - Validate data (e.g., using Standard Schema)
+ * - Provide default values
+ */
+import type { Token } from "../container";
+import type { Context } from "../context";
+import type { StandardSchema } from "../types";
+/**
+ * Parameter metadata available to pipes
+ */
+export interface ParameterMetadata {
+    /** Parameter index */
+    index: number;
+    /** Parameter name if available */
+    name?: string;
+    /** Decorator type (body, query, param, etc.) */
+    decorator?: string;
+}
+/**
+ * Context available to pipes during transformation
+ */
+export interface PipeContext {
+    /** The request context */
+    context: Context;
+    /** Parameter metadata */
+    metadata?: ParameterMetadata;
+    /** Target type information */
+    type?: unknown;
+}
+/**
+ * Pipe interface for data transformation
+ *
+ * @example
+ * ```typescript
+ * class ParseIntPipe implements PipeTransform<string, number> {
+ *   transform(value: string, context: PipeContext): number {
+ *     const parsed = parseInt(value, 10);
+ *     if (isNaN(parsed)) {
+ *       throw new Error('Validation failed');
+ *     }
+ *     return parsed;
+ *   }
+ * }
+ * ```
+ */
+export interface PipeTransform<T = unknown, R = unknown> {
+    transform(value: T, context: PipeContext): R | Promise<R>;
+}
+/**
+ * Pipe function type (for functional pipes)
+ *
+ * @example
+ * ```typescript
+ * const trimPipe: PipeFn<string, string> = (value) => value.trim();
+ * ```
+ */
+export type PipeFn<T = unknown, R = unknown> = (value: T, context: PipeContext) => R | Promise<R>;
+/**
+ * Pipe type - can be:
+ * - A token for a pipe class registered in the container
+ * - A pipe class instance
+ * - A pipe function
+ */
+export type Pipe<T = unknown, R = unknown> = Token<PipeTransform<T, R>> | PipeTransform<T, R> | PipeFn<T, R>;
+/**
+ * Metadata for a parameter with pipes
+ */
+export interface ParameterPipeMetadata {
+    /** Parameter index */
+    index: number;
+    /** Parameter decorator type */
+    decorator: "body" | "query" | "param" | "custom";
+    /** Key for query/param decorators */
+    key?: string;
+    /** Schema for validation */
+    schema?: StandardSchema;
+    /** Pipes to apply */
+    pipes: Pipe[];
+}
+/**
+ * Get pipes metadata from a method
+ */
+export declare function getMethodPipes(target: object, propertyKey: string | symbol): ParameterPipeMetadata[] | undefined;
+/**
+ * Decorator to apply pipes to a parameter.
+ * Pipes are executed in the order they are provided.
+ *
+ * @param pipes - Pipes to apply
+ * @returns ParameterDecorator
+ *
+ * @example
+ * ```typescript
+ * @Get(':id')
+ * getUser(@Param('id', ParseIntPipe) id: number) {}
+ * ```
+ */
+export declare function UsePipes(...pipes: Pipe[]): ParameterDecorator;
+/**
+ * Extract and optionally validate request body.
+ *
+ * @param schema - Optional Standard Schema for validation
+ * @returns ParameterDecorator
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * createUser(@Body(userSchema) body: User) {}
+ * ```
+ */
+export declare function Body(schema?: StandardSchema): ParameterDecorator;
+/**
+ * Extract and optionally validate query parameter.
+ *
+ * @param key - Query parameter key (optional, if omitted returns all query params)
+ * @param schema - Optional Standard Schema for validation
+ * @returns ParameterDecorator
+ *
+ * @example
+ * ```typescript
+ * @Get()
+ * search(@Query('q') query: string) {}
+ *
+ * @Get()
+ * search(@Query('limit', limitSchema) limit: number) {}
+ * ```
+ */
+export declare function Query(key?: string, schema?: StandardSchema): ParameterDecorator;
+/**
+ * Extract and transform route parameter.
+ *
+ * @param key - Route parameter key (optional, if omitted returns all params)
+ * @param pipes - Pipes to apply for transformation
+ * @returns ParameterDecorator
+ *
+ * @example
+ * ```typescript
+ * @Get(':id')
+ * getUser(@Param('id', ParseIntPipe) id: number) {}
+ * ```
+ */
+export declare function Param(key?: string, ...pipes: Pipe[]): ParameterDecorator;
+/**
+ * ValidationPipe - Validates using Standard Schema
+ *
+ * @example
+ * ```typescript
+ * @Body(userSchema) body: User
+ * // or explicitly
+ * @UsePipes(new ValidationPipe(userSchema))
+ * ```
+ */
+export declare class ValidationPipe<T = unknown> implements PipeTransform<unknown, T> {
+    private schema;
+    constructor(schema: StandardSchema<unknown, T>);
+    transform(value: unknown, context: PipeContext): Promise<T>;
+}
+/**
+ * ParseIntPipe - Transforms string to integer
+ *
+ * @example
+ * ```typescript
+ * @Param('id', ParseIntPipe) id: number
+ * ```
+ */
+export declare class ParseIntPipe implements PipeTransform<string, number> {
+    transform(value: string, context: PipeContext): number;
+}
+/**
+ * ParseFloatPipe - Transforms string to float
+ *
+ * @example
+ * ```typescript
+ * @Param('price', ParseFloatPipe) price: number
+ * ```
+ */
+export declare class ParseFloatPipe implements PipeTransform<string, number> {
+    transform(value: string, context: PipeContext): number;
+}
+/**
+ * ParseBoolPipe - Transforms string to boolean
+ *
+ * @example
+ * ```typescript
+ * @Query('active', ParseBoolPipe) active: boolean
+ * ```
+ */
+export declare class ParseBoolPipe implements PipeTransform<string, boolean> {
+    private readonly truthyValues;
+    private readonly falsyValues;
+    transform(value: string, context: PipeContext): boolean;
+}
+/**
+ * DefaultValuePipe - Provides default value when input is undefined or null
+ *
+ * @example
+ * ```typescript
+ * @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number
+ * ```
+ */
+export declare class DefaultValuePipe<T> implements PipeTransform<unknown, T> {
+    private defaultValue;
+    constructor(defaultValue: T);
+    transform(value: unknown, context: PipeContext): T;
+}
+/**
+ * TrimPipe - Trims string whitespace
+ *
+ * @example
+ * ```typescript
+ * @Query('name', TrimPipe) name: string
+ * ```
+ */
+export declare class TrimPipe implements PipeTransform<string, string> {
+    transform(value: string, context: PipeContext): string;
+}
+/**
+ * ParseJsonPipe - Parses JSON string to object
+ *
+ * @example
+ * ```typescript
+ * @Query('data', ParseJsonPipe) data: MyObject
+ * ```
+ */
+export declare class ParseJsonPipe<T = unknown> implements PipeTransform<string, T> {
+    transform(value: string, context: PipeContext): T;
+}
+/**
+ * ParseArrayPipe - Transforms comma-separated string to array
+ *
+ * @example
+ * ```typescript
+ * @Query('tags', ParseArrayPipe) tags: string[]
+ * ```
+ */
+export declare class ParseArrayPipe implements PipeTransform<string, string[]> {
+    private separator;
+    constructor(separator?: string);
+    transform(value: string, context: PipeContext): string[];
+}
+/**
+ * Pipe executor options
+ */
+export interface PipeExecutorOptions {
+    /** Global pipes applied to all parameters */
+    globalPipes?: Pipe[];
+    /** Pipes from parameter decorator */
+    parameterPipes?: Pipe[];
+    /** Container for resolving pipe instances */
+    resolvePipe?: (pipe: Pipe) => PipeTransform | PipeFn | null;
+}
+/**
+ * Execute pipes in order and return the transformed value
+ *
+ * @param value - Initial value to transform
+ * @param context - Pipe context
+ * @param options - Pipe executor options
+ * @returns Transformed value
+ * @throws Error if any pipe fails
+ */
+export declare function executePipes<T = unknown>(value: unknown, context: PipeContext, options: PipeExecutorOptions): Promise<T>;
+/**
+ * Extract parameter value from context based on decorator type
+ */
+export declare function extractParameterValue(context: Context, metadata: ParameterPipeMetadata): Promise<unknown>;
+/**
+ * Create a 400 Bad Request response for pipe errors
+ */
+export declare function createBadRequestResponse(error: Error): Response;
+/**
+ * Check if a value is a PipeTransform instance
+ */
+export declare function isPipeTransform(value: unknown): value is PipeTransform;
+/**
+ * Check if a value is a pipe function
+ */
+export declare function isPipeFn(value: unknown): value is PipeFn;
+//# sourceMappingURL=pipes.d.ts.map

package/dist/modules/pipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipes.d.ts","sourceRoot":"","sources":["../../src/modules/pipes.ts"],"names":[],"mappings":"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"}