Skip to content

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

License

Notifications You must be signed in to change notification settings

Wildhoney/Paramo

Repository files navigation

Paramo

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

Travis   npm   License MIT   Coveralls   code style: prettier

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.