twilio-sync
Options
All
  • Public
  • Public/Protected
  • All
Menu

Represents a Sync document, the contents of which is a single JSON object. Use the SyncClient.document method to obtain a reference to a Sync document. Information about rate limits can be found here.

Hierarchy

  • Closeable
    • SyncDocument

Index

Events

Accessors

Methods

Events

Static Readonly removed

removed: "removed" = 'removed'

Fired when the document is removed, regardless of whether the remover was local or remote.

Parameters:

  1. object args - info object provided with the event. It has following properties:
    • boolean isLocal - is true if document was removed by a local actor, false otherwise
    • object previousData - contains a snapshot of the document data before removal
example
document.on('removed', (args) => {
  console.log(`Document ${document.sid} was removed`);
  console.log('args.isLocal:', args.isLocal);
  console.log('args.previousData:', args.previousData);
});

Static Readonly updated

updated: "updated" = 'updated'

Fired when the document's contents have changed, regardless of whether the updater was local or remote.

Parameters:

  1. object args - info object provided with the event. It has the following properties:
    • boolean isLocal - is true if document was updated by a local actor, false otherwise
    • object data - a snapshot of the document's new contents
    • object previousData - contains a snapshot of the document data before the update
example
document.on('updated', (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);
});

Accessors

data

  • get data(): Object

  • The contents of this document.

    Returns Object

dateUpdated

  • get dateUpdated(): Date

  • Date when the document was last updated.

    Returns Date

sid

  • get sid(): string

  • The immutable identifier of this document, assigned by the system.

    Returns string

uniqueName

  • get uniqueName(): string

  • An optional immutable identifier that may be assigned by the programmer to this document during creation. Globally unique among other documents.

    Returns string

Methods

close

  • close(): void

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

    Returns void

mutate

  • Schedules a modification to this document that will apply a mutation function.

    example
    const mutatorFunction = (currentValue) => {
    currentValue.viewCount = (currentValue.viewCount ?? 0) + 1;
    return currentValue;
};
document.mutate(mutatorFunction, { ttl: 86400 }))
  .then((newValue) => {
    console.log('Document mutate() successful, new data:', newValue);
  })
  .catch((error) => {
    console.error('Document mutate() failed', error);
  });

    Parameters

    • mutator: Mutator

      A function that outputs 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.

    • Optional metadataUpdates: SyncDocumentMetadata

      New document metadata.

    Returns Promise<Object>

    Resolves with the most recent Document state, whether the output of a successful mutation or a state that prompted graceful cancellation (mutator returned null).

removeDocument

  • removeDocument(): Promise<never>

  • Delete a document.

    example
    document.removeDocument()
  .then(() => {
    console.log('Document removeDocument() successful');
  })
  .catch((error) => {
    console.error('Document removeDocument() failed', error);
  });

    Returns Promise<never>

    A promise which resolves if (and only if) the document is ultimately deleted.

set

  • Assign new contents to this document. The current data will be overwritten.

    example
    // Say, the Document data is `{ name: 'John Smith', age: 34 }`
document.set({ name: 'Barbara Oaks' }, { ttl: 86400 })
  .then((newValue) => {
    // Now the Document data is `{ name: 'Barbara Oaks' }`
    console.log('Document set() successful, new data:', newValue);
  })
  .catch((error) => {
    console.error('Document set() failed', error);
  });

    Parameters

    • data: Object

      The new contents to assign.

    • Optional metadataUpdates: SyncDocumentMetadata

      New document metadata.

    Returns Promise<Object>

    A promise resolving to the new data of the document.

setTtl

  • setTtl(ttl: number): Promise<void>

  • Update the time-to-live of the document.

    example
    document.setTtl(3600)
  .then(() => {
    console.log('Document setTtl() successful');
  })
  .catch((error) => {
    console.error('Document setTtl() failed', error);
  });

    Parameters

    • ttl: number

      Specifies the time-to-live in seconds after which the document is subject to automatic deletion. The value 0 means infinity.

    Returns Promise<void>

    A promise that resolves after the TTL update was successful.

update

  • 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((currentValue) => Object.assign(currentValue, obj));
    example
    // Say, the Document data is `{ name: 'John Smith' }`
document.update({ age: 34 }, { ttl: 86400 })
  .then((newValue) => {
    // Now the Document data is `{ name: 'John Smith', age: 34 }`
    console.log('Document update() successful, new data:', newValue);
  })
  .catch((error) => {
    console.error('Document update() failed', error);
  });

    Parameters

    • obj: Object

      Specifies the particular (top-level) attributes that will receive new values.

    • Optional metadataUpdates: SyncDocumentMetadata

      New document metadata.

    Returns Promise<Object>

    A promise resolving to the new data of the document.