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':[]}

// Get the "todo" subdoc
todo = doc.at('todo');

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

// Push a value to the "todo" subdoc
todo.push('take out the garbage');

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

// Set the "todo" subdoc to a completely different value
todo.set('some string value');

// Print out the "todo" subdoc again
console.log( todo.get(); ) // => 'some string value'

// 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) {
    // ...
  }
})

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

• 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(listener);

• insert

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

  (Strings, lists and objects) Emitted when a remote client inserts an item into the list, adds a key/value pair to an object, or inserts text into the string. Call subdoc.get() to get the new value. position is the position in string, index of the array, or key of the object.

• delete

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

  (Strings, lists and objects) Emitted when a remote client removes an item from the list, deletes a key/value pair from an object, or deletes text from the string. data contains the item or text that was removed. position is the position in string, index of the array, or key of the object.

• 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.