firestore-batch-updater 1.16.0 → 1.18.0

package/README.ko.md

@@ -21,6 +21,7 @@
 - 전체 문서 조회 - `getAll()`로 매칭되는 모든 문서 데이터 조회
 - 집계 쿼리 - `aggregate()`로 서버 사이드 `sum`, `average`, `count` 연산
 - 간편 집계 - `sum()`, `avg()`, `min()`, `max()`로 단일 필드 간편 집계
+- 통합 통계 - `fieldStats()`로 sum/avg/min/max/count 한 번에 조회
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
@@ -29,6 +30,7 @@
 - 고유값 조회 - `distinct()`로 특정 필드의 중복 없는 값 목록 조회
 - JSON 내보내기/가져오기 - `toJSON()` / `fromJSON()`으로 문서 JSON 파일 내보내기/가져오기
 - 그룹별 개수 조회 - `countBy()`로 특정 필드 값별 문서 수 집계
+- 그룹별 문서 조회 - `groupBy()`로 필드 값별로 문서 그룹핑
 - 랜덤 샘플링 - `sample()`로 쿼리 결과에서 랜덤 문서 추출
 - 필드 값 추출 - `pluck()`로 특정 필드 값만 간단하게 배열로 추출
 - 문서 ID 추출 - `pluckIds()`로 매칭 문서의 ID만 배열로 추출
@@ -121,6 +123,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `avg(field)` | 숫자 필드 평균 조회 | `number \| null` |
 | `min(field)` | 필드 최소값 조회 | `any` |
 | `max(field)` | 필드 최대값 조회 | `any` |
+| `fieldStats(field)` | sum/avg/min/max/count 한 번에 조회 | `FieldStatsResult` |
 | `paginate(options)` | 커서 기반 페이지네이션 | `PaginateResult` |
 | `bulkCreate(docs, options?)` | 여러 문서를 각기 다른 데이터로 생성 | `BulkCreateResult` |
 | `bulkUpdate(updates, options?)` | 여러 문서에 각기 다른 데이터 업데이트 | `BulkUpdateResult` |
@@ -134,6 +137,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `toJSON(path, options?)` | 문서를 JSON 파일로 내보내기 | `ToJSONResult` |
 | `fromJSON(path, options?)` | JSON 파일에서 문서 가져오기 | `FromJSONResult` |
 | `countBy(field)` | 필드 값별 문서 수 집계 | `CountByResult` |
+| `groupBy(field)` | 필드 값별 문서 그룹핑 | `GroupByResult` |
 | `getFields(field)` | 특정 필드 값 조회 | `FieldValueResult[]` |
 
 ### 옵션
@@ -182,6 +186,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `UpsertResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `DeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
 | `AggregateResult` | `{ [alias]: number \| null }` |
+| `FieldStatsResult` | `sum`, `avg`, `min`, `max`, `count` |
 | `PaginateResult` | `docs[]`, `nextCursor`, `hasMore` |
 | `BulkCreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
@@ -191,6 +196,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `ToJSONResult` | `filePath`, `documentCount` |
 | `FromJSONResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `CountByResult` | `{ [value]: number }` |
+| `GroupByResult` | `{ [value]: { id, data }[] }` |
 | `FieldValueResult` | `id`, `value` |
 
 ## 사용 예시
@@ -569,6 +575,26 @@ const maxScore = await updater
 
 > 참고: 한 필드에 `where()`를 걸고 다른 필드에 `min()/max()`를 사용할 경우 Firestore 복합 인덱스가 필요할 수 있습니다. `FAILED_PRECONDITION` 오류가 발생하면 오류 메시지의 링크를 통해 인덱스를 생성하세요.
 
+### 통합 필드 통계
+
+```typescript
+// 한 필드의 sum, avg, min, max, count를 한 번에 조회
+const stats = await updater.collection("products").fieldStats("price");
+console.log(stats);
+// { sum: 12500, avg: 250, min: 50, max: 500, count: 50 }
+
+// 대시보드에서 유용
+const orderStats = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .fieldStats("amount");
+
+console.log(`총 매출: ${orderStats.sum}원`);
+console.log(`평균 주문액: ${orderStats.avg}원`);
+console.log(`주문 수: ${orderStats.count}건`);
+console.log(`범위: ${orderStats.min}원 - ${orderStats.max}원`);
+```
+
 ### 커서 기반 페이지네이션
 
 ```typescript
@@ -789,6 +815,33 @@ const countryCounts = await updater.collection("users").countBy("address.country
 console.log(countryCounts); // { US: 80, KR: 45, JP: 25 }
 ```
 
+### 필드 값별 문서 그룹핑
+
+```typescript
+// 필드 값별로 문서를 그룹핑 (전체 문서 데이터 포함)
+const usersByRole = await updater.collection("users").groupBy("role");
+
+console.log(`관리자: ${usersByRole.admin.length}명`);
+usersByRole.admin.forEach(user => {
+  console.log(`- ${user.id}: ${user.data.name}`);
+});
+
+// where 필터와 함께 사용
+const activeProducts = await updater
+  .collection("products")
+  .where("status", "==", "active")
+  .groupBy("category");
+
+for (const [category, products] of Object.entries(activeProducts)) {
+  console.log(`${category}: ${products.length}개`);
+}
+
+// 중첩 필드 지원
+const usersByCountry = await updater
+  .collection("users")
+  .groupBy("address.country");
+```
+
 ### JSON 가져오기
 
 ```typescript

package/README.md

@@ -21,6 +21,7 @@ English | [한국어](./README.ko.md)
 - 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()`, `avg()`, `min()`, `max()` for simple single-field aggregation
+- Combined stats - Use `fieldStats()` to get sum/avg/min/max/count in one call
 - 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
@@ -29,6 +30,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
+- Group documents - Use `groupBy()` to group matching documents by a field value
 - Random sampling - Use `sample()` to get random documents from query results
 - Field value extraction - Use `pluck()` to get a simple array of field values
 - Document ID extraction - Use `pluckIds()` to get an array of matching document IDs
@@ -121,6 +123,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `avg(field)` | Get average of a numeric field | `number \| null` |
 | `min(field)` | Get minimum value of a field | `any` |
 | `max(field)` | Get maximum value of a field | `any` |
+| `fieldStats(field)` | Get sum/avg/min/max/count for a field in one call | `FieldStatsResult` |
 | `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` |
@@ -134,6 +137,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `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` |
+| `groupBy(field)` | Group documents by field value | `GroupByResult` |
 | `getFields(field)` | Get specific field values | `FieldValueResult[]` |
 
 ### Options
@@ -182,6 +186,7 @@ All write operations support an optional `options` parameter:
 | `UpsertResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `DeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
 | `AggregateResult` | `{ [alias]: number \| null }` |
+| `FieldStatsResult` | `sum`, `avg`, `min`, `max`, `count` |
 | `PaginateResult` | `docs[]`, `nextCursor`, `hasMore` |
 | `BulkCreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
@@ -191,6 +196,7 @@ All write operations support an optional `options` parameter:
 | `ToJSONResult` | `filePath`, `documentCount` |
 | `FromJSONResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `CountByResult` | `{ [value]: number }` |
+| `GroupByResult` | `{ [value]: { id, data }[] }` |
 | `FieldValueResult` | `id`, `value` |
 
 ## Usage Examples
@@ -593,6 +599,26 @@ const maxScore = await updater
 
 > Note: Combining `where()` on one field with `min()/max()` on a different field may require a Firestore composite index. If you see a `FAILED_PRECONDITION` error, follow the link in the error message to create the required index.
 
+### Combined Field Stats
+
+```typescript
+// Get sum, avg, min, max, count for a single field in one call
+const stats = await updater.collection("products").fieldStats("price");
+console.log(stats);
+// { sum: 12500, avg: 250, min: 50, max: 500, count: 50 }
+
+// Useful for dashboards
+const orderStats = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .fieldStats("amount");
+
+console.log(`Total revenue: $${orderStats.sum}`);
+console.log(`Average order: $${orderStats.avg}`);
+console.log(`Order count: ${orderStats.count}`);
+console.log(`Range: $${orderStats.min} - $${orderStats.max}`);
+```
+
 ### Cursor-Based Pagination
 
 ```typescript
@@ -802,6 +828,33 @@ const countryCounts = await updater.collection("users").countBy("address.country
 console.log(countryCounts); // { US: 80, KR: 45, JP: 25 }
 ```
 
+### Group Documents by Field Value
+
+```typescript
+// Group documents by a field value (with full document data)
+const usersByRole = await updater.collection("users").groupBy("role");
+
+console.log(`Admins: ${usersByRole.admin.length}`);
+usersByRole.admin.forEach(user => {
+  console.log(`- ${user.id}: ${user.data.name}`);
+});
+
+// With where filter
+const activeProducts = await updater
+  .collection("products")
+  .where("status", "==", "active")
+  .groupBy("category");
+
+for (const [category, products] of Object.entries(activeProducts)) {
+  console.log(`${category}: ${products.length} products`);
+}
+
+// Nested field support
+const usersByCountry = await updater
+  .collection("users")
+  .groupBy("address.country");
+```
+
 ### Import from JSON
 
 ```typescript

package/dist/index.d.mts

@@ -455,12 +455,33 @@ interface CopyToResult {
     copiedIds: string[];
     failedDocIds?: string[];
 }
+/**
+ * Result of fieldStats operation
+ * Combined statistics for a single field
+ */
+interface FieldStatsResult {
+    sum: number | null;
+    avg: number | null;
+    min: any;
+    max: any;
+    count: number;
+}
 /**
  * Result of countBy operation
  */
 interface CountByResult {
     [value: string]: number;
 }
+/**
+ * Result of groupBy operation
+ * Field value → array of matching documents
+ */
+interface GroupByResult {
+    [value: string]: {
+        id: string;
+        data: Record<string, any>;
+    }[];
+}
 /**
  * Options for fromJSON operation
  */
@@ -669,6 +690,13 @@ declare class BatchUpdater {
      * @returns Maximum field value, or null if no documents match
      */
     max(field: string): Promise<any>;
+    /**
+     * Get combined statistics (sum, avg, min, max, count) for a single field
+     * Convenience method that runs aggregate + min + max in parallel
+     * @param field - Field path to compute statistics for
+     * @returns Object with sum, avg, min, max, count
+     */
+    fieldStats(field: string): Promise<FieldStatsResult>;
     /**
      * Get documents with cursor-based pagination
      * @param options - Pagination options (pageSize, startAfter cursor)
@@ -793,6 +821,12 @@ declare class BatchUpdater {
      * @returns Object mapping field values to their document counts
      */
     countBy(field: string): Promise<CountByResult>;
+    /**
+     * Group matching documents by a specific field value
+     * @param field - Field path to group by
+     * @returns Object mapping field values to arrays of matching documents { id, data }
+     */
+    groupBy(field: string): Promise<GroupByResult>;
     /**
      * Import documents from a JSON file into Firestore
      * @param filePath - Path to the JSON file to import
@@ -897,4 +931,4 @@ declare function isValidUpdateData(value: any): value is Record<string, any>;
  */
 declare function formatError(error: unknown, context?: string): string;
 
-export { type AggregateResult, type AggregateSpec, BatchUpdater, type BulkCreateInput, type BulkCreateOptions, type BulkCreateResult, type BulkDeleteOptions, type BulkDeleteResult, type BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CopyToOptions, type CopyToResult, type CountByResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type FromJSONOptions, type FromJSONResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type ToJSONOptions, type ToJSONResult, type TransformFn, type TransformOptions, type TransformResult, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };
+export { type AggregateResult, type AggregateSpec, BatchUpdater, type BulkCreateInput, type BulkCreateOptions, type BulkCreateResult, type BulkDeleteOptions, type BulkDeleteResult, type BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CopyToOptions, type CopyToResult, type CountByResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldStatsResult, type FieldValueResult, type FromJSONOptions, type FromJSONResult, type GroupByResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type ToJSONOptions, type ToJSONResult, type TransformFn, type TransformOptions, type TransformResult, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };

package/dist/index.d.ts

@@ -455,12 +455,33 @@ interface CopyToResult {
     copiedIds: string[];
     failedDocIds?: string[];
 }
+/**
+ * Result of fieldStats operation
+ * Combined statistics for a single field
+ */
+interface FieldStatsResult {
+    sum: number | null;
+    avg: number | null;
+    min: any;
+    max: any;
+    count: number;
+}
 /**
  * Result of countBy operation
  */
 interface CountByResult {
     [value: string]: number;
 }
+/**
+ * Result of groupBy operation
+ * Field value → array of matching documents
+ */
+interface GroupByResult {
+    [value: string]: {
+        id: string;
+        data: Record<string, any>;
+    }[];
+}
 /**
  * Options for fromJSON operation
  */
@@ -669,6 +690,13 @@ declare class BatchUpdater {
      * @returns Maximum field value, or null if no documents match
      */
     max(field: string): Promise<any>;
+    /**
+     * Get combined statistics (sum, avg, min, max, count) for a single field
+     * Convenience method that runs aggregate + min + max in parallel
+     * @param field - Field path to compute statistics for
+     * @returns Object with sum, avg, min, max, count
+     */
+    fieldStats(field: string): Promise<FieldStatsResult>;
     /**
      * Get documents with cursor-based pagination
      * @param options - Pagination options (pageSize, startAfter cursor)
@@ -793,6 +821,12 @@ declare class BatchUpdater {
      * @returns Object mapping field values to their document counts
      */
     countBy(field: string): Promise<CountByResult>;
+    /**
+     * Group matching documents by a specific field value
+     * @param field - Field path to group by
+     * @returns Object mapping field values to arrays of matching documents { id, data }
+     */
+    groupBy(field: string): Promise<GroupByResult>;
     /**
      * Import documents from a JSON file into Firestore
      * @param filePath - Path to the JSON file to import
@@ -897,4 +931,4 @@ declare function isValidUpdateData(value: any): value is Record<string, any>;
  */
 declare function formatError(error: unknown, context?: string): string;
 
-export { type AggregateResult, type AggregateSpec, BatchUpdater, type BulkCreateInput, type BulkCreateOptions, type BulkCreateResult, type BulkDeleteOptions, type BulkDeleteResult, type BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CopyToOptions, type CopyToResult, type CountByResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type FromJSONOptions, type FromJSONResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type ToJSONOptions, type ToJSONResult, type TransformFn, type TransformOptions, type TransformResult, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };
+export { type AggregateResult, type AggregateSpec, BatchUpdater, type BulkCreateInput, type BulkCreateOptions, type BulkCreateResult, type BulkDeleteOptions, type BulkDeleteResult, type BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CopyToOptions, type CopyToResult, type CountByResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldStatsResult, type FieldValueResult, type FromJSONOptions, type FromJSONResult, type GroupByResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type ToJSONOptions, type ToJSONResult, type TransformFn, type TransformOptions, type TransformResult, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };

package/dist/index.js

@@ -547,6 +547,34 @@ var BatchUpdater = class {
     const value = this.getNestedValue(snapshot.docs[0].data(), field);
     return value ?? null;
   }
+  /**
+   * Get combined statistics (sum, avg, min, max, count) for a single field
+   * Convenience method that runs aggregate + min + max in parallel
+   * @param field - Field path to compute statistics for
+   * @returns Object with sum, avg, min, max, count
+   */
+  async fieldStats(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field is required for fieldStats operation");
+    }
+    const [aggResult, minVal, maxVal] = await Promise.all([
+      this.aggregate({
+        _sum: { op: "sum", field },
+        _avg: { op: "average", field },
+        _count: { op: "count" }
+      }),
+      this.min(field),
+      this.max(field)
+    ]);
+    return {
+      sum: aggResult._sum,
+      avg: aggResult._avg,
+      min: minVal,
+      max: maxVal,
+      count: aggResult._count ?? 0
+    };
+  }
   /**
    * Get documents with cursor-based pagination
    * @param options - Pagination options (pageSize, startAfter cursor)
@@ -1422,6 +1450,31 @@ var BatchUpdater = class {
     }
     return counts;
   }
+  /**
+   * Group matching documents by a specific field value
+   * @param field - Field path to group by
+   * @returns Object mapping field values to arrays of matching documents { id, data }
+   */
+  async groupBy(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field path is required");
+    }
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    const groups = {};
+    for (const doc of snapshot.docs) {
+      const data = doc.data();
+      const value = this.getNestedValue(data, field);
+      if (value === void 0 || value === null) continue;
+      const key = String(value);
+      if (!groups[key]) {
+        groups[key] = [];
+      }
+      groups[key].push({ id: doc.id, data });
+    }
+    return groups;
+  }
   /**
    * Import documents from a JSON file into Firestore
    * @param filePath - Path to the JSON file to import

package/dist/index.mjs

@@ -502,6 +502,34 @@ var BatchUpdater = class {
     const value = this.getNestedValue(snapshot.docs[0].data(), field);
     return value ?? null;
   }
+  /**
+   * Get combined statistics (sum, avg, min, max, count) for a single field
+   * Convenience method that runs aggregate + min + max in parallel
+   * @param field - Field path to compute statistics for
+   * @returns Object with sum, avg, min, max, count
+   */
+  async fieldStats(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field is required for fieldStats operation");
+    }
+    const [aggResult, minVal, maxVal] = await Promise.all([
+      this.aggregate({
+        _sum: { op: "sum", field },
+        _avg: { op: "average", field },
+        _count: { op: "count" }
+      }),
+      this.min(field),
+      this.max(field)
+    ]);
+    return {
+      sum: aggResult._sum,
+      avg: aggResult._avg,
+      min: minVal,
+      max: maxVal,
+      count: aggResult._count ?? 0
+    };
+  }
   /**
    * Get documents with cursor-based pagination
    * @param options - Pagination options (pageSize, startAfter cursor)
@@ -1377,6 +1405,31 @@ var BatchUpdater = class {
     }
     return counts;
   }
+  /**
+   * Group matching documents by a specific field value
+   * @param field - Field path to group by
+   * @returns Object mapping field values to arrays of matching documents { id, data }
+   */
+  async groupBy(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field path is required");
+    }
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    const groups = {};
+    for (const doc of snapshot.docs) {
+      const data = doc.data();
+      const value = this.getNestedValue(data, field);
+      if (value === void 0 || value === null) continue;
+      const key = String(value);
+      if (!groups[key]) {
+        groups[key] = [];
+      }
+      groups[key].push({ id: doc.id, data });
+    }
+    return groups;
+  }
   /**
    * Import documents from a JSON file into Firestore
    * @param filePath - Path to the JSON file to import

package/package.json

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