JSON Client API (0.6.x)

The JSON API is an easy way to manipulate JSON documents. e.g:

// Create some JSON object
var myObject = { todo: [] };

// Set the structure of the document to the JSON object
doc.set( myObject );

// Get the document's JSON object
docObject = doc.get(); // => {'todo': 'nothing here'};

// Get the "todo" subdoc - this creates a new context that must be tracked -> use sparingly
todo = doc.getContextAt('todo');

// print out the "todo" subdoc
console.log( todo.get(); ) // => 'nothing here';

// Set the "todo" subdoc to a completely different value
todo.set([]);

// Print out the "todo" subdoc again
console.log( todo.get(); ) // => [];

// Push a value to the "todo" subdoc
todo.push({ item: 'take out the garbage', deadline: '8/14/2021', done: false });

// Print out the "todo" subdoc again
console.log( todo.get() ); // => [{ item: 'take out the garbage', deadline: '8/14/2021', done: false }]

// change the first item text
todo.remove([0, 'item', 13], 7);
todo.insert([0, 'item', 13], 'trash');

// Set the first todo item to done
todo.set([0, 'done'], true);

// Print out the first "todo" 
console.log( todo.get([0]) ); // => { item: 'take out the trash', deadline: '8/14/2021', done: true }

// Get the document JSON object again
doc.get(); // => {'todo':'some string value'};

// Create event when something is inserted into the doc
todo.on('insert', function (pos, item) {
  ...
})
todo.on('child op', function (path, op) {
  var item_idx = path[0]
  console.log("Item "+item_idx+" now reads "+todo.get()[item_idx])
  if (op.si != undefined) {
    // ...
  } else if (op.sd != undefined) {
    // ...
  }
})

// IMPORTANT: remove the todo context when we are done with it
todo.destroy();

This API is not yet stable, and may change at any time!

A note on paths

Locations within a JSON object are uniquely identified by a path consisting of hash keys and array indices. For example, given the following object:

obj = {
  a: 'v',
  b: {
    i: 'x',
    ii: [
      'y',
      'z'
    ]
  }
}

resolvePath(['a']) == 'v'
resolvePath(['b', 'i']) == 'x'
resolvePath(['b', 'ii', 1]) == 'z'

• doc.at(path...)

  Returns a sub-document starting at path. For the document itself, use doc.at(). doc.at can also accept an array as its only argument.

• subdoc.get(), subdoc.getText()

  Returns the snapshot at the subdocument.

• subdoc.set(value, callback)

  Sets the document at subdoc to value.

• subdoc.insert(pos, data, callback) (Strings and lists only)

  Inserts data at pos in the string or list. The item at pos (and everything after it) is pushed forward.

• subdoc.del(pos, length, callback) (Strings only)

  Deletes length characters starting at pos from the string.

• subdoc.remove(callback)

  Removes the subdocument from the tree.

• subdoc.push(item, callback) (Lists only)

  Inserts item at the end of the list.

• subdoc.move(from, to, callback) (Lists only)

  Causes the item at index from to have the index to.

• subdoc.add(amount, callback) (Numbers only)

  Adds amount to the number.

• removeListener(l)

  subdoc = doc.at(...)
  l = subdoc.on('insert', ...)
  subdoc.removeListener(l)
  // doc.removeListener(l) also works.

• For compatibility with the text API, subdoc.getText() and subdoc.getLength() are provided, returning the current snapshot and the .length of the subdoc, respectively. Note that .length is only defined on arrays and strings.

Events

Subscribing to an event with subdoc.on returns a listener object. Unsubscribe from the event by passing the listener returned by subdoc.on to subdoc.removeListener(listener). Thus, to add and remove a listener to the insert event:

var listener = subdoc.on('insert', function (position, data) { ... });
subdoc.removeListener(lister);

• insert

  subdoc.on('insert', function (position, data) { ... })

  (Strings and lists) Emitted when a remote client inserts an item into the list, or inserts text into the string. Call subdoc.get() to get the new value.

• delete

  subdoc.on('delete', function (position, data) { ... })

  (Strings and lists) Emitted when a remote client removes an item from the list, or deletes text from the string. data contains the item or text that was removed.

• replace

  subdoc.on('replace', function (position, was, now) { ... })

  (Lists and objects) Emitted when a remote client replaces an element of an object or list. position is the index of the array or the key of the object.

• move

  subdoc.on('move', function (from, to) { ... })

  (Lists only) Emitted when a remote client moves an element in the list from from to to.

• add

  subdoc.on('add', function (amount) { ... })

  (Numbers only) Emitted when a remote client adds amount to the number.

• child op

  subdoc.on('child op', function (path, op) { ... })

  Emitted when a remote operation changes any element contained in subdoc. path is the path below this document, such that subdoc.get()[path[0]][path[1]][...][path[path.length-2]] is the affected element, and path[path.length-1] is the index into that element (except for na operations, in which case there is no index). op is the raw operation that was applied. See JSON Operations for details.