Skip to content

Latest commit

 

History

History
156 lines (102 loc) · 4.61 KB

README.md

File metadata and controls

156 lines (102 loc) · 4.61 KB
Raw

Coerce

Configurable utility for coercing values.

npm npm David Travis

How to use

Install the library via NPM:

npm install @InlineManual/coerce --save

Then use in your project like this:

import constructCoertor from 'coerce';

You can use predefined coercion configs:

var coerceText = constructCoertor('text');

coerceText();      // "" (empty string)
coerceText('aaa'); // "aaa"
coerceText(123);   // "123" (number converted to string)
coerceText(true);  // "true"

Or you can define your own coercion config:

var coerceCustom = constructCoertor({
  number: 'some number',
  text: function (input) {return 'aaa' + input;}
});

// if value is any other type than function, it will be returned for
// that type
coerceCustom(123); // "some number"

// function will be used to transform the input value
coerceCustom('bbb'); // "aaabbb"

// if value for any type is not defined, `null` will be used
coerceCustom(true); // null

Predefined coercion types

array

  • Converts null and unefined to an empty array ([]).
  • Leaves array unchanged.

date

Used to handle timestamps.

  • Leaves number unchanged.
  • Converts now to current timestamp.
  • Converts strings like -1 hour to relative timestamp. See parse-relative-time for more details.

element

  • Treats string as CSS selector, returns first matched element (if any).
  • Returns object unchanged.

empty

  • Converts undefined to true.
  • Converts null to true.
  • Converts array to true if empty, otherwise false.
  • Converts string to true if empty, otherwise false.
  • Converts number to true if value is 0, otherwise false.
  • Converts boolean to true if false, otherwise false. (Yeah, I know this is a bit confusing, but if you think about it, it makes sense.)
  • Converts object to true if it has no keys (e.g. {}), otherwise false.
  • Converts function to false.

acceptNumber

Same as empty, but always converts number to false.

rejectNumber

Same as empty, but always converts number to true.

number

  • Leaves number unchanged.
  • Converts undefined to 0.
  • Converts null to 0.
  • Converts false to 0, true to 1.
  • string
    • If empty, converts to 0.
    • If it is possible to parse the string to number, returns parsed number.
    • Otherwise returns null.

text

Alias: string

  • Leaves string unchanged.
  • Converts undefined to "" (empty string).
  • Converts null to "" (empty string).
  • Converts number to string.
  • Converts false to "false", true to "true" (textual representation).

function

  • Leaves function unchanged.
  • Converts all other types to a function that returns original input.

boolean

  • Leaves boolean unchanged.
  • Converts undefined and null to false.
  • Converts zero (0), empty string (""), empty array ([]) and empty object ({}) to false, otherwise to true.
  • Evaluates function and converts returned result to boolean.

Documentation

constructCoertor

Constructs function that will coerce any input according to config.

Parameters

  • config [(string | coercionConfig)] Identifier of pre-made coercion config (string) or custom config (object).

Returns Function

coercionConfigItem

Parameters

  • config (optional, default {})

coercionConfig

Parameters

  • config (optional, default {})

Bug reports, feature requests and contact

If you found any bugs, if you have feature requests or any questions, please, either file an issue at GitHub or send me an e-mail at riki@fczbkk.com.

License

Coerce is published under the MIT license.