Bundstreg
Functional alternatives to many native JavaScript methods and then some
Bundstreg is a set of utility functions designed to replace many native JavaScript methods with often faster alternatives in the same vein as Underscore, Lodash, and the likes. The thing that Bundstreg does differently from these libraries is its focus on minimalism and speed as well as the fact that none of the functions ever mutate their input.
Contents
Installation
$ npm install --save bundstreg
Usage
Try out Bundstreg in your browser
import {values, join, replace} from 'bundstreg';
const o = {hello: 'Hello', world: 'World'};
replace(join(values(o), ' '), 'Hello', 'Hey');
// => 'Hey World'
Benchmark
Bundstreg includes a simple benchmark suite based on Benchmark.js used for comparing the throughput of functions in Bundstreg against their Lodash and native equivalents. The benchmarks can be run in Node.js:
$ node -r babel-core/register bench[/<file>]
Bundstreg aims to provide functions that performance-wise are at least on par with their native equivalents and ideally faster. V8 is used as the implementation reference and functions in Bundstreg are when possible smarter versions of the native functions found there.
API
concat
Join a number of arrays to a single array.
Parameters
arrays
...Array The arrays to concatenate.
Examples
concat([1, 2], [3, 4], [5, 6]);
// => [1, 2, 3, 4, 5, 6]
Returns Array The concatenated array.
each
Loop over an array and invoke an iteratee on each array element.
Parameters
Examples
const a = [1, 2, 3];
each(a, (e, i) => console.log(e, i));
every
Check if a predicate returns truthy for all elements of an array.
Parameters
Examples
const a = [2, 4, 6];
every(a, (e, i) => e % 2 === 0);
// => true
Returns boolean true
if the predicate returns truthy for all elements of the array, otherwise false
.
fill
Fill a portion of an array with a value.
Parameters
array
Array The array to fill.value
any The value to fill the array with.start
number? The index at which to start filling in values. (optional, default0
)end
number? The index at which to end filling in values. (optional, defaultarray.length
)
Examples
const a = [1, 2, 3, 4];
fill(a, 'foo', 1, 3);
// => [1, 'foo', 'foo', 4]
Returns Array The array with the value filled in.
filter
Filter an array by only keeping elements for which a predicate returns truthy.
Parameters
Examples
const a = [1, 2, 3, 4];
filter(a, (e, i) => e % 2 === 0);
// => [2, 4]
Returns Array The filtered array.
findIndex
Find the index of the first element of an array for which a predicate returns truthy.
Parameters
array
Array The array to look for an element in.predicate
Function The predicate to invoke on each element.
Examples
const a = [1, 2, 3];
find(a, (e, i) => e % 2 === 0);
// => 1
Returns any The index of the first element for which the predicate returns truthy, or -1
.
find
Find the first element of an array for which a predicate returns truthy.
Parameters
array
Array The array to look for an element in.predicate
Function The predicate to invoke on each element.
Examples
const a = [1, 2, 3];
find(a, (e, i) => e % 2 === 0);
// => 2
Returns any The first element for which the predicate returns truthy, or undefined
.
flatMap
Create an array of flattened values returned from invocations of an iteratee on each element of an array.
Parameters
Examples
const a = [1, 2, 3];
flatMap(a, (e, i) => [e, e]);
// => [1, 1, 2, 2, 3, 3]
Returns Array The array of flattened values returned from each invocation of the iteratee.
flatten
Flatten an array of arrays.
Parameters
array
Array The array to flatten.
Examples
flatten([[1, 2], [3, 4], [5, 6]]);
// => [1, 2, 3, 4, 5, 6]
Returns Array The flattened array.
includes
Check if an array includes a specific element.
Parameters
array
Array The array to check.query
any The element to check for.position
number? The position at which to start looking. (optional, default0
)
Examples
const a = [1, 2, 3];
includes(a, 2);
// => true
Returns boolean true
if the array includes the element, otherwise false
.
join
Join the elements of an array to a string using a separator.
Parameters
array
Array The array whose elements to join.separator
string? The separator to use for joining the elements. (optional, default','
)
Examples
const a = [1, 2, 3];
join(a, ' + ');
// => '1 + 2 + 3'
Returns string The resulting string.
map
Create an array of values returned from invocations of an iteratee on each element of an array.
Parameters
Examples
const a = [1, 2, 3];
map(a, (e, i) => e * 2);
// => [2, 4, 6]
Returns Array The array of values returned from each invocation of the iteratee.
partition
Partition an array into two arrays where the first contains elements for which the predicate returns truthy.
Parameters
Examples
const a = [1, 2, 3, 4];
partition(a, (e, i) => e % 2 === 0);
// => [[2, 4], [1, 3]]
Returns Array An array containing the two paritions.
reduce
Reduce an array to a value accumulated by invoking an iteratee on each element of the array.
Parameters
array
Array The array to reduce.iteratee
Function The iteratee to invoke of each element.accumulator
any? The initial value. (optional, defaultarray[0]
)
Examples
const a = [1, 2, 3];
reduce(a, (s, n) => s + n);
// => 6
Returns any The accumulated value.
reverse
Reverse the elements of an array.
Parameters
array
Array The array to reverse.
Examples
const a = [1, 2, 3, 4, 5];
reverse(a);
// => [5, 4, 3, 2, 1]
Returns Array The reversed array.
slice
Create a shallow copy of a portion of an array.
Parameters
array
Array The array to copy.start
number? The index at which to begin the copy. (optional, default0
)end
number? The index at which to end the copy. (optional, defaultarray.length
)
Examples
const a = [1, 2, 3, 4];
slice(a, 1, 3);
// => [2, 3]
Returns Array The copy of the array.
some
Check if a predicate returns truthy for any element of an array.
Parameters
Examples
const a = [1, 2, 3];
some(a, (e, i) => e % 2 === 0);
// => true
Returns boolean true
if the predicate returns truthy for any element of the array, otherwise false
.
sort
Sort the elements of an array.
Parameters
Examples
const a = [3, 1, 2, 7, 6, 4, 5, 10, 8, 9];
sort(a);
// => [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
Returns Array The sorted array.
assign
Copy the key/values pairs of one or more source objects to a target object.
Parameters
Examples
const o = {foo: 1};
assign(o, {bar: 2});
// => {foo: 1, bar: 2}
Returns Object The target object.
entries
Get the entries of an object as an array of [key, value]
pairs.
Parameters
object
Object The object whose entries to get.
Examples
const o = {foo: 1, bar: 2};
entries(o);
// => [['foo', 1], ['bar', 2]]
Returns Array The entries of the object.
keys
Get the keys of an object as an array.
Parameters
object
Object The object whose keys to get.
Examples
const o = {foo: 1, bar: 2};
keys(o);
// => ['foo', 'bar']
Returns Array The keys of the object.
values
Get the values of an object as an array.
Parameters
object
Object The object whose values to get.
Examples
const o = {foo: 1, bar: 2};
keys(o);
// => [1, 2]
Returns Array The values of the object.
contains
Check if a string contains a specific substring.
Parameters
string
string The string to check.query
string The substring to check for.position
number? The position at which to start looking.
Examples
const s = 'Hello World';
contains(s, 'orl');
// => true
Returns boolean true
if the string contains the substring, otherwise false
.
endsWith
Check if a string ends with a specific substring.
Parameters
string
string The string to check.query
string The substring to check for.position
number? The position at which to stop looking. (optional, defaultstring.length
)
Examples
const s = 'Hello World';
endsWith(s, 'rld');
// => true
Returns boolean true
if the string ends with the substring, otherwise false
.
replace
Replace occurences of a pattern in a string with a replacement.
Note: If a string is used as pattern then only the first occurence of the string will be replaced. To perform a global replacement use a regular expression with the
g
flag.
Parameters
string
string The string to perform the replacement in.pattern
(string | RegExp) The pattern to replace.replacement
(string | Function) The replacement for the pattern.
Examples
const s = 'Hello World';
replace(s, 'Hello', 'Howdy');
// => 'Howdy World'
Returns string The string with occurences of the pattern replaced by the replacement.
split
Split a string into an array of substrings.
Note: If no separator is provided then the returned array will contain a single substring consisting of the entire original string. If the separator is the empty string then the string will be split on every character.
Parameters
string
string The string to split.separator
(string | RegExp)? The separator to use for splitting the string.limit
number? The number of splits to be made.
Examples
const s = 'Hello World';
split(s, ' ');
// => ['Hello', 'World']
Returns Array<string> The array of substrings.
startsWith
Check if a string starts with a specific substring.
Parameters
string
string The string to check.query
string The substring to check for.position
number? The position at which to start looking. (optional, default0
)
Examples
const s = 'Hello World';
startsWith(s, 'Hel');
// => true
Returns boolean true
if the string starts with the substring, otherwise false
.
toLower
Lowercase a string.
Parameters
string
string The string to lowercase.
Examples
const s = 'Hello World';
toLower(s);
// => 'hello world'
Returns string The lowercased string.
toUpper
Uppercase a string.
Parameters
string
string The string to uppercase.
Examples
const s = 'Hello World';
toUpper(s);
// => 'HELLO WORLD'
Returns string The uppercased string.
trim
Trim trailing whitespace from a string.
Parameters
string
string The string to trim.
Examples
const s = ' Hello World \t';
trim(s);
// => 'Hello World'
Returns string The trimmed string.
is
Check if two values are the same. This is neither the same as the ==
operator nor the ===
operator as is()
treats +0
and -0
as being not equal and NaN
as being equal to itself.
Parameters
x
any The first value.y
any The second value.
Examples
// These are all true:
is(173, 173);
is('foo', 'foo');
is(0, 0);
is(NaN, NaN);
is(null, null);
// These are all false:
is('foo', 'bar');
is(0, -0);
is({}, {});
is([], []);
Returns boolean true
if the values are the same, otherwise false
.
License
Copyright © 2016 Kasper Kronborg Isager. Licensed under the terms of the MIT license.