Namespace: JSUtils

utils/jsutils~JSUtils

Methods

(static) arrayMap(arr) → {Map}

Return a two-way Map that maps each element to its index (and vice-versa).

Return a two-way Map that maps each element to its index (and vice-versa).

Parameters:
Name Type Description
arr Array
Source:
Returns:
Type
Map

(static) counterToBase64()

Convert a counter to a Base64 encoded string.

Convert a counter to a Base64 encoded string. Padding is stripped. \,+ are replaced with _,- respectively. Warning: Max integer is 2^31 - 1 for bitwise operations.

Source:

(static) deepEquals(a, b) → {boolean}

Determine whether two objects are identical, recursively.

Determine whether two objects are identical, recursively.

Parameters:
Name Type Description
a any
b any
Source:
Returns:
Type
boolean

(static) deepFreeze(o) → {any}

Deep-freeze an object.

Deep-freeze an object. Maps and Sets are handled with .freezeMap and .freezeSet.

Parameters:
Name Type Description
o any
Source:
See:
Returns:

Frozen object

Type
any

(static) deepFreezeButIgnore(o, ignoreFields) → {Object}

Deep freeze an object, except for the specified fields.

Deep freeze an object, except for the specified fields.

Parameters:
Name Type Description
o Object
ignoreFields Object
Source:
Returns:

Frozen object.

Type
Object

(static) elapsedTime(previousTime) → {number}

Return millisecond accurate system time differential

.

Return millisecond accurate system time differential

Parameters:
Name Type Description
previousTime number
Source:
Returns:
Type
number

(static) escapeRegExp(s) → {string}

Escape special regexp characters in a string.

Escape special regexp characters in a string.

Parameters:
Name Type Description
s string
Source:
Returns:

A regular expression string that matches the literal characters in s.

Type
string

(static) freezeMap()

ES6 maps/sets are still writable even when frozen, because they store data inside the object linked from an internal slot.

ES6 maps/sets are still writable even when frozen, because they store data inside the object linked from an internal slot. This freezes a map by disabling the mutation methods, although it's not bulletproof: you could use Map.prototype.set.call(m, ...) to still mutate the backing store.

Source:

(static) freezeSet()

This makes a set read-only.

This makes a set read-only.

Source:
See:

(static) lastItem(array) → {any}

Return the last item in an array.

Return the last item in an array.

Parameters:
Name Type Description
array Array
Source:
Returns:

The last item in array

Type
any

(static) mapObject(obj) → {Map}

Return a Map with the same initial keys and values as the given Object.

Return a Map with the same initial keys and values as the given Object.

Parameters:
Name Type Description
obj Object
Source:
Returns:
Type
Map

(static) mkPromised(callback, namesopt) → {function|Promise}

Helper function to ease migration to Promise-based control flow (aka, "after years of wandering, arrive in the Promise land").

Helper function to ease migration to Promise-based control flow (aka, "after years of wandering, arrive in the Promise land"). This function allows retrofitting an existing callback-based method to return an equivalent Promise, allowing enlightened new code to omit the callback parameter and treat it as if it had an API which simply returned a Promise for the result.

Sample use:

  // callback is node-style: callback(err, value)
  function legacyApi(param1, param2, callback) {
    callback = JSUtils.mkPromised(callback); // THIS LINE IS NEW
    ... some implementation here...
    return callback.promise; // THIS LINE IS NEW
  }
  // old-style caller, still works:
  legacyApi(x, y, function(err, value) { ... });
  // new-style caller, such hotness:
  return legacyApi(x, y).then(function(value) { ... });

The optional names parameter to mkPromised is the same as the optional second argument to Promise.promisify in https://github/cscott/prfun. It allows the use of mkPromised for legacy functions which promise multiple results to their callbacks, eg:

  callback(err, body, response);  // from npm "request" module

For this callback signature, you have two options:

  1. Pass true as the names parameter:
      function legacyRequest(options, callback) {
        callback = JSUtils.mkPromised(callback, true);
        ... existing implementation...
        return callback.promise;
      }
    This resolves the promise with the array [body, response], so a Promise-using caller looks like:
      return legacyRequest(options).then(function(r) {
        var body = r[0], response = r[1];
        ...
      }
    If you are using prfun then Promise#spread is convenient:
      return legacyRequest(options).spread(function(body, response) {
        ...
      });
  2. Alternatively (and probably preferably), provide an array of strings as the names parameter:
      function legacyRequest(options, callback) {
        callback = JSUtils.mkPromised(callback, ['body','response']);
        ... existing implementation...
        return callback.promise;
      }
    The resolved value will be an object with those fields:
      return legacyRequest(options).then(function(r) {
        var body = r.body, response = r.response;
        ...
      }
    Note that in both cases the legacy callback behavior is unchanged:
    legacyRequest(options, function(err, body, response) { ... });
Parameters:
Name Type Attributes Description
callback function | undefined
names true | Array.<string> <optional>
Source:
Returns:
  • Type
    function
  • [return.promise] A promise that will be fulfilled when the returned callback function is invoked.

    Type
    Promise

(static) pushArray()

Append an array to an accumulator using the most efficient method available.

Append an array to an accumulator using the most efficient method available. Makes sure that accumulation is O(n).

Source:

(static) rejoin() → {RegExp}

Join pieces of regular expressions together.

Join pieces of regular expressions together. This helps avoid having to switch between string and regexp quoting rules, and can also give you a poor-man's version of the "x" flag, ie:

 var re = rejoin( "(",
     /foo|bar/, "|",
     someRegExpFromAVariable
     ")", { flags: "i" } );

Note that this is basically string concatenation, except that regular expressions are converted to strings using their .source property, and then the final resulting string is converted to a regular expression.

If the final argument is a regular expression, its flags will be used for the result. Alternatively, you can make the final argument an object, with a flags property (as shown in the example above).

Source:
Returns:
Type
RegExp

(static) sortObject()

Sort keys in an object, recursively, for better reproducibility.

Sort keys in an object, recursively, for better reproducibility. (This is especially useful before serializing as JSON.)

Source:

(static) startTime() → {number}

Return accurate system time

.

Return accurate system time

Source:
Returns:
Type
number