firestore-batch-updater 1.7.0 → 1.8.0

package/README.ko.md

@@ -22,6 +22,8 @@
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
+- 문서 변환 - `transform()`으로 각 문서에 커스텀 로직 적용 (가격 인상, 데이터 마이그레이션 등)
+- 복사 & 이동 - `copyTo()`로 컬렉션 간 문서 복사/이동 (데이터 변환 옵션 포함)
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -110,6 +112,8 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `bulkCreate(docs, options?)` | 여러 문서를 각기 다른 데이터로 생성 | `BulkCreateResult` |
 | `bulkUpdate(updates, options?)` | 여러 문서에 각기 다른 데이터 업데이트 | `BulkUpdateResult` |
 | `bulkDelete(ids, options?)` | ID 배열로 여러 문서 삭제 | `BulkDeleteResult` |
+| `transform(fn, options?)` | 커스텀 함수로 문서 변환 | `TransformResult` |
+| `copyTo(target, options?)` | 다른 컬렉션으로 문서 복사/이동 | `CopyToResult` |
 | `getFields(field)` | 특정 필드 값 조회 | `FieldValueResult[]` |
 
 ### 옵션
@@ -162,6 +166,8 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `BulkCreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `BulkDeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
+| `TransformResult` | `successCount`, `failureCount`, `skippedCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
+| `CopyToResult` | `successCount`, `failureCount`, `totalCount`, `copiedIds[]`, `failedDocIds?`, `logFilePath?` |
 | `FieldValueResult` | `id`, `value` |
 
 ## 사용 예시
@@ -609,6 +615,58 @@ const result2 = await updater.collection("logs").bulkDelete(expiredLogIds, {
 });
 ```
 
+### 문서 변환
+
+```typescript
+// 각 문서에 커스텀 로직 적용
+const result = await updater
+  .collection("products")
+  .where("category", "==", "electronics")
+  .transform((doc) => ({
+    price: doc.data.price * 1.1, // 10% 가격 인상
+    name: doc.data.name.toUpperCase(),
+  }));
+
+console.log(`변환: ${result.successCount}, 건너뜀: ${result.skippedCount}`);
+
+// 조건부 건너뛰기 (null 반환 시 스킵)
+const result2 = await updater
+  .collection("users")
+  .transform((doc) => {
+    if (doc.data.score < 50) return null; // 낮은 점수 건너뛰기
+    return { tier: "premium" };
+  });
+```
+
+### 문서 복사 & 이동
+
+```typescript
+// 다른 컬렉션으로 문서 복사
+const result = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .copyTo("archived_users");
+
+console.log(`${result.successCount}개 문서 복사 완료`);
+
+// 데이터 변환하며 복사 (민감 정보 제거 등)
+await updater
+  .collection("users")
+  .copyTo("public_profiles", {
+    transform: (doc) => ({
+      name: doc.data.name,
+      avatar: doc.data.avatar,
+      // password, email 제외
+    }),
+  });
+
+// 문서 이동 (복사 + 원본 삭제)
+await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .copyTo("order_archive", { deleteSource: true });
+```
+
 ### Dry Run 모드
 
 ```typescript

package/README.md

@@ -22,6 +22,8 @@ English | [한국어](./README.ko.md)
 - Cursor pagination - Use `paginate()` for memory-efficient page-by-page iteration
 - Direct ID lookup - Use `getOne()` for fast document retrieval by ID
 - Bulk operations - Use `bulkCreate()`, `bulkUpdate()`, `bulkDelete()` for efficient multi-document operations with different data each
+- 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
 - 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
@@ -110,6 +112,8 @@ console.log(`Updated ${result.successCount} documents`);
 | `bulkCreate(docs, options?)` | Create multiple docs with different data | `BulkCreateResult` |
 | `bulkUpdate(updates, options?)` | Update multiple docs with different data | `BulkUpdateResult` |
 | `bulkDelete(ids, options?)` | Delete multiple docs by ID | `BulkDeleteResult` |
+| `transform(fn, options?)` | Transform docs with custom function | `TransformResult` |
+| `copyTo(target, options?)` | Copy/move docs to another collection | `CopyToResult` |
 | `getFields(field)` | Get specific field values | `FieldValueResult[]` |
 
 ### Options
@@ -162,6 +166,8 @@ All write operations support an optional `options` parameter:
 | `BulkCreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `BulkDeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
+| `TransformResult` | `successCount`, `failureCount`, `skippedCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
+| `CopyToResult` | `successCount`, `failureCount`, `totalCount`, `copiedIds[]`, `failedDocIds?`, `logFilePath?` |
 | `FieldValueResult` | `id`, `value` |
 
 ## Usage Examples
@@ -597,6 +603,58 @@ const result2 = await updater.collection("logs").bulkDelete(expiredLogIds, {
 });
 ```
 
+### Transform Documents
+
+```typescript
+// Apply custom logic to each document
+const result = await updater
+  .collection("products")
+  .where("category", "==", "electronics")
+  .transform((doc) => ({
+    price: doc.data.price * 1.1, // 10% price increase
+    name: doc.data.name.toUpperCase(),
+  }));
+
+console.log(`Transformed ${result.successCount}, skipped ${result.skippedCount}`);
+
+// Skip documents conditionally (return null)
+const result2 = await updater
+  .collection("users")
+  .transform((doc) => {
+    if (doc.data.score < 50) return null; // Skip low scores
+    return { tier: "premium" };
+  });
+```
+
+### Copy & Move Documents
+
+```typescript
+// Copy documents to another collection
+const result = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .copyTo("archived_users");
+
+console.log(`Copied ${result.successCount} documents`);
+
+// Copy with data transformation (e.g., remove sensitive fields)
+await updater
+  .collection("users")
+  .copyTo("public_profiles", {
+    transform: (doc) => ({
+      name: doc.data.name,
+      avatar: doc.data.avatar,
+      // password, email omitted
+    }),
+  });
+
+// Move documents (copy + delete source)
+await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .copyTo("order_archive", { deleteSource: true });
+```
+
 ### Dry Run Mode
 
 ```typescript

package/dist/index.d.mts

@@ -387,6 +387,74 @@ interface BulkUpdateResult {
     totalCount: number;
     failedDocIds?: string[];
 }
+/**
+ * Transform function that receives document data and returns the update data
+ */
+type TransformFn = (doc: {
+    id: string;
+    data: Record<string, any>;
+}) => Record<string, any> | null;
+/**
+ * Options for transform operation
+ */
+interface TransformOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+    /**
+     * Batch size for pagination (optional)
+     */
+    batchSize?: number;
+}
+/**
+ * Result of transform operation
+ */
+interface TransformResult {
+    successCount: number;
+    failureCount: number;
+    skippedCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
+/**
+ * Options for copyTo operation
+ */
+interface CopyToOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+    /**
+     * Optional transform function to modify data before copying
+     */
+    transform?: TransformFn;
+    /**
+     * Whether to delete source documents after copying (move operation)
+     * @default false
+     */
+    deleteSource?: boolean;
+}
+/**
+ * Result of copyTo operation
+ */
+interface CopyToResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    copiedIds: string[];
+    failedDocIds?: string[];
+}
 
 /**
  * BatchUpdater - Core class for batch operations on Firestore
@@ -580,6 +648,25 @@ declare class BatchUpdater {
     bulkDelete(ids: string[], options?: BulkDeleteOptions): Promise<BulkDeleteResult & {
         logFilePath?: string;
     }>;
+    /**
+     * Transform matching documents using a custom function
+     * Reads each document, applies the transform function, and updates with the result
+     * @param transformFn - Function that receives { id, data } and returns update data, or null to skip
+     * @param options - Transform options (e.g., progress callback, log options, batchSize)
+     * @returns Transform result with success/failure/skipped counts and optional log file path
+     */
+    transform(transformFn: TransformFn, options?: TransformOptions): Promise<TransformResult & {
+        logFilePath?: string;
+    }>;
+    /**
+     * Copy matching documents to another collection
+     * @param targetCollection - Target collection path to copy documents to
+     * @param options - Copy options (transform, deleteSource for move, progress callback)
+     * @returns Copy result with success/failure counts, copied IDs, and optional log file path
+     */
+    copyTo(targetCollection: string, options?: CopyToOptions): Promise<CopyToResult & {
+        logFilePath?: string;
+    }>;
     /**
      * Upsert documents matching query conditions
      * Updates existing documents or creates them if they don't exist
@@ -675,4 +762,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 CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, 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 CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, 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

@@ -387,6 +387,74 @@ interface BulkUpdateResult {
     totalCount: number;
     failedDocIds?: string[];
 }
+/**
+ * Transform function that receives document data and returns the update data
+ */
+type TransformFn = (doc: {
+    id: string;
+    data: Record<string, any>;
+}) => Record<string, any> | null;
+/**
+ * Options for transform operation
+ */
+interface TransformOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+    /**
+     * Batch size for pagination (optional)
+     */
+    batchSize?: number;
+}
+/**
+ * Result of transform operation
+ */
+interface TransformResult {
+    successCount: number;
+    failureCount: number;
+    skippedCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
+/**
+ * Options for copyTo operation
+ */
+interface CopyToOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+    /**
+     * Optional transform function to modify data before copying
+     */
+    transform?: TransformFn;
+    /**
+     * Whether to delete source documents after copying (move operation)
+     * @default false
+     */
+    deleteSource?: boolean;
+}
+/**
+ * Result of copyTo operation
+ */
+interface CopyToResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    copiedIds: string[];
+    failedDocIds?: string[];
+}
 
 /**
  * BatchUpdater - Core class for batch operations on Firestore
@@ -580,6 +648,25 @@ declare class BatchUpdater {
     bulkDelete(ids: string[], options?: BulkDeleteOptions): Promise<BulkDeleteResult & {
         logFilePath?: string;
     }>;
+    /**
+     * Transform matching documents using a custom function
+     * Reads each document, applies the transform function, and updates with the result
+     * @param transformFn - Function that receives { id, data } and returns update data, or null to skip
+     * @param options - Transform options (e.g., progress callback, log options, batchSize)
+     * @returns Transform result with success/failure/skipped counts and optional log file path
+     */
+    transform(transformFn: TransformFn, options?: TransformOptions): Promise<TransformResult & {
+        logFilePath?: string;
+    }>;
+    /**
+     * Copy matching documents to another collection
+     * @param targetCollection - Target collection path to copy documents to
+     * @param options - Copy options (transform, deleteSource for move, progress callback)
+     * @returns Copy result with success/failure counts, copied IDs, and optional log file path
+     */
+    copyTo(targetCollection: string, options?: CopyToOptions): Promise<CopyToResult & {
+        logFilePath?: string;
+    }>;
     /**
      * Upsert documents matching query conditions
      * Updates existing documents or creates them if they don't exist
@@ -675,4 +762,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 CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, 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 CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, 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

@@ -972,6 +972,231 @@ var BatchUpdater = class {
     }
     return result;
   }
+  /**
+   * Transform matching documents using a custom function
+   * Reads each document, applies the transform function, and updates with the result
+   * @param transformFn - Function that receives { id, data } and returns update data, or null to skip
+   * @param options - Transform options (e.g., progress callback, log options, batchSize)
+   * @returns Transform result with success/failure/skipped counts and optional log file path
+   */
+  async transform(transformFn, options = {}) {
+    this.validateSetup();
+    if (typeof transformFn !== "function") {
+      throw new Error("Transform function is required");
+    }
+    const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath, this.conditions) : null;
+    let successCount = 0;
+    let failureCount = 0;
+    let skippedCount = 0;
+    let totalCount = 0;
+    const failedDocIds = [];
+    const processDocuments = async (docs, processedSoFar, grandTotal) => {
+      const bulkWriter = this.firestore.bulkWriter();
+      let processedCount = processedSoFar;
+      const docIdMap = /* @__PURE__ */ new Map();
+      bulkWriter.onWriteResult((ref) => {
+        successCount++;
+        processedCount++;
+        const docId = docIdMap.get(ref.path) || ref.id;
+        logCollector?.addEntry(docId, "success");
+        if (options.onProgress) {
+          const progress = calculateProgress(processedCount, grandTotal);
+          options.onProgress(progress);
+        }
+      });
+      bulkWriter.onWriteError((error) => {
+        failureCount++;
+        processedCount++;
+        const docId = error.documentRef?.id || "unknown";
+        failedDocIds.push(docId);
+        logCollector?.addEntry(docId, "failure", error.message);
+        if (options.onProgress) {
+          const progress = calculateProgress(processedCount, grandTotal);
+          options.onProgress(progress);
+        }
+        return false;
+      });
+      for (const doc of docs) {
+        const updateData = transformFn({ id: doc.id, data: doc.data() });
+        if (updateData === null) {
+          skippedCount++;
+          processedCount++;
+          if (options.onProgress) {
+            const progress = calculateProgress(processedCount, grandTotal);
+            options.onProgress(progress);
+          }
+          continue;
+        }
+        docIdMap.set(doc.ref.path, doc.id);
+        bulkWriter.update(doc.ref, updateData);
+      }
+      await bulkWriter.close();
+      return processedCount;
+    };
+    if (options.batchSize && options.batchSize > 0) {
+      const countSnapshot = await this.buildQuery().count().get();
+      totalCount = countSnapshot.data().count;
+      if (totalCount === 0) {
+        const result2 = {
+          successCount: 0,
+          failureCount: 0,
+          skippedCount: 0,
+          totalCount: 0
+        };
+        if (logCollector && options.log) {
+          result2.logFilePath = logCollector.finalize(options.log);
+        }
+        return result2;
+      }
+      let processedCount = 0;
+      let lastDoc = null;
+      while (true) {
+        let paginatedQuery = this.buildQuery().limit(options.batchSize);
+        if (lastDoc) {
+          paginatedQuery = paginatedQuery.startAfter(lastDoc);
+        }
+        const snapshot = await paginatedQuery.get();
+        if (snapshot.empty) break;
+        processedCount = await processDocuments(
+          snapshot.docs,
+          processedCount,
+          totalCount
+        );
+        lastDoc = snapshot.docs[snapshot.docs.length - 1];
+        if (snapshot.docs.length < options.batchSize) break;
+      }
+    } else {
+      const query = this.buildQuery();
+      const snapshot = await query.get();
+      totalCount = snapshot.size;
+      if (totalCount === 0) {
+        const result2 = {
+          successCount: 0,
+          failureCount: 0,
+          skippedCount: 0,
+          totalCount: 0
+        };
+        if (logCollector && options.log) {
+          result2.logFilePath = logCollector.finalize(options.log);
+        }
+        return result2;
+      }
+      await processDocuments(snapshot.docs, 0, totalCount);
+    }
+    const result = {
+      successCount,
+      failureCount,
+      skippedCount,
+      totalCount,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
+  /**
+   * Copy matching documents to another collection
+   * @param targetCollection - Target collection path to copy documents to
+   * @param options - Copy options (transform, deleteSource for move, progress callback)
+   * @returns Copy result with success/failure counts, copied IDs, and optional log file path
+   */
+  async copyTo(targetCollection, options = {}) {
+    this.validateSetup();
+    if (!targetCollection || typeof targetCollection !== "string") {
+      throw new Error("Target collection path is required");
+    }
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "copyTo() cannot be used with collectionGroup(). Use collection() with a specific path instead."
+      );
+    }
+    const logCollector = options.log?.enabled ? createLogCollector("create", targetCollection) : null;
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    const totalCount = snapshot.size;
+    if (totalCount === 0) {
+      const result2 = {
+        successCount: 0,
+        failureCount: 0,
+        totalCount: 0,
+        copiedIds: []
+      };
+      if (logCollector && options.log) {
+        result2.logFilePath = logCollector.finalize(options.log);
+      }
+      return result2;
+    }
+    let successCount = 0;
+    let failureCount = 0;
+    const copiedIds = [];
+    const failedDocIds = [];
+    const bulkWriter = this.firestore.bulkWriter();
+    const targetCol = this.firestore.collection(targetCollection);
+    let processedCount = 0;
+    const docIdMap = /* @__PURE__ */ new Map();
+    bulkWriter.onWriteResult((ref) => {
+      successCount++;
+      processedCount++;
+      const docId = docIdMap.get(ref.path) || ref.id;
+      copiedIds.push(docId);
+      logCollector?.addEntry(docId, "success");
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+    });
+    bulkWriter.onWriteError((error) => {
+      failureCount++;
+      processedCount++;
+      const docId = error.documentRef?.id || "unknown";
+      failedDocIds.push(docId);
+      logCollector?.addEntry(docId, "failure", error.message);
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+      return false;
+    });
+    for (const doc of snapshot.docs) {
+      let data = doc.data();
+      if (options.transform) {
+        const transformed = options.transform({ id: doc.id, data });
+        if (transformed === null) {
+          processedCount++;
+          if (options.onProgress) {
+            const progress = calculateProgress(processedCount, totalCount);
+            options.onProgress(progress);
+          }
+          continue;
+        }
+        data = transformed;
+      }
+      const targetRef = targetCol.doc(doc.id);
+      docIdMap.set(targetRef.path, doc.id);
+      bulkWriter.set(targetRef, data);
+    }
+    await bulkWriter.close();
+    if (options.deleteSource && copiedIds.length > 0) {
+      const deleteBulkWriter = this.firestore.bulkWriter();
+      const sourceCol = this.firestore.collection(this.collectionPath);
+      for (const id of copiedIds) {
+        deleteBulkWriter.delete(sourceCol.doc(id));
+      }
+      await deleteBulkWriter.close();
+    }
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      copiedIds,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
   /**
    * Upsert documents matching query conditions
    * Updates existing documents or creates them if they don't exist

package/dist/index.mjs

@@ -927,6 +927,231 @@ var BatchUpdater = class {
     }
     return result;
   }
+  /**
+   * Transform matching documents using a custom function
+   * Reads each document, applies the transform function, and updates with the result
+   * @param transformFn - Function that receives { id, data } and returns update data, or null to skip
+   * @param options - Transform options (e.g., progress callback, log options, batchSize)
+   * @returns Transform result with success/failure/skipped counts and optional log file path
+   */
+  async transform(transformFn, options = {}) {
+    this.validateSetup();
+    if (typeof transformFn !== "function") {
+      throw new Error("Transform function is required");
+    }
+    const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath, this.conditions) : null;
+    let successCount = 0;
+    let failureCount = 0;
+    let skippedCount = 0;
+    let totalCount = 0;
+    const failedDocIds = [];
+    const processDocuments = async (docs, processedSoFar, grandTotal) => {
+      const bulkWriter = this.firestore.bulkWriter();
+      let processedCount = processedSoFar;
+      const docIdMap = /* @__PURE__ */ new Map();
+      bulkWriter.onWriteResult((ref) => {
+        successCount++;
+        processedCount++;
+        const docId = docIdMap.get(ref.path) || ref.id;
+        logCollector?.addEntry(docId, "success");
+        if (options.onProgress) {
+          const progress = calculateProgress(processedCount, grandTotal);
+          options.onProgress(progress);
+        }
+      });
+      bulkWriter.onWriteError((error) => {
+        failureCount++;
+        processedCount++;
+        const docId = error.documentRef?.id || "unknown";
+        failedDocIds.push(docId);
+        logCollector?.addEntry(docId, "failure", error.message);
+        if (options.onProgress) {
+          const progress = calculateProgress(processedCount, grandTotal);
+          options.onProgress(progress);
+        }
+        return false;
+      });
+      for (const doc of docs) {
+        const updateData = transformFn({ id: doc.id, data: doc.data() });
+        if (updateData === null) {
+          skippedCount++;
+          processedCount++;
+          if (options.onProgress) {
+            const progress = calculateProgress(processedCount, grandTotal);
+            options.onProgress(progress);
+          }
+          continue;
+        }
+        docIdMap.set(doc.ref.path, doc.id);
+        bulkWriter.update(doc.ref, updateData);
+      }
+      await bulkWriter.close();
+      return processedCount;
+    };
+    if (options.batchSize && options.batchSize > 0) {
+      const countSnapshot = await this.buildQuery().count().get();
+      totalCount = countSnapshot.data().count;
+      if (totalCount === 0) {
+        const result2 = {
+          successCount: 0,
+          failureCount: 0,
+          skippedCount: 0,
+          totalCount: 0
+        };
+        if (logCollector && options.log) {
+          result2.logFilePath = logCollector.finalize(options.log);
+        }
+        return result2;
+      }
+      let processedCount = 0;
+      let lastDoc = null;
+      while (true) {
+        let paginatedQuery = this.buildQuery().limit(options.batchSize);
+        if (lastDoc) {
+          paginatedQuery = paginatedQuery.startAfter(lastDoc);
+        }
+        const snapshot = await paginatedQuery.get();
+        if (snapshot.empty) break;
+        processedCount = await processDocuments(
+          snapshot.docs,
+          processedCount,
+          totalCount
+        );
+        lastDoc = snapshot.docs[snapshot.docs.length - 1];
+        if (snapshot.docs.length < options.batchSize) break;
+      }
+    } else {
+      const query = this.buildQuery();
+      const snapshot = await query.get();
+      totalCount = snapshot.size;
+      if (totalCount === 0) {
+        const result2 = {
+          successCount: 0,
+          failureCount: 0,
+          skippedCount: 0,
+          totalCount: 0
+        };
+        if (logCollector && options.log) {
+          result2.logFilePath = logCollector.finalize(options.log);
+        }
+        return result2;
+      }
+      await processDocuments(snapshot.docs, 0, totalCount);
+    }
+    const result = {
+      successCount,
+      failureCount,
+      skippedCount,
+      totalCount,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
+  /**
+   * Copy matching documents to another collection
+   * @param targetCollection - Target collection path to copy documents to
+   * @param options - Copy options (transform, deleteSource for move, progress callback)
+   * @returns Copy result with success/failure counts, copied IDs, and optional log file path
+   */
+  async copyTo(targetCollection, options = {}) {
+    this.validateSetup();
+    if (!targetCollection || typeof targetCollection !== "string") {
+      throw new Error("Target collection path is required");
+    }
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "copyTo() cannot be used with collectionGroup(). Use collection() with a specific path instead."
+      );
+    }
+    const logCollector = options.log?.enabled ? createLogCollector("create", targetCollection) : null;
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    const totalCount = snapshot.size;
+    if (totalCount === 0) {
+      const result2 = {
+        successCount: 0,
+        failureCount: 0,
+        totalCount: 0,
+        copiedIds: []
+      };
+      if (logCollector && options.log) {
+        result2.logFilePath = logCollector.finalize(options.log);
+      }
+      return result2;
+    }
+    let successCount = 0;
+    let failureCount = 0;
+    const copiedIds = [];
+    const failedDocIds = [];
+    const bulkWriter = this.firestore.bulkWriter();
+    const targetCol = this.firestore.collection(targetCollection);
+    let processedCount = 0;
+    const docIdMap = /* @__PURE__ */ new Map();
+    bulkWriter.onWriteResult((ref) => {
+      successCount++;
+      processedCount++;
+      const docId = docIdMap.get(ref.path) || ref.id;
+      copiedIds.push(docId);
+      logCollector?.addEntry(docId, "success");
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+    });
+    bulkWriter.onWriteError((error) => {
+      failureCount++;
+      processedCount++;
+      const docId = error.documentRef?.id || "unknown";
+      failedDocIds.push(docId);
+      logCollector?.addEntry(docId, "failure", error.message);
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+      return false;
+    });
+    for (const doc of snapshot.docs) {
+      let data = doc.data();
+      if (options.transform) {
+        const transformed = options.transform({ id: doc.id, data });
+        if (transformed === null) {
+          processedCount++;
+          if (options.onProgress) {
+            const progress = calculateProgress(processedCount, totalCount);
+            options.onProgress(progress);
+          }
+          continue;
+        }
+        data = transformed;
+      }
+      const targetRef = targetCol.doc(doc.id);
+      docIdMap.set(targetRef.path, doc.id);
+      bulkWriter.set(targetRef, data);
+    }
+    await bulkWriter.close();
+    if (options.deleteSource && copiedIds.length > 0) {
+      const deleteBulkWriter = this.firestore.bulkWriter();
+      const sourceCol = this.firestore.collection(this.collectionPath);
+      for (const id of copiedIds) {
+        deleteBulkWriter.delete(sourceCol.doc(id));
+      }
+      await deleteBulkWriter.close();
+    }
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      copiedIds,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
   /**
    * Upsert documents matching query conditions
    * Updates existing documents or creates them if they don't exist

package/package.json

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