@firecode/admin - npm Package Compare versions

Comparing version 0.6.0 to 0.6.1

lib/createBatchMigrator/BatchMigrator.d.ts

@@ -24,152 +24,9 @@ import type { firestore } from 'firebase-admin';
     withTraverser<C2 extends BaseTraversalConfig>(traverser: Traverser<D, C2>): BatchMigrator<D, C2, Traverser<D, C2>>;
-    /**
-     * Sets all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param data - The data with which to set each document.
-     * @param options - An object to configure the set behavior.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     set(data: Partial<D>, options: SetOptions): Promise<MigrationResult>;
-    /**
-     * Sets all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param data - The data with which to set each document.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     set(data: D): Promise<MigrationResult>;
-    /**
-     * Sets all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param getData - A function that returns an object with which to set each document.
-     * @param options - An object to configure the set behavior.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     set(getData: SetPartialDataGetter<D>, options: SetOptions): Promise<MigrationResult>;
-    /**
-     * Sets all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param getData - A function that returns an object with which to set each document.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     set(getData: SetDataGetter<D>): Promise<MigrationResult>;
-    /**
-     * Updates all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param getData - A function that returns the data with which to update each document.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     update(getData: UpdateDataGetter<D>): Promise<MigrationResult>;
-    /**
-     * Updates all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param data - The data with which to update each document. Must be a non-empty object.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     update(data: firestore.UpdateData): Promise<MigrationResult>;
-    /**
-     * Updates all documents in this collection with the provided field-value pair.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param field - The field to update in each document.
-     * @param value - The value with which to update the specified field in each document. Must not be `undefined`.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     update(field: string | firestore.FieldPath, value: any): Promise<MigrationResult>;
 }

lib/createBatchMigrator/index.d.ts

@@ -11,3 +11,5 @@ import type { firestore } from 'firebase-admin';
  * This migrator uses batch writes when writing to docs so the entire operation will fail if a single write isn't successful.
+ *
  * @param traverser The traverser object that this migrator will use when traversing the collection and writing to documents.
+ * @returns A batch migrator object.
  */
@@ -20,6 +22,8 @@ export declare function createBatchMigrator<D extends firestore.DocumentData, C extends BaseTraversalConfig, T extends Traverser<D, C>>(traverser: Traverser<D, C>): BatchMigrator<D, C, T>;
  * This migrator uses batch writes when writing to docs so the entire operation will fail if a single write isn't successful.
- * @param traversable A collection-like traversable group of documents to migrate.
+ *
+ * @param traversable A collection-like traversable group of documents.
  * @param traversalConfig Optional. The traversal configuration with which the default traverser will be created.
+ * @returns A batch migrator object.
  */
 export declare function createBatchMigrator<D extends firestore.DocumentData>(traversable: Traversable<D>, traversalConfig?: Partial<BaseTraversalConfig>): BatchMigrator<D, BaseTraversalConfig, SlowTraverser<D>>;
 export { BatchMigrator };

lib/createFastTraverser/FastTraverser.d.ts

 import type { firestore } from 'firebase-admin';
 import { Traverser } from '../Traverser';
 import type { Traversable, FastTraversalConfig, TraversalResult, BatchCallbackAsync } from '../types';
+/**
+ * A fast traverser object that facilitates Firestore collection traversals.
+ */
 export declare class FastTraverser<D extends firestore.DocumentData> extends Traverser<D, FastTraversalConfig> {
@@ -18,3 +21,3 @@ readonly traversable: Traversable<D>;
      * - Space complexity: _O_(`maxConcurrentBatchCount` * (`batchSize` * _D_ + _S_))
-     * - Billing: _N_ reads
+     * - Billing: _max_(1, _N_) reads
      *
@@ -21,0 +24,0 @@ * where:

lib/createFastTraverser/FastTraverser.js

@@ -72,2 +72,5 @@ "use strict";
 var PROCESS_QUEUE_INTERVAL = 250;
+/**
+ * A fast traverser object that facilitates Firestore collection traversals.
+ */
 var FastTraverser = /** @class */ (function (_super) {
@@ -94,3 +97,3 @@ __extends(FastTraverser, _super);
      * - Space complexity: _O_(`maxConcurrentBatchCount` * (`batchSize` * _D_ + _S_))
-     * - Billing: _N_ reads
+     * - Billing: _max_(1, _N_) reads
      *
@@ -97,0 +100,0 @@ * where:

lib/createFastTraverser/index.d.ts

@@ -10,4 +10,8 @@ import type { firestore } from 'firebase-admin';
  * before a later batch. This traverser uses more memory but is significantly faster than the default traverser.
+ *
+ * @param traversable A collection-like traversable group of documents.
+ * @param config Optional. The traversal configuration with which the traverser will be created.
+ * @returns A fast traverser object.
  */
 export declare function createFastTraverser<D extends firestore.DocumentData>(traversable: Traversable<D>, config?: Partial<FastTraversalConfig>): FastTraverser<D>;
 export { FastTraverser };

lib/createFastTraverser/index.js

@@ -12,2 +12,6 @@ "use strict";
  * before a later batch. This traverser uses more memory but is significantly faster than the default traverser.
+ *
+ * @param traversable A collection-like traversable group of documents.
+ * @param config Optional. The traversal configuration with which the traverser will be created.
+ * @returns A fast traverser object.
  */
@@ -14,0 +18,0 @@ function createFastTraverser(traversable, config) {

lib/createMigrator/DefaultMigrator.d.ts

@@ -24,152 +24,9 @@ import type { firestore } from 'firebase-admin';
     withTraverser<C2 extends BaseTraversalConfig>(traverser: Traverser<D, C2>): DefaultMigrator<D, C2, Traverser<D, C2>>;
-    /**
-     * Sets all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param data - The data with which to set each document.
-     * @param options - An object to configure the set behavior.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     set(data: Partial<D>, options: SetOptions): Promise<MigrationResult>;
-    /**
-     * Sets all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param data - The data with which to set each document.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     set(data: D): Promise<MigrationResult>;
-    /**
-     * Sets all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param getData - A function that returns an object with which to set each document.
-     * @param options - An object to configure the set behavior.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     set(getData: SetPartialDataGetter<D>, options: SetOptions): Promise<MigrationResult>;
-    /**
-     * Sets all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param getData - A function that returns an object with which to set each document.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     set(getData: SetDataGetter<D>): Promise<MigrationResult>;
-    /**
-     * Updates all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param getData - A function that returns the data with which to update each document.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     update(getData: UpdateDataGetter<D>): Promise<MigrationResult>;
-    /**
-     * Updates all documents in this collection with the provided data.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param data - The data with which to update each document. Must be a non-empty object.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     update(data: firestore.UpdateData): Promise<MigrationResult>;
-    /**
-     * Updates all documents in this collection with the provided field-value pair.
-     *
-     * **Properties:**
-     *
-     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
-     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-     * - Billing: _N_ reads, _K_ writes
-     *
-     * where:
-     *
-     * - _N_: number of docs in the traversable
-     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
-     * - _W_(`batchSize`): average batch write time
-     * - _TC_(`traverser`): time complexity of the underlying traverser
-     * - _SC_(`traverser`): space complexity of the underlying traverser
-     *
-     * @param field - The field to update in each document.
-     * @param value - The value with which to update the specified field in each document. Must not be `undefined`.
-     * @returns A Promise resolving to an object representing the details of the migration.
-     */
     update(field: string | firestore.FieldPath, value: any): Promise<MigrationResult>;
 }

lib/createMigrator/index.d.ts

@@ -12,2 +12,3 @@ import type { firestore } from 'firebase-admin';
  * @param traverser The traverser object that this migrator will use when traversing the collection and writing to documents.
+ * @returns A default migrator object.
  */
@@ -22,4 +23,5 @@ export declare function createMigrator<D extends firestore.DocumentData, C extends BaseTraversalConfig, T extends Traverser<D, C>>(traverser: Traverser<D, C>): DefaultMigrator<D, C, T>;
  * @param traversalConfig Optional. The traversal configuration with which the default traverser will be created.
+ * @returns A default migrator object.
  */
 export declare function createMigrator<D extends firestore.DocumentData>(traversable: Traversable<D>, traversalConfig?: Partial<BaseTraversalConfig>): DefaultMigrator<D, BaseTraversalConfig, SlowTraverser<D>>;
 export { DefaultMigrator };

lib/createTraverser/index.d.ts

@@ -8,4 +8,8 @@ import type { firestore } from 'firebase-admin';
  * Promise to resolve before moving to the next batch.
+ *
+ * @param traversable A collection-like traversable group of documents.
+ * @param config Optional. The traversal configuration with which the traverser will be created.
+ * @returns A default (slow) traverser object.
  */
 export declare function createTraverser<D extends firestore.DocumentData>(traversable: Traversable<D>, config?: Partial<BaseTraversalConfig>): SlowTraverser<D>;
 export { SlowTraverser };

lib/createTraverser/index.js

@@ -10,2 +10,6 @@ "use strict";
  * Promise to resolve before moving to the next batch.
+ *
+ * @param traversable A collection-like traversable group of documents.
+ * @param config Optional. The traversal configuration with which the traverser will be created.
+ * @returns A default (slow) traverser object.
  */
@@ -12,0 +16,0 @@ function createTraverser(traversable, config) {

lib/createTraverser/SlowTraverser.d.ts

 import type { firestore } from 'firebase-admin';
 import { Traverser } from '../Traverser';
 import type { Traversable, BaseTraversalConfig, TraversalResult, BatchCallbackAsync } from '../types';
+/**
+ * A slow traverser object that facilitates Firestore collection traversals.
+ */
 export declare class SlowTraverser<D extends firestore.DocumentData> extends Traverser<D, BaseTraversalConfig> {
     readonly traversable: Traversable<D>;
     constructor(traversable: Traversable<D>, config?: Partial<BaseTraversalConfig>);
-    withConfig(c: Partial<BaseTraversalConfig>): SlowTraverser<D>;
     /**
+     * Applies a the specified config values to the traverser.
+     *
+     * @param config Partial traversal configuration.
+     * @returns A new SlowTraverser object.
+     */
+    withConfig(config: Partial<BaseTraversalConfig>): SlowTraverser<D>;
+    /**
      * Traverses the entire collection in batches of the size specified in traversal config. Invokes the specified
@@ -16,3 +25,3 @@ * async callback for each batch of document snapshots. Waits for the callback Promise to resolve before moving to the next batch.
      * - Space complexity: _O_(`batchSize` * _D_ + _S_)
-     * - Billing: _N_ reads
+     * - Billing: max(1, _N_) reads
      *
@@ -28,5 +37,5 @@ * where:
      * @param callback An asynchronous callback function to invoke for each batch of document snapshots.
-     * @returns A Promise resolving to an object representing the details of the traversal.
+     * @returns A Promise resolving to an object representing the details of the traversal. The Promise resolves when the entire traversal ends.
      */
     traverse(callback: BatchCallbackAsync<D>): Promise<TraversalResult>;
 }

lib/createTraverser/SlowTraverser.js

@@ -69,2 +69,5 @@ "use strict";
 var defaultTraversalConfig = Traverser_1.Traverser.getDefaultConfig();
+/**
+ * A slow traverser object that facilitates Firestore collection traversals.
+ */
 var SlowTraverser = /** @class */ (function (_super) {
@@ -77,4 +80,10 @@ __extends(SlowTraverser, _super);
     }
-    SlowTraverser.prototype.withConfig = function (c) {
-        return new SlowTraverser(this.traversable, __assign(__assign({}, this.traversalConfig), c));
+    /**
+     * Applies a the specified config values to the traverser.
+     *
+     * @param config Partial traversal configuration.
+     * @returns A new SlowTraverser object.
+     */
+    SlowTraverser.prototype.withConfig = function (config) {
+        return new SlowTraverser(this.traversable, __assign(__assign({}, this.traversalConfig), config));
     };
@@ -89,3 +98,3 @@ /**
      * - Space complexity: _O_(`batchSize` * _D_ + _S_)
-     * - Billing: _N_ reads
+     * - Billing: max(1, _N_) reads
      *
@@ -101,3 +110,3 @@ * where:
      * @param callback An asynchronous callback function to invoke for each batch of document snapshots.
-     * @returns A Promise resolving to an object representing the details of the traversal.
+     * @returns A Promise resolving to an object representing the details of the traversal. The Promise resolves when the entire traversal ends.
      */
@@ -104,0 +113,0 @@ SlowTraverser.prototype.traverse = function (callback) {

lib/Migrator.d.ts

 import type { firestore } from 'firebase-admin';
 import type { Traverser } from './Traverser';
 import type { BaseTraversalConfig, BatchCallback, SetOptions, SetDataGetter, SetPartialDataGetter, UpdateDataGetter, MigrationPredicate, MigrationResult } from './types';
+/**
+ * Represents the general interface of a migrator.
+ */
 export declare abstract class Migrator<D extends firestore.DocumentData, C extends BaseTraversalConfig> {
@@ -27,9 +30,152 @@ protected registeredCallbacks: {
     abstract set(getData: SetPartialDataGetter<D>, options: SetOptions): Promise<MigrationResult>;
+    /**
+     * Sets all documents in this collection with the provided data.
+     *
+     * **Properties:**
+     *
+     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
+     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
+     * - Billing: _max_(1, _N_) reads, _K_ writes
+     *
+     * where:
+     *
+     * - _N_: number of docs in the traversable
+     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
+     * - _W_(`batchSize`): average batch write time
+     * - _TC_(`traverser`): time complexity of the underlying traverser
+     * - _SC_(`traverser`): space complexity of the underlying traverser
+     *
+     * @param data - The data with which to set each document.
+     * @param options - An object to configure the set behavior.
+     * @returns A Promise resolving to an object representing the details of the migration.
+     */
     abstract set(data: Partial<D>, options: SetOptions): Promise<MigrationResult>;
+    /**
+     * Sets all documents in this collection with the provided data.
+     *
+     * **Properties:**
+     *
+     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
+     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
+     * - Billing: _max_(1, _N_) reads, _K_ writes
+     *
+     * where:
+     *
+     * - _N_: number of docs in the traversable
+     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
+     * - _W_(`batchSize`): average batch write time
+     * - _TC_(`traverser`): time complexity of the underlying traverser
+     * - _SC_(`traverser`): space complexity of the underlying traverser
+     *
+     * @param data - The data with which to set each document.
+     * @returns A Promise resolving to an object representing the details of the migration.
+     */
     abstract set(data: D): Promise<MigrationResult>;
+    /**
+     * Sets all documents in this collection with the provided data.
+     *
+     * **Properties:**
+     *
+     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
+     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
+     * - Billing: _max_(1, _N_) reads, _K_ writes
+     *
+     * where:
+     *
+     * - _N_: number of docs in the traversable
+     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
+     * - _W_(`batchSize`): average batch write time
+     * - _TC_(`traverser`): time complexity of the underlying traverser
+     * - _SC_(`traverser`): space complexity of the underlying traverser
+     *
+     * @param getData - A function that returns the data with which to set each document.
+     * @param options - An object to configure the set behavior.
+     * @returns A Promise resolving to an object representing the details of the migration.
+     */
     abstract set(getData: SetPartialDataGetter<D>, options: SetOptions): Promise<MigrationResult>;
+    /**
+     * Sets all documents in this collection with the provided data.
+     *
+     * **Properties:**
+     *
+     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
+     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
+     * - Billing: _max_(1, _N_) reads, _K_ writes
+     *
+     * where:
+     *
+     * - _N_: number of docs in the traversable
+     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
+     * - _W_(`batchSize`): average batch write time
+     * - _TC_(`traverser`): time complexity of the underlying traverser
+     * - _SC_(`traverser`): space complexity of the underlying traverser
+     *
+     * @param getData - A function that returns the data with which to set each document.
+     * @returns A Promise resolving to an object representing the details of the migration.
+     */
     abstract set(getData: SetDataGetter<D>): Promise<MigrationResult>;
+    /**
+     * Updates all documents in this collection with the provided data.
+     *
+     * **Properties:**
+     *
+     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
+     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
+     * - Billing: _max_(1, _N_) reads, _K_ writes
+     *
+     * where:
+     *
+     * - _N_: number of docs in the traversable
+     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
+     * - _W_(`batchSize`): average batch write time
+     * - _TC_(`traverser`): time complexity of the underlying traverser
+     * - _SC_(`traverser`): space complexity of the underlying traverser
+     *
+     * @param getData - A function that returns the data with which to update each document.
+     * @returns A Promise resolving to an object representing the details of the migration.
+     */
     abstract update(getData: UpdateDataGetter<D>): Promise<MigrationResult>;
+    /**
+     * Updates all documents in this collection with the provided data.
+     *
+     * **Properties:**
+     *
+     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
+     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
+     * - Billing: _max_(1, _N_) reads, _K_ writes
+     *
+     * where:
+     *
+     * - _N_: number of docs in the traversable
+     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
+     * - _W_(`batchSize`): average batch write time
+     * - _TC_(`traverser`): time complexity of the underlying traverser
+     * - _SC_(`traverser`): space complexity of the underlying traverser
+     *
+     * @param data - The data with which to update each document. Must be a non-empty object.
+     * @returns A Promise resolving to an object representing the details of the migration.
+     */
     abstract update(data: firestore.UpdateData): Promise<MigrationResult>;
+    /**
+     * Updates all documents in this collection with the provided field-value pair.
+     *
+     * **Properties:**
+     *
+     * - Time complexity: _TC_(`traverser`) where _C_ = _W_(`batchSize`)
+     * - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
+     * - Billing: _max_(1, _N_) reads, _K_ writes
+     *
+     * where:
+     *
+     * - _N_: number of docs in the traversable
+     * - _K_: number of docs that passed the migration predicate (_K_<=_N_)
+     * - _W_(`batchSize`): average batch write time
+     * - _TC_(`traverser`): time complexity of the underlying traverser
+     * - _SC_(`traverser`): space complexity of the underlying traverser
+     *
+     * @param field - The field to update in each document.
+     * @param value - The value with which to update the specified field in each document. Must not be `undefined`.
+     * @returns A Promise resolving to an object representing the details of the migration.
+     */
     abstract update(field: string | firestore.FieldPath, value: any): Promise<MigrationResult>;
 }

lib/Migrator.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Migrator = void 0;
+/**
+ * Represents the general interface of a migrator.
+ */
 var Migrator = /** @class */ (function () {
@@ -5,0 +8,0 @@ function Migrator() {

lib/Traverser.d.ts

 import type { firestore } from 'firebase-admin';
 import type { Traversable, BaseTraversalConfig, TraverseEachConfig, TraversalResult, BatchCallbackAsync } from './types';
+/**
+ * Represents the general interface of a traverser.
+ */
 export declare abstract class Traverser<D extends firestore.DocumentData, C extends BaseTraversalConfig> {
@@ -12,3 +15,3 @@ static getDefaultConfig(): BaseTraversalConfig;
      * @param config The sequential traversal configuration.
-     * @returns A Promise resolving to an object representing the details of the traversal.
+     * @returns A Promise resolving to an object representing the details of the traversal. The Promise resolves when the entire traversal ends.
      */
@@ -15,0 +18,0 @@ traverseEach(callback: (snapshot: firestore.QueryDocumentSnapshot<D>) => Promise<void>, c?: Partial<TraverseEachConfig>): Promise<TraversalResult>;

lib/Traverser.js

@@ -76,2 +76,5 @@ "use strict";
 }
+/**
+ * Represents the general interface of a traverser.
+ */
 var Traverser = /** @class */ (function () {
@@ -90,3 +93,3 @@ function Traverser(c) {
      * @param config The sequential traversal configuration.
-     * @returns A Promise resolving to an object representing the details of the traversal.
+     * @returns A Promise resolving to an object representing the details of the traversal. The Promise resolves when the entire traversal ends.
      */
@@ -93,0 +96,0 @@ Traverser.prototype.traverseEach = function (callback, c) {

package.json

 {
   "name": "@firecode/admin",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "A collection traversal library for Firestore",
@@ -48,3 +48,3 @@ "keywords": [
   },
-  "gitHead": "413879072fa8f93cf75b8fda63cd94bc2de35155"
+  "gitHead": "f710279eb81ab8ac02816545e448f054d12c2d4d"
 }

README.md

@@ -5,3 +5,3 @@ # Firecode
 
-When you have millions of documents in a collection, you can't just get all of them at once as your program's memory will explode. Firecode's configurable traverser objects let you do this in a simple, intuitive and memory-efficient way using batching.
+When you have millions of documents in a collection, you can't just get all of them at once as your program's memory usage will explode. Firecode's configurable traverser objects let you do this in a simple, intuitive and memory-efficient way using batching.
 
@@ -55,5 +55,5 @@ Firecode is an extremely light, well-typed, zero-dependency library that is useful in a variety of scenarios. You can use it in database migration scripts (e.g. when you need to add a new field to all docs) or a scheduled Cloud Function that needs to check every doc in a collection periodically or a locally run script that retrieves some data from a collection.
 
-1. **Traverser**: An object that walks you through a collection of documents (or more generally a [Traversable](./packages/admin/docs/API.md#Traversable)).
+1. **Traverser**: An object that walks you through a collection of documents (or more generally a [Traversable](./docs/API.md#Traversable)).
 
-2. **Migrator**: A convenience object used for database migrations. It lets you easily write to the documents within a given traversable and uses a traverser to do that.
+2. **Migrator**: A convenience object used for database migrations. It lets you easily write to the documents within a given traversable and uses a traverser to do that. You can easily write your own migration logic in the traverser callback if you don't want to use a migrator.
 
@@ -101,5 +101,5 @@ ## Quick Start
   batchSize: 500,
+  // This means we are prepared to hold 500 * 20 = 10,000 docs in memory
   maxConcurrentBatchCount: 20,
 });
-// This means we should expect to hold 500 * 20 = 10,000 projects in memory
 const { docCount } = await traverser.traverse(async (_, batchIndex) => {
@@ -175,12 +175,14 @@ console.log(`Gonna process batch ${batchIndex} now!`);
 const migrator = createBatchMigrator(postsColGroup);
-const { migratedDocCount } = await migrator.update(
-  (snap) => {
+const { migratedDocCount } = await migrator
+  .withPredicate(
+    // Ignore if it doesn't have a `postedAt` field
+    (snap) => snap.data().postedAt !== undefined
+  )
+  .update((snap) => {
     const { postedAt } = snap.data();
     return {
-      publishedAt: postedAt!, // Safe to assert
+      publishedAt: postedAt!, // Safe to assert now
       postedAt: firestore.FieldValue.delete(),
     };
-  },
-  (snap) => snap.data().postedAt !== undefined // Ignore if it doesn't have a `postedAt` field
-);
+  });
 console.log(`Updated ${migratedDocCount} posts!`);
@@ -201,3 +203,3 @@ ```
 - Space complexity: _O_(`batchSize` \* _D_ + _S_)
-- Billing: _N_ reads
+- Billing: _max_(1, _N_) reads
 
@@ -212,3 +214,3 @@ where:
 
-### [createFastTraverser](./docs/API.md#createFastTraverser) (coming in the next release)
+### [createFastTraverser](./docs/API.md#createFastTraverser)
 
@@ -221,3 +223,3 @@ Creates a fast traverser that facilitates Firestore collection traversals. When traversing the collection, this traverser invokes a specified async callback for each batch of document snapshots and immediately moves to the next batch. It 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. This traverser uses more memory but is significantly faster than the default traverser.
 - Space complexity: _O_(`maxConcurrentBatchCount` \* (`batchSize` \* _D_ + _S_))
-- Billing: _N_ reads
+- Billing: _max_(1, _N_) reads
 
@@ -232,3 +234,3 @@ where:
 
-### [createMigrator](./docs/API.md#createMigrator) (coming in v0.7)
+### [createMigrator](./docs/API.md#createMigrator)
 
@@ -241,3 +243,3 @@ Creates a migrator that facilitates database migrations. The migrator accepts a custom traverser to traverse the collection. Otherwise it will create a default traverser with your desired traversal config. This migrator does not use atomic writes so it is possible that when a write fails other writes go through.
 - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-- Billing: _N_ reads, _K_ writes
+- Billing: _max_(1, _N_) reads, _K_ writes
 
@@ -260,3 +262,3 @@ where:
 - Space complexity: _SC_(`traverser`) where _S_ = _O_(`batchSize`)
-- Billing: _N_ reads, _K_ writes
+- Billing: _max_(1, _N_) reads, _K_ writes
 
@@ -263,0 +265,0 @@ where:

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

270

increased by0.75%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Total package byte prevSize

149200

decreased by-2.39%

Lines of code

2090

decreased by-3.91%

No dependency changes