“2”: The Type Conversion Library
A Node.js module for converting between various JavaScript types: arrays, iterators, maps, numbers, objects, and strings.
const toArray toIterator toMap toNumber toObject toString = const obj = a: 1 b: 2obj:::::::: :::::: // {a: 1, b: 2} let data = '1.23'data = data = // '1.23'
Installation
Requires Node.js 8.3.0 or above.
npm i 2
Usage
Requiring the Functions
You can require needed functions via a destructuring assignment:
const toArray toIterator toMap toNumber toObject toString =
(If your project has a linting rule that precludes shadowing the global toString
function, you can also destructure the toStr
function, which is the same as toString
.)
You can also require individual functions via submodules:
const toArray = const toIterator = const toMap = const toNumber = const toObject = const toString =
Converting to Arrays
const toArray = // Map => Arrayconst map = mapmap // [['a', 1], ['b', 2]] // Iterator => Array // [1, 2] // Object => Array // [['a', 1], ['b', 2]] // Array-like object => Array // ['first', 'second'] // Primitive value => Array // ['test']
Converting to Iterators
const toIterator = // Object => Iteratorlet iterator = iteratornextvalue // ['a', 1]iteratornextvalue // ['b', 2]iteratornextdone // true // Primitive value => Iteratornextvalue // 'test'
Converting to Maps
const toMap = // Array of key/value pairs => Mapconst map1 = map1 // 1map1 // 2 // Array of values => Mapconst map2 = map2 // 'a'map2 // 'b' // Object => Mapconst map3 = map3 // 1map3 // 2
Converting to Numbers
const toNumber = // 1.2 // 0 // 0 // 0 // Can specify a fallback other than zero: // 100 // You can choose to throw an error for invalid inputs. // throws error // Option to round floats: // 4.7 // 5 // By default, Infinity is not considered a valid number,// but this can be changed: // 0 // Infinity // Number object => Numberconst numberObject = 123typeof numberObject // 'object'typeof // 'number' // Can parse strings that have digit grouping: // 1234// The built-in Number function, on the other hand, cannot:Number'1,234' // NaN // Can be configured to interpret the comma as a decimal point: // 1.234
Converting to Objects
const toObject = // Array of key/value pairs => Objectconst obj1 = obj1a // 1obj1b // 2 // Array => Objectconst obj2 = Objectlength // 2obj20 // 'first'obj21 // 'second' // In the above example, the array indices become the object keys.// But you can make the keys mirror the values instead:const obj3 = Objectlength // 2obj3first // 'first'obj3second // 'second' // Map => Objectconst map = mapmapconst obj4 = obj4key1 // 'value1'obj4key2 // 'value2' // Duplicate keys // throws an error (default behavior)const obj5 = // error-throwing disabledObjectlength // 1obj5key // 2 // Setting property descriptorsconst obj6 = Objectlength // 0 (because the properties are non-enumerable)obj6a // 1obj6b // 2
Converting to Strings
const toString = // '123' // '0' // '' // '' // '' // '' // '' // '' // '' // '' // '' // '' // Compare the above to standard JavaScript string conversion:Stringtrue // 'true'Stringfalse // 'false'Stringundefined // 'undefined'Stringnull // 'null'StringInfinity // 'Infinity'StringNaN // 'NaN'String{} // '[object Object]'String // ''String {} // 'function () {}'StringSymbol'test' // 'Symbol(test)' // Default fallback is an empty string, but you can change it: // '' // 'N/A' // You can choose to throw an error for invalid inputs. // throws error // String object => Stringconst stringObject = 'test'typeof stringObject // 'object'typeof // 'string'
Version Migration Guide
Here are backward-incompatible changes you need to know about.
2.x ⇒ 3.x
- The minimum supported Node version is now 8.3.0 (instead of 7.0.0).
toNumber
no lounger rounds theelseReturn
value whenround
istrue
. If you need this behavior, applyMath.round
to yourelseReturn
value manually.toObject
will now throw an error if an entries array contains duplicate keys. In version 2, the last equivalent key would have silently overwritten the prior ones. You can restore the previous behavior by setting the newthrowIfEquivKeys
option tofalse
.
1.x ⇒ 2.x
fallback
has been renamed toelseReturn
.- Use
elseThrow: true
instead offallback: null
. - Unlike the old
fallback
parameter,elseReturn
does not type-enforce its values. toObject
withmirror: true
will now throw an error if any key would overwrite another key. In version 1, this would have been allowed.toObject
withmirror: true
will now allow an object to become an object key, so long as its string representation is not equivalent to that of any other key. In version 1, attempting to use an object as an object key would silently fail and would result in numeric index keys being used instead.