firestore-batch-updater 1.2.0 → 1.3.0

package/README.ko.md

@@ -14,6 +14,8 @@
 - 진행 상황 추적 - 실시간 진행률 콜백
 - 일괄 생성/Upsert/삭제 - 여러 문서를 한 번에 생성, upsert 또는 삭제
 - 정렬 및 제한 - `orderBy()`와 `limit()`으로 정밀한 제어
+- 필드 선택 - `select()`로 필요한 필드만 로드 (메모리 및 비용 절약)
+- 단일 문서 조회 - `findOne()`으로 효율적인 단일 문서 검색
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -83,7 +85,9 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `where(field, op, value)` | 필터 조건 추가 (체이닝 가능) | `this` |
 | `orderBy(field, direction?)` | 정렬 추가 (체이닝 가능) | `this` |
 | `limit(count)` | 문서 수 제한 (체이닝 가능) | `this` |
+| `select(...fields)` | 특정 필드만 조회 (체이닝 가능) | `this` |
 | `count()` | 매칭되는 문서 개수 조회 | `CountResult` |
+| `findOne()` | 첫 번째 매칭 문서 조회 | `{ id, data } \| null` |
 | `preview(data)` | 업데이트 전 미리보기 | `PreviewResult` |
 | `update(data, options?)` | 매칭되는 문서 업데이트 | `UpdateResult` |
 | `create(docs, options?)` | 새 문서 생성 | `CreateResult` |
@@ -316,6 +320,50 @@ const result = await updater
 console.log(`${result.count}명의 비활성 사용자 발견`);
 ```
 
+### 특정 필드만 조회
+
+```typescript
+// name, email 필드만 로드 (메모리 및 읽기 비용 절약)
+const result = await updater
+  .collection("users")
+  .select("name", "email")
+  .where("status", "==", "active")
+  .findOne();
+
+console.log(result?.data); // { name, email }만 포함
+
+// 모든 작업에서 사용 가능 - 문서에 선택된 필드만 포함됨
+const emails = await updater
+  .collection("users")
+  .select("email")
+  .where("verified", "==", true)
+  .getFields("email");
+```
+
+### 단일 문서 조회
+
+```typescript
+// 첫 번째 매칭 문서 찾기
+const user = await updater
+  .collection("users")
+  .where("email", "==", "user@example.com")
+  .findOne();
+
+if (user) {
+  console.log("사용자 발견:", user.id);
+  console.log("사용자 데이터:", user.data);
+} else {
+  console.log("사용자를 찾을 수 없음");
+}
+
+// select와 함께 사용하여 효율적인 조회
+const profile = await updater
+  .collection("users")
+  .select("name", "avatar", "tier")
+  .where("username", "==", "johndoe")
+  .findOne();
+```
+
 ### Dry Run 모드
 
 ```typescript

package/README.md

@@ -14,6 +14,8 @@ 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
+- Field selection - Use `select()` to load only needed fields (saves memory and costs)
+- Find single document - Use `findOne()` for efficient single-document retrieval
 - FieldValue support - Use `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()`, etc.
 - Subcollection & Collection Group - Query subcollections or all collections with the same name
 - Dry run mode - Simulate operations without making changes
@@ -83,7 +85,9 @@ console.log(`Updated ${result.successCount} documents`);
 | `where(field, op, value)` | Add filter condition (chainable) | `this` |
 | `orderBy(field, direction?)` | Add sorting (chainable) | `this` |
 | `limit(count)` | Limit number of documents (chainable) | `this` |
+| `select(...fields)` | Select specific fields to retrieve (chainable) | `this` |
 | `count()` | Count matching documents | `CountResult` |
+| `findOne()` | Find first matching document | `{ id, data } \| null` |
 | `preview(data)` | Preview changes before update | `PreviewResult` |
 | `update(data, options?)` | Update matching documents | `UpdateResult` |
 | `create(docs, options?)` | Create new documents | `CreateResult` |
@@ -315,6 +319,50 @@ const result = await updater
 console.log(`Found ${result.count} inactive users`);
 ```
 
+### Select Specific Fields
+
+```typescript
+// Only load name and email fields (reduces memory and read costs)
+const result = await updater
+  .collection("users")
+  .select("name", "email")
+  .where("status", "==", "active")
+  .findOne();
+
+console.log(result?.data); // Only contains { name, email }
+
+// Works with all operations - documents will only have selected fields
+const emails = await updater
+  .collection("users")
+  .select("email")
+  .where("verified", "==", true)
+  .getFields("email");
+```
+
+### Find Single Document
+
+```typescript
+// Find first matching document
+const user = await updater
+  .collection("users")
+  .where("email", "==", "user@example.com")
+  .findOne();
+
+if (user) {
+  console.log("Found user:", user.id);
+  console.log("User data:", user.data);
+} else {
+  console.log("User not found");
+}
+
+// Combine with select for efficient lookup
+const profile = await updater
+  .collection("users")
+  .select("name", "avatar", "tier")
+  .where("username", "==", "johndoe")
+  .findOne();
+```
+
 ### Dry Run Mode
 
 ```typescript

package/dist/index.d.mts

@@ -12,6 +12,9 @@ interface ProgressInfo {
     current: number;
     total: number;
     percentage: number;
+    elapsedTime: number;
+    docsPerSecond: number;
+    eta: number;
 }
 /**
  * Options for update operations
@@ -37,6 +40,14 @@ interface UpdateOptions {
      * Returns what would happen without making any changes
      */
     dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch update operation
@@ -140,6 +151,14 @@ interface UpsertOptions {
      * Returns what would happen without making any changes
      */
     dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch upsert operation
@@ -174,6 +193,14 @@ interface DeleteOptions {
      * Returns what would happen without making any changes
      */
     dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch delete operation
@@ -248,6 +275,7 @@ declare class BatchUpdater {
     private conditions;
     private orderByConditions;
     private limitCount?;
+    private selectedFields?;
     /**
      * Create a new BatchUpdater instance
      * @param firestore - Initialized Firestore instance from firebase-admin
@@ -287,11 +315,25 @@ declare class BatchUpdater {
      * @returns This instance for chaining
      */
     limit(count: number): this;
+    /**
+     * Select specific fields to retrieve (reduces memory usage and read costs)
+     * @param fields - Field paths to retrieve
+     * @returns This instance for chaining
+     */
+    select(...fields: string[]): this;
     /**
      * Count documents matching the query conditions
      * @returns Count result with number of matching documents
      */
     count(): Promise<CountResult>;
+    /**
+     * Find the first document matching the query conditions
+     * @returns First matching document with id and data, or null if not found
+     */
+    findOne(): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Preview changes before executing update
      * @param updateData - Data to update
@@ -384,12 +426,13 @@ declare function createLogCollector(operation: "update" | "create" | "upsert" |
  */
 
 /**
- * Calculate progress information
+ * Calculate progress information with timing details
  * @param current - Number of documents processed so far
  * @param total - Total number of documents to process
- * @returns Progress information with percentage
+ * @param startTime - Start time of the operation (from Date.now())
+ * @returns Progress information with percentage, timing, and ETA
  */
-declare function calculateProgress(current: number, total: number): ProgressInfo;
+declare function calculateProgress(current: number, total: number, startTime?: number): ProgressInfo;
 /**
  * Extract field names from update data
  * @param updateData - Data to be updated

package/dist/index.d.ts

@@ -12,6 +12,9 @@ interface ProgressInfo {
     current: number;
     total: number;
     percentage: number;
+    elapsedTime: number;
+    docsPerSecond: number;
+    eta: number;
 }
 /**
  * Options for update operations
@@ -37,6 +40,14 @@ interface UpdateOptions {
      * Returns what would happen without making any changes
      */
     dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch update operation
@@ -140,6 +151,14 @@ interface UpsertOptions {
      * Returns what would happen without making any changes
      */
     dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch upsert operation
@@ -174,6 +193,14 @@ interface DeleteOptions {
      * Returns what would happen without making any changes
      */
     dryRun?: boolean;
+    /**
+     * Maximum number of retry attempts for failed operations (default: 0)
+     */
+    retries?: number;
+    /**
+     * Delay between retry attempts in milliseconds (default: 1000)
+     */
+    retryDelay?: number;
 }
 /**
  * Result of batch delete operation
@@ -248,6 +275,7 @@ declare class BatchUpdater {
     private conditions;
     private orderByConditions;
     private limitCount?;
+    private selectedFields?;
     /**
      * Create a new BatchUpdater instance
      * @param firestore - Initialized Firestore instance from firebase-admin
@@ -287,11 +315,25 @@ declare class BatchUpdater {
      * @returns This instance for chaining
      */
     limit(count: number): this;
+    /**
+     * Select specific fields to retrieve (reduces memory usage and read costs)
+     * @param fields - Field paths to retrieve
+     * @returns This instance for chaining
+     */
+    select(...fields: string[]): this;
     /**
      * Count documents matching the query conditions
      * @returns Count result with number of matching documents
      */
     count(): Promise<CountResult>;
+    /**
+     * Find the first document matching the query conditions
+     * @returns First matching document with id and data, or null if not found
+     */
+    findOne(): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Preview changes before executing update
      * @param updateData - Data to update
@@ -384,12 +426,13 @@ declare function createLogCollector(operation: "update" | "create" | "upsert" |
  */
 
 /**
- * Calculate progress information
+ * Calculate progress information with timing details
  * @param current - Number of documents processed so far
  * @param total - Total number of documents to process
- * @returns Progress information with percentage
+ * @param startTime - Start time of the operation (from Date.now())
+ * @returns Progress information with percentage, timing, and ETA
  */
-declare function calculateProgress(current: number, total: number): ProgressInfo;
+declare function calculateProgress(current: number, total: number, startTime?: number): ProgressInfo;
 /**
  * Extract field names from update data
  * @param updateData - Data to be updated

package/dist/index.js

@@ -164,12 +164,20 @@ function createLogCollector(operation, collection, conditions, updateData) {
 }
 
 // src/utils/index.ts
-function calculateProgress(current, total) {
+function calculateProgress(current, total, startTime) {
   const percentage = total === 0 ? 0 : Math.round(current / total * 100);
+  const now = Date.now();
+  const elapsedTime = startTime ? now - startTime : 0;
+  const docsPerSecond = elapsedTime > 0 ? Math.round(current / elapsedTime * 1e3 * 100) / 100 : 0;
+  const remaining = total - current;
+  const eta = docsPerSecond > 0 ? Math.round(remaining / docsPerSecond * 100) / 100 : 0;
   return {
     current,
     total,
-    percentage
+    percentage,
+    elapsedTime,
+    docsPerSecond,
+    eta
   };
 }
 function getAffectedFields(updateData) {
@@ -213,6 +221,7 @@ var BatchUpdater = class {
     this.conditions = [];
     this.orderByConditions = [];
     this.limitCount = void 0;
+    this.selectedFields = void 0;
     return this;
   }
   /**
@@ -226,6 +235,7 @@ var BatchUpdater = class {
     this.conditions = [];
     this.orderByConditions = [];
     this.limitCount = void 0;
+    this.selectedFields = void 0;
     return this;
   }
   /**
@@ -258,6 +268,15 @@ var BatchUpdater = class {
     this.limitCount = count;
     return this;
   }
+  /**
+   * Select specific fields to retrieve (reduces memory usage and read costs)
+   * @param fields - Field paths to retrieve
+   * @returns This instance for chaining
+   */
+  select(...fields) {
+    this.selectedFields = fields;
+    return this;
+  }
   /**
    * Count documents matching the query conditions
    * @returns Count result with number of matching documents
@@ -270,6 +289,23 @@ var BatchUpdater = class {
       count: snapshot.data().count
     };
   }
+  /**
+   * Find the first document matching the query conditions
+   * @returns First matching document with id and data, or null if not found
+   */
+  async findOne() {
+    this.validateSetup();
+    const query = this.buildQuery().limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const doc = snapshot.docs[0];
+    return {
+      id: doc.id,
+      data: doc.data()
+    };
+  }
   /**
    * Preview changes before executing update
    * @param updateData - Data to update
@@ -857,6 +893,9 @@ var BatchUpdater = class {
     if (this.limitCount !== void 0 && this.limitCount > 0) {
       query = query.limit(this.limitCount);
     }
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      query = query.select(...this.selectedFields);
+    }
     return query;
   }
   /**

package/dist/index.mjs

@@ -119,12 +119,20 @@ function createLogCollector(operation, collection, conditions, updateData) {
 }
 
 // src/utils/index.ts
-function calculateProgress(current, total) {
+function calculateProgress(current, total, startTime) {
   const percentage = total === 0 ? 0 : Math.round(current / total * 100);
+  const now = Date.now();
+  const elapsedTime = startTime ? now - startTime : 0;
+  const docsPerSecond = elapsedTime > 0 ? Math.round(current / elapsedTime * 1e3 * 100) / 100 : 0;
+  const remaining = total - current;
+  const eta = docsPerSecond > 0 ? Math.round(remaining / docsPerSecond * 100) / 100 : 0;
   return {
     current,
     total,
-    percentage
+    percentage,
+    elapsedTime,
+    docsPerSecond,
+    eta
   };
 }
 function getAffectedFields(updateData) {
@@ -168,6 +176,7 @@ var BatchUpdater = class {
     this.conditions = [];
     this.orderByConditions = [];
     this.limitCount = void 0;
+    this.selectedFields = void 0;
     return this;
   }
   /**
@@ -181,6 +190,7 @@ var BatchUpdater = class {
     this.conditions = [];
     this.orderByConditions = [];
     this.limitCount = void 0;
+    this.selectedFields = void 0;
     return this;
   }
   /**
@@ -213,6 +223,15 @@ var BatchUpdater = class {
     this.limitCount = count;
     return this;
   }
+  /**
+   * Select specific fields to retrieve (reduces memory usage and read costs)
+   * @param fields - Field paths to retrieve
+   * @returns This instance for chaining
+   */
+  select(...fields) {
+    this.selectedFields = fields;
+    return this;
+  }
   /**
    * Count documents matching the query conditions
    * @returns Count result with number of matching documents
@@ -225,6 +244,23 @@ var BatchUpdater = class {
       count: snapshot.data().count
     };
   }
+  /**
+   * Find the first document matching the query conditions
+   * @returns First matching document with id and data, or null if not found
+   */
+  async findOne() {
+    this.validateSetup();
+    const query = this.buildQuery().limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const doc = snapshot.docs[0];
+    return {
+      id: doc.id,
+      data: doc.data()
+    };
+  }
   /**
    * Preview changes before executing update
    * @param updateData - Data to update
@@ -812,6 +848,9 @@ var BatchUpdater = class {
     if (this.limitCount !== void 0 && this.limitCount > 0) {
       query = query.limit(this.limitCount);
     }
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      query = query.select(...this.selectedFields);
+    }
     return query;
   }
   /**

package/package.json

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