feat: add recursive delete to Firestore class

[thebrianchen]

Fixes #746.

This PR adds recursive delete functionality to the top level Firestore class in a method that recursively deletes all documents and subcollections at and under the specified level. If any delete fails, the promise is rejected with an error message containing the number of failed deletes and the stack trace of the last failed delete. The provided reference is deleted regardless of whether all deletes succeeded.

Example:

// Recursively delete a reference and log the references of failures.
const bulkWriter = firestore.bulkWriter();
bulkWriter
  .onWriteError((error) => {
    if (
      error.failedAttempts < MAX_RETRY_ATTEMPTS
    ) {
      return true;
    } else {
      console.log('Failed write at document: ', error.documentRef.path);
      return false;
    }
  });
await firestore.recursiveDelete(docRef, bulkWriter);

[codecov]

Codecov Report

Merging #1494 (81878c9) into master (09f7095) will increase coverage by 0.29%.
The diff coverage is 98.75%.

@@            Coverage Diff             @@
##           master    #1494      +/-   ##
==========================================
+ Coverage   98.22%   98.52%   +0.29%     
==========================================
  Files          32       33       +1     
  Lines       20052    20382     +330     
  Branches     1390     1328      -62     
==========================================
+ Hits        19697    20082     +385     
+ Misses        351      295      -56     
- Partials        4        5       +1     

Impacted Files	Coverage Δ
dev/src/recursive-delete.ts	98.40% <98.40%> (ø)
dev/src/bulk-writer.ts	100.00% <100.00%> (ø)
dev/src/index.ts	97.67% <100.00%> (+2.22%)	⬆️
dev/src/reference.ts	99.89% <100.00%> (+0.68%)	⬆️
dev/src/path.ts	98.57% <0.00%> (+0.42%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 09f7095...81878c9. Read the comment docs.

[jakeleventhal]

@thebrianchen how exactly does this work? What is docRef referring to? How would you delete an entire collection?

[schmidt-sebastian]

You pass a DocumentReference which will delete the reference, plus any nested collections and documents whose path starts with that of the DocumentReference. You can also pass a CollectionReference, which will delete all directly nested documents and their collections and documents.

[jakeleventhal]

will this work with collections that have queries?
@schmidt-sebastian

const bulkWriter = firestore.bulkWriter();
bulkWriter.onWriteError(() => true);
await firestore.recursiveDelete(firestore.collection('Things').where('UserId', '==', id), bulkWriter);

[schmidt-sebastian]

No, unfortunately it won't. The underlying implementation issues a "key only query" to recursively list all documents in the collection. This query is limited and does not support any additional constraints.