JSON Client API

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

doc.get() // => {'todo':[]}
todo = doc.at('todo')
todo.get() // => []
todo.push('take out the garbage')
doc.get() // => {'todo':['take out the garbage']}
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, cb)

  Sets the document at subdoc to value.

• subdoc.insert(pos, data, cb) (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, cb) (Strings only)

  Deletes length characters starting at pos from the string.

• subdoc.remove(cb)

  Removes the subdocument from the tree.

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

  Inserts item at the end of the list.

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

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

• subdoc.add(amount, cb) (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

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