next-form-request 0.1.1 → 2.0.0

package/dist/index.d.mts

@@ -1,7 +1,229 @@
 import { NextApiRequest, NextApiResponse } from 'next';
-import { S as SupportedRequest, V as ValidatorAdapter, a as ValidationErrors } from './ZodAdapter-D7D3Sc-a.mjs';
-export { A as AppRouterHandler, P as PagesRouterHandler, R as RequestData, c as ValidationConfig, b as ValidationResult, Z as ZodAdapter, i as isAppRouterRequest, d as isPagesRouterRequest } from './ZodAdapter-D7D3Sc-a.mjs';
-import 'zod';
+import { S as SupportedRequest, V as ValidatorAdapter, a as ValidationErrors, b as ValidationConfig, c as ValidationResult } from './ZodAdapter-Ni7VwvnR.mjs';
+export { A as AppRouterHandler, P as PagesRouterHandler, R as RequestData, Z as ZodAdapter, i as isAppRouterRequest, d as isPagesRouterRequest } from './ZodAdapter-Ni7VwvnR.mjs';
+import { z } from 'zod';
+
+/**
+ * Rate limit configuration
+ */
+interface RateLimitConfig {
+    /**
+     * Maximum number of requests allowed in the time window
+     */
+    maxAttempts: number;
+    /**
+     * Time window in milliseconds
+     */
+    windowMs: number;
+    /**
+     * Function to generate the rate limit key from the request
+     * Common options: IP address, user ID, API key, etc.
+     * @default Uses IP address
+     */
+    key?: (request: Request | NextApiRequest) => string | Promise<string>;
+    /**
+     * Custom store for rate limit data
+     * Defaults to in-memory store (not suitable for production with multiple instances)
+     */
+    store?: RateLimitStore;
+    /**
+     * Whether to skip rate limiting for certain requests
+     */
+    skip?: (request: Request | NextApiRequest) => boolean | Promise<boolean>;
+    /**
+     * Custom error message when rate limited
+     */
+    message?: string;
+}
+/**
+ * Rate limit state for a specific key
+ */
+interface RateLimitState {
+    /** Number of requests made in the current window */
+    count: number;
+    /** Timestamp when the window resets */
+    resetAt: number;
+}
+/**
+ * Rate limit check result
+ */
+interface RateLimitResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Number of requests remaining in the current window */
+    remaining: number;
+    /** Total limit */
+    limit: number;
+    /** Timestamp when the window resets */
+    resetAt: number;
+    /** Number of seconds until reset */
+    retryAfter: number;
+}
+/**
+ * Interface for rate limit storage
+ */
+interface RateLimitStore {
+    /** Get the current state for a key */
+    get(key: string): Promise<RateLimitState | null>;
+    /** Set the state for a key */
+    set(key: string, state: RateLimitState, ttlMs: number): Promise<void>;
+    /** Increment the count for a key, returns new state */
+    increment(key: string, windowMs: number): Promise<RateLimitState>;
+}
+/**
+ * In-memory rate limit store (for development/testing only)
+ * In production, use Redis or another distributed store
+ */
+declare class MemoryRateLimitStore implements RateLimitStore {
+    private store;
+    get(key: string): Promise<RateLimitState | null>;
+    set(key: string, state: RateLimitState, _ttlMs: number): Promise<void>;
+    increment(key: string, windowMs: number): Promise<RateLimitState>;
+    private cleanup;
+}
+/**
+ * Set a custom default rate limit store
+ * Useful for setting up Redis or other distributed stores
+ */
+declare function setDefaultRateLimitStore(store: RateLimitStore): void;
+/**
+ * Check rate limit for a request
+ */
+declare function checkRateLimit(request: Request | NextApiRequest, config: RateLimitConfig): Promise<RateLimitResult>;
+/**
+ * Rate limit error thrown when a request exceeds the rate limit
+ */
+declare class RateLimitError extends Error {
+    readonly retryAfter: number;
+    readonly remaining: number;
+    readonly limit: number;
+    readonly resetAt: number;
+    constructor(result: RateLimitResult, message?: string);
+    /**
+     * Get headers to send with the rate limit response
+     */
+    getHeaders(): Record<string, string>;
+}
+/**
+ * Create rate limit configuration with sensible defaults
+ */
+declare function rateLimit(config: Partial<RateLimitConfig> & {
+    maxAttempts: number;
+    windowMs: number;
+}): RateLimitConfig;
+
+/**
+ * Coercion utilities for automatically converting string values from form data
+ * to their appropriate JavaScript types.
+ */
+/**
+ * Options for coercion
+ */
+interface CoercionOptions {
+    /** Coerce "true"/"false" strings to booleans */
+    booleans?: boolean;
+    /** Coerce numeric strings to numbers */
+    numbers?: boolean;
+    /** Coerce ISO date strings to Date objects */
+    dates?: boolean;
+    /** Coerce "null" string to null */
+    nulls?: boolean;
+    /** Coerce empty strings to undefined */
+    emptyStrings?: boolean;
+    /** Coerce JSON strings to objects/arrays */
+    json?: boolean;
+    /** Custom coercion functions for specific fields */
+    fields?: Record<string, (value: unknown) => unknown>;
+}
+/**
+ * Coerce form data values to their appropriate JavaScript types.
+ *
+ * Form submissions typically send everything as strings. This function
+ * automatically converts common patterns:
+ * - "true" / "false" → boolean
+ * - "123" / "45.67" → number
+ * - "2024-01-01" → Date
+ * - "null" → null
+ *
+ * @example
+ * ```typescript
+ * const formData = {
+ *   name: "John",
+ *   age: "25",
+ *   active: "true",
+ *   createdAt: "2024-01-01",
+ * };
+ *
+ * const coerced = coerceFormData(formData);
+ * // {
+ * //   name: "John",
+ * //   age: 25,
+ * //   active: true,
+ * //   createdAt: Date("2024-01-01"),
+ * // }
+ * ```
+ */
+declare function coerceFormData<T extends Record<string, unknown>>(data: T, options?: CoercionOptions): T;
+/**
+ * Create a Zod preprocessor for automatic coercion
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { zodCoerce } from 'next-request';
+ *
+ * const schema = z.preprocess(
+ *   zodCoerce(),
+ *   z.object({
+ *     name: z.string(),
+ *     age: z.number(),
+ *     active: z.boolean(),
+ *   })
+ * );
+ * ```
+ */
+declare function zodCoerce(options?: CoercionOptions): (data: unknown) => unknown;
+/**
+ * Common coercion presets
+ */
+declare const coercionPresets: {
+    /** Coerce all supported types */
+    all: {
+        booleans: true;
+        numbers: true;
+        dates: true;
+        nulls: true;
+        emptyStrings: true;
+        json: true;
+    };
+    /** Only coerce booleans and numbers (safest) */
+    safe: {
+        booleans: true;
+        numbers: true;
+        dates: false;
+        nulls: false;
+        emptyStrings: false;
+        json: false;
+    };
+    /** Coerce booleans, numbers, and dates */
+    standard: {
+        booleans: true;
+        numbers: true;
+        dates: true;
+        nulls: false;
+        emptyStrings: false;
+        json: false;
+    };
+    /** No coercion */
+    none: {
+        booleans: false;
+        numbers: false;
+        dates: false;
+        nulls: false;
+        emptyStrings: false;
+        json: false;
+    };
+};
 
 /**
  * Abstract base class for form request validation.
@@ -73,6 +295,38 @@ declare abstract class FormRequest<TValidated = unknown> {
      * @returns true if authorized, false otherwise
      */
     authorize(): boolean | Promise<boolean>;
+    /**
+     * Define rate limiting for this request.
+     * Override this method to add rate limiting.
+     *
+     * @example
+     * ```typescript
+     * rateLimit() {
+     *   return {
+     *     maxAttempts: 5,
+     *     windowMs: 60000, // 1 minute
+     *     key: (req) => this.input('email') || 'anonymous',
+     *   };
+     * }
+     * ```
+     */
+    rateLimit(): RateLimitConfig | null;
+    /**
+     * Define coercion options for form data.
+     * Override this method to enable automatic type coercion.
+     *
+     * @example
+     * ```typescript
+     * coercion() {
+     *   return {
+     *     booleans: true,  // "true" → true
+     *     numbers: true,   // "123" → 123
+     *     dates: true,     // "2024-01-01" → Date
+     *   };
+     * }
+     * ```
+     */
+    coercion(): CoercionOptions | null;
     /**
      * Called before validation runs.
      * Use this to normalize or transform input data.
@@ -152,6 +406,7 @@ declare abstract class FormRequest<TValidated = unknown> {
      * Run validation and return the validated data.
      * Throws ValidationError if validation fails.
      * Throws AuthorizationError if authorization fails.
+     * Throws RateLimitError if rate limit is exceeded.
      *
      * @returns The validated data with full type inference
      */
@@ -248,13 +503,13 @@ declare class AuthorizationError extends Error {
 }
 
 /**
- * Type for FormRequest constructor
+ * Extract the validated type from a FormRequest constructor
+ * This works by:
+ * 1. Getting the instance type from the constructor: InstanceType<T>
+ * 2. Checking if that instance extends FormRequest<infer V>
+ * 3. Extracting V which is the TValidated generic parameter
  */
-type FormRequestClass<TValidated> = {
-    new (): FormRequest<TValidated>;
-    fromAppRouter(request: Request, params?: Record<string, string>): Promise<FormRequest<TValidated>>;
-    fromPagesRouter(request: NextApiRequest, params?: Record<string, string>): Promise<FormRequest<TValidated>>;
-};
+type InferValidatedType$1<T extends new () => any> = InstanceType<T> extends FormRequest<infer V> ? V : never;
 /**
  * Handler function for App Router
  */
@@ -266,7 +521,7 @@ type PagesRouterHandler<TValidated> = (validated: TValidated, req: NextApiReques
 /**
  * Context parameter for App Router (Next.js 13+)
  */
-interface AppRouterContext {
+interface AppRouterContext$1 {
     params?: Record<string, string> | Promise<Record<string, string>>;
 }
 /**
@@ -291,7 +546,9 @@ interface AppRouterContext {
  * });
  * ```
  */
-declare function withRequest<TValidated>(RequestClass: FormRequestClass<TValidated>, handler: AppRouterHandler<TValidated>): (request: Request, context?: AppRouterContext) => Promise<Response>;
+declare function withRequest<T extends new () => FormRequest<any>>(RequestClass: T & {
+    fromAppRouter(request: Request, params?: Record<string, string>): Promise<InstanceType<T>>;
+}, handler: AppRouterHandler<InferValidatedType$1<T>>): (request: Request, context?: AppRouterContext$1) => Promise<Response>;
 /**
  * Wrap a Pages Router API handler with form request validation.
  *
@@ -314,7 +571,9 @@ declare function withRequest<TValidated>(RequestClass: FormRequestClass<TValidat
  * });
  * ```
  */
-declare function withApiRequest<TValidated>(RequestClass: FormRequestClass<TValidated>, handler: PagesRouterHandler<TValidated>): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+declare function withApiRequest<T extends new () => FormRequest<any>>(RequestClass: T & {
+    fromPagesRouter(request: NextApiRequest, params?: Record<string, string>): Promise<InstanceType<T>>;
+}, handler: PagesRouterHandler<InferValidatedType$1<T>>): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
 /**
  * Create a wrapper with custom error handling for App Router.
  *
@@ -337,7 +596,9 @@ declare function createAppRouterWrapper(options: {
     onValidationError?: (error: ValidationError) => Response;
     onAuthorizationError?: (error: AuthorizationError) => Response;
     onError?: (error: unknown) => Response;
-}): <TValidated>(RequestClass: FormRequestClass<TValidated>, handler: AppRouterHandler<TValidated>) => (request: Request, context?: AppRouterContext) => Promise<Response>;
+}): <T extends new () => FormRequest<any>>(RequestClass: T & {
+    fromAppRouter(request: Request, params?: Record<string, string>): Promise<InstanceType<T>>;
+}, handler: AppRouterHandler<InferValidatedType$1<T>>) => (request: Request, context?: AppRouterContext$1) => Promise<Response>;
 /**
  * Create a wrapper with custom error handling for Pages Router.
  *
@@ -360,6 +621,579 @@ declare function createPagesRouterWrapper(options: {
     onValidationError?: (error: ValidationError, req: NextApiRequest, res: NextApiResponse) => void | Promise<void>;
     onAuthorizationError?: (error: AuthorizationError, req: NextApiRequest, res: NextApiResponse) => void | Promise<void>;
     onError?: (error: unknown, req: NextApiRequest, res: NextApiResponse) => void | Promise<void>;
-}): <TValidated>(RequestClass: FormRequestClass<TValidated>, handler: PagesRouterHandler<TValidated>) => (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+}): <T extends new () => FormRequest<any>>(RequestClass: T & {
+    fromPagesRouter(request: NextApiRequest, params?: Record<string, string>): Promise<InstanceType<T>>;
+}, handler: PagesRouterHandler<InferValidatedType$1<T>>) => (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+
+/**
+ * Infer the validated type from a ValidationAdapter
+ * This extracts the generic type parameter T from ValidatorAdapter<T>
+ */
+type InferValidatedType<T> = T extends ValidatorAdapter<infer V> ? V : never;
+/**
+ * Handler function for App Router with schema validation
+ */
+type SchemaHandler<TValidated> = (data: TValidated, request: Request) => Response | Promise<Response>;
+/**
+ * Handler function for Pages Router with schema validation
+ */
+type ApiSchemaHandler<TValidated> = (data: TValidated, req: NextApiRequest, res: NextApiResponse) => void | Promise<void>;
+/**
+ * Context parameter for App Router (Next.js 13+)
+ */
+interface AppRouterContext {
+    params?: Record<string, string> | Promise<Record<string, string>>;
+}
+/**
+ * Wrap an App Router route handler with simple schema validation.
+ *
+ * This is a lightweight alternative to withRequest for cases where you don't need
+ * hooks or authorization - just schema validation.
+ *
+ * The handler receives validated data and only executes if validation passes.
+ * ValidationError is thrown on validation failure.
+ *
+ * @example
+ * ```typescript
+ * // app/api/users/route.ts
+ * import { withSchema, ZodAdapter } from 'next-request';
+ * import { z } from 'zod';
+ *
+ * const userSchema = z.object({
+ *   name: z.string().min(2),
+ *   email: z.string().email(),
+ * });
+ *
+ * export const POST = withSchema(new ZodAdapter(userSchema), async (data) => {
+ *   // data is typed as { name: string; email: string }
+ *   const user = await db.users.create({ data });
+ *   return Response.json({ user }, { status: 201 });
+ * });
+ * ```
+ */
+declare function withSchema<T extends ValidatorAdapter<any>>(adapter: T, handler: SchemaHandler<InferValidatedType<T>>): (request: Request, context?: AppRouterContext) => Promise<Response>;
+/**
+ * Wrap a Pages Router API handler with simple schema validation.
+ *
+ * This is a lightweight alternative to withApiRequest for cases where you don't need
+ * hooks or authorization - just schema validation.
+ *
+ * The handler receives validated data and only executes if validation passes.
+ * ValidationError is thrown on validation failure.
+ *
+ * @example
+ * ```typescript
+ * // pages/api/users.ts
+ * import { withApiSchema, ZodAdapter } from 'next-request';
+ * import { z } from 'zod';
+ *
+ * const userSchema = z.object({
+ *   name: z.string().min(2),
+ *   email: z.string().email(),
+ * });
+ *
+ * export default withApiSchema(new ZodAdapter(userSchema), async (data, req, res) => {
+ *   // data is typed as { name: string; email: string }
+ *   const user = await db.users.create({ data });
+ *   res.status(201).json({ user });
+ * });
+ * ```
+ */
+declare function withApiSchema<T extends ValidatorAdapter<any>>(adapter: T, handler: ApiSchemaHandler<InferValidatedType<T>>): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+
+interface YupSchema<T> {
+    validate(data: unknown, options?: {
+        abortEarly?: boolean;
+        stripUnknown?: boolean;
+    }): Promise<T>;
+    validateSync(data: unknown, options?: {
+        abortEarly?: boolean;
+        stripUnknown?: boolean;
+    }): T;
+}
+/**
+ * Validator adapter for Yup schemas
+ *
+ * @example
+ * ```typescript
+ * import * as yup from 'yup';
+ * import { YupAdapter } from 'next-request';
+ *
+ * const schema = yup.object({
+ *   email: yup.string().email().required(),
+ *   name: yup.string().min(2).required(),
+ * });
+ *
+ * class MyRequest extends FormRequest<yup.InferType<typeof schema>> {
+ *   rules() {
+ *     return new YupAdapter(schema);
+ *   }
+ * }
+ * ```
+ */
+declare class YupAdapter<T> implements ValidatorAdapter<T> {
+    private schema;
+    constructor(schema: YupSchema<T>);
+    validate(data: unknown, config?: ValidationConfig): Promise<ValidationResult<T>>;
+    validateSync(data: unknown, config?: ValidationConfig): ValidationResult<T>;
+    private isYupValidationError;
+    private formatYupErrors;
+}
+
+interface ValibotIssue {
+    path?: Array<{
+        key: string | number;
+    } | string | number>;
+    message?: string;
+    type?: string;
+}
+interface SafeParseResult<T> {
+    success: boolean;
+    output?: T;
+    issues?: ValibotIssue[];
+}
+interface ValibotSchema<TOutput = unknown> {
+    _output?: TOutput;
+}
+/**
+ * Validator adapter for Valibot schemas.
+ *
+ * Since valibot is an optional peer dependency, you must pass the safeParse function
+ * from your valibot installation.
+ *
+ * @example
+ * ```typescript
+ * import * as v from 'valibot';
+ * import { ValibotAdapter } from 'next-request';
+ *
+ * const schema = v.object({
+ *   email: v.pipe(v.string(), v.email()),
+ *   name: v.pipe(v.string(), v.minLength(2)),
+ * });
+ *
+ * class MyRequest extends FormRequest<v.InferOutput<typeof schema>> {
+ *   rules() {
+ *     return new ValibotAdapter(schema, v.safeParse);
+ *   }
+ * }
+ * ```
+ */
+declare class ValibotAdapter<T> implements ValidatorAdapter<T> {
+    private schema;
+    private safeParseFunc;
+    constructor(schema: ValibotSchema<T>, safeParse: (schema: ValibotSchema<T>, data: unknown) => SafeParseResult<T>);
+    validate(data: unknown, config?: ValidationConfig): Promise<ValidationResult<T>>;
+    validateSync(data: unknown, config?: ValidationConfig): ValidationResult<T>;
+    private formatValibotErrors;
+}
+
+interface ArkTypeSchema<T = unknown> {
+    (data: unknown): T | ArkTypeErrors;
+}
+interface ArkTypeErrors {
+    summary: string;
+    errors?: Array<{
+        path: string[];
+        message: string;
+        code?: string;
+    }>;
+    [Symbol.iterator]?: () => Iterator<{
+        path: string[];
+        message: string;
+    }>;
+}
+/**
+ * Validator adapter for ArkType schemas
+ *
+ * @example
+ * ```typescript
+ * import { type } from 'arktype';
+ * import { ArkTypeAdapter } from 'next-request';
+ *
+ * const schema = type({
+ *   email: 'string.email',
+ *   name: 'string >= 2',
+ * });
+ *
+ * class MyRequest extends FormRequest<typeof schema.infer> {
+ *   rules() {
+ *     return new ArkTypeAdapter(schema);
+ *   }
+ * }
+ * ```
+ */
+declare class ArkTypeAdapter<T> implements ValidatorAdapter<T> {
+    private schema;
+    constructor(schema: ArkTypeSchema<T>);
+    validate(data: unknown, config?: ValidationConfig): Promise<ValidationResult<T>>;
+    validateSync(data: unknown, config?: ValidationConfig): ValidationResult<T>;
+    private formatArkTypeErrors;
+}
+
+/**
+ * Options for file validation
+ */
+interface FormFileOptions {
+    /**
+     * Maximum file size. Can be a number (bytes) or a string like "5mb"
+     */
+    maxSize?: string | number;
+    /**
+     * Minimum file size. Can be a number (bytes) or a string like "1kb"
+     */
+    minSize?: string | number;
+    /**
+     * Allowed MIME types. Supports wildcards like "image/*"
+     * @example ['image/*', 'application/pdf']
+     */
+    types?: string[];
+    /**
+     * Allowed file extensions (without the dot)
+     * @example ['jpg', 'png', 'pdf']
+     */
+    extensions?: string[];
+    /**
+     * Whether the file is required
+     * @default true
+     */
+    required?: boolean;
+}
+/**
+ * Validated file data returned after successful validation
+ */
+interface ValidatedFile {
+    /** Original file name */
+    name: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    type: string;
+    /** The File object (browser) or Blob */
+    file: File | Blob;
+    /** File extension (lowercase, without dot) */
+    extension: string;
+    /** Get file as ArrayBuffer */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Get file as text */
+    text(): Promise<string>;
+    /** Get file as readable stream */
+    stream(): ReadableStream<Uint8Array>;
+}
+/**
+ * Create a Zod schema for file validation with common file constraints.
+ *
+ * @example
+ * ```typescript
+ * import { formFile } from 'next-request';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   avatar: formFile({ maxSize: '5mb', types: ['image/*'] }),
+ *   document: formFile({ maxSize: '10mb', types: ['application/pdf'] }),
+ *   attachment: formFile({ maxSize: '20mb', extensions: ['pdf', 'doc', 'docx'] }),
+ * });
+ * ```
+ */
+declare function formFile(options?: FormFileOptions): z.ZodType<ValidatedFile>;
+/**
+ * Create a Zod schema for multiple file uploads
+ *
+ * @example
+ * ```typescript
+ * import { formFiles } from 'next-request';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   images: formFiles({ maxSize: '5mb', types: ['image/*'], maxFiles: 5 }),
+ * });
+ * ```
+ */
+declare function formFiles(options?: FormFileOptions & {
+    /** Minimum number of files */
+    minFiles?: number;
+    /** Maximum number of files */
+    maxFiles?: number;
+}): z.ZodType<ValidatedFile[]>;
+/**
+ * Type helper to extract the inferred type from a formFile schema
+ */
+type InferFormFile = ValidatedFile;
+type InferFormFiles = ValidatedFile[];
+
+/**
+ * Options for error formatting
+ */
+interface ErrorFormattingOptions {
+    /** Include field path in error messages */
+    includePath?: boolean;
+    /** Custom path separator for nested fields */
+    pathSeparator?: string;
+    /** Maximum number of errors per field */
+    maxErrorsPerField?: number;
+    /** Include array indices in paths */
+    includeArrayIndices?: boolean;
+}
+/**
+ * Structured error format for nested objects and arrays
+ */
+interface StructuredErrors {
+    /** Flat errors (field path → messages) */
+    flat: ValidationErrors;
+    /** Nested errors matching the original object structure */
+    nested: Record<string, unknown>;
+    /** Array of all error messages */
+    all: string[];
+    /** Count of total errors */
+    count: number;
+    /** Check if a specific field has errors */
+    has(field: string): boolean;
+    /** Get errors for a specific field */
+    get(field: string): string[];
+    /** Get first error for a specific field */
+    first(field: string): string | undefined;
+}
+/**
+ * Format validation errors with improved support for nested objects and arrays.
+ *
+ * @example
+ * ```typescript
+ * const errors = {
+ *   'user.email': ['Invalid email'],
+ *   'items.0.name': ['Name is required'],
+ *   'items.1.price': ['Price must be positive'],
+ * };
+ *
+ * const formatted = formatErrors(errors);
+ * // formatted.nested = {
+ * //   user: { email: ['Invalid email'] },
+ * //   items: [
+ * //     { name: ['Name is required'] },
+ * //     { price: ['Price must be positive'] },
+ * //   ],
+ * // }
+ * ```
+ */
+declare function formatErrors(errors: ValidationErrors, options?: ErrorFormattingOptions): StructuredErrors;
+/**
+ * Flatten nested errors into dot-notation paths
+ *
+ * @example
+ * ```typescript
+ * const nested = {
+ *   user: { email: ['Invalid email'] },
+ *   items: [
+ *     { name: ['Name is required'] },
+ *   ],
+ * };
+ *
+ * const flat = flattenErrors(nested);
+ * // { 'user.email': ['Invalid email'], 'items.0.name': ['Name is required'] }
+ * ```
+ */
+declare function flattenErrors(nested: Record<string, unknown>, options?: ErrorFormattingOptions): ValidationErrors;
+/**
+ * Get human-readable error summary
+ */
+declare function summarizeErrors(errors: ValidationErrors): string;
+/**
+ * Filter errors to only include specific fields
+ */
+declare function filterErrors(errors: ValidationErrors, fields: string[]): ValidationErrors;
+/**
+ * Merge multiple error objects
+ */
+declare function mergeErrors(...errorSets: ValidationErrors[]): ValidationErrors;
+
+/**
+ * Result of a mock validation
+ */
+interface MockValidationResult<T> {
+    /** Whether validation succeeded */
+    success: boolean;
+    /** Validated data (if successful) */
+    data?: T;
+    /** Validation errors (if failed) */
+    errors?: ValidationErrors;
+    /** Whether authorization was denied */
+    unauthorized?: boolean;
+    /** The FormRequest instance */
+    instance: FormRequest<T>;
+}
+/**
+ * Options for creating a mock request
+ */
+interface MockRequestOptions {
+    /** HTTP method */
+    method?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Query parameters */
+    query?: Record<string, string>;
+    /** Route parameters */
+    params?: Record<string, string>;
+    /** Base URL for the request */
+    baseUrl?: string;
+}
+/**
+ * Create a mock Request object for testing
+ */
+declare function createMockRequest(body: unknown, options?: MockRequestOptions): Request;
+/**
+ * Test a FormRequest with mock data
+ *
+ * @example
+ * ```typescript
+ * import { testFormRequest } from 'next-request/testing';
+ *
+ * describe('CreateUserRequest', () => {
+ *   it('should validate valid data', async () => {
+ *     const result = await testFormRequest(CreateUserRequest, {
+ *       email: 'user@example.com',
+ *       password: 'securepassword123',
+ *     });
+ *
+ *     expect(result.success).toBe(true);
+ *     expect(result.data?.email).toBe('user@example.com');
+ *   });
+ *
+ *   it('should reject invalid email', async () => {
+ *     const result = await testFormRequest(CreateUserRequest, {
+ *       email: 'invalid-email',
+ *       password: 'securepassword123',
+ *     });
+ *
+ *     expect(result.success).toBe(false);
+ *     expect(result.errors?.email).toBeDefined();
+ *   });
+ * });
+ * ```
+ */
+declare function testFormRequest<T>(RequestClass: new () => FormRequest<T>, body: unknown, options?: MockRequestOptions): Promise<MockValidationResult<T>>;
+/**
+ * Add static mock method to FormRequest class
+ * This allows calling CreateUserRequest.mock({ ... }) directly
+ *
+ * @example
+ * ```typescript
+ * import { addMockMethod } from 'next-request/testing';
+ *
+ * // Add mock method to a specific request class
+ * addMockMethod(CreateUserRequest);
+ *
+ * // Now you can use it directly
+ * const result = await CreateUserRequest.mock({ email: 'invalid' });
+ * expect(result.errors?.email).toBeDefined();
+ * ```
+ */
+declare function addMockMethod<T>(RequestClass: new () => FormRequest<T>): void;
+/**
+ * Type helper for FormRequest classes with mock method
+ */
+interface MockableFormRequest<T> {
+    new (): FormRequest<T>;
+    mock(body: unknown, options?: MockRequestOptions): Promise<MockValidationResult<T>>;
+}
+/**
+ * Assert that validation passes
+ */
+declare function expectValid<T>(result: MockValidationResult<T>): asserts result is MockValidationResult<T> & {
+    success: true;
+    data: T;
+};
+/**
+ * Assert that validation fails
+ */
+declare function expectInvalid<T>(result: MockValidationResult<T>): asserts result is MockValidationResult<T> & {
+    success: false;
+    errors: ValidationErrors;
+};
+/**
+ * Assert that a specific field has errors
+ */
+declare function expectFieldError<T>(result: MockValidationResult<T>, field: string, messagePattern?: string | RegExp): void;
+
+/**
+ * Create an authenticated request base class
+ *
+ * @example
+ * ```typescript
+ * const AuthenticatedRequest = createAuthenticatedRequest(async (request) => {
+ *   const token = request.header('authorization');
+ *   return !!token && await verifyToken(token);
+ * });
+ *
+ * class MyRequest extends AuthenticatedRequest<MyData> {
+ *   rules() { return new ZodAdapter(schema); }
+ * }
+ * ```
+ */
+declare function createAuthenticatedRequest<TBase = unknown>(authorizeFn: (request: FormRequest<TBase>) => boolean | Promise<boolean>): abstract new <T>() => FormRequest<T>;
+/**
+ * Compose multiple authorization checks
+ *
+ * @example
+ * ```typescript
+ * const authorize = composeAuthorization(
+ *   isAuthenticated,
+ *   hasRole('admin'),
+ *   hasPermission('products.create')
+ * );
+ *
+ * class CreateProductRequest extends FormRequest<CreateProductData> {
+ *   authorize = authorize;
+ *   rules() { return new ZodAdapter(schema); }
+ * }
+ * ```
+ */
+declare function composeAuthorization(...checks: Array<(request: FormRequest<unknown>) => boolean | Promise<boolean>>): (this: FormRequest<unknown>) => Promise<boolean>;
+/**
+ * Common authorization helpers
+ */
+declare const authHelpers: {
+    /**
+     * Check if request has a specific header
+     */
+    hasHeader: (headerName: string) => (request: FormRequest<unknown>) => boolean;
+    /**
+     * Check if request has authorization header
+     */
+    isAuthenticated: (request: FormRequest<unknown>) => boolean;
+    /**
+     * Check if request has a bearer token
+     */
+    hasBearerToken: (request: FormRequest<unknown>) => boolean;
+    /**
+     * Extract bearer token from request
+     */
+    getBearerToken: (request: FormRequest<unknown>) => string | null;
+    /**
+     * Check if request has API key
+     */
+    hasApiKey: (headerName?: string) => (request: FormRequest<unknown>) => boolean;
+};
+/**
+ * Lifecycle hook composition utilities
+ */
+declare const hookHelpers: {
+    /**
+     * Compose multiple beforeValidation hooks
+     */
+    beforeValidation: (...hooks: Array<(this: FormRequest<unknown>) => void | Promise<void>>) => (this: FormRequest<unknown>) => Promise<void>;
+    /**
+     * Compose multiple afterValidation hooks
+     */
+    afterValidation: <T>(...hooks: Array<(this: FormRequest<T>, data: T) => void | Promise<void>>) => (this: FormRequest<T>, data: T) => Promise<void>;
+    /**
+     * Common beforeValidation transformations
+     */
+    transforms: {
+        /** Trim all string values */
+        trimStrings: (this: FormRequest<unknown>) => void;
+        /** Lowercase specific fields */
+        lowercase: (...fields: string[]) => (this: FormRequest<unknown>) => void;
+        /** Uppercase specific fields */
+        uppercase: (...fields: string[]) => (this: FormRequest<unknown>) => void;
+    };
+};
 
-export { AuthorizationError, FormRequest, SupportedRequest, ValidationError, ValidationErrors, ValidatorAdapter, createAppRouterWrapper, createPagesRouterWrapper, withApiRequest, withRequest };
+export { ArkTypeAdapter, AuthorizationError, type CoercionOptions, type ErrorFormattingOptions, type FormFileOptions, FormRequest, type InferFormFile, type InferFormFiles, MemoryRateLimitStore, type MockRequestOptions, type MockValidationResult, type MockableFormRequest, type RateLimitConfig, RateLimitError, type RateLimitResult, type RateLimitState, type RateLimitStore, type StructuredErrors, SupportedRequest, ValibotAdapter, type ValidatedFile, ValidationConfig, ValidationError, ValidationErrors, ValidationResult, ValidatorAdapter, YupAdapter, addMockMethod, authHelpers, checkRateLimit, coerceFormData, coercionPresets, composeAuthorization, createAppRouterWrapper, createAuthenticatedRequest, createMockRequest, createPagesRouterWrapper, expectFieldError, expectInvalid, expectValid, filterErrors, flattenErrors, formFile, formFiles, formatErrors, hookHelpers, mergeErrors, rateLimit, setDefaultRateLimitStore, summarizeErrors, testFormRequest, withApiRequest, withApiSchema, withRequest, withSchema, zodCoerce };