firestore-batch-updater 1.1.0 → 1.2.0

package/README.ko.md

@@ -14,7 +14,10 @@
 - 진행 상황 추적 - 실시간 진행률 콜백
 - 일괄 생성/Upsert/삭제 - 여러 문서를 한 번에 생성, upsert 또는 삭제
 - 정렬 및 제한 - `orderBy()`와 `limit()`으로 정밀한 제어
-- FieldValue 지원 - `increment()`, `arrayUnion()`, `serverTimestamp()` 등 사용 가능
+- FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
+- 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
+- Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
+- 문서 개수 조회 - 문서를 로드하지 않고 빠르게 개수 확인
 - 로그 파일 생성 - 감사를 위한 상세 작업 로그 (선택사항)
 
 ## 설치
@@ -75,10 +78,12 @@ 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` |
+| `count()` | 매칭되는 문서 개수 조회 | `CountResult` |
 | `preview(data)` | 업데이트 전 미리보기 | `PreviewResult` |
 | `update(data, options?)` | 매칭되는 문서 업데이트 | `UpdateResult` |
 | `create(docs, options?)` | 새 문서 생성 | `CreateResult` |
@@ -95,6 +100,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
   onProgress?: (progress: ProgressInfo) => void;
   log?: LogOptions;
   batchSize?: number;  // update/upsert/delete 전용
+  dryRun?: boolean;    // update/upsert/delete 전용 - 실제 쓰기 없이 시뮬레이션
 }
 
 // ProgressInfo
@@ -116,10 +122,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 +296,80 @@ 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}명의 비활성 사용자 발견`);
+```
+
+### 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,10 @@ 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.
+- 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 +78,12 @@ 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` |
+| `count()` | Count matching documents | `CountResult` |
 | `preview(data)` | Preview changes before update | `PreviewResult` |
 | `update(data, options?)` | Update matching documents | `UpdateResult` |
 | `create(docs, options?)` | Create new documents | `CreateResult` |
@@ -95,6 +100,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 +122,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 +295,80 @@ 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`);
+```
+
+### 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

@@ -32,6 +32,11 @@ 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;
 }
 /**
  * Result of batch update operation
@@ -130,6 +135,11 @@ 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;
 }
 /**
  * Result of batch upsert operation
@@ -159,6 +169,11 @@ 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;
 }
 /**
  * Result of batch delete operation
@@ -170,6 +185,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,6 +244,7 @@ interface OperationLog {
 declare class BatchUpdater {
     private firestore;
     private collectionPath?;
+    private isCollectionGroup;
     private conditions;
     private orderByConditions;
     private limitCount?;
@@ -225,10 +255,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 +287,11 @@ declare class BatchUpdater {
      * @returns This instance for chaining
      */
     limit(count: number): this;
+    /**
+     * Count documents matching the query conditions
+     * @returns Count result with number of matching documents
+     */
+    count(): Promise<CountResult>;
     /**
      * Preview changes before executing update
      * @param updateData - Data to update
@@ -259,12 +301,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 +315,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 +327,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
@@ -374,4 +417,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

@@ -32,6 +32,11 @@ 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;
 }
 /**
  * Result of batch update operation
@@ -130,6 +135,11 @@ 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;
 }
 /**
  * Result of batch upsert operation
@@ -159,6 +169,11 @@ 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;
 }
 /**
  * Result of batch delete operation
@@ -170,6 +185,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,6 +244,7 @@ interface OperationLog {
 declare class BatchUpdater {
     private firestore;
     private collectionPath?;
+    private isCollectionGroup;
     private conditions;
     private orderByConditions;
     private limitCount?;
@@ -225,10 +255,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 +287,11 @@ declare class BatchUpdater {
      * @returns This instance for chaining
      */
     limit(count: number): this;
+    /**
+     * Count documents matching the query conditions
+     * @returns Count result with number of matching documents
+     */
+    count(): Promise<CountResult>;
     /**
      * Preview changes before executing update
      * @param updateData - Data to update
@@ -259,12 +301,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 +315,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 +327,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
@@ -374,4 +417,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

@@ -196,17 +196,33 @@ 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;
+    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;
@@ -242,6 +258,18 @@ var BatchUpdater = class {
     this.limitCount = count;
     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
+    };
+  }
   /**
    * Preview changes before executing update
    * @param updateData - Data to update
@@ -276,14 +304,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 +470,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 +540,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 +686,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 +847,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);
     }

package/dist/index.mjs

@@ -151,17 +151,33 @@ 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;
+    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;
@@ -197,6 +213,18 @@ var BatchUpdater = class {
     this.limitCount = count;
     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
+    };
+  }
   /**
    * Preview changes before executing update
    * @param updateData - Data to update
@@ -231,14 +259,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 +425,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 +495,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 +641,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 +802,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);
     }

package/package.json

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