Query String Machine

Query String Machine is a query string parser that supports type coercion, default values & validation. No dependencies.

Installation

Download QueryStringMachine.js and include it with a script tag, like:

<script src="https://github.com/phetsims/query-string-machine/raw/main/QueryStringMachine.js"></script>

Usage

After downloading and including QueryStringMachine, you can use it to obtain values from the query string. Query String Machine values can be obtained by calling QueryStringMachine.get, which supports the following types:

boolean

Type: 'boolean' returns a primitive boolean value. Note this of type boolean, not string.


var audio = QueryStringMachine.get( 'audio', { type: 'boolean' } );

// http://localhost/test.html?audio=false   => audio===false
// http://localhost/test.html?audio=true    => audio===true

flag

Type: 'flag' takes the boolean value true if and only if it is provided


var audio = QueryStringMachine.get( 'audio', { type: 'flag' } );

// http://localhost/test.html            => audio===false
// http://localhost/test.html?audio      => audio===true

number

Type: 'number' provides numeric values. Note that for each type, a defaultValue can be provided. If defaultValue is not provided, then that query parameter is required, or QueryStringMachine will error.

var delay = QueryStringMachine.get( 'delay', { type: 'number', defaultValue: 1000 }};

// http://localhost/test.html            => delay===1000
// http://localhost/test.html?delay=123  => delay===123

string

Type: 'string' provides values as strings:

var name = QueryStringMachine.get( 'name', { type: 'string', defaultValue: 'Alice' }};

// http://localhost/test.html            => name==='Alice'
// http://localhost/test.html?name=Bob   => name==='Bob'

array

Type: 'array' provides values as strings, using a nested element schema

var words = QueryStringMachine.get( 'heights', { type: 'array', elementSchema: { type: 'string' } } };

// http://localhost/test.html?words=hello,there  => words===['hello', 'there']
// http://localhost/test.html?words=hi           => words===['hi']

custom

By providing a parse function, you can support arbitrary types:

var lower = QueryStringMachine.get( 'name', {
  parse: function( string ) {
    return string.toLowerCase();
  }
};

// http://localhost/test.html?name=Edward       => name==='edward'

Allowed Values

Each type supports allowed values, which specifies an array of valid values, which are checked with ===.

var height = QueryStringMachine.get( 'height', {
  type: 'number',
  allowedValues: [ 4, 5, 6, 7, 8 ]
};

// http://localhost/test.html?height=123 => throws an Error

Multiple Values

In addition to QueryStringMachine.get, you can use QueryStringMachine.getAll which provides multiple values at the same time:

QueryStringMachine.getAll( {
    height: {
      type: 'number',
      defaultValue: 6,
      allowedValues: [ 4, 5, 6, 7, 8 ]
    },
    name: {
      type: 'string',
      defaultValue: 'Larry',
      validate: function( str ) {
        assert && assert( str.indexOf( 'Z' ) !== 0, 'Name cannot start with Z: ' + str );
      }
    },
    custom: {
      parse: function( string ) {
        return string.toLowerCase();
      },
      allowedValues: [ 'abc', 'def', 'ghi' ],
      defaultValue: 'abc'
    },
    isWebGL: {
      type: 'flag'
    },
    screens: {
      type: 'array',
      elementType: 'number',
      defaultValue: [],
      // separator can be overridden, defaults to ','
    }
  } )

returns the following results:

// http://localhost/query-string-machine/test-query-string-machine.html
{
  "height": 6,
  "name": "Larry",
  "custom": "abc",
  "isWebGL": false,
  "screens": []
}

// http://localhost/query-string-machine/test-query-string-machine.html?height=7&isWebGL&wisdom=123
{
  "height": 7,
  "name": "Larry",
  "custom": "abc",
  "isWebGL": true,
  "screens": []
}

// http://localhost/query-string-machine/test-query-string-machine.html?height=7&isWebGL&wisdom=123&custom=DEF
{
  "height": 7,
  "name": "Larry",
  "custom": "def",
  "isWebGL": true,
  "screens": []
}

// http://localhost/query-string-machine/test-query-string-machine.html?height=0
Error( 'value not allowed: 0, allowedValues = 4,5,6,7,8' )

// http://localhost/query-string-machine/test-query-string-machine.html?isWebGL&screens=1,2,3,5
{
  "height": 6,
  "name": "Larry",
  "custom": "abc",
  "isWebGL": true,
  "screens": [
    1,
    2,
    3,
    5
  ]
}

Additional Features

Most use cases are covered by the preceding examples, but in some cases you will want to parse arbitrary strings or check for the existence of a key.

Parsing arbitrary strings

By default, Query String Machine parses the browser query string window.location.search. It can also parse values from provided strings like so:

var text = QueryStringMachine.getForString( 'text', { type: 'string' }, '?text=hello' );
var queryParameters = QueryStringMachine.getAllForString( {
  name: {
    type: 'string'
  },
  age: {
    type: 'number',
    defaultValue: '0',
  }, '?name=Shirley&age=100' );

Checking for the existence of a key

In some cases, it is only important to check for the existence of a key. This can be done using Query String Machine like so:

var containsAudioKey = QueryStringMachine.containsKey( 'audio' );
var queryParameters = QueryStringMachine.containsKeyForString( 'audio', '?mute' );

Launch test-query-string-machine.html for automated tests

phetsims / query-string-machine

readme