firestore-batch-updater 1.18.0 → 1.20.0

package/README.ko.md

@@ -24,6 +24,8 @@
 - 통합 통계 - `fieldStats()`로 sum/avg/min/max/count 한 번에 조회
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
+- 문서 ID 존재 확인 - `has(id)`로 데이터 읽기 없이 특정 문서 ID 존재 여부 확인
+- 다중 ID 조회 - `pick(ids)`로 여러 문서 ID를 한 번에 효율적으로 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
 - 문서 변환 - `transform()`으로 각 문서에 커스텀 로직 적용 (가격 인상, 데이터 마이그레이션 등)
 - 복사 & 이동 - `copyTo()`로 컬렉션 간 문서 복사/이동 (데이터 변환 옵션 포함)
@@ -109,6 +111,8 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `isEmpty()` | 매칭되는 문서가 없는지 확인 | `boolean` |
 | `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` |
@@ -646,6 +650,42 @@ const order = await updater
   .getOne("order-456");
 ```
 
+### 문서 ID 존재 확인
+
+```typescript
+// 특정 문서 ID가 존재하는지 확인 (데이터 읽기 없이 효율적)
+const exists = await updater.collection("users").has("user-123");
+
+if (exists) {
+  console.log("사용자가 존재합니다!");
+} else {
+  console.log("사용자를 찾을 수 없음");
+}
+
+// 가드 절에 유용
+if (!(await updater.collection("users").has(userId))) {
+  throw new Error("사용자를 찾을 수 없습니다");
+}
+```
+
+### 여러 문서 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

@@ -24,6 +24,8 @@ English | [한국어](./README.ko.md)
 - Combined stats - Use `fieldStats()` to get sum/avg/min/max/count in one call
 - 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
@@ -109,6 +111,8 @@ console.log(`Updated ${result.successCount} documents`);
 | `isEmpty()` | Check if no matching documents exist | `boolean` |
 | `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` |
@@ -665,6 +669,42 @@ const profile = await updater
   .getOne("user-123");
 ```
 
+### Check Document Exists by ID
+
+```typescript
+// Check if a specific document ID exists (without reading data)
+const exists = await updater.collection("users").has("user-123");
+
+if (exists) {
+  console.log("User exists!");
+} else {
+  console.log("User not found");
+}
+
+// Useful for guard clauses before operations
+if (!(await updater.collection("users").has(userId))) {
+  throw new Error("User not found");
+}
+```
+
+### 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

@@ -629,6 +629,21 @@ declare class BatchUpdater {
         id: string;
         data: Record<string, any>;
     } | null>;
+    /**
+     * Check if a document with the given ID exists in the collection
+     * @param id - Document ID to check
+     * @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

@@ -629,6 +629,21 @@ declare class BatchUpdater {
         id: string;
         data: Record<string, any>;
     } | null>;
+    /**
+     * Check if a document with the given ID exists in the collection
+     * @param id - Document ID to check
+     * @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

@@ -373,6 +373,49 @@ var BatchUpdater = class {
       data: docSnapshot.data()
     };
   }
+  /**
+   * Check if a document with the given ID exists in the collection
+   * @param id - Document ID to check
+   * @returns true if the document exists, false otherwise
+   */
+  async has(id) {
+    this.validateSetup();
+    if (!id || typeof id !== "string") {
+      throw new Error("Document ID is required");
+    }
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "has() cannot be used with collectionGroup(). Use exists() with where conditions instead."
+      );
+    }
+    const docRef = this.firestore.collection(this.collectionPath).doc(id);
+    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

@@ -328,6 +328,49 @@ var BatchUpdater = class {
       data: docSnapshot.data()
     };
   }
+  /**
+   * Check if a document with the given ID exists in the collection
+   * @param id - Document ID to check
+   * @returns true if the document exists, false otherwise
+   */
+  async has(id) {
+    this.validateSetup();
+    if (!id || typeof id !== "string") {
+      throw new Error("Document ID is required");
+    }
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "has() cannot be used with collectionGroup(). Use exists() with where conditions instead."
+      );
+    }
+    const docRef = this.firestore.collection(this.collectionPath).doc(id);
+    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.18.0",
+  "version": "1.20.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",