v2.0.0

Version 2.0.0 with improved references. In addition to much more powerful references, there are also breaking changes with the passed event arguments and how you access the list of instances from a Immstruct instance.

Breaking Changes

1. Removes instances property from API. No longer a property .instances on the Immstruct instance which allow you to access the list of instances. It's now a method instance which allow you to get either the complete list, if no arguments, or a specific instance given by key as first argument.

   var immstruct = require('immstruct');
   
   immstruct('foo', {});
   immstruct.instance(); // => { 'foo': Immutable.Map }
   immstruct.instance('foo'); // =>  Immutable.Map
   
   // Same for instances of Immstruct:
   
   var localImmstruct = new immstruct.Immstruct();
   localImmstruct.get('foo', {});
   localImmstruct.instance(); // => { 'foo': Immutable.Map }
   localImmstruct.instance('foo'); // =>  Immutable.Map

2. References should now much more powerful and will listen to changes down the tree or on objects that are created after a reference is initiated. See #60 for more information. You can now do things as:

   var structure = immstruct({
   someBox: { message: 'Hello World!' }
   });
   var ref = structure.reference('someBox');
   
   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'; });

3. Changes order of arguments for all events. See #64. New order is documented as:

   • swap: Emitted when any cursor is updated (new information is set).
     Triggered in any change, both change, add and delete. One use case for
     this is to re-render design components. Structures passed as arguments
     are scoped to the path passed to the reference.
     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.

4. Now, 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.

   For instance:

   var structure = immstruct({ 'foo': { 'bar': 'hello' } });
   var ref = structure.reference('foo');
   ref.observe(function (newData, oldData, keyPath) {
    keyPath.should.eql(['foo', '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.

   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'; });

Additions

1. Adds ability to create references from cursors

   var structure = immstruct({ foo: 'bar' });
   var myCursor = structure.cursor('foo');
   var refToMyCursor = structure.reference(myCursor);

2. Adds ability to create child cursors (see #74) based on keyPath.

   var structure = immstruct({ foo: { bar: 'Hello' } });
   var refToFoo = structure.reference('foo');
   var refToBar = refToFoo.reference('bar');

3. Add ability to provide a limit to cap history

   Implement the ability to have history capped to a certain number of operations which is good for long running systems or heavy data use.

   By specifying the optional limit, the history mechanism will release old records once it hits the threshold.

   Default if not passed is Infinity.

     // optionalKey and/or optionalLimit can be omitted from the call
     var optLimit = 10; // only keep last 10 of history, default Infinity
     var structure = immstruct.withHistory('optKey', optLimit, { 'foo': 'bar' });
     var structureNoKey = immstruct.withHistory(optLimit, { 'foo': 'bar' });
   
     // Or with no limit
     var structureNoKeyUnlimited = immstruct.withHistory({ 'foo': 'bar' });
     var structureKeyUnlimited = immstruct.withHistory('foo', { 'foo': 'bar' });
   

4. Added event type 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.

5. Adds support for react-native

Bugfixes

1. Makes animation frame queue per instance. Fixes #49
2. Fixes IE8 'Expected identifier' error as "super" is a reserved keyword in IE8. See #69
3. Adds function names to change listeners decorators for easier debugging
4. Adds support for falsy keyPaths. Fixes #50
5. Optimizes the render loop / event handling. Vastly improves performance and number of operations per second. See more info at #56 and #60.

v1.4.1

Fixes correct usage for arguments variable for use strict, not breaking old browsers.

v1.4.0

Additions

1. References 🏇 . You can now create references to data and observe on specific paths of the structure. Read more in the docs and see #30 #31 #33
2. Make local instance of Immstruct (with it's own list of Structure instances): 84a35e1 . See #10
3. Structure object is now available on Immstruct object. 9e74b10

Examples of references

var structure = immstruct({ 'foo': 'bar' });
var ref = structure.reference('foo');

console.log(ref.cursor().deref()) //=> 'bar'

var oldCursor = structure.cursor('foo');
console.log(oldCursor.deref()) //=> 'bar'

var newCursor = structure.cursor('foo').update(function () { return 'updated'; });
console.log(newCursor.deref()) //=> 'updated'

// You don't need to manage and track fresh/stale cursors.
// A reference cursor will do it for you.
console.log(ref.cursor().deref()) //=> 'updated'

v1.3.1

Additions

1. Added dist files to project

Changes

1. Simplified changeListener, removing unnecessary code ( #29 )

v1.3.0

Additions

1. Exposes more accessible Structure constructor. ( #11 )

Fixes

1. Patches swap change on original structure to better handle removes and additions ( #13 )
2. Fixes where swap was emitted when the structure didn't change ( #17 )
3. Now passes keyPath for swap and next-animation-frame events ( #21 )
4. Adds call to possiblyEmitAnimationFrameEvent on forceHasSwapped ( #26 )

Thanks to changes from @dashed

v1.2.1

Patches:

1. Fixes modifying structure during add, change, or delete events. #8
2. Fixes emit event (add, change, delete) when updating value at key path to falsey value (e.g. void 0, false, etc). #8
3. Improves heuristic on detecting existence of key path within a cursor by using notSetValue. #8

Thanks to @dashed for the PR.

v1.2.0

Additions:

• Now you can remove single instances:

var immstruct = require('immstruct');
var structure = immstruct('key');

immstruct.remove(structure.key);

• Immstruct now exposes the internal instance object:

var immstruct = require('immstruct');
var structure = immstruct('key');

immstruct.internals[structure.key] //=> Structure

With this you can iterate over the instances and do more fancy things - use it with care.

v1.1.0

Changes:

1. Now using passing arguments to swap and next-animation-frame:

structure.on('swap', function (newStructure, oldStructure) {
   // Do something like undo/history
});

v1.0.1

Changes:

1. Now using EventEmitter3 as a lighter alternative to Node built in EventEmitter2. (Fixes #4)

v1.0.0

Breaking changes through bumping dependencies

1. Now uses Immutable 3.0 which has breaking changes.