@terreno/api 0.0.17 → 0.1.0

package/dist/openApiBuilder.js

@@ -66,6 +66,7 @@ exports.createOpenApiBuilder = createOpenApiBuilder;
 var merge_1 = __importDefault(require("lodash/merge"));
 var logger_1 = require("./logger");
 var openApi_1 = require("./openApi");
+var openApiValidator_1 = require("./openApiValidator");
 /**
  * A fluent builder for constructing OpenAPI middleware.
  *
@@ -99,10 +100,13 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
      * @param options - Router options containing the OpenAPI path configuration
      */
     function OpenApiMiddlewareBuilder(options) {
+        /** Store the raw query parameter schemas for validation */
+        this.queryParamSchemas = {};
         this.options = options;
         this.config = {
             responses: {},
         };
+        this.validationConfig = {};
     }
     /**
      * Sets the tags for the OpenAPI operation.
@@ -201,6 +205,8 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
                 _c),
             required: (_e = options === null || options === void 0 ? void 0 : options.required) !== null && _e !== void 0 ? _e : true,
         };
+        // Store the schema for validation
+        this.requestBodySchema = schema;
         return this;
     };
     /**
@@ -324,6 +330,8 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
             required: (_c = options === null || options === void 0 ? void 0 : options.required) !== null && _c !== void 0 ? _c : false,
             schema: schema,
         });
+        // Store for validation
+        this.queryParamSchemas[name] = __assign(__assign({}, schema), { required: options === null || options === void 0 ? void 0 : options.required });
         return this;
     };
     /**
@@ -358,6 +366,74 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
         });
         return this;
     };
+    /**
+     * Enables runtime validation for this route.
+     *
+     * When enabled, the built middleware will validate incoming requests
+     * against the documented schema before the handler runs.
+     *
+     * @param options - Optional configuration for validation
+     * @param options.body - Enable body validation (default: true if request body is defined)
+     * @param options.query - Enable query parameter validation (default: true if query params are defined)
+     * @param options.enabled - Override the global validation enabled setting
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * createOpenApiBuilder(options)
+     *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+     *   .withValidation() // Enable validation
+     *   .build();
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withValidation = function (options) {
+        var _c, _d, _e;
+        this.validationConfig = {
+            enabled: (_c = options === null || options === void 0 ? void 0 : options.enabled) !== null && _c !== void 0 ? _c : true,
+            validateBody: (_d = options === null || options === void 0 ? void 0 : options.body) !== null && _d !== void 0 ? _d : true,
+            validateQuery: (_e = options === null || options === void 0 ? void 0 : options.query) !== null && _e !== void 0 ? _e : true,
+        };
+        return this;
+    };
+    /**
+     * Builds and returns the OpenAPI middleware along with schemas.
+     *
+     * This method is useful when you want to use asyncHandler's integrated
+     * validation instead of separate validation middleware.
+     *
+     * @returns Object containing middleware and schemas
+     *
+     * @example
+     * ```typescript
+     * const {middleware, bodySchema} = createOpenApiBuilder(options)
+     *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+     *   .buildWithSchemas();
+     *
+     * router.post("/users", middleware, asyncHandler(async (req, res) => {
+     *   // handler code
+     * }, {bodySchema, validate: true}));
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.buildWithSchemas = function () {
+        var _c, _d, _e, _f, _g;
+        var noop = function (_a, _b, next) { return next(); };
+        // Build the OpenAPI documentation middleware only (no validation middleware)
+        var openApiMiddleware = noop;
+        if ((_c = this.options.openApi) === null || _c === void 0 ? void 0 : _c.path) {
+            openApiMiddleware = this.options.openApi.path((0, merge_1.default)(__assign(__assign({}, this.config), { responses: __assign(__assign({}, this.config.responses), openApi_1.defaultOpenApiErrorResponses) }), (_e = (_d = this.options.openApiOverwrite) === null || _d === void 0 ? void 0 : _d.get) !== null && _e !== void 0 ? _e : {}));
+        }
+        else {
+            logger_1.logger.debug("No options.openApi provided, skipping OpenApiMiddleware");
+        }
+        var globalConfig = (0, openApiValidator_1.getOpenApiValidatorConfig)();
+        var validationEnabled = (_f = this.validationConfig.enabled) !== null && _f !== void 0 ? _f : ((0, openApiValidator_1.isOpenApiValidatorConfigured)() && ((_g = globalConfig.validateRequests) !== null && _g !== void 0 ? _g : false));
+        return {
+            bodySchema: this.requestBodySchema,
+            middleware: openApiMiddleware,
+            querySchema: Object.keys(this.queryParamSchemas).length > 0 ? this.queryParamSchemas : undefined,
+            validationEnabled: validationEnabled,
+        };
+    };
     /**
      * Builds and returns the OpenAPI middleware.
      *
@@ -365,10 +441,13 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
      * that integrates with the OpenAPI documentation system. If no OpenAPI
      * path is configured in options, returns a no-op middleware.
      *
+     * If validation was enabled via `withValidation()`, returns an array
+     * of middleware: [openApiDocMiddleware, validationMiddleware].
+     *
      * Default error responses (400, 401, 403, 404, 405) are automatically
      * merged with the configured responses.
      *
-     * @returns Express middleware function for OpenAPI documentation
+     * @returns Express middleware function(s) for OpenAPI documentation and optional validation
      *
      * @example
      * ```typescript
@@ -381,13 +460,38 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
      * ```
      */
     OpenApiMiddlewareBuilder.prototype.build = function () {
-        var _c, _d, _e;
+        var _c, _d, _e, _f, _g;
         var noop = function (_a, _b, next) { return next(); };
-        if (!((_c = this.options.openApi) === null || _c === void 0 ? void 0 : _c.path)) {
+        // Build the OpenAPI documentation middleware
+        var openApiMiddleware = noop;
+        if ((_c = this.options.openApi) === null || _c === void 0 ? void 0 : _c.path) {
+            openApiMiddleware = this.options.openApi.path((0, merge_1.default)(__assign(__assign({}, this.config), { responses: __assign(__assign({}, this.config.responses), openApi_1.defaultOpenApiErrorResponses) }), (_e = (_d = this.options.openApiOverwrite) === null || _d === void 0 ? void 0 : _d.get) !== null && _e !== void 0 ? _e : {}));
+        }
+        else {
             logger_1.logger.debug("No options.openApi provided, skipping OpenApiMiddleware");
-            return noop;
         }
-        return this.options.openApi.path((0, merge_1.default)(__assign(__assign({}, this.config), { responses: __assign(__assign({}, this.config.responses), openApi_1.defaultOpenApiErrorResponses) }), (_e = (_d = this.options.openApiOverwrite) === null || _d === void 0 ? void 0 : _d.get) !== null && _e !== void 0 ? _e : {}));
+        // Check if validation should be enabled
+        var globalConfig = (0, openApiValidator_1.getOpenApiValidatorConfig)();
+        var shouldValidate = (_f = this.validationConfig.enabled) !== null && _f !== void 0 ? _f : ((0, openApiValidator_1.isOpenApiValidatorConfigured)() && ((_g = globalConfig.validateRequests) !== null && _g !== void 0 ? _g : false));
+        if (!shouldValidate) {
+            return openApiMiddleware;
+        }
+        // Build validation middleware
+        var validators = [openApiMiddleware];
+        // Add body validation if we have a request body schema
+        if (this.validationConfig.validateBody && this.requestBodySchema) {
+            validators.push((0, openApiValidator_1.validateRequestBody)(this.requestBodySchema, { enabled: true }));
+        }
+        // Add query validation if we have query parameter schemas
+        if (this.validationConfig.validateQuery && Object.keys(this.queryParamSchemas).length > 0) {
+            validators.push((0, openApiValidator_1.validateQueryParams)(this.queryParamSchemas, { enabled: true }));
+        }
+        // If only one middleware (the openApi one), return it directly
+        if (validators.length === 1) {
+            return openApiMiddleware;
+        }
+        // Return array of middleware to be spread in route definition
+        return validators;
     };
     return OpenApiMiddlewareBuilder;
 }());

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>;