Interface Traverser<D>

Readonly traversable

Readonly traversalConfig

traverse

• traverse(callback): Promise<TraversalResult>

• Traverses the entire collection in batches of the size specified in traversal config. Invokes the specified async callback for each batch of document snapshots and immediately moves to the next batch. Does not wait for the callback Promise to resolve before moving to the next batch so there is no guarantee that any given batch will finish processing before a later batch.

  Parameters

  • callback: BatchCallback<D>

    An asynchronous callback function to invoke for each batch of document snapshots.

  Returns Promise<TraversalResult>

  A Promise resolving to an object representing the details of the traversal.

  Remarks

  This method throws only when the batch callback throws and the number of retries equals maxBatchRetryCount. The last error thrown by the batch callback propagates up to this method.

  Complexity:

  • Time complexity: O((N / batchSize) * (Q(batchSize) + C(batchSize) / maxConcurrentBatchCount))
  • Space complexity: O(maxConcurrentBatchCount * (batchSize * D + S))
  • Billing: max(1, N) reads

  where:

  • N: number of docs in the traversable
  • Q(batchSize): average batch query time
  • C(batchSize): average callback processing time
  • D: average document size
  • S: average extra space used by the callback

traverseEach

• traverseEach(callback, config?): Promise<TraversalResult>

• Traverses the entire collection in batches of the size specified in traversal config. Invokes the specified callback sequentially for each document snapshot in each batch.

  Parameters

  • callback: TraverseEachCallback<D>

    An asynchronous callback function to invoke for each document snapshot in each batch.

  • Optional config: Partial<TraverseEachConfig>

    The sequential traversal configuration.

  Returns Promise<TraversalResult>

  A Promise resolving to an object representing the details of the traversal. The Promise resolves when the entire traversal ends.

withConfig

• withConfig(config): Traverser<D>

• Applies the specified config values to the traverser.

  Parameters

  • config: Partial<TraversalConfig>

    Partial traversal configuration.

  Returns Traverser<D>

  A new Traverser object.

withExitEarlyPredicate

• withExitEarlyPredicate(predicate): Traverser<D>

• Applies the specified exit-early predicate to the traverser. After retrieving each batch, the traverser will evaluate the predicate with the current batch doc snapshots and batch index and decide whether to continue the traversal or exit early.

  Parameters

  • predicate: ExitEarlyPredicate<D>

    A synchronous function that takes batch doc snapshots and the 0-based batch index and returns a boolean indicating whether to exit traversal early.

  Returns Traverser<D>

  A new Traverser object.

  Remarks

  If you have already applied other exit-early predicates to this traverser, this and all the other predicates will be evaluated and the resulting booleans will be OR'd to get the boolean that indicates whether to exit early or not. This is consistent with the intuitive default behavior that the traverser doesn't exit early.

  Example

  const newTraverser = traverser
    .withExitEarlyPredicate((batchDocs) => batchDocs.some((d) => d.get('name') === undefined))
    .withExitEarlyPredicate((_, batchIndex) => batchIndex === 99);
  Copy

  In the above case newTraverser will exit early if the name field of one of the docs in the batch is missing OR if the batch index is 99. That is, it will never reach batch 100 and depending on the documents in the database it may exit earlier than 99.