Needful

Needful is a functionally-flavored micro library for the modern, pragmatic JavaScript developer.

Why use Needful?

Small

Needful exports a single 7kb UMD which covers the 90% use-case for functional-style JavaScript programming. It has equivalents to all the most useful parts of lodash (such as keypath operations) without all the pieces you probably don't need.

Simple

Don't get mired in incidental complexity. Why waste cycles deliberating over how to most efficiently include lodash in your build, or fussing over whether you should use lodash-fp or lodash-es. Just pull in Needful and keep working the essential problem.

Smart

Needful is clojurist-friendly. 0 == true. Also, immutability is baked-in.

Why not use lodash / ramda / underscore?

No one's stopping you.

Do you want a feature that Needful is missing? Use Lodash. It's got you covered.

Need automatic currying? Use Ramda. It's got your back.

Want something time-tested and battle-hardened? Use Underscore. It's been around forever—and it works.

Needful is smaller (7kb) and simpler (a single export) than its peers while still covering practically everything you'll need for effective functional-style JavaScript programming (over 5 dozen functions!).

Needful does the needful, and no more.

You can't always get what you want But if you try sometimes you just might find You get what you need

API

nil : undefined

A safe reference to undefined.

While it rarely happens in practice, undefined is not a keyword and it is possible for it to be shadowed. Use nil and avoid the concern entirely.

Kind: global variable
See: isNil, notNil
Since: 1.2.0

isArray(value) ⇒ boolean

A convenient reference to Array.isArray.

Kind: global function
Returns: boolean - Returns true if value is an object, else false.
Since: 1.2.1

Param	Type	Description
value	*	The value to check.

is(value, type) ⇒ boolean

Checks if value is of type. It's just JavaScript's typeof keyword, as a function.

Kind: global function
Returns: boolean - Returns true if value is of given type, else false.
Since: 1.0.0

Param	Type	Description
value	*	The value to check.
type	'undefined' | 'boolean' | 'string' | 'number' | 'object' | 'function' | 'symbol'	The type to check against.

Example

is({}, 'object');
// => true

is([], 'object');
// => true

is(null, 'object');
// => true

is('foo', 'string');
// => true

is(123, 'number');
// => true

isNil(value) ⇒ boolean

Checks if value is null or undefined.

Kind: global function
Returns: boolean - Returns true if value is nullish, else false.
See: nil, notNil
Since: 1.2.0

Param	Type	Description
value	*	The value to check.

Example

isNil(null)
// => true

isNil(void 0)
// => true

isNil(NaN)
// => false

notNil(value) ⇒ boolean

Checks if value is not null and not undefined.

Complements isNil.

Kind: global function
Returns: boolean - Returns true if value is not nullish, else false.
See: nil, isNil
Since: 1.2.1

Param	Type	Description
value	*	The value to check.

Example

notNil(null)
// => false

notNil(void 0)
// => false

notNil(NaN)
// => true

isObject(value) ⇒ boolean

Checks if value is not null and has a typeof 'object'.

Kind: global function
Returns: boolean - Returns true if value is an object, else false.
Since: 0.0.1

Param	Type	Description
value	*	The value to check.

Example

isObject({})
// => true

isObject([1, 2, 3])
// => true

isObject(Function)
// => true

isObject(null)
// => false

isEqual(value, other) ⇒ boolean

Compares value to other and tests for strict equality.

Kind: global function
Returns: boolean - Returns true if the values are strictly equal, else false.
Since: 1.4.0

Param	Type	Description
value	*	The value to compare.
other	*	The other value to compare.

Example

isEqual({}, {})
// => false

isEqual([], [])
// => false

const foo = {};
const bar = foo;
isEqual(foo, bar);
// => true

isEqual('a', 'a');
// => true

isFalse() ⇒ boolean

Checks if value is false.

Kind: global function
Returns: boolean - Returns true when value is equal to false.
See: isTrue, isFalsy, isTruthy, not
Since: 1.2.0

isFalsy(value) ⇒ boolean

Checks if value is falsy.

Kind: global function
Returns: boolean - Returns true when value is null, undefined' or false`.
See: isTrue, isFalse, isTruthy, not
Since: 1.2.0

Param	Type	Description
value	*	The value to check.

complement(fn) ⇒ boolean

Given a function returns a function which when invoked will return the logically opposite value.

Note: 0 is considered to be truthy.

Kind: global function
Returns: boolean - Returns true if value is an object, else false.
Since: 1.2.1

Param	Type	Description
fn	function	The value to check.

Example

complement(() => true)();
// => false

complement(() => false)();
// => true

complement(() => nil)();
// => true

complement(() => 0)();
// => false

isTruthy(value) ⇒ boolean

Checks if value is truthy.

Kind: global function
Returns: boolean - Returns true when value is not null, not undefined' and not false`.
See: isTrue, isFalse, isFalsy, not
Since: 0.0.2

Param	Type	Description
value	*	The value to check.

isZero(value) ⇒ boolean

Checks if value is 0.

JavaScript treats 0 as falsy, Needful treats 0 as truthy, so it makes sense to provide a functional helper for 0 checks.

Kind: global function
Returns: boolean - Returns true when value is 0.
Since: 1.5.3

Param	Type	Description
value	*	The value to check.

isString(value) ⇒ boolean

Checks if value is a string.

Kind: global function
Returns: boolean - Returns true when value of type 'string'.
Since: 0.0.2

Param	Type	Description
value	*	The value to check.

isNumber(value) ⇒ boolean

Checks if value is a number.

Kind: global function
Returns: boolean - Returns true when value of type 'number'.
Since: 0.0.2

Param	Type	Description
value	*	The value to check.

isNumeric(value) ⇒ boolean

Checks if value is a number or a string which can be parsed as a valid number. Faster than a regex.

Kind: global function
Returns: boolean - Returns true when value is of type 'number' or is a string which can be parsed as a number.
Since: 1.8.0

Param	Type	Description
value	*	The value to check.

isBoolean(value) ⇒ boolean

Checks if value is a boolean.

Kind: global function
Returns: boolean - Returns true when value of type 'boolean'.
Since: 0.0.2

Param	Type	Description
value	*	The value to check.

isUndefined(value) ⇒ boolean

Checks if value is undefined.

Kind: global function
Returns: boolean - Returns true when value of type 'undefined'.
Since: 0.0.2

Param	Type	Description
value	*	The value to check.

isNull(value) ⇒ boolean

Checks if value is null.

Kind: global function
Returns: boolean - Returns true when value is null.
Since: 0.0.2

Param	Type	Description
value	*	The value to check.

isPlainObject(value) ⇒ boolean

Checks if value is a plain object.

Kind: global function
Returns: boolean - Returns true when value is a plain old JavaScript object.
Since: 0.0.1

Param	Type	Description
value	*	The value to check.

not()

Functional bang.

Kind: global function
Since: 0.0.1

partial(fn, ...args)

Partially apply arguments.

Kind: global function
Since: 0.0.1

Param	Type	Description
fn	function	Function to partial apply arguments to.
...args	*	Argument to partially apply.

Example

const concat = (a, b) => '' + a + b;
const fooify = partial(concat, 'foo');
fooify('bar');
// => 'foobar'

partialRight(fn, ...args)

Partially apply arguments, starting from the right of the arguments given at call time.

Kind: global function
Since: 0.0.1

Param	Type	Description
fn	function	Function to partial apply arguments to.
...args	*	Argument to partially apply.

Example

const concat = (a, b) => '' + a + b;
const fooify = partialRight(concat, 'foo');
fooify('bar');
// => 'barfoo'

clone(value) ⇒ *

Deeply clones plain objects and arrays. Primitives are passed through unchanged.

Kind: global function
Returns: * - Returns cloned Object, Array or passes thru other values
See: clone
Since: 1.5.0

Param	Type	Description
value	*	Value to clone.

fill(array, value, start, end) ⇒ Array

Fills all the elements of an array from a start index to an end index with a static value. The end index is not included.

Kind: global function
Returns: Array - Returns new array filled with given value from given start index through given end index.
Since: 1.2.0

Param	Type	Description
array	Array	Array
value	*	Value to fill.
start	number	Start index, defaults to 0.
end	number	End index.

Example

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

push(array, ...value) ⇒ Array

Adds one or more elements to the end of an array.

Kind: global function
Returns: Array - Returns new array with given value(s) added to the end.
Since: 1.2.0

Param	Type	Description
array	Array	Array
...value	*	Value(s) to be added.

Example

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

reverse(array) ⇒ Array

Reverse the order of a given array.

Kind: global function
Returns: Array - Returns new array with values in reverse order.
Since: 1.2.0

Param	Type	Description
array	Array	Array

Example

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

unshift(array, ...value) ⇒ Array

Adds one or more elements to the beginning of an array.

Kind: global function
Returns: Array - Returns new array with given value(s) added to the beginning.
Since: 1.2.0

Param	Type	Description
array	Array	Array
...value	*	Value(s) to be added.

Example

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

splice(array, start, count, ...values) ⇒ Array

Changes the contents of an array by removing or replacing existing elements and/or adding new elements.

Kind: global function
Returns: Array - Returns new array with count elements removed from start and values added at start.
Since: 1.2.0

Param	Type	Description
array	Array	Array
start	number	Start index.
count	number	Delete count.
...values	*	Values to add.

Example

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

concat(...arrays) ⇒ Array

Merges two or more arrays.

Kind: global function
Returns: Array - Returns new array with arrays concatenated.

Param	Type	Description
...arrays	Array	Arrays to merge.

Example

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

join(array, separator) ⇒ Array

Joins all elements of an array into a string.

Kind: global function
Returns: Array - Returns string with all elements of array joined. If given array is empty, returns empty string.

Param	Type	Description
array	Array	Array to join.
separator	string	String which separates each pair of adjacent elements of the array.

Example

join([ 'a', 'b', 'c' ], '-');
// => 'a-b-c'

slice(array, start, end) ⇒ Array

Returns a new array from given start index up until given end index.

Kind: global function
Returns: Array - Returns new array containing elements between start and end index of array

Param	Type	Description
array	Array	Array to slice
start	number	Start index
end	number	End index (selects up to but does not include end index)

Example

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

every(array, predicate) ⇒ boolean

Tests whether all elements in the array pass the test implemented by the given predicate function.

Kind: global function
Returns: boolean - Returns boolean indicating whether or not every element in array satisfies predicate

Param	Type	Description
array	Array	Array to test
predicate	function	Predicate function

Example

every([ 1, 2, 3 ], v => typeof v === 'number');
// => true
every([ 1, 'foo', 3 ], v => typeof v === 'number');
// => false

filter(array, predicate) ⇒ Array

Returns new array containing only elements of given array which pass given predicate.

Kind: global function
Returns: Array - Returns new array containing only the element of the original array whose values pass the test implemented by the given predicate function.

Param	Type	Description
array	Array	Array to filter
predicate	function	Predicate function

Example

filter([ 1, 2, 3 ], v => v % 2);
// => [ 1, 3 ]

find(array, predicate) ⇒ Array

Returns deep clone of first element in array which pass given predicate.

Kind: global function
Returns: Array - Returns clone of first element within array the original array whose values pass the test implemented by the given predicate function.

Param	Type	Description
array	Array	Array to search
predicate	function	Predicate function

Example

find([ 1, 2, 3 ], v => v % 2);
// => 1

findIndex()

TODO

Kind: global function

forEach()

TODO

Kind: global function

map()

TODO

Kind: global function

reduce()

TODO

Kind: global function

reduceRight()

TODO

Kind: global function

some()

TODO

Kind: global function

entries()

TODO

Kind: global function

keys()

TODO

Kind: global function

values()

TODO

Kind: global function

pop()

TODO

Kind: global function

shift()

TODO

Kind: global function

includes()

TODO

Kind: global function

indexOf()

TODO

Kind: global function

lastIndexOf()

TODO

Kind: global function

sort()

TODO

Kind: global function

and()

TODO

Kind: global function

or()

TODO

Kind: global function

isEquiv()

Returns true if two given values are equivalent.

Kind: global function

pipe()

Performs left-to-right function composition.

Kind: global function

compose()

Performs right-to-left function composition.

Kind: global function

isEmpty()

A predicate for determining if a given value is "empty". Returns true for empty strings, empty arrays, empty objects as well as for null or undefined.

Kind: global function

castPath()

Converts a keypath string to an array representation of the keypath. Given an array, the array will be shallow-cloned and returned otherwise unchanged.

Kind: global function

get()

Get the value at a given keypath within an given object. If a third argument is supplied, the value of that argument will be used as a default.

Kind: global function

has()

Returns a truthy value indicating presence or absence of the value at a given keypath in a given object.

Kind: global function

walkPath()

Walk a given object along a given keypath and apply a given function to each intermediate value.

Kind: global function

assoc()

Set a value at a given keypath within an given object. Returns a new object. Original is unchanged.

Kind: global function

dissoc()

Unset a value at a given keypath within an given object. Returns a new object. Original is unchanged.

Kind: global function

set()

Set a value at a given keypath within an given object. Warning: Mutates the given object! Use assoc for an immutable version.

Kind: global function
See: assoc

drop()

Unsets a value at a given keypath within an given object. Warning: Mutates the given object! Use dissoc for an immutable version.

Kind: global function

assign()

A convenient reference to Object.assign.

Kind: global function

merge()

Performs a deep merge of all given objects.

Kind: global function

See Also

• as-needed

License

MIT