README.md

Utils

Utilities.

Installation

npm install @stdlib/utils

Alternatively,

• To load the package in a website via a script tag without installation and bundlers, use the ES Module available on the esm branch.
• If you are using Deno, visit the deno branch.
• For use in Observable, or in browser/node environments, use the Universal Module Definition (UMD) build available on the umd branch.

The branches.md file summarizes the available branches and displays a diagram illustrating their relationships.

Usage

var utils = require( '@stdlib/utils' );

utils

Namespace containing utilities.

var o = utils;
// returns {...}

The namespace has the following sub-namespaces:

• async: async utilities.

Data Structures

• CircularBuffer( buffer ): circular buffer constructor.
• CompactAdjacencyMatrix( N ): compact adjacency matrix constructor.
• DoublyLinkedList(): doubly linked list constructor.
• FIFO(): first-in-first-out (FIFO) queue.
• LinkedList(): singly linked list.
• namedtypedtuple( fields[, options] ): create a factory for generating named typed tuples.
• Stack(): stack data structure.

Collections

• anyByRight( collection, predicate[, thisArg ] ): test whether at least one element in a collection passes a test implemented by a predicate function, iterating from right to left.
• anyBy( collection, predicate[, thisArg ] ): test whether at least one element in a collection passes a test implemented by a predicate function.
• any( collection ): test whether at least one element in a collection is truthy.
• append( collection1, collection2 ): add elements from one collection to the end of another collection.
• bifurcateBy( collection, [options,] predicate ): split values into two groups according to a predicate function.
• bifurcateIn( obj, [options,] predicate ): split an object's own and inherited property values into two groups according to a predicate function.
• bifurcateOwn( obj, [options,] predicate ): split an object's own property values into two groups according to a predicate function.
• bifurcate( collection, [options,] filter ): split values into two groups.
• countBy( collection, [options,] indicator ): group values according to an indicator function and return group counts.
• everyByRight( collection, predicate[, thisArg ] ): test whether all elements in a collection pass a test implemented by a predicate function, iterating from right to left.
• everyBy( collection, predicate[, thisArg ] ): test whether all elements in a collection pass a test implemented by a predicate function.
• every( collection ): test whether all elements in a collection are truthy.
• forEachRight( collection, fcn[, thisArg ] ): invoke a function for each element in a collection, iterating from the right to left.
• forEach( collection, fcn[, thisArg ] ): invoke a function for each element in a collection.
• groupBy( collection, [options,] indicator ): group values according to an indicator function.
• groupIn( obj, [options,] indicator ): group an object's own and inherited property values according to an indicator function.
• groupOwn( obj, [options,] indicator ): group an object's own property values according to an indicator function.
• group( collection, [options,] groups ): group values as arrays associated with distinct keys.
• inmapRight( collection, fcn[, thisArg ] ): invoke a function for each element in a collection and update the collection in-place, iterating from right to left.
• inmap( collection, fcn[, thisArg ] ): invoke a function for each element in a collection and update the collection in-place.
• keyByRight( collection, fcn[, thisArg ] ): convert a collection to an object whose keys are determined by a provided function and whose values are the collection values, iterating from right to left.
• keyBy( collection, fcn[, thisArg ] ): convert a collection to an object whose keys are determined by a provided function and whose values are the collection values.
• noneByRight( collection, predicate[, thisArg ] ): test whether all elements in a collection fail a test implemented by a predicate function, iterating from right to left.
• noneBy( collection, predicate[, thisArg ] ): test whether all elements in a collection fail a test implemented by a predicate function.
• none( collection ): test whether all elements in a collection are falsy.
• pop( collection ): remove and return the last element of a collection.
• prepend( collection1, collection2 ): add elements from one collection to the beginning of another collection.
• push( collection, ...items ): add one or more elements to the end of a collection.
• reduceRight( arr, initial, reducer[, thisArg ] ): apply a function against an accumulator and each element in an array while iterating from right to left and return the accumulated result.
• reduce( arr, initial, reducer[, thisArg ] ): apply a function against an accumulator and each element in an array and return the accumulated result.
• reduce2d( arr, initial, fcn[, thisArg] ): reduce the number of dimensions by one of a two-dimensional nested array by applying a function against an accumulator and each element along the innermost dimension and returning the accumulation results as a one-dimensional array.
• shift( collection ): remove and return the first element of a collection.
• someByRight( collection, n, predicate[, thisArg ] ): test whether a collection contains at least n elements which pass a test implemented by a predicate function, iterating from right to left.
• someBy( collection, n, predicate[, thisArg ] ): test whether a collection contains at least n elements which pass a test implemented by a predicate function.
• some( collection, n ): test whether a collection contains at least n elements which are truthy.
• tabulateBy( collection[, options,] indicator ): generate a frequency table according to an indicator function.
• tabulate( collection ): generate a frequency table.
• unshift( collection, ...items ): add one or more elements to the beginning of a collection.
• untilEachRight( collection, predicate, fcn[, thisArg ] ): until a test condition is true, invoke a function for each element in a collection, iterating from right to left.
• untilEach( collection, predicate, fcn[, thisArg ] ): until a test condition is true, invoke a function for each element in a collection.
• whileEachRight( collection, predicate, fcn[, thisArg ] ): while a test condition is true, invoke a function for each element in a collection, iterating from right to left.
• whileEach( collection, predicate, fcn[, thisArg ] ): while a test condition is true, invoke a function for each element in a collection.

Arrays

• deepPluck( arr, path[, options] ): extract a nested property value from each element of an object array.
• find( arr, [opts,] clbk ): find elements in an array-like object that satisfy a test condition.
• flattenArray( arr[, options] ): flatten an array.
• objectFromEntries( entries ): create an object from key-value pairs.
• indexOf( arr, searchElement[, fromIndex] ): return the first index at which a given element can be found.
• pluck( arr, prop[, options] ): extract a property value from each element of an object array.
• unzip( arr[, idx] ): unzip a zipped array (i.e., a nested array of tuples).
• zip( arr1, arr2,...[, opts] ): generate array tuples from input arrays.

Objects

• capitalizeKeys( obj ): convert the first letter of each object key to uppercase.
• commonKeys( obj1, obj2[, obj3[,...,objN]] ): return the common own property names of two or more objects.
• deepGet( obj, path[, options] ): get a nested property value.
• deepSet( obj, path, value[, options] ): set a nested property value.
• setConfigurableReadOnlyAccessor( obj, prop, getter ): define a configurable read-only accessor.
• setConfigurableReadOnly( obj, prop, value ): define a configurable read-only property.
• setConfigurableReadWriteAccessor( obj, prop, getter, setter ): define a configurable read-write accessor.
• setConfigurableWriteOnlyAccessor( obj, prop, setter ): define a configurable write-only accessor.
• setMemoizedConfigurableReadOnly( obj, prop, fcn ): define a configurable memoized read-only object property.
• defineMemoizedProperty( obj, prop, descriptor ): define a memoized object property.
• setMemoizedReadOnly( obj, prop, fcn ): define a memoized read-only object property.
• setNonEnumerableProperty( obj, prop, value ): define a non-enumerable property.
• setNonEnumerableReadOnlyAccessor( obj, prop, getter ): define a non-enumerable read-only accessor.
• setNonEnumerableReadOnly( obj, prop, value ): define a non-enumerable read-only property.
• setNonEnumerableReadWriteAccessor( obj, prop, getter, setter ): define a non-enumerable read-write accessor.
• setNonEnumerableWriteOnlyAccessor( obj, prop, setter ): define a non-enumerable write-only accessor.
• defineProperties( obj, properties ): define (and/or modify) object properties.
• defineProperty( obj, prop, descriptor ): define (or modify) an object property.
• setReadOnlyAccessor( obj, prop, getter ): define a read-only accessor.
• setReadOnly( obj, prop, value ): define a read-only property.
• setReadWriteAccessor( obj, prop, getter, setter ): define a read-write accessor.
• setWriteOnlyAccessor( obj, prop, setter ): define a write-only accessor.
• objectEntriesIn( obj ): return an array of an object's own and inherited enumerable property key-value pairs.
• objectEntries( obj ): return an array of an object's own enumerable property key-value pairs.
• enumerablePropertiesIn( obj ): return an array of an object's own and inherited enumerable property names and symbols.
• enumerableProperties( obj ): return an array of an object's own enumerable property names and symbols.
• enumerablePropertySymbolsIn( obj ): return an array of an object's own and inherited enumerable symbol properties.
• enumerablePropertySymbols( obj ): return an array of an object's own enumerable symbol properties.
• flattenObject( obj[, options] ): flatten an object.
• forIn( obj, fcn[, thisArg ] ): invoke a function for each own and inherited enumerable property of an object.
• forOwn( obj, fcn[, thisArg ] ): invoke a function for each own enumerable property of an object.
• getPrototypeOf( value ): return the prototype of a provided object.
• inheritedEnumerableProperties( obj[, level] ): return an array of an object's inherited enumerable property names and symbols.
• inheritedEnumerablePropertySymbols( obj[, level] ): return an array of an object's inherited enumerable symbol properties.
• inheritedKeys( obj[, level] ): return an array of an object's inherited enumerable property names.
• inheritedNonEnumerableProperties( obj[, level] ): return an array of an object's inherited non-enumerable property names and symbols.
• inheritedNonEnumerablePropertyNames( obj[, level] ): return an array of an object's inherited non-enumerable property names.
• inheritedNonEnumerablePropertySymbols( obj[, level] ): return an array of an object's inherited non-enumerable symbol properties.
• inheritedProperties( obj[, level] ): return an array of an object's inherited property names and symbols.
• inheritedPropertyDescriptor( obj, property[, level] ): return a property descriptor for an object's inherited property.
• inheritedPropertyDescriptors( obj[, level] ): return an object's inherited property descriptors.
• inheritedPropertyNames( obj[, level] ): return an array of an object's inherited enumerable and non-enumerable property names.
• inheritedPropertySymbols( obj[, level] ): return an array of an object's inherited symbol properties.
• inheritedWritableProperties( obj[, level] ): return an array of an object's inherited writable property names and symbols.
• inheritedWritablePropertyNames( obj[, level] ): return an array of an object's inherited writable property names.
• inheritedWritablePropertySymbols( obj[, level] ): return an array of an object's inherited writable symbol properties.
• keysIn( obj ): return an array of an object's own and inherited enumerable property names.
• lowercaseKeys( obj ): convert each object key to lowercase.
• mapKeys( obj, transform ): map keys from one object to a new object having the same values.
• mapValues( obj, transform ): map values from one object to a new object having the same keys.
• merge( target, source1[, source2[,...,sourceN]] ): merge and extend objects.
• moveProperty( source, prop, target ): move a property from one object to another object.
• nonEnumerablePropertiesIn( obj ): return an array of an object's own and inherited non-enumerable property names and symbols.
• nonEnumerableProperties( obj ): return an array of an object's own non-enumerable property names and symbols.
• nonEnumerablePropertyNamesIn( obj ): return an array of an object's own and inherited non-enumerable property names.
• nonEnumerablePropertyNames( obj ): return an array of an object's own non-enumerable property names.
• nonEnumerablePropertySymbolsIn( obj ): return an array of an object's own and inherited non-enumerable symbol properties.
• nonEnumerablePropertySymbols( obj ): return an array of an object's own non-enumerable symbol properties.
• nonIndexKeys( obj ): return an array of an object's own enumerable property names which are not integer indices.
• objectInverseBy( obj, [options,] transform ): invert an object, such that keys become values and values become keys, according to a transform function.
• objectInverse( obj[, options] ): invert an object, such that keys become values and values become keys.
• omitBy( obj, predicate ): return a partial object copy excluding properties for which a predicate (function) returns a truthy value.
• omit( obj, keys ): return a partial object copy excluding specified keys.
• pickArguments( fcn, indices[, thisArg] ): create a function that invokes a provided function with specified arguments.
• pickBy( obj, predicate ): return a partial object copy containing properties for which a predicate (function) returns a truthy value.
• pick( obj, keys ): return a partial object copy containing only specified keys.
• propertiesIn( obj ): return an array of an object's own and inherited property names and symbols.
• properties( obj ): return an array of an object's own enumerable and non-enumerable property names and symbols.
• propertyDescriptorIn( obj, property ): return a property descriptor for an object's own or inherited property.
• propertyDescriptor( obj, property ): return a property descriptor for an object's own property.
• propertyDescriptorsIn( obj ): return an object's own and inherited property descriptors.
• propertyDescriptors( obj ): return an object's own property descriptors.
• propertyNamesIn( obj ): return an array of an object's own and inherited enumerable and non-enumerable property names.
• propertyNames( obj ): return an array of an object's own enumerable and non-enumerable property names.
• propertySymbolsIn( obj ): return an array of an object's own and inherited symbol properties.
• propertySymbols( obj ): return an array of an object's own symbol properties.
• uncapitalizeKeys( obj ): convert the first letter of each object key to lowercase.
• uppercaseKeys( obj ): convert each object key to uppercase.
• objectValuesIn( obj ): return an array of an object's own and inherited enumerable property values.
• objectValues( obj ): return an array of an object's own enumerable property values.
• writablePropertiesIn( obj ): return an array of an object's own and inherited writable property names and symbols.
• writableProperties( obj ): return an array of an object's own writable property names and symbols.
• writablePropertyNamesIn( obj ): return an array of an object's own and inherited writable property names.
• writablePropertyNames( obj ): return an array of an object's own writable property names.
• writablePropertySymbolsIn( obj ): return an array of an object's own and inherited writable symbol properties.
• writablePropertySymbols( obj ): return an array of an object's own writable symbol properties.

Functions

• argumentFunction( idx ): create an argument function.
• compose( ...fcn ): function composition.
• constantFunction( x ): constant function.
• curryRight( fcn[, arity][, thisArg] ): transform a function into a sequence of functions each accepting a single argument.
• curry( fcn[, arity][, thisArg] ): transform a function into a sequence of functions each accepting a single argument.
• doUntilEachRight( collection, fcn, predicate[, thisArg ] ): until a test condition is true, invoke a function for each element in a collection, iterating from right to left.
• doUntilEach( collection, fcn, predicate[, thisArg ] ): until a test condition is true, invoke a function for each element in a collection.
• doUntil( fcn, predicate[, thisArg ] ): invoke a function until a test condition is true.
• doWhileEachRight( collection, fcn, predicate[, thisArg ] ): while a test condition is true, invoke a function for each element in a collection, iterating from right to left.
• doWhileEach( collection, fcn, predicate[, thisArg ] ): while a test condition is true, invoke a function for each element in a collection.
• doWhile( fcn, predicate[, thisArg ] ): invoke a function while a test condition is true.
• filterArguments( fcn, predicate[, thisArg] ): create a function that invokes a provided function according to a predicate function.
• functionName( fcn ): determine a function's name.
• functionSequence( ...fcn ): function sequence.
• identity( x ): identity function.
• mapArguments( fcn, clbk[, thisArg] ): create a function that applies arguments to a provided function after transforming arguments according to a callback function.
• mapFun( fcn, n[, thisArg ] ): invoke a function n times and return an array of accumulated function return values.
• maskArguments( fcn, mask[, thisArg] ): create a function that invokes a provided function according to an argument mask.
• memoize( fcn[, hashFunction] ): memoize a function.
• noop(): function which does nothing.
• papplyRight( fcn[, ...args] ): partially apply function arguments from the right.
• papply( fcn[, ...args] ): partially apply function arguments.
• rejectArguments( fcn, predicate[, thisArg] ): create a function that invokes a provided function according to a predicate function.
• reorderArguments( fcn, indices[, thisArg] ): create a function that invokes a provided function with reordered arguments.
• reverseArguments( fcn[, thisArg] ): create a function that invokes a provided function with arguments in reverse order.
• uncurryRight( fcn[, arity][, thisArg] ): transform a curried function into a function invoked with multiple arguments.
• uncurry( fcn[, arity][, thisArg] ): transform a curried function into a function invoked with multiple arguments.
• until( predicate, fcn[, thisArg ] ): invoke a function until a test condition is true.
• whilst( predicate, fcn[, thisArg ] ): invoke a function while a test condition is true.

Error Handling

• trycatch( x, y ): if a function does not throw, return the function return value; otherwise, return y.
• tryFunction( fcn ): wrap a function in a try/catch block.
• tryRequire( id ): wrap require in a try/catch block.
• trythen( x, y ): if a function does not throw, return the function return value; otherwise, return the return value of a second function.

General Utilities

• commonKeysIn( obj1, obj2[, obj3[,...,objN]] ): return the common own and inherited property names of two or more objects.
• constructorName( value ): determine the name of a value's constructor.
• convertPath( from, to ): convert between POSIX and Windows paths.
• copy( value[, level] ): copy or deep clone a value to an arbitrary depth.
• decorateAfter( fcn, arity, after[, thisArg] ): decorate a provided function such that the function's return value is provided as an argument to another function.
• dirname( path ): return a directory name.
• dsv: utilities for working with data formatted as delimiter-separated values (DSV).
• rescape( str ): escape a regular expression string or pattern.
• evil( str ): alias for eval global.
• extname( filename ): return a filename extension.
• getGlobal( [codegen] ): return the global object.
• ifelse( bool, x, y ): if a condition is truthy, return x; otherwise, return y.
• ifthen( bool, x, y ): if a condition is truthy, invoke x; otherwise, invoke y.
• inherit( ctor, superCtor ): implement prototypical inheritance by replacing the prototype of one constructor with the prototype of another constructor.
• objectKeys( obj ): return an array of an object's own enumerable property names.
• mapReduceRight( arr, initial, mapper, reducer[, thisArg ] ): perform a single-pass map-reduce operation against each element in an array while iterating from right to left and return the accumulated result.
• mapReduce( arr, initial, mapper, reducer[, thisArg ] ): perform a single-pass map-reduce operation against each element in an array and return the accumulated result.
• mapRight( arr, fcn[, thisArg] ): apply a function to each element in an array and assign the result to an element in an output array, iterating from right to left.
• map( arr, fcn[, thisArg] ): apply a function to each element in an array and assign the result to an element in an output array.
• map2Right( x, y, fcn[, thisArg] ): apply a function to elements in two input arrays while iterating from right to left and assign the results to an output array.
• map2( x, y, fcn[, thisArg] ): apply a function to elements in two input arrays and assign the results to an output array.
• map2d( arr, fcn[, thisArg] ): apply a function to each nested element in an array of arrays and assign the result to a nested element in a new array of arrays.
• map3d( arr, fcn[, thisArg] ): apply a function to each nested element in a three-dimensional nested array and assign the result to a nested element in a new three-dimensional nested array.
• map4d( arr, fcn[, thisArg] ): apply a function to each nested element in a four-dimensional nested array and assign the result to a nested element in a new four-dimensional nested array.
• map5d( arr, fcn[, thisArg] ): apply a function to each nested element in a five-dimensional nested array and assign the result to a nested element in a new five-dimensional nested array.
• naryFunction( fcn, arity[, thisArg] ): create a function that invokes a provided function with a specified number of arguments.
• nativeClass( value ): determine the specification defined classification of an object.
• nextTick( clbk[, ...args] ): add a callback to the "next tick queue".
• openURL(): open a URL.
• parallel( files, [options,] clbk ): execute scripts in parallel.
• parseJSON( str[, reviver] ): parse a string as JSON.
• realmax( dtype ): return the maximum finite value capable of being represented by a numeric real type.
• realmin( dtype ): return the smallest positive normal value capable of being represented by a numeric real type.
• reFromString( str ): create a regular expression from a regular expression string.
• safeintmax( dtype ): return the maximum safe integer capable of being represented by a numeric real type.
• safeintmin( dtype ): return the minimum safe integer capable of being represented by a numeric real type.
• sizeOf( dtype ): return the size (in bytes) of the canonical binary representation of a specified numeric type.
• thunk( fcn[, ...args] ): generate a thunk.
• timeit( code, [options,] clbk ): time a snippet.
• typemax( dtype ): return the maximum value of a specified numeric type.
• typemin( dtype ): return the minimum value of a specified numeric type.
• typeOf( value ): determine a value's type.

Examples

var objectKeys = require( '@stdlib/utils/keys' );
var utils = require( '@stdlib/utils' );

console.log( objectKeys( utils ) );

---

Notice

This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.

Community

---

License

See LICENSE.

Copyright

Copyright © 2016-2023. The Stdlib Authors.