firestore-batch-updater 1.1.0 → 1.3.0

package/README.ko.md

@@ -14,7 +14,12 @@
 - 진행 상황 추적 - 실시간 진행률 콜백
 - 일괄 생성/Upsert/삭제 - 여러 문서를 한 번에 생성, upsert 또는 삭제
 - 정렬 및 제한 - `orderBy()`와 `limit()`으로 정밀한 제어
-- FieldValue 지원 - `increment()`, `arrayUnion()`, `serverTimestamp()` 등 사용 가능
+- 필드 선택 - `select()`로 필요한 필드만 로드 (메모리 및 비용 절약)
+- 단일 문서 조회 - `findOne()`으로 효율적인 단일 문서 검색
+- FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
+- 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
+- Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
+- 문서 개수 조회 - 문서를 로드하지 않고 빠르게 개수 확인
 - 로그 파일 생성 - 감사를 위한 상세 작업 로그 (선택사항)
 
 ## 설치
@@ -75,10 +80,14 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 
 | 메서드 | 설명 | 반환값 |
 |--------|------|--------|
-| `collection(path)` | 작업할 컬렉션 선택 | `this` |
+| `collection(path)` | 작업할 컬렉션 선택 (서브컬렉션 경로 지원) | `this` |
+| `collectionGroup(id)` | 동일 ID의 모든 컬렉션 쿼리 | `this` |
 | `where(field, op, value)` | 필터 조건 추가 (체이닝 가능) | `this` |
 | `orderBy(field, direction?)` | 정렬 추가 (체이닝 가능) | `this` |
 | `limit(count)` | 문서 수 제한 (체이닝 가능) | `this` |
+| `select(...fields)` | 특정 필드만 조회 (체이닝 가능) | `this` |
+| `count()` | 매칭되는 문서 개수 조회 | `CountResult` |
+| `findOne()` | 첫 번째 매칭 문서 조회 | `{ id, data } \| null` |
 | `preview(data)` | 업데이트 전 미리보기 | `PreviewResult` |
 | `update(data, options?)` | 매칭되는 문서 업데이트 | `UpdateResult` |
 | `create(docs, options?)` | 새 문서 생성 | `CreateResult` |
@@ -95,6 +104,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
   onProgress?: (progress: ProgressInfo) => void;
   log?: LogOptions;
   batchSize?: number;  // update/upsert/delete 전용
+  dryRun?: boolean;    // update/upsert/delete 전용 - 실제 쓰기 없이 시뮬레이션
 }
 
 // ProgressInfo
@@ -116,10 +126,15 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 - 미설정: 모든 문서를 메모리에 한 번에 로드 (소규모 컬렉션에 적합)
 - 설정 시 (예: `batchSize: 1000`): 커서 페이지네이션을 사용하여 배치 단위로 처리 (대규모 컬렉션의 메모리 문제 방지)
 
+**dryRun 옵션:**
+- `true` 설정 시: 실제 변경 없이 `DryRunResult` 반환 (`wouldAffect` 개수와 `sampleIds` 포함)
+
 ### 반환 타입
 
 | 타입 | 필드 |
 |------|------|
+| `CountResult` | `count` |
+| `DryRunResult` | `wouldAffect`, `sampleIds[]`, `operation` |
 | `PreviewResult` | `affectedCount`, `samples[]`, `affectedFields[]` |
 | `UpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `CreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
@@ -285,6 +300,124 @@ await updater
   .collection("users")
   .where("status", "==", "active")
   .update({ updatedAt: FieldValue.serverTimestamp() });
+
+// 필드 삭제
+await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .update({ temporaryData: FieldValue.delete() });
+```
+
+### 문서 개수 조회
+
+```typescript
+// 문서를 로드하지 않고 빠르게 개수 조회
+const result = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .count();
+
+console.log(`${result.count}명의 비활성 사용자 발견`);
+```
+
+### 특정 필드만 조회
+
+```typescript
+// name, email 필드만 로드 (메모리 및 읽기 비용 절약)
+const result = await updater
+  .collection("users")
+  .select("name", "email")
+  .where("status", "==", "active")
+  .findOne();
+
+console.log(result?.data); // { name, email }만 포함
+
+// 모든 작업에서 사용 가능 - 문서에 선택된 필드만 포함됨
+const emails = await updater
+  .collection("users")
+  .select("email")
+  .where("verified", "==", true)
+  .getFields("email");
+```
+
+### 단일 문서 조회
+
+```typescript
+// 첫 번째 매칭 문서 찾기
+const user = await updater
+  .collection("users")
+  .where("email", "==", "user@example.com")
+  .findOne();
+
+if (user) {
+  console.log("사용자 발견:", user.id);
+  console.log("사용자 데이터:", user.data);
+} else {
+  console.log("사용자를 찾을 수 없음");
+}
+
+// select와 함께 사용하여 효율적인 조회
+const profile = await updater
+  .collection("users")
+  .select("name", "avatar", "tier")
+  .where("username", "==", "johndoe")
+  .findOne();
+```
+
+### Dry Run 모드
+
+```typescript
+// 실제 변경 없이 작업 시뮬레이션
+const simulation = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .update(
+    { status: "archived" },
+    { dryRun: true }
+  );
+
+console.log(`${simulation.wouldAffect}개 문서가 영향을 받을 예정`);
+console.log("샘플 ID:", simulation.sampleIds);
+
+// 삭제에도 사용 가능
+const deleteSimulation = await updater
+  .collection("logs")
+  .where("createdAt", "<", thirtyDaysAgo)
+  .delete({ dryRun: true });
+
+console.log(`${deleteSimulation.wouldAffect}개 문서가 삭제될 예정`);
+```
+
+### 서브컬렉션
+
+```typescript
+// 특정 서브컬렉션 경로 쿼리
+const result = await updater
+  .collection("users/user-123/orders")
+  .where("status", "==", "pending")
+  .update({ status: "cancelled" });
+
+// 동적 경로 사용
+const userId = "user-123";
+await updater
+  .collection(`users/${userId}/notifications`)
+  .where("read", "==", false)
+  .delete();
+```
+
+### 컬렉션 그룹 쿼리
+
+```typescript
+// 모든 사용자의 "orders" 서브컬렉션을 한 번에 쿼리
+const result = await updater
+  .collectionGroup("orders")
+  .where("status", "==", "pending")
+  .where("createdAt", "<", thirtyDaysAgo)
+  .update({ status: "expired" });
+
+console.log(`${result.successCount}개 주문 업데이트 완료`);
+
+// 참고: collectionGroup은 쿼리 필드에 대한 Firestore 인덱스가 필요합니다
 ```
 
 > **참고:** 서로 다른 필드에 여러 `where()` 조건을 사용하거나, `where()`와 `orderBy()`를 다른 필드에 사용할 경우, Firestore에서 [복합 인덱스](https://firebase.google.com/docs/firestore/query-data/indexing)가 필요할 수 있습니다. `FAILED_PRECONDITION` 오류가 발생하면 오류 메시지의 링크를 통해 필요한 인덱스를 생성하세요.

package/README.md

@@ -14,7 +14,12 @@ English | [한국어](./README.ko.md)
 - Progress tracking - Real-time progress callbacks
 - Batch create/upsert/delete - Create, upsert, or delete multiple documents at once
 - Sorting and limiting - Use `orderBy()` and `limit()` for precise control
-- FieldValue support - Use `increment()`, `arrayUnion()`, `serverTimestamp()`, etc.
+- Field selection - Use `select()` to load only needed fields (saves memory and costs)
+- Find single document - Use `findOne()` for efficient single-document retrieval
+- 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
+- Count documents - Quickly count matching documents without loading them
 - Log file generation - Optional detailed operation logs for auditing
 
 ## Installation
@@ -75,10 +80,14 @@ console.log(`Updated ${result.successCount} documents`);
 
 | Method | Description | Returns |
 |--------|-------------|---------|
-| `collection(path)` | Select collection to operate on | `this` |
+| `collection(path)` | Select collection to operate on (supports subcollection paths) | `this` |
+| `collectionGroup(id)` | Query all collections with the same ID | `this` |
 | `where(field, op, value)` | Add filter condition (chainable) | `this` |
 | `orderBy(field, direction?)` | Add sorting (chainable) | `this` |
 | `limit(count)` | Limit number of documents (chainable) | `this` |
+| `select(...fields)` | Select specific fields to retrieve (chainable) | `this` |
+| `count()` | Count matching documents | `CountResult` |
+| `findOne()` | Find first matching document | `{ id, data } \| null` |
 | `preview(data)` | Preview changes before update | `PreviewResult` |
 | `update(data, options?)` | Update matching documents | `UpdateResult` |
 | `create(docs, options?)` | Create new documents | `CreateResult` |
@@ -95,6 +104,7 @@ All write operations support an optional `options` parameter:
   onProgress?: (progress: ProgressInfo) => void;
   log?: LogOptions;
   batchSize?: number;  // For update/upsert/delete
+  dryRun?: boolean;    // For update/upsert/delete - simulate without writing
 }
 
 // ProgressInfo
@@ -116,10 +126,15 @@ All write operations support an optional `options` parameter:
 - When not set: All documents are loaded into memory at once (suitable for small collections)
 - When set (e.g., `batchSize: 1000`): Documents are processed in batches using cursor pagination (suitable for large collections to prevent memory issues)
 
+**dryRun option:**
+- When `true`: Returns `DryRunResult` with `wouldAffect` count and `sampleIds` without making any changes
+
 ### Return Types
 
 | Type | Fields |
 |------|--------|
+| `CountResult` | `count` |
+| `DryRunResult` | `wouldAffect`, `sampleIds[]`, `operation` |
 | `PreviewResult` | `affectedCount`, `samples[]`, `affectedFields[]` |
 | `UpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `CreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
@@ -284,6 +299,124 @@ await updater
   .collection("users")
   .where("status", "==", "active")
   .update({ lastSeen: FieldValue.serverTimestamp() });
+
+// Delete a field
+await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .update({ temporaryData: FieldValue.delete() });
+```
+
+### Count Documents
+
+```typescript
+// Quickly count matching documents without loading them
+const result = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .count();
+
+console.log(`Found ${result.count} inactive users`);
+```
+
+### Select Specific Fields
+
+```typescript
+// Only load name and email fields (reduces memory and read costs)
+const result = await updater
+  .collection("users")
+  .select("name", "email")
+  .where("status", "==", "active")
+  .findOne();
+
+console.log(result?.data); // Only contains { name, email }
+
+// Works with all operations - documents will only have selected fields
+const emails = await updater
+  .collection("users")
+  .select("email")
+  .where("verified", "==", true)
+  .getFields("email");
+```
+
+### Find Single Document
+
+```typescript
+// Find first matching document
+const user = await updater
+  .collection("users")
+  .where("email", "==", "user@example.com")
+  .findOne();
+
+if (user) {
+  console.log("Found user:", user.id);
+  console.log("User data:", user.data);
+} else {
+  console.log("User not found");
+}
+
+// Combine with select for efficient lookup
+const profile = await updater
+  .collection("users")
+  .select("name", "avatar", "tier")
+  .where("username", "==", "johndoe")
+  .findOne();
+```
+
+### Dry Run Mode
+
+```typescript
+// Simulate an operation without making any changes
+const simulation = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .update(
+    { status: "archived" },
+    { dryRun: true }
+  );
+
+console.log(`Would affect ${simulation.wouldAffect} documents`);
+console.log("Sample IDs:", simulation.sampleIds);
+
+// Also works with delete
+const deleteSimulation = await updater
+  .collection("logs")
+  .where("createdAt", "<", thirtyDaysAgo)
+  .delete({ dryRun: true });
+
+console.log(`Would delete ${deleteSimulation.wouldAffect} documents`);
+```
+
+### Subcollections
+
+```typescript
+// Query a specific subcollection path
+const result = await updater
+  .collection("users/user-123/orders")
+  .where("status", "==", "pending")
+  .update({ status: "cancelled" });
+
+// Or use dynamic paths
+const userId = "user-123";
+await updater
+  .collection(`users/${userId}/notifications`)
+  .where("read", "==", false)
+  .delete();
+```
+
+### Collection Group Queries
+
+```typescript
+// Query ALL "orders" subcollections across all users
+const result = await updater
+  .collectionGroup("orders")
+  .where("status", "==", "pending")
+  .where("createdAt", "<", thirtyDaysAgo)
+  .update({ status: "expired" });
+
+console.log(`Updated ${result.successCount} orders across all users`);
+
+// Note: collectionGroup requires a Firestore index on the queried fields
 ```
 
 ### Error Handling

package/dist/index.d.mts

@@ -12,6 +12,9 @@ interface ProgressInfo {
     current: number;
     total: number;
     percentage: number;
+    elapsedTime: number;
+    docsPerSecond: number;
+    eta: number;
 }
 /**
  * Options for update operations
@@ -32,6 +35,19 @@ interface UpdateOptions {
      * When not set, all documents are loaded at once
      */
     batchSize?: number;
+    /**
+     * Dry run mode - simulate the operation without actually writing
+     * Returns what would happen without making any changes
+     */
+    dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch update operation
@@ -130,6 +146,19 @@ interface UpsertOptions {
      * When not set, all documents are loaded at once
      */
     batchSize?: number;
+    /**
+     * Dry run mode - simulate the operation without actually writing
+     * Returns what would happen without making any changes
+     */
+    dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch upsert operation
@@ -159,6 +188,19 @@ interface DeleteOptions {
      * When not set, all documents are loaded at once
      */
     batchSize?: number;
+    /**
+     * Dry run mode - simulate the operation without actually writing
+     * Returns what would happen without making any changes
+     */
+    dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch delete operation
@@ -170,6 +212,20 @@ interface DeleteResult {
     deletedIds: string[];
     failedDocIds?: string[];
 }
+/**
+ * Result of count operation
+ */
+interface CountResult {
+    count: number;
+}
+/**
+ * Result of dry run operation
+ */
+interface DryRunResult {
+    wouldAffect: number;
+    sampleIds: string[];
+    operation: "update" | "upsert" | "delete";
+}
 /**
  * Log options for batch operations
  */
@@ -215,9 +271,11 @@ interface OperationLog {
 declare class BatchUpdater {
     private firestore;
     private collectionPath?;
+    private isCollectionGroup;
     private conditions;
     private orderByConditions;
     private limitCount?;
+    private selectedFields?;
     /**
      * Create a new BatchUpdater instance
      * @param firestore - Initialized Firestore instance from firebase-admin
@@ -225,10 +283,17 @@ declare class BatchUpdater {
     constructor(firestore: Firestore);
     /**
      * Select a collection to operate on
+     * Supports subcollection paths like "users/userId/orders"
      * @param path - Collection path
      * @returns This instance for chaining
      */
     collection(path: string): this;
+    /**
+     * Select a collection group to operate on (queries across all subcollections with the same name)
+     * @param collectionId - Collection ID (not a path, just the collection name)
+     * @returns This instance for chaining
+     */
+    collectionGroup(collectionId: string): this;
     /**
      * Add a where condition to filter documents
      * @param field - Field path
@@ -250,6 +315,25 @@ declare class BatchUpdater {
      * @returns This instance for chaining
      */
     limit(count: number): this;
+    /**
+     * Select specific fields to retrieve (reduces memory usage and read costs)
+     * @param fields - Field paths to retrieve
+     * @returns This instance for chaining
+     */
+    select(...fields: string[]): this;
+    /**
+     * Count documents matching the query conditions
+     * @returns Count result with number of matching documents
+     */
+    count(): Promise<CountResult>;
+    /**
+     * Find the first document matching the query conditions
+     * @returns First matching document with id and data, or null if not found
+     */
+    findOne(): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Preview changes before executing update
      * @param updateData - Data to update
@@ -259,12 +343,12 @@ declare class BatchUpdater {
     /**
      * Execute batch update operation
      * @param updateData - Data to update
-     * @param options - Update options (e.g., progress callback, log options, batchSize for pagination)
-     * @returns Update result with success/failure counts and optional log file path
+     * @param options - Update options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+     * @returns Update result with success/failure counts and optional log file path, or DryRunResult if dryRun is true
      */
-    update(updateData: Record<string, any>, options?: UpdateOptions): Promise<UpdateResult & {
+    update(updateData: Record<string, any>, options?: UpdateOptions): Promise<(UpdateResult & {
         logFilePath?: string;
-    }>;
+    }) | DryRunResult>;
     /**
      * Get specific field values from matching documents
      * @param fieldPath - Field path to retrieve
@@ -273,6 +357,7 @@ declare class BatchUpdater {
     getFields(fieldPath: string): Promise<FieldValueResult[]>;
     /**
      * Create multiple documents in batch
+     * Note: This method does not work with collectionGroup()
      * @param documents - Array of documents to create
      * @param options - Create options (e.g., progress callback, log options)
      * @returns Create result with success/failure counts, created IDs, and optional log file path
@@ -284,20 +369,20 @@ declare class BatchUpdater {
      * Upsert documents matching query conditions
      * Updates existing documents or creates them if they don't exist
      * @param updateData - Data to set/merge
-     * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination)
-     * @returns Upsert result with success/failure counts and optional log file path
+     * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+     * @returns Upsert result with success/failure counts and optional log file path, or DryRunResult if dryRun is true
      */
-    upsert(updateData: Record<string, any>, options?: UpsertOptions): Promise<UpsertResult & {
+    upsert(updateData: Record<string, any>, options?: UpsertOptions): Promise<(UpsertResult & {
         logFilePath?: string;
-    }>;
+    }) | DryRunResult>;
     /**
      * Delete documents matching query conditions
-     * @param options - Delete options (e.g., progress callback, log options, batchSize for pagination)
-     * @returns Delete result with success/failure counts, deleted IDs, and optional log file path
+     * @param options - Delete options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+     * @returns Delete result with success/failure counts, deleted IDs, and optional log file path, or DryRunResult if dryRun is true
      */
-    delete(options?: DeleteOptions): Promise<DeleteResult & {
+    delete(options?: DeleteOptions): Promise<(DeleteResult & {
         logFilePath?: string;
-    }>;
+    }) | DryRunResult>;
     /**
      * Validate that collection is set
      * @private
@@ -341,12 +426,13 @@ declare function createLogCollector(operation: "update" | "create" | "upsert" |
  */
 
 /**
- * Calculate progress information
+ * Calculate progress information with timing details
  * @param current - Number of documents processed so far
  * @param total - Total number of documents to process
- * @returns Progress information with percentage
+ * @param startTime - Start time of the operation (from Date.now())
+ * @returns Progress information with percentage, timing, and ETA
  */
-declare function calculateProgress(current: number, total: number): ProgressInfo;
+declare function calculateProgress(current: number, total: number, startTime?: number): ProgressInfo;
 /**
  * Extract field names from update data
  * @param updateData - Data to be updated
@@ -374,4 +460,4 @@ declare function isValidUpdateData(value: any): value is Record<string, any>;
  */
 declare function formatError(error: unknown, context?: string): string;
 
-export { BatchUpdater, type CreateDocumentInput, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PreviewResult, type ProgressInfo, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };
+export { BatchUpdater, type CountResult, type CreateDocumentInput, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PreviewResult, type ProgressInfo, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };

package/dist/index.d.ts

@@ -12,6 +12,9 @@ interface ProgressInfo {
     current: number;
     total: number;
     percentage: number;
+    elapsedTime: number;
+    docsPerSecond: number;
+    eta: number;
 }
 /**
  * Options for update operations
@@ -32,6 +35,19 @@ interface UpdateOptions {
      * When not set, all documents are loaded at once
      */
     batchSize?: number;
+    /**
+     * Dry run mode - simulate the operation without actually writing
+     * Returns what would happen without making any changes
+     */
+    dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch update operation
@@ -130,6 +146,19 @@ interface UpsertOptions {
      * When not set, all documents are loaded at once
      */
     batchSize?: number;
+    /**
+     * Dry run mode - simulate the operation without actually writing
+     * Returns what would happen without making any changes
+     */
+    dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch upsert operation
@@ -159,6 +188,19 @@ interface DeleteOptions {
      * When not set, all documents are loaded at once
      */
     batchSize?: number;
+    /**
+     * Dry run mode - simulate the operation without actually writing
+     * Returns what would happen without making any changes
+     */
+    dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch delete operation
@@ -170,6 +212,20 @@ interface DeleteResult {
     deletedIds: string[];
     failedDocIds?: string[];
 }
+/**
+ * Result of count operation
+ */
+interface CountResult {
+    count: number;
+}
+/**
+ * Result of dry run operation
+ */
+interface DryRunResult {
+    wouldAffect: number;
+    sampleIds: string[];
+    operation: "update" | "upsert" | "delete";
+}
 /**
  * Log options for batch operations
  */
@@ -215,9 +271,11 @@ interface OperationLog {
 declare class BatchUpdater {
     private firestore;
     private collectionPath?;
+    private isCollectionGroup;
     private conditions;
     private orderByConditions;
     private limitCount?;
+    private selectedFields?;
     /**
      * Create a new BatchUpdater instance
      * @param firestore - Initialized Firestore instance from firebase-admin
@@ -225,10 +283,17 @@ declare class BatchUpdater {
     constructor(firestore: Firestore);
     /**
      * Select a collection to operate on
+     * Supports subcollection paths like "users/userId/orders"
      * @param path - Collection path
      * @returns This instance for chaining
      */
     collection(path: string): this;
+    /**
+     * Select a collection group to operate on (queries across all subcollections with the same name)
+     * @param collectionId - Collection ID (not a path, just the collection name)
+     * @returns This instance for chaining
+     */
+    collectionGroup(collectionId: string): this;
     /**
      * Add a where condition to filter documents
      * @param field - Field path
@@ -250,6 +315,25 @@ declare class BatchUpdater {
      * @returns This instance for chaining
      */
     limit(count: number): this;
+    /**
+     * Select specific fields to retrieve (reduces memory usage and read costs)
+     * @param fields - Field paths to retrieve
+     * @returns This instance for chaining
+     */
+    select(...fields: string[]): this;
+    /**
+     * Count documents matching the query conditions
+     * @returns Count result with number of matching documents
+     */
+    count(): Promise<CountResult>;
+    /**
+     * Find the first document matching the query conditions
+     * @returns First matching document with id and data, or null if not found
+     */
+    findOne(): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Preview changes before executing update
      * @param updateData - Data to update
@@ -259,12 +343,12 @@ declare class BatchUpdater {
     /**
      * Execute batch update operation
      * @param updateData - Data to update
-     * @param options - Update options (e.g., progress callback, log options, batchSize for pagination)
-     * @returns Update result with success/failure counts and optional log file path
+     * @param options - Update options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+     * @returns Update result with success/failure counts and optional log file path, or DryRunResult if dryRun is true
      */
-    update(updateData: Record<string, any>, options?: UpdateOptions): Promise<UpdateResult & {
+    update(updateData: Record<string, any>, options?: UpdateOptions): Promise<(UpdateResult & {
         logFilePath?: string;
-    }>;
+    }) | DryRunResult>;
     /**
      * Get specific field values from matching documents
      * @param fieldPath - Field path to retrieve
@@ -273,6 +357,7 @@ declare class BatchUpdater {
     getFields(fieldPath: string): Promise<FieldValueResult[]>;
     /**
      * Create multiple documents in batch
+     * Note: This method does not work with collectionGroup()
      * @param documents - Array of documents to create
      * @param options - Create options (e.g., progress callback, log options)
      * @returns Create result with success/failure counts, created IDs, and optional log file path
@@ -284,20 +369,20 @@ declare class BatchUpdater {
      * Upsert documents matching query conditions
      * Updates existing documents or creates them if they don't exist
      * @param updateData - Data to set/merge
-     * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination)
-     * @returns Upsert result with success/failure counts and optional log file path
+     * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+     * @returns Upsert result with success/failure counts and optional log file path, or DryRunResult if dryRun is true
      */
-    upsert(updateData: Record<string, any>, options?: UpsertOptions): Promise<UpsertResult & {
+    upsert(updateData: Record<string, any>, options?: UpsertOptions): Promise<(UpsertResult & {
         logFilePath?: string;
-    }>;
+    }) | DryRunResult>;
     /**
      * Delete documents matching query conditions
-     * @param options - Delete options (e.g., progress callback, log options, batchSize for pagination)
-     * @returns Delete result with success/failure counts, deleted IDs, and optional log file path
+     * @param options - Delete options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+     * @returns Delete result with success/failure counts, deleted IDs, and optional log file path, or DryRunResult if dryRun is true
      */
-    delete(options?: DeleteOptions): Promise<DeleteResult & {
+    delete(options?: DeleteOptions): Promise<(DeleteResult & {
         logFilePath?: string;
-    }>;
+    }) | DryRunResult>;
     /**
      * Validate that collection is set
      * @private
@@ -341,12 +426,13 @@ declare function createLogCollector(operation: "update" | "create" | "upsert" |
  */
 
 /**
- * Calculate progress information
+ * Calculate progress information with timing details
  * @param current - Number of documents processed so far
  * @param total - Total number of documents to process
- * @returns Progress information with percentage
+ * @param startTime - Start time of the operation (from Date.now())
+ * @returns Progress information with percentage, timing, and ETA
  */
-declare function calculateProgress(current: number, total: number): ProgressInfo;
+declare function calculateProgress(current: number, total: number, startTime?: number): ProgressInfo;
 /**
  * Extract field names from update data
  * @param updateData - Data to be updated
@@ -374,4 +460,4 @@ declare function isValidUpdateData(value: any): value is Record<string, any>;
  */
 declare function formatError(error: unknown, context?: string): string;
 
-export { BatchUpdater, type CreateDocumentInput, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PreviewResult, type ProgressInfo, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };
+export { BatchUpdater, type CountResult, type CreateDocumentInput, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PreviewResult, type ProgressInfo, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };

package/dist/index.js

@@ -164,12 +164,20 @@ function createLogCollector(operation, collection, conditions, updateData) {
 }
 
 // src/utils/index.ts
-function calculateProgress(current, total) {
+function calculateProgress(current, total, startTime) {
   const percentage = total === 0 ? 0 : Math.round(current / total * 100);
+  const now = Date.now();
+  const elapsedTime = startTime ? now - startTime : 0;
+  const docsPerSecond = elapsedTime > 0 ? Math.round(current / elapsedTime * 1e3 * 100) / 100 : 0;
+  const remaining = total - current;
+  const eta = docsPerSecond > 0 ? Math.round(remaining / docsPerSecond * 100) / 100 : 0;
   return {
     current,
     total,
-    percentage
+    percentage,
+    elapsedTime,
+    docsPerSecond,
+    eta
   };
 }
 function getAffectedFields(updateData) {
@@ -196,20 +204,38 @@ var BatchUpdater = class {
    * @param firestore - Initialized Firestore instance from firebase-admin
    */
   constructor(firestore) {
+    this.isCollectionGroup = false;
     this.conditions = [];
     this.orderByConditions = [];
     this.firestore = firestore;
   }
   /**
    * Select a collection to operate on
+   * Supports subcollection paths like "users/userId/orders"
    * @param path - Collection path
    * @returns This instance for chaining
    */
   collection(path2) {
     this.collectionPath = path2;
+    this.isCollectionGroup = false;
     this.conditions = [];
     this.orderByConditions = [];
     this.limitCount = void 0;
+    this.selectedFields = void 0;
+    return this;
+  }
+  /**
+   * Select a collection group to operate on (queries across all subcollections with the same name)
+   * @param collectionId - Collection ID (not a path, just the collection name)
+   * @returns This instance for chaining
+   */
+  collectionGroup(collectionId) {
+    this.collectionPath = collectionId;
+    this.isCollectionGroup = true;
+    this.conditions = [];
+    this.orderByConditions = [];
+    this.limitCount = void 0;
+    this.selectedFields = void 0;
     return this;
   }
   /**
@@ -242,6 +268,44 @@ var BatchUpdater = class {
     this.limitCount = count;
     return this;
   }
+  /**
+   * Select specific fields to retrieve (reduces memory usage and read costs)
+   * @param fields - Field paths to retrieve
+   * @returns This instance for chaining
+   */
+  select(...fields) {
+    this.selectedFields = fields;
+    return this;
+  }
+  /**
+   * Count documents matching the query conditions
+   * @returns Count result with number of matching documents
+   */
+  async count() {
+    this.validateSetup();
+    const query = this.buildQuery();
+    const snapshot = await query.count().get();
+    return {
+      count: snapshot.data().count
+    };
+  }
+  /**
+   * Find the first document matching the query conditions
+   * @returns First matching document with id and data, or null if not found
+   */
+  async findOne() {
+    this.validateSetup();
+    const query = this.buildQuery().limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const doc = snapshot.docs[0];
+    return {
+      id: doc.id,
+      data: doc.data()
+    };
+  }
   /**
    * Preview changes before executing update
    * @param updateData - Data to update
@@ -276,14 +340,24 @@ var BatchUpdater = class {
   /**
    * Execute batch update operation
    * @param updateData - Data to update
-   * @param options - Update options (e.g., progress callback, log options, batchSize for pagination)
-   * @returns Update result with success/failure counts and optional log file path
+   * @param options - Update options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+   * @returns Update result with success/failure counts and optional log file path, or DryRunResult if dryRun is true
    */
   async update(updateData, options = {}) {
     this.validateSetup();
     if (!isValidUpdateData(updateData)) {
       throw new Error("Update data must be a non-empty object");
     }
+    if (options.dryRun) {
+      const query = this.buildQuery();
+      const snapshot = await query.limit(10).get();
+      const countSnapshot = await this.buildQuery().count().get();
+      return {
+        wouldAffect: countSnapshot.data().count,
+        sampleIds: snapshot.docs.map((doc) => doc.id),
+        operation: "update"
+      };
+    }
     const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath, this.conditions, updateData) : null;
     let successCount = 0;
     let failureCount = 0;
@@ -432,12 +506,16 @@ var BatchUpdater = class {
   }
   /**
    * Create multiple documents in batch
+   * Note: This method does not work with collectionGroup()
    * @param documents - Array of documents to create
    * @param options - Create options (e.g., progress callback, log options)
    * @returns Create result with success/failure counts, created IDs, and optional log file path
    */
   async create(documents, options = {}) {
     this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error("create() cannot be used with collectionGroup(). Use collection() with a specific path instead.");
+    }
     if (!Array.isArray(documents) || documents.length === 0) {
       throw new Error("Documents array must be non-empty");
     }
@@ -498,14 +576,24 @@ var BatchUpdater = class {
    * Upsert documents matching query conditions
    * Updates existing documents or creates them if they don't exist
    * @param updateData - Data to set/merge
-   * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination)
-   * @returns Upsert result with success/failure counts and optional log file path
+   * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+   * @returns Upsert result with success/failure counts and optional log file path, or DryRunResult if dryRun is true
    */
   async upsert(updateData, options = {}) {
     this.validateSetup();
     if (!isValidUpdateData(updateData)) {
       throw new Error("Update data must be a non-empty object");
     }
+    if (options.dryRun) {
+      const query = this.buildQuery();
+      const snapshot = await query.limit(10).get();
+      const countSnapshot = await this.buildQuery().count().get();
+      return {
+        wouldAffect: countSnapshot.data().count,
+        sampleIds: snapshot.docs.map((doc) => doc.id),
+        operation: "upsert"
+      };
+    }
     const logCollector = options.log?.enabled ? createLogCollector("upsert", this.collectionPath, this.conditions, updateData) : null;
     let successCount = 0;
     let failureCount = 0;
@@ -634,11 +722,21 @@ var BatchUpdater = class {
   }
   /**
    * Delete documents matching query conditions
-   * @param options - Delete options (e.g., progress callback, log options, batchSize for pagination)
-   * @returns Delete result with success/failure counts, deleted IDs, and optional log file path
+   * @param options - Delete options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+   * @returns Delete result with success/failure counts, deleted IDs, and optional log file path, or DryRunResult if dryRun is true
    */
   async delete(options = {}) {
     this.validateSetup();
+    if (options.dryRun) {
+      const query = this.buildQuery();
+      const snapshot = await query.limit(10).get();
+      const countSnapshot = await this.buildQuery().count().get();
+      return {
+        wouldAffect: countSnapshot.data().count,
+        sampleIds: snapshot.docs.map((doc) => doc.id),
+        operation: "delete"
+      };
+    }
     const logCollector = options.log?.enabled ? createLogCollector("delete", this.collectionPath, this.conditions) : null;
     let successCount = 0;
     let failureCount = 0;
@@ -785,9 +883,7 @@ var BatchUpdater = class {
    * @private
    */
   buildQuery() {
-    let query = this.firestore.collection(
-      this.collectionPath
-    );
+    let query = this.isCollectionGroup ? this.firestore.collectionGroup(this.collectionPath) : this.firestore.collection(this.collectionPath);
     for (const condition of this.conditions) {
       query = query.where(condition.field, condition.operator, condition.value);
     }
@@ -797,6 +893,9 @@ var BatchUpdater = class {
     if (this.limitCount !== void 0 && this.limitCount > 0) {
       query = query.limit(this.limitCount);
     }
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      query = query.select(...this.selectedFields);
+    }
     return query;
   }
   /**

package/dist/index.mjs

@@ -119,12 +119,20 @@ function createLogCollector(operation, collection, conditions, updateData) {
 }
 
 // src/utils/index.ts
-function calculateProgress(current, total) {
+function calculateProgress(current, total, startTime) {
   const percentage = total === 0 ? 0 : Math.round(current / total * 100);
+  const now = Date.now();
+  const elapsedTime = startTime ? now - startTime : 0;
+  const docsPerSecond = elapsedTime > 0 ? Math.round(current / elapsedTime * 1e3 * 100) / 100 : 0;
+  const remaining = total - current;
+  const eta = docsPerSecond > 0 ? Math.round(remaining / docsPerSecond * 100) / 100 : 0;
   return {
     current,
     total,
-    percentage
+    percentage,
+    elapsedTime,
+    docsPerSecond,
+    eta
   };
 }
 function getAffectedFields(updateData) {
@@ -151,20 +159,38 @@ var BatchUpdater = class {
    * @param firestore - Initialized Firestore instance from firebase-admin
    */
   constructor(firestore) {
+    this.isCollectionGroup = false;
     this.conditions = [];
     this.orderByConditions = [];
     this.firestore = firestore;
   }
   /**
    * Select a collection to operate on
+   * Supports subcollection paths like "users/userId/orders"
    * @param path - Collection path
    * @returns This instance for chaining
    */
   collection(path2) {
     this.collectionPath = path2;
+    this.isCollectionGroup = false;
     this.conditions = [];
     this.orderByConditions = [];
     this.limitCount = void 0;
+    this.selectedFields = void 0;
+    return this;
+  }
+  /**
+   * Select a collection group to operate on (queries across all subcollections with the same name)
+   * @param collectionId - Collection ID (not a path, just the collection name)
+   * @returns This instance for chaining
+   */
+  collectionGroup(collectionId) {
+    this.collectionPath = collectionId;
+    this.isCollectionGroup = true;
+    this.conditions = [];
+    this.orderByConditions = [];
+    this.limitCount = void 0;
+    this.selectedFields = void 0;
     return this;
   }
   /**
@@ -197,6 +223,44 @@ var BatchUpdater = class {
     this.limitCount = count;
     return this;
   }
+  /**
+   * Select specific fields to retrieve (reduces memory usage and read costs)
+   * @param fields - Field paths to retrieve
+   * @returns This instance for chaining
+   */
+  select(...fields) {
+    this.selectedFields = fields;
+    return this;
+  }
+  /**
+   * Count documents matching the query conditions
+   * @returns Count result with number of matching documents
+   */
+  async count() {
+    this.validateSetup();
+    const query = this.buildQuery();
+    const snapshot = await query.count().get();
+    return {
+      count: snapshot.data().count
+    };
+  }
+  /**
+   * Find the first document matching the query conditions
+   * @returns First matching document with id and data, or null if not found
+   */
+  async findOne() {
+    this.validateSetup();
+    const query = this.buildQuery().limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const doc = snapshot.docs[0];
+    return {
+      id: doc.id,
+      data: doc.data()
+    };
+  }
   /**
    * Preview changes before executing update
    * @param updateData - Data to update
@@ -231,14 +295,24 @@ var BatchUpdater = class {
   /**
    * Execute batch update operation
    * @param updateData - Data to update
-   * @param options - Update options (e.g., progress callback, log options, batchSize for pagination)
-   * @returns Update result with success/failure counts and optional log file path
+   * @param options - Update options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+   * @returns Update result with success/failure counts and optional log file path, or DryRunResult if dryRun is true
    */
   async update(updateData, options = {}) {
     this.validateSetup();
     if (!isValidUpdateData(updateData)) {
       throw new Error("Update data must be a non-empty object");
     }
+    if (options.dryRun) {
+      const query = this.buildQuery();
+      const snapshot = await query.limit(10).get();
+      const countSnapshot = await this.buildQuery().count().get();
+      return {
+        wouldAffect: countSnapshot.data().count,
+        sampleIds: snapshot.docs.map((doc) => doc.id),
+        operation: "update"
+      };
+    }
     const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath, this.conditions, updateData) : null;
     let successCount = 0;
     let failureCount = 0;
@@ -387,12 +461,16 @@ var BatchUpdater = class {
   }
   /**
    * Create multiple documents in batch
+   * Note: This method does not work with collectionGroup()
    * @param documents - Array of documents to create
    * @param options - Create options (e.g., progress callback, log options)
    * @returns Create result with success/failure counts, created IDs, and optional log file path
    */
   async create(documents, options = {}) {
     this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error("create() cannot be used with collectionGroup(). Use collection() with a specific path instead.");
+    }
     if (!Array.isArray(documents) || documents.length === 0) {
       throw new Error("Documents array must be non-empty");
     }
@@ -453,14 +531,24 @@ var BatchUpdater = class {
    * Upsert documents matching query conditions
    * Updates existing documents or creates them if they don't exist
    * @param updateData - Data to set/merge
-   * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination)
-   * @returns Upsert result with success/failure counts and optional log file path
+   * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+   * @returns Upsert result with success/failure counts and optional log file path, or DryRunResult if dryRun is true
    */
   async upsert(updateData, options = {}) {
     this.validateSetup();
     if (!isValidUpdateData(updateData)) {
       throw new Error("Update data must be a non-empty object");
     }
+    if (options.dryRun) {
+      const query = this.buildQuery();
+      const snapshot = await query.limit(10).get();
+      const countSnapshot = await this.buildQuery().count().get();
+      return {
+        wouldAffect: countSnapshot.data().count,
+        sampleIds: snapshot.docs.map((doc) => doc.id),
+        operation: "upsert"
+      };
+    }
     const logCollector = options.log?.enabled ? createLogCollector("upsert", this.collectionPath, this.conditions, updateData) : null;
     let successCount = 0;
     let failureCount = 0;
@@ -589,11 +677,21 @@ var BatchUpdater = class {
   }
   /**
    * Delete documents matching query conditions
-   * @param options - Delete options (e.g., progress callback, log options, batchSize for pagination)
-   * @returns Delete result with success/failure counts, deleted IDs, and optional log file path
+   * @param options - Delete options (e.g., progress callback, log options, batchSize for pagination, dryRun)
+   * @returns Delete result with success/failure counts, deleted IDs, and optional log file path, or DryRunResult if dryRun is true
    */
   async delete(options = {}) {
     this.validateSetup();
+    if (options.dryRun) {
+      const query = this.buildQuery();
+      const snapshot = await query.limit(10).get();
+      const countSnapshot = await this.buildQuery().count().get();
+      return {
+        wouldAffect: countSnapshot.data().count,
+        sampleIds: snapshot.docs.map((doc) => doc.id),
+        operation: "delete"
+      };
+    }
     const logCollector = options.log?.enabled ? createLogCollector("delete", this.collectionPath, this.conditions) : null;
     let successCount = 0;
     let failureCount = 0;
@@ -740,9 +838,7 @@ var BatchUpdater = class {
    * @private
    */
   buildQuery() {
-    let query = this.firestore.collection(
-      this.collectionPath
-    );
+    let query = this.isCollectionGroup ? this.firestore.collectionGroup(this.collectionPath) : this.firestore.collection(this.collectionPath);
     for (const condition of this.conditions) {
       query = query.where(condition.field, condition.operator, condition.value);
     }
@@ -752,6 +848,9 @@ var BatchUpdater = class {
     if (this.limitCount !== void 0 && this.limitCount > 0) {
       query = query.limit(this.limitCount);
     }
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      query = query.select(...this.selectedFields);
+    }
     return query;
   }
   /**

package/package.json

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