firestore-batch-updater 1.13.0 → 1.14.0

package/README.ko.md

@@ -30,6 +30,7 @@
 - JSON 내보내기/가져오기 - `toJSON()` / `fromJSON()`으로 문서 JSON 파일 내보내기/가져오기
 - 그룹별 개수 조회 - `countBy()`로 특정 필드 값별 문서 수 집계
 - 랜덤 샘플링 - `sample()`로 쿼리 결과에서 랜덤 문서 추출
+- 필드 값 추출 - `pluck()`로 특정 필드 값만 간단하게 배열로 추출
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -125,6 +126,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `copyTo(target, options?)` | 다른 컬렉션으로 문서 복사/이동 | `CopyToResult` |
 | `distinct(field)` | 특정 필드의 고유값 조회 | `any[]` |
 | `sample(n)` | 매칭 문서에서 랜덤 샘플 추출 | `{ id, data }[]` |
+| `pluck(field)` | 특정 필드 값만 배열로 추출 | `any[]` |
 | `toJSON(path, options?)` | 문서를 JSON 파일로 내보내기 | `ToJSONResult` |
 | `fromJSON(path, options?)` | JSON 파일에서 문서 가져오기 | `FromJSONResult` |
 | `countBy(field)` | 필드 값별 문서 수 집계 | `CountByResult` |
@@ -781,6 +783,25 @@ await updater.collection("users").toJSON("./backup.json");
 await updater.collection("users_backup").fromJSON("./backup.json");
 ```
 
+### 필드 값 추출
+
+```typescript
+// 이메일 값만 간단한 배열로 추출
+const emails = await updater
+  .collection("users")
+  .where("status", "==", "active")
+  .pluck("email");
+console.log(emails); // ["alice@test.com", "bob@test.com", ...]
+
+// 가격 값 추출 후 계산
+const prices = await updater.collection("products").pluck("price");
+const total = prices.reduce((sum, p) => sum + p, 0);
+
+// 중첩 필드 지원
+const countries = await updater.collection("users").pluck("address.country");
+// ["US", "KR", "JP", ...]
+```
+
 ### 랜덤 샘플링
 
 ```typescript

package/README.md

@@ -30,6 +30,7 @@ English | [한국어](./README.ko.md)
 - JSON export/import - Use `toJSON()` / `fromJSON()` to export/import documents as JSON
 - 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
 - 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
@@ -125,6 +126,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `copyTo(target, options?)` | Copy/move docs to another collection | `CopyToResult` |
 | `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[]` |
 | `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` |
@@ -794,6 +796,25 @@ await updater.collection("users").toJSON("./backup.json");
 await updater.collection("users_backup").fromJSON("./backup.json");
 ```
 
+### Pluck Field Values
+
+```typescript
+// Get just the email values as a simple array
+const emails = await updater
+  .collection("users")
+  .where("status", "==", "active")
+  .pluck("email");
+console.log(emails); // ["alice@test.com", "bob@test.com", ...]
+
+// Get prices for calculation
+const prices = await updater.collection("products").pluck("price");
+const total = prices.reduce((sum, p) => sum + p, 0);
+
+// Nested field support
+const countries = await updater.collection("users").pluck("address.country");
+// ["US", "KR", "JP", ...]
+```
+
 ### Random Sampling
 
 ```typescript

package/dist/index.d.mts

@@ -682,6 +682,13 @@ declare class BatchUpdater {
      * @returns Array of field values with document IDs
      */
     getFields(fieldPath: string): Promise<FieldValueResult[]>;
+    /**
+     * Get an array of values for a specific field from matching documents
+     * Convenience wrapper around getFields() that returns only values (no IDs)
+     * @param field - Field path to extract values from
+     * @returns Array of field values (null/undefined values are excluded)
+     */
+    pluck(field: string): Promise<any[]>;
     /**
      * Create multiple documents in batch
      * Note: This method does not work with collectionGroup()

package/dist/index.d.ts

@@ -682,6 +682,13 @@ declare class BatchUpdater {
      * @returns Array of field values with document IDs
      */
     getFields(fieldPath: string): Promise<FieldValueResult[]>;
+    /**
+     * Get an array of values for a specific field from matching documents
+     * Convenience wrapper around getFields() that returns only values (no IDs)
+     * @param field - Field path to extract values from
+     * @returns Array of field values (null/undefined values are excluded)
+     */
+    pluck(field: string): Promise<any[]>;
     /**
      * Create multiple documents in batch
      * Note: This method does not work with collectionGroup()

package/dist/index.js

@@ -726,6 +726,28 @@ var BatchUpdater = class {
     }
     return results;
   }
+  /**
+   * Get an array of values for a specific field from matching documents
+   * Convenience wrapper around getFields() that returns only values (no IDs)
+   * @param field - Field path to extract values from
+   * @returns Array of field values (null/undefined values are excluded)
+   */
+  async pluck(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field path is required");
+    }
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    const values = [];
+    for (const doc of snapshot.docs) {
+      const value = this.getNestedValue(doc.data(), field);
+      if (value !== void 0 && value !== null) {
+        values.push(value);
+      }
+    }
+    return values;
+  }
   /**
    * Create multiple documents in batch
    * Note: This method does not work with collectionGroup()

package/dist/index.mjs

@@ -681,6 +681,28 @@ var BatchUpdater = class {
     }
     return results;
   }
+  /**
+   * Get an array of values for a specific field from matching documents
+   * Convenience wrapper around getFields() that returns only values (no IDs)
+   * @param field - Field path to extract values from
+   * @returns Array of field values (null/undefined values are excluded)
+   */
+  async pluck(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field path is required");
+    }
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    const values = [];
+    for (const doc of snapshot.docs) {
+      const value = this.getNestedValue(doc.data(), field);
+      if (value !== void 0 && value !== null) {
+        values.push(value);
+      }
+    }
+    return values;
+  }
   /**
    * 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.13.0",
+  "version": "1.14.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",