Mongoose adapter — @ascendance-hub/sapphire-mongoose

The Mongoose adapter converts a Sapphire IR (SapphireSchemaNode) into a mongoose.Schema (when the root node is an object) or a SchemaTypeDefinition (anywhere else). It is the closest match for Sapphire’s modeling style — Mongoose has a similar “schema-as-definition” surface — and is the adapter where the most modifiers survive at the DB level.

Unofficial. A community adapter — not affiliated with, sponsored, or endorsed by the Mongoose project or Automattic, Inc.

Install

npm install @ascendance-hub/sapphire-core @ascendance-hub/sapphire-mongoose mongoose

Both @ascendance-hub/sapphire-core and mongoose are peer dependencies. The package will not pull them in transitively — install them alongside.

Register the adapter

The adapter is not auto-registered. Call registerAdapter once in your application entry point — typically the same module that constructs your Sapphire instance:

import { Sapphire, registerAdapter } from '@ascendance-hub/sapphire-core'
import { toMongooseSchema } from '@ascendance-hub/sapphire-mongoose'

registerAdapter('mongoose', toMongooseSchema)

export const a = new Sapphire({ defaultAdapter: 'mongoose' })

registerAdapter is process-global. Calling it twice with the same name throws; calling it from a library is discouraged — leave it to the consuming application.

Quickstart

import mongoose from 'mongoose'
import { toMongooseSchema } from '@ascendance-hub/sapphire-mongoose'
import { a } from './sapphire'

const User = a
  .object({
    name: a.string().min(1),
    email: a.string().email().unique(),
    age: a.number().int().min(0).optional(),
  })
  .name('User')
  .timestamps()
  .index(['email'], { unique: true })

const UserSchema = User.getSchema('mongoose') as mongoose.Schema
const UserModel = mongoose.model('User', UserSchema)

field.getSchema('mongoose') is sugar for toMongooseSchema(field.toSchema()) once the adapter is registered — the latter is the explicit form when you want to skip the registry.

IR → Mongoose mapping

Every Sapphire IR kind lands somewhere in Mongoose’s SchemaTypeDefinition. The table below is exhaustive — what isn’t covered here is not part of the adapter’s surface.

Universal modifiers

These apply to every node kind unless noted:

[!WARNING] coerce() is silently dropped. Mongoose has its own cast layer that handles coercion universally (e.g. "42" → 42 for Number fields). If you need Sapphire-level coercion to run, pipe the input through safeParse before assigning to a Mongoose document.

Schema-level options

The root-level ObjectField carries schema-wide flags that translate to Mongoose SchemaOptions:

Refs

Sapphire refs resolve lazily by name:

const Post = a
  .object({
    title: a.string(),
    author: a.ref('User'),
  })
  .name('Post')

Emits { type: ObjectId, ref: 'User', required: true }. The string lands directly in Mongoose’s ref slot — Mongoose’s populate('author') then handles the lookup at query time. The adapter does not verify that a model named 'User' exists; that resolution happens when Mongoose runs the query. If you want a typed ref, use a.ref(SchemaObj) instead of the string form — the IR is identical, but the call site is typesafe against your name(...) registry.

See refs-and-relations.md for the full ref lifecycle.

.adapter('mongoose', opts) escape hatch

Values from .adapter('mongoose', { ... }) are read from node.meta.mongoose and merged into the field’s Mongoose definition last (after Sapphire-derived keys). They win on conflicts, with one exception — the blacklist:

const META_BLACKLIST = new Set(['type', 'required'])

type and required are always Sapphire-controlled; trying to override them via the escape hatch is a no-op.

Common keys:

Any other key Mongoose accepts on a SchemaTypeDefinition is honored verbatim — the adapter simply copies the entries onto the definition object.

MongooseAdapterOptions

The second argument to toMongooseSchema(node, options?):

toMongooseSchema(node, { subdocId: true })

Custom root _id

To use a custom identity (string UUID, number, etc.) instead of the auto-generated ObjectId, declare a field literally named _id in the object. Mongoose honors a declared _id path and skips the auto ObjectId:

const User = a.object({
  _id: a.string(), // custom string id — you supply it on every insert
  name: a.string(),
})
toMongooseSchema(User.toSchema()) // → Schema with a String _id, no auto ObjectId

To strip the root _id entirely (rare — capped logs, views):

toMongooseSchema(User.toSchema(), { rootId: 'none' }) // → Schema with { _id: false }

rootId: 'none' is ignored when the schema already declares its own _id field — a field you explicitly asked for is never stripped.

Limitations

[!WARNING] Tuples enforce length only at the DB level. Per-position type checking lives in safeParse — Mongoose receives [Mixed] plus a length validator. If you need per-position checks before persistence, run safeParse on the value first.

[!WARNING] Unions degrade to Mixed. No Mongoose-level validation. Pair with safeParse to get the discriminated-union check.

[!WARNING] record with non-string keys falls back to Mixed. Mongoose’s Map keys are always strings — a.record(a.number(), ...) loses key typing in the DB. The keys.kind ∈ { string, enum, literal } path uses Map correctly.

[!WARNING] nullable() is a no-op. Mongoose has no dedicated nullable flag; non-required fields accept null implicitly. If you need strict null rejection, validate via safeParse.

[!WARNING] nullable() + required differs across Sapphire and Mongoose. Sapphire treats null as a valid value when nullable: true is set. Mongoose, by default, treats null as missing for the required check. Result: a field declared as a.string().nullable() (with the default required: true) will pass Sapphire.safeParse(null) but Mongoose .validate() will reject null on the same path. If you want Mongoose to also accept null without filling, pass an explicit default: null via the escape hatch (.adapter('mongoose', { default: null })), or drop nullable() and validate elsewhere.

[!WARNING] coerce() is dropped. Use safeParse before handing values to Mongoose if you want Sapphire’s coercion semantics.

[!WARNING] Subdocument _id: false is the default. Mongoose’s own default is true. Set subdocId: true on toMongooseSchema to opt back in.

[!WARNING] No discriminator / plugin / hook support. Sapphire emits a bare Schema. Mongoose’s discriminators, plugins, and middleware are deferred to V1_FUTURE — wire them on the returned Schema yourself if you need them now.

Related

• Fields and modifiers — what each IR kind models.
• Refs and relations — ref lifecycle across adapters.
• Escape hatch — universal .adapter(name, opts) contract.
• Recipes → One schema, many adapters.
• Recipes → Custom error messages.