@terreno/api 0.0.17 → 0.1.0

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

package/src/openApiValidator.test.ts

@@ -0,0 +1,241 @@
+import {afterEach, beforeEach, describe, expect, it} from "bun:test";
+
+import {modelRouter} from "./api";
+import {addAuthRoutes, setupAuth} from "./auth";
+import {
+  buildQuerySchemaFromFields,
+  configureOpenApiValidator,
+  isOpenApiValidatorConfigured,
+  resetOpenApiValidatorConfig,
+  validateRequestBody,
+} from "./openApiValidator";
+import {Permissions} from "./permissions";
+import {authAsUser, FoodModel, getBaseServer, RequiredModel, setupDb, UserModel} from "./tests";
+
+// RequiredModel has a clean schema that AJV can compile (no non-standard types).
+// It has: name (String, required), about (String, optional)
+const requiredRouterOptions = {
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    delete: [Permissions.IsAdmin],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsAuthenticated],
+    update: [Permissions.IsAuthenticated],
+  },
+  queryFields: ["name"],
+  sort: "-name" as const,
+};
+
+const setupFreshApp = async () => {
+  const freshApp = getBaseServer();
+  setupAuth(freshApp, UserModel as any);
+  addAuthRoutes(freshApp, UserModel as any);
+  return freshApp;
+};
+
+describe("openApiValidator", () => {
+  beforeEach(async () => {
+    resetOpenApiValidatorConfig();
+    await setupDb();
+    await RequiredModel.deleteMany({});
+  });
+
+  afterEach(() => {
+    resetOpenApiValidatorConfig();
+  });
+
+  describe("isConfigured flag", () => {
+    it("is false by default", () => {
+      expect(isOpenApiValidatorConfigured()).toBe(false);
+    });
+
+    it("becomes true after configureOpenApiValidator()", () => {
+      configureOpenApiValidator();
+      expect(isOpenApiValidatorConfigured()).toBe(true);
+    });
+
+    it("resets to false after resetOpenApiValidatorConfig()", () => {
+      configureOpenApiValidator();
+      expect(isOpenApiValidatorConfigured()).toBe(true);
+      resetOpenApiValidatorConfig();
+      expect(isOpenApiValidatorConfigured()).toBe(false);
+    });
+  });
+
+  describe("no-op when not configured", () => {
+    it("does not strip or validate when not configured", async () => {
+      const freshApp = await setupFreshApp();
+      freshApp.use("/required", modelRouter(RequiredModel, requiredRouterOptions));
+      const admin = await authAsUser(freshApp, "admin");
+
+      // When not configured, validation is a no-op — valid requests pass through
+      const res = await admin.post("/required").send({name: "Apple"}).expect(201);
+      expect(res.body.data.name).toBe("Apple");
+    });
+  });
+
+  describe("active after configuration", () => {
+    it("strips extra properties when removeAdditional is true", async () => {
+      configureOpenApiValidator({removeAdditional: true});
+
+      const freshApp = await setupFreshApp();
+      freshApp.use("/required", modelRouter(RequiredModel, requiredRouterOptions));
+      const admin = await authAsUser(freshApp, "admin");
+
+      const res = await admin
+        .post("/required")
+        .send({fakeField: "this should be stripped", name: "Apple"})
+        .expect(201);
+
+      expect(res.body.data.name).toBe("Apple");
+      expect(res.body.data.fakeField).toBeUndefined();
+    });
+
+    it("rejects missing required fields", async () => {
+      configureOpenApiValidator();
+
+      const freshApp = await setupFreshApp();
+      freshApp.use("/required", modelRouter(RequiredModel, requiredRouterOptions));
+      const admin = await authAsUser(freshApp, "admin");
+
+      const res = await admin.post("/required").send({about: "no name"}).expect(400);
+      expect(res.body.title).toBe("Request validation failed");
+    });
+  });
+
+  describe("onAdditionalPropertiesRemoved hook", () => {
+    it("fires callback with removed property names", async () => {
+      const removedProps: string[] = [];
+
+      configureOpenApiValidator({
+        onAdditionalPropertiesRemoved: (props) => {
+          removedProps.push(...props);
+        },
+        removeAdditional: true,
+      });
+
+      const freshApp = await setupFreshApp();
+      freshApp.use("/required", modelRouter(RequiredModel, requiredRouterOptions));
+      const admin = await authAsUser(freshApp, "admin");
+
+      await admin
+        .post("/required")
+        .send({extraA: "stripped", extraB: "also stripped", name: "Apple"})
+        .expect(201);
+
+      expect(removedProps).toContain("extraA");
+      expect(removedProps).toContain("extraB");
+    });
+  });
+
+  describe("per-route validation: false override", () => {
+    it("skips validation when validation is false", async () => {
+      configureOpenApiValidator({removeAdditional: true});
+
+      const freshApp = await setupFreshApp();
+      freshApp.use(
+        "/required",
+        modelRouter(RequiredModel, {
+          ...requiredRouterOptions,
+          validation: false,
+        })
+      );
+      const admin = await authAsUser(freshApp, "admin");
+
+      // With validation: false, extra properties are NOT stripped by validator
+      // RequiredModel does not have strict: "throw" so the extra field will just be ignored by Mongoose
+      const res = await admin
+        .post("/required")
+        .send({fakeField: "not stripped", name: "Apple"})
+        .expect(201);
+
+      expect(res.body.data.name).toBe("Apple");
+    });
+  });
+
+  describe("sanitization of non-standard mongoose-to-swagger types", () => {
+    it("validates models with ObjectId and DateOnly fields after sanitization", async () => {
+      configureOpenApiValidator({removeAdditional: true});
+
+      const freshApp = await setupFreshApp();
+      freshApp.use(
+        "/food",
+        modelRouter(FoodModel, {
+          permissions: {
+            create: [Permissions.IsAuthenticated],
+            delete: [Permissions.IsAdmin],
+            list: [Permissions.IsAuthenticated],
+            read: [Permissions.IsAuthenticated],
+            update: [Permissions.IsAuthenticated],
+          },
+          queryFields: ["name", "calories", "hidden"],
+          sort: "-created",
+        })
+      );
+      const admin = await authAsUser(freshApp, "admin");
+
+      const res = await admin
+        .post("/food")
+        .send({calories: 100, likesIds: [], name: "Apple", source: {name: "Test"}})
+        .expect(201);
+
+      expect(res.body.data.name).toBe("Apple");
+    });
+  });
+
+  describe("buildQuerySchemaFromFields", () => {
+    it("always includes limit, page, and sort", () => {
+      const schema = buildQuerySchemaFromFields(FoodModel, []);
+      expect(schema.limit).toBeDefined();
+      expect(schema.page).toBeDefined();
+      expect(schema.sort).toBeDefined();
+    });
+
+    it("includes queryFields from model schema", () => {
+      const schema = buildQuerySchemaFromFields(FoodModel, ["name", "calories"]);
+      expect(schema.name).toBeDefined();
+      expect(schema.calories).toBeDefined();
+      expect(schema.hidden).toBeUndefined();
+    });
+
+    it("marks query fields as not required", () => {
+      const schema = buildQuerySchemaFromFields(FoodModel, ["name"]);
+      expect(schema.name.required).toBe(false);
+    });
+  });
+
+  describe("validateRequestBody middleware", () => {
+    it("is a no-op when not configured", () => {
+      resetOpenApiValidatorConfig();
+
+      const middleware = validateRequestBody({
+        name: {required: true, type: "string"},
+      });
+
+      let nextCalled = false;
+      const req = {body: {}} as any;
+      const res = {} as any;
+      const next = () => {
+        nextCalled = true;
+      };
+
+      middleware(req, res, next);
+      expect(nextCalled).toBe(true);
+    });
+
+    it("validates when configured", () => {
+      configureOpenApiValidator();
+
+      const middleware = validateRequestBody({
+        name: {required: true, type: "string"},
+      });
+
+      const req = {body: {}, method: "POST", path: "/test"} as any;
+      const res = {} as any;
+
+      expect(() => {
+        middleware(req, res, () => {});
+      }).toThrow();
+    });
+  });
+});