pretender-query-param-handler

This package provides a helper function and wrapped Pretender class with support for matching query params as part of a registered handler.

Installation

# npm
npm install pretender-query-param-handler

# yarn
yarn add pretender-query-param-handler

Usage

Nothing beats a quick demo:

import { QueryParamAwarePretender } from 'pretender-query-param-handler';

let server = new QueryParamAwarePretender();

server.get('/api/graphql?foo=bar', () => [ 200, {}, '{ "query": "bar" }']);
server.get('/api/graphql?foo=baz', () => [ 200, {}, '{ "query": "baz" }']);
server.get('/api/graphql?foo=*', () => [ 200, {}, '{ "query": "xyz" }']);
server.get('/api/graphql', () => [ 200, {}, '{ "query": "none" }']);

let result;
result = await fetch('/api/graphql?foo=baz');
console.log(await result.json());
//=> { query: 'baz' }

result = await fetch('/api/graphql?foo=xyz');
console.log(await result.json());
//=> { query: 'xyz' }

result = await fetch('/api/graphql?foo=bar');
console.log(await result.json());
//=> { query: 'bar' }

result = await fetch('/api/graphql?foo=xyz&bar=123');
console.log(await result.json());
//=> { query: 'none' }

result = await fetch('/api/graphql');
console.log(await result.json());
//=> { query: 'none' }

Pattern Matching

Simple pattern based matching is supported in query string. Currently the only pattern suported is '*', which matches anything, even an empty string. Multiple patterns can be used in a query string, e.g.:

'/api/graphql?foo=*&bar=*&var=1234'

Please note: any other forms of paterns, including regular expressions, are not supported.

Fallback

Fallback means doing pathname based matching while ignoring the query string altogether, that is, '/api/graphql?foo=abc&...' is equivalent to '/api/graphql' for the purpose of matching.

pretender-query-param-handler performs URL matching in the following stages:

1. Returns an error message if no handler found for the pathname.
2. Performs a search against pre-registered query string literals and returns the handler if there's a match.
3. Performa a search against a pre-registered query string patterns and returns the handler if there's a match.
4. Returns the handler for pathname.

E.g.:

server.get('/api/graphql?foo=abc', /* handlerA */ () => [ 200, {}, '{ "query": "abc" }']);
server.get('/api/graphql?foo=*', /* handlerB */ () => [ 200, {}, '{ "query": "xyz" }']);
server.get('/api/graphql', /* handlerC */ () => [ 200, {}, '{ "query": "none" }']);

result = await fetch('/api/graphql?foo=abc');  // matches handlerA
console.log(await result.json());
//=> { query: 'abc' }

result = await fetch('/api/graphql?foo=xyz'); // matches handlerB
console.log(await result.json());
//=> { query: 'xyz' }

result = await fetch('/api/graphql?bar=xyz'); // fallback: matches handlerC
console.log(await result.json());
//=> { query: 'none' }

result = await fetch('/api/graphql?foo=xyz&bar=1234'); // fallback: matches handlerC
console.log(await result.json());
//=> { query: 'none' }

result = await fetch('/api/json?foo=xyz'); // no match
console.log(await result.json());
//=> Error message

Normalize URLs

In some cases, the order of the query params doesn't matter. Then you can set normalizeURLs to true and the server will normalize (sort) the query params while mocking and matching

import { QueryParamAwarePretender } from 'pretender-query-param-handler';

let server = new QueryParamAwarePretender({
  normalizeURLs: true
});

server.get('/api/graphql?foo=bar&bar=baz', () => [ 200, {}, '{ "query": { "foo": "bar", "bar": "baz" } }'),

let result;
result = await fetch('/api/graphql?bar=baz&foo=bar');
console.log(await result.json());
//=> { query: { foo: 'bar', bar: 'baz' } }

Unhandled Requests

const parentUnhandledRequest = this.server.unhandledRequest;
server.unhandledRequest = function () {
  try {
    parentUnhandledRequest.apply(this, arguments);
  } catch (error) {
    error.requestedQueryParams  // Map<ParamName,ParamValue> unhandled request
    error.existingQueryParams   // Map<ParamName,ParamValue> registered handlers

    // You can customize error messages here
    throw error;
  }
};

Limitations

Internet Explorer/IE is not supported due to the lack of proper Api support.

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.