Required dependencies

npm install user@example.com
npm install kareem mpath mquery ms sift mongodb

No native build steps are required. mongoose targets Node.js >= 16. No pod install, Android linking, or Expo prebuild is needed.

Project setup

1. Copy the source/ directory into your project, e.g. src/vendor/mongoose-lib/.
2. When importing directly from source (e.g. for patching), update your path alias:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "mongoose-core/*": ["src/vendor/mongoose-lib/*"]
    }
  }
}

3. Prefer importing the published package normally unless you are modifying internals:

import mongoose from 'mongoose'; // resolves to source/index.js via npm

4. Set your MongoDB URI in an environment variable:

MONGODB_URI=mongodb://127.0.0.1:27017/mydb

5. Call mongoose.connect() once at application startup (before any model operations).

Public API

mongoose (default export)

import mongoose from 'mongoose';
// or from source directly:
const mongoose = require('./source/index');

The default export is a singleton Mongoose instance. Use it to call connect, define schemas/models, and access the full error hierarchy. It exposes .Mongoose for creating isolated instances and .mongo for the raw MongoDB driver.

Schema

import { Schema } from 'mongoose';

const schema = new Schema(
  { name: String; age: Number },
  { timestamps: true }
);

Defines the shape, defaults, validators, indexes, and virtuals for a collection. Pass to mongoose.model(). Available schema types: String, Number, Boolean, Date, Buffer, Mixed, ObjectId, Array, Map, Decimal128, UUID, BigInt, Double, Int32.

mongoose.Error

import mongoose from 'mongoose';

const {
  ValidationError,
  ValidatorError,
  CastError,
  DocumentNotFoundError,
  VersionError,
} = mongoose.Error;

The error namespace mirrors source/error/index.js. Use it in catch blocks to distinguish Mongoose-specific errors (e.g. err instanceof mongoose.Error.CastError) from driver-level or network errors.

Connection

import mongoose from 'mongoose';

const conn = mongoose.createConnection('mongodb://127.0.0.1:27017/mydb');
conn.on('connected', () => console.log('ready'));
conn.on('error', (err) => console.error(err));

createConnection returns a Connection instance (source/connection.js). Use it when you need multiple databases in the same process. Each connection manages its own model registry.

Working examples

Scenario - Define a schema and model, insert and query documents

A typical REST API route handler that creates a new user document and reads it back.

import mongoose, { Schema, Document } from 'mongoose';

interface IUser extends Document {
  name: string;
  email: string;
  createdAt: Date;
}

const userSchema = new Schema<IUser>(
  {
    name:  { type: String, required: true, trim: true },
    email: { type: String, required: true, unique: true, lowercase: true },
  },
  { timestamps: true }
);

const User = mongoose.model<IUser>('User', userSchema);

async function run() {
  await mongoose.connect(process.env.MONGODB_URI!);

  const user = await User.create({ name: 'Alice', email: 'alice@example.com' });
  console.log(user._id);

  const found = await User.findOne({ email: 'alice@example.com' }).lean();
  console.log(found?.name);

  await mongoose.disconnect();
}

run();

Scenario - Schema validation and catching ValidationError

Demonstrates the mongoose.Error.ValidationError class exported from source/error/index.js.

import mongoose, { Schema } from 'mongoose';

const productSchema = new Schema({
  title:    { type: String, required: true },
  price:    { type: Number, min: [0, 'Price must be non-negative'] },
  category: { type: String, enum: ['book', 'electronics', 'clothing'] },
});

const Product = mongoose.model('Product', productSchema);

async function createProduct(data: object) {
  await mongoose.connect(process.env.MONGODB_URI!);

  try {
    const doc = new Product(data);
    await doc.validate();          // throws ValidationError before hitting DB
    await doc.save();
    return doc;
  } catch (err) {
    if (err instanceof mongoose.Error.ValidationError) {
      // err.errors is a map of path -> ValidatorError
      for (const [path, ve] of Object.entries(err.errors)) {
        console.error(`${path}: ${ve.message}`);
      }
    }
    throw err;
  }
}

createProduct({ title: '', price: -5, category: 'unknown' });

Scenario - Multiple connections with isolated model registries

Uses createConnection from source/connection.js to connect two databases independently.

import mongoose from 'mongoose';

const connA = mongoose.createConnection('mongodb://127.0.0.1:27017/db_a');
const connB = mongoose.createConnection('mongodb://127.0.0.1:27017/db_b');

const LogSchema = new mongoose.Schema({ message: String, level: String });

const LogA = connA.model('Log', LogSchema);
const LogB = connB.model('Log', LogSchema);

async function writeLog(db: 'a' | 'b', message: string) {
  const Model = db === 'a' ? LogA : LogB;
  await Model.create({ message, level: 'info' });
}

(async () => {
  await Promise.all([connA.asPromise(), connB.asPromise()]);
  await writeLog('a', 'hello from db_a');
  await writeLog('b', 'hello from db_b');
  await connA.close();
  await connB.close();
})();

File walkthrough

• index.js - Wires the node-mongodb-native driver, calls setDriver, attaches .mongo (raw driver), and re-exports the mongoose singleton.
• mongoose.js - Defines the Mongoose class; index.js uses a singleton of it as the default export.
• schema.js - Schema constructor; parses path definitions and stores type trees, validators, indexes, and hooks.
• schema/ - One file per schema type; each extends schemaType.js and implements cast(), castForQuery(), and validation.
• model.js - Model class; static methods (find, create, updateMany, aggregate, bulkWrite) and instance methods (save, remove).
• document.js - Base Document; tracks modified paths, runs validation, serializes to plain objects.
• query.js - Chainable query builder; methods like .select(), .populate(), .sort(), .lean(), .exec().
• connection.js - Manages a single MongoDB connection, emits lifecycle events, owns its model registry.
• aggregate.js - Fluent aggregation pipeline builder returned by Model.aggregate().
• error/ - Full error hierarchy: MongooseError → ValidationError, CastError, DocumentNotFoundError, VersionError, etc.
• cast/ - Stateless functions that coerce raw values to their schema types (used internally by query and document paths).
• cursor/ - QueryCursor (.cursor()), AggregationCursor (.cursor() on aggregate), and ChangeStream wrappers.
• drivers/node-mongodb-native/ - Thin adapter classes (Collection, Connection) that delegate to the official mongodb driver.
• plugins/ - Three built-in plugins applied globally: saveSubdocs, sharding, trackTransaction.
• helpers/ - Private helpers for discriminators, document internals, and cursor operations; not part of public API.
• schemaType.js - Abstract base for all schema types; defines the cast, validate, default, and index contract.
• virtualType.js - Represents a virtual path with .get() and .set() callbacks (no DB column).
• stateMachine.js - Lightweight finite state machine backing connection and document state transitions.
• utils.js - Internal helpers (deep clone, merge, type checks); not a public API.

Common pitfalls and fixes

• Calling mongoose.model() before connect() resolves - Model definition is fine before connecting, but operations (save, find) queue and may time out; always await mongoose.connect() at startup.
• Re-defining a model with the same name throws OverwriteModelError - Use mongoose.models.User || mongoose.model('User', schema) to guard hot-reload environments (Next.js, ts-node-dev).
• CastError on _id with string ObjectId values - Mongoose casts automatically; if you bypass with .lean() + raw filter, pass new mongoose.Types.ObjectId(id) explicitly.
• TypeScript: Document generic and lean() returning {} type - Use Model.findOne().lean<IUser>() or define your model as Model<IUser> to preserve types through lean queries.
• mongoose@9 drops callback support - All async methods return Promises only; remove all callback-style calls (e.g. Model.find({}, cb)) or the callback is silently ignored.
• Multiple Mongoose instances sharing the same connection - If you instantiate new mongoose.Mongoose() for isolation, remember to call setDriver on the new instance or you will get a "driver not set" error at runtime.

Vibe-coding prompt template

I have placed the Mongoose ODM core source (mongoose@9.5.0) at `src/vendor/mongoose-lib/`
and a USAGE.md integration guide alongside it.

Please help me integrate this library into my Node.js/TypeScript project step by step:

1. Read USAGE.md and `src/vendor/mongoose-lib/index.js` to understand the entry point and exports.
2. Install all required dependencies listed in USAGE.md (kareem, mongodb, mpath, mquery, ms, sift).
3. Create a `src/db.ts` file that calls `mongoose.connect()` using the MONGODB_URI environment variable
   and exports the mongoose instance.
4. Define a typed Mongoose schema and model for [DESCRIBE YOUR ENTITY] in `src/models/[entity].ts`,
   using the Schema types from `src/vendor/mongoose-lib/schema/index.js`.
5. Add CRUD service functions (create, findById, update, delete) in `src/services/[entity]Service.ts`.
6. Wire up error handling using `mongoose.Error.ValidationError` and `mongoose.Error.CastError`
   as shown in USAGE.md.
7. Verify TypeScript types compile without errors.

Constraints: use user@example.com API only (no callbacks, Promises only). Reference real exports
from USAGE.md. Do not invent methods not present in the source.

License and credit

Mongoose is released under the MIT License. See source/LICENSE if present in this block, or refer to the official repository. Upstream package: mongoose on npm.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

JSON Object Signing and Encryption for Node.js

Automation, Utilities & Developer Tools

Free