@terreno/api 0.0.18 → 0.1.0

package/src/api.ts

@@ -18,6 +18,12 @@ import {
   listOpenApiMiddleware,
   patchOpenApiMiddleware,
 } from "./openApi";
+import {
+  buildQuerySchemaFromFields,
+  type ModelRouterValidationOptions,
+  validateModelRequestBody,
+  validateQueryParams,
+} from "./openApiValidator";
 import {checkPermissions, permissionMiddleware, type RESTPermissions} from "./permissions";
 import type {PopulatePath} from "./populate";
 import {
@@ -263,6 +269,19 @@ export interface ModelRouterOptions<T> {
    * that you want to be documented and typed in the SDK.
    */
   openApiExtraModelProperties?: any;
+  /**
+   * Enable runtime validation of request bodies against the OpenAPI schema.
+   * When enabled, requests that don't match the documented schema will return 400 errors.
+   *
+   * Can be set to:
+   * - `true`: Enable validation for create and update operations
+   * - `false`: Disable validation (default)
+   * - Object with `validateCreate` and `validateUpdate` booleans for fine-grained control
+   *
+   * Note: Global validation can be enabled via `configureOpenApiValidator()`.
+   * This option overrides the global setting for this specific router.
+   */
+  validation?: boolean | ModelRouterValidationOptions;
 }
 
 // Ensures query params are allowed. Also checks nested query params when using $and/$or.
@@ -309,6 +328,78 @@ function checkQueryParamAllowed(
 //   return result;
 // }
 
+// Helper to determine if validation should be enabled for a specific operation.
+// When options.validation is not set, returns true — the middleware's own
+// isConfigured check will decide whether to actually validate.
+function shouldValidate(
+  options: ModelRouterOptions<any>,
+  operation: "create" | "update" | "query"
+): boolean {
+  // Check route-specific validation option first
+  if (options.validation !== undefined) {
+    if (typeof options.validation === "boolean") {
+      return options.validation;
+    }
+    if (operation === "create") {
+      return options.validation.validateCreate ?? true;
+    }
+    if (operation === "update") {
+      return options.validation.validateUpdate ?? true;
+    }
+    return options.validation.validateQuery ?? true;
+  }
+
+  // Default: let middleware's isConfigured check decide
+  return true;
+}
+
+// Get body validation middleware if validation is enabled
+function getBodyValidationMiddleware<T>(
+  model: Model<T>,
+  options: ModelRouterOptions<T>,
+  operation: "create" | "update"
+): (req: Request, res: Response, next: NextFunction) => void {
+  const validationOptions: import("./openApiValidator").RequestBodyValidatorOptions = {};
+  if (!shouldValidate(options, operation)) {
+    validationOptions.enabled = false;
+  }
+  if (typeof options.validation === "object") {
+    if (options.validation.onError) {
+      validationOptions.onError = options.validation.onError;
+    }
+    if (options.validation.onAdditionalPropertiesRemoved) {
+      validationOptions.onAdditionalPropertiesRemoved =
+        options.validation.onAdditionalPropertiesRemoved;
+    }
+    const excludeFields =
+      operation === "create"
+        ? options.validation.excludeFromCreate
+        : options.validation.excludeFromUpdate;
+    if (excludeFields?.length) {
+      validationOptions.excludeFields = excludeFields;
+    }
+  }
+
+  return validateModelRequestBody(model, validationOptions);
+}
+
+// Get query validation middleware if validation is enabled
+function getQueryValidationMiddleware<T>(
+  model: Model<T>,
+  options: ModelRouterOptions<T>
+): (req: Request, res: Response, next: NextFunction) => void {
+  const querySchema = buildQuerySchemaFromFields(model, options.queryFields);
+  const validationOptions: import("./openApiValidator").QueryValidatorOptions = {};
+  if (!shouldValidate(options, "query")) {
+    validationOptions.enabled = false;
+  }
+  if (typeof options.validation === "object" && options.validation.onError) {
+    validationOptions.onError = options.validation.onError;
+  }
+
+  return validateQueryParams(querySchema, validationOptions);
+}
+
 /**
  * Create a set of CRUD routes given a Mongoose model and configuration options.
  *
@@ -325,12 +416,18 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
 
   const responseHandler = options.responseHandler ?? defaultResponseHandler;
 
+  // Always install validation middleware — they are no-ops until configureOpenApiValidator() is called
+  const createValidation = getBodyValidationMiddleware(model, options, "create");
+  const updateValidation = getBodyValidationMiddleware(model, options, "update");
+  const queryValidation = getQueryValidationMiddleware(model, options);
+
   router.post(
     "/",
     [
       authenticateMiddleware(options.allowAnonymous),
       createOpenApiMiddleware(model, options),
       permissionMiddleware(model, options),
+      createValidation,
     ],
     asyncHandler(async (req: Request, res: Response) => {
       let body: Partial<T> | (Partial<T> | undefined)[] | null | undefined;
@@ -439,6 +536,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
       authenticateMiddleware(options.allowAnonymous),
       permissionMiddleware(model, options),
       listOpenApiMiddleware(model, options),
+      queryValidation,
     ],
     asyncHandler(async (req: Request, res: Response) => {
       let query: any = {};
@@ -625,6 +723,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
       authenticateMiddleware(options.allowAnonymous),
       patchOpenApiMiddleware(model, options),
       permissionMiddleware(model, options),
+      updateValidation,
     ],
     asyncHandler(async (req: Request, res: Response) => {
       let doc: mongoose.Document & T = (req as any).obj;
@@ -984,9 +1083,116 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
   return router;
 }
 
-// Since express doesn't handle async routes well, wrap them with this function.
-export const asyncHandler = (fn: any) => (req: Request, res: Response, next: NextFunction) => {
-  return Promise.resolve(fn(req, res, next)).catch(next);
+/**
+ * Options for the asyncHandler function.
+ */
+export interface AsyncHandlerOptions {
+  /**
+   * Schema for validating request body.
+   * When provided and validation is enabled, the request body will be validated
+   * against this schema before the handler runs.
+   */
+  bodySchema?: Record<string, import("./openApiBuilder").OpenApiSchemaProperty>;
+
+  /**
+   * Schema for validating query parameters.
+   * When provided and validation is enabled, query params will be validated
+   * against this schema before the handler runs.
+   */
+  querySchema?: Record<string, import("./openApiBuilder").OpenApiSchemaProperty>;
+
+  /**
+   * Override global validation setting for this handler.
+   * - `true`: Enable validation regardless of global setting
+   * - `false`: Disable validation regardless of global setting
+   * - `undefined`: Use global setting
+   */
+  validate?: boolean;
+}
+
+/**
+ * Wraps async route handlers to properly catch and forward errors.
+ *
+ * Since Express doesn't handle async routes well, wrap them with this function.
+ * Optionally supports integrated request validation.
+ *
+ * @param fn - The async route handler function
+ * @param options - Optional configuration for validation
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage without validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code
+ * }));
+ *
+ * // With integrated validation
+ * router.post("/users", asyncHandler(async (req, res) => {
+ *   // handler code - body is already validated
+ * }, {
+ *   bodySchema: {
+ *     name: {type: "string", required: true},
+ *     email: {type: "string", format: "email", required: true},
+ *   },
+ *   validate: true,
+ * }));
+ * ```
+ */
+export const asyncHandler = (fn: any, options?: AsyncHandlerOptions) => {
+  // If no validation options, return simple handler
+  if (!options?.bodySchema && !options?.querySchema) {
+    return (req: Request, res: Response, next: NextFunction) => {
+      return Promise.resolve(fn(req, res, next)).catch(next);
+    };
+  }
+
+  // Import validation functions dynamically to avoid circular deps at module load
+  const {
+    validateRequestBody,
+    validateQueryParams,
+    getOpenApiValidatorConfig,
+  } = require("./openApiValidator");
+
+  // Build validation middleware
+  const validators: ((req: Request, res: Response, next: NextFunction) => void)[] = [];
+
+  // Determine if validation should be enabled
+  const shouldValidate = options.validate ?? getOpenApiValidatorConfig().validateRequests ?? false;
+
+  if (shouldValidate) {
+    if (options.bodySchema) {
+      validators.push(validateRequestBody(options.bodySchema, {enabled: true}));
+    }
+    if (options.querySchema) {
+      validators.push(validateQueryParams(options.querySchema, {enabled: true}));
+    }
+  }
+
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Run validators sequentially, then the handler
+    const runValidators = (index: number): void => {
+      if (index >= validators.length) {
+        // All validators passed, run the actual handler
+        Promise.resolve(fn(req, res, next)).catch(next);
+        return;
+      }
+
+      try {
+        validators[index](req, res, (err?: any) => {
+          if (err) {
+            next(err);
+            return;
+          }
+          runValidators(index + 1);
+        });
+      } catch (err) {
+        next(err);
+      }
+    };
+
+    runValidators(0);
+  };
 };
 
 // For backwards compatibility with the old names.

package/src/auth.ts

@@ -299,7 +299,9 @@ export function addAuthRoutes(
         logger.warn(`Invalid login: ${info}`);
         return res.status(401).json({message: info?.message});
       }
-      logger.info(`User logged in: ${user._id}, type: ${(user as any).type || "N/A"}`);
+      if (process.env.NODE_ENV !== "test") {
+        logger.info(`User logged in: ${user._id}, type: ${(user as any).type || "N/A"}`);
+      }
       const tokens = await generateTokens(user, authOptions);
       return res.json({
         data: {refreshToken: tokens.refreshToken, token: tokens.token, userId: user?._id},

package/src/errors.ts

@@ -136,21 +136,24 @@ export class APIError extends Error {
 // model.
 export function errorsPlugin(schema: Schema): void {
   const errorSchema = new Schema({
-    code: String,
-    detail: String,
-    id: String,
+    code: {description: "Application-specific error code", type: String},
+    detail: {description: "Human-readable explanation of the error", type: String},
+    id: {description: "Unique identifier for this error occurrence", type: String},
     links: {
-      about: String,
-      type: String,
+      about: {description: "Link to documentation about this error", type: String},
+      type: {description: "Link describing the error type", type: String},
     },
-    meta: Schema.Types.Mixed,
+    meta: {description: "Non-standard meta information about the error", type: Schema.Types.Mixed},
     source: {
-      header: String,
-      parameter: String,
-      pointer: String,
+      header: {description: "HTTP header that caused the error", type: String},
+      parameter: {description: "Query parameter that caused the error", type: String},
+      pointer: {
+        description: "JSON pointer to the request field that caused the error",
+        type: String,
+      },
     },
-    status: Number,
-    title: {required: true, type: String},
+    status: {description: "HTTP status code for this error", type: Number},
+    title: {description: "Short summary of the error", required: true, type: String},
   });
 
   schema.add({apiErrors: errorSchema});

package/src/example.ts

@@ -32,8 +32,8 @@ interface Food {
 }
 
 const userSchema = new Schema<User>({
-  admin: {default: false, type: Boolean},
-  username: String,
+  admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
+  username: {description: "The user's username", type: String},
 });
 
 userSchema.plugin(passportLocalMongoose as any, {usernameField: "email"});
@@ -42,11 +42,11 @@ userSchema.plugin(baseUserPlugin);
 const UserModel = model<User>("User", userSchema);
 
 const schema = new Schema<Food>({
-  calories: Number,
-  created: Date,
-  hidden: {default: false, type: Boolean},
-  name: String,
-  ownerId: {ref: "User", type: "ObjectId"},
+  calories: {description: "Number of calories in the food", type: Number},
+  created: {description: "When this food was created", type: Date},
+  hidden: {default: false, description: "Whether this food is hidden from listings", type: Boolean},
+  name: {description: "The name of the food", type: String},
+  ownerId: {description: "The user who owns this food entry", ref: "User", type: "ObjectId"},
 });
 
 const FoodModel = model<Food>("Food", schema);

package/src/githubAuth.test.ts

@@ -20,9 +20,9 @@ interface TestUser extends GitHubUserFields {
 
 // Create schema for GitHub-enabled user
 const testUserSchema = new Schema<TestUser>({
-  admin: {default: false, type: Boolean},
-  name: String,
-  username: String,
+  admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
+  name: {description: "The user's display name", type: String},
+  username: {description: "The user's username", type: String},
 });
 
 testUserSchema.plugin(passportLocalMongoose as any, {

package/src/index.ts

@@ -8,8 +8,10 @@ export * from "./middleware";
 export * from "./notifiers";
 export * from "./openApiBuilder";
 export * from "./openApiEtag";
+export * from "./openApiValidator";
 export * from "./permissions";
 export * from "./plugins";
 export * from "./populate";
+export * from "./terrenoPlugin";
 export * from "./transformers";
 export * from "./utils";

package/src/openApi.test.ts

@@ -160,13 +160,13 @@ describe("openApi", () => {
     // Ensure that a Number query field supports gt/gte/lt/lte and just a Number
     expect(foodQuery.schema).toEqual({
       oneOf: [
-        {type: "number"},
+        {description: "Number of calories in the food", type: "number"},
         {
           properties: {
-            $gt: {type: "number"},
-            $gte: {type: "number"},
-            $lt: {type: "number"},
-            $lte: {type: "number"},
+            $gt: {description: "Number of calories in the food", type: "number"},
+            $gte: {description: "Number of calories in the food", type: "number"},
+            $lt: {description: "Number of calories in the food", type: "number"},
+            $lte: {description: "Number of calories in the food", type: "number"},
           },
           type: "object",
         },
@@ -278,6 +278,7 @@ describe("openApi populate", () => {
           type: "string",
         },
         name: {
+          description: "The user's display name",
           type: "string",
         },
       },
@@ -293,12 +294,14 @@ describe("openApi populate", () => {
     });
 
     expect(properties.likesIds).toEqual({
+      description: "User likes for this food",
       items: {
         properties: {
           _id: {
             type: "string",
           },
           likes: {
+            description: "Whether the user liked the item",
             type: "boolean",
           },
           userId: {

package/src/openApiBuilder.ts

@@ -34,6 +34,12 @@ import merge from "lodash/merge";
 import type {ModelRouterOptions} from "./api";
 import {logger} from "./logger";
 import {defaultOpenApiErrorResponses} from "./openApi";
+import {
+  getOpenApiValidatorConfig,
+  isOpenApiValidatorConfigured,
+  validateQueryParams,
+  validateRequestBody,
+} from "./openApiValidator";
 
 /**
  * Defines a property within an OpenAPI schema.
@@ -222,6 +228,33 @@ interface OpenApiConfig {
   responses: Record<number | string, OpenApiResponse>;
 }
 
+/**
+ * Internal validation configuration for the builder.
+ */
+interface ValidationConfig {
+  /** Whether to validate request body */
+  validateBody?: boolean;
+  /** Whether to validate query parameters */
+  validateQuery?: boolean;
+  /** Override the global validation enabled setting */
+  enabled?: boolean;
+}
+
+/**
+ * Result from building OpenAPI middleware with schemas exposed.
+ * Useful when you want to use the schemas with asyncHandler's validation.
+ */
+export interface OpenApiBuildResult {
+  /** The OpenAPI documentation middleware */
+  middleware: any;
+  /** Request body schema if defined */
+  bodySchema?: Record<string, OpenApiSchemaProperty>;
+  /** Query parameter schemas if defined */
+  querySchema?: Record<string, OpenApiSchemaProperty>;
+  /** Whether validation was enabled on this builder */
+  validationEnabled: boolean;
+}
+
 /**
  * A fluent builder for constructing OpenAPI middleware.
  *
@@ -255,6 +288,15 @@ export class OpenApiMiddlewareBuilder {
   /** Accumulated OpenAPI configuration from builder methods */
   private config: OpenApiConfig;
 
+  /** Validation configuration */
+  private validationConfig: ValidationConfig;
+
+  /** Store the raw request body schema for validation */
+  private requestBodySchema?: Record<string, OpenApiSchemaProperty>;
+
+  /** Store the raw query parameter schemas for validation */
+  private queryParamSchemas: Record<string, OpenApiSchemaProperty> = {};
+
   /**
    * Creates a new OpenApiMiddlewareBuilder instance.
    *
@@ -265,6 +307,7 @@ export class OpenApiMiddlewareBuilder {
     this.config = {
       responses: {},
     };
+    this.validationConfig = {};
   }
 
   /**
@@ -368,6 +411,10 @@ export class OpenApiMiddlewareBuilder {
       },
       required: options?.required ?? true,
     };
+
+    // Store the schema for validation
+    this.requestBodySchema = schema as Record<string, OpenApiSchemaProperty>;
+
     return this;
   }
 
@@ -515,6 +562,13 @@ export class OpenApiMiddlewareBuilder {
       required: options?.required ?? false,
       schema,
     });
+
+    // Store for validation
+    this.queryParamSchemas[name] = {
+      ...schema,
+      required: options?.required,
+    };
+
     return this;
   }
 
@@ -557,6 +611,90 @@ export class OpenApiMiddlewareBuilder {
     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();
+   * ```
+   */
+  withValidation(options?: {body?: boolean; query?: boolean; enabled?: boolean}): this {
+    this.validationConfig = {
+      enabled: options?.enabled ?? true,
+      validateBody: options?.body ?? true,
+      validateQuery: options?.query ?? 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}));
+   * ```
+   */
+  buildWithSchemas(): OpenApiBuildResult {
+    const noop = (_a: any, _b: any, next: () => void): void => next();
+
+    // Build the OpenAPI documentation middleware only (no validation middleware)
+    let openApiMiddleware: any = noop;
+    if (this.options.openApi?.path) {
+      openApiMiddleware = this.options.openApi.path(
+        merge(
+          {
+            ...this.config,
+            responses: {
+              ...this.config.responses,
+              ...defaultOpenApiErrorResponses,
+            },
+          },
+          this.options.openApiOverwrite?.get ?? {}
+        )
+      );
+    } else {
+      logger.debug("No options.openApi provided, skipping OpenApiMiddleware");
+    }
+
+    const globalConfig = getOpenApiValidatorConfig();
+    const validationEnabled =
+      this.validationConfig.enabled ??
+      (isOpenApiValidatorConfigured() && (globalConfig.validateRequests ?? false));
+
+    return {
+      bodySchema: this.requestBodySchema,
+      middleware: openApiMiddleware,
+      querySchema:
+        Object.keys(this.queryParamSchemas).length > 0 ? this.queryParamSchemas : undefined,
+      validationEnabled,
+    };
+  }
+
   /**
    * Builds and returns the OpenAPI middleware.
    *
@@ -564,10 +702,13 @@ export class OpenApiMiddlewareBuilder {
    * 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
@@ -582,23 +723,55 @@ export class OpenApiMiddlewareBuilder {
   build(): any {
     const noop = (_a: any, _b: any, next: () => void): void => next();
 
-    if (!this.options.openApi?.path) {
+    // Build the OpenAPI documentation middleware
+    let openApiMiddleware: any = noop;
+    if (this.options.openApi?.path) {
+      openApiMiddleware = this.options.openApi.path(
+        merge(
+          {
+            ...this.config,
+            responses: {
+              ...this.config.responses,
+              ...defaultOpenApiErrorResponses,
+            },
+          },
+          this.options.openApiOverwrite?.get ?? {}
+        )
+      );
+    } else {
       logger.debug("No options.openApi provided, skipping OpenApiMiddleware");
-      return noop;
     }
 
-    return this.options.openApi.path(
-      merge(
-        {
-          ...this.config,
-          responses: {
-            ...this.config.responses,
-            ...defaultOpenApiErrorResponses,
-          },
-        },
-        this.options.openApiOverwrite?.get ?? {}
-      )
-    );
+    // Check if validation should be enabled
+    const globalConfig = getOpenApiValidatorConfig();
+    const shouldValidate =
+      this.validationConfig.enabled ??
+      (isOpenApiValidatorConfigured() && (globalConfig.validateRequests ?? false));
+
+    if (!shouldValidate) {
+      return openApiMiddleware;
+    }
+
+    // Build validation middleware
+    const validators: any[] = [openApiMiddleware];
+
+    // Add body validation if we have a request body schema
+    if (this.validationConfig.validateBody && this.requestBodySchema) {
+      validators.push(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(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;
   }
 }