js-data

Namespace: utils

utils

Utility methods used by JSData.

Details
Type Source
Object utils.js, line 1
Example 
import {utils} from 'js-data'
console.log(utils.isString('foo')) // true

Members

<static> Promise

Reference to the Promise constructor used by JSData. Defaults to window.Promise or global.Promise.

Details
Type Since Source
Function 3.0.0 utils.js, line 68
Example 

import Promise from 'bluebird'
import {utils} from 'js-data'
utils.Promise = Promise

Methods

<static> addHiddenPropsToTarget(target, props)

Define hidden (non-enumerable), writable properties on target from the provided props.

Method parameters:
Name Type Description
target Object

That to which props should be added.
props Object

Properties to be added to target.
Details
Since Source
3.0.0 utils.js, line 175
Example 
import {utils} from 'js-data'
function Cat () {}
utils.addHiddenPropsToTarget(Cat.prototype, {
  say () {
    console.log('meow')
  }
})
const cat = new Cat()
cat.say() // "meow"

<static> areDifferent(a, b, opts)

Return whether the two objects are deeply different.

Method parameters:
Name Type Argument Description
a Object

Base object.
b Object

Comparison object.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
equalsFn Function <optional>
 utils.deepEqual

Equality function.
ignore Array <optional>
 []

Array of strings or RegExp of fields to ignore.
Return value:
Type Description
Boolean

Whether the two objects are deeply different.
Details
Since Source See
3.0.0 utils.js, line 206
Example 
import {utils} from 'js-data'
utils.areDifferent({}, {}) // false
utils.areDifferent({ a: 1 }, { a: 1 }) // false
utils.areDifferent({ foo: 'bar' }, {}) // true

<static> classCallCheck(instance, ctor)

Verified that the given constructor is being invoked via new, as opposed to just being called like a normal function.

Method parameters:
Name Type Description
instance *

Instance that is being constructed.
ctor Constructor

Constructor function used to construct the instance.
Throws:

Throws an error if the constructor is being improperly invoked.

Type
Error
Details
Since Source
3.0.0 utils.js, line 234
Example 
import {utils} from 'js-data'
function Cat () {
  utils.classCallCheck(this, Cat)
}
const cat = new Cat() // this is ok
Cat() // this throws an error

<static> copy(from, to, stackFrom, stackTo, blacklist, plain)

Deep copy a value.

Method parameters:
Name Type Argument Description
from *

Value to deep copy.
to * <optional>

Destination object for the copy operation.
stackFrom * <optional>

For internal use.
stackTo * <optional>

For internal use.
blacklist Array.<String> | Array.<RegExp> <optional>

List of strings or RegExp of properties to skip.
plain Boolean <optional>

Whether to make a plain copy (don't try to use original prototype).
Return value:
Type Description
*

Deep copy of from.
Details
Since Source
3.0.0 utils.js, line 281
Example 
import {utils} from 'js-data'
const a = { foo: { bar: 'baz' } }
const b = utils.copy(a)
a === b // false
utils.areDifferent(a, b) // false

<static> deepEqual(a, b)

Check whether the two provided objects are deeply equal.

Method parameters:
Name Type Description
a Object

First object in the comparison.
b Object

Second object in the comparison.
Return value:
Type Description
Boolean

Whether the two provided objects are deeply equal.
Details
Since Source See
3.0.0 utils.js, line 1458
Example 
import {utils} from 'js-data'

const objA = {
  name: 'John',
  id: 27,
  nested: {
    item: 'item 1',
    colors: ['red', 'green', 'blue']
  }
}

const objB = {
  name: 'John',
  id: 27,
  nested: {
    item: 'item 1',
    colors: ['red', 'green', 'blue']
  }
}

console.log(utils.deepEqual(a,b)) // true
objB.nested.colors.add('yellow') // make a change to a nested object's array
console.log(utils.deepEqual(a,b)) // false

<static> deepFillIn(dest, source)

Recursively shallow fill in own enumerable properties from source to dest.

Method parameters:
Name Type Description
dest Object

The destination object.
source Object

The source object.
Details
Since Source See
3.0.0 utils.js, line 356
Example 
import {utils} from 'js-data'
const a = { foo: { bar: 'baz' }, beep: 'boop' }
const b = { beep: 'bip' }
utils.deepFillIn(b, a)
console.log(b) // {"foo":{"bar":"baz"},"beep":"bip"}

<static> deepMixIn(dest, source)

Recursively shallow copy enumerable properties from source to dest.

Method parameters:
Name Type Description
dest Object

The destination object.
source Object

The source object.
Details
Since Source See
3.0.0 utils.js, line 388
Example 
import {utils} from 'js-data'
const a = { foo: { bar: 'baz' }, beep: 'boop' }
const b = { beep: 'bip' }
utils.deepFillIn(b, a)
console.log(b) // {"foo":{"bar":"baz"},"beep":"boop"}

<static> diffObjects(newObject, oldObject, opts)

Return a diff of the base object to the comparison object.

Method parameters:
Name Type Argument Description
newObject Object

Comparison object.
oldObject Object

Base object.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
equalsFn Function <optional>
 utils.deepEqual

Equality function.
ignore Array <optional>
 []

Array of strings or RegExp of fields to ignore.
Return value:
Type Description
Object

The diff from the base object to the comparison object.
Details
Since Source See
3.0.0 utils.js, line 420
Example 
import {utils} from 'js-data'
const oldObject = { foo: 'bar', a: 1234 }
const newObject = { beep: 'boop', a: 5678 }
const diff = utils.diffObjects(oldObject, newObject)
console.log(diff.added) // {"beep":"boop"}
console.log(diff.changed) // {"a":5678}
console.log(diff.removed) // {"foo":undefined}

<static> equal(a, b)

Return whether the two values are equal according to the == operator.

Method parameters:
Name Type Description
a *

First value in the comparison.
b *

Second value in the comparison.
Return value:
Type Description
Boolean

Whether the two values are equal according to ==.
Details
Since Source
3.0.0 utils.js, line 488
Example 
import {utils} from 'js-data'
console.log(utils.equal(1,1)) // true
console.log(utils.equal(1,'1')) // true
console.log(utils.equal(93, 66)) // false

<static> err(domain, target)

Produce a factory function for making Error objects with the provided metadata. Used throughout the various js-data components.

Method parameters:
Name Type Description
domain String

Namespace.
target String

Target.
Return value:
Type Description
Function

Factory function.
Details
Since Source
3.0.0 utils.js, line 507
Example 
import {utils} from 'js-data'
const errorFactory = utils.err('domain', 'target')
const error400 = errorFactory(400, 'expected type', 'actual type')
console.log(error400) // [Error: [domain:target] expected: expected type, found: string
http://www.js-data.io/v3.0/docs/errors#400]

<static> eventify(target, getter, setter)

Add eventing capabilities into the target object.

Method parameters:
Name Type Argument Description
target Object

Target object.
getter Function <optional>

Custom getter for retrieving the object's event listeners.
setter Function <optional>

Custom setter for setting the object's event listeners.
Details
Since Source
3.0.0 utils.js, line 533
Example 
import {utils} from 'js-data'
const user = { name: 'John' }
utils.eventify(user)
user.on('foo', () => console.log(arguments))
user.emit('foo', 1, 'bar') // should log to console values (1, "bar")

<static> extend(props, props)

Used for sublcassing. Invoke this method in the context of a superclass to to produce a subclass based on props and classProps.

Method parameters:
Name Type Description
props Object

Instance properties for the subclass.

Properties
Name Type Argument Description
constructor Object <optional>

Provide a custom constructor function to use as the subclass.
props Object

Static properties for the subclass.
Return value:
Type Description
Constructor

A new subclass.
Details
Since Source
3.0.0 utils.js, line 609
Example 
import {utils} from 'js-data'
function Animal () {}
Animal.extend = utils.extend
const Cat = Animal.extend({
  say () {
    console.log('meow')
  }
})
const cat = new Cat()
cat instanceof Animal // true
cat instanceof Cat // true
cat.say() // "meow"

<static> fillIn(dest, source)

Shallow copy own enumerable properties from src to dest that are on src but are missing from `dest.

Method parameters:
Name Type Description
dest Object

The destination object.
source Object

The source object.
Details
Since Source See
3.0.0 utils.js, line 686
Example 
import {utils} from 'js-data'
const a = { foo: 'bar', beep: 'boop' }
const b = { beep: 'bip' }
utils.fillIn(b, a)
console.log(b) // {"foo":"bar","beep":"bip"}

<static> findIndex(array, fn)

Find the last index of an item in an array according to the given checker function.

Method parameters:
Name Type Description
array Array

The array to search.
fn Function

Checker function.
Return value:
Type Description
Number

Index if found or -1 if not found.
Details
Since Source
3.0.0 utils.js, line 712
Example 
import {utils} from 'js-data'

const john = { name: 'John', age: 20 }
const sara = { name: 'Sara', age: 25 }
const dan = { name: 'Dan', age: 20 }
const users = [john, sara, dan]

console.log(utils.findIndex(users, (user) => user.age === 25)) // 1
console.log(utils.findIndex(users, (user) => user.age > 19)) // 2
console.log(utils.findIndex(users, (user) => user.name === 'John')) // 0
console.log(utils.findIndex(users, (user) => user.name === 'Jimmy')) // -1

<static> forEachRelation(mapper, opts, fn, thisArg)

Recursively iterate over a Mapper's relations according to opts.with.

Method parameters:
Name Type Description
mapper Mapper

Mapper.
opts Object

Configuration options.
fn Function

Callback function.
thisArg *

Execution context for the callback function.
Details
Since Source
3.0.0 utils.js, line 748

<static> forOwn(object, fn, thisArg)

Iterate over an object's own enumerable properties.

Method parameters:
Name Type Argument Description
object Object

The object whose properties are to be enumerated.
fn Function

Iteration function.
thisArg Object <optional>

Content to which to bind fn.
Details
Since Source
3.0.0 utils.js, line 769
Example 
import {utils} from 'js-data'
const a = { b: 1, c: 4 }
let sum = 0
utils.forOwn(a, function (value, key) {
  sum += value
})
console.log(sum) // 5

<static> fromJson(json)

Proxy for JSON.parse.

Method parameters:
Name Type Description
json String

JSON to parse.
Return value:
Type Description
Object

Parsed object.
Details
Since Source See
3.0.0 utils.js, line 798
Example 
import {utils} from 'js-data'

const a = utils.fromJson('{"name" : "John"}')
console.log(a) // { name: 'John' }

<static> get(object, prop)

Retrieve the specified property from the given object. Supports retrieving nested properties.

Method parameters:
Name Type Description
object Object

Object from which to retrieve a property's value.
prop String

Property to retrieve.
Return value:
Type Description
*

Value of the specified property.
Details
Since Source See
3.0.0 utils.js, line 817
Example 
import {utils} from 'js-data'
const a = { foo: { bar: 'baz' }, beep: 'boop' }
console.log(utils.get(a, 'beep')) // "boop"
console.log(utils.get(a, 'foo.bar')) // "baz"

<static> getSuper(instance, isCtor)

Return the superclass for the given instance or subclass. If an instance is provided, then finds the parent class of the instance's constructor.

Method parameters:
Name Type Argument Default Description
instance Object | Function

Instance or constructor.
isCtor Boolean <optional>
 false

Whether instance is a constructor.
Return value:
Type Description
Constructor

The superclass (grandparent constructor).
Details
Since Source
3.0.0 utils.js, line 851
Example 
import {utils} from 'js-data'
// using ES2015 classes
class Foo {}
class Bar extends Foo {}
const barInstance = new Bar()
let baseType = utils.getSuper(barInstance)
console.log(Foo === baseType) // true

// using Function constructor with utils.extend
function Foo () {}
Foo.extend = utils.extend
const Bar = Foo.extend()
const barInstance = new Bar()
let baseType = utils.getSuper(barInstance)
console.log(Foo === baseType) // true

<static> intersection(array1, array2)

Return the intersection of two arrays.

Method parameters:
Name Type Description
array1 Array

First array.
array2 Array

Second array.
Return value:
Type Description
Array

Array of elements common to both arrays.
Details
Since Source
3.0.0 utils.js, line 886
Example 
import {utils} from 'js-data'
const arrA = ['green', 'red', 'blue', 'red']
const arrB = ['green', 'yellow', 'red']
const intersected = utils.intersection(arrA, arrB)

console.log(intersected) // ['green', 'red'])

<static> isArray(value)

Proxy for Array.isArray.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is an array.
Details
Since Source
3.0.0 utils.js, line 923
Example 
import {utils} from 'js-data'
const a = [1,2,3,4,5]
const b = { foo: "bar" }
console.log(utils.isArray(a)) // true
console.log(utils.isArray(b)) // false

<static> isBlacklisted(prop, blacklist)

Return whether prop is matched by any string or regular expression in blacklist.

Method parameters:
Name Type Description
prop String

The name of a property to check.
blacklist Array

Array of strings and regular expressions.
Return value:
Type Description
Boolean

Whether prop was matched.
Details
Since Source
3.0.0 utils.js, line 940
Example 
import {utils} from 'js-data'
const blacklist = [/^\$hashKey/g, /^_/g, 'id']
console.log(utils.isBlacklisted("$hashKey", blacklist)) // true
console.log(utils.isBlacklisted("id", blacklist)) // true
console.log(utils.isBlacklisted("_myProp", blacklist)) // true
console.log(utils.isBlacklisted("my_id", blacklist)) // false

<static> isBoolean(value)

Return whether the provided value is a boolean.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is a boolean.
Details
Since Source
3.0.0 utils.js, line 972
Example 
import {utils} from 'js-data'
const a = true
const b = { foo: "bar" }
console.log(utils.isBoolean(a)) // true
console.log(utils.isBoolean(b)) // false

<static> isDate(value)

Return whether the provided value is a date.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Date

Whether the provided value is a date.
Details
Since Source
3.0.0 utils.js, line 991
Example 
import {utils} from 'js-data'
const a = new Date()
const b = { foo: "bar" }
console.log(utils.isDate(a)) // true
console.log(utils.isDate(b)) // false

<static> isFunction(value)

Return whether the provided value is a function.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is a function.
Details
Since Source
3.0.0 utils.js, line 1010
Example 
import {utils} from 'js-data'
const a = function (){ console.log('foo bar')}
const b = { foo: "bar" }
console.log(utils.isFunction(a)) // true
console.log(utils.isFunction(b)) // false

<static> isInteger(value)

Return whether the provided value is an integer.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is an integer.
Details
Since Source
3.0.0 utils.js, line 1029
Example 
import {utils} from 'js-data'
const a = 1
const b = 1.25
const c = '1'
console.log(utils.isInteger(a)) // true
console.log(utils.isInteger(b)) // false
console.log(utils.isInteger(c)) // false

<static> isNull(value)

Return whether the provided value is null.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is null.
Details
Since Source
3.0.0 utils.js, line 1050
Example 
import {utils} from 'js-data'
const a = null
const b = { foo: "bar" }
console.log(utils.isNull(a)) // true
console.log(utils.isNull(b)) // false

<static> isNumber(value)

Return whether the provided value is a number.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is a number.
Details
Since Source
3.0.0 utils.js, line 1069
Example 
import {utils} from 'js-data'
const a = 1
const b = -1.25
const c = '1'
console.log(utils.isNumber(a)) // true
console.log(utils.isNumber(b)) // true
console.log(utils.isNumber(c)) // false

<static> isObject(value)

Return whether the provided value is an object.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is an object.
Details
Since Source
3.0.0 utils.js, line 1091
Example 
import {utils} from 'js-data'
const a = { foo: "bar" }
const b = 'foo bar'
console.log(utils.isObject(a)) // true
console.log(utils.isObject(b)) // false

<static> isRegExp(value)

Return whether the provided value is a regular expression.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is a regular expression.
Details
Since Source
3.0.0 utils.js, line 1110
Example 
import {utils} from 'js-data'
const a = /^\$.+$/ig
const b = new RegExp('^\$.+$', 'ig')
const c = { foo: "bar" }
console.log(utils.isRegExp(a)) // true
console.log(utils.isRegExp(b)) // true
console.log(utils.isRegExp(c)) // false

<static> isSorN(value)

Return whether the provided value is a string or a number.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is a string or a number.
Details
Since Source
3.0.0 utils.js, line 1131
Example 
import {utils} from 'js-data'
console.log(utils.isSorN('')) // true
console.log(utils.isSorN(-1.65)) // true
console.log(utils.isSorN('my string')) // true
console.log(utils.isSorN({})) // false
console.log(utils.isSorN([1,2,4])) // false

<static> isString(value)

Return whether the provided value is a string.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is a string.
Details
Since Source
3.0.0 utils.js, line 1151
Example 
import {utils} from 'js-data'
console.log(utils.isString('')) // true
console.log(utils.isString('my string')) // true
console.log(utils.isString(100)) // false
console.log(utils.isString([1,2,4])) // false

<static> isUndefined(value)

Return whether the provided value is a undefined.

Method parameters:
Name Type Description
value *

The value to test.
Return value:
Type Description
Boolean

Whether the provided value is a undefined.
Details
Since Source
3.0.0 utils.js, line 1170
Example 
import {utils} from 'js-data'
const a = undefined
const b = { foo: "bar"}
console.log(utils.isUndefined(a)) // true
console.log(utils.isUndefined(b.baz)) // true
console.log(utils.isUndefined(b)) // false
console.log(utils.isUndefined(b.foo)) // false

<static> logify(target)

Mix in logging capabilities to the target.

Method parameters:
Name Type Description
target *

The target.
Details
Since Source
3.0.0 utils.js, line 1191
Example 
import {utils} from 'js-data'
const a = { foo: "bar"}

// Add standard logging to an object
utils.logify(a)
a.log('info', 'test log info') // output 'test log info' to console.

// Toggle debug output of an object
a.dbg('test debug output') // does not output because debug is off.
a.debug = true
a.dbg('test debug output') // output 'test debug output' to console.

<static> noDupeAdd(array, record, fn)

Adds the given record to the provided array only if it's not already in the array.

Method parameters:
Name Type Description
array Array

The array.
record *

The value to add.
fn Function

Callback function passed to utils.findIndex.
Details
Since Source
3.0.0 utils.js, line 1236
Example 
import {utils} from 'js-data'
const colors = ['red', 'green', 'yellow']

console.log(colors.length) // 3
utils.noDupeAdd(colors, 'red')
console.log(colors.length) // 3, red already exists

utils.noDupeAdd(colors, 'blue')
console.log(colors.length) // 4, blue was added

<static> omit(props, keys)

Return a shallow copy of the provided object, minus the properties specified in keys.

Method parameters:
Name Type Description
props Object

The object to copy.
keys Array.<String>

Array of strings, representing properties to skip.
Return value:
Type Description
Object

Shallow copy of props, minus keys.
Details
Since Source
3.0.0 utils.js, line 1267
Example 
import {utils} from 'js-data'
const a = { name: 'John', $hashKey: 1214910 }

let b = utils.omit(a, ['$hashKey'])
console.log(b) // { name: 'John' }

<static> pick(props, keys)

Return a shallow copy of the provided object, but only include the properties specified in keys.

Method parameters:
Name Type Description
props Object

The object to copy.
keys Array.<String>

Array of strings, representing properties to keep.
Return value:
Type Description
Object

Shallow copy of props, but only including keys.
Details
Since Source
3.0.0 utils.js, line 1294
Example 
import {utils} from 'js-data'
const a = { name: 'John', $hashKey: 1214910 }

let b = utils.pick(a, ['$hashKey'])
console.log(b) // { $hashKey: 1214910 }

<static> plainCopy(value)

Return a plain copy of the given value.

Method parameters:
Name Type Description
value *

The value to copy.
Return value:
Type Description
*

Plain copy of value.
Details
Since Source See
3.0.0 utils.js, line 1318
Example 
import {utils} from 'js-data'
const a = { name: 'John' }
let b = utils.plainCopy(a)
console.log(a === b) // false

<static> reject(value)

Shortcut for utils.Promise.reject(value).

Method parameters:
Name Type Argument Description
value * <optional>

Value with which to reject the Promise.
Return value:
Type Description
Promise

Promise reject with value.
Details
Since Source See
3.0.0 utils.js, line 1337
Example 
import {utils} from 'js-data'

utils.reject("Testing static reject").then(function(data) {
  // not called
}).catch(function(reason) {
  console.log(reason); // "Testing static reject"
})

<static> remove(array, fn)

Remove the last item found in array according to the given checker function.

Method parameters:
Name Type Description
array Array

The array to search.
fn Function

Checker function.
Details
Source
utils.js, line 1359
Example 
import {utils} from 'js-data'

const colors = ['red', 'green', 'yellow', 'red']
utils.remove(colors, (color) => color === 'red')
console.log(colors) // ['red', 'green', 'yellow']

<static> resolve(value)

Shortcut for utils.Promise.resolve(value).

Method parameters:
Name Type Argument Description
value * <optional>

Value with which to resolve the Promise.
Return value:
Type Description
Promise

Promise resolved with value.
Details
Since Source See
3.0.0 utils.js, line 1400
Example 
import {utils} from 'js-data'

utils.resolve("Testing static resolve").then(function(data) {
  console.log(data); // "Testing static resolve"
}).catch(function(reason) {
  // not called
})

<static> set(object, path, value)

Set the value at the provided key or path.

Method parameters:
Name Type Argument Description
object Object

The object on which to set a property.
path String | Object

The key or path to the property. Can also pass in an object of path/value pairs, which will all be set on the target object.
value * <optional>

The value to set.
Details
Source
utils.js, line 1404
Example 
import {utils} from 'js-data'

const john = {
  name: 'John',
  age: 25,
  parent: {
    name: 'John's Mom',
    age: 50
  }
}
// set value by key
utils.set(john, 'id', 98)
console.log(john.id) // 98

// set value by path
utils.set(john, 'parent.id', 20)
console.log(john.parent.id) // 20

// set value by path/value map
utils.set(john, {
  'id': 1098,
  'parent': { id: 1020 },
  'parent.age': '55'
})
console.log(john.id) // 1098
console.log(john.parent.id) // 1020
console.log(john.parent.age) // 55

<static> toJson(value)

Proxy for JSON.stringify.

Method parameters:
Name Type Description
value *

Value to serialize to JSON.
Return value:
Type Description
String

JSON string.
Details
Since Source See
3.0.0 utils.js, line 1529
Example 
import {utils} from 'js-data'

const a = { name: 'John' }
let jsonVal = utils.toJson(a)
console.log(jsonVal) // '{"name" : "John"}'

<static> unset(object, path)

Unset the value at the provided key or path.

Method parameters:
Name Type Description
object Object

The object from which to delete the property.
path String

The key or path to the property.
Details
Since Source See
3.0.0 utils.js, line 1547
Example 
import {utils} from 'js-data'

const john = {
  name: 'John',
  age: 25,
  parent: {
    name: 'John's Mom',
    age: 50
  }
}

utils.unset(john, age)
utils.unset(john, parent.age)

console.log(john.age) // null
console.log(john.parent.age) // null