Why another JS util library?
1) 101 will be maintained to minimize overlap with vanilla JS.
- 101 utils are made to work well with vanilla JS methods.
- 101 will only duplicate vanilla JS to provide Functional Programming paradigms, or if the method is not available in a widely supported JS version (currently ES5).
- Other libraries often duplicate a lot of ES5: forEach, map, reduce, filter, sort, and more.
2) No need for custom builds.
- With 101, import naturally, and what you use will be bundled.
- Each util method is a module that can be required
require('101/<util>')
. - Currently CommonJS (node, browserify, webpack, etc) is supported, I will add other module system support on request.
- Other libraries can be large, and require manually creating custom builds when optimizing for size.
Why not release each as individual modules?
I usually agree with this philosophy; however, while in practice, adherence to the module-pattern can become quite annoying for micro-modules (like those in 101):
- Micro-modules existance throughout a project can change very frequently, because of this one may find themselves constantly updating their package.json (repeatedly adding and removing the same micro-modules).
- Unbundling micro-modules can lead to projects with hundreds of dependencies which can be tedious to maintain.
Installation
npm install 101
Usage
assign (aka extend)
Just like ES6's Object.assign
. Extend an object with any number of objects (returns original).
var assign = ; var target = foo: 1 ;var source1 = bar: 1 ;var source2 = baz: 1 ; // { foo: 1, bar: 1, baz: 1 } target extended with source objects // { foo: 1, bar: 1, baz: 1 } target extended with source objects
and
Functional version of &&
. Works great with array.reduce
.
var and = ; ; // false; // true; // "foo"
apply
Functional version of function.apply
.
Supports partial functionality (great with array functions).
var apply = ;sum; // [6] = [sum(1,2,3)] = [1+2+3] { /* sums all arguments */ } { return thisprop; }; // 'val'
bindAll
Bind methods in an object. You can pass an array containing the name of the methods to bind as second argument or leave it empty to bind all the available methods.
var bindAll = ;var obj = { this; } { return ; } { console; } msg: 'Hello World' obj; // undefined ;obj; // "Hello World" ;obj; // "Hello World"
clone
It's clone (Only exporting this bc it is used internal to 101)
var clone = ;var obj = foo: 1 bar: 2; ; // { foo: 1, bar: 2 }
compose
Functional composition method. Works great with array.reduce
.
var compose = ; 'nope'; // isNaN(parseInt('nope')) // true
converge
Converges an array of functions into one. Works great with compose
.
var converge = ; 6 2; // mul(add(6, 2), sub(6, 2)) // (6+2) * (6-2) = 36 a: true b: false a: false b: false a: true b: true; // [{a: true, b: true}] f j; // f(g(h(j), i(j)))
curry
Returns a curried function.
var curry = ; { return a + b; } var curriedAdd = ;var add2 = ; ; // 8; // 10 { return Arrayprototypeslice; } 101; // "101"
defaults
Fill non-existing object values with defaults. Use it to set defaults on options. Works with supplying default values in sub-objects as well. Supports partial functionality (great with array functions). Mutates first argument and returns mutated argument.
var defaults = ;var opts = foo: 0 bar: 1 ;var defs = foo: 1 bar: 2 qux: 2 ; ; // returns mutated `opts` { foo: 0, bar: 1, qux: 2 }opts; // [ { foo: 0, bar: 1, qux: 2 } ] var opts = foo: one: 1 two: 2 ;var defs = foo: two: 20 three: 30 ;; // { foo: { one: 1, two: 2, three: 30 } }
del
Functional version of delete obj[key] which returns the same obj without the deleted key. Supports partial functionality (great with array functions, like map).
var del = ;var obj = foo: 1 bar: 2; ; // { bar: 2 } // use it with array.mapobj obj obj; // [{ bar: 2 }, {same}, {same}] // supports keypaths by defaultvar obj = foo: moo: 1 boo: 2 bar: 3; ; // { foo: { boo: 2 }, bar:3 } // pass an array of keys to be deleted // { foo: { boo: 2 } }
envIs
Functional version of str === process.env.NODE_ENV
.
Or's multiple environments.
var envIs = ;// process.env.NODE_ENV = development; // true; // false; // false; // true
equals
Functional implementation of Object.is with polyfill for browsers without implementations of Object.is Supports partial functionality (great with array functions).
var equals = ; ; // true123; // true; // false
exists
Simple exists function.
var exists = ; ; // true; // false; // false
find
Just like ES6's array.find
.
Finds the first value in the list that passes the given function (predicate) and returns it. If list is not provided find will return a partial-function which accepts a list as the first argument.
var find = ;var hasProps = ;var arr = a: 1 b: 1 b: 1 c: 1 ; var item = ;// returns { a: 1, b: 1 }// returns null if not found // partial-functionvar partial = ;var item = ;// returns { a: 1, b: 1 }// returns null if not found
findIndex
Just like ES6's array.findIndex
.
Finds the first value in the list that passes the given function (predicate) and returns it's index. If list is not provided findIndex will return a partial-function which accepts a list as the first argument.
var findIndex = ;var arr = 1 2 3; var index = ;// returns 1// returns -1 if not found
flip
Returns a function with flipped arguments
var flip = ;var curry = ;var hasKeypaths = ; var hasFooBar = 'foo.bar'; ; // true { return pre + str;} 'hello' '_'; // "_hello"
groupBy
Hashes an array into groups based on the value of a provided common key.
Works nicely with pluck
and reduce
.
var groupBy = ;var arr = id: 1 foo: 'bar' id: 2 foo: 'qux' id: 3 foo: 'qux'; /*{ bar: [ {id: 1, foo: 'bar'} ], qux: [ {id: 2, foo: 'qux'}, {id: 3, foo: 'qux'} ]}*/// always provide initial value when using with reduce!arr // assumes pluck if passed stringarr // also accepts function/*{ bar: [ {id: 1, foo: 'bar'} ], qux: [ {id: 2, foo: 'qux'}, {id: 3, foo: 'qux'} ]}*/
hasKeypaths
Determines whether the keypaths exist and have the specified values. Supports partial functionality (great with array functions, and 101/find).
var hasKeypaths = ;var obj = foo: bar: qux: 1 ; ; // true; // true; // false; // false; // false // optional 'deep' arg, defaults to truevar barObj = bar: 1 ;; // true; // true; // false; // true; // true, uses [hasOwnProperty vs in](http://stackoverflow.com/questions/13632999/if-key-in-object-or-ifobject-hasownpropertykey) // use it with find, findIndex, or filter!var arr = obj b: 1 c: 1 ;; // { foo: { bar: { qux: 1 } } }; // { foo: { bar: { qux: 1 } } } // use it to verify options object has required propertiesvar opts = host: 'localhost' port: '3333' user: id: 5 ;; // true
hasProperties
Determines whether the keys exist and, if specified, has the values. Supports partial functionality (great with array functions, and 101/find). NOTE: I am considering deprecating this method, bc it is so similar to has-keypaths.
var hasProps = ;var obj = qux: 1;obj'foo.bar' = 1 ; // true // true // optional 'deep' arg, defaults to truevar barObj = bar: 1 ;; // true; // true; // false; // true, uses [hasOwnProperty vs in](http://stackoverflow.com/questions/13632999/if-key-in-object-or-ifobject-hasownpropertykey)// use it with find, findIndex, or filter!var arr = a: 1 b: 1 b: 1 c: 1 ;; // { a: 1, b: 1 }; // { a: 1, b: 1 }
includes
Polyfill of ES7 proposed Array.prototype.includes. Will default to Array.prototype.includes if present.
var includes = ;var haystack = 'a' 'b' 'c' 'd' 'e';; // true // optional 3rd argument, searchFrom. Begin searching the target array from a specified index.; // false; // true // partial argument functionalityvar i = ; // true // false // example composition usage:var not = ;var notIn = ;1 2 3 4 5; // [4, 5]
indexBy
Hashes an array of objects based on the value of a provided common key.
Works nicely with pluck
and reduce
.
var arr = foo: 'bar' foo: 'qux'; arr // assumes pluck if passed stringarr // also accepts function// {bar: {foo: 'bar'}, qux: {foo: 'qux'}}// always provide initial value when using with reduce!arr // {bar: {foo: 'bar'}, qux: {foo: 'qux'}}
instanceOf
Functional version of JavaScript's instanceof. Supports partial functionality (great with array functions).
var instanceOf = ; 'foo' 'bar' 1; // [true, true, false]
isBoolean
Functional version of typeof val === 'boolean'
.
Supports partial functionality (great with array functions).
var isBoolean = ; true false 1; // [true, true, false]
isEmpty
Functional version of val empty object, array or object
var isEmpty = ; ; // true; // true; // true; // false
isFunction
Functional version of typeof val === 'function'
var isFunction = ; parseInt {} 'foo'; // [true, true, false]
isInteger
Check if a value is an instance of an integer.
var isInteger = ; ; // true; // false
isNumber
Functional version of val typeof 'number'.
var isNumber = ; 'foo' NaN 1; // [false, false, true]
isObject
Functional strict version of val typeof 'object' (and not array or regexp)
var isObject = ; {} foo: 1 100; // [true, true, false]
isRegExp
Check if a value is an instance of RegExp
var isRegExp = ; '.*' /.*/ {} 1; // [true, true, false, false]
isString
Functional version of val typeof 'string'
var isString = ; 'foo' 'bar' 1; // [true, true, false]
keysIn
Return an array containing all the keys of an object.
It differs from the native Object.keys
by including also the prototype
keys.
var keysIn = ;var { thismsg = 'Hello World';}Userprototype { /* example function */ } var user = ;; // ['msg', 'isLoggedIn']
last
Returns the last value of a list
var last = ; ; // 3; // 'o'
lens
Create a lens to access a data structure. When passed a property key as a string, it returns a function fn(obj)
that acts as a getter for that. It also exposes .set(value, obj)
and .mod(fn, obj)
.
var fooLens = ;var { return str; };var obj = foo: 'foo' bar: 'bar'; ; // => 'foo'fooLens; // => { foo: 'moo', bar: 'bar' }fooLens; // => { foo: 'MOO', bar: 'bar' }
You may also provide getter and setter functions.
var arr = 'foo' 'bar';var first = ; ; // => 'foo'firstarr; // => ['moo', 'bar']firstarr; // => ['FOO', 'bar']
noop
No-op function
; // function () {}
not
Functional version of !
.
var not = ; 'hey'; // false100; // true
omit
Immutable version of delete obj.key
. Returns a new object without the specified keys.
Supports partial functionality (great with array functions, like map).
var omit = ;var obj = foo: 1 bar: 2; ; // { bar: 1 }; // { bar: 1 }; // { } // use it with array.mapobj obj obj; // [{ bar: 1 }, { bar: 1 }, { bar: 1 }];
or
Functional version of ||
.
Works great with array.reduce
.
var or = ; ; // true; // true; // false; // "foo"
passAll
Muxes arguments across many functions and &&
's the results.
Supports partial functionality (great with array functions, like map).
var passAll = ; '' 'foo' 'bar' 100; // [false, true, true, false]
passAny
Muxes arguments across many functions and ||
's the results.
Supports partial functionality (great with array functions, like map).
var passAny = ; '' 'foo' 'bar' 100; // [true, true, true, true]
pick
Returns a new object with the specified keys (with key values from obj). Supports regular expressions and partial functionality (great with array functions, like map).
var pick = ;var obj = foo: 1 bar: 2 qwk: wrk: 1 'qwk.wrk': 2; ; // { foo: 1 }; // { foo: 1 }; // { foo: 1 }; // { foo: 1, bar: 2 } // use it with array.mapobj obj obj; // [{ foo: 1 }, { foo: 1 }, { foo: 1 }]; // supports keypaths; // { qwk: { wrk: 1 } }; // { 'qwk.wrk': 2 } }
pluck
Functional version of obj[key], returns the value of the key from obj. Supports partial functionality (great with array functions, like map).
var pluck = ;var obj = foo: 1 bar: 2; ; // 1 // use it with array.mapobj obj obj; // [1, 1, 1] // supports keypaths by defaultvar obj = foo: bar: 1 'foo.bar': 2; ; // 1, supports keypaths by default; // 2, pass false to not use keypaths
put
Immutable version of obj[key] = val
. Returns a clone of the obj with the value put at the key.
Supports partial functionality (great with array functions, like map).
var put = ;var obj = foo: 1 bar: 2; ; // { foo: 1, bar:2, baz: 3 }obj; // { foo: 1, bar: 2 } (not modified) // use it with array.mapobj obj obj; // [{ foo: 100, bar: 2 }, {copy}, {copy}]obj; // { foo: 1, bar: 2 } (not modified) // supports keypaths by defaultvar obj = bar: 2; ; // { foo: { qux: 100 }, bar: 2 }; // { foo: { qux: 100 }, bar: 2, yolo: 1 }obj; // { foo: 1, bar: 2 } (not modified)
set
Functional version of obj[key] = val, returns the same obj with the key and value set. Supports partial functionality (great with array functions, like map).
var set = ;var obj = foo: 1 bar: 2; ; // 1 // use it with array.mapobj obj obj; // [{ foo: 100, bar: 2 }, {same}, {same}] // supports keypaths by defaultvar obj = bar: 2; ; // { foo: { qux: 100 }, bar: 2 }; // { foo: { qux: 100 }, bar: 2, yolo: 1 }
values
Returns Array containing the values of the properties of an object
var values = ;var obj foo: 'apple' bar: 'orange'; var objValues = ;objValues // ['apple', 'orange']
xor
Exclusive or
Works great with array.reduce
.
var xor = ; ; // false; // true; // true; // false
License
MIT