Skip to content

Latest commit

 

History

History
383 lines (280 loc) · 9.33 KB

ImmutableApi.md

File metadata and controls

383 lines (280 loc) · 9.33 KB

PathSegment

a non-empty string, or a non-negative integer (index)

Examples

const pathSegmentString = 'hi';
const PathSegmentInt = 0;

isPath

tests whether the argument is a ImmutablePath

Parameters

  • maybePath Any

Examples

import { List } from 'immutable';
import { isPath } from 'referencejs/immutable';

isPath(List(['foo', 0])) === true;
isPath(['foo', 0]) === false;
isPath(List(['', -10])) === false;

Returns Boolean

isPathSegment

Tests whether the given argument is a PathSegment

Parameters

  • maybePathSegment any

Examples

// Also imports from 'referencejs/immutable'
import { isPathSegment } from 'referencejs';
isPathSegment('users') === true
isPathSegment(5) === true
isPathSegment({}) === false

Returns boolean

isReference

Tests whether the argument is an ImmutableReference. ImmutableReference is typed as a Record, however the only requirement is that it is an Immutable object where get('path') returns an ImmutablePath.

Parameters

  • maybeReference Any

Examples

import { isReference, createReference } from 'referencejs/immutable';

isReference(createReference('foo')) === true;
isReference({}) === false;
isReference(null) === false;

Returns Any

EmptyReference

A Symbol returned when a Reference or ImmutableReference is not present in Store or ImmutableStore

Examples

import { createReference, dereference } from 'referencejs';

const store = {};
const reference = createReference('nothing', 'here');
dereference(store, reference) === EmptyReference
import { Map } from 'immutable';
import { createReference, dereference } from 'referencejs/immutable';

const store = Map();
const reference = createReference('nothing', 'here');
dereference(store, reference) === EmptyReference

storeHasReference

Test if ImmutableReference is set in ImmutableStore.

Parameters

Examples

import { Map } from 'immutable';
import { storehasReference, createReference } from 'referencejs/immutable';

const store = Map({
  foo: 5,
});

const reference = createReference('foo');
const emptyRefrence = createReference('bar');

storehasReference(store, foo) === true;
storehasReference(store, emptyRefrence) === false;

Returns Boolean

resolveReference

Returns a new ImmutableStore with value at reference

Parameters

Examples

import { Map } from 'immutable';
import { createReference, resolveReference, dereference } from 'referencejs/immutable';

const user = Map({
 name: "john"
});
const userReference = createReference('auth', 'users', 'user_1');

let store = Map();
store = resolveReference(store, userReference, user);
dereference(store, userReference) === user;

Returns Any An ImmutableStore containing value at reference

createPath

Create a reference path from either an array of PathSegments, or multiple PathSegment arguments

Parameters

Examples

import { List } from 'immutable'
import { createPath } from 'referencejs/immutable';
createPath(['foo', 'bar']);
createPath('foo', 'bar');
createPath(List(['foo', 'bar']));

// Throws an error
createPath(['foo'], 'bar')
createPath(List(['foo']), 'bar');
createPath({}, 9);
  • Throws Error if both an array of PathSegments and multiple PathSegment arguments are passed
  • Throws Error if something besides a PathSegment is passed

Returns ImmutablePath

dereference

retrieves a value at a reference from a store

Parameters

Examples

import { fromJS } from 'immutable';
import { createReference, dereference } from 'referencejs/immutable';

const user = fromJS({
 name: "john"
});
const userReference = createReference('auth', 'users', 'user_1');
const store = fromJS({
  auth: {
    users: {
      user_1: user
    }
  }
});
dereference(store, userReference) === user;

Returns Any The value at reference or EmptyRefrence if value is not present

ImmutablePath

A non-empty List of strings and non-negative integers (indeces). They describe how to traverse an Immutable object to retrieve a value. You should always use createPath. This validates the ImmutablePath, future-proofs your code, and lets you switch from Plain to Immutable by changing an import path.

Examples

import { fromJS, List } from 'immutable';
const store = fromJS({
  auth: {
    users: [
      {
        name: 'Jon'
      }
    ]
  }
});
const path = List(['auth', 'users', 0, 'name']);

createReference

Creates an ImmutableReference

Parameters

Examples

import { fromJS } from 'immutable';
import { createReference } from 'referencejs/immutable'

const store = fromJS({
  foo: {
    bar: 5
  },
  baz: ['hi']
});
// create a reference to 'foo.bar' in plain JS object
createReference('foo', 'bar');
createReference(['foo', 'bar']);
createReference(List(['foo', 'bar']));

//create a reference to 'baz[0]'
createReference('baz', 0);
createReference(['baz', 0]);
createReference(List(['baz', 0]));

Returns Any

ImmutableReference

A wrapper around at ImmutablePath. You should always use createReference. This validates the ImmutableReference, future-proofs your code, and lets you switch from Plain to Immutable by changing an import path.

Examples

import { fromJS, List, Record } from 'immutable';
const store = fromJS({
  auth: {
    users: [
      {
        name: 'Jon'
      }
    ]
  }
});
const Reference = Record({ path: List() });
const reference = Reference({
  path: List(['auth', 'users', 0, 'name'])
});

smartDereference

Traverses {@param val} and dereferences every reference.

Parameters

  • store ImmutableStore
  • val The object to scan. ImmutableReferences are dereferenced, all other immutable objects are traversed, and everything else is returned unmodified.

Examples

import { fromJS, Map } from 'immutable';
import { createReference, resolveReference, smartDereference } from 'referencejs/immutable';

function createUserReference(user) {
  return createReference('users', user.id);
}

let store = Map();

const jon = Map({
 id: 'user_1',
 name: 'jon'
});
const jonReference = createUserReference(jon);
store = resolveReference(store, jonReference, jon);

const james = Map({
  id: 'user_2',
  name: 'james'
});
const jamesReference = createUserReference(james);
store = resolveReference(store, jamesReference, james);

const sally = Map({
 id: 'user_3',
 name: 'sally',
});
const sallyReference = createUserReference(sally);
store = resolveReference(store, sallyReference, sally);

const relations = fromJS([
  {
    from: jonReference,
    to: sallyReference,
    type: "husband"
  },{
    from: sallyReference,
    to: jonReference,
    type: "wife"
  },{
    from: sallyReference,
    to: jamesReference,
    type: "daughter"
  },{
    from: jonReference,
    to: jamesReference,
    type: "son-in-law"
  },{
    from: jamesReference,
    to: jonReference,
    type: "father-in-law"
  },
]);
// 'from' and 'to' will be their respective user objects in the store
const dereferencedRelations = smartDereference(store, relations);

Returns Any A new immutable object with all references dereferenced

ImmutableStore

A Map

Examples

import { fromJS } from 'immutable';
const store = fromJS({
  foo: [{
    bar: 'hi'
  }]
});