This project provides the ability to listen for dataLayer messages and to read the key/value pairs
that have been set by all the previous messages. It can be used by the tools/vendors mentioned above,
or by page authors that need to read back the data they've emitted.

To use this library, you'll need to get it onto the page. You can do this by hosting a copy and
sourcing it from the page, or by compiling it into your own JavaScript library. Once it's on the
page, you can create a new helper object like this:

As each message is processed, its key/value pairs will be added to the abstract data
model. If the key doesn't currently exist in the model, this operation is simple.
The pair is simply added to the model object. But in the case of key conflicts, we have
to specify how values will be overwritten and/or merged.

There are two possible actions to take when merging a key/value pair onto the abstract
model; overwriting the existing value or recursively merging the new value onto the
existing value. The action taken will depend on the type of the two values. For this,
we define three types of values:

* JavaScript Arrays
* "Plain" Objects
* Everything else

Hopefully, JavaScript Arrays are self-explanatory. "Plain" Objects are JavaScript
objects that were created via Object literal notation (e.g. {one: 2}) or via "new Object".
Nulls, Dates, RegExps, Windows, DOM Elements, etc. are not "Plain". Those fall into the
category of "everything else", along with strings, numbers, booleans, undefined, etc.

Once the type of the new and existing values has been categorized this way, we can use the
following table to describe what action will happen for that key/value pair:

Existing Value | New Value | Merging Action
---------------|--------------|--------------------------
Array | Array | Recursively merge
Array | Plain Object | Overwrite existing value
Array | Other | Overwrite existing value
Plain Object | Array | Overwrite existing value
Plain Object | Plain Object | Recursively merge
Plain Object | Other | Overwrite existing value
Other | Array | Overwrite existing value
Other | Plain Object | Overwrite existing value
Other | Other | Overwrite existing value

$3

Existing Value | New Value | Result of Overwrite
-----------------|------------------|---------------------
[1, 2, 3] | 'hello' | 'hello'
{ducks: 'quack'} | [1, 2, 3] | [1, 2, 3]
{ducks: 'quack'} | 'hello' | 'hello'
'hello' | [1, 2, 3] | [1, 2, 3]
'hello' | {ducks: 'quack'} | {ducks: 'quack'}
'hello' | 42 | 42

$3

Existing Value | New Value | Result of Overwrite
-------------------|-------------------------------|----------------------------
{one: 1, three: 3} | {two: 2} | {one: 1, three: 3, two: 2}
{one: 1, three: 3} | {three: 4} | {one: 1, three: 4}
{one: {two: 3}} | {one: {four: 5}} | {one: {two: 3, four: 5}}
{one: {two: 3}} | {two: 4} | {one: {two: 3}, two: 4}
[] | ['hello'] | ['hello']
[1] | [undefined, 2] | [1, 2]
[1, {two: 3}] | [undefined, {two: 4, six: 8}] | [1, {two: 4, six: 8}]

$3

The first of these syntaxes allows you to call any method supported on the existing type.
For example, if the existing value in the abstract model is an Array, you'd have a wide
variety of APIs that can be called (e.g. push, pop, concat, shift, unshift, etc.). To invoke
this syntax, you would push a "command array" onto the dataLayer instead of a normal message
object.

In the following example, no arguments are provided:

In the following example, the value to update (bbb) is nested inside a top level object (aaa):

And the following example demonstrates an operation on a Date object. Remember that all types
are supported, not just Arrays:

Notice that because command arrays are processed asynchronously, nothing can be done with the
return values from these method invocations. This brings us to our second syntax for updating
values in the abstract data model.

$3

When a function is processed, it will be executed in the context of the abstract data model. The
value of "this" will be an interface that represents the current abstract data model. This
interfact will provide two APIs: get(key) and set(key, value). The following examples demonstrate
how these APIs can be used to update values in the abstract data model.

dataLayer.push(function() {
  this.get('time').setMonth(0); 
})

The following example demonstrates updating a nested value:

dataLayer.push(function() {
  var ccc = this.get('aaa.bbb.ccc');
  ccc.push(ccc.pop() * 2);
})

The following example demonstrates overwriting a value:

dataLayer.push(function() {
  this.set('abc', {xyz: this.get('abc')});
})

Listening for Messages

There are three types of messages:
* Standard Messages (Objects)
* Native Method Calls (Command Arrays)
* Custom Method Calls (Functions)

This helper library provides tools and vendors a way to consume these messages. It automatically
listens for new messages and merges them onto its abstract data model. You can query the model
using the get() API, or you can get message notifications with a callback function.

At this point, we highly recommend that you read the code and browse the tests for examples of
how the library works and how it can be used.

Build and Test

A few prerequisites:

1. Install Node.js and npm
2. Install Git

Clone a copy of the project repo by running: