@ibm-cloud/cloudant - v0.12.26
    Preparing search index...

    Class ChangesFollower

    A helper for using the changes feed.

    There are two modes of operation:

    • startOneOff to fetch the changes from the supplied since sequence until there are no further pending changes.
    • start to fetch the changes from the supplied since sequence and then continuing to listen indefinitely for further new changes.

    The starting sequence ID can be changed for either mode by using CloudantV1.PostChangesParams.since. By default when using:

    • startOneOff the feed will start from the beginning.
    • start the feed will start from "now".

    In either mode the Stream of changes can be terminated early by calling stop.

    By default ChangesFollower will suppress transient errors indefinitely and endeavour to run to completion or listen forever. For applications where that behaviour is not desirable an alternate constructor is available where a errorTolerance may be specified to limit the time since the last successful response that transient errors will be suppressed.

    It should be noted that errors considered terminal, for example, the database not existing or invalid credentials are never suppressed and will throw an exception immediately.

    The CloudantV1.PostChangesParams model of changes feed options is used to configure the behaviour of the ChangesFollower. However, a subset of the options are invalid as they are configured internally by the implementation and will cause an Error to be thrown if supplied. These invalid options are:

    Only the value of _selector is permitted for the CloudantV1.PostChangesParams.filter option. Selector based filters perform better than JS based filters and using one of the alternative JS based filter types will cause ChangesFollower to throw an Error.

    It should also be noted that the CloudantV1.PostChangesParams.limit parameter will truncate the stream at the given number of changes in either operating mode.

    The ChangesFollower requires the CloudantV1 client to have HTTP call and read timeouts of at least 1 minute. The default client configuration has sufficiently long timeouts.

    Index
    • Returns the most recent sequence ID that is safe to use as a checkpoint, advancing beyond the supplied checkpoint sequence ID where possible.

      With highly filtered changes feeds, multiple pages can pass through the follower without returning any changes. Using only the seq of the last processed ChangesResultItem in those cases causes a long changes feed rewind on the next run. To avoid this, call this method after fully processing each ChangesResultItem with a non-null seq and persist the returned value to use as the since parameter for the next run.

      Note: the follower retains a bounded window of recent sequence IDs. If subsequent page fetches displace the supplied checkpointSequenceId from that window, this method returns the supplied value unchanged. Call this method and persist its result regularly to obtain a fresh sequence ID.

      Parameters

      • checkpointSequenceId: string

        the last checkpoint sequence ID — either the non-null seq of the last ChangesResultItem fully processed, or a value previously returned by this method.

      Returns string

      the most recent safe sequence ID to use as a checkpoint, or the supplied value if no newer sequence is available

      if checkpointSequenceId is null or empty