next-form-request 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,365 @@
+import { NextApiRequest, NextApiResponse } from 'next';
+import { S as SupportedRequest, V as ValidatorAdapter, a as ValidationErrors } from './ZodAdapter-D7D3Sc-a.js';
+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.js';
+import 'zod';
+
+/**
+ * Abstract base class for form request validation.
+ * Inspired by Laravel's Form Request pattern.
+ *
+ * @example
+ * ```typescript
+ * import { FormRequest, ZodAdapter } from 'next-request';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   email: z.string().email(),
+ *   password: z.string().min(8),
+ * });
+ *
+ * export class LoginRequest extends FormRequest<z.infer<typeof schema>> {
+ *   rules() {
+ *     return new ZodAdapter(schema);
+ *   }
+ *
+ *   async authorize() {
+ *     return true; // Allow all requests
+ *   }
+ *
+ *   beforeValidation() {
+ *     this.body.email = this.body.email?.toLowerCase().trim();
+ *   }
+ * }
+ * ```
+ */
+declare abstract class FormRequest<TValidated = unknown> {
+    /**
+     * The original request object
+     */
+    protected request: SupportedRequest;
+    /**
+     * Parsed request body (mutable for beforeValidation hook)
+     */
+    protected body: Record<string, unknown>;
+    /**
+     * Query parameters from the URL
+     */
+    protected query: Record<string, string | string[] | undefined>;
+    /**
+     * Route parameters (e.g., /users/[id])
+     */
+    protected params: Record<string, string>;
+    /**
+     * Request headers
+     */
+    protected headers: Record<string, string | string[] | undefined>;
+    /**
+     * Validated data (populated after successful validation)
+     */
+    private _validated;
+    /**
+     * Partial validated data (fields that passed validation)
+     */
+    private _safe;
+    /**
+     * Define the validation rules for this request.
+     * Return a ValidatorAdapter instance (e.g., ZodAdapter, YupAdapter).
+     */
+    abstract rules(): ValidatorAdapter<TValidated>;
+    /**
+     * Determine if the user is authorized to make this request.
+     * Override this method to add authorization logic.
+     *
+     * @returns true if authorized, false otherwise
+     */
+    authorize(): boolean | Promise<boolean>;
+    /**
+     * Called before validation runs.
+     * Use this to normalize or transform input data.
+     *
+     * @example
+     * ```typescript
+     * beforeValidation() {
+     *   this.body.email = this.body.email?.toLowerCase().trim();
+     * }
+     * ```
+     */
+    beforeValidation(): void | Promise<void>;
+    /**
+     * Called after validation succeeds.
+     * Use this for logging, analytics, or post-processing.
+     *
+     * @param data The validated data
+     */
+    afterValidation(_data: TValidated): void | Promise<void>;
+    /**
+     * Called when validation fails.
+     * Use this for logging or custom error handling.
+     *
+     * @param errors The validation errors
+     */
+    onValidationFailed(_errors: ValidationErrors): void | Promise<void>;
+    /**
+     * Called when authorization fails.
+     * Use this for logging or custom error handling.
+     */
+    onAuthorizationFailed(): void | Promise<void>;
+    /**
+     * Custom validation error messages.
+     * Keys can be field names or "field.rule" patterns.
+     *
+     * @example
+     * ```typescript
+     * messages() {
+     *   return {
+     *     'email.email': 'Please provide a valid email address',
+     *     'password.min': 'Password must be at least 8 characters',
+     *   };
+     * }
+     * ```
+     */
+    messages(): Record<string, string>;
+    /**
+     * Custom attribute names for error messages.
+     * Used to replace field names in error messages.
+     *
+     * @example
+     * ```typescript
+     * attributes() {
+     *   return {
+     *     'email': 'email address',
+     *     'dob': 'date of birth',
+     *   };
+     * }
+     * ```
+     */
+    attributes(): Record<string, string>;
+    /**
+     * Create a FormRequest instance from an App Router Request.
+     *
+     * @param request The incoming Request object
+     * @param params Route parameters (from params in route handler)
+     */
+    static fromAppRouter<T extends FormRequest>(this: new () => T, request: Request, params?: Record<string, string>): Promise<T>;
+    /**
+     * Create a FormRequest instance from a Pages Router NextApiRequest.
+     *
+     * @param request The incoming NextApiRequest object
+     * @param params Route parameters
+     */
+    static fromPagesRouter<T extends FormRequest>(this: new () => T, request: NextApiRequest, params?: Record<string, string>): Promise<T>;
+    /**
+     * Run validation and return the validated data.
+     * Throws ValidationError if validation fails.
+     * Throws AuthorizationError if authorization fails.
+     *
+     * @returns The validated data with full type inference
+     */
+    validate(): Promise<TValidated>;
+    /**
+     * Get the validated data (after calling validate()).
+     * Throws if validate() hasn't been called successfully.
+     */
+    validated(): TValidated;
+    /**
+     * Get only the fields that passed validation.
+     * Safe to call even if validation hasn't completed.
+     */
+    safe(): Partial<TValidated>;
+    /**
+     * Get raw input data (body merged with query for GET requests).
+     */
+    all(): Record<string, unknown>;
+    /**
+     * Get a specific input value.
+     */
+    input<T = unknown>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Check if input has a specific key.
+     */
+    has(key: string): boolean;
+    /**
+     * Get only specified keys from input.
+     */
+    only<K extends string>(...keys: K[]): Pick<Record<string, unknown>, K>;
+    /**
+     * Get all input except specified keys.
+     */
+    except(...keys: string[]): Record<string, unknown>;
+    /**
+     * Get the original request object.
+     */
+    getRequest(): SupportedRequest;
+    /**
+     * Check if this is an App Router request.
+     */
+    isAppRouter(): boolean;
+    /**
+     * Get a header value.
+     */
+    header(name: string): string | string[] | undefined;
+    /**
+     * Get a route parameter.
+     */
+    param(name: string): string | undefined;
+    /**
+     * Get the data that will be validated.
+     * Override this to customize what data is passed to the validator.
+     */
+    protected getDataForValidation(): unknown;
+}
+
+/**
+ * Error thrown when request validation fails
+ */
+declare class ValidationError extends Error {
+    readonly errors: ValidationErrors;
+    constructor(errors: ValidationErrors);
+    /**
+     * Get all error messages as a flat array
+     */
+    getAllMessages(): string[];
+    /**
+     * Get errors for a specific field
+     */
+    getFieldErrors(field: string): string[];
+    /**
+     * Check if a specific field has errors
+     */
+    hasFieldError(field: string): boolean;
+    /**
+     * Convert to JSON-serializable object
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        errors: ValidationErrors;
+    };
+}
+/**
+ * Error thrown when request authorization fails
+ */
+declare class AuthorizationError extends Error {
+    constructor(message?: string);
+    toJSON(): {
+        name: string;
+        message: string;
+    };
+}
+
+/**
+ * Type for FormRequest constructor
+ */
+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>>;
+};
+/**
+ * Handler function for App Router
+ */
+type AppRouterHandler<TValidated> = (validated: TValidated, request: Request, formRequest: FormRequest<TValidated>) => Response | Promise<Response>;
+/**
+ * Handler function for Pages Router
+ */
+type PagesRouterHandler<TValidated> = (validated: TValidated, req: NextApiRequest, res: NextApiResponse, formRequest: FormRequest<TValidated>) => 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 form request validation.
+ *
+ * The handler receives validated data and only executes if:
+ * 1. Authorization passes (authorize() returns true)
+ * 2. Validation passes (rules() validates successfully)
+ *
+ * Errors are thrown, not auto-handled - catch ValidationError and
+ * AuthorizationError in your handler or error boundary.
+ *
+ * @example
+ * ```typescript
+ * // app/api/users/route.ts
+ * import { withRequest } from 'next-request';
+ * import { CreateUserRequest } from '@/requests/CreateUserRequest';
+ *
+ * export const POST = withRequest(CreateUserRequest, async (data, request) => {
+ *   const user = await db.users.create({ data });
+ *   return Response.json({ user }, { status: 201 });
+ * });
+ * ```
+ */
+declare function withRequest<TValidated>(RequestClass: FormRequestClass<TValidated>, handler: AppRouterHandler<TValidated>): (request: Request, context?: AppRouterContext) => Promise<Response>;
+/**
+ * Wrap a Pages Router API handler with form request validation.
+ *
+ * The handler receives validated data and only executes if:
+ * 1. Authorization passes (authorize() returns true)
+ * 2. Validation passes (rules() validates successfully)
+ *
+ * Errors are thrown, not auto-handled - catch ValidationError and
+ * AuthorizationError in your handler.
+ *
+ * @example
+ * ```typescript
+ * // pages/api/users.ts
+ * import { withApiRequest } from 'next-request';
+ * import { CreateUserRequest } from '@/requests/CreateUserRequest';
+ *
+ * export default withApiRequest(CreateUserRequest, async (data, req, res) => {
+ *   const user = await db.users.create({ data });
+ *   res.status(201).json({ user });
+ * });
+ * ```
+ */
+declare function withApiRequest<TValidated>(RequestClass: FormRequestClass<TValidated>, handler: PagesRouterHandler<TValidated>): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+/**
+ * Create a wrapper with custom error handling for App Router.
+ *
+ * @example
+ * ```typescript
+ * import { createAppRouterWrapper, ValidationError, AuthorizationError } from 'next-request';
+ *
+ * const withValidation = createAppRouterWrapper({
+ *   onValidationError: (error) => Response.json({ errors: error.errors }, { status: 422 }),
+ *   onAuthorizationError: () => Response.json({ message: 'Forbidden' }, { status: 403 }),
+ * });
+ *
+ * export const POST = withValidation(CreateUserRequest, async (data) => {
+ *   const user = await db.users.create({ data });
+ *   return Response.json({ user }, { status: 201 });
+ * });
+ * ```
+ */
+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>;
+/**
+ * Create a wrapper with custom error handling for Pages Router.
+ *
+ * @example
+ * ```typescript
+ * import { createPagesRouterWrapper, ValidationError, AuthorizationError } from 'next-request';
+ *
+ * const withValidation = createPagesRouterWrapper({
+ *   onValidationError: (error, req, res) => res.status(422).json({ errors: error.errors }),
+ *   onAuthorizationError: (error, req, res) => res.status(403).json({ message: 'Forbidden' }),
+ * });
+ *
+ * export default withValidation(CreateUserRequest, async (data, req, res) => {
+ *   const user = await db.users.create({ data });
+ *   res.status(201).json({ user });
+ * });
+ * ```
+ */
+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>;
+
+export { AuthorizationError, FormRequest, SupportedRequest, ValidationError, ValidationErrors, ValidatorAdapter, createAppRouterWrapper, createPagesRouterWrapper, withApiRequest, withRequest };