Schema Reference

This page documents the methods exposed by collection schemas (MongsterSchema) and embedded document schemas (ObjectSchema). Use it as a reference once you already know what you want to do; the Schema guide is the better starting point.

For the field-level chainers (min, max, enum, optional, validate, etc.), see the Schema Builder API.

On this page

• MongsterSchema (collection schemas)
  • getShape, addIndex, withTimestamps, pre / post, getHooks, clone, collectIndexes, parse / parseForUpdate
• ObjectSchema (embedded documents)
  • getShape / getChecks, addIndex / withTimestamps / default / defaultFn, getRootIndexes

MongsterSchema (collection schemas)

Returned by M.schema(shape).

getShape()

Returns the raw shape you passed to M.schema(...). Useful when you need to introspect a schema (for example in tooling or custom helpers).

const shape = todoSchema.getShape();
// shape: { title: StringSchema, done: BooleanSchema }

addIndex(keys, options?)

Declares a compound index. Chainable; returns a cloned schema.

const orderSchema = M.schema({
  customerId: M.objectId(),
  placedAt: M.date(),
}).addIndex({ customerId: 1, placedAt: -1 }, { unique: true });

See Indexes for the full list of options.

withTimestamps(config?)

Adds createdAt and updatedAt to the inferred document type and writes them on insert. Updates automatically append $currentDate for updatedAt, and upserts add createdAt.

const schema = M.schema({ name: M.string() }).withTimestamps({
  createdAt: "madeAt",
  updatedAt: false,
});

config accepts:

• createdAt?: boolean | string
• updatedAt?: boolean | string

Use a string to rename the field. Use false to drop the field from the inferred shape.

pre(op, fn) and post(op, fn)

Attach schema-level hooks. See Hooks for context shapes and the group aliases (save, modify, remove).

getHooks()

Returns the schema's internal HookRegistry. Useful when writing helpers that need to compose hooks across schemas.

clone()

Returns a new schema instance with the same shape, indexes, options, and hooks. Mongster calls this internally on every chain operation — withTimestamps, addIndex, and the field-level index helpers (uniqueIndex, sparseIndex, ttl, ...) all return a clone. You typically do not need to call it directly.

collectIndexes()

Recursively walks the schema (including nested M.object, M.array, M.union, and M.tuple) and returns every declared index, with nested paths rewritten to MongoDB dot notation.

const indexes = userSchema.collectIndexes();
// [
//   { key: { email: 1 }, unique: true },
//   { key: { "profile.handle": 1 }, unique: true },
// ]

This is the same data MongsterModel.syncIndexes() and MongsterClient.syncIndexes() use.

parse(value) and parseForUpdate(value, isUpsert?)

parse(value) runs full schema validation and is what createOne, insertOne, replaceOne, and similar write paths call internally. parseForUpdate(value, isUpsert?) is the looser variant used for updateOne / findOneAndUpdate; it allows partial input and validates update-operator objects.

You usually do not call these directly. They are documented here because they are part of the public type surface exported from mongster.

ObjectSchema (embedded documents)

Returned by M.object(shape). Has the same runtime methods as MongsterSchema, scoped to the embedded shape.

const addressSchema = M.object({
  street: M.string(),
  city: M.string(),
})
  .addIndex({ city: 1, street: 1 })
  .withTimestamps({ createdAt: false, updatedAt: false });

getShape() and getChecks()

getShape() returns the inner shape record. getChecks() returns the object's default-related checks (set by .default(...) or .defaultFn(...)).

addIndex(keys, options?), withTimestamps(config?), default(o), defaultFn(fn)

Mirrors the root schema versions. The resulting fields are added to the embedded document instead of the top-level collection.

getRootIndexes(path)

Internal helper used by collectIndexes on the parent schema. Re-keys the embedded schema's addIndex declarations so the keys are relative to the embedded path. You typically do not need to call this directly.