skald v1.22.2

skald

Shakeable, tested javascript utility functions in a pure functional programming style

What is it?

Short answer: Yet another utility library

Long answer: Skald is a utility library to aid in pure functional javascript programming. It's meant to be shakeable, light-weight, and 100% tested. The entire library will compile down to < 7kb before gzipping (at present) and contains ~90 functions.

How do you use it?

Here's an example of a block of a short ES6 module

const sumPlusOne = arr => arr
    .map(val => val + 1)
    .reduce((acc, val) => acc + val, 0);

export default sumPlusOne;

Here's an example of how that code might be written with skald

import { add, compose, mapBy, reduceBy } from 'skald';

const addOne = add(1);
const mapByAddOne = mapBy(addOne);
const reduceByAdd = reduceBy(add, 0);
const sumPlusOne = compose(reduceByAdd, mapByAddOne);

export default sumPlusOne;

It's a little more code in your module, but:

• We didn't need to declare any functions directly
• We were able to reuse a simple function like add
• The code is easy to understand
• It slims down nicely when run through a build minification

That's about it.

Functions

add(a, b) ⇒ number

Add two numbers

Kind: global function
Since: 1.0.0

Example

add(1,2); //=> 3
    add(2)(3); //=> 5

and(...args) ⇒ boolean

Determine if all arguments are truthy or if array is truthy

Kind: global function
Since: 1.0.0

Example

and(true, true); //=> true
    and([true, true]); //=> true
    and(true, true, false); //=> false

andWith(fns, val) ⇒ boolean | function

Take an array of functions (or values) and determine if all results are true given value

Kind: global function
Since: 1.10.0

Example

const foo = val => val < 10;
    const bar = val => val > 5;
    andWith([foo, bar], 6); //=> true
    andWith([foo, bar])(1); //=> false

appendTo(str, append) ⇒ function | string

Append string to the end of another string

Kind: global function
Since: 1.13.0

Example

appendTo('foo', 'bar'); //=> 'foobar'
    appendTo('bar')('baz'); //=> 'barbaz'

apply(fns, vals) ⇒ function | array

Apply functions from an array to corresponding index in other array

Kind: global function
Since: 1.11.0

Example

const add1 = a => a + 1;
    const add2 = a => a + 2;
    apply([add1, add2], [0, 0]); //=> [1, 2];
    apply([add1])([1, 2, 3]); //=> [2, 2, 3];

args(...vals) ⇒ Array

Returns an array of passed arguments

Kind: global function
Since: 1.16.0

Example

args(1, 2, [3, 4]); //=> [1, 2, [3, 4]]

at(index, val) ⇒ *

Returns copy of entry or character at given index in string or array

Kind: global function
Since: 1.5.0

Example

at(2, 'foo'); //=> 'o'
    at(1)([0, 1, 2]); //=> 1

attempt(toTry, onError) ⇒ *

Attempt something. If an error is thrown, return something else. (Wrapper for try / catch)

Kind: global function
Since: 1.7.0

Example

attempt(() => JSON.parse('<>'), false); //=> false
    attempt(5, () => ({})); //=> 5

bindTo(fn, ...args) ⇒ function

Takes a function and arguments. Leaves undefined arguments unbound and binds defined arguments to their position in arguments list.

Kind: global function
Since: 1.8.0

Example

const foo = (a, b, c) = a + b + c;
    bindTo(foo, 1, 2)(3); //=> 6
    bindTo(foo, undefined, 1, 2)(1); //=> 4
    bindTo(foo, undefined, undefined, 3)(1, 2); //=> 6
    bindTo(foo, undefined, 1)(1)(1); //=> 3

call(fn, arr) ⇒ function

Execute function with array as arguments

Kind: global function
Since: 1.17.0

Example

const foo = (a, b) => a + b;
    call(foo, [1, 2]) //=> 3
    call(foo)([2, 3]) //=> 5

callback(cb, predicate) ⇒ *

Take two arguments and if second argument is truthy, return first.

Kind: global function
Since: 1.0.0

Example

callback('foo', true); //=> 'foo'
    callback('foo', false); //=> null

callbackWith(cb, predicate, val) ⇒ *

Take two arguments and if second argument is truthy, return first based on val

Kind: global function
Since: 1.9.0

Example

callbackWith(a => a, true, 3); //=> 3
    callbackWith(a => a, false, 3); //=> null

concat(val) ⇒ function

Returns a function which accepts no params and returns the passed value

Kind: global function
Since: 1.16.0

Example

cast(6); //=> () = 6;

compose(...args) ⇒ function

Compose functions from right to left

Kind: global function
Since: 1.0.0

Example

compose(val => val + 1, val => val + 2); //=> val => val + 3

composeL(...args) ⇒ function

Compose functions from right to left

Kind: global function
Since: 1.0.0

Example

compose(val => val + 1, val => val + 2); //=> val => val + 3

concat(...args) ⇒ function | Array

Returns a new array, which is a merge of at least two arrays

Kind: global function
Since: 1.16.0

Example

const([1, 2], [3, 4]); //=> [1, 2, 3, 4]

curry(fn, ...args) ⇒ function | *

Curry arguments to function and return new function

Kind: global function
Since: 1.0.0

Example

const foo = (a, b, c) => a + b + c;
    curry(foo, 1, 2)(3); //=> 6
    curry(foo, 1)(3, 4); //=> 8
    curry(foo, 2)(3)(4); //=> 9
    curry(foo)(1)(1)(1); // => 3

deepEquals(a, b) ⇒ boolean | function

Allow comparison of two objects or arrays

Kind: global function
Since: 1.4.0

Example

deepEquals({}, {}); //=> true
    deepEquals([])([]); //=> true

defaultTo(def, val) ⇒ *

Sets default value if passed value is falsy

Kind: global function
Since: 1.2.0

Example

defaultTo(5, undefined); //=> 5
    defaultTo(3)(4); //=> 4

define(fn) ⇒ function | *

Take a function with a known signature and allow arguments to be passed until it executes

Kind: global function
Update:
Since: 1.0.0

Example

const foo = (a, b, c) => a + b + c;
    const bar = define(foo);
    bar(1); // (b, c) => 1 + b + c
    bar(1)(2); // c => 1 + 2 + c
    bar(1)(2)(3); // 6

divide(a, b) ⇒ number | function

Divide two numbers

Kind: global function
Since: 1.0.0

Example

divide(9, 3); //=> 3
    divide(4)(2); //=> 2

equals(a, b) ⇒ boolean | function

Determine if two values are equal

Kind: global function
Since: 1.0.0

Example

equals(1, 1); //=> true
    equals(1)(2); //=> false

everyBy(fn, arr) ⇒ function | boolean

Determine if all values in array satisfy function

Kind: global function
Since: 1.17.0

Example

const isTrue = val => val === true;
    everyBy(isTrue, [true, true]) //=> true
    everyBy(isTrue)([true, false]) //=> false

excludes(search, val) ⇒ boolean | function

Returns true if string is not in string or array

Kind: global function
Since: 1.4.0

Example

excludes('h', 'hello'); //=> false
    excludes('a')('apple'); //=> false

executeWith(val, fn) ⇒ function | *

Create a function which executes a function based on a defined value

Kind: global function
Since: 1.11.0

Example

const addOne = a => a + 1;
    executeOn(1, addOne); //=> 2
    executeOn(2)(addOne); //=> 3

executeWith(fn, ...args) ⇒ function

Create a function which executes a function with each arg being transformed by a function

Kind: global function
Since: 1.11.0

Example

const foo = (a, b) => a + b;
    const add1 = a => a + 1;
    const add2 = b => b + 2;
    executeWith(foo, add1, add2)(0, 0); //=> 3
    executeWith(foo, add1)(0, 0); //=> 1

fillBy(val, arr) ⇒ function | arr

Fill an array with a defined value

Kind: global function
Since: 1.17.0

Example

fillBy(1, [undefined, undefined]); //=> [1, 1]
    fillBy(2)([undefined, undefined); //=> [2, 2]

filterBy(fn, arr) ⇒ function | Array

Filter elements in an array by function

Kind: global function
Since: 1.9.0

Example

const foo = val => val < 3;
    filterBy(foo, [1, 2, 4]); //=> [1, 2]
    filterBy(foo)([2,3]); //=> [2]

getEmptyArr() ⇒ Array

Returns an empty array

Kind: global function
Since: 1.16.0
Example

getEmptyArray(); //=> []

getEmptyObj() ⇒ Object

Returns an empty object

Kind: global function
Since: 1.16.0
Example

getEmptyObj(); //=> {}

getObject(prop, value) ⇒ function | Object

Get an object with single property and value

Kind: global function
Since: 1.15.0

Example

getObject('a', 1); //=> { a: 1 }
    getProp('b')(2); //=> { b: 2 }

getProp(prop, obj) ⇒ function | *

Get property of an object

Kind: global function
Since: 1.15.0

Example

getProp('a', { a: 1 }); //=> 1
    getProp('b')({ b: 2 }); //=> 2

gt(a, b) ⇒ function | boolean

Determine if first value is greater than

Kind: global function
Since: 1.0.0

Example

gt(2, 1); //=> true
    gt('b')('c'); //=> false

gte(a, b) ⇒ function | boolean

Determine if value is greater than or equal to other value

Kind: global function
Since: 1.0.0

Example

gte(1, 1); //=> true
    gte('b')('a'); //=> true

has(obj, key) ⇒ function | boolean

Return true if object has key

Kind: global function
Since: 1.9.0

Example

has({ a: 1 }, 'a'); //=> true
   has({ a: 1 })('a'); //=> true
   has({ a: 1 })('b'); //=> false

identity() ⇒ *

A function which returns whatever is passed into it

Kind: global function
Params: * val
Since: 1.5.0
Example

identity(5); //=> 5
    identity({}); //=> {}

includes(search, val) ⇒ boolean | function

Returns true if string is in string or array

Kind: global function
Since: 1.4.0

Example

includes('h', 'hello'); //=> true
    includes('a')('apple'); //=> true

invoke(fn) ⇒ *

Invoke a function without arguments

Kind: global function
Since: 1.18.0

Example

var foo = () => 1;
    invoke(foo); //=> 1;

isArray(val) ⇒ boolean

Determine if value is array

Kind: global function
Since: 1.0.0

Example

isArray([]); //=> true
    isArray(1); //=> false

isBoolean(val) ⇒ boolean

Determine if value is boolean;

Kind: global function
Since: 1.0.0

Example

isBoolean(1); //=> false
    isBoolean(false); //=> true

isEmpty(val) ⇒ boolean

Check whether object, array, or string is empty

Kind: global function
Since: 1.5.0

Example

isEmpty([]); //=> true
    isEmpty({}); //=> true
    isEmpty(''); //=> true

isFunction(val) ⇒ boolean

Determine if value is function

Kind: global function
Since: 1.0.0

Example

isFunction(1); //=> false
    isFunction(() => ({})); //=> true

isNaN(val) ⇒ boolean

Determine if value is NaN

Kind: global function
Since: 1.0.0

Example

isNaN(NaN); //=> true
    isNaN(1); //=> false

isNull(val) ⇒ boolean

Determine if value is null

Kind: global function
Since: 1.0.0

Example

isNull(null); //=> true
    isNull({}); //=> false

isNumber(val) ⇒ boolean

Determine if value is function

Kind: global function
Since: 1.0.0

Example

isNumber(1); //=> true
    isNumber([]); //=> false

isObject(val) ⇒ boolean

Detemine if value is object

Kind: global function
Since: 1.0.0

Example

isObject({}); //=> true
    isObject(1); //=> false

isPromise(val) ⇒ boolean

Take a value and determine if it is a promise

Kind: global function
Since: 1.1.0

Example

isPromise(Promise.resolve()); //=> true
    isPromise('foo'); //=> false

isPropertyOf(key, obj) ⇒ boolean

Determine if string is property of object

Kind: global function
Since: 1.13.0

Example

isPropertyOf('foo', { foo: 'a' }); //=> true
    isPropertyOf('foo')({ bar: 'b' }); //=> false

isString(val) ⇒ boolean

Determine if value is string

Kind: global function
Since: 1.0.0

Example

isString('foo'); //=> true;
    isString(true); //=> false;

isUndefined(val) ⇒ boolean

Determine if value is undefined

Kind: global function
Since: 1.0.0

Example

isUndefined(undefined); //=> true
    isUndefined(true); //=> false

iterate(fn, len) ⇒ Array

Return array of function iterations of specified length generated from 0-based index

Kind: global function
Since: 1.9.0

Example

const foo = index => index + 1;
    iterate(foo, 3); //=> [1, 2, 3]
    iterate(foo)(2); //=> [1, 2]

joinBy(delimiter, arr) ⇒ function | string

Join array to string, delimited by other string

Kind: global function
Since: 1.13.0

Example

joinBy('.', ['foo', 'bar', 'baz']); //=> 'foo.bar.baz'
    joinBy(',')([1, 2, 3]); //=> '1.2.3';

lt(a, b) ⇒ function | boolean

Determine if value is less than other value

Kind: global function
Since: 1.0.0

Example

lt(1, 2); //=> true
    lt('a')('b'); //=> true

lte(a, b) ⇒ function | boolean

Determine if value is less than or equal to other value

Kind: global function
Since: 1.0.0

Example

lte(1, 1); //=> true
    lte('a')('b'); //=> true

mapBy(fn, arr) ⇒ function | Array

Map elements in an array by function

Kind: global function
Since: 1.9.0

Example

const foo = val => val + 1;
    mapBy(foo, [1, 2]); //=> [2, 3]
    mapBy(foo)([4, 5]); //=> [5, 6]

maybe(fn, val) ⇒ function | *

Execute a function if the argument is not null or undefined

Kind: global function
Since: 1.23.0
Author: oculus42

Example

const foo = val => val + 1;
    maybe(foo, 1); //=> 2
    maybe(foo)(null); //=> null

memoize(fn, function) ⇒ function

Cache return contents of functions

Kind: global function
Since: 1.9.0

merge(...args) ⇒ Object

Returns new object, which is a shallow merge of multiple objects

Kind: global function
Since: 1.16.0

Example

merge({ a: 1 }, { b: 2}); //=> { a: 1, b: 2 }

multiply(a, b) ⇒ function | number

Multiply two numbers together

Kind: global function
Since: 1.0.0

Example

multiply(2, 3); //=> 6
    multiply(2)(2); //=> 4

none(...args) ⇒ boolean

Returns true if no argument or array value is true

Kind: global function
Since: 1.4.0

noop() ⇒ undefined

Executes a noop

Kind: global function
Since: 1.5.0

not(val) ⇒ boolean | function

Returns false if truthy, true if falsy, negation if function

Kind: global function
Since: 1.1.0

Example

const identity = a => a;
    not(1); //=> false
    not(false); //=> true
    not(identity)(true); //=> false

notEquals(a, b) ⇒ function | boolean

Return true if two values are not equal

Kind: global function
Since: 1.1.0

Example

notEquals(1, 2); //=> true
    notEquals(3)(4); //=> true

or(...args) ⇒ boolean

Determine if at least one argument or array value is truthy

Kind: global function
Since: 1.0.0

Example

or(true, false, false); //=> true
    or([false, false, true]); //=> true

orWith(args, val) ⇒ boolean | function

Take an array of functions (or values) and determine if one result is true given value

Kind: global function
Since: 1.10.0

Example

const foo = val => val > 10;
    const bar = val => val < 5;
    orWith([foo, bar], 6); //=> false
    orWith([foo, bar])(1); //=> true

orderBy(template, src) ⇒ function | Array

Generate array based on template of indexes and source

Kind: global function
Since: 1.19.0

Example

orderBy([1, 2, 0], ['a', 'b', 'c']); //=> ['b', 'c', 'a'];
    orderBy([2, 0, 1])(['d', 'e', 'f']); //=> ['f', 'd', 'e'];

power(exponent, base) ⇒ function | number

Return exponent from one number to another

Kind: global function
Since: 1.20.0

Example

power(2, 3); //=> 9
    power(2)(2); //=> 4

prependTo(str, append) ⇒ function | string

Prepend string to the beginning of another string

Kind: global function
Since: 1.13.0

Example

prependTo('foo', 'bar'); //=> 'barfoo'
    prependTo('bar')('baz'); //=> 'bazbar'

reduceBy(fn, accumulator, arr) ⇒ function | *

Reduce array to new value by function

Kind: global function
Since: 1.9.0

Example

const foo = (acc, val) = acc + val;
    reduceBy(foo, 1, [1, 1]); //=> 3
    reduceBy(foo, 2)([2, 2]); //=> 6
    reduceBy(foo)(3)([3, 3]); //=> 9

replaceWith(search, rep, str) ⇒ string | function

Replace search with new value in string

Kind: global function
Since: 1.6.0

Example

replaceWith('f', 'b', 'foo'); //=> 'boo'
    replaceWith(/o/g)('a')('foo'); //=> 'faa'

reverse(fn) ⇒ function

Take a function and return a function which accepts args in reverse order

Kind: global function
Since: 1.1.0

Example

const foo = (a, b, c) => a + b - c;
    reverse(foo); //=> (c)(b)(a) => c + b - a;

setProp(prop, value, obj) ⇒ function | Object

Returns a copy of an object with a new name / value pair

Kind: global function
Since: 1.21.0

Example

setProp('a', 1, {}); //=> { a: 1 }
    getProp('b')(2)({}); //=> { b: 2 }

sliceFrom(start, end, val) ⇒ function | Array | string

Slice an array or string

Kind: global function
Since: 1.17.1

Example

sliceFrom(0, 1, [1, 2, 3]) //=> [0];

someBy(fn, arr) ⇒ function | boolean

Determine if at least one value in array satisfy function

Kind: global function
Since: 1.17.0

Example

const isTrue = val => val === true;
    someBy(isTrue, [true, false]) //=> true
    someBy(isTrue)([false, false]) //=> false

splitBy(search, str) ⇒ function | Array

Split string to array by another string

Kind: global function
Since: 1.13.0

Example

splitBy('.', 'foo.bar.baz'); //=> ['foo', 'bar', 'baz']
    splitBy(',')('1,2,3'); //=> ['1', '2', '3'];

spread(...args) ⇒ Array

Convert argument list to array (alias args)

Kind: global function
Since: 1.17.0

Example

spread(1, 2, 3); //=> [1, 2, 3]

subtract(a, b) ⇒ function | number

Subtract one number from another

Kind: global function
Since: 1.0.0

Example

subtract(3, 2); //=> 1
    subtract(2)(1); //=> 1

ternary(failure, success, predicate) ⇒ *

Return success or failure based on predicate evaluation. If success or failure are functions, returns executed result.

Kind: global function
Since: 1.0.0

Example

ternary(1, 2, true); //=> 2
    ternary(1, 2, false); //=> 1

ternaryL(predicate, success, failure) ⇒ *

Return success or failure based on predicate evaluation. If success or failure are functions, returns executed result.

Kind: global function
Since: 1.1.0

Example

ternaryL(true, 1, 2); //=> 1
    ternaryL(false, 1, 2); //=> 2

ternaryWith(failure, success, predicate, val) ⇒ *

Return success or failure based on predicate evaluation. If success or failure are functions, returns executed result with passed in parameter;

Kind: global function
Since: 1.9.0

Example

const foo = val => val + 1;
    const bar = val => val - 1;
    ternaryWith(bar, foo, true, 3); //=> 4
    ternaryWith(bar, foo, false, 2); //=> 1

toArray(...args) ⇒ Array

Force args to array if not arrays

Kind: global function
Since: 1.0.0

Example

toArray([1, 2]); //=> [1, 2]
    toArray(2, 3); //=> [2, 3]

toBoolean(value) ⇒ boolean

Returns boolean value and converts string 'false' to false

Kind: global function
Since: 1.0.0

Example

toBoolean('false'); //=> false
    toBoolean({}); //=> true

toFunction(value) ⇒ function

Returns function which returns value if value is not a function.

Kind: global function
Since: 1.0.0

Example

toFunction(3); //=> () => 3
    toFunction(() => 1); //=> () => 1

toNumber(value) ⇒ number

Parses int or float or Infinity to numeric value

Kind: global function
Since: 1.0.0

Example

toNumber('Infinity'); //=> Infinity
    toNumber('1.0'); //=> 1
    toNumber({}); //=> NaN

toObject(value) ⇒ Object

Forces value into object. If not object, returns {}

Kind: global function
Since: 1.0.0

Example

toObject({ a: 1 }); //=> { a: 1 }
    toObject(null); //=> null
    toObject('foo'); //=> {}

toPromise(val) ⇒ Promise

Take a value and if not a promise, make it a promise

Kind: global function
Since: 1.1.0

Example

const foo = toPromise(5);
    foo.then(console.log); //=> 5;

toString(value) ⇒ string

Converts value to string. Converts undefined to empty string.

Kind: global function
Since: 1.0.0

Example

toString('foo'); //=> 'foo'
    toString(false); //=> 'false'
    toString(undefined); //=> ''

traverse(obj, path) ⇒ *

Safely traverse object nested properties

Kind: global function
Since: 1.6.0

Example

traverse({}, ['a', 'b', 'c']); //=> undefined
    traverse({ a: 1 })(['a']); //=> 1

traverseR(path, obj) ⇒ *

Safely traverse object nested properties

Kind: global function
Since: 1.14.0

Example

traverse(['a', 'b', 'c'], {}); //=> undefined
    traverse(['a'])({ a: 1 }); //=> 1

typeOf(val) ⇒ string

Returns typeof value

Kind: global function
Since: 1.0.0

Example

typeOf([]); //=> 'object'
    typeOf(undefined); //=> 'undefined'
    typeOf(5); //=> 'number'