README.md

Swiss-army knife of stringifying, parsing and manipulating URL parameters by applying types to the parameters.

       

npm: npm install paramo

yarn: yarn add paramo

---

Getting Started

Paramo takes the very useful query-string library and applies the concept of types as an added layer. Although query-string provides some typecasting of values, it's far from ideal. Using the example below we can setup a type system to transform URL parameters back and forth between string representations.

import { create, type } from 'paramo';

const types = {
    name: type.String,
    age: type.Int,
};

const user = create(types);

// { name: 'Adam', age: 34 }
user.parse('name=Adam&age=34');

// name=Adam&age=34
user.stringify({ name: 'Adam', age: 34 });

The String and Int types are probably the most simple types. Using the Bool type takes a little more configuration if the default isn't sufficient, as booleans can be represented as strings in many various ways. With that in mind, you can provide a second argument to the create function which overrides the defaults – in our case to modify the string representations of boolean values to be the pirate-esque yar and naw.

import { create, type } from 'paramo';

const types = {
    name: type.String,
    age: type.Int,
    developer: type.Bool,
};

const user = create(types, {
    booleanStrings: ['yar', 'naw'],
});

// { name: 'Adam', age, 34: developer: true }
user.parse('name=Adam&age=34&developer=yar');

// name=Adam&age=34&developer=yar
user.stringify({ name: 'Adam', age: 34, developer: true });

We can then introduce the concept of arrays which uses the query-string API for specifying how lists are represented – by default as duplicate keys.

import { create, type, option } from 'paramo';

const types = {
    name: type.String,
    age: type.Int,
    developer: type.Bool,
    languages: type.Array(type.String),
};

const user = create(types, {
    booleanStrings: ['yar', 'naw'],
    arrayFormat: option.arrayFormat.comma,
});

// { name: 'Adam', age, 34: developer: true, languages: ['JavaScript', 'Ruby', 'Haskell'] }
user.parse('name=Adam&age=34&developer=yar&languages=JavaScript,Ruby,Haskell');

// name=Adam&age=34&developer=yar&languages=JavaScript,Ruby,Haskell
user.stringify({
    name: 'Adam',
    age: 34,
    developer: true,
    languages: ['Javascript', 'Ruby', 'Haskell'],
});

Default Values

You can set defaults for the parameters by using the array notation. For example if by default all users are developers, then you can bake that into your types.

const types = {
    name: type.String,
    age: type.Int,
    developer: [type.Bool, true],
    languages: type.Array(type.String),
};

When you user.stringify all parameters are still set, but in some cases you may wish for the default values to be omitted, as the default values may not matter if they are also baked into the back-end. For these instances you can set the stripDefaults option when creating the type instance.

const user = create(types, {
    booleanStrings: ['yar', 'naw'],
    stripDefaults: true,
});

Furthermore when dealing with defaults you may wish for defaults to appear in user.parse unless they're defined in the URL parameters – you can use the includeDefaults option. You can use the same option for user.stringify if you don't set the aforementioned stripDefaults option.

Configurable Options

Option	Default	Description
includeDefaults	false	Include default values when parsing.
stripDefaults	false	Include default values when stringifying.
stripRedundant	false	Exclude parameters which are not included in the types.
booleanStrings	['true', 'false']	Tuple of custom boolean types: ['yup', 'nup'].
arrayFormat	null	query-string option for representing arrays as strings.
arrayFormatSeparator	,	query-string option for setting a custom separator.
dateFormat	YYYY-MM-DD	moment formatting for dates.
keyFormat	null	Applying snakecase, kebabcase and pascalcase to the parameters.
splitKeys	null	Allows the custom splitting of keys when decamelising.
processKeys	null	Allows the setting up of a key processing function.
stripPrefix	false	Whether to include the question mark when stringifying params.
encodeParams	true	Determines whether keys and values are encoded.
decodeParams	true	Determines whether keys and values are decoded.
sortParams	false	Function for sorting the params when stringifying.
plainObject	false	Force the parsed object to return a plain object.