firestore-batch-updater 1.17.0 → 1.18.0

package/README.ko.md

@@ -30,6 +30,7 @@
 - 고유값 조회 - `distinct()`로 특정 필드의 중복 없는 값 목록 조회
 - JSON 내보내기/가져오기 - `toJSON()` / `fromJSON()`으로 문서 JSON 파일 내보내기/가져오기
 - 그룹별 개수 조회 - `countBy()`로 특정 필드 값별 문서 수 집계
+- 그룹별 문서 조회 - `groupBy()`로 필드 값별로 문서 그룹핑
 - 랜덤 샘플링 - `sample()`로 쿼리 결과에서 랜덤 문서 추출
 - 필드 값 추출 - `pluck()`로 특정 필드 값만 간단하게 배열로 추출
 - 문서 ID 추출 - `pluckIds()`로 매칭 문서의 ID만 배열로 추출
@@ -136,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[]` |
 
 ### 옵션
@@ -194,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` |
 
 ## 사용 예시
@@ -812,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

@@ -30,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
@@ -136,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
@@ -194,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
@@ -825,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

@@ -472,6 +472,16 @@ interface FieldStatsResult {
 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
  */
@@ -811,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
@@ -915,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 FieldStatsResult, 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

@@ -472,6 +472,16 @@ interface FieldStatsResult {
 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
  */
@@ -811,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
@@ -915,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 FieldStatsResult, 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

@@ -1450,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

@@ -1405,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.17.0",
+  "version": "1.18.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",