One More Inverse Link Regression

Big thanks to @gnarf for catching and fixing yet another regression with inverse link management - see #129 🤘

Fix Inverse Link Regression

Thanks very much to @gnarf for finding and fixing a regression introduced in v0.6.4 related to inverse link tracking (commit e06086b).

Cache Control

This release cements the central role of the Cache in maintaining links of all forms and dependencies between records. Not only can the Cache maintain reverse links, it can also maintain inverse links and dependencies between related objects. These abilities are controlled by the Cache options: maintainRevLinks, maintainInverseLinks, and maintainDependencies. All of these options are enabled by default.

Thanks to @gnarf for the new maintainDependencies option, which allows for dependent relationships to be defined that will cause cascading removals when the parent is removed. The following schema definition ensures that moons will be removed when their corresponding planets are removed:

  var dependentSchema = new Schema({
    models: {
      planet: {
        links: {
          moons: {type: 'hasMany', model: 'moon', dependent: 'remove'}
        }
      },
      moon: {
        links: {
          planet: {type: 'hasOne', model: 'planet'}
        }
      }
    }
  });

Thanks to @opsb and @walter for the introduction of a new coalesceOperations function. This function coalesces operations into a minimal set of equivalent operations. For example:

var squashed = coalesceOperations([
  {op: 'add', path: ['contact', '1234', '__rel', 'address'], value: "abc123"},
  {op: 'add', path: ['contact', '1234'], value: { id: '1234', __rel: { address: 'def789' } }}
]);

console.log(squashed);
// [{op: 'add', path: ['contact', '1234'], value: { id: '1234', __rel: { address: "def789" } }}]

This method will be key to using sources as editing contexts to apply a minimal set of operations back to the parent source.

Globals Builds Fix

This release fixes the globals builds that were broken when a new ES6 transpiler was introduced along with the Broccoli infrastructure improvements. You should now be able to directly reference members of top-level namespaces such as Orbit and OC.

Common Ancestors

This release solves a number of issues related to transformations, relationships, and timeouts.

It introduces a new methodology for tracking operation relationships. Operations are now considered "related" if they share a common ancestor. Related operations are always processed together as part of the same transformation.

Note for Source Authors

Source authors can now group operations together, even if they are all siblings, by providing them with a shared ancestor operation. This shared ancestor doesn't need to be applied to the source, and its properties can be blank. Its sole purpose is to connect operations so that they will be applied together as part of the same Transformation. This can be done by creating child operations with spawn.

For instance:

var parentOperation = new Operation();
var childOperation1 = parentOperation.spawn({op: 'add', path: path1, value: value1});
var childOperation2 = parentOperation.spawn({op: 'add', path: path2, value: value2});

Transformations

This release "transforms" the infrastructure used by Transformable sources. The
intent is to better expose the queues and the actions placed in queues, while
also correcting ordering issues by tracking the ancestry of operations.

New Operation, Action, and Transformation classes

Operation

Operation provides a thin wrapper over a JSON Patch operation.

Operations maintain the standard Patch attributes: op, path, and value.

Operations are automatically assigned a UUID id. They can maintain their
ancestry in a log. In this way, it is possible to determine whether
operations preceded each other.

Operations can spawn descendants, which automatically adds the parent to
the child's history.

The transform and didTransform methods on Transformable sources will
automatically normalize POJO operations into Operation instances.

Action

Actions wrap functions that are queued in an ActionQueue.

Actions can maintain optional metadata such as id and data. This metadata
makes it easier to identify actions within a queue. It can also be used by
actions themselves during processing.

Transformation

Transformations are created implicitly by Transformable sources in order
to group together related operations (i.e. those with a shared history).
This allows related operations to be processed together, and unrelated
operations to be queued in separate transformations to be processed
later.

A transformation tracks the original operations pushed to it, and can
verify whether other operations are descendants of those originals.

Important Note for Source Authors

In order to ensure that related transforms are resolved together and unrelated
transforms are queued for later processing, it's necessary to track operation
ancestry.

This should be straightforward within your sources. When sources receive
operations in _transform, they should now be of type Operation. If one
operation spawns another, then simply create the child operation using the
spawn method.

For example:

var childOperation = operation.spawn({op: 'add', path: path, value: value});

See the source for Cache, MemorySource, and JSONAPISource for
further examples.

0.5.3

Significant changes:

• Individual transforms are now processed thoroughly before other queued transforms are processed. This includes resultant didTransform events and subsequent actions, which will be processed immediately instead of being pushed to the end of the transform queue. This allows consecutive transforms to be applied to a Transformable source without explicitly settling each transform in between. This change also eliminates the need for a separate transformQueue to be maintained on the TransformConnector.
• hasMany relationships can now be flagged as actsAsSet to indicate that they should be updated together as a set. This is used by the JSONAPISource to send complete arrays of ids when any member has changed.
• New Requestable interface method in OC: updateLink. This is used to update a relationship completely. It can be used with any hasOne relationship and any hasMany relationship flagged as actsAsSet (see above).
• New rollbackTransformsOnFailure option for TransformConnector will automatically rollback changes on the source when corresponding transforms on the target fail.
• OC.Source gains new helper methods: _normalizeId and _normalizeLink. These methods extract id values given objects, arrays, or strings, and greatly clean up the Source code.
• New isObject utility method

Full changelog