paramo

Paramo

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 https://github.com/sindresorhus/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,
    isDeveloper: type.Bool,
};

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

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

// name=Adam&age=34&isDeveloper=yar
user.stringify({ name: 'Adam', age: 34, isDeveloper: 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,
    isDeveloper: type.Bool,
    programmingLanguages: type.Array(type.String),
};

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

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

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

Configurable Options

Option	Default	Description
includeDefaults	true	Include default parameters set in the types.
stripRedundant	false	Exclude parameters which are not included in the types.
booleanStrings	['true', 'false']	Tuple of custom boolean types: ['yup', 'nup'].
arrayFormat	null	https://github.com/sindresorhus/query-string option for representing arrays as strings.
stripDefaults	false	Whether default values are stipped when stringifying.
dateFormat	yyyy-mm-dd	https://date-fns.org formatting for dates.
keyFormat	null	Applying snakecase and kebabcase to the parameters.