firestore-batch-updater 1.19.0 → 1.21.0

package/README.ko.md

@@ -25,6 +25,8 @@
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
 - 문서 ID 존재 확인 - `has(id)`로 데이터 읽기 없이 특정 문서 ID 존재 여부 확인
+- 다중 ID 조회 - `pick(ids)`로 여러 문서 ID를 한 번에 효율적으로 조회
+- 처음 & 마지막 문서 - `first()` / `last()`로 정렬 기준 첫 번째/마지막 문서 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
 - 문서 변환 - `transform()`으로 각 문서에 커스텀 로직 적용 (가격 인상, 데이터 마이그레이션 등)
 - 복사 & 이동 - `copyTo()`로 컬렉션 간 문서 복사/이동 (데이터 변환 옵션 포함)
@@ -111,6 +113,9 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `findOne()` | 첫 번째 매칭 문서 조회 | `{ id, data } \| null` |
 | `getOne(id)` | ID로 문서 직접 조회 | `{ id, data } \| null` |
 | `has(id)` | 문서 ID 존재 여부 확인 | `boolean` |
+| `pick(ids)` | 여러 문서 ID로 한 번에 조회 | `{ id, data }[]` |
+| `first()` | 정렬 기준 첫 번째 문서 조회 | `{ id, data } \| null` |
+| `last()` | 정렬 기준 마지막 문서 조회 | `{ id, data } \| null` |
 | `getAll()` | 모든 매칭 문서 조회 | `{ id, data }[]` |
 | `preview(data)` | 업데이트 전 미리보기 | `PreviewResult` |
 | `update(data, options?)` | 매칭되는 문서 업데이트 | `UpdateResult` |
@@ -666,6 +671,50 @@ 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
+// 정렬 기준 첫 번째 문서 조회
+const youngest = await updater
+  .collection("users")
+  .orderBy("age", "asc")
+  .first();
+console.log(`최연소: ${youngest?.data.name}`);
+
+// 정렬 기준 마지막 문서 조회
+const oldest = await updater
+  .collection("users")
+  .orderBy("age", "asc")
+  .last();
+console.log(`최고령: ${oldest?.data.name}`);
+
+// where, select와 함께 사용
+const cheapest = await updater
+  .collection("products")
+  .where("price", ">=", 10)
+  .select("name", "price")
+  .orderBy("price", "asc")
+  .first();
+```
+
 ### 벌크 업데이트
 
 ```typescript

package/README.md

@@ -25,6 +25,8 @@ 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
+- First & Last - Use `first()` / `last()` to get the first or last document by orderBy
 - 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 +113,9 @@ 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 }[]` |
+| `first()` | Get first document by orderBy | `{ id, data } \| null` |
+| `last()` | Get last document by orderBy | `{ id, data } \| null` |
 | `getAll()` | Get all matching documents | `{ id, data }[]` |
 | `preview(data)` | Preview changes before update | `PreviewResult` |
 | `update(data, options?)` | Update matching documents | `UpdateResult` |
@@ -685,6 +690,50 @@ 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)
+```
+
+### First & Last Document
+
+```typescript
+// Get the first document (by orderBy)
+const youngest = await updater
+  .collection("users")
+  .orderBy("age", "asc")
+  .first();
+console.log(`Youngest: ${youngest?.data.name}`);
+
+// Get the last document (by orderBy)
+const oldest = await updater
+  .collection("users")
+  .orderBy("age", "asc")
+  .last();
+console.log(`Oldest: ${oldest?.data.name}`);
+
+// Works with where and select
+const cheapest = await updater
+  .collection("products")
+  .where("price", ">=", 10)
+  .select("name", "price")
+  .orderBy("price", "asc")
+  .first();
+```
+
 ### Bulk Update with Different Data
 
 ```typescript

package/dist/index.d.mts

@@ -635,6 +635,34 @@ 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>;
+    }[]>;
+    /**
+     * Get the first document based on the current orderBy conditions
+     * Requires at least one orderBy() to be set
+     * @returns First document with id and data, or null if no documents match
+     */
+    first(): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
+    /**
+     * Get the last document based on the current orderBy conditions
+     * Requires at least one orderBy() to be set
+     * Reverses the orderBy direction internally to fetch the last document efficiently
+     * @returns Last document with id and data, or null if no documents match
+     */
+    last(): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update

package/dist/index.d.ts

@@ -635,6 +635,34 @@ 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>;
+    }[]>;
+    /**
+     * Get the first document based on the current orderBy conditions
+     * Requires at least one orderBy() to be set
+     * @returns First document with id and data, or null if no documents match
+     */
+    first(): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
+    /**
+     * Get the last document based on the current orderBy conditions
+     * Requires at least one orderBy() to be set
+     * Reverses the orderBy direction internally to fetch the last document efficiently
+     * @returns Last document with id and data, or null if no documents match
+     */
+    last(): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update

package/dist/index.js

@@ -392,6 +392,80 @@ 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()
+    }));
+  }
+  /**
+   * Get the first document based on the current orderBy conditions
+   * Requires at least one orderBy() to be set
+   * @returns First document with id and data, or null if no documents match
+   */
+  async first() {
+    this.validateSetup();
+    if (this.orderByConditions.length === 0) {
+      throw new Error("first() requires at least one orderBy() condition");
+    }
+    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() };
+  }
+  /**
+   * Get the last document based on the current orderBy conditions
+   * Requires at least one orderBy() to be set
+   * Reverses the orderBy direction internally to fetch the last document efficiently
+   * @returns Last document with id and data, or null if no documents match
+   */
+  async last() {
+    this.validateSetup();
+    if (this.orderByConditions.length === 0) {
+      throw new Error("last() requires at least one orderBy() condition");
+    }
+    let query = this.isCollectionGroup ? this.firestore.collectionGroup(this.collectionPath) : this.firestore.collection(this.collectionPath);
+    for (const condition of this.conditions) {
+      query = query.where(condition.field, condition.operator, condition.value);
+    }
+    for (const orderBy of this.orderByConditions) {
+      query = query.orderBy(
+        orderBy.field,
+        orderBy.direction === "asc" ? "desc" : "asc"
+      );
+    }
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      query = query.select(...this.selectedFields);
+    }
+    query = query.limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const doc = snapshot.docs[0];
+    return { id: doc.id, data: doc.data() };
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update

package/dist/index.mjs

@@ -347,6 +347,80 @@ 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()
+    }));
+  }
+  /**
+   * Get the first document based on the current orderBy conditions
+   * Requires at least one orderBy() to be set
+   * @returns First document with id and data, or null if no documents match
+   */
+  async first() {
+    this.validateSetup();
+    if (this.orderByConditions.length === 0) {
+      throw new Error("first() requires at least one orderBy() condition");
+    }
+    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() };
+  }
+  /**
+   * Get the last document based on the current orderBy conditions
+   * Requires at least one orderBy() to be set
+   * Reverses the orderBy direction internally to fetch the last document efficiently
+   * @returns Last document with id and data, or null if no documents match
+   */
+  async last() {
+    this.validateSetup();
+    if (this.orderByConditions.length === 0) {
+      throw new Error("last() requires at least one orderBy() condition");
+    }
+    let query = this.isCollectionGroup ? this.firestore.collectionGroup(this.collectionPath) : this.firestore.collection(this.collectionPath);
+    for (const condition of this.conditions) {
+      query = query.where(condition.field, condition.operator, condition.value);
+    }
+    for (const orderBy of this.orderByConditions) {
+      query = query.orderBy(
+        orderBy.field,
+        orderBy.direction === "asc" ? "desc" : "asc"
+      );
+    }
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      query = query.select(...this.selectedFields);
+    }
+    query = query.limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const doc = snapshot.docs[0];
+    return { id: doc.id, data: doc.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.21.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",