@terreno/api 0.10.0 → 0.11.0

package/src/openApiValidator.test.ts

@@ -1,13 +1,21 @@
 import {afterEach, beforeEach, describe, expect, it} from "bun:test";
+import type {ErrorObject} from "ajv";
 
 import {modelRouter} from "./api";
 import {addAuthRoutes, setupAuth} from "./auth";
 import {
   buildQuerySchemaFromFields,
   configureOpenApiValidator,
+  createModelValidators,
+  createValidator,
+  getOpenApiValidatorConfig,
+  getSchemaFromModel,
   isOpenApiValidatorConfigured,
   resetOpenApiValidatorConfig,
+  validateModelRequestBody,
+  validateQueryParams,
   validateRequestBody,
+  validateResponseData,
 } from "./openApiValidator";
 import {Permissions} from "./permissions";
 import {authAsUser, FoodModel, getBaseServer, RequiredModel, setupDb, UserModel} from "./tests";
@@ -237,5 +245,407 @@ describe("openApiValidator", () => {
         middleware(req, res, () => {});
       }).toThrow();
     });
+
+    it("calls onError callback instead of throwing when provided at option level", () => {
+      configureOpenApiValidator();
+
+      let capturedErrors: ErrorObject[] = [];
+      const middleware = validateRequestBody(
+        {name: {required: true, type: "string"}},
+        {
+          onError: (errors) => {
+            capturedErrors = errors;
+          },
+        }
+      );
+
+      let nextCalled = false;
+      const req = {body: {}, method: "POST", path: "/test"} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+      expect(capturedErrors.length).toBeGreaterThan(0);
+    });
+
+    it("calls global onValidationError when no per-route handler", () => {
+      let capturedErrors: ErrorObject[] = [];
+      configureOpenApiValidator({
+        onValidationError: (errors) => {
+          capturedErrors = errors;
+        },
+      });
+
+      const middleware = validateRequestBody({name: {required: true, type: "string"}});
+
+      let nextCalled = false;
+      const req = {body: {}, method: "POST", path: "/test"} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+      expect(capturedErrors.length).toBeGreaterThan(0);
+    });
+
+    it("skips validation when enabled=false on options", () => {
+      configureOpenApiValidator();
+
+      const middleware = validateRequestBody(
+        {name: {required: true, type: "string"}},
+        {enabled: false}
+      );
+
+      let nextCalled = false;
+      const req = {body: {}, method: "POST", path: "/test"} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+    });
+
+    it("respects validateRequests=false in global config", () => {
+      configureOpenApiValidator({validateRequests: false});
+
+      const middleware = validateRequestBody({name: {required: true, type: "string"}});
+
+      let nextCalled = false;
+      const req = {body: {}, method: "POST", path: "/test"} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+    });
+  });
+
+  describe("validateQueryParams middleware", () => {
+    it("is a no-op when not configured", () => {
+      resetOpenApiValidatorConfig();
+
+      const middleware = validateQueryParams({
+        page: {type: "number"},
+      });
+
+      let nextCalled = false;
+      const req = {method: "GET", path: "/test", query: {}} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+    });
+
+    it("coerces types when configured", () => {
+      configureOpenApiValidator({coerceTypes: true});
+
+      const middleware = validateQueryParams({
+        page: {type: "number"},
+      });
+
+      const req = {method: "GET", path: "/test", query: {page: "3"}} as any;
+      const res = {} as any;
+      middleware(req, res, () => {});
+
+      expect(req.query.page).toBe(3);
+    });
+
+    it("throws validation error when query does not match", () => {
+      configureOpenApiValidator({coerceTypes: false});
+
+      const middleware = validateQueryParams({
+        page: {required: true, type: "number"},
+      });
+
+      const req = {method: "GET", path: "/test", query: {}} as any;
+      const res = {} as any;
+      // Required top-level property missing triggers an error
+      // We need required: [] at schema level via required: true on property. Confirm via calling.
+      expect(() => {
+        middleware(req, res, () => {});
+      }).toThrow();
+    });
+
+    it("uses onError callback for query validation", () => {
+      let captured: any[] = [];
+      configureOpenApiValidator({coerceTypes: false});
+
+      const middleware = validateQueryParams(
+        {page: {required: true, type: "number"}},
+        {
+          onError: (errors) => {
+            captured = errors;
+          },
+        }
+      );
+
+      let nextCalled = false;
+      const req = {method: "GET", path: "/test", query: {}} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+      expect(captured.length).toBeGreaterThan(0);
+    });
+
+    it("skips query validation when enabled=false", () => {
+      configureOpenApiValidator();
+
+      const middleware = validateQueryParams(
+        {page: {required: true, type: "number"}},
+        {enabled: false}
+      );
+
+      let nextCalled = false;
+      const req = {method: "GET", path: "/test", query: {}} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+    });
+  });
+
+  describe("validateResponseData", () => {
+    it("returns valid when validateResponses is disabled", () => {
+      configureOpenApiValidator({validateResponses: false});
+      const result = validateResponseData({foo: "bar"}, {name: {type: "string"}});
+      expect(result.valid).toBe(true);
+    });
+
+    it("validates response shape when validateResponses is enabled", () => {
+      configureOpenApiValidator({validateResponses: true});
+      const result = validateResponseData(
+        {name: "Apple"},
+        {name: {required: true, type: "string"}}
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("returns errors for invalid response shape", () => {
+      configureOpenApiValidator({coerceTypes: false, validateResponses: true});
+      const result = validateResponseData(
+        {name: 42 as any},
+        {name: {required: true, type: "string"}}
+      );
+      expect(result.valid).toBe(false);
+      expect(result.errors).toBeDefined();
+    });
+  });
+
+  describe("createValidator", () => {
+    it("runs body then query validation and calls next once both pass", () => {
+      configureOpenApiValidator({coerceTypes: true});
+
+      const middleware = createValidator({
+        body: {name: {required: true, type: "string"}},
+        query: {page: {type: "number"}},
+      });
+
+      let nextCalled = false;
+      const req = {
+        body: {name: "ok"},
+        method: "POST",
+        path: "/test",
+        query: {page: "2"},
+      } as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+      expect(req.query.page).toBe(2);
+    });
+
+    it("skips when neither body nor query schemas are provided", () => {
+      configureOpenApiValidator();
+
+      const middleware = createValidator({});
+
+      let nextCalled = false;
+      const req = {body: {}, method: "POST", path: "/test", query: {}} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+    });
+
+    it("runs only query validation when only query provided", () => {
+      configureOpenApiValidator({coerceTypes: true});
+
+      const middleware = createValidator({
+        query: {page: {type: "number"}},
+      });
+
+      let nextCalled = false;
+      const req = {method: "GET", path: "/test", query: {page: "5"}} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+      expect(req.query.page).toBe(5);
+    });
+
+    it("propagates body validation error via next", () => {
+      let capturedErrors: ErrorObject[] = [];
+      configureOpenApiValidator({
+        onValidationError: (errors) => {
+          capturedErrors = errors;
+        },
+      });
+
+      const middleware = createValidator({
+        body: {name: {required: true, type: "string"}},
+        query: {page: {type: "number"}},
+      });
+
+      const req = {body: {}, method: "POST", path: "/test", query: {}} as any;
+      const res = {} as any;
+
+      let nextCalled = false;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(capturedErrors.length).toBeGreaterThan(0);
+      expect(nextCalled).toBe(true);
+    });
+  });
+
+  describe("createModelValidators", () => {
+    beforeEach(() => {
+      configureOpenApiValidator();
+    });
+
+    it("returns create and update middleware", () => {
+      const validators = createModelValidators(RequiredModel);
+      expect(typeof validators.create).toBe("function");
+      expect(typeof validators.update).toBe("function");
+    });
+
+    it("create validator rejects body with wrong type", () => {
+      configureOpenApiValidator({coerceTypes: false});
+      const {create} = createModelValidators(RequiredModel);
+
+      const req = {body: {name: 123}, method: "POST", path: "/required"} as any;
+      const res = {} as any;
+      expect(() => {
+        create(req, res, () => {});
+      }).toThrow();
+    });
+
+    it("update validator allows a partial body", () => {
+      const {update} = createModelValidators(RequiredModel);
+
+      let nextCalled = false;
+      const req = {body: {about: "info"}, method: "PATCH", path: "/required"} as any;
+      const res = {} as any;
+      update(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+    });
+
+    it("supports onAdditionalPropertiesRemoved option", () => {
+      configureOpenApiValidator({removeAdditional: true});
+      const removedProps: string[] = [];
+      const {create} = createModelValidators(RequiredModel, {
+        onAdditionalPropertiesRemoved: (props) => {
+          removedProps.push(...props);
+        },
+      });
+
+      // Extra property gets stripped and hook is called
+      const req = {
+        body: {extra: "strip me", name: "Apple"},
+        method: "POST",
+        path: "/required",
+      } as any;
+      create(req, {} as any, () => {});
+      expect(removedProps).toContain("extra");
+    });
+
+    it("supports onError option", () => {
+      configureOpenApiValidator({coerceTypes: false});
+      let errorHandled: any[] = [];
+      const {create} = createModelValidators(RequiredModel, {
+        onError: (errors) => {
+          errorHandled = errors;
+        },
+      });
+
+      // Wrong type triggers error handler
+      const req = {body: {name: 42}, method: "POST", path: "/required"} as any;
+      create(req, {} as any, () => {});
+      expect(errorHandled.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("validateModelRequestBody", () => {
+    beforeEach(() => {
+      configureOpenApiValidator();
+    });
+
+    it("creates a validator from a Mongoose model", () => {
+      const middleware = validateModelRequestBody(RequiredModel);
+
+      const req = {body: {}, method: "POST", path: "/required"} as any;
+      const res = {} as any;
+      expect(() => {
+        middleware(req, res, () => {});
+      }).toThrow();
+    });
+
+    it("respects excludeFields option", () => {
+      const middleware = validateModelRequestBody(RequiredModel, {
+        excludeFields: ["name"],
+      });
+
+      // Without 'name' required, empty body passes
+      let nextCalled = false;
+      const req = {body: {}, method: "POST", path: "/required"} as any;
+      const res = {} as any;
+      middleware(req, res, () => {
+        nextCalled = true;
+      });
+
+      expect(nextCalled).toBe(true);
+    });
+  });
+
+  describe("getSchemaFromModel", () => {
+    it("returns properties for a Mongoose model", () => {
+      const schema = getSchemaFromModel(RequiredModel);
+      expect(schema.name).toBeDefined();
+      expect(schema.about).toBeDefined();
+    });
+  });
+
+  describe("getOpenApiValidatorConfig", () => {
+    it("returns a shallow copy of the config", () => {
+      configureOpenApiValidator({removeAdditional: false});
+      const config = getOpenApiValidatorConfig();
+      expect(config.removeAdditional).toBe(false);
+
+      // Mutating the returned copy should not affect internal state
+      (config as any).removeAdditional = true;
+      expect(getOpenApiValidatorConfig().removeAdditional).toBe(false);
+    });
   });
 });

package/src/plugins.ts

@@ -15,10 +15,12 @@ export interface BaseUser {
   email: string;
 }
 
-export function baseUserPlugin(schema: Schema<any, any, any, any>) {
-  schema.add({admin: {default: false, type: Boolean}});
-  schema.add({email: {index: true, type: String}});
-}
+export const baseUserPlugin = (schema: Schema<any, any, any, any>): void => {
+  schema.add({
+    admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
+  });
+  schema.add({email: {description: "The user's email address", index: true, type: String}});
+};
 
 /** For models with the isDeletedPlugin, extend this interface to add the appropriate fields. */
 export interface IsDeleted {
@@ -26,7 +28,7 @@ export interface IsDeleted {
   deleted: boolean;
 }
 
-export function isDeletedPlugin(schema: Schema<any, any, any, any>, defaultValue = false) {
+export const isDeletedPlugin = (schema: Schema<any, any, any, any>, defaultValue = false): void => {
   schema.add({
     deleted: {
       default: defaultValue,
@@ -37,21 +39,24 @@ export function isDeletedPlugin(schema: Schema<any, any, any, any>, defaultValue
       type: Boolean,
     },
   });
-  function applyDeleteFilter(q: Query<any, any>) {
+  const applyDeleteFilter = (q: Query<any, any>): void => {
     const query = q.getQuery();
     if (query && query.deleted === undefined) {
       void q.where({deleted: {$ne: true}});
     }
-  }
+  };
   schema.pre("find", function () {
     applyDeleteFilter(this);
   });
   schema.pre("findOne", function () {
     applyDeleteFilter(this);
   });
-}
+};
 
-export function isDisabledPlugin(schema: Schema<any, any, any, any>, defaultValue = false) {
+export const isDisabledPlugin = (
+  schema: Schema<any, any, any, any>,
+  defaultValue = false
+): void => {
   schema.add({
     disabled: {
       default: defaultValue,
@@ -60,16 +65,18 @@ export function isDisabledPlugin(schema: Schema<any, any, any, any>, defaultValu
       type: Boolean,
     },
   });
-}
+};
 
 export interface CreatedDeleted {
   updated: {type: Date; required: true};
   created: {type: Date; required: true};
 }
 
-export function createdUpdatedPlugin(schema: Schema<any, any, any, any>) {
-  schema.add({updated: {index: true, type: Date}});
-  schema.add({created: {index: true, type: Date}});
+export const createdUpdatedPlugin = (schema: Schema<any, any, any, any>): void => {
+  schema.add({
+    updated: {description: "When this document was last updated", index: true, type: Date},
+  });
+  schema.add({created: {description: "When this document was created", index: true, type: Date}});
 
   schema.pre("save", function () {
     if (this.disableCreatedUpdatedPlugin === true) {
@@ -86,11 +93,13 @@ export function createdUpdatedPlugin(schema: Schema<any, any, any, any>) {
   schema.pre(/save|updateOne|insertMany/, function () {
     void this.updateOne({}, {$set: {updated: new Date()}});
   });
-}
+};
 
-export function firebaseJWTPlugin(schema: Schema) {
-  schema.add({firebaseId: {index: true, type: String}});
-}
+export const firebaseJWTPlugin = (schema: Schema): void => {
+  schema.add({
+    firebaseId: {description: "The user's Firebase authentication ID", index: true, type: String},
+  });
+};
 
 /**
  * This adds a static method `Model.findOneOrNone` to the schema. This should replace `Model.findOne` in most instances.
@@ -99,7 +108,7 @@ export function firebaseJWTPlugin(schema: Schema) {
  * document, or throws an exception if multiple are found.
  * @param schema Mongoose Schema
  */
-export function findOneOrNone<T>(schema: Schema<T>) {
+export const findOneOrNone = <T>(schema: Schema<T>): void => {
   schema.statics.findOneOrNone = async function (
     query: Record<string, any>,
     errorArgs?: Partial<APIErrorConstructor>
@@ -118,7 +127,7 @@ export function findOneOrNone<T>(schema: Schema<T>) {
     }
     return results[0];
   };
-}
+};
 
 /**
  * This adds a static method `Model.findExactlyOne` to the schema. This or findOneOrNone should replace `Model.findOne`
@@ -128,7 +137,7 @@ export function findOneOrNone<T>(schema: Schema<T>) {
  * multiple or none are found.
  * @param schema Mongoose Schema
  */
-export function findExactlyOne<T>(schema: Schema<T>) {
+export const findExactlyOne = <T>(schema: Schema<T>): void => {
   schema.statics.findExactlyOne = async function (
     query: Record<string, any>,
     errorArgs?: Partial<APIErrorConstructor>
@@ -152,7 +161,7 @@ export function findExactlyOne<T>(schema: Schema<T>) {
     }
     return results[0];
   };
-}
+};
 
 /**
  * This adds a static method `Model.upsert` to the schema. This method will either update an existing document
@@ -160,7 +169,7 @@ export function findExactlyOne<T>(schema: Schema<T>) {
  * match the conditions to prevent ambiguous updates.
  * @param schema Mongoose Schema
  */
-export function upsertPlugin<T>(schema: Schema<any, any, any, any>) {
+export const upsertPlugin = <T>(schema: Schema<any, any, any, any>): void => {
   schema.statics.upsert = async function (
     conditions: Record<string, any>,
     update: Record<string, any>
@@ -187,7 +196,7 @@ export function upsertPlugin<T>(schema: Schema<any, any, any, any>) {
     const newDoc = new this(combinedData);
     return newDoc.save();
   };
-}
+};
 
 /** For models with the upsertPlugin, extend this interface to add the upsert static method. */
 export interface HasUpsert<T> {

package/src/populate.test.ts

@@ -1,7 +1,8 @@
 import {beforeEach, describe, expect, it} from "bun:test";
+import mongoose, {Schema} from "mongoose";
 
-import {unpopulate} from "./populate";
-import {FoodModel, setupDb} from "./tests";
+import {fixMixedFields, getOpenApiSpecForModel, unpopulate} from "./populate";
+import {FoodModel, setupDb, UserModel} from "./tests";
 
 describe("populate functions", () => {
   let admin: any;
@@ -121,3 +122,78 @@ describe("unpopulate edge cases", () => {
     expect(result.containers[1].items).toEqual(["item-3", "item-4"]);
   });
 });
+
+describe("fixMixedFields", () => {
+  it("returns early when schema is missing", () => {
+    const properties = {foo: {type: "object"}};
+    expect(() => fixMixedFields(null, properties)).not.toThrow();
+  });
+
+  it("returns early when properties is missing", () => {
+    const schema = new Schema({});
+    expect(() => fixMixedFields(schema, null as any)).not.toThrow();
+  });
+
+  it("replaces Mixed fields with only description", () => {
+    const schema = new Schema({data: {description: "any data", type: Schema.Types.Mixed}});
+    const properties: any = {data: {description: "any data", type: "object"}};
+    fixMixedFields(schema, properties);
+    expect(properties.data).toEqual({description: "any data"});
+  });
+
+  it("recurses into arrays of sub-documents", () => {
+    const subSchema = new Schema({meta: {type: Schema.Types.Mixed}});
+    const schema = new Schema({items: [subSchema]});
+    const properties: any = {
+      items: {
+        items: {
+          properties: {
+            meta: {type: "object"},
+          },
+        },
+        type: "array",
+      },
+    };
+    fixMixedFields(schema, properties);
+    expect(properties.items.items.properties.meta).toEqual({description: undefined});
+  });
+
+  it("skips unknown paths", () => {
+    const schema = new Schema({foo: String});
+    const properties = {unknownKey: {type: "string"}};
+    expect(() => fixMixedFields(schema, properties)).not.toThrow();
+  });
+});
+
+describe("getOpenApiSpecForModel edge cases", () => {
+  it("returns model properties without populatePaths", () => {
+    const result = getOpenApiSpecForModel(UserModel);
+    expect(result.properties).toBeDefined();
+  });
+
+  it("returns with extraModelProperties merged", () => {
+    const result = getOpenApiSpecForModel(UserModel, {
+      extraModelProperties: {customField: {type: "string"}},
+    });
+    expect(result.properties.customField).toEqual({type: "string"});
+  });
+
+  it("skips populate paths without ref", () => {
+    // Create a schema with a non-referenced ObjectId field
+    const testSchema = new Schema({name: String, simpleId: Schema.Types.ObjectId});
+    const TestModelNoRef =
+      mongoose.models.TestModelNoRef || mongoose.model("TestModelNoRef", testSchema);
+    const result = getOpenApiSpecForModel(TestModelNoRef, {
+      populatePaths: [{path: "simpleId"}],
+    });
+    // Should not throw, simpleId stays as-is
+    expect(result.properties).toBeDefined();
+  });
+
+  it("populates with fields allowlist", () => {
+    const result = getOpenApiSpecForModel(FoodModel, {
+      populatePaths: [{fields: ["name"], path: "ownerId"}],
+    });
+    expect(result.properties).toBeDefined();
+  });
+});