firestore-batch-updater 1.17.0 → 1.19.0

package/README.ko.md

@@ -24,12 +24,14 @@
 - 통합 통계 - `fieldStats()`로 sum/avg/min/max/count 한 번에 조회
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
+- 문서 ID 존재 확인 - `has(id)`로 데이터 읽기 없이 특정 문서 ID 존재 여부 확인
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
 - 문서 변환 - `transform()`으로 각 문서에 커스텀 로직 적용 (가격 인상, 데이터 마이그레이션 등)
 - 복사 & 이동 - `copyTo()`로 컬렉션 간 문서 복사/이동 (데이터 변환 옵션 포함)
 - 고유값 조회 - `distinct()`로 특정 필드의 중복 없는 값 목록 조회
 - JSON 내보내기/가져오기 - `toJSON()` / `fromJSON()`으로 문서 JSON 파일 내보내기/가져오기
 - 그룹별 개수 조회 - `countBy()`로 특정 필드 값별 문서 수 집계
+- 그룹별 문서 조회 - `groupBy()`로 필드 값별로 문서 그룹핑
 - 랜덤 샘플링 - `sample()`로 쿼리 결과에서 랜덤 문서 추출
 - 필드 값 추출 - `pluck()`로 특정 필드 값만 간단하게 배열로 추출
 - 문서 ID 추출 - `pluckIds()`로 매칭 문서의 ID만 배열로 추출
@@ -108,6 +110,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `isEmpty()` | 매칭되는 문서가 없는지 확인 | `boolean` |
 | `findOne()` | 첫 번째 매칭 문서 조회 | `{ id, data } \| null` |
 | `getOne(id)` | ID로 문서 직접 조회 | `{ id, data } \| null` |
+| `has(id)` | 문서 ID 존재 여부 확인 | `boolean` |
 | `getAll()` | 모든 매칭 문서 조회 | `{ id, data }[]` |
 | `preview(data)` | 업데이트 전 미리보기 | `PreviewResult` |
 | `update(data, options?)` | 매칭되는 문서 업데이트 | `UpdateResult` |
@@ -136,6 +139,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 +198,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` |
 
 ## 사용 예시
@@ -643,6 +648,24 @@ const order = await updater
   .getOne("order-456");
 ```
 
+### 문서 ID 존재 확인
+
+```typescript
+// 특정 문서 ID가 존재하는지 확인 (데이터 읽기 없이 효율적)
+const exists = await updater.collection("users").has("user-123");
+
+if (exists) {
+  console.log("사용자가 존재합니다!");
+} else {
+  console.log("사용자를 찾을 수 없음");
+}
+
+// 가드 절에 유용
+if (!(await updater.collection("users").has(userId))) {
+  throw new Error("사용자를 찾을 수 없습니다");
+}
+```
+
 ### 벌크 업데이트
 
 ```typescript
@@ -812,6 +835,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

@@ -24,12 +24,14 @@ English | [한국어](./README.ko.md)
 - 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
+- Document ID check - Use `has(id)` to check if a specific document ID exists without reading data
 - Bulk operations - Use `bulkCreate()`, `bulkUpdate()`, `bulkDelete()` for efficient multi-document operations with different data each
 - Transform - Use `transform()` to apply custom logic to each document (e.g., price increase, data migration)
 - Copy & Move - Use `copyTo()` to copy/move documents between collections with optional data transformation
 - 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
@@ -108,6 +110,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `isEmpty()` | Check if no matching documents exist | `boolean` |
 | `findOne()` | Find first matching document | `{ id, data } \| null` |
 | `getOne(id)` | Get document by ID directly | `{ id, data } \| null` |
+| `has(id)` | Check if document ID exists | `boolean` |
 | `getAll()` | Get all matching documents | `{ id, data }[]` |
 | `preview(data)` | Preview changes before update | `PreviewResult` |
 | `update(data, options?)` | Update matching documents | `UpdateResult` |
@@ -136,6 +139,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 +198,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
@@ -662,6 +667,24 @@ const profile = await updater
   .getOne("user-123");
 ```
 
+### Check Document Exists by ID
+
+```typescript
+// Check if a specific document ID exists (without reading data)
+const exists = await updater.collection("users").has("user-123");
+
+if (exists) {
+  console.log("User exists!");
+} else {
+  console.log("User not found");
+}
+
+// Useful for guard clauses before operations
+if (!(await updater.collection("users").has(userId))) {
+  throw new Error("User not found");
+}
+```
+
 ### Bulk Update with Different Data
 
 ```typescript
@@ -825,6 +848,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
  */
@@ -619,6 +629,12 @@ declare class BatchUpdater {
         id: string;
         data: Record<string, any>;
     } | null>;
+    /**
+     * Check if a document with the given ID exists in the collection
+     * @param id - Document ID to check
+     * @returns true if the document exists, false otherwise
+     */
+    has(id: string): Promise<boolean>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update
@@ -811,6 +827,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 +937,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
  */
@@ -619,6 +629,12 @@ declare class BatchUpdater {
         id: string;
         data: Record<string, any>;
     } | null>;
+    /**
+     * Check if a document with the given ID exists in the collection
+     * @param id - Document ID to check
+     * @returns true if the document exists, false otherwise
+     */
+    has(id: string): Promise<boolean>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update
@@ -811,6 +827,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 +937,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

@@ -373,6 +373,25 @@ var BatchUpdater = class {
       data: docSnapshot.data()
     };
   }
+  /**
+   * Check if a document with the given ID exists in the collection
+   * @param id - Document ID to check
+   * @returns true if the document exists, false otherwise
+   */
+  async has(id) {
+    this.validateSetup();
+    if (!id || typeof id !== "string") {
+      throw new Error("Document ID is required");
+    }
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "has() cannot be used with collectionGroup(). Use exists() with where conditions instead."
+      );
+    }
+    const docRef = this.firestore.collection(this.collectionPath).doc(id);
+    const docSnapshot = await docRef.get();
+    return docSnapshot.exists;
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update
@@ -1450,6 +1469,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

@@ -328,6 +328,25 @@ var BatchUpdater = class {
       data: docSnapshot.data()
     };
   }
+  /**
+   * Check if a document with the given ID exists in the collection
+   * @param id - Document ID to check
+   * @returns true if the document exists, false otherwise
+   */
+  async has(id) {
+    this.validateSetup();
+    if (!id || typeof id !== "string") {
+      throw new Error("Document ID is required");
+    }
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "has() cannot be used with collectionGroup(). Use exists() with where conditions instead."
+      );
+    }
+    const docRef = this.firestore.collection(this.collectionPath).doc(id);
+    const docSnapshot = await docRef.get();
+    return docSnapshot.exists;
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update
@@ -1405,6 +1424,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.19.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",