firestore-batch-updater 1.5.0 → 1.6.0

package/README.ko.md

@@ -20,6 +20,8 @@
 - 전체 문서 조회 - `getAll()`로 매칭되는 모든 문서 데이터 조회
 - 집계 쿼리 - `aggregate()`로 서버 사이드 `sum`, `average`, `count` 연산
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
+- ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
+- 벌크 업데이트 - `bulkUpdate()`로 여러 문서에 각기 다른 데이터 업데이트
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -93,6 +95,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `count()` | 매칭되는 문서 개수 조회 | `CountResult` |
 | `exists()` | 매칭되는 문서 존재 여부 확인 | `boolean` |
 | `findOne()` | 첫 번째 매칭 문서 조회 | `{ id, data } \| null` |
+| `getOne(id)` | ID로 문서 직접 조회 | `{ id, data } \| null` |
 | `getAll()` | 모든 매칭 문서 조회 | `{ id, data }[]` |
 | `preview(data)` | 업데이트 전 미리보기 | `PreviewResult` |
 | `update(data, options?)` | 매칭되는 문서 업데이트 | `UpdateResult` |
@@ -104,6 +107,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `deleteOne()` | 첫 번째 매칭 문서 삭제 | `{ success, id }` |
 | `aggregate(spec)` | sum/average/count 집계 쿼리 | `AggregateResult` |
 | `paginate(options)` | 커서 기반 페이지네이션 | `PaginateResult` |
+| `bulkUpdate(updates, options?)` | 여러 문서에 각기 다른 데이터 업데이트 | `BulkUpdateResult` |
 | `getFields(field)` | 특정 필드 값 조회 | `FieldValueResult[]` |
 
 ### 옵션
@@ -153,6 +157,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `DeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
 | `AggregateResult` | `{ [alias]: number \| null }` |
 | `PaginateResult` | `docs[]`, `nextCursor`, `hasMore` |
+| `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `FieldValueResult` | `id`, `value` |
 
 ## 사용 예시
@@ -511,6 +516,62 @@ const page = await updater
   .paginate({ pageSize: 50 });
 ```
 
+### ID로 문서 조회
+
+```typescript
+// 문서 ID로 직접 조회 (쿼리 필터 없이 가장 빠름)
+const user = await updater.collection("users").getOne("user-123");
+
+if (user) {
+  console.log(`찾음: ${user.data.name} (${user.data.email})`);
+} else {
+  console.log("사용자를 찾을 수 없음");
+}
+
+// select와 함께 사용하여 특정 필드만 가져오기
+const userBasic = await updater
+  .collection("users")
+  .select("name", "email")
+  .getOne("user-123");
+
+// 서브컬렉션에서 문서 조회
+const order = await updater
+  .collection("users/user-123/orders")
+  .getOne("order-456");
+```
+
+### 벌크 업데이트
+
+```typescript
+// 여러 문서를 각각 다른 데이터로 업데이트
+const result = await updater.collection("users").bulkUpdate([
+  { id: "user-1", data: { name: "Alice", age: 30 } },
+  { id: "user-2", data: { name: "Bob", status: "active" } },
+  { id: "user-3", data: { email: "charlie@example.com" } },
+]);
+
+console.log(`성공: ${result.successCount}, 실패: ${result.failureCount}`);
+
+// 진행 상황 콜백과 함께 사용
+const result = await updater.collection("products").bulkUpdate(
+  [
+    { id: "prod-1", data: { price: 29.99, stock: 100 } },
+    { id: "prod-2", data: { price: 49.99, stock: 50 } },
+    // ... 더 많은 업데이트
+  ],
+  {
+    onProgress: (progress) => {
+      console.log(`${progress.processedCount}/${progress.totalCount} 처리됨`);
+    },
+  }
+);
+
+// 실패 처리
+if (result.failureCount > 0) {
+  console.log("실패한 문서 ID:", result.failedDocIds);
+}
+```
+
 ### Dry Run 모드
 
 ```typescript

package/README.md

@@ -20,6 +20,8 @@ English | [한국어](./README.ko.md)
 - Get all documents - Use `getAll()` to retrieve all matching documents with data
 - Aggregation - Use `aggregate()` for server-side `sum`, `average`, and `count` operations
 - Cursor pagination - Use `paginate()` for memory-efficient page-by-page iteration
+- Direct ID lookup - Use `getOne()` for fast document retrieval by ID
+- Bulk updates - Use `bulkUpdate()` to update multiple documents with different data each
 - 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
@@ -93,6 +95,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `count()` | Count matching documents | `CountResult` |
 | `exists()` | Check if matching documents exist | `boolean` |
 | `findOne()` | Find first matching document | `{ id, data } \| null` |
+| `getOne(id)` | Get document by ID directly | `{ id, data } \| null` |
 | `getAll()` | Get all matching documents | `{ id, data }[]` |
 | `preview(data)` | Preview changes before update | `PreviewResult` |
 | `update(data, options?)` | Update matching documents | `UpdateResult` |
@@ -104,6 +107,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `deleteOne()` | Delete first matching document | `{ success, id }` |
 | `aggregate(spec)` | Run sum/average/count queries | `AggregateResult` |
 | `paginate(options)` | Cursor-based pagination | `PaginateResult` |
+| `bulkUpdate(updates, options?)` | Update multiple docs with different data | `BulkUpdateResult` |
 | `getFields(field)` | Get specific field values | `FieldValueResult[]` |
 
 ### Options
@@ -153,6 +157,7 @@ All write operations support an optional `options` parameter:
 | `DeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
 | `AggregateResult` | `{ [alias]: number \| null }` |
 | `PaginateResult` | `docs[]`, `nextCursor`, `hasMore` |
+| `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `FieldValueResult` | `id`, `value` |
 
 ## Usage Examples
@@ -510,6 +515,51 @@ const page = await updater
   .paginate({ pageSize: 50 });
 ```
 
+### Get Document by ID
+
+```typescript
+// Fast lookup when you know the document ID
+const user = await updater.collection("users").getOne("user-123");
+
+if (user) {
+  console.log(`Found: ${user.data.name}`);
+} else {
+  console.log("User not found");
+}
+
+// Works with select for field filtering
+const profile = await updater
+  .collection("users")
+  .select("name", "avatar")
+  .getOne("user-123");
+```
+
+### Bulk Update with Different Data
+
+```typescript
+// Update multiple documents with different data for each
+const result = await updater.collection("users").bulkUpdate([
+  { id: "user-1", data: { score: 100, rank: 1 } },
+  { id: "user-2", data: { score: 85, rank: 2 } },
+  { id: "user-3", data: { score: 70, rank: 3 } },
+]);
+
+console.log(`Updated ${result.successCount} documents`);
+
+// With progress tracking
+const result2 = await updater.collection("products").bulkUpdate(
+  [
+    { id: "prod-1", data: { price: 29.99, stock: 100 } },
+    { id: "prod-2", data: { price: 49.99, stock: 50 } },
+  ],
+  {
+    onProgress: (progress) => {
+      console.log(`${progress.percentage}% complete`);
+    },
+  }
+);
+```
+
 ### Dry Run Mode
 
 ```typescript

package/dist/index.d.mts

@@ -302,6 +302,36 @@ interface PaginateResult {
     nextCursor: unknown | null;
     hasMore: boolean;
 }
+/**
+ * Input for bulk update operation
+ */
+interface BulkUpdateInput {
+    id: string;
+    data: Record<string, any>;
+}
+/**
+ * Options for bulk update operation
+ */
+interface BulkUpdateOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+}
+/**
+ * Result of bulk update operation
+ */
+interface BulkUpdateResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
 
 /**
  * BatchUpdater - Core class for batch operations on Firestore
@@ -389,6 +419,15 @@ declare class BatchUpdater {
         id: string;
         data: Record<string, any>;
     }[]>;
+    /**
+     * Get a document by its ID directly (faster than findOne with where)
+     * @param id - Document ID
+     * @returns Document with id and data, or null if not found
+     */
+    getOne(id: string): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update
@@ -459,6 +498,15 @@ declare class BatchUpdater {
     create(documents: CreateDocumentInput[], options?: CreateOptions): Promise<CreateResult & {
         logFilePath?: string;
     }>;
+    /**
+     * Update multiple documents with different data for each
+     * @param updates - Array of { id, data } objects specifying updates for each document
+     * @param options - Bulk update options (e.g., progress callback, log options)
+     * @returns Bulk update result with success/failure counts and optional log file path
+     */
+    bulkUpdate(updates: BulkUpdateInput[], options?: BulkUpdateOptions): Promise<BulkUpdateResult & {
+        logFilePath?: string;
+    }>;
     /**
      * Upsert documents matching query conditions
      * Updates existing documents or creates them if they don't exist
@@ -554,4 +602,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 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 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 };

package/dist/index.d.ts

@@ -302,6 +302,36 @@ interface PaginateResult {
     nextCursor: unknown | null;
     hasMore: boolean;
 }
+/**
+ * Input for bulk update operation
+ */
+interface BulkUpdateInput {
+    id: string;
+    data: Record<string, any>;
+}
+/**
+ * Options for bulk update operation
+ */
+interface BulkUpdateOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+}
+/**
+ * Result of bulk update operation
+ */
+interface BulkUpdateResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
 
 /**
  * BatchUpdater - Core class for batch operations on Firestore
@@ -389,6 +419,15 @@ declare class BatchUpdater {
         id: string;
         data: Record<string, any>;
     }[]>;
+    /**
+     * Get a document by its ID directly (faster than findOne with where)
+     * @param id - Document ID
+     * @returns Document with id and data, or null if not found
+     */
+    getOne(id: string): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update
@@ -459,6 +498,15 @@ declare class BatchUpdater {
     create(documents: CreateDocumentInput[], options?: CreateOptions): Promise<CreateResult & {
         logFilePath?: string;
     }>;
+    /**
+     * Update multiple documents with different data for each
+     * @param updates - Array of { id, data } objects specifying updates for each document
+     * @param options - Bulk update options (e.g., progress callback, log options)
+     * @returns Bulk update result with success/failure counts and optional log file path
+     */
+    bulkUpdate(updates: BulkUpdateInput[], options?: BulkUpdateOptions): Promise<BulkUpdateResult & {
+        logFilePath?: string;
+    }>;
     /**
      * Upsert documents matching query conditions
      * Updates existing documents or creates them if they don't exist
@@ -554,4 +602,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 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 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 };

package/dist/index.js

@@ -332,6 +332,38 @@ var BatchUpdater = class {
       data: doc.data()
     }));
   }
+  /**
+   * Get a document by its ID directly (faster than findOne with where)
+   * @param id - Document ID
+   * @returns Document with id and data, or null if not found
+   */
+  async getOne(id) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "getOne() cannot be used with collectionGroup(). Use findOne() with where conditions instead."
+      );
+    }
+    const docRef = this.firestore.collection(this.collectionPath).doc(id);
+    let docSnapshot;
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      const query = this.firestore.collection(this.collectionPath).where("__name__", "==", docRef).select(...this.selectedFields);
+      const snapshot = await query.get();
+      if (snapshot.empty) {
+        return null;
+      }
+      docSnapshot = snapshot.docs[0];
+    } else {
+      docSnapshot = await docRef.get();
+      if (!docSnapshot.exists) {
+        return null;
+      }
+    }
+    return {
+      id: docSnapshot.id,
+      data: docSnapshot.data()
+    };
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update
@@ -721,6 +753,81 @@ var BatchUpdater = class {
     }
     return result;
   }
+  /**
+   * Update multiple documents with different data for each
+   * @param updates - Array of { id, data } objects specifying updates for each document
+   * @param options - Bulk update options (e.g., progress callback, log options)
+   * @returns Bulk update result with success/failure counts and optional log file path
+   */
+  async bulkUpdate(updates, options = {}) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "bulkUpdate() cannot be used with collectionGroup(). Use collection() with a specific path instead."
+      );
+    }
+    if (!Array.isArray(updates) || updates.length === 0) {
+      throw new Error("Updates array must be non-empty");
+    }
+    for (const update of updates) {
+      if (!update.id || typeof update.id !== "string") {
+        throw new Error("Each update must have a valid id");
+      }
+      if (!isValidUpdateData(update.data)) {
+        throw new Error("Each update must have valid data");
+      }
+    }
+    const totalCount = updates.length;
+    let successCount = 0;
+    let failureCount = 0;
+    const failedDocIds = [];
+    const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath) : null;
+    const bulkWriter = this.firestore.bulkWriter();
+    const collection = this.firestore.collection(this.collectionPath);
+    let processedCount = 0;
+    const docIdMap = /* @__PURE__ */ new Map();
+    for (const update of updates) {
+      const docRef = collection.doc(update.id);
+      docIdMap.set(docRef.path, update.id);
+    }
+    bulkWriter.onWriteResult((ref) => {
+      successCount++;
+      processedCount++;
+      const docId = docIdMap.get(ref.path) || ref.id;
+      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 update of updates) {
+      const docRef = collection.doc(update.id);
+      bulkWriter.update(docRef, update.data);
+    }
+    await bulkWriter.close();
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      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

@@ -287,6 +287,38 @@ var BatchUpdater = class {
       data: doc.data()
     }));
   }
+  /**
+   * Get a document by its ID directly (faster than findOne with where)
+   * @param id - Document ID
+   * @returns Document with id and data, or null if not found
+   */
+  async getOne(id) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "getOne() cannot be used with collectionGroup(). Use findOne() with where conditions instead."
+      );
+    }
+    const docRef = this.firestore.collection(this.collectionPath).doc(id);
+    let docSnapshot;
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      const query = this.firestore.collection(this.collectionPath).where("__name__", "==", docRef).select(...this.selectedFields);
+      const snapshot = await query.get();
+      if (snapshot.empty) {
+        return null;
+      }
+      docSnapshot = snapshot.docs[0];
+    } else {
+      docSnapshot = await docRef.get();
+      if (!docSnapshot.exists) {
+        return null;
+      }
+    }
+    return {
+      id: docSnapshot.id,
+      data: docSnapshot.data()
+    };
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update
@@ -676,6 +708,81 @@ var BatchUpdater = class {
     }
     return result;
   }
+  /**
+   * Update multiple documents with different data for each
+   * @param updates - Array of { id, data } objects specifying updates for each document
+   * @param options - Bulk update options (e.g., progress callback, log options)
+   * @returns Bulk update result with success/failure counts and optional log file path
+   */
+  async bulkUpdate(updates, options = {}) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "bulkUpdate() cannot be used with collectionGroup(). Use collection() with a specific path instead."
+      );
+    }
+    if (!Array.isArray(updates) || updates.length === 0) {
+      throw new Error("Updates array must be non-empty");
+    }
+    for (const update of updates) {
+      if (!update.id || typeof update.id !== "string") {
+        throw new Error("Each update must have a valid id");
+      }
+      if (!isValidUpdateData(update.data)) {
+        throw new Error("Each update must have valid data");
+      }
+    }
+    const totalCount = updates.length;
+    let successCount = 0;
+    let failureCount = 0;
+    const failedDocIds = [];
+    const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath) : null;
+    const bulkWriter = this.firestore.bulkWriter();
+    const collection = this.firestore.collection(this.collectionPath);
+    let processedCount = 0;
+    const docIdMap = /* @__PURE__ */ new Map();
+    for (const update of updates) {
+      const docRef = collection.doc(update.id);
+      docIdMap.set(docRef.path, update.id);
+    }
+    bulkWriter.onWriteResult((ref) => {
+      successCount++;
+      processedCount++;
+      const docId = docIdMap.get(ref.path) || ref.id;
+      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 update of updates) {
+      const docRef = collection.doc(update.id);
+      bulkWriter.update(docRef, update.data);
+    }
+    await bulkWriter.close();
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      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.5.0",
+  "version": "1.6.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",