@terreno/api 0.0.18 → 0.2.0

package/dist/openApiValidator.d.ts

@@ -0,0 +1,296 @@
+/**
+ * OpenAPI Request Validator
+ *
+ * Provides runtime validation of incoming requests against OpenAPI schemas.
+ * Uses AJV for JSON Schema validation with OpenAPI-compatible settings.
+ *
+ * Validation is always installed as middleware but only activates after
+ * `configureOpenApiValidator()` is called. This makes it safe to include
+ * in modelRouter by default.
+ *
+ * @module openApiValidator
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * // Enable validation globally at server startup
+ * configureOpenApiValidator({
+ *   removeAdditional: true,
+ *   onAdditionalPropertiesRemoved: (props, req) => {
+ *     logger.warn(`Stripped: ${props.join(", ")} on ${req.method} ${req.path}`);
+ *   },
+ * });
+ *
+ * // modelRouter automatically validates when configured
+ * modelRouter(Todo, {
+ *   permissions: {...},
+ *   validation: {
+ *     validateCreate: true,
+ *     validateUpdate: true,
+ *     validateQuery: true,
+ *   },
+ * });
+ * ```
+ */
+import { type ErrorObject } from "ajv";
+import type { NextFunction, Request, Response } from "express";
+import type { Model } from "mongoose";
+import type { OpenApiSchemaProperty } from "./openApiBuilder";
+/**
+ * Global configuration for OpenAPI validation.
+ * This can be set at server startup to control validation behavior.
+ */
+export interface OpenApiValidatorConfig {
+    /**
+     * Enable or disable request body validation.
+     * Default: true (when configureOpenApiValidator is called)
+     */
+    validateRequests?: boolean;
+    /**
+     * Enable or disable response validation.
+     * Default: false (response validation has performance overhead)
+     */
+    validateResponses?: boolean;
+    /**
+     * Whether to coerce types (e.g., string "123" to number 123).
+     * Default: true
+     */
+    coerceTypes?: boolean;
+    /**
+     * Whether to remove additional properties not in the schema.
+     * Default: true
+     */
+    removeAdditional?: boolean;
+    /**
+     * Custom error handler for validation failures.
+     * If not provided, throws an APIError with status 400.
+     */
+    onValidationError?: (errors: ErrorObject[], req: Request) => void;
+    /**
+     * Log validation errors for debugging.
+     * Default: true
+     */
+    logValidationErrors?: boolean;
+    /**
+     * Callback fired when additional properties are removed from a request body.
+     * Only fires when `removeAdditional: true` and extra properties are present.
+     * Receives the list of removed property names and the request.
+     */
+    onAdditionalPropertiesRemoved?: (removedProperties: string[], req: Request) => void;
+}
+/**
+ * Check whether `configureOpenApiValidator()` has been called.
+ * Validation middleware is a no-op when this returns false.
+ */
+export declare function isOpenApiValidatorConfigured(): boolean;
+/**
+ * Configure the global OpenAPI validator settings.
+ * Calling this function activates validation — middleware that was previously
+ * installed as a no-op will begin validating requests.
+ *
+ * @param config - Configuration options to merge with existing config
+ *
+ * @example
+ * ```typescript
+ * configureOpenApiValidator({
+ *   removeAdditional: true,
+ *   onAdditionalPropertiesRemoved: (props, req) => {
+ *     Sentry.captureMessage(`Stripped: ${props.join(", ")} on ${req.method} ${req.path}`);
+ *   },
+ * });
+ * ```
+ */
+export declare function configureOpenApiValidator(config?: Partial<OpenApiValidatorConfig>): void;
+/**
+ * Get the current global validator configuration.
+ */
+export declare function getOpenApiValidatorConfig(): OpenApiValidatorConfig;
+/**
+ * Reset the global validator configuration to defaults.
+ * Also resets `isConfigured` to false.
+ * Useful for testing.
+ */
+export declare function resetOpenApiValidatorConfig(): void;
+/**
+ * Options for the request body validator middleware.
+ */
+export interface RequestBodyValidatorOptions {
+    /**
+     * Override the global validateRequests setting for this specific route.
+     */
+    enabled?: boolean;
+    /**
+     * List of required field names.
+     */
+    required?: string[];
+    /**
+     * Fields to exclude from validation (e.g. fields set by preCreate hooks).
+     * Excluded fields are removed from both the schema properties and the required array.
+     */
+    excludeFields?: string[];
+    /**
+     * Custom error handler for this specific route.
+     */
+    onError?: (errors: ErrorObject[], req: Request) => void;
+    /**
+     * Callback fired when additional properties are removed.
+     * Overrides the global onAdditionalPropertiesRemoved for this route.
+     */
+    onAdditionalPropertiesRemoved?: (removedProperties: string[], req: Request) => void;
+}
+/**
+ * Creates middleware that validates the request body against an OpenAPI schema.
+ *
+ * The middleware checks `isConfigured` at request time — if `configureOpenApiValidator()`
+ * has not been called, the middleware is a no-op.
+ *
+ * @param schema - The schema to validate against (same format as withRequestBody)
+ * @param options - Optional configuration for this validator
+ * @returns Express middleware function
+ */
+export declare function validateRequestBody(schema: Record<string, OpenApiSchemaProperty>, options?: RequestBodyValidatorOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Options for the query parameter validator middleware.
+ */
+export interface QueryValidatorOptions {
+    /**
+     * Override the global validateRequests setting for this specific route.
+     */
+    enabled?: boolean;
+    /**
+     * Custom error handler for this specific route.
+     */
+    onError?: (errors: ErrorObject[], req: Request) => void;
+}
+/**
+ * Creates middleware that validates query parameters against an OpenAPI schema.
+ *
+ * @param schema - The schema to validate against
+ * @param options - Optional configuration for this validator
+ * @returns Express middleware function
+ */
+export declare function validateQueryParams(schema: Record<string, OpenApiSchemaProperty>, options?: QueryValidatorOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Options for creating a combined validation middleware.
+ */
+export interface CreateValidatorOptions {
+    /**
+     * Schema for request body validation.
+     */
+    body?: Record<string, OpenApiSchemaProperty>;
+    /**
+     * Schema for query parameter validation.
+     */
+    query?: Record<string, OpenApiSchemaProperty>;
+    /**
+     * Override the global validation enabled setting.
+     */
+    enabled?: boolean;
+}
+/**
+ * Creates a combined validation middleware for both body and query parameters.
+ *
+ * @param options - Configuration for what to validate
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * router.post("/search", [
+ *   openApiMiddleware,
+ *   createValidator({
+ *     body: {query: {type: "string", required: true}},
+ *     query: {limit: {type: "number"}},
+ *   }),
+ * ], handler);
+ * ```
+ */
+export declare function createValidator(options: CreateValidatorOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Validates response data against a schema.
+ * This is primarily for development/testing to ensure responses match documentation.
+ *
+ * @param data - The response data to validate
+ * @param schema - The expected schema
+ * @returns Object with valid flag and any errors
+ */
+export declare function validateResponseData(data: unknown, schema: Record<string, OpenApiSchemaProperty>): {
+    valid: boolean;
+    errors?: ErrorObject[];
+};
+/**
+ * Extract an OpenAPI-compatible schema from a Mongoose model.
+ * This allows you to use the same schema definitions for both documentation
+ * and runtime validation.
+ *
+ * @param model - A Mongoose model
+ * @returns Schema properties suitable for validation
+ */
+export declare function getSchemaFromModel<T>(model: Model<T>): Record<string, OpenApiSchemaProperty>;
+/**
+ * Creates a request body validator middleware from a Mongoose model.
+ * This is a convenience function that combines getSchemaFromModel and validateRequestBody.
+ *
+ * @param model - A Mongoose model to derive the schema from
+ * @param options - Optional configuration for the validator
+ * @returns Express middleware function
+ */
+export declare function validateModelRequestBody<T>(model: Model<T>, options?: RequestBodyValidatorOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Options for creating validation middleware for a modelRouter.
+ */
+export interface ModelRouterValidationOptions {
+    /**
+     * Enable validation for create (POST) requests.
+     * Default: true (when validation is globally enabled)
+     */
+    validateCreate?: boolean;
+    /**
+     * Enable validation for update (PATCH) requests.
+     * Default: true (when validation is globally enabled)
+     */
+    validateUpdate?: boolean;
+    /**
+     * Enable validation for query (GET list) requests.
+     * Default: true (when validation is globally enabled)
+     */
+    validateQuery?: boolean;
+    /**
+     * Fields to exclude from create validation (e.g. fields injected by preCreate).
+     */
+    excludeFromCreate?: string[];
+    /**
+     * Fields to exclude from update validation (e.g. fields injected by preUpdate).
+     */
+    excludeFromUpdate?: string[];
+    /**
+     * Custom error handler for validation failures.
+     */
+    onError?: (errors: ErrorObject[], req: Request) => void;
+    /**
+     * Callback fired when additional properties are removed from a request body.
+     * Overrides the global onAdditionalPropertiesRemoved for this router.
+     */
+    onAdditionalPropertiesRemoved?: (removedProperties: string[], req: Request) => void;
+}
+/**
+ * Creates validation middleware for use with modelRouter.
+ * Returns an object with middleware for each operation type.
+ *
+ * @param model - The Mongoose model
+ * @param options - Configuration options
+ * @returns Object with create and update validation middleware
+ */
+export declare function createModelValidators<T>(model: Model<T>, options?: ModelRouterValidationOptions): {
+    create: (req: Request, res: Response, next: NextFunction) => void;
+    update: (req: Request, res: Response, next: NextFunction) => void;
+};
+/**
+ * Build a query parameter schema from a model's Mongoose schema and queryFields array.
+ * Always includes pagination parameters (limit, page, sort).
+ *
+ * @param model - A Mongoose model
+ * @param queryFields - Array of field names allowed for querying
+ * @returns Schema properties suitable for query validation
+ */
+export declare function buildQuerySchemaFromFields<T>(model: Model<T>, queryFields?: string[]): Record<string, OpenApiSchemaProperty>;