“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}=require('2')constobj={a: 1,b: 2}
obj::toMap()::toArray()::toObject()::toIterator()
::toArray()::toMap()::toObject()// {a: 1, b: 2}letdata='1.23'data=toNumber(data)data=toString(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}=require('2')

(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:

consttoArray=require('2/array')consttoIterator=require('2/iterator')consttoMap=require('2/map')consttoNumber=require('2/number')consttoObject=require('2/object')consttoString=require('2/string')

Converting to Arrays

consttoArray=require('2/array')// Map => Arrayconstmap=newMap()map.set('a',1)map.set('b',2)toArray(map)// [['a', 1], ['b', 2]]// Iterator => ArraytoArray(map.values())// [1, 2]// Object => ArraytoArray({a: 1,b: 2})// [['a', 1], ['b', 2]]// Array-like object => ArraytoArray({0: 'first',1: 'second'},{detectIndexKeys: true})// ['first', 'second']// Primitive value => ArraytoArray('test')// ['test']

Converting to Iterators

consttoIterator=require('2/iterator')// Object => Iteratorletiterator=toIterator({a: 1,b: 2})iterator.next().value// ['a', 1]iterator.next().value// ['b', 2]iterator.next().done// true// Primitive value => IteratortoIterator('test').next().value// 'test'

Converting to Maps

consttoMap=require('2/map')// Array of key/value pairs => Mapconstmap1=toMap([['a',1],['b',2]])map1.get('a')// 1map1.get('b')// 2// Array of values => Mapconstmap2=toMap(['a','b'])map2.get(0)// 'a'map2.get(1)// 'b'// Object => Mapconstmap3=toMap({a: 1,b: 2})map3.get('a')// 1map3.get('b')// 2

Converting to Numbers

consttoNumber=require('2/number')toNumber('1.2')// 1.2toNumber(Infinity)// 0toNumber(NaN)// 0toNumber('not a number')// 0// Can specify a fallback other than zero:toNumber('not a number',{elseReturn: 100})// 100// You can choose to throw an error for invalid inputs.toNumber('not a number',{elseThrow: true})// throws errortoNumber('not a number',{elseThrow: newTypeError('Not a number!')})// Option to round floats:toNumber('4.7')// 4.7toNumber('4.7',{round: true})// 5// By default, Infinity is not considered a valid number,// but this can be changed:toNumber(Infinity)// 0toNumber(Infinity,{finite: false})// Infinity// Number object => NumberconstnumberObject=newNumber(123)typeofnumberObject// 'object'typeoftoNumber(numberObject)// 'number'// Can parse strings that have digit grouping:toNumber('1,234')// 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:toNumber('1,234',{decimalComma: true})// 1.234

Converting to Objects

consttoObject=require('2/object')// Array of key/value pairs => Objectconstobj1=toObject([['a',1],['b',2]])obj1.a// 1obj1.b// 2// Array => Objectconstobj2=toObject(['first','second'])Object.keys(obj2).length// 2obj2[0]// 'first'obj2[1]// 'second'// In the above example, the array indices become the object keys.// But you can make the keys mirror the values instead:constobj3=toObject(['first','second'],{mirror: true})Object.keys(obj3).length// 2obj3.first// 'first'obj3.second// 'second'// Map => Objectconstmap=newMap()map.set('key1','value1')map.set('key2','value2')constobj4=toObject(map)obj4.key1// 'value1'obj4.key2// 'value2'// Duplicate keystoObject([['key',1],['key',2]])// throws an error (default behavior)constobj5=toObject([['key',1],['key',2]],{throwIfEquivKeys: false})// error-throwing disabledObject.keys(obj5).length// 1obj5.key// 2// Setting property descriptorsconstobj6=toObject([['a',1],['b',2]],{descriptors: {enumerable: false}})Object.keys(obj6).length// 0 (because the properties are non-enumerable)obj6.a// 1obj6.b// 2

Converting to Strings

consttoString=require('2/string')toString(123)// '123'toString(-0)// '0'toString(true)// ''toString(false)// ''toString(undefined)// ''toString(null)// ''toString(Infinity)// ''toString(NaN)// ''toString({})// ''toString([])// ''toString(function(){})// ''toString(Symbol('test'))// ''// Compare the above to standard JavaScript string conversion:String(true)// 'true'String(false)// 'false'String(undefined)// 'undefined'String(null)// 'null'String(Infinity)// 'Infinity'String(NaN)// 'NaN'String({})// '[object Object]'String([])// ''String(function(){})// 'function () {}'String(Symbol('test'))// 'Symbol(test)'// Default fallback is an empty string, but you can change it:toString(undefined)// ''toString(undefined,{elseReturn: 'N/A'})// 'N/A'// You can choose to throw an error for invalid inputs.toString(undefined,{elseThrow: true})// throws error// String object => StringconststringObject=newString('test')typeofstringObject// 'object'typeoftoString(stringObject)// '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 the elseReturn value when round is true. If you need this behavior, apply Math.round to your elseReturn 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 new throwIfEquivKeys option to false.

1.x ⇒ 2.x

• fallback has been renamed to elseReturn.
• Use elseThrow: true instead of fallback: null.
• Unlike the old fallback parameter, elseReturn does not type-enforce its values.
• toObject with mirror: true will now throw an error if any key would overwrite another key. In version 1, this would have been allowed.
• toObject with mirror: 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.