feathers-mongoose

library8.5.1jsnpmunverified

A Feathers database adapter for Mongoose ORM, allowing developers to integrate MongoDB with FeathersJS real-time APIs. Current stable version is 8.5.1, compatible with Feathers v5 (Dove), Mongoose >=6, and Node >=12. Key differentiators: built-in pagination, query modifiers, lean option for performance, discriminator support, and full integration with Feathers query syntax. Released under the FeathersJS ecosystem, it follows the Common database adapter API and provides TypeScript types.

database

npm install feathers-mongoose

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FEATHERS-MONGOOSE

feathers-mongoose

databasejavascriptv8.5.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

service

✓ import { service } from 'feathers-mongoose'

✗ import service from 'feathers-mongoose'

Default export no longer exists in v8; use named import.

service (CommonJS)

✓ const { service } = require('feathers-mongoose')

✗ const service = require('feathers-mongoose')

CommonJS also requires destructuring from v8 onward.

Model (TypeScript type)

✓ import type { Service, ServiceOptions } from 'feathers-mongoose'

✗ import { Service, ServiceOptions } from 'feathers-mongoose'

TypeScript users: use 'import type' for service types to avoid runtime overhead.

Sets up a Feathers service using Mongoose model with pagination and lean queries, then creates and retrieves messages.

import mongoose from 'mongoose'; import { service } from 'feathers-mongoose'; import { feathers } from '@feathersjs/feathers'; const app = feathers(); mongoose.connect('mongodb://localhost:27017/feathers'); mongoose.Promise = global.Promise; const messageSchema = new mongoose.Schema({ text: { type: String, required: true } }); const Model = mongoose.model('Message', messageSchema); app.use('messages', service({ Model, lean: true, paginate: { default: 10, max: 100 } })); async function start() { const messages = app.service('messages'); await messages.create({ text: 'Hello' }); const result = await messages.find({ query: { $limit: 5 } }); console.log(result); } start().catch(console.error);

Debug

Known issues

breakingfeathers-mongoose v8 drops support for Feathers v4 (Buzzard) and earlier; requires Feathers v5+.

fix

Upgrade to @feathersjs/feathers@5 and @feathersjs/commons@5.

affects: >=8.0.0

breakingfeathers-mongoose v8 changes exports to named exports only; default export removed.

fix

Use `import { service } from 'feathers-mongoose'` instead of `import service from 'feathers-mongoose'`.

affects: >=8.0.0

deprecatedCalling `service(options)` with Mongoose model that uses callbacks is deprecated; use async/await or promises.

fix

Ensure your Mongoose models use promises (e.g., `model.find().exec()`) rather than callbacks.

affects: >=6.0.0

gotchaSetting `lean: false` returns Mongoose documents that are not plain JavaScript objects; attempting to modify them directly will fail.

fix

Call `toObject()` on the document before modifying, or set `lean: true` in service options.

affects: >=0.0.0

gotchaWith `lean: true`, Mongoose virtuals are not included in results unless explicitly populated.

fix

Use Mongoose schema options `{ toJSON: { virtuals: true } }` and query with `.populate()` if needed.

affects: >=0.0.0

gotchaThe `id` option defaults to `'_id'`; if you change it, the service expects `_id` field in documents to be mapped to the custom id field automatically.

fix

Set `id` option to match your schema's id field (e.g., `id: 'customId'`). Ensure MongoDB documents have `_id` set accordingly.

affects: >=0.0.0

Errors

Common errors & fixes

MongooseError: Operation `messages.find()` buffering timed out after 10000ms

Mongoose connection not established before service operation.

fix

Ensure `mongoose.connect()` is called and awaited before using the service, or use `mongoose.connection.on('connected', ...)`.

TypeError: Cannot destructure property 'service' of 'require(...)' as it is undefined.

Using default require without destructuring on feathers-mongoose v8+.

fix

Use `const { service } = require('feathers-mongoose');` instead of `const service = require('feathers-mongoose');`.

CastError: Cast to ObjectId failed for value "..." at path "_id" for model "..."

Invalid ID string passed to `get`, `patch`, or `remove` methods.

fix

Ensure the ID is a valid MongoDB ObjectId string (24 hex chars) or use `null` for multi-update/remove.

ValidationError: Message validation failed: text: Path `text` is required.

Required schema field missing in `create` or `patch` call.

fix

Include all required fields in the data object, or set default values in Mongoose schema.

Upgrade

Version history

8.5.1latest on npm

Audit

Dependencies

mongooserequiredRequired peer dependency; provides MongoDB ODM functionality

Agent activity

2 hits · last 30 days

node

Resources

githubgit://github.com/feathersjs-ecosystem/feathers-mongoose ↗

packagefeathers-mongoose ↗

homepagehttps://github.com/feathersjs-ecosystem/feathers-mongoose ↗