Registry / database / hapi-query-builder

hapi-query-builder

JSON →
library2.2.0jsnpmunverified

Hapi.js plugin that automatically parses URL query parameters into MongoDB/Mongoose query objects. Current stable version is 2.2.0, with a release cadence (latest update Oct 2023). It supports pagination, sorting, field selection, search ($q), and conditional operators. Unlike similar libraries, it tightly integrates with Hapi (v21+) and exposes parsed queries directly on `request.parsedQuery`. Requires Node >=18.20.1 and @hapi/hapi >=21.x.x.

database
npm install hapi-query-builder
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · HAPI-QUERY-BUILDER
H
hapi-query-builder
databasejavascriptv2.2.0
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.

plugin
✓ await server.register({ plugin: require('hapi-query-builder'), options: {} })
✗ import hapiQueryBuilder from 'hapi-query-builder'
CommonJS package; no default ESM export. Must use require(). Plugin is registered via server.register().
request.parsedQuery
✓ handler: function (request, h) { const q = request.parsedQuery; }
✗ request.query.parsedQuery
parsedQuery is injected by the plugin into the request object, not a nested property of request.query.
options.defaultSelectField
✓ options: { defaultSelectField: '_id' }
✗ options: { selectSchema: '_id' }
Only supported option is defaultSelectField (optional). No selectSchema option exists.

Registers hapi-query-builder plugin, sets defaultSelectField, and creates a route that returns parsed MongoDB query from URL params.

const Hapi = require('@hapi/hapi'); (async () => { try { const server = new Hapi.Server({ host: 'localhost', port: 3000, }); await server.register({ plugin: require('hapi-query-builder'), options: { defaultSelectField: '_id', }, }); server.route({ method: 'GET', path: '/user', handler: function (request, h) { return request.parsedQuery; }, }); await server.start(); console.log('Server running at:', server.info.uri); } catch (err) { console.error(err); process.exit(1); } })();
Debug
Known issues
breakingRequires node >=18.20.1 and hapi >=21.x.x; older versions not supported.
fix
Upgrade Node to >=18.20.1 and @hapi/hapi to >=21.x.x.
affects: < 2.0.0
gotchaThe plugin only works with GET requests; POST and other methods are ignored.
fix
Ensure your query-building routes are GET only.
affects: >=1.0.0
gotchaUsing dot notation in field names (e.g., `$select=user.name`) may produce unexpected behavior; the package does not support nested field selections.
fix
Avoid nested field references in $select. Use a flat field list.
affects: >=1.0.0
deprecatedThe option `defaultSelectField` is optional but if omitted, $select will default to empty which might exclude all fields in Mongoose.
fix
Always provide a defaultSelectField (commonly '_id') to avoid empty select.
affects: >=1.0.0
gotchaSearch query $q expects format `text|field1,field2`; missing pipe or commas will cause incorrect parsing.
fix
Ensure correct delimiter: pipe separates search term from fields, commas separate multiple fields.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot destructure property 'options' of 'plugin' as it is undefined.
Missing options object in server.register call or incorrect import.
fix
Use `require('hapi-query-builder')` and pass at least empty options: `options: {}`.
Error: hapi-query-builder requires @hapi/hapi >=21.x.x
Incompatible Hapi version (<21).
fix
Upgrade @hapi/hapi to version 21 or higher.
request.parsedQuery is undefined
Plugin not registered before routes are defined.
fix
Ensure `await server.register(...)` is called before adding routes.
Query parameter '$or' is parsed incorrectly
Wrong separator in $or value; must be field|value pairs separated by commas.
fix
Use format `$or=field1|value1,field2|value2`.
Upgrade
Version history
2.2.0latest on npm
Audit
Dependencies
@hapi/hapioptionalPeer dependency required to register as a Hapi plugin.
Agent activity
6 hits · last 30 days
node
6
Resources
githubhttps://github.com/singhamjesh/hapi-query-builder ↗
packagehapi-query-builder ↗
homepagehttps://github.com/singhamjesh/hapi-query-builder#readme ↗
hapi-query-builder — npm install hapi-query-builder · libregistry