firestore-batch-updater 1.11.0 → 1.13.0

package/README.ko.md

@@ -20,6 +20,7 @@
 - 비어있는지 확인 - `isEmpty()`로 매칭 문서가 없는지 확인 (`exists()`의 반대)
 - 전체 문서 조회 - `getAll()`로 매칭되는 모든 문서 데이터 조회
 - 집계 쿼리 - `aggregate()`로 서버 사이드 `sum`, `average`, `count` 연산
+- 간편 집계 - `sum()`과 `avg()`로 단일 필드 간편 집계
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
@@ -28,6 +29,7 @@
 - 고유값 조회 - `distinct()`로 특정 필드의 중복 없는 값 목록 조회
 - JSON 내보내기/가져오기 - `toJSON()` / `fromJSON()`으로 문서 JSON 파일 내보내기/가져오기
 - 그룹별 개수 조회 - `countBy()`로 특정 필드 값별 문서 수 집계
+- 랜덤 샘플링 - `sample()`로 쿼리 결과에서 랜덤 문서 추출
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -113,6 +115,8 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `delete(options?)` | 매칭되는 문서 삭제 | `DeleteResult` |
 | `deleteOne()` | 첫 번째 매칭 문서 삭제 | `{ success, id }` |
 | `aggregate(spec)` | sum/average/count 집계 쿼리 | `AggregateResult` |
+| `sum(field)` | 숫자 필드 합계 조회 | `number \| null` |
+| `avg(field)` | 숫자 필드 평균 조회 | `number \| null` |
 | `paginate(options)` | 커서 기반 페이지네이션 | `PaginateResult` |
 | `bulkCreate(docs, options?)` | 여러 문서를 각기 다른 데이터로 생성 | `BulkCreateResult` |
 | `bulkUpdate(updates, options?)` | 여러 문서에 각기 다른 데이터 업데이트 | `BulkUpdateResult` |
@@ -120,6 +124,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `transform(fn, options?)` | 커스텀 함수로 문서 변환 | `TransformResult` |
 | `copyTo(target, options?)` | 다른 컬렉션으로 문서 복사/이동 | `CopyToResult` |
 | `distinct(field)` | 특정 필드의 고유값 조회 | `any[]` |
+| `sample(n)` | 매칭 문서에서 랜덤 샘플 추출 | `{ id, data }[]` |
 | `toJSON(path, options?)` | 문서를 JSON 파일로 내보내기 | `ToJSONResult` |
 | `fromJSON(path, options?)` | JSON 파일에서 문서 가져오기 | `FromJSONResult` |
 | `countBy(field)` | 필드 값별 문서 수 집계 | `CountByResult` |
@@ -511,6 +516,30 @@ console.log(`평균: ${stats.avgAmount}원`);
 console.log(`주문 수: ${stats.orderCount}건`);
 ```
 
+### 간편 합계 & 평균
+
+```typescript
+// 필드 합계를 바로 조회 (aggregate spec 불필요)
+const totalRevenue = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .sum("amount");
+
+console.log(`총 매출: ${totalRevenue}원`);
+
+// 필드 평균을 바로 조회
+const avgScore = await updater
+  .collection("users")
+  .where("status", "==", "active")
+  .avg("score");
+
+console.log(`평균 점수: ${avgScore}`);
+
+// aggregate()와 동일하지만 단일 필드 조회 시 더 간편
+// aggregate({ total: { op: "sum", field: "amount" } }) → sum("amount")
+// aggregate({ avg: { op: "average", field: "score" } }) → avg("score")
+```
+
 ### 커서 기반 페이지네이션
 
 ```typescript
@@ -752,6 +781,26 @@ await updater.collection("users").toJSON("./backup.json");
 await updater.collection("users_backup").fromJSON("./backup.json");
 ```
 
+### 랜덤 샘플링
+
+```typescript
+// 랜덤으로 5개 문서 추출
+const samples = await updater.collection("users").sample(5);
+samples.forEach(doc => console.log(doc.id, doc.data.name));
+
+// 필터된 결과에서 랜덤 샘플
+const activeUsers = await updater
+  .collection("users")
+  .where("status", "==", "active")
+  .sample(3);
+
+// select와 함께 사용하여 메모리 효율 극대화
+const randomProducts = await updater
+  .collection("products")
+  .select("name", "price")
+  .sample(10);
+```
+
 ### Dry Run 모드
 
 ```typescript

package/README.md

@@ -20,6 +20,7 @@ English | [한국어](./README.ko.md)
 - Empty check - Use `isEmpty()` to check if no matching documents exist (opposite of `exists()`)
 - Get all documents - Use `getAll()` to retrieve all matching documents with data
 - Aggregation - Use `aggregate()` for server-side `sum`, `average`, and `count` operations
+- Quick aggregation - Use `sum()` and `avg()` for simple single-field aggregation
 - Cursor pagination - Use `paginate()` for memory-efficient page-by-page iteration
 - Direct ID lookup - Use `getOne()` for fast document retrieval by ID
 - Bulk operations - Use `bulkCreate()`, `bulkUpdate()`, `bulkDelete()` for efficient multi-document operations with different data each
@@ -28,6 +29,7 @@ English | [한국어](./README.ko.md)
 - Distinct values - Use `distinct()` to get unique field values from matching documents
 - JSON export/import - Use `toJSON()` / `fromJSON()` to export/import documents as JSON
 - Group counting - Use `countBy()` to count documents grouped by field value
+- Random sampling - Use `sample()` to get random documents from query results
 - FieldValue support - Use `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()`, etc.
 - Subcollection & Collection Group - Query subcollections or all collections with the same name
 - Dry run mode - Simulate operations without making changes
@@ -113,6 +115,8 @@ console.log(`Updated ${result.successCount} documents`);
 | `delete(options?)` | Delete matching documents | `DeleteResult` |
 | `deleteOne()` | Delete first matching document | `{ success, id }` |
 | `aggregate(spec)` | Run sum/average/count queries | `AggregateResult` |
+| `sum(field)` | Get sum of a numeric field | `number \| null` |
+| `avg(field)` | Get average of a numeric field | `number \| null` |
 | `paginate(options)` | Cursor-based pagination | `PaginateResult` |
 | `bulkCreate(docs, options?)` | Create multiple docs with different data | `BulkCreateResult` |
 | `bulkUpdate(updates, options?)` | Update multiple docs with different data | `BulkUpdateResult` |
@@ -120,6 +124,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `transform(fn, options?)` | Transform docs with custom function | `TransformResult` |
 | `copyTo(target, options?)` | Copy/move docs to another collection | `CopyToResult` |
 | `distinct(field)` | Get unique values of a field | `any[]` |
+| `sample(n)` | Get random sample of matching documents | `{ id, data }[]` |
 | `toJSON(path, options?)` | Export documents to JSON file | `ToJSONResult` |
 | `fromJSON(path, options?)` | Import documents from JSON file | `FromJSONResult` |
 | `countBy(field)` | Count documents grouped by field value | `CountByResult` |
@@ -535,6 +540,30 @@ console.log(`Average: $${stats.avgAmount}`);
 console.log(`Orders: ${stats.orderCount}`);
 ```
 
+### Quick Sum & Average
+
+```typescript
+// Get sum of a field directly (no need for aggregate spec)
+const totalRevenue = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .sum("amount");
+
+console.log(`Total revenue: $${totalRevenue}`);
+
+// Get average of a field directly
+const avgScore = await updater
+  .collection("users")
+  .where("status", "==", "active")
+  .avg("score");
+
+console.log(`Average score: ${avgScore}`);
+
+// Equivalent to aggregate(), but simpler for single-field queries
+// aggregate({ total: { op: "sum", field: "amount" } }) → sum("amount")
+// aggregate({ avg: { op: "average", field: "score" } }) → avg("score")
+```
+
 ### Cursor-Based Pagination
 
 ```typescript
@@ -765,6 +794,26 @@ await updater.collection("users").toJSON("./backup.json");
 await updater.collection("users_backup").fromJSON("./backup.json");
 ```
 
+### Random Sampling
+
+```typescript
+// Get 5 random documents
+const samples = await updater.collection("users").sample(5);
+samples.forEach(doc => console.log(doc.id, doc.data.name));
+
+// Random sample from filtered results
+const activeUsers = await updater
+  .collection("users")
+  .where("status", "==", "active")
+  .sample(3);
+
+// With select for memory efficiency
+const randomProducts = await updater
+  .collection("products")
+  .select("name", "price")
+  .sample(10);
+```
+
 ### Dry Run Mode
 
 ```typescript

package/dist/index.d.mts

@@ -641,6 +641,20 @@ declare class BatchUpdater {
      * @returns Object with alias keys and numeric results
      */
     aggregate(spec: AggregateSpec): Promise<AggregateResult>;
+    /**
+     * Get the sum of a numeric field from matching documents
+     * Convenience wrapper around aggregate() for simple sum queries
+     * @param field - Field path to sum
+     * @returns Sum of the field values, or null if no documents match
+     */
+    sum(field: string): Promise<number | null>;
+    /**
+     * Get the average of a numeric field from matching documents
+     * Convenience wrapper around aggregate() for simple average queries
+     * @param field - Field path to average
+     * @returns Average of the field values, or null if no documents match
+     */
+    avg(field: string): Promise<number | null>;
     /**
      * Get documents with cursor-based pagination
      * @param options - Pagination options (pageSize, startAfter cursor)
@@ -730,6 +744,15 @@ declare class BatchUpdater {
      * @returns Array of unique values
      */
     distinct(field: string): Promise<any[]>;
+    /**
+     * Get a random sample of matching documents
+     * @param n - Number of documents to sample
+     * @returns Array of randomly selected documents with { id, data }
+     */
+    sample(n: number): Promise<{
+        id: string;
+        data: Record<string, any>;
+    }[]>;
     /**
      * Export matching documents to a JSON file
      * @param filePath - Path for the output JSON file

package/dist/index.d.ts

@@ -641,6 +641,20 @@ declare class BatchUpdater {
      * @returns Object with alias keys and numeric results
      */
     aggregate(spec: AggregateSpec): Promise<AggregateResult>;
+    /**
+     * Get the sum of a numeric field from matching documents
+     * Convenience wrapper around aggregate() for simple sum queries
+     * @param field - Field path to sum
+     * @returns Sum of the field values, or null if no documents match
+     */
+    sum(field: string): Promise<number | null>;
+    /**
+     * Get the average of a numeric field from matching documents
+     * Convenience wrapper around aggregate() for simple average queries
+     * @param field - Field path to average
+     * @returns Average of the field values, or null if no documents match
+     */
+    avg(field: string): Promise<number | null>;
     /**
      * Get documents with cursor-based pagination
      * @param options - Pagination options (pageSize, startAfter cursor)
@@ -730,6 +744,15 @@ declare class BatchUpdater {
      * @returns Array of unique values
      */
     distinct(field: string): Promise<any[]>;
+    /**
+     * Get a random sample of matching documents
+     * @param n - Number of documents to sample
+     * @returns Array of randomly selected documents with { id, data }
+     */
+    sample(n: number): Promise<{
+        id: string;
+        data: Record<string, any>;
+    }[]>;
     /**
      * Export matching documents to a JSON file
      * @param filePath - Path for the output JSON file

package/dist/index.js

@@ -469,6 +469,38 @@ var BatchUpdater = class {
     }
     return result;
   }
+  /**
+   * Get the sum of a numeric field from matching documents
+   * Convenience wrapper around aggregate() for simple sum queries
+   * @param field - Field path to sum
+   * @returns Sum of the field values, or null if no documents match
+   */
+  async sum(field) {
+    this.validateSetup();
+    if (!field) {
+      throw new Error("Field is required for sum operation");
+    }
+    const result = await this.aggregate({
+      _sum: { op: "sum", field }
+    });
+    return result._sum;
+  }
+  /**
+   * Get the average of a numeric field from matching documents
+   * Convenience wrapper around aggregate() for simple average queries
+   * @param field - Field path to average
+   * @returns Average of the field values, or null if no documents match
+   */
+  async avg(field) {
+    this.validateSetup();
+    if (!field) {
+      throw new Error("Field is required for average operation");
+    }
+    const result = await this.aggregate({
+      _avg: { op: "average", field }
+    });
+    return result._avg;
+  }
   /**
    * Get documents with cursor-based pagination
    * @param options - Pagination options (pageSize, startAfter cursor)
@@ -1231,6 +1263,34 @@ var BatchUpdater = class {
     }
     return values;
   }
+  /**
+   * Get a random sample of matching documents
+   * @param n - Number of documents to sample
+   * @returns Array of randomly selected documents with { id, data }
+   */
+  async sample(n) {
+    this.validateSetup();
+    if (!Number.isInteger(n) || n < 1) {
+      throw new Error("Sample size must be a positive integer");
+    }
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return [];
+    }
+    const docs = snapshot.docs.map((doc) => ({
+      id: doc.id,
+      data: doc.data()
+    }));
+    if (docs.length <= n) {
+      return docs;
+    }
+    for (let i = docs.length - 1; i > docs.length - 1 - n; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [docs[i], docs[j]] = [docs[j], docs[i]];
+    }
+    return docs.slice(docs.length - n);
+  }
   /**
    * Export matching documents to a JSON file
    * @param filePath - Path for the output JSON file

package/dist/index.mjs

@@ -424,6 +424,38 @@ var BatchUpdater = class {
     }
     return result;
   }
+  /**
+   * Get the sum of a numeric field from matching documents
+   * Convenience wrapper around aggregate() for simple sum queries
+   * @param field - Field path to sum
+   * @returns Sum of the field values, or null if no documents match
+   */
+  async sum(field) {
+    this.validateSetup();
+    if (!field) {
+      throw new Error("Field is required for sum operation");
+    }
+    const result = await this.aggregate({
+      _sum: { op: "sum", field }
+    });
+    return result._sum;
+  }
+  /**
+   * Get the average of a numeric field from matching documents
+   * Convenience wrapper around aggregate() for simple average queries
+   * @param field - Field path to average
+   * @returns Average of the field values, or null if no documents match
+   */
+  async avg(field) {
+    this.validateSetup();
+    if (!field) {
+      throw new Error("Field is required for average operation");
+    }
+    const result = await this.aggregate({
+      _avg: { op: "average", field }
+    });
+    return result._avg;
+  }
   /**
    * Get documents with cursor-based pagination
    * @param options - Pagination options (pageSize, startAfter cursor)
@@ -1186,6 +1218,34 @@ var BatchUpdater = class {
     }
     return values;
   }
+  /**
+   * Get a random sample of matching documents
+   * @param n - Number of documents to sample
+   * @returns Array of randomly selected documents with { id, data }
+   */
+  async sample(n) {
+    this.validateSetup();
+    if (!Number.isInteger(n) || n < 1) {
+      throw new Error("Sample size must be a positive integer");
+    }
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return [];
+    }
+    const docs = snapshot.docs.map((doc) => ({
+      id: doc.id,
+      data: doc.data()
+    }));
+    if (docs.length <= n) {
+      return docs;
+    }
+    for (let i = docs.length - 1; i > docs.length - 1 - n; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [docs[i], docs[j]] = [docs[j], docs[i]];
+    }
+    return docs.slice(docs.length - n);
+  }
   /**
    * Export matching documents to a JSON file
    * @param filePath - Path for the output JSON file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firestore-batch-updater",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",