Registry / database / mongoose-smart-query

mongoose-smart-query

library1.4.2jsnpmunverified

Mongoose plugin that transforms REST query parameters into efficient MongoDB aggregation pipelines. v1.4.2, actively maintained. Automatically generates queries from req.query objects based on schema definitions, supports pagination, text search, autocomplete/regex search, and field protection. Ships TypeScript types. Uses aggregation pipeline for all queries, not Mongoose find(). Requires Mongoose ^8 and Typesense ^3.0.6 as peer dependencies. Differentiator: schema-aware query generation with built-in auto-pagination (will default to true in next major).

database

npm install mongoose-smart-query

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGOOSE-SMART-QUE

mongoose-smart-query

databasejavascriptv1.4.2

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.

default

✓ import mongooseSmartQuery from 'mongoose-smart-query'

✗ const mongooseSmartQuery = require('mongoose-smart-query')

Plugin is ESM-friendly. CommonJS require still works, but TypeScript defaults to ESM.

SmartQueryStatics

✓ import { SmartQueryStatics } from 'mongoose-smart-query'

✗ import SmartQueryStatics from 'mongoose-smart-query'

A named export for TypeScript type extension of Model.

SmartQueryOptions

✓ import { SmartQueryOptions } from 'mongoose-smart-query'

Named type export for plugin options object.

normalizeSearchText

✓ import { normalizeSearchText } from 'mongoose-smart-query'

✗ import normalizeSearchText from 'mongoose-smart-query'

Named export utility function for text normalization.

Set up a Mongoose model with the smart-query plugin and perform a basic query from a request query object.

import mongoose, { Schema, Model } from 'mongoose'; import mongooseSmartQuery, { SmartQueryStatics } from 'mongoose-smart-query'; interface IUser { name: string; email: string; age: number; } type UserModel = Model<IUser> & SmartQueryStatics; const userSchema = new Schema<IUser>({ name: String, email: String, age: Number, }); userSchema.plugin(mongooseSmartQuery, { defaultFields: 'name email', protectedFields: 'password', fieldsForDefaultQuery: 'name', }); const User = mongoose.model<IUser, UserModel>('User', userSchema); // Example query from req.query const reqQuery = { name: 'John', age: { $gte: 18 }, sort: '-age', limit: 10 }; const users = await User.smartQuery(reqQuery); console.log(users);

Debug

Known issues

breakingIn the next major version, autoPaginate will default to true. Current default is false, so paginated results require explicit opt-in.

fix

Set autoPaginate: false explicitly if you want to keep current behavior, or prepare to handle paginated objects in responses.

affects: >=1.0.0 <2.0.0

gotchaAll queries use the aggregation pipeline, not Mongoose's find(). This means documents are plain objects, not Mongoose documents, so methods like save() are not available on results. Use Model.bulkWrite() or similar for updates.

fix

If you need Mongoose document methods, use Model.find() directly instead of smartQuery.

affects: >=1.0.0

deprecatedThe $q parameter for autocomplete search uses $regex, which can be slow on large collections without proper indexes. The plugin does not automatically create indexes.

fix

Create a text index on fields used in fieldsForDefaultQuery and consider using $text search instead.

affects: >=1.0.0

gotchaTypeScript types: SmartQueryStatics must be intersected with your Model type. Without it, smartQuery will not be recognized as a method.

fix

Declare your model type as Model<IYourInterface> & SmartQueryStatics.

affects: >=1.1.0

gotchaThe plugin automatically protects fields listed in protectedFields, but they are still stored in the database. The protection only prevents them from being returned in queries via smartQuery.

fix

Use Mongoose schema-level select: false for sensitive fields as an additional layer.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Person.smartQuery is not a function

SmartQueryStatics type not added to model, or plugin not applied before model creation.

fix

Ensure you add the plugin before calling mongoose.model() and extend your model type with SmartQueryStatics.

Cannot find module 'mongoose-smart-query'

Package not installed or missing from node_modules.

fix

Run npm install mongoose-smart-query and ensure peer dependencies mongoose and typesense are installed.

Query parameter '$q' is not supported for autocomplete search

fieldsForDefaultQuery option not set when using $q parameter.

fix

Add fieldsForDefaultQuery to plugin options: { fieldsForDefaultQuery: 'field1 field2' }

Argument of type '...' is not assignable to parameter of type 'SmartQueryOptions'

TypeScript strict mode may require explicit typing of options object.

fix

Import SmartQueryOptions and cast: ...smartQuery(req.query, { autoPaginate: true } as SmartQueryOptions)

Upgrade

Version history

1.4.2latest on npm

Audit

Dependencies

mongooserequiredPeer dependency: plugin operates on Mongoose schemas

typesenseoptionalPeer dependency: required for Typesense integration

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/mgyugcha/mongoose-smart-query ↗

packagemongoose-smart-query ↗

homepagehttps://github.com/mgyugcha/mongoose-smart-query#readme ↗