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. Information about rate limits can be found here.
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.
data 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 data based on the existing data. 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 data:', 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(data [, metadataUpdates])

Assign new contents to this document. The current data will be overwritten.
Parameters:
Name Type Argument Description
data Object The new contents to assign.
metadataUpdates Document#Metadata <optional>
 New document metadata.
Returns:
A promise resolving to the new data of the document.
Type
Promise.<Object>
Example
// Say, the Document data is { name: 'John Smith', age: 34 }
document.set({ name: 'Barbara Oaks' }, { ttl: 86400 })
  .then(function(newValue) {
    // Now the Document data is { name: 'Barbara Oaks' }
    console.log('Document set() successful, new data:', 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 data of the document.
Type
Promise.<Object>
Example
// Say, the Document data is { name: 'John Smith' }
document.update({ age: 34 }, { ttl: 86400 })
  .then(function(newValue) {
    // Now the Document data is { name: 'John Smith', age: 34 }
    console.log('Document update() successful, new data:', 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 data.
Parameters:
Name Type Description
currentValue Object The current data of the document in the cloud.
Returns:
The desired new data 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.
previousData Object Contains a snapshot of the document data before removal.
Example
document.on('removed', function(args) {
  console.log('Document ' + document.sid + ' was removed');
  console.log('args.isLocal: ', args.isLocal);
  console.log('args.previousData: ', args.previousData);
});

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
data Object A snapshot of the document's new contents.
isLocal Boolean Equals 'true' if document was updated by local actor, 'false' otherwise.
previousData Object Contains a snapshot of the document data before the update.
Example
document.on('updated', function(args) {
  console.log('Document ' + document.sid + ' was updated');
  console.log('args.data: ', args.data);
  console.log('args.isLocal: ', args.isLocal);
  console.log('args.previousData: ', args.previousData);
});