Model

A Mongster model is the typed entry point for one collection. It combines a collection name with a schema and exposes CRUD, aggregation, hooks, and index management.

import { M, model, mongster } from "mongster";

const userSchema = M.schema({
  email: M.string().uniqueIndex(),
  name: M.string().min(1),
}).withTimestamps();

const User = model("users", userSchema);

const auditSchema = M.schema({
  action: M.string(),
  at: M.date().defaultFn(() => new Date()),
});

const AuditLog = mongster.model("audit_logs", auditSchema);

await User.syncIndexes({ autoDrop: false });

const collectionName = User.getCollectionName();
const rawCollection = User.getCollection();

Ways to create a model

• model(name, schema) uses the default exported mongster client.
• mongster.model(name, schema) is the same idea, but more explicit.
• client.model(name, schema) is for custom MongsterClient instances.

The shape of the API

• Create: insertOne, insertMany, createOne, createMany
• Read: find, findOne, findById, count, estimatedCount, distinct
• Update: updateOne, updateMany, findOneAndUpdate, replaceOne, findOneAndReplace, upsertOne
• Delete: deleteOne, deleteMany, findOneAndDelete
• Extra: aggregate, aggregateRaw, bulkWrite, syncIndexes, pre, post

insert* vs create*

Use insertOne and insertMany when you want MongoDB's raw write result. Use createOne and createMany when you want the created documents back.

Common write operations

replaceOne and friends

replaceOne, findOneAndReplace, findOneAndUpdate, and findOneAndDelete all run through the schema and return a typed result.

import { Todo } from "./models";
const todoId = new ObjectId();

await Todo.replaceOne(
  { _id: todoId },
  { title: "Rewrite the docs", completed: false },
);

const updated = await Todo.findOneAndUpdate(
  { _id: todoId },
  { $set: { completed: true } },
  { includeResultMetadata: true },
);

await Todo.findOneAndDelete({ _id: todoId }, { includeResultMetadata: true });

[!NOTE] findOneAndUpdate, findOneAndReplace, and findOneAndDelete require includeResultMetadata: true in options for the typed return shape. The MongoDB driver enforces this for typed return values.

upsertOne

upsertOne(filter, doc) parses the document with the schema and routes the body into $set plus $setOnInsert: { _id }. Use it when you have a natural unique key and want a single round trip.

await User.upsertOne(
  { email: "alice@example.com" },
  { email: "alice@example.com", name: "Alice" },
);

bulkWrite

bulkWrite(operations, options) forwards an array of write operations to the driver. Mongster triggers syncIndexes() for the model before the call if it has not run yet, and fires the bulkWrite hook with the operations array.

await Todo.bulkWrite([
  { updateOne: { filter: { _id: id }, update: { $set: { completed: true } } } },
  { deleteOne: { filter: { completed: true } } },
]);

For typed aggregations, see the Aggregation guide and the Aggregate API.

Transaction-scoped models

Inside mongster.transaction(), call ctx.use(Model) to get a transaction-scoped model with the same surface area and the session already injected.