`Immstruct`

Creates a new instance of Immstruct, having it's own list of Structure instances.

Examples:

var ImmstructInstance = require('immstruct').Immstruct;
var immstruct = new ImmstructInstance();
var structure = immstruct.get({ data: });

Properties

property	type	description
`instances`	Array.	Array of `Structure` instances.

Returns Immstruct,

`immstruct.get([key], [data])`

Gets or creates a new instance of {Structure}. Provide optional key to be able to retrieve it from list of instances. If no key is provided, a random key will be generated.

Examples:

var immstruct = require('immstruct');
var structure = immstruct.get('myStruct', { foo: 'Hello' });

Parameters

param	type	description
`[key]`	string	optional: - defaults to random string
`[data]`	Object,Immutable	optional: - defaults to empty data

Returns Structure,

`immstruct.instance([name])`

Get list of all instances created.

Parameters

param	type	description
`[name]`	string	optional: - Name of the instance to get. If undefined get all instances

Returns Structure,Object.<String, Structure>,

`immstruct.clear`

Clear the entire list of Structure instances from the Immstruct instance. You would do this to start from scratch, freeing up memory.

Examples:

var immstruct = require('immstruct');
immstruct.clear();

`immstruct.remove(key)`

Remove one Structure instance from the Immstruct instances list. Provided by key

Examples:

var immstruct = require('immstruct');
immstruct('myKey', { foo: 'hello' });
immstruct.remove('myKey');

Parameters

param	type	description
`key`	string

Returns boolean,

`immstruct.withHistory([key], [limit], [data])`

Gets or creates a new instance of Structure with history (undo/redo) activated per default. Same usage and signature as regular Immstruct.get.

Provide optional key to be able to retrieve it from list of instances. If no key is provided, a random key will be generated.

Provide optional limit to cap the last number of history references that will be kept. Once limit is reached, a new history record shifts off the oldest record. The default if omitted is Infinity. Setting to 0 is the as not having history enabled in the first place.

Examples:

var immstruct = require('immstruct');
var structure = immstruct.withHistory('myStruct', 10, { foo: 'Hello' });
var structure = immstruct.withHistory(10, { foo: 'Hello' });
var structure = immstruct.withHistory('myStruct', { foo: 'Hello' });
var structure = immstruct.withHistory({ foo: 'Hello' });

Parameters

param	type	description
`[key]`	string	optional: - defaults to random string
`[limit]`	number	optional: - defaults to Infinity
`[data]`	Object,Immutable	optional: - defaults to empty data

Returns Structure,

`immstruct([key], [data])`

This is a default instance of Immstruct as well as a shortcut for creating Structure instances (See Immstruct.get and Immstruct). This is what is returned from require('immstruct').

From Immstruct.get: Gets or creates a new instance of {Structure} in the default Immstruct instance. A link to immstruct.get(). Provide optional key to be able to retrieve it from list of instances. If no key is provided, a random key will be generated.

Examples:

var immstruct = require('immstruct');
var structure = immstruct('myStruct', { foo: 'Hello' });
var structure2 = immstruct.withHistory({ bar: 'Bye' });
immstruct.remove('myStruct');
// ...

Parameters

param	type	description
`[key]`	string	optional: - defaults to random string
`[data]`	Object,Immutable	optional: - defaults to empty data

Returns Structure,Function,

`Structure([options])`

Creates a new Structure instance. Also accessible through Immstruct.Structre.

A structure is also an EventEmitter object, so it has methods as .on, .off, and all other EventEmitter methods.

For the swap event, the root structure (see structure.current) is passed as arguments, but for type specific events (add, change and delete), the actual changed value is passed.

For instance:

var structure = new Structure({ 'data': { 'foo': { 'bar': 'hello' } } });

structure.on('swap', function (newData, oldData, keyPath) {
  keyPath.should.eql(['foo', 'bar']);
  newData.toJS().should.eql({ 'foo': { 'bar': 'bye' } });
  oldData.toJS().should.eql({ 'foo': { 'bar': 'hello' } });
});

structure.cursor(['foo', 'bar']).update(function () {
 return 'bye';
});

But for change

var structure = new Structure({ 'data': { 'foo': { 'bar': 'hello' } } });

structure.on('change', function (newData, oldData, keyPath) {
  keyPath.should.eql(['foo', 'bar']);
  newData.should.eql('bye');
  oldData.should.eql('hello');
});

structure.cursor(['foo', 'bar']).update(function () {
 return 'bye';
});

All keyPaths passed to listeners are the full path to where the actual change happened

Examples:

var Structure = require('immstruct/structure');
var s = new Structure({ data: { foo: 'bar' }});

// Or:
// var Structure = require('immstruct').Structure;

Events

swap: Emitted when cursor is updated (new information is set). Is emitted on all types of changes, additions and deletions. The passed structures are always the root structure. One use case for this is to re-render design components. Callback is passed arguments: newStructure, oldStructure, keyPath.
next-animation-frame: Same as swap, but only emitted on animation frame. Could use with many render updates and better performance. Callback is passed arguments: newStructure, oldStructure, keyPath.
change: Emitted when data/value is updated and it existed before. Emits values: newValue, oldValue and path.
delete: Emitted when data/value is removed. Emits value: removedValue and path.
add: Emitted when new data/value is added. Emits value: newValue and path.
any: With the same semantics as add, change or delete, any is triggered for all types of changes. Differs from swap in the arguments that it is passed. Is passed newValue (or undefined), oldValue (or undefined) and full keyPath. New and old value are the changed value, not relative/scoped to the reference path as with swap.

Options

{
  key: string, // Defaults to random string
  data: Object|Immutable, // defaults to empty Map
  history: boolean, // Defaults to false
  historyLimit: number, // If history enabled, Defaults to Infinity
}

Parameters

param	type	description
`[options]`	{ key: `string`, data: `Object`, history: `boolean` }	optional: - defaults to random key and empty data (immutable structure). No history

|

Properties

property	type	description
`history`	Immutable.List	`Immutable.List` with history.
`current`	Object,Immutable	Provided data as immutable data
`key`	string	Generated or provided key.

Returns Structure,

`structure.cursor([path])`

Create a Immutable.js Cursor for a given path on the current structure (see Structure.current). Changes made through created cursor will cause a swap event to happen (see Events).

This method returns a Immutable.js Cursor. See the Immutable.js docs for more info on how to use cursors.

Examples:

var Structure = require('immstruct/structure');
var s = new Structure({ data: { foo: 'bar', a: { b: 'foo' } }});
s.cursor().set('foo', 'hello');
s.cursor('foo').update(function () { return 'Changed'; });
s.cursor(['a', 'b']).update(function () { return 'bar'; });

See more examples in the tests

Parameters

param	type	description
`[path]`	string,Array.	optional: - defaults to empty string. Can be array for path. See Immutable.js Cursors

Returns Cursor, Gives a Cursor from Immutable.js

`structure.reference([path|cursor])`

Creates a reference. A reference can be a pointer to a cursor, allowing you to create cursors for a specific path any time. This is essentially a way to have "always updated cursors" or Reference Cursors. See example for better understanding the concept.

References also allow you to listen for changes specific for a path.

Examples:

var structure = immstruct({
  someBox: { message: 'Hello World!' }
});
var ref = structure.reference(['someBox']);

var unobserve = ref.observe(function () {
  // Called when data the path 'someBox' is changed.
  // Also called when the data at ['someBox', 'message'] is changed.
});

// Update the data using the ref
ref.cursor().update(function () { return 'updated'; });

// Update the data using the initial structure
structure.cursor(['someBox', 'message']).update(function () { return 'updated again'; });

// Remove the listener
unobserve();

See more examples in the readme

Parameters

param	type	description
`[path	cursor]`	string,Array.,Cursor

|

Returns Reference,

`reference.observe([eventName], callback)`

Observe for changes on a reference. On references you can observe for changes, but a reference is not an EventEmitter it self.

The passed keyPath for swap events are relative to the reference, but

Note: As on swap for normal immstruct events, the passed arguments for the event is the root, not guaranteed to be the actual changed value. The structure is how ever scoped to the path passed in to the reference. All values passed to the eventlistener for the swap event are relative to the path used as key path to the reference.

For instance:

var structure = immstruct({ 'foo': { 'bar': 'hello' } });
var ref = structure.reference('foo');
ref.observe(function (newData, oldData, keyPath) {
  keyPath.should.eql(['bar']);
  newData.toJS().should.eql({ 'bar': 'updated' });
  oldData.toJS().should.eql({ 'bar': 'hello' });
});
ref.cursor().update(['bar'], function () { return 'updated'; });

For type specific events, how ever, the actual changed value is passed, not the root data. In these cases, the full keyPath to the change is passed.

For instance:

var structure = immstruct({ 'foo': { 'bar': 'hello' } });
var ref = structure.reference('foo');
ref.observe('change', function (newValue, oldValue, keyPath) {
  keyPath.should.eql(['foo', 'bar']);
  newData.should.eql('updated');
  oldData.should.eql('hello');
});
ref.cursor().update(['bar'], function () { return 'updated'; });

Examples:

var ref = structure.reference(['someBox']);

var unobserve = ref.observe('delete', function () {
  // Called when data the path 'someBox' is removed from the structure.
});

See more examples in the readme

Events

swap: Emitted when any cursor is updated (new information is set). Triggered in any data swap is made on the structure. One use case for this is to re-render design components. Data passed as arguments are scoped/relative to the path passed to the reference, this also goes for keyPath. Callback is passed arguments: newStructure, oldStructure, keyPath.
change: Emitted when data/value is updated and it existed before. Emits values: newValue, oldValue and path.
delete: Emitted when data/value is removed. Emits value: removedValue and path.
add: Emitted when new data/value is added. Emits value: newValue and path.
any: With the same semantics as add, change or delete, any is triggered for all types of changes. Differs from swap in the arguments that it is passed. Is passed newValue (or undefined), oldValue (or undefined) and full keyPath. New and old value are the changed value, not relative/scoped to the reference path as with swap.

Parameters

param	type	description
`[eventName]`	string	optional: - Type of change
`callback`	Function	- Callback when referenced data is swapped

Returns Function, Function for removing observer (unobserve)

`reference.cursor([subpath])`

Create a new, updated, cursor from the base path provded to the reference. This returns a Immutable.js Cursor as the regular cursor method. You can also provide a sub-path to create a reference in a deeper level.

Examples:

var ref = structure.reference(['someBox']);
var cursor = ref.cursor('someSubPath');
var cursor2 = ref.cursor();

See more examples in the readme

Parameters

param	type	description
`[subpath]`	string	optional: - Subpath to a deeper structure

Returns Cursor, Immutable.js cursor

`reference.reference([path])`

Creates a reference on a lower level path. See creating normal references.

Examples:

var structure = immstruct({
  someBox: { message: 'Hello World!' }
});
var ref = structure.reference('someBox');

var newReference = ref.reference('message');

See more examples in the readme

Parameters

param	type	description
`[path]`	string,Array.	optional: - defaults to empty string. Can be array for path. See Immutable.js Cursors

Returns Reference,

`reference.unobserveAll`

Remove all observers from reference.

Returns Void,

`reference.destroy`

Destroy reference. Unobserve all observers, set all endpoints of reference to dead. For cleaning up memory.

Returns Void,

`structure.forceHasSwapped(newData, oldData, keyPath)`

Force emitting swap event. Pass on new, old and keypath passed to swap. If newData is null current will be used.

Parameters

param	type	description
`newData`	Object	- Immutable object for the new data to emit
`oldData`	Object	- Immutable object for the old data to emit
`keyPath`	string	- Structure path (in tree) to where the changes occured.

Returns Void,

`structure.undo(steps)`

Undo IFF history is activated and there are steps to undo. Returns new current immutable structure.

Will NOT emit swap when redo. You have to do this yourself.

Define number of steps to undo in param.

Parameters

param	type	description
`steps`	number	- Number of steps to undo

Returns Object, New Immutable structure after undo

`structure.redo(head)`

Redo IFF history is activated and you can redo. Returns new current immutable structure. Define number of steps to redo in param. Will NOT emit swap when redo. You have to do this yourself.

Parameters

param	type	description
`head`	number	- Number of steps to head to in redo

Returns Object, New Immutable structure after redo

`structure.undoUntil(structure)`

Undo IFF history is activated and passed structure exists in history. Returns the same immutable structure as passed as argument.

Will NOT emit swap after undo. You have to do this yourself.

Parameters

param	type	description
`structure`	Object	- Immutable structure to redo until

Returns Object, New Immutable structure after undo

Files

api.md

Latest commit

History

api.md

File metadata and controls

Immstruct

Examples:

Properties

immstruct.get([key], [data])

Examples:

Parameters

immstruct.instance([name])

Parameters

immstruct.clear

Examples:

immstruct.remove(key)

Examples:

Parameters

immstruct.withHistory([key], [limit], [data])

Examples:

Parameters

immstruct([key], [data])

Examples:

Parameters

Structure([options])

Examples:

Events

Options

Parameters

Properties

structure.cursor([path])

Examples:

Parameters

structure.reference([path|cursor])

Examples:

Parameters

reference.observe([eventName], callback)

Examples:

Events

Parameters

reference.cursor([subpath])

Examples:

Parameters

reference.reference([path])

Examples:

Parameters

reference.unobserveAll

reference.destroy

structure.forceHasSwapped(newData, oldData, keyPath)

Parameters

structure.undo(steps)

Parameters

structure.redo(head)

Parameters

structure.undoUntil(structure)

Parameters

Private members

`Immstruct`

`immstruct.get([key], [data])`

`immstruct.instance([name])`

`immstruct.clear`

`immstruct.remove(key)`

`immstruct.withHistory([key], [limit], [data])`

`immstruct([key], [data])`

`Structure([options])`

`structure.cursor([path])`

`structure.reference([path|cursor])`

`reference.observe([eventName], callback)`

`reference.cursor([subpath])`

`reference.reference([path])`

`reference.unobserveAll`

`reference.destroy`

`structure.forceHasSwapped(newData, oldData, keyPath)`

`structure.undo(steps)`

`structure.redo(head)`

`structure.undoUntil(structure)`