Utilities

Wiki ▸ API Reference ▸ Utilities

Utilities

Type Checkers

# dl.isObject(value)

Checks if value is an Object.

# dl.isFunction(value)

Checks if value is a Function.

# dl.isString(value)

Checks if value is a String.

# dl.isArray(value)

Checks if value is an Array.

# dl.isNumber(value)

Checks if value is a Number.

# dl.isBoolean(value)

Checks if value is a Boolean.

# dl.isDate(value)

Checks if value is a Date.

# dl.isValid(value)

Checks if value is not null, undefined or NaN.

# dl.isBuffer(value)

Checks if value is a Buffer instance.

Type Conversion

# dl.number(value)

Coerce value to a Number, ignoring nulls. Empty strings are mapped to null values.

# dl.boolean(value)

Coerce value to a Boolean, ignoring nulls. Empty strings are mapped to null values.

# dl.date(value)

Coerce (parse) value to a Date, ignoring nulls. Empty strings are mapped to null values.

# dl.array(value)

If value is an array or null, returns it as-is. Otherwise, returns the single-element array [value].

# dl.str(value)

Coerce value to a JSON-style string with quotation characters escaped as needed.

Object Helpers

# dl.duplicate(value)

Creates a deep duplicate of an object. Internally, this method round-trips the value through JSON.stringify and JSON.parse. As a result, non-JSON-serializable values (for example, Function objects) are not duplicated.

# dl.equal(a, b)

Checks if a and b are deeply equal. Internally, this method calls JSON.stringify and compares the resulting strings. As a result, any non-JSON-serializable values will not be compared.

# dl.extend(object[, a, b, …])

Extend object by copying (in order) the properties of all other input objects.

# dl.keys(object)

Extract and return an array of object's keys. All properties of object, including those defined up the prototype chain, will be returned.

# dl.vals(object)

Extract and return an array of an object's values. Values for all properties of object, including those defined up the prototype chain, will be returned.

# dl.toMap(array[, accessor])

Generate a boolean map object for array. An optional accessor function or property string may be specified, which is equivalent to calling array.map(dl.$(accessor)) before generating the map.

dl.toMap([1, 2, 3, 'a', 1]); // {'1': 1, '2': 1, '3': 1, 'a': 1}
dl.toMap([{x:1}, {x:1}, {x:'a'}], 'x'); // {'1': 1, 'a': 1}

Object Properties

# dl.field(string)

Parse a string property descriptor (e.g., "foo.bar") to an array.

dl.field("foo.bar.baz"); // ['foo', 'bar', 'baz']

# dl.accessor(field)

Parse a field property descriptor and return a corresponding accessor (getter) function. If field is a function or is null, it is returned as-is. Otherwise, field is parsed using dl.field and the result is used to create an accessor function that returns the field value for an input object.

dl.accessor('foo')({foo: 1, bar: 2}); // 1

# dl.$(field)

Convenience shorthand for dl.accessor.

dl.$('foo')({foo: 1, bar: 2}); // 1

# dl.mutator(field)

Parse a field property descriptor and return a corresponding mutator (setter) function. The argument field is parsed using dl.field and the result is used to create a mutator function that updates the field value for an input object.

var obj = {foo: 1, bar: 2};
dl.mutator('foo')(obj, 3);
obj.foo === 3; // true

# dl.$valid(field)

Create an accessor that indicates if an extracted value is valid. Valid values are those that are not null, undefined, or NaN (see dl.isValid).

dl.$valid('foo')({foo: 'hello', bar: 2}); // true
dl.$valid('foo')({foo: null, bar: 2});    // false

# dl.$length(field)

Create an accessor that extracts the length of String or Array values.

dl.$length('foo')({foo: 'hello', bar: 2}); // 5

# dl.$in(field, valueset)

Create an accessor that tests if an extracted value is contained in a set. The argument valueset can either be an array of values or an object with set values as keys. If an object is provided, only keys that map to truthy values will be considered members of the set.

dl.$in('foo', ['hello', 'world'])({foo: 'hello'});       // true
dl.$in('foo', ['hello', 'world'])({foo: 'bye'});         // false
dl.$in('foo', {'hello':1, 'world':1})({foo: 'hello'});   // true
dl.$in('foo', {'hello':1, 'world':1})({foo: 'goodbye'}); // false
dl.$in('foo', {'hello':0, 'world':1})({foo: 'hello'});   // false

# dl.$year(field)

Create an accessor that extracts the year from Date or timestamp values.

dl.$year('d')({d: new Date(2015, 4, 14, 7, 37)}); // 2015

# dl.$utcYear(field)

Create an accessor that extracts the Coordinated Universal Time (UTC) year from Date or timestamp values.

dl.$utcYear('d')({d: Date.UTC(2015, 4, 14, 7, 37)}); // 2015

# dl.$month(field)

Create an accessor that extracts the month from Date or timestamp values.

dl.$month('d')({d: new Date(2015, 4, 14, 7, 37)}); // 4 (May)

# dl.$utcMonth(field)

Create an accessor that extracts the Coordinated Universal Time (UTC) month from Date or timestamp values.

dl.$utcMonth('d')({d: Date.UTC(2015, 4, 14, 7, 37)}); // 4 (May)

# dl.$date(field)

Create an accessor that extracts the date (day of the month) from Date or timestamp values.

dl.$date('d')({d: new Date(2015, 4, 14, 7, 37)}); // 14

# dl.$utcDate(field)

Create an accessor that extracts the Coordinated Universal Time (UTC) date (day of the month) from Date or timestamp values.

dl.$utcDate('d')({d: Date.UTC(2015, 4, 14, 7, 37)}); // 14

# dl.$day(field)

Create an accessor that extracts the day of the week from Date or timestamp values.

dl.$day('d')({d: new Date(2015, 4, 14, 7, 37)}); // 4 (Thursday)

# dl.$utcDay(field)

Create an accessor that extracts the Coordinated Universal Time (UTC) day of the week from Date or timestamp values.

dl.$utcDay('d')({d: Date.UTC(2015, 4, 14, 7, 37)}); // 4 (Thursday)

# dl.$hour(field)

Create an accessor that extracts the hour from Date or timestamp values.

dl.$hour('d')({d: new Date(2015, 4, 14, 7, 37)}); // 7

# dl.$utcHour(field)

Create an accessor that extracts the Coordinated Universal Time (UTC) hour from Date or timestamp values.

dl.$utcHour('d')({d: Date.UTC(2015, 4, 14, 7, 37)}); // 7

# dl.$minute(field)

Create an accessor that extracts the minutes from Date or timestamp values.

dl.$minute('d')({d: new Date(2015, 4, 14, 7, 37)}); // 37

# dl.$utcMinute(field)

Create an accessor that extracts the Coordinated Universal Time (UTC) minutes from Date or timestamp values.

dl.$utcMinute('d')({d: Date.UTC(2015, 4, 14, 7, 37)}); // 37

# dl.$second(field)

Create an accessor that extracts the seconds from Date or timestamp values.

dl.$second('d')({d: new Date(2015, 4, 14, 7, 37, 29)}); // 29

# dl.$utcSecond(field)

Create an accessor that extracts the Coordinated Universal Time (UTC) seconds from Date or timestamp values.

dl.$utcSecond('d')({d: Date.UTC(2015, 4, 14, 7, 37, 29)}); // 29

Sorting

# dl.comparator(sortby)

Given either a string or array of strings as input, return a comparator function (suitable for use by Array.sort) that sorts values according to the given fields. The argument sortby can be either a single string or an array of strings. Each string value should indicate an object property to sort by. In addition, each string value may be prepended by '+' (to indicate ascending order, the default) or '-' (to indicate descending order).

var list = [{a:3, b:2}, {a:1, b:4}, {a:2, b:2}];
list.sort(dl.comparator('a')); // [{a:1, b:4}, {a:2, b:2}, {a:3, b:2}];
list.sort(dl.comparator(['+b', '-a'])); // [{a:3, b:2}, {a:2, b:2}, {a:1, b:4}];

# dl.cmp(a, b)

A default comparison function that sorts data in natural order.

# dl.numcmp(a, b)

A default comparison function for numerical data.

# dl.stablesort(array, sortby, key)

An alternative sorting method with guaranteed stable ordering. Sorts the input array using the comparator function sortby. In the case of ties, elements are compared using their original index in the array. The required key function argument should return a unique key value for each object.

# dl.permute(array)

Performs an in-place Fisher-Yates permutation of an array.

Strings

# dl.keystr(values)

Map the values array to a string to use as a hash key.

# dl.pad(string, length[, position, padchar])

Pads a string such that it is exactly length characters long. If the length of the input string already matches of exceeds length then it is returned as-is. The optional position argument indicates to what side(s) of the string the padding should be applied. The accepted options are 'left', 'right' or 'center'; the default is 'right'. The optional padchar argument (a string of length 1) indicates which character should be used to pad the text. By default the string is padded with whitespace.

dl.pad('hi', 5, 'right');   // 'hi   '
dl.pad('hi', 5, 'left');    // '   hi'
dl.pad('hi', 5, 'center');  // ' hi  '
dl.pad('hi', 5, null, '!'); // 'hi!!!'

# dl.truncate(string, length[, position, word, ellipsis])

Truncate string such that it is no more than length characters long. The optional argument position indicates if the string should be truncated (have text removed) from the 'left', 'right' or 'center'. If true, the word argument indicates that the method should attempt to truncate to word boundaries, even if this results in a string shorter than length. The ellipsis argument indicates the string that should be used for missing text; the default is … (Unicode U+2606).

dl.truncate('123456789', 5, 'right');   // '1234…'
dl.truncate('123456789', 5, 'left');    // '…6789'
dl.truncate('123456789', 5, 'center');  // '12…89'

Miscellaneous

# dl.identity(value)

An identity function that simply returns the input value.

# dl.length(value)

Helper function that returns the length of a String or Array value.

# dl.true()

Helper function that simply returns the value true.

# dl.false()

Helper function that simply returns the value false.