firestore-batch-updater 1.19.0 → 1.20.0

package/README.ko.md

@@ -25,6 +25,7 @@
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
 - 문서 ID 존재 확인 - `has(id)`로 데이터 읽기 없이 특정 문서 ID 존재 여부 확인
+- 다중 ID 조회 - `pick(ids)`로 여러 문서 ID를 한 번에 효율적으로 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
 - 문서 변환 - `transform()`으로 각 문서에 커스텀 로직 적용 (가격 인상, 데이터 마이그레이션 등)
 - 복사 & 이동 - `copyTo()`로 컬렉션 간 문서 복사/이동 (데이터 변환 옵션 포함)
@@ -111,6 +112,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `findOne()` | 첫 번째 매칭 문서 조회 | `{ id, data } \| null` |
 | `getOne(id)` | ID로 문서 직접 조회 | `{ id, data } \| null` |
 | `has(id)` | 문서 ID 존재 여부 확인 | `boolean` |
+| `pick(ids)` | 여러 문서 ID로 한 번에 조회 | `{ id, data }[]` |
 | `getAll()` | 모든 매칭 문서 조회 | `{ id, data }[]` |
 | `preview(data)` | 업데이트 전 미리보기 | `PreviewResult` |
 | `update(data, options?)` | 매칭되는 문서 업데이트 | `UpdateResult` |
@@ -666,6 +668,24 @@ if (!(await updater.collection("users").has(userId))) {
 }
 ```
 
+### 여러 문서 ID로 조회
+
+```typescript
+// 여러 문서를 한 번에 조회 (getOne() 여러 번 호출보다 효율적)
+const users = await updater
+  .collection("users")
+  .pick(["user-1", "user-2", "user-3"]);
+
+console.log(`${users.length}명 조회됨`);
+users.forEach((u) => console.log(`${u.id}: ${u.data.name}`));
+
+// 존재하지 않는 ID는 자동으로 건너뜀
+const docs = await updater
+  .collection("products")
+  .pick(["prod-1", "non-existent", "prod-3"]);
+// prod-1, prod-3만 반환 (존재하는 경우)
+```
+
 ### 벌크 업데이트
 
 ```typescript

package/README.md

@@ -25,6 +25,7 @@ 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
 - Document ID check - Use `has(id)` to check if a specific document ID exists without reading data
+- Multi-ID lookup - Use `pick(ids)` to get multiple documents by IDs in a single efficient call
 - 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
@@ -111,6 +112,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `findOne()` | Find first matching document | `{ id, data } \| null` |
 | `getOne(id)` | Get document by ID directly | `{ id, data } \| null` |
 | `has(id)` | Check if document ID exists | `boolean` |
+| `pick(ids)` | Get multiple documents by IDs | `{ id, data }[]` |
 | `getAll()` | Get all matching documents | `{ id, data }[]` |
 | `preview(data)` | Preview changes before update | `PreviewResult` |
 | `update(data, options?)` | Update matching documents | `UpdateResult` |
@@ -685,6 +687,24 @@ if (!(await updater.collection("users").has(userId))) {
 }
 ```
 
+### Get Multiple Documents by IDs
+
+```typescript
+// Get multiple documents in a single call (more efficient than multiple getOne)
+const users = await updater
+  .collection("users")
+  .pick(["user-1", "user-2", "user-3"]);
+
+console.log(`Found ${users.length} users`);
+users.forEach((u) => console.log(`${u.id}: ${u.data.name}`));
+
+// Non-existent IDs are silently skipped
+const docs = await updater
+  .collection("products")
+  .pick(["prod-1", "non-existent", "prod-3"]);
+// Returns only prod-1 and prod-3 (if they exist)
+```
+
 ### Bulk Update with Different Data
 
 ```typescript

package/dist/index.d.mts

@@ -635,6 +635,15 @@ declare class BatchUpdater {
      * @returns true if the document exists, false otherwise
      */
     has(id: string): Promise<boolean>;
+    /**
+     * Get multiple documents by their IDs in a single call
+     * @param ids - Array of document IDs to retrieve
+     * @returns Array of documents with id and data (skips non-existent documents)
+     */
+    pick(ids: string[]): Promise<{
+        id: string;
+        data: Record<string, any>;
+    }[]>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update

package/dist/index.d.ts

@@ -635,6 +635,15 @@ declare class BatchUpdater {
      * @returns true if the document exists, false otherwise
      */
     has(id: string): Promise<boolean>;
+    /**
+     * Get multiple documents by their IDs in a single call
+     * @param ids - Array of document IDs to retrieve
+     * @returns Array of documents with id and data (skips non-existent documents)
+     */
+    pick(ids: string[]): Promise<{
+        id: string;
+        data: Record<string, any>;
+    }[]>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update

package/dist/index.js

@@ -392,6 +392,30 @@ var BatchUpdater = class {
     const docSnapshot = await docRef.get();
     return docSnapshot.exists;
   }
+  /**
+   * Get multiple documents by their IDs in a single call
+   * @param ids - Array of document IDs to retrieve
+   * @returns Array of documents with id and data (skips non-existent documents)
+   */
+  async pick(ids) {
+    this.validateSetup();
+    if (!Array.isArray(ids) || ids.length === 0) {
+      throw new Error("Document IDs array is required and must not be empty");
+    }
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "pick() cannot be used with collectionGroup(). Use getAll() with where conditions instead."
+      );
+    }
+    const docRefs = ids.map(
+      (id) => this.firestore.collection(this.collectionPath).doc(id)
+    );
+    const snapshots = await this.firestore.getAll(...docRefs);
+    return snapshots.filter((snap) => snap.exists).map((snap) => ({
+      id: snap.id,
+      data: snap.data()
+    }));
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update

package/dist/index.mjs

@@ -347,6 +347,30 @@ var BatchUpdater = class {
     const docSnapshot = await docRef.get();
     return docSnapshot.exists;
   }
+  /**
+   * Get multiple documents by their IDs in a single call
+   * @param ids - Array of document IDs to retrieve
+   * @returns Array of documents with id and data (skips non-existent documents)
+   */
+  async pick(ids) {
+    this.validateSetup();
+    if (!Array.isArray(ids) || ids.length === 0) {
+      throw new Error("Document IDs array is required and must not be empty");
+    }
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "pick() cannot be used with collectionGroup(). Use getAll() with where conditions instead."
+      );
+    }
+    const docRefs = ids.map(
+      (id) => this.firestore.collection(this.collectionPath).doc(id)
+    );
+    const snapshots = await this.firestore.getAll(...docRefs);
+    return snapshots.filter((snap) => snap.exists).map((snap) => ({
+      id: snap.id,
+      data: snap.data()
+    }));
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update

package/package.json

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