Documentation

Class: Document

Document

Represents a Sync Document, the contents of which is a single JSON object. Use the Client#document method to obtain a reference to a Sync Document.
Properties:
Name Type Argument Default Description
sid String The immutable identifier of this document, assigned by the system.
uniqueName String <optional>
 null An optional immutable identifier that may be assigned by the programmer to this document during creation. Globally unique among other Documents.
dateUpdated Date Date when the Document was last updated.
value Object The contents of this document.
Fires:

Methods

close()

Conclude work with the document instance and remove all event listeners attached to it. Any subsequent operation on this object will be rejected with error. Other local copies of this document will continue operating and receiving events normally.
Example
document.close();

<async> mutate(mutator [, metadataUpdates])

Schedules a modification to this document that will apply a mutation function.
Parameters:
Name Type Argument Description
mutator Document~Mutator A function that outputs a new value based on the existing value. May be called multiple times, particularly if this Document is modified concurrently by remote code. If the mutation ultimately succeeds, the Document will have made the particular transition described by this function.
metadataUpdates Document#Metadata <optional>
 New document metadata.
Returns:
Resolves with the most recent Document state, whether the output of a successful mutation or a state that prompted graceful cancellation (mutator returned null).
Type
Promise.<Object>
Example
var mutatorFunction = function(currentValue) {
    currentValue.viewCount = (currentValue.viewCount || 0) + 1;
    return currentValue;
};
document.mutate(mutatorFunction, { ttl: 86400 }))
  .then(function(newValue) {
    console.log('Document mutate() successful, new value:', newValue);
  })
  .catch(function(error) {
    console.error('Document mutate() failed', error);
  });

<async> removeDocument()

Delete a document.
Returns:
A promise which resolves if (and only if) the document is ultimately deleted.
Type
Promise.<void>
Example
document.removeDocument()
  .then(function() {
    console.log('Document removeDocument() successful');
  })
  .catch(function(error) {
    console.error('Document removeDocument() failed', error);
  });

<async> set(value [, metadataUpdates])

Assign new contents to this document. The current value will be overwritten.
Parameters:
Name Type Argument Description
value Object The new contents to assign.
metadataUpdates Document#Metadata <optional>
 New document metadata.
Returns:
A promise resolving to the new value of the document.
Type
Promise.<Object>
Example
// Say, the Document value is { name: 'John Smith', age: 34 }
document.set({ name: 'Barbara Oaks' }, { ttl: 86400 })
  .then(function(newValue) {
    // Now the Document value is { name: 'Barbara Oaks' }
    console.log('Document set() successful, new value:', newValue);
  })
  .catch(function(error) {
    console.error('Document set() failed', error);
  });

<async> setTtl(ttl)

Update the time-to-live of the document.
Parameters:
Name Type Description
ttl Number Specifies the time-to-live in seconds after which the document is subject to automatic deletion. The value 0 means infinity.
Returns:
A promise that resolves after the TTL update was successful.
Type
Promise.<void>
Example
document.setTtl(3600)
  .then(function() {
    console.log('Document setTtl() successful');
  })
  .catch(function(error) {
    console.error('Document setTtl() failed', error);
  });

<async> update(obj [, metadataUpdates])

Modify a document by appending new fields (or by overwriting existing ones) with the values from the provided Object. This is equivalent to 
document.mutate(function(currentValue) {
  return Object.assign(currentValue, obj));
});
Parameters:
Name Type Argument Description
obj Object Specifies the particular (top-level) attributes that will receive new values.
metadataUpdates Document#Metadata <optional>
 New document metadata.
Returns:
A promise resolving to the new value of the document.
Type
Promise.<Object>
Example
// Say, the Document value is { name: 'John Smith' }
document.update({ age: 34 }, { ttl: 86400 })
  .then(function(newValue) {
    // Now the Document value is { name: 'John Smith', age: 34 }
    console.log('Document update() successful, new value:', newValue);
  })
  .catch(function(error) {
    console.error('Document update() failed', error);
  });

Type Definitions

Metadata

Contains Document metadata.
Type:
  • Object
Properties:
Name Type Argument Description
ttl Number <optional>
 Specifies the time-to-live in seconds after which the document is subject to automatic deletion. The value 0 means infinity.

Mutator(currentValue)

Applies a transformation to the document value.
Parameters:
Name Type Description
currentValue Object The current value of the document in the cloud.
Returns:
The desired new value for the document or null to gracefully cancel the mutation.
Type
Object

Events

removed

Fired when the document is removed, whether the remover was local or remote.
Parameters:
Name Type Description
args Object Arguments provided with the event.
Properties
Name Type Description
isLocal Boolean Equals 'true' if document was removed by local actor, 'false' otherwise.
Example
document.on('removed', function(args) {
  console.log('Document ' + document.sid + ' was removed');
  console.log('args.isLocal:', args.isLocal);
});

updated

Fired when the document's contents have changed, whether the updater was local or remote.
Parameters:
Name Type Description
args Object Arguments provided with the event.
Properties
Name Type Description
value Object A snapshot of the document's new contents.
isLocal Boolean Equals 'true' if document was updated by local actor, 'false' otherwise.
Example
document.on('updated', function(args) {
  console.log('Document ' + document.sid + ' was updated');
  console.log('args.value: ', args.value);
  console.log('args.isLocal: ', args.isLocal);
});