firestore-batch-updater 1.15.0 → 1.16.0

package/README.ko.md

@@ -31,6 +31,7 @@
 - 그룹별 개수 조회 - `countBy()`로 특정 필드 값별 문서 수 집계
 - 랜덤 샘플링 - `sample()`로 쿼리 결과에서 랜덤 문서 추출
 - 필드 값 추출 - `pluck()`로 특정 필드 값만 간단하게 배열로 추출
+- 문서 ID 추출 - `pluckIds()`로 매칭 문서의 ID만 배열로 추출
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -129,6 +130,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `distinct(field)` | 특정 필드의 고유값 조회 | `any[]` |
 | `sample(n)` | 매칭 문서에서 랜덤 샘플 추출 | `{ id, data }[]` |
 | `pluck(field)` | 특정 필드 값만 배열로 추출 | `any[]` |
+| `pluckIds()` | 매칭 문서의 ID만 배열로 추출 | `string[]` |
 | `toJSON(path, options?)` | 문서를 JSON 파일로 내보내기 | `ToJSONResult` |
 | `fromJSON(path, options?)` | JSON 파일에서 문서 가져오기 | `FromJSONResult` |
 | `countBy(field)` | 필드 값별 문서 수 집계 | `CountByResult` |
@@ -827,6 +829,32 @@ const countries = await updater.collection("users").pluck("address.country");
 // ["US", "KR", "JP", ...]
 ```
 
+### 문서 ID 추출
+
+```typescript
+// 매칭 문서의 ID만 배열로 추출
+const inactiveIds = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .pluckIds();
+console.log(inactiveIds); // ["user-1", "user-3", ...]
+
+// bulkDelete/bulkUpdate와 체이닝하여 효율적 처리
+const expiredIds = await updater
+  .collection("sessions")
+  .where("expiresAt", "<", new Date())
+  .pluckIds();
+
+await updater.collection("sessions").bulkDelete(expiredIds);
+
+// limit, orderBy와 함께 사용 가능
+const topIds = await updater
+  .collection("users")
+  .orderBy("score", "desc")
+  .limit(10)
+  .pluckIds();
+```
+
 ### 랜덤 샘플링
 
 ```typescript

package/README.md

@@ -31,6 +31,7 @@ English | [한국어](./README.ko.md)
 - Group counting - Use `countBy()` to count documents grouped by field value
 - Random sampling - Use `sample()` to get random documents from query results
 - Field value extraction - Use `pluck()` to get a simple array of field values
+- Document ID extraction - Use `pluckIds()` to get an array of matching document IDs
 - 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
@@ -129,6 +130,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `distinct(field)` | Get unique values of a field | `any[]` |
 | `sample(n)` | Get random sample of matching documents | `{ id, data }[]` |
 | `pluck(field)` | Get array of values for a specific field | `any[]` |
+| `pluckIds()` | Get array of matching document IDs | `string[]` |
 | `toJSON(path, options?)` | Export documents to JSON file | `ToJSONResult` |
 | `fromJSON(path, options?)` | Import documents from JSON file | `FromJSONResult` |
 | `countBy(field)` | Count documents grouped by field value | `CountByResult` |
@@ -840,6 +842,32 @@ const countries = await updater.collection("users").pluck("address.country");
 // ["US", "KR", "JP", ...]
 ```
 
+### Pluck Document IDs
+
+```typescript
+// Get all matching document IDs as an array
+const inactiveIds = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .pluckIds();
+console.log(inactiveIds); // ["user-1", "user-3", ...]
+
+// Chain with bulk operations for efficient workflows
+const expiredIds = await updater
+  .collection("sessions")
+  .where("expiresAt", "<", new Date())
+  .pluckIds();
+
+await updater.collection("sessions").bulkDelete(expiredIds);
+
+// Works with limit() and orderBy()
+const topIds = await updater
+  .collection("users")
+  .orderBy("score", "desc")
+  .limit(10)
+  .pluckIds();
+```
+
 ### Random Sampling
 
 ```typescript

package/dist/index.d.mts

@@ -703,6 +703,12 @@ declare class BatchUpdater {
      * @returns Array of field values (null/undefined values are excluded)
      */
     pluck(field: string): Promise<any[]>;
+    /**
+     * Get an array of document IDs from matching documents
+     * Useful for passing IDs directly to bulkUpdate(), bulkDelete(), etc.
+     * @returns Array of document IDs
+     */
+    pluckIds(): Promise<string[]>;
     /**
      * Create multiple documents in batch
      * Note: This method does not work with collectionGroup()

package/dist/index.d.ts

@@ -703,6 +703,12 @@ declare class BatchUpdater {
      * @returns Array of field values (null/undefined values are excluded)
      */
     pluck(field: string): Promise<any[]>;
+    /**
+     * Get an array of document IDs from matching documents
+     * Useful for passing IDs directly to bulkUpdate(), bulkDelete(), etc.
+     * @returns Array of document IDs
+     */
+    pluckIds(): Promise<string[]>;
     /**
      * Create multiple documents in batch
      * Note: This method does not work with collectionGroup()

package/dist/index.js

@@ -794,6 +794,17 @@ var BatchUpdater = class {
     }
     return values;
   }
+  /**
+   * Get an array of document IDs from matching documents
+   * Useful for passing IDs directly to bulkUpdate(), bulkDelete(), etc.
+   * @returns Array of document IDs
+   */
+  async pluckIds() {
+    this.validateSetup();
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    return snapshot.docs.map((doc) => doc.id);
+  }
   /**
    * Create multiple documents in batch
    * Note: This method does not work with collectionGroup()

package/dist/index.mjs

@@ -749,6 +749,17 @@ var BatchUpdater = class {
     }
     return values;
   }
+  /**
+   * Get an array of document IDs from matching documents
+   * Useful for passing IDs directly to bulkUpdate(), bulkDelete(), etc.
+   * @returns Array of document IDs
+   */
+  async pluckIds() {
+    this.validateSetup();
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    return snapshot.docs.map((doc) => doc.id);
+  }
   /**
    * Create multiple documents in batch
    * Note: This method does not work with collectionGroup()

package/package.json

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