firestore-batch-updater 1.20.0 → 1.21.0

package/README.ko.md

@@ -26,6 +26,7 @@
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
 - 문서 ID 존재 확인 - `has(id)`로 데이터 읽기 없이 특정 문서 ID 존재 여부 확인
 - 다중 ID 조회 - `pick(ids)`로 여러 문서 ID를 한 번에 효율적으로 조회
+- 처음 & 마지막 문서 - `first()` / `last()`로 정렬 기준 첫 번째/마지막 문서 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
 - 문서 변환 - `transform()`으로 각 문서에 커스텀 로직 적용 (가격 인상, 데이터 마이그레이션 등)
 - 복사 & 이동 - `copyTo()`로 컬렉션 간 문서 복사/이동 (데이터 변환 옵션 포함)
@@ -113,6 +114,8 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `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` |
@@ -686,6 +689,32 @@ const docs = await updater
 // 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

@@ -26,6 +26,7 @@ English | [한국어](./README.ko.md)
 - 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
@@ -113,6 +114,8 @@ console.log(`Updated ${result.successCount} documents`);
 | `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` |
@@ -705,6 +708,32 @@ const docs = await updater
 // 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

@@ -644,6 +644,25 @@ declare class BatchUpdater {
         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

@@ -644,6 +644,25 @@ declare class BatchUpdater {
         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

@@ -416,6 +416,56 @@ var BatchUpdater = class {
       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

@@ -371,6 +371,56 @@ var BatchUpdater = class {
       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.20.0",
+  "version": "1.21.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",