{"id":42840,"library":"hapi-query-builder","title":"hapi-query-builder","description":"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.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/singhamjesh/hapi-query-builder","tags":["javascript","hapi","hapi.js","query","hapi-query","mongodb","mongodb-query","query-builder","hapi-query-builder"],"install":[{"cmd":"npm install hapi-query-builder","lang":"bash","label":"npm"},{"cmd":"yarn add hapi-query-builder","lang":"bash","label":"yarn"},{"cmd":"pnpm add hapi-query-builder","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to register as a Hapi plugin.","package":"@hapi/hapi","optional":true}],"imports":[{"note":"CommonJS package; no default ESM export. Must use require(). Plugin is registered via server.register().","wrong":"import hapiQueryBuilder from 'hapi-query-builder'","symbol":"plugin","correct":"await server.register({ plugin: require('hapi-query-builder'), options: {} })"},{"note":"parsedQuery is injected by the plugin into the request object, not a nested property of request.query.","wrong":"request.query.parsedQuery","symbol":"request.parsedQuery","correct":"handler: function (request, h) { const q = request.parsedQuery; }"},{"note":"Only supported option is defaultSelectField (optional). No selectSchema option exists.","wrong":"options: { selectSchema: '_id' }","symbol":"options.defaultSelectField","correct":"options: { defaultSelectField: '_id' }"}],"quickstart":{"code":"const Hapi = require('@hapi/hapi');\n\n(async () => {\n  try {\n    const server = new Hapi.Server({\n      host: 'localhost',\n      port: 3000,\n    });\n\n    await server.register({\n      plugin: require('hapi-query-builder'),\n      options: {\n        defaultSelectField: '_id',\n      },\n    });\n\n    server.route({\n      method: 'GET',\n      path: '/user',\n      handler: function (request, h) {\n        return request.parsedQuery;\n      },\n    });\n\n    await server.start();\n    console.log('Server running at:', server.info.uri);\n  } catch (err) {\n    console.error(err);\n    process.exit(1);\n  }\n})();","lang":"javascript","description":"Registers hapi-query-builder plugin, sets defaultSelectField, and creates a route that returns parsed MongoDB query from URL params."},"warnings":[{"fix":"Upgrade Node to >=18.20.1 and @hapi/hapi to >=21.x.x.","message":"Requires node >=18.20.1 and hapi >=21.x.x; older versions not supported.","severity":"breaking","affected_versions":"< 2.0.0"},{"fix":"Ensure your query-building routes are GET only.","message":"The plugin only works with GET requests; POST and other methods are ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid nested field references in $select. Use a flat field list.","message":"Using dot notation in field names (e.g., `$select=user.name`) may produce unexpected behavior; the package does not support nested field selections.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always provide a defaultSelectField (commonly '_id') to avoid empty select.","message":"The option `defaultSelectField` is optional but if omitted, $select will default to empty which might exclude all fields in Mongoose.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Ensure correct delimiter: pipe separates search term from fields, commas separate multiple fields.","message":"Search query $q expects format `text|field1,field2`; missing pipe or commas will cause incorrect parsing.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'18.20.1':59 '2.2.0':21 '2023':29 '21':62 'automat':8 'builder':4,77,81 'cadenc':25 'condit':39 'current':17 'direct':54 'expos':51 'field':34 'hapi':2,48,65,69,79 'hapi-queri':68 'hapi-query-build':1,78 'hapi.js':5,66 'hapi/hapi':61 'integr':46 'javascript':64 'latest':26 'librari':43 'mongodb':71,73 'mongodb-queri':72 'mongodb/mongoose':14 'node':58 'object':16 'oct':28 'oper':40 'pagin':32 'paramet':12 'pars':9,52 'plugin':6 'q':37 'queri':3,11,15,53,67,70,74,76,80 'query-build':75 'releas':24 'request.parsedquery':56 'requir':57 'search':36 'select':35 'similar':42 'sort':33 'stabl':18 'support':31 'tight':45 'unlik':41 'updat':27 'url':10 'v21':49 'version':19 'x.x':63","created_at":"2026-06-05T16:56:55.177068+00:00","updated_at":"2026-06-05T16:56:55.177068+00:00","problems":[{"fix":"Use `require('hapi-query-builder')` and pass at least empty options: `options: {}`.","cause":"Missing options object in server.register call or incorrect import.","error":"TypeError: Cannot destructure property 'options' of 'plugin' as it is undefined."},{"fix":"Upgrade @hapi/hapi to version 21 or higher.","cause":"Incompatible Hapi version (<21).","error":"Error: hapi-query-builder requires @hapi/hapi >=21.x.x"},{"fix":"Ensure `await server.register(...)` is called before adding routes.","cause":"Plugin not registered before routes are defined.","error":"request.parsedQuery is undefined"},{"fix":"Use format `$or=field1|value1,field2|value2`.","cause":"Wrong separator in $or value; must be field|value pairs separated by commas.","error":"Query parameter '$or' is parsed incorrectly"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/singhamjesh/hapi-query-builder#readme","github":"https://github.com/singhamjesh/hapi-query-builder","docs":null,"changelog":null,"pypi":null,"npm":"hapi-query-builder","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}