Class Collection<D>

Readonlyconfig

Readonlydatabase

Readonlyname

addChangeListener

• addChangeListener(callback: CollectionChangeCallback): ListenerToken

  Adds a listener function that will be called after any document(s) change. If documents are changed while in a transaction, the listener is not called until the transaction successfully commits.

  Note: Purged and expired documents do not trigger notifications.

  Parameters

  • callback: CollectionChangeCallback

    The function to be called after documents change.

  Returns ListenerToken

  A ListenerToken whose ListenerToken.remove method you can call to remove the listener.

addDocumentChangeListener

• addDocumentChangeListener(
      docID: DocID,
      callback: DocumentChangeCallback,
  ): ListenerToken

  Adds a listener function that will be called after a specific document changes.

  Note: If the document is changed while in a transaction, the listener is not called until the transaction successfully commits.

  Note: Purged and expired documents do not trigger notifications.

  Parameters

  • docID: DocID

    The ID of the document to monitor.

  • callback: DocumentChangeCallback

    The function to be called after the document changes.

  Returns ListenerToken

  A ListenerToken whose ListenerToken.remove method you can call to remove the listener.

count

• count(what?: "deleted" | "docs" | "includeDeleted"): Promise<number>

  By default, returns the number of documents in the collection. If what is "deleted", it returns the number of deleted docs ("tombstones".) If what is "includeDeleted", it returns the total number of live and deleted docs.

  Parameters

  • what: "deleted" | "docs" | "includeDeleted" = 'docs'

  Returns Promise<number>

createDocument

• createDocument(id: DocID | null, body?: D): CBLDocument<D>

  Creates a new document instance tied to this collection. The document will not be persisted to the database until you save it.

  Parameters

  • id: DocID | null

    The document ID, which must be unique in the Collection. If you pass null, a random ID will be generated.

  • Optionalbody: D

    The initial contents of the document; if omitted, it will be empty.

  Returns CBLDocument<D>

delete

• delete(
      doc: CBLDocument<D> | DocumentMeta<D>,
      onConflict?: ConflictHandler<D>,
  ): Promise<boolean>

  Deletes a document from this collection.

  Deletion leaves behind an invisible "tombstone" revision, a placeholder that's used by the Replicator to sync the deletion back to a server. If you don't want the overhead, and this deletion does not need to be synced, consider using purge instead.

  Conflicts can occur when deleting, just as on a regular save. A ConflictHandler allows you to handle them.

  Performance note: If you are deleting multiple documents, use updateMultiple instead; it's much faster than saving one at a time.

  Parameters

  • doc: CBLDocument<D> | DocumentMeta<D>

    The document.

  • OptionalonConflict: ConflictHandler<D>

    Optional conflict handler callback.

  Returns Promise<boolean>

  true if saved, false if the ConflictHandler decided to 'revert'.

  Throws

  ConflictError on conflict.

  Throws

  EncryptionError if the database is encrypted and locked.

deletedDocumentIDs

• deletedDocumentIDs(): Promise<DocID[]>

  Returns the DocIDs of all deleted documents.

  Returns Promise<DocID[]>

documentIDs

• documentIDs(): Promise<DocID[]>

  Returns the DocIDs of all (undeleted) documents.

  Returns Promise<DocID[]>

doDelete

• doDelete(
      doc: DocumentMeta<D>,
      onConflict?: ConflictHandler<D>,
  ): Promise<[RevID, Sequence] | undefined>

  Parameters

  • doc: DocumentMeta<D>
  • OptionalonConflict: ConflictHandler<D>

  Returns Promise<[RevID, Sequence] | undefined>

eachDocument

• eachDocument(callback: (doc: CBLDocument<D>) => boolean): Promise<boolean>

  Invokes the callback with each (undeleted) Document of the Collection, ordered by docID. The callback should return true to continue, or false to stop the iteration.

  Parameters

  • callback: (doc: CBLDocument<D>) => boolean

  Returns Promise<boolean>

  True if the iteration completed, false if it was stopped.

getDocument

• getDocument(id: DocID): Promise<CBLDocument<D> | undefined>

  Loads an existing document, or returns undefined if it doesn't exist.

  Parameters

  • id: DocID

  Returns Promise<CBLDocument<D> | undefined>

getDocumentExpiration

• getDocumentExpiration(doc: DocID | CBLDocument<D>): Promise<Date | undefined>

  Gets a document's expiration date.

  Parameters

  • doc: DocID | CBLDocument<D>

  Returns Promise<Date | undefined>

  The expiration date, or undefined if none, or if the document doesn't exist.

purge

• purge(doc: DocID | CBLDocument<D>): Promise<void>

  Deletes all traces of a document, without leaving a "tombstone" revision behind. However, this means purges are not visible to the replicator, which has two side effects:

  • A push replication will not push the deletion to a server.
  • If the document is later updated on the server side, the next pull replication will download the new revision.

  Parameters

  • doc: DocID | CBLDocument<D>

    The document or DocID.

  Returns Promise<void>

purgeMultiple

• purgeMultiple(docs: readonly (DocID | CBLDocument<D>)[]): Promise<void>

  Purges multiple documents at once.

  Parameters

  • docs: readonly (DocID | CBLDocument<D>)[]

  Returns Promise<void>

save

• save(
      doc: CBLDocument<D> | DocumentMeta<D>,
      onConflict?: ConflictHandler<D>,
  ): Promise<boolean>

  Saves a document to this collection.

  If the document in the database has been changed since this instance was read -- by your app or by a replicator pulling revisions from a server -- a conflict occurs. By default, a ConflictError will be thrown. If you pass a ConflictHandler callback, it will be invoked during the save and can decide how to resolve the conflict.

  Performance note: If you are saving multiple documents to a collection, use updateMultiple instead; it's much faster than saving one at a time.

  Parameters

  • doc: CBLDocument<D> | DocumentMeta<D>
  • OptionalonConflict: ConflictHandler<D>

    Optional conflict handler callback.

  Returns Promise<boolean>

  true if saved, false if the ConflictHandler decided to 'revert'.

  Throws

  ConflictError on conflict.

  Throws

  EncryptionError if the database is encrypted and locked.

setDocumentExpiration

• setDocumentExpiration(
      doc: DocID | CBLDocument<D>,
      expiration: number | Date | undefined,
  ): Promise<void>

  Sets or clears an expiration date for a document.

  Parameters

  • doc: DocID | CBLDocument<D>

    The document or DocID

  • expiration: number | Date | undefined

    Can be an absolute Date, or a number interpreted as milliseconds into the future, or undefined to disable expiration.

  Returns Promise<void>

  Throws

  if the document doesn't exist.

updateMultiple

• updateMultiple(
      args: {
          bestEffort?: boolean;
          delete?: readonly CBLDocument<D>[];
          onConflict?: ConflictHandler<D>;
          save?: readonly CBLDocument<D>[];
      },
  ): Promise<void>

  Saves and/or deletes multiple documents at once in a single database transaction. This is much faster than saving each individually.

  The args object has the following properties, all optional:

  • save: Array of CBLDocuments to save
  • delete: Array of CBLDocuments to delete
  • onConflict: Conflict handler
  • bestEffort: If true, the transaction will commit even if some documents had errors. An error will still be thrown, though.

  Parameters

  • args: {
        bestEffort?: boolean;
        delete?: readonly CBLDocument<D>[];
        onConflict?: ConflictHandler<D>;
        save?: readonly CBLDocument<D>[];
    }

  Returns Promise<void>

  Throws

  MultipleConflictsError if any documents failed to update. Its errors property tells which documents failed and why.