Express Typed Query

Exhausted from double checking types passed to your data layer? Well this simple package leverages the power of qs and parses your query sting to usable types. Use real types when exchanging parameters without JSON serialization. Make sure your users can get the data they need in the most flexible way possible. Converts query strings to Javascript typed objects including dates and malformed JSON.

Github

NPM

Install

npm

npm install express-typed-query

yarn

yarn add express-typed-query

pnpm

pnpm add express-typed-query

Usage

Global

MJS / TS

1import express from 'express';
2import etq from 'express-typed-query';
3
4const app = express();
5
6// Global Middleware
7etq.configure(app, etqOptions);
8
9// ...app middleware and routes...
10
11// OR
12
13// Route Middleware
14etq.configure(app, { global: false, ...etqOptions });
15const router = express.Router();
16const options = { ... };
17
18etq.register(router.get('/path', (req, res, next) => { ... }), options);
19
20// ...app middleware and routes...

1import express from 'express';
2import { configure, register, init } from 'express-typed-query';
3
4const app = express();
5
6// Global Middleware
7configure(app, options);
8
9// ...app middleware and routes...
10
11// OR
12
13// Route Middleware
14etq.configure(app, { global: false, ...etqOptions });
15const router = express.Router();
16const options = { disable: <true/false>, global: <true/false> };
17
18register(router.get('/path', (req, res, next) => { ... }), options);
19
20// ...app middleware and routes...

CommonJs

1const express = require('express');
2const etq = require('express-typed-query');
3
4const app = express();
5
6// Global Middleware
7etq.configure(app, options);
8
9// ...app middleware and routes...
10
11// OR
12
13// Route Middleware
14etq.configure(app, { global: false, ...etqOptions });
15const router = express.Router();
16const options = { disable: <true/false>, global: <true/false> };
17
18register(router.get('/path', (req, res, next) => { ... }), options);
19
20// ...app middleware and routes...

1const express = require('express');
2const { configure } = require('express-typed-query');
3
4const app = express();
5
6// Global Middleware
7configure(app, options);
8
9// ...app middleware and routes...
10
11// OR
12
13// Route Middleware
14etq.configure(app, { global: false, ...etqOptions });
15const router = express.Router();
16const options = { disable: <true/false>, global: <true/false> };
17
18register(router.get('/path', (req, res, next) => { ... }), options);
19
20// ...app middleware and routes...

Options (IOptions)

Global vs Middleware (TGlobal)

The global pattern is used by default which will implement the query parser as a function using the set and get methods on the Express app object. Keep in mind that this config must occur before any app.use calls.

This will only allow you to disable keys at a global level. If you have keys for specific endpoints, whose key/value pairs should not be parsed you'll have to set the global option to false.

See examples/global.ts for examples run pnpm run serve:global

When disabling the global parser, you'll need to register routes that will be ignored. See the examples/routes.ts for route middleware examples. pnpm run serve:routes

middleware ({ global: false }) (TMiddlewareOption)

When disabling the global options this will allow you to register a middleware to run before and/or after the parsing of a query. When using a middleware the init function must be called in order to prevent the default parser from performing parsing on any middlewares used to manipulate the request or response object.

1import express from 'express';
2import etq from 'express-type-query';
3
4const app = express();
5const router = express.Router();
6
7etq.init();
8
9// Will be added to the stack and called before query parsing.
10app.use((req, res, next) => {});
11
12// Middleware
13const before = (request, response, next) => {
14  // do work before parsing
15};
16
17const after = (request, response, next) => {
18  // do work after parsing
19};
20
21// Only run before
22const middlewares = before;
23const middlewares = [before];
24// Run before and after
25const middlewares = [before, after];
26// Only run after
27const middlewares = [null, after];
28
29// Route handler
30const handler = app.get('/get', () => {});
31
32etq.configure(handler, { middleware: middlewares });

qsOptions (TQsParseOptions)

If you'd like to override the qs parser's behavior you can use this option which

Logging (TLogging)

This package uses JavaScript console logging by default. You can provide a log level to adjust what is logged using the log level option. The default level is "error" if no option is provided.

level (TLevel)

Setting the log level

1const options = { logging: { level: 'debug' } };

logString (TLogString)

You can provide a string or function that will be prepended to all logs output by this module. The default log string function is

1const options = {
2  logging: {
3    logString: (logLevel: string) => `${new Date().toISOString()} [${logLevel.toUpperCase()}] -`
4  }
5};

tag (TTag)

By default tagging is off. If you'd like to distinguish logs created by this package pass the tag logging option. This will prepend '' to the front of all log messages output by the package.

1const options = {
2  logging: {
3    tag: true
4  }
5};

logger (ILogger)

If you'd like to provide your own logger. This will override all of the prior logging settings set. It must have the following level methods in order of precedence:

1error 0
2warn  1
3info  2
4debug 3
5trace 4

1const options = { logging: { logger: <Logger> } };

Dates (TDates)

If you'd like dates to be parsed from strings you can use the following option

1const options = { dates: true };

This option will try parse date strings that are parsable into date objects.

Hail Mary (THailMary)

Sometimes complex JSON queries may have mistakes or incorrect quotes. Using the hailMary flag will try replace all quotes in a string that appears to contain JSON and attempt to parse it. This operation is risky as it makes assumptions regarding the string. If it fails an error will be thrown indicating it was unable to be parsed.

If the hailMary flag is not set the original string will be parsed back and error handling will be required by the caller.

1const options = { hailMary: true };
2
3Input
4const qs = 'filter={string: "string", boolean: true, number: 1, float: 1.11, null: null, array: ["string", true, 1, 1.11, null] }';
5
6Output
7const output = { filter: {
8  string: 'string',
9  boolean: true,
10  number: 1,
11  float: 1.11,
12  null: null,
13  array: [
14    'string',
15    true,
16    1,
17    1.11
18  ]
19}}

disable (TDisable)

In some cases we have keys that should always remain in the type they are set. For example when using a q parameter ?q="1234" that would be parsed to a number and when searching on a text field we'd run into issues. You can pass in an array of keys to instruct the parser to disable parsing and return the original value at a global level.

1const options: Options = { disable: ['q'] };

Parameter Parsing

Utilizing terms from the Open API 3.1.0 spec, this module will parse form and deepObjects using the explode settings to convert each to their respective representation.

Repeated Keys keys=x&keys=y

Primitive types with repeated keys will be parsed to their associated type for instance

1Input
2'?id=1&id=2&name=John&name=Doe'
3
4Output
5{
6  id: [1, 2],
7  name: ["John", "Doe"]
8}

Array Keys keys[]=x&key[]=y

This format ensures a key/value intended to be an array will be interpreted as such.

1Input
2'?id[]=1&name[]=John'
3
4Output
5{
6  id: [1],
7  name: ["John"]
8}

If we use the repeated key syntax and the API is expecting an array as in the following example:

1Input
2'?id=1&name=John'
3
4Output
5{
6  id: 1,
7  name: "John"
8}

It results in more processing by the route to handle the case where the data layer is expecting an array.

Deep Objects

Leveraging Open API terminology again, we can nest arrays of objects as follows

1Input
2'?user[a]={ "id": 1, name: "John" }'
3
4Output
5{ user: { a: { id: 1, name: 'John' } }}

Using Examples

Run the following commands to use the examples

1pnpm install
2
3<!-- Global -->
4pnpm serve-global
5
6<!-- Middleware -->
7pnpm serve-routes