Connect Querystring Middleware

Common errors

• TypeError: (0 , qs_middleware__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

  cause Attempting to import `qs-middleware` using ES Module `import` syntax in an environment that doesn't correctly handle CommonJS interop, or mistakenly assuming a default export.
  fix Change the import statement to `const query = require('qs-middleware');`. If in an ESM file, you might need to use `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const query = require('qs-middleware');` or rely on bundler configuration.

• Querystring parsing behavior differs from expected (e.g., dots not treated as nested objects, arrays not parsed correctly)

  cause The `qs-middleware` package bundles an older version of the `qs` library, which might have different default behaviors or lack newer configuration options compared to a separately installed, modern `qs`.
  fix Ensure you are passing the correct `options` object to `query()` (e.g., `{ allowDots: true }`). If the issue persists, the bundled `qs` version might be too old; consider abandoning `qs-middleware` in favor of directly using a modern `qs` library to parse `request.url` manually.

• ReferenceError: require is not defined in ES module scope

  cause Trying to use `require()` in an ES Module (`.mjs` file or `type: "module"` in `package.json`) without proper setup.
  fix For CommonJS modules like `qs-middleware` in an ES Module context, you can create a `require` function using `import { createRequire } from 'module'; const require = createRequire(import.meta.url);` at the top of your file, then use `const query = require('qs-middleware');`.

Warnings

• breaking This package is a CommonJS module and does not natively support ES Module (ESM) import syntax. Direct `import` statements will fail in pure ESM environments without specific Node.js interop (`createRequire`) or bundler configurations.
  Fix: Use `const query = require('qs-middleware');` for CommonJS projects or rely on a bundler's CJS-to-ESM transpilation for ESM projects.
• gotcha The project is abandoned (last commit 2016), meaning it bundles an older version of the `qs` module. This might lead to unexpected querystring parsing behaviors or a lack of features/fixes present in newer `qs` releases.
  Fix: Inspect the `package-lock.json` of `qs-middleware` to determine the bundled `qs` version. If modern `qs` features or bug fixes are required, consider a more actively maintained alternative or manually parse `request.url` with a modern `qs` version.
• gotcha As an abandoned project, `qs-middleware` will not receive security updates. Any vulnerabilities found in its dependencies (like `qs`) or in the middleware itself will remain unaddressed.
  Fix: For production applications or those requiring robust security, it is strongly recommended to use a more actively maintained querystring parsing solution or to implement custom parsing using a modern, regularly updated `qs` version directly.
• gotcha While `qs-middleware` works with frameworks like Express (which builds on Connect), Express itself provides robust built-in `req.query` parsing. Using `qs-middleware` with Express might be redundant or potentially cause conflicts if not carefully managed alongside Express's native parsers.
  Fix: For Express applications, evaluate if `qs-middleware` is truly necessary. Express's default `req.query` parsing is often sufficient, and `express.urlencoded()` can be used for body parsing. Only use `qs-middleware` if its specific `qs` configuration cannot be replicated or overridden via Express's defaults.

Install

• npm install qs-middleware npm
• yarn add qs-middleware yarn
• pnpm add qs-middleware pnpm

Imports

• query
  wrong:

  import query from 'qs-middleware';

  correct:

  const query = require('qs-middleware');

  This package is a CommonJS module and does not natively support ES Modules `import` syntax. Attempting to use `import` will likely lead to runtime errors or require specific Node.js interop configurations (`createRequire`) or bundler setups.
• query
  wrong:

  import { query } from 'qs-middleware';

  correct:

  const query = require('qs-middleware');

  The `qs-middleware` package exports a single function as its module.exports. There are no named exports available for destructuring in CommonJS or ES Modules contexts.

Quickstart

This quickstart demonstrates how to set up `qs-middleware` with a basic Connect server to automatically parse URL querystrings into `request.query`. It shows how to pass options to the underlying `qs` module and confirms how the parsed query is accessible and returned in the HTTP response.

const http = require('http');
const connect = require('connect');
const query = require('qs-middleware');

const app = connect();

// Create a simple Connect application that uses qs-middleware
// Pass options directly to the underlying 'qs' module, e.g., allowDots
app.use(query({ allowDots: true, depth: 5 })); 

app.use(function(request, response) {
    console.log('Parsed Query:', request.query);
    response.setHeader('Content-Type', 'application/json');
    response.end(JSON.stringify({
        message: 'Query parsed successfully!',
        query: request.query,
        example_urls: [
            'http://localhost:3000/?name=Alice&age=30',
            'http://localhost:3000/?user.name=Bob&items[0]=apple&items[1]=orange&foo=bar&nested[a][b][c]=d'
        ]
    }, null, 2));
});

const server = http.createServer(app);
server.listen(3000, () => {
    console.log('Connect app with qs-middleware running on http://localhost:3000');
    console.log('Try visiting: http://localhost:3000/?name=Alice&age=30');
    console.log('Or with qs options in effect: http://localhost:3000/?user.name=Bob&items[0]=apple&items[1]=orange');
});