@terreno/api 0.0.1

package/src/plugins.test.ts

@@ -0,0 +1,390 @@
+import {beforeEach, describe, expect, it, setSystemTime} from "bun:test";
+import type express from "express";
+import {type Document, type Model, model, Schema} from "mongoose";
+import supertest from "supertest";
+import type TestAgent from "supertest/lib/agent";
+import {modelRouter} from "./api";
+import {addAuthRoutes, setupAuth} from "./auth";
+import type {APIErrorConstructor} from "./errors";
+import {Permissions} from "./permissions";
+import {
+  createdUpdatedPlugin,
+  DateOnly,
+  findExactlyOne,
+  findOneOrNone,
+  type IsDeleted,
+  isDeletedPlugin,
+  upsertPlugin,
+} from "./plugins";
+import {authAsUser, getBaseServer, setupDb, UserModel} from "./tests";
+
+interface Stuff extends IsDeleted {
+  _id: string;
+  name: string;
+  ownerId: string;
+  date: Date;
+  created: Date;
+  updated?: Date;
+}
+
+interface StuffModelType extends Model<Stuff> {
+  findOneOrNone(
+    query: Record<string, any>,
+    errorArgs?: Partial<APIErrorConstructor>
+  ): Promise<(Document & Stuff) | null>;
+  findExactlyOne(
+    query: Record<string, any>,
+    errorArgs?: Partial<APIErrorConstructor>
+  ): Promise<Document & Stuff>;
+}
+
+const stuffSchema = new Schema<Stuff>({
+  date: DateOnly,
+  name: String,
+  ownerId: String,
+});
+
+stuffSchema.plugin(isDeletedPlugin);
+stuffSchema.plugin(findOneOrNone);
+stuffSchema.plugin(findExactlyOne);
+stuffSchema.plugin(upsertPlugin);
+stuffSchema.plugin(createdUpdatedPlugin);
+
+const StuffModel = model<Stuff>("Stuff", stuffSchema) as unknown as StuffModelType;
+
+describe("createdUpdate", () => {
+  it("sets created and updated on save", async () => {
+    setSystemTime(new Date("2022-12-17T03:24:00.000Z"));
+
+    const stuff = await StuffModel.create({name: "Things", ownerId: "123"});
+    expect(stuff.created).not.toBeNull();
+    expect(stuff.updated).not.toBeNull();
+    expect(stuff.created.toISOString()).toBe("2022-12-17T03:24:00.000Z");
+    expect(stuff.updated?.toISOString()).toBe("2022-12-17T03:24:00.000Z");
+
+    stuff.name = "Thangs";
+    // Advance time by 10 seconds
+    setSystemTime(new Date("2022-12-17T03:24:10.000Z"));
+    await stuff.save();
+    expect(stuff.created.toISOString()).toBe("2022-12-17T03:24:00.000Z");
+    expect(stuff.updated && stuff.updated > stuff.created).toBe(true);
+    setSystemTime();
+  });
+});
+
+describe("isDeleted", () => {
+  beforeEach(async () => {
+    await StuffModel.deleteMany({});
+    await Promise.all([
+      StuffModel.create({
+        deleted: true,
+        name: "Things",
+        ownerId: "123",
+      }),
+      StuffModel.create({
+        name: "StuffNThings",
+        ownerId: "123",
+      }),
+    ]);
+  });
+
+  it('filters out deleted documents from "find"', async () => {
+    let stuff = await StuffModel.find({});
+    expect(stuff).toHaveLength(1);
+    expect(stuff[0].name).toBe("StuffNThings");
+    // Providing deleted in query should return deleted documents:
+    stuff = await StuffModel.find({deleted: true});
+    expect(stuff).toHaveLength(1);
+    expect(stuff[0].name).toBe("Things");
+  });
+
+  it('filters out deleted documents from "findOne"', async () => {
+    let stuff = await StuffModel.findOne({});
+    expect(stuff?.name).toBe("StuffNThings");
+    // Providing deleted in query should return deleted document:
+    stuff = await StuffModel.findOne({deleted: true});
+    expect(stuff?.name).toBe("Things");
+  });
+});
+
+describe("findOneOrNone", () => {
+  let things: any;
+
+  beforeEach(async () => {
+    await StuffModel.deleteMany({});
+    await setupDb();
+
+    [things] = await Promise.all([
+      StuffModel.create({
+        name: "Things",
+        ownerId: "123",
+      }),
+      StuffModel.create({
+        name: "StuffNThings",
+        ownerId: "123",
+      }),
+    ]);
+  });
+
+  it("returns null with no matches.", async () => {
+    const result = await StuffModel.findOneOrNone({name: "OtherStuff"});
+    expect(result).toBeNull();
+  });
+
+  it("returns a single match", async () => {
+    const result = await StuffModel.findOneOrNone({name: "Things"});
+    expect(result).not.toBeNull();
+    expect(result?._id.toString()).toBe(things._id.toString());
+  });
+
+  it("throws error with two matches.", async () => {
+    const fn = () => StuffModel.findOneOrNone({ownerId: "123"});
+    await expect(fn()).rejects.toThrow(/Stuff\.findOne query returned multiple documents/);
+  });
+
+  it("throws custom error with two matches.", async () => {
+    const fn = () => StuffModel.findOneOrNone({ownerId: "123"}, {status: 400, title: "Oh no!"});
+
+    try {
+      await fn();
+      // If the promise doesn't reject, the test should fail
+      throw new Error("Expected promise to reject");
+    } catch (error: any) {
+      // Check if the error has title and status properties
+      expect(error.title).toBe("Oh no!");
+      expect(error.status).toBe(400);
+      expect(error.detail).toBe('query: {"ownerId":"123"}');
+    }
+  });
+});
+
+describe("findExactlyOne", () => {
+  let things: any;
+
+  beforeEach(async () => {
+    await StuffModel.deleteMany({});
+    await setupDb();
+
+    [things] = await Promise.all([
+      StuffModel.create({
+        name: "Things",
+        ownerId: "123",
+      }),
+      StuffModel.create({
+        name: "StuffNThings",
+        ownerId: "123",
+      }),
+    ]);
+  });
+
+  it("throws error with no matches.", async () => {
+    const fn = () => StuffModel.findExactlyOne({name: "OtherStuff"});
+    await expect(fn()).rejects.toThrow(/Stuff\.findExactlyOne query returned no documents/);
+  });
+
+  it("returns a single match", async () => {
+    const result = await StuffModel.findExactlyOne({name: "Things"});
+    expect(result._id.toString()).toBe(things._id.toString());
+  });
+
+  it("throws error with two matches.", async () => {
+    const fn = () => StuffModel.findExactlyOne({ownerId: "123"});
+    await expect(fn()).rejects.toThrow(/Stuff\.findExactlyOne query returned multiple documents/);
+  });
+
+  it("throws custom error with two matches.", async () => {
+    const fn = () => StuffModel.findExactlyOne({ownerId: "123"}, {status: 400, title: "Oh no!"});
+
+    try {
+      await fn();
+      // If the promise doesn't reject, the test should fail
+      throw new Error("Expected promise to reject");
+    } catch (error: any) {
+      // Check if the error has title and status properties
+      expect(error.title).toBe("Oh no!");
+      expect(error.status).toBe(400);
+      expect(error.detail).toBe('query: {"ownerId":"123"}');
+    }
+  });
+});
+
+describe("upsertPlugin", () => {
+  beforeEach(async () => {
+    await StuffModel.deleteMany({});
+    await setupDb();
+  });
+
+  it("creates a new document when none exists", async () => {
+    const result = await (StuffModel as any).upsert({name: "NewThing"}, {ownerId: "456"});
+    expect(result.name).toBe("NewThing");
+    expect(result.ownerId).toBe("456");
+
+    const found = await StuffModel.findOne({name: "NewThing"});
+    expect(found).not.toBeNull();
+    expect(found?.ownerId).toBe("456");
+  });
+
+  it("updates existing document when one exists", async () => {
+    const initial = await StuffModel.create({
+      name: "ExistingThing",
+      ownerId: "123",
+    });
+
+    const result = await (StuffModel as any).upsert({name: "ExistingThing"}, {ownerId: "789"});
+
+    expect(result._id.toString()).toBe(initial._id.toString());
+    expect(result.ownerId).toBe("789");
+
+    const allDocs = await StuffModel.find({name: "ExistingThing"});
+    expect(allDocs).toHaveLength(1);
+    expect(allDocs[0].ownerId).toBe("789");
+  });
+
+  it("throws error when multiple documents match conditions", async () => {
+    await Promise.all([
+      StuffModel.create({name: "Thing1", ownerId: "123"}),
+      StuffModel.create({name: "Thing2", ownerId: "123"}),
+    ]);
+
+    const fn = () => (StuffModel as any).upsert({ownerId: "123"}, {name: "Updated"});
+    await expect(fn()).rejects.toThrow(/Stuff\.upsert find query returned multiple documents/);
+  });
+
+  it("combines conditions and update data for new documents", async () => {
+    const result = await (StuffModel as any).upsert({name: "TestCondition"}, {ownerId: "999"});
+
+    expect(result.name).toBe("TestCondition");
+    expect(result.ownerId).toBe("999");
+  });
+});
+
+describe("TypeScript return types", () => {
+  let _things: any;
+
+  beforeEach(async () => {
+    await StuffModel.deleteMany({});
+    await setupDb();
+
+    [_things] = await Promise.all([
+      StuffModel.create({
+        date: new Date("2023-01-01"),
+        name: "Things",
+        ownerId: "123",
+      }),
+      StuffModel.create({
+        date: new Date("2023-01-02"),
+        name: "StuffNThings",
+        ownerId: "123",
+      }),
+    ]);
+  });
+
+  it("findOneOrNone returns properly typed document or null", async () => {
+    const result = await StuffModel.findOneOrNone({name: "Things"});
+
+    if (result) {
+      expect(typeof result._id.toString()).toBe("string");
+      expect(typeof result.name).toBe("string");
+      expect(typeof result.ownerId).toBe("string");
+      expect(result.date).toBeInstanceOf(Date);
+    } else {
+      expect(result).toBeNull();
+    }
+  });
+
+  it("findExactlyOne returns properly typed document", async () => {
+    const result = await StuffModel.findExactlyOne({name: "Things"});
+
+    expect(typeof result._id.toString()).toBe("string");
+    expect(typeof result.name).toBe("string");
+    expect(typeof result.ownerId).toBe("string");
+    expect(result.date).toBeInstanceOf(Date);
+  });
+});
+describe("DateOnly", () => {
+  it("throws error with invalid date", async () => {
+    try {
+      await StuffModel.create({
+        date: "foo" as any,
+        name: "Things",
+        ownerId: "123",
+      });
+    } catch (error: any) {
+      expect(error.message).toMatch(/Cast to DateOnly failed/);
+      return;
+    }
+    throw new Error("Expected error was not thrown");
+  });
+
+  it("adjusts date to date only", async () => {
+    const res = await StuffModel.create({
+      date: "2005-10-10T17:17:17.017Z",
+      name: "Things",
+      ownerId: "123",
+    });
+    expect(res.date.toISOString()).toBe("2005-10-10T00:00:00.000Z");
+  });
+
+  it("filter on date only", async () => {
+    await StuffModel.create({
+      date: "2000-10-10T17:17:17.017Z",
+      name: "Things",
+      ownerId: "123",
+    });
+    let found = await StuffModel.findOne({
+      date: {
+        $gte: "2000-01-01T00:00:00.000Z",
+        $lt: "2001-01-01T00:00:00.000Z",
+      },
+    });
+    expect(found?.date.toISOString()).toBe("2000-10-10T00:00:00.000Z");
+    found = await StuffModel.findOne({
+      date: {
+        $gte: "2000-01-01T12:12:12.000Z",
+        $lt: "2001-01-01T12:12:12.000Z",
+      },
+    });
+    expect(found?.date.toISOString()).toBe("2000-10-10T00:00:00.000Z");
+  });
+
+  describe("handle 404", () => {
+    let agent: TestAgent;
+    let app: express.Application;
+
+    beforeEach(async () => {
+      await setupDb();
+      app = getBaseServer();
+      setupAuth(app, UserModel as any);
+      addAuthRoutes(app, UserModel as any);
+      app.use(
+        "/stuff",
+        modelRouter(StuffModel, {
+          allowAnonymous: true,
+          permissions: {
+            create: [Permissions.IsAny],
+            delete: [Permissions.IsAny],
+            list: [Permissions.IsAny],
+            read: [Permissions.IsAny],
+            update: [Permissions.IsAny],
+          },
+        })
+      );
+      supertest(app);
+      agent = await authAsUser(app, "notAdmin");
+    });
+
+    it("returns 404 with context for hidden document", async () => {
+      const doc = await StuffModel.create({deleted: true, name: "test"});
+      const res = await agent.get(`/stuff/${doc._id}`).expect(404);
+      expect(res.body.title).toBe(`Document ${doc._id} not found for model Stuff`);
+      expect(res.body.meta).toEqual({deleted: "true"});
+    });
+
+    it("returns 404 without meta for missing document", async () => {
+      const nonExistentId = "507f1f77bcf86cd799439011";
+      const res = await agent.get(`/stuff/${nonExistentId}`).expect(404);
+      expect(res.body.title).toBe(`Document ${nonExistentId} not found for model Stuff`);
+      expect(res.body.meta).toBeUndefined();
+    });
+  });
+});

package/src/plugins.ts

@@ -0,0 +1,289 @@
+import {DateTime} from "luxon";
+import mongoose, {
+  type Document,
+  Error as MongooseError,
+  type Query,
+  type Schema,
+  SchemaType,
+  type SchemaTypeOptions,
+} from "mongoose";
+
+import {APIError, type APIErrorConstructor} from "./errors";
+
+export interface BaseUser {
+  admin: boolean;
+  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}});
+}
+
+/** For models with the isDeletedPlugin, extend this interface to add the appropriate fields. */
+export interface IsDeleted {
+  // Whether the model should be treated as deleted or not.
+  deleted: boolean;
+}
+
+export function isDeletedPlugin(schema: Schema<any, any, any, any>, defaultValue = false) {
+  schema.add({
+    deleted: {
+      default: defaultValue,
+      description:
+        "Deleted objects are not returned in any find() or findOne() by default. " +
+        "Add {deleted: true} to find them.",
+      index: true,
+      type: Boolean,
+    },
+  });
+  function applyDeleteFilter(q: Query<any, any>) {
+    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) {
+  schema.add({
+    disabled: {
+      default: defaultValue,
+      description: "When a user is set to disable, all requests will return a 401",
+      index: true,
+      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}});
+
+  schema.pre("save", function () {
+    if (this.disableCreatedUpdatedPlugin === true) {
+      return;
+    }
+    // If we aren't specifying created, use now.
+    if (!this.created) {
+      this.created = new Date();
+    }
+    // All writes change the updated time.
+    this.updated = new Date();
+  });
+
+  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}});
+}
+
+/**
+ * This adds a static method `Model.findOneOrNone` to the schema. This should replace `Model.findOne` in most instances.
+ * `Model.findOne` should only be used with a unique index, but that's not apparent from the docs. Otherwise you can wind
+ * up with a random document that matches the query. The returns either null if no document matches, the actual
+ * document, or throws an exception if multiple are found.
+ * @param schema Mongoose Schema
+ */
+export function findOneOrNone<T>(schema: Schema<T>) {
+  schema.statics.findOneOrNone = async function (
+    query: Record<string, any>,
+    errorArgs?: Partial<APIErrorConstructor>
+  ): Promise<(Document & T) | null> {
+    const results = await this.find(query);
+    if (results.length === 0) {
+      return null;
+    }
+    if (results.length > 1) {
+      throw new APIError({
+        detail: `query: ${JSON.stringify(query)}`,
+        status: 500,
+        title: `${this.modelName}.findOne query returned multiple documents`,
+        ...errorArgs,
+      });
+    }
+    return results[0];
+  };
+}
+
+/**
+ * This adds a static method `Model.findExactlyOne` to the schema. This or findOneOrNone should replace `Model.findOne`
+ * in most instances.
+ * `Model.findOne` should only be used with a unique index, but that's not apparent from the docs. Otherwise you can wind
+ * up with a random document that matches the query. The returns the one matching document, or throws an exception if
+ * multiple or none are found.
+ * @param schema Mongoose Schema
+ */
+export function findExactlyOne<T>(schema: Schema<T>) {
+  schema.statics.findExactlyOne = async function (
+    query: Record<string, any>,
+    errorArgs?: Partial<APIErrorConstructor>
+  ): Promise<Document & T> {
+    const results = await this.find(query);
+    if (results.length === 0) {
+      throw new APIError({
+        detail: `query: ${JSON.stringify(query)}`,
+        status: 404,
+        title: `${this.modelName}.findExactlyOne query returned no documents`,
+        ...errorArgs,
+      });
+    }
+    if (results.length > 1) {
+      throw new APIError({
+        detail: `query: ${JSON.stringify(query)}`,
+        status: 500,
+        title: `${this.modelName}.findExactlyOne query returned multiple documents`,
+        ...errorArgs,
+      });
+    }
+    return results[0];
+  };
+}
+
+/**
+ * This adds a static method `Model.upsert` to the schema. This method will either update an existing document
+ * that matches the conditions or create a new document if none exists. It throws an error if multiple documents
+ * match the conditions to prevent ambiguous updates.
+ * @param schema Mongoose Schema
+ */
+export function upsertPlugin<T>(schema: Schema<any, any, any, any>) {
+  schema.statics.upsert = async function (
+    conditions: Record<string, any>,
+    update: Record<string, any>
+  ): Promise<T> {
+    // Try to find the document with the given conditions.
+    const docs = await this.find(conditions);
+    if (docs.length > 1) {
+      throw new APIError({
+        detail: `query: ${JSON.stringify(conditions)}`,
+        status: 500,
+        title: `${this.modelName}.upsert find query returned multiple documents`,
+      });
+    }
+    const doc = docs[0];
+
+    if (doc) {
+      // If the document exists, update it with the provided update values.
+      Object.assign(doc, update);
+      return doc.save();
+    }
+    // If the document doesn't exist, create a new one with the combined conditions and update
+    // values.
+    const combinedData = {...conditions, ...update};
+    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> {
+  upsert(conditions: Record<string, any>, update: Record<string, any>): Promise<T>;
+}
+
+export interface FindOneOrNonePlugin<T> {
+  findOneOrNone(
+    query: Record<string, any>,
+    errorArgs?: Partial<APIErrorConstructor>
+  ): Promise<(Document & T) | null>;
+}
+
+export interface FindExactlyOnePlugin<T> {
+  findExactlyOne(
+    query: Record<string, any>,
+    errorArgs?: Partial<APIErrorConstructor>
+  ): Promise<Document & T>;
+}
+
+export class DateOnly extends SchemaType {
+  constructor(key: string, options: SchemaTypeOptions<any>) {
+    super(key, options, "DateOnly");
+  }
+
+  handleSingle(val) {
+    return this.cast(val);
+  }
+
+  $conditionalHandlers = {
+    ...(SchemaType as any).prototype.$conditionalHandlers,
+    $gt: this.handleSingle,
+    $gte: this.handleSingle,
+    $lt: this.handleSingle,
+    $lte: this.handleSingle,
+  };
+
+  // Based on castForQuery in mongoose/lib/schema/date.js
+  // When using $gt, $gte, $lt, $lte, etc, we need to cast the value to a Date
+  castForQuery($conditional, val, context): Date | undefined {
+    if ($conditional == null) {
+      return (this as any).applySetters(val, context);
+    }
+
+    const handler = this.$conditionalHandlers[$conditional];
+
+    if (!handler) {
+      throw new Error(`Can't use ${$conditional} with DateOnly.`);
+    }
+
+    return handler.call(this, val);
+  }
+
+  // When either setting a value to a DateOnly or fetching from the DB,
+  // we want to strip off the time portion.
+  cast(val: any): Date | undefined {
+    if (val instanceof Date) {
+      const date = DateTime.fromJSDate(val).toUTC().startOf("day");
+      if (!date.isValid) {
+        throw new MongooseError.CastError(
+          "DateOnly",
+          val,
+          this.path,
+          new Error("Value is not a valid date")
+        );
+      }
+      return date.toJSDate();
+    }
+    if (typeof val === "string" || typeof val === "number") {
+      const date = DateTime.fromJSDate(new Date(val)).toUTC().startOf("day");
+      if (!date.isValid) {
+        throw new MongooseError.CastError(
+          "DateOnly",
+          val,
+          this.path,
+          new Error("Value is not a valid date")
+        );
+      }
+      return date.toJSDate();
+    }
+    // Handle $gte, $lte, etc
+    if (typeof val === "object") {
+      return val;
+    }
+    throw new MongooseError.CastError(
+      "DateOnly",
+      val,
+      this.path,
+      new Error("Value is not a valid date")
+    );
+  }
+
+  get(val: any): this {
+    return (val instanceof Date ? DateTime.fromJSDate(val).startOf("day").toJSDate() : val) as any;
+  }
+}
+
+// Register DateOnly with Mongoose's Schema.Types
+(mongoose.Schema.Types as any).DateOnly = DateOnly;