@terreno/api 0.0.11-beta.1 → 0.0.11

package/src/api.ts

@@ -241,6 +241,16 @@ export interface ModelRouterOptions<T> {
     request: express.Request,
     options: ModelRouterOptions<T>
   ) => Promise<JSONValue>;
+  /**
+   * The discriminatorKey that you passed when creating the Mongoose models. Defaults to __t. See:
+   * https://mongoosejs.com/docs/discriminators.html If this key is provided,
+   * you must provide the same key as part of the top level of the body when making performing
+   * update or delete operations on this model.
+   *    \{discriminatorKey: "__t"\}
+   *
+   *     PATCH \{__t: "SuperUser", name: "Foo"\} // __t is required or there will be a 404 error.
+   */
+  discriminatorKey?: string;
   /**
    * The OpenAPI generator for this server. This is used to generate the OpenAPI documentation.
    */
@@ -265,6 +275,23 @@ export interface ModelRouterOptions<T> {
   openApiExtraModelProperties?: any;
 }
 
+// A function to decide which model to use. If no discriminators are provided,
+// just returns the base model. If
+export function getModel(baseModel: Model<any>, body?: any, options?: ModelRouterOptions<any>) {
+  const discriminatorKey = options?.discriminatorKey ?? "__t";
+  const modelName = body?.[discriminatorKey];
+  if (!modelName) {
+    return baseModel;
+  }
+  const model = baseModel.discriminators?.[modelName];
+  if (!model) {
+    throw new Error(
+      `Could not find discriminator model for key ${modelName}, baseModel: ${baseModel}`
+    );
+  }
+  return model;
+}
+
 // Ensures query params are allowed. Also checks nested query params when using $and/$or.
 function checkQueryParamAllowed(
   queryParam: string,
@@ -310,12 +337,15 @@ function checkQueryParamAllowed(
 // }
 
 /**
- * Create a set of CRUD routes given a Mongoose model and configuration options.
+ * Create a set of CRUD routes given a Mongoose model $baseModel and configuration options.
  *
- * @param model A Mongoose Model
+ * @param baseModel A Mongoose Model
  * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
  */
-export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router {
+export function modelRouter<T>(
+  baseModel: Model<T>,
+  options: ModelRouterOptions<T>
+): express.Router {
   const router = express.Router();
 
   // Do before the other router options so endpoints take priority.
@@ -329,10 +359,12 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
     "/",
     [
       authenticateMiddleware(options.allowAnonymous),
-      createOpenApiMiddleware(model, options),
-      permissionMiddleware(model, options),
+      createOpenApiMiddleware(baseModel, options),
+      permissionMiddleware(baseModel, options),
     ],
     asyncHandler(async (req: Request, res: Response) => {
+      const model = getModel(baseModel, req.body?.__t, options);
+
       let body: Partial<T> | (Partial<T> | undefined)[] | null | undefined;
       try {
         body = transform<T>(options, req.body, "create", req.user);
@@ -394,7 +426,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
 
       if (options.populatePaths) {
         try {
-          let populateQuery: any = model.findById(data._id);
+          let populateQuery = model.findById(data._id);
           populateQuery = addPopulateToQuery(populateQuery, options.populatePaths);
           data = await populateQuery.exec();
         } catch (error: any) {
@@ -437,10 +469,13 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
     "/",
     [
       authenticateMiddleware(options.allowAnonymous),
-      permissionMiddleware(model, options),
-      listOpenApiMiddleware(model, options),
+      permissionMiddleware(baseModel, options),
+      listOpenApiMiddleware(baseModel, options),
     ],
     asyncHandler(async (req: Request, res: Response) => {
+      // For pure read queries, Mongoose will return the correct data with just the base model.
+      const model = baseModel;
+
       let query: any = {};
       for (const queryParam of Object.keys(options.defaultQueryParams ?? [])) {
         query[queryParam] = options.defaultQueryParams?.[queryParam];
@@ -589,8 +624,8 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
     "/:id",
     [
       authenticateMiddleware(options.allowAnonymous),
-      getOpenApiMiddleware(model, options),
-      permissionMiddleware(model, options),
+      getOpenApiMiddleware(baseModel, options),
+      permissionMiddleware(baseModel, options),
     ],
     asyncHandler(async (req: Request, res: Response) => {
       const data: mongoose.Document & T = (req as any).obj;
@@ -623,10 +658,12 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
     "/:id",
     [
       authenticateMiddleware(options.allowAnonymous),
-      patchOpenApiMiddleware(model, options),
-      permissionMiddleware(model, options),
+      patchOpenApiMiddleware(baseModel, options),
+      permissionMiddleware(baseModel, options),
     ],
     asyncHandler(async (req: Request, res: Response) => {
+      const model = getModel(baseModel, req.body, options);
+
       let doc: mongoose.Document & T = (req as any).obj;
 
       let body;
@@ -694,7 +731,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
       }
 
       if (options.populatePaths) {
-        let populateQuery: any = model.findById(doc._id);
+        let populateQuery = model.findById(doc._id);
         populateQuery = addPopulateToQuery(populateQuery, options.populatePaths);
         doc = await populateQuery.exec();
       }
@@ -729,10 +766,12 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
     "/:id",
     [
       authenticateMiddleware(options.allowAnonymous),
-      deleteOpenApiMiddleware(model, options),
-      permissionMiddleware(model, options),
+      deleteOpenApiMiddleware(baseModel, options),
+      permissionMiddleware(baseModel, options),
     ],
     asyncHandler(async (req: Request, res: Response) => {
+      const model = getModel(baseModel, req.body, options);
+
       const doc: mongoose.Document & T & {deleted?: boolean} = (req as any).obj;
 
       if (options.preDelete) {
@@ -810,6 +849,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
     operation: "POST" | "PATCH" | "DELETE"
   ) {
     // TODO Combine array operations and .patch(), as they are very similar.
+    const model = getModel(baseModel, req.body, options);
 
     if (!(await checkPermissions("update", options.permissions.update, req.user))) {
       throw new APIError({
@@ -821,7 +861,9 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
     const doc = await model.findById(req.params.id);
     // Make a copy for passing pre-saved values to hooks.
     const prevDoc = cloneDeep(doc);
-    if (!doc) {
+    // We fail here because we might fetch the document without the __t but we'd be missing all the
+    // hooks.
+    if (!doc || (doc.__t && !req.body.__t)) {
       throw new APIError({
         status: 404,
         title: `Could not find document to PATCH: ${req.params.id}`,
@@ -937,7 +979,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
 
     if (options.postUpdate) {
       try {
-        await options.postUpdate(doc as any, body, req, prevDoc as any);
+        await options.postUpdate(doc, body, req, prevDoc);
       } catch (error: any) {
         throw new APIError({
           disableExternalErrorTracking: getDisableExternalErrorTracking(error),
@@ -947,7 +989,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
         });
       }
     }
-    return res.json({data: serialize<T>(req, options, doc as any)});
+    return res.json({data: serialize<T>(req, options, doc)});
   }
 
   async function arrayPost(req: Request, res: Response) {
@@ -962,7 +1004,7 @@ export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
     return arrayOperation(req, res, "DELETE");
   }
   // Set up routes for managing array fields. Check if there any array fields to add this for.
-  if (Object.values(model.schema.paths).find((config: any) => config.instance === "Array")) {
+  if (Object.values(baseModel.schema.paths).find((config: any) => config.instance === "Array")) {
     router.post(
       "/:id/:field",
       authenticateMiddleware(options.allowAnonymous),

package/src/permissions.ts

@@ -4,7 +4,7 @@ import type express from "express";
 import type {NextFunction} from "express";
 import mongoose, {type Model} from "mongoose";
 
-import {addPopulateToQuery, type ModelRouterOptions, type RESTMethod} from "./api";
+import {addPopulateToQuery, getModel, type ModelRouterOptions, type RESTMethod} from "./api";
 import type {User} from "./auth";
 import {APIError} from "./errors";
 import {logger} from "./logger";
@@ -101,8 +101,8 @@ export async function checkPermissions<T>(
 // finds the relevant object, checks the permissions, and attaches the object to the request as
 // req.obj.
 export function permissionMiddleware<T>(
-  model: Model<T>,
-  options: Pick<ModelRouterOptions<T>, "permissions" | "populatePaths">
+  baseModel: Model<T>,
+  options: Pick<ModelRouterOptions<T>, "permissions" | "populatePaths" | "discriminatorKey">
 ) {
   return async (req: express.Request, _res: express.Response, next: NextFunction) => {
     if (req.method === "OPTIONS") {
@@ -131,6 +131,8 @@ export function permissionMiddleware<T>(
         });
       }
 
+      const model = getModel(baseModel, req.body, options);
+
       // All methods check for permissions.
       if (!(await checkPermissions(method, options.permissions[method], req.user))) {
         throw new APIError({
@@ -157,7 +159,15 @@ export function permissionMiddleware<T>(
           title: `GET failed on ${req.params.id}`,
         });
       }
-      if (!data) {
+      if (!data || (["update", "delete"].includes(method) && data?.__t && !req.body?.__t)) {
+        // For discriminated models, return 404 without checking hidden state
+        if (["update", "delete"].includes(method) && data?.__t && !req.body?.__t) {
+          throw new APIError({
+            status: 404,
+            title: `Document ${req.params.id} not found for model ${model.modelName}`,
+          });
+        }
+
         // Check if document exists but is hidden. Completely skip plugins.
         const hiddenDoc = await model.collection.findOne({
           _id: new mongoose.Types.ObjectId(req.params.id),

package/src/utils.test.ts

@@ -1,194 +1,14 @@
-import {describe, expect, it, spyOn} from "bun:test";
-import mongoose from "mongoose";
+import {describe, expect, it} from "bun:test";
 
-import {checkModelsStrict, isValidObjectId} from "./utils";
+import {isValidObjectId} from "./utils";
 
 describe("utils", () => {
-  describe("isValidObjectId", () => {
-    it("checks valid ObjectIds", () => {
-      expect(isValidObjectId("62c44da0003d9f8ee8cc925c")).toBe(true);
-      expect(isValidObjectId("620000000000000000000000")).toBe(true);
-      // Mongoose's builtin "ObjectId.isValid" will falsely say this is an ObjectId.
-      expect(isValidObjectId("1234567890ab")).toBe(false);
-      expect(isValidObjectId("microsoft123")).toBe(false);
-      expect(isValidObjectId("62c44da0003d9f8ee8cc925x")).toBe(false);
-    });
-  });
-
-  describe("checkModelsStrict", () => {
-    it("throws error when toObject.virtuals is not true", () => {
-      // Create a schema without toObject.virtuals
-      const testSchema = new mongoose.Schema({name: String});
-      testSchema.set("strict", "throw");
-      // Not setting toObject.virtuals
-
-      if (mongoose.models.ToObjectTestModel) {
-        delete mongoose.models.ToObjectTestModel;
-      }
-      mongoose.model("ToObjectTestModel", testSchema);
-
-      try {
-        // This should throw because ToObjectTestModel doesn't have toObject.virtuals
-        expect(() => checkModelsStrict()).toThrow("toObject.virtuals not set to true");
-      } finally {
-        delete mongoose.models.ToObjectTestModel;
-      }
-    });
-
-    it("throws error when toJSON.virtuals is not true", () => {
-      // Create a schema with toObject.virtuals but without toJSON.virtuals
-      const testSchema = new mongoose.Schema({name: String});
-      testSchema.set("toObject", {virtuals: true});
-      testSchema.set("strict", "throw");
-      // Not setting toJSON.virtuals
-
-      if (mongoose.models.ToJsonTestModel) {
-        delete mongoose.models.ToJsonTestModel;
-      }
-      mongoose.model("ToJsonTestModel", testSchema);
-
-      // Use spyOn to intercept modelNames and return only our test model
-      const spy = spyOn(mongoose, "modelNames").mockReturnValue(["ToJsonTestModel"]);
-
-      try {
-        expect(() => checkModelsStrict()).toThrow("toJSON.virtuals not set to true");
-      } finally {
-        spy.mockRestore();
-        delete mongoose.models.ToJsonTestModel;
-      }
-    });
-
-    it("throws error when strict mode is not set to throw", () => {
-      // Create a schema with virtuals but without strict mode
-      const testSchema = new mongoose.Schema({name: String});
-      testSchema.set("toObject", {virtuals: true});
-      testSchema.set("toJSON", {virtuals: true});
-      // Not setting strict to "throw"
-
-      if (mongoose.models.StrictTestModel) {
-        delete mongoose.models.StrictTestModel;
-      }
-      mongoose.model("StrictTestModel", testSchema);
-
-      const spy = spyOn(mongoose, "modelNames").mockReturnValue(["StrictTestModel"]);
-
-      try {
-        expect(() => checkModelsStrict()).toThrow("is not set to strict mode");
-      } finally {
-        spy.mockRestore();
-        delete mongoose.models.StrictTestModel;
-      }
-    });
-
-    it("passes when all checks pass", () => {
-      // Create a properly configured schema
-      const testSchema = new mongoose.Schema({name: String});
-      testSchema.set("toObject", {virtuals: true});
-      testSchema.set("toJSON", {virtuals: true});
-      testSchema.set("strict", "throw");
-
-      if (mongoose.models.GoodTestModel) {
-        delete mongoose.models.GoodTestModel;
-      }
-      mongoose.model("GoodTestModel", testSchema);
-
-      const spy = spyOn(mongoose, "modelNames").mockReturnValue(["GoodTestModel"]);
-
-      try {
-        expect(() => checkModelsStrict()).not.toThrow();
-      } finally {
-        spy.mockRestore();
-        delete mongoose.models.GoodTestModel;
-      }
-    });
-
-    it("skips strict mode check for ignored models", () => {
-      // Create a properly configured model
-      const goodSchema = new mongoose.Schema({name: String});
-      goodSchema.set("toObject", {virtuals: true});
-      goodSchema.set("toJSON", {virtuals: true});
-      goodSchema.set("strict", "throw");
-
-      if (mongoose.models.GoodModel) {
-        delete mongoose.models.GoodModel;
-      }
-      mongoose.model("GoodModel", goodSchema);
-
-      // Create a model without strict mode that we'll ignore
-      const badSchema = new mongoose.Schema({name: String});
-      badSchema.set("toObject", {virtuals: true});
-      badSchema.set("toJSON", {virtuals: true});
-      // Not setting strict - should fail unless ignored
-
-      if (mongoose.models.IgnoredModel) {
-        delete mongoose.models.IgnoredModel;
-      }
-      mongoose.model("IgnoredModel", badSchema);
-
-      const spy = spyOn(mongoose, "modelNames").mockReturnValue(["GoodModel", "IgnoredModel"]);
-
-      try {
-        // Without ignoring, should throw for IgnoredModel
-        expect(() => checkModelsStrict()).toThrow("is not set to strict mode");
-
-        // With ignoring IgnoredModel, should pass
-        expect(() => checkModelsStrict(["IgnoredModel"])).not.toThrow();
-      } finally {
-        spy.mockRestore();
-        delete mongoose.models.GoodModel;
-        delete mongoose.models.IgnoredModel;
-      }
-    });
-
-    it("handles multiple models and validates all", () => {
-      // Create three properly configured models
-      const schema1 = new mongoose.Schema({name: String});
-      schema1.set("toObject", {virtuals: true});
-      schema1.set("toJSON", {virtuals: true});
-      schema1.set("strict", "throw");
-
-      const schema2 = new mongoose.Schema({value: Number});
-      schema2.set("toObject", {virtuals: true});
-      schema2.set("toJSON", {virtuals: true});
-      schema2.set("strict", "throw");
-
-      const schema3 = new mongoose.Schema({active: Boolean});
-      schema3.set("toObject", {virtuals: true});
-      schema3.set("toJSON", {virtuals: true});
-      schema3.set("strict", "throw");
-
-      if (mongoose.models.MultiModel1) delete mongoose.models.MultiModel1;
-      if (mongoose.models.MultiModel2) delete mongoose.models.MultiModel2;
-      if (mongoose.models.MultiModel3) delete mongoose.models.MultiModel3;
-
-      mongoose.model("MultiModel1", schema1);
-      mongoose.model("MultiModel2", schema2);
-      mongoose.model("MultiModel3", schema3);
-
-      const spy = spyOn(mongoose, "modelNames").mockReturnValue([
-        "MultiModel1",
-        "MultiModel2",
-        "MultiModel3",
-      ]);
-
-      try {
-        expect(() => checkModelsStrict()).not.toThrow();
-      } finally {
-        spy.mockRestore();
-        delete mongoose.models.MultiModel1;
-        delete mongoose.models.MultiModel2;
-        delete mongoose.models.MultiModel3;
-      }
-    });
-
-    it("handles empty model list", () => {
-      const spy = spyOn(mongoose, "modelNames").mockReturnValue([]);
-
-      try {
-        expect(() => checkModelsStrict()).not.toThrow();
-      } finally {
-        spy.mockRestore();
-      }
-    });
+  it("checks valid ObjectIds", () => {
+    expect(isValidObjectId("62c44da0003d9f8ee8cc925c")).toBe(true);
+    expect(isValidObjectId("620000000000000000000000")).toBe(true);
+    // Mongoose's builtin "ObjectId.isValid" will falsely say this is an ObjectId.
+    expect(isValidObjectId("1234567890ab")).toBe(false);
+    expect(isValidObjectId("microsoft123")).toBe(false);
+    expect(isValidObjectId("62c44da0003d9f8ee8cc925x")).toBe(false);
   });
 });

package/CLAUDE.md

@@ -1,107 +0,0 @@
-# @terreno/api
-
-REST API framework built on Express/Mongoose, styled after Django REST Framework.
-
-## Commands
-
-```bash
-bun run compile          # Compile TypeScript
-bun run dev              # Watch mode
-bun run test             # Run tests
-bun run lint             # Lint code
-bun run lint:fix         # Fix lint issues
-```
-
-## Architecture
-
-### modelRouter
-
-Automatically creates RESTful CRUD APIs for Mongoose models with built-in permissions, population, filtering, and lifecycle hooks.
-
-```typescript
-import {modelRouter, modelRouterOptions, Permissions} from "@terreno/api";
-
-const router = modelRouter(YourModel, {
-  permissions: {
-    list: [Permissions.IsAuthenticated],
-    create: [Permissions.IsAuthenticated],
-    read: [Permissions.IsOwner],
-    update: [Permissions.IsOwner],
-    delete: [],  // Disabled
-  },
-  sort: "-created",
-  queryFields: ["_id", "type", "name"],
-});
-```
-
-### Custom Routes
-
-For non-CRUD endpoints, use the OpenAPI builder:
-
-```typescript
-import {asyncHandler, authenticateMiddleware, createOpenApiBuilder} from "@terreno/api";
-
-router.get("/yourRoute/:id", [
-  authenticateMiddleware(),
-  createOpenApiBuilder(options)
-    .withTags(["yourTag"])
-    .withSummary("Brief summary")
-    .withPathParameter("id", {type: "string"})
-    .withResponse(200, {data: {type: "object"}})
-    .build(),
-], asyncHandler(async (req, res) => {
-  return res.json({data: result});
-}));
-```
-
-## Conventions
-
-### Error Handling
-- Throw `APIError` with appropriate status codes: `throw new APIError({status: 400, title: "Message"})`
-- Services should throw user-friendly errors
-
-### Mongoose
-- Do not use `Model.findOne` - use `Model.findExactlyOne` or `Model.findOneOrThrow`
-- Define statics/methods by direct assignment: `schema.methods = {bar() {}}`
-- All model types live in `src/modelInterfaces.ts`
-
-### User Type Casting
-- In API routes: `req.user` is `UserDocument | undefined`
-- In @terreno/api callbacks: cast with `const user = u as unknown as UserDocument`
-- Never use `as any as UserDocument`
-
-### Logging
-- Use `logger.info/warn/error/debug` for permanent logs (not `console.log`)
-
-### Testing
-- Use bun test with expect for testing
-- Use existing manual mocks from `src/__mocks__/`
-- Never mock @terreno/api or models
-
-## Model Type Generation
-
-When creating/modifying Mongoose models, update `src/modelInterfaces.ts`:
-
-```typescript
-export type YourModelMethods = {
-  customMethod: (this: YourModelDocument, param: string) => Promise<void>;
-};
-
-export type YourModelStatics = DefaultStatics<YourModelDocument> & {
-  customStatic: (this: YourModelModel, param: string) => Promise<YourModelDocument>;
-};
-
-export type YourModelModel = DefaultModel<YourModelDocument> & YourModelStatics;
-export type YourModelSchema = mongoose.Schema<YourModelDocument, YourModelModel, YourModelMethods>;
-export type YourModelDocument = DefaultDoc & YourModelMethods & {
-  fieldName: string;
-};
-```
-
-## SDK Generation
-
-After modifying routes, regenerate the SDK:
-
-```bash
-bun run sdk
-```