Model

Models expose the collection-level API you use most often. Transaction-scoped models created through ctx.use(Model) keep the same surface, but inject a session automatically.

import { M, model } from "mongster";

const taskSchema = M.schema({
  title: M.string(),
  completed: M.boolean().default(false),
}).withTimestamps();

const Task = model("tasks", taskSchema);

await Task.createOne({ title: "Write docs" });
await Task.find({ completed: false }).limit(5);
await Task.updateOne({ title: "Write docs" }, { $set: { completed: true } });
await Task.deleteMany({ completed: true });

const stats = await Task.aggregate().match({ completed: true }).count("done").exec();

Read surface

Write surface

Cross-cutting notes:

• insertOne, insertMany, createOne, createMany, replaceOne, findOneAndReplace, upsertOne validate through schema.parse. Throws QueryError on non-array / empty-array input where applicable.
• findOneAndUpdate, findOneAndReplace, findOneAndDelete require includeResultMetadata: true in options for the typed return shape — see the Model guide.
• For the rules Mongster applies to update operators ($set, $inc, $push, ...), see the Updates guide.
• bulkWrite triggers syncIndexes() if not yet synced and fires the bulkWrite hook with the operations array.

upsertOne in detail

upsertOne(filter, doc) is sugar for updateOne(filter, parsedDoc, { upsert: true }). Mongster parses the document with the schema, removes _id from the body, and emits:

• $set for the body fields,
• $setOnInsert: { _id } when _id is present.

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

Aggregation

Extra helpers

Transaction models

Inside mongster.transaction(async (ctx) => ...), ctx.use(Model) returns a transaction model with the same CRUD and query helpers. The difference is that every operation already passes { session }.

import { Account } from "./models";

await mongster.transaction(async (ctx) => {
  const TxAccount = ctx.use(Account);
  await TxAccount.updateOne(
    { email: "alice@example.com" },
    { $inc: { balance: -50 } },
  );
});

Related references

• Queries — FindQuery and FindOneQuery.
• Aggregate — AggregateQuery.
• Schema Reference — schema-level hooks (pre / post on a schema).
• Errors — QueryError, ValidationError, IndexSyncError.