Skip to content

PlainApi.md

Latest commit

 

History

History
366 lines (264 loc) · 8 KB

PlainApi.md

File metadata and controls

366 lines (264 loc) · 8 KB

createPath

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

Parameters

Examples

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

// Throws an error
createPath(['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 Path

createReference

Creates a Reference.

Parameters

Examples

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

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

Returns Any

dereference

retrieves a value at a reference from a store

Parameters

Examples

import { createReference, dereference } from 'referencejs';

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

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

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

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

isPath

tests whether the argument is a Path

Parameters

  • maybePath Any

Examples

import { isPath } from 'referencejs';

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

Returns Boolean

isReference

Tests whether the argument is a Reference.

Parameters

  • maybeReference Any

Examples

import { isReference, createReference } from 'referencejs';

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

Returns Any

resolveReference

Returns a new Store with value at reference

Parameters

  • store Store
  • reference Reference Reference where the value should be placed
  • value any The value to place in the store

Examples

import { createReference, resolveReference, dereference } from 'referencejs';

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

let store = {};
store = resolveReference(store, userReference, user);
dereference(store, userReference) === user;

Returns Any A new Store containing value at reference

smartDereference

Traverses val and dereferences every reference.

Parameters

Examples

import { createReference, resolveReference, smartDereference } from 'referencejs';

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

let store = {};

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

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

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

const relations = [
  {
    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 object with all references dereferenced

storeHasReference

Test if Reference is set in Store.

Parameters

Examples

import { storehasReference, createReference } from 'referencejs';

const store = {
  foo: 5,
};

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

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

Returns Boolean

PathSegment

a non-empty string, or a non-negative integer

Examples

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

Path

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

Examples

const store = {
  auth: {
    users: [
      {
        name: 'Jon'
      }
    ]
  }
}
const path = ['auth', 'users', 0, 'name'];

Reference

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

Examples

const store = {
  auth: {
    users: [
      {
        name: 'Jon'
      }
    ]
  }
}
const reference = {
  path: ['auth', 'users', 0, 'name']
}

Store

A plain JS object

Examples

const store = {
  foo: [{
    bar: 'hi'
  }]
};