firestore-batch-updater 1.14.0 → 1.16.0

package/README.ko.md

@@ -20,7 +20,7 @@
 - 비어있는지 확인 - `isEmpty()`로 매칭 문서가 없는지 확인 (`exists()`의 반대)
 - 전체 문서 조회 - `getAll()`로 매칭되는 모든 문서 데이터 조회
 - 집계 쿼리 - `aggregate()`로 서버 사이드 `sum`, `average`, `count` 연산
-- 간편 집계 - `sum()`과 `avg()`로 단일 필드 간편 집계
+- 간편 집계 - `sum()`, `avg()`, `min()`, `max()`로 단일 필드 간편 집계
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
@@ -31,6 +31,7 @@
 - 그룹별 개수 조회 - `countBy()`로 특정 필드 값별 문서 수 집계
 - 랜덤 샘플링 - `sample()`로 쿼리 결과에서 랜덤 문서 추출
 - 필드 값 추출 - `pluck()`로 특정 필드 값만 간단하게 배열로 추출
+- 문서 ID 추출 - `pluckIds()`로 매칭 문서의 ID만 배열로 추출
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -118,6 +119,8 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `aggregate(spec)` | sum/average/count 집계 쿼리 | `AggregateResult` |
 | `sum(field)` | 숫자 필드 합계 조회 | `number \| null` |
 | `avg(field)` | 숫자 필드 평균 조회 | `number \| null` |
+| `min(field)` | 필드 최소값 조회 | `any` |
+| `max(field)` | 필드 최대값 조회 | `any` |
 | `paginate(options)` | 커서 기반 페이지네이션 | `PaginateResult` |
 | `bulkCreate(docs, options?)` | 여러 문서를 각기 다른 데이터로 생성 | `BulkCreateResult` |
 | `bulkUpdate(updates, options?)` | 여러 문서에 각기 다른 데이터 업데이트 | `BulkUpdateResult` |
@@ -127,6 +130,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `distinct(field)` | 특정 필드의 고유값 조회 | `any[]` |
 | `sample(n)` | 매칭 문서에서 랜덤 샘플 추출 | `{ id, data }[]` |
 | `pluck(field)` | 특정 필드 값만 배열로 추출 | `any[]` |
+| `pluckIds()` | 매칭 문서의 ID만 배열로 추출 | `string[]` |
 | `toJSON(path, options?)` | 문서를 JSON 파일로 내보내기 | `ToJSONResult` |
 | `fromJSON(path, options?)` | JSON 파일에서 문서 가져오기 | `FromJSONResult` |
 | `countBy(field)` | 필드 값별 문서 수 집계 | `CountByResult` |
@@ -542,6 +546,29 @@ console.log(`평균 점수: ${avgScore}`);
 // aggregate({ avg: { op: "average", field: "score" } }) → avg("score")
 ```
 
+### 최솟값 & 최댓값
+
+```typescript
+// 필드의 최솟값/최댓값 조회
+const cheapest = await updater.collection("products").min("price");
+const mostExpensive = await updater.collection("products").max("price");
+console.log(`가격 범위: ${cheapest}원 - ${mostExpensive}원`);
+
+// 날짜/타임스탬프에도 사용 가능
+const earliestOrder = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .min("createdAt");
+
+// 매칭 문서가 없으면 null 반환
+const maxScore = await updater
+  .collection("users")
+  .where("status", "==", "nonexistent")
+  .max("score"); // null
+```
+
+> 참고: 한 필드에 `where()`를 걸고 다른 필드에 `min()/max()`를 사용할 경우 Firestore 복합 인덱스가 필요할 수 있습니다. `FAILED_PRECONDITION` 오류가 발생하면 오류 메시지의 링크를 통해 인덱스를 생성하세요.
+
 ### 커서 기반 페이지네이션
 
 ```typescript
@@ -802,6 +829,32 @@ const countries = await updater.collection("users").pluck("address.country");
 // ["US", "KR", "JP", ...]
 ```
 
+### 문서 ID 추출
+
+```typescript
+// 매칭 문서의 ID만 배열로 추출
+const inactiveIds = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .pluckIds();
+console.log(inactiveIds); // ["user-1", "user-3", ...]
+
+// bulkDelete/bulkUpdate와 체이닝하여 효율적 처리
+const expiredIds = await updater
+  .collection("sessions")
+  .where("expiresAt", "<", new Date())
+  .pluckIds();
+
+await updater.collection("sessions").bulkDelete(expiredIds);
+
+// limit, orderBy와 함께 사용 가능
+const topIds = await updater
+  .collection("users")
+  .orderBy("score", "desc")
+  .limit(10)
+  .pluckIds();
+```
+
 ### 랜덤 샘플링
 
 ```typescript

package/README.md

@@ -20,7 +20,7 @@ English | [한국어](./README.ko.md)
 - Empty check - Use `isEmpty()` to check if no matching documents exist (opposite of `exists()`)
 - Get all documents - Use `getAll()` to retrieve all matching documents with data
 - Aggregation - Use `aggregate()` for server-side `sum`, `average`, and `count` operations
-- Quick aggregation - Use `sum()` and `avg()` for simple single-field aggregation
+- Quick aggregation - Use `sum()`, `avg()`, `min()`, `max()` for simple single-field aggregation
 - Cursor pagination - Use `paginate()` for memory-efficient page-by-page iteration
 - Direct ID lookup - Use `getOne()` for fast document retrieval by ID
 - Bulk operations - Use `bulkCreate()`, `bulkUpdate()`, `bulkDelete()` for efficient multi-document operations with different data each
@@ -31,6 +31,7 @@ English | [한국어](./README.ko.md)
 - 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
+- Document ID extraction - Use `pluckIds()` to get an array of matching document IDs
 - 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
@@ -118,6 +119,8 @@ console.log(`Updated ${result.successCount} documents`);
 | `aggregate(spec)` | Run sum/average/count queries | `AggregateResult` |
 | `sum(field)` | Get sum of a numeric field | `number \| null` |
 | `avg(field)` | Get average of a numeric field | `number \| null` |
+| `min(field)` | Get minimum value of a field | `any` |
+| `max(field)` | Get maximum value of a field | `any` |
 | `paginate(options)` | Cursor-based pagination | `PaginateResult` |
 | `bulkCreate(docs, options?)` | Create multiple docs with different data | `BulkCreateResult` |
 | `bulkUpdate(updates, options?)` | Update multiple docs with different data | `BulkUpdateResult` |
@@ -127,6 +130,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `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[]` |
+| `pluckIds()` | Get array of matching document IDs | `string[]` |
 | `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` |
@@ -566,6 +570,29 @@ console.log(`Average score: ${avgScore}`);
 // aggregate({ avg: { op: "average", field: "score" } }) → avg("score")
 ```
 
+### Min & Max
+
+```typescript
+// Get the minimum/maximum value of a field
+const cheapest = await updater.collection("products").min("price");
+const mostExpensive = await updater.collection("products").max("price");
+console.log(`Price range: $${cheapest} - $${mostExpensive}`);
+
+// Works with dates/timestamps too
+const earliestOrder = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .min("createdAt");
+
+// Returns null if no documents match
+const maxScore = await updater
+  .collection("users")
+  .where("status", "==", "nonexistent")
+  .max("score"); // null
+```
+
+> Note: Combining `where()` on one field with `min()/max()` on a different field may require a Firestore composite index. If you see a `FAILED_PRECONDITION` error, follow the link in the error message to create the required index.
+
 ### Cursor-Based Pagination
 
 ```typescript
@@ -815,6 +842,32 @@ const countries = await updater.collection("users").pluck("address.country");
 // ["US", "KR", "JP", ...]
 ```
 
+### Pluck Document IDs
+
+```typescript
+// Get all matching document IDs as an array
+const inactiveIds = await updater
+  .collection("users")
+  .where("status", "==", "inactive")
+  .pluckIds();
+console.log(inactiveIds); // ["user-1", "user-3", ...]
+
+// Chain with bulk operations for efficient workflows
+const expiredIds = await updater
+  .collection("sessions")
+  .where("expiresAt", "<", new Date())
+  .pluckIds();
+
+await updater.collection("sessions").bulkDelete(expiredIds);
+
+// Works with limit() and orderBy()
+const topIds = await updater
+  .collection("users")
+  .orderBy("score", "desc")
+  .limit(10)
+  .pluckIds();
+```
+
 ### Random Sampling
 
 ```typescript

package/dist/index.d.mts

@@ -655,6 +655,20 @@ declare class BatchUpdater {
      * @returns Average of the field values, or null if no documents match
      */
     avg(field: string): Promise<number | null>;
+    /**
+     * Get the minimum value of a numeric field from matching documents
+     * Uses orderBy + limit(1) since Firestore doesn't support min/max aggregation natively
+     * @param field - Field path to find the minimum value of
+     * @returns Minimum field value, or null if no documents match
+     */
+    min(field: string): Promise<any>;
+    /**
+     * Get the maximum value of a numeric field from matching documents
+     * Uses orderBy + limit(1) since Firestore doesn't support min/max aggregation natively
+     * @param field - Field path to find the maximum value of
+     * @returns Maximum field value, or null if no documents match
+     */
+    max(field: string): Promise<any>;
     /**
      * Get documents with cursor-based pagination
      * @param options - Pagination options (pageSize, startAfter cursor)
@@ -689,6 +703,12 @@ declare class BatchUpdater {
      * @returns Array of field values (null/undefined values are excluded)
      */
     pluck(field: string): Promise<any[]>;
+    /**
+     * Get an array of document IDs from matching documents
+     * Useful for passing IDs directly to bulkUpdate(), bulkDelete(), etc.
+     * @returns Array of document IDs
+     */
+    pluckIds(): Promise<string[]>;
     /**
      * Create multiple documents in batch
      * Note: This method does not work with collectionGroup()

package/dist/index.d.ts

@@ -655,6 +655,20 @@ declare class BatchUpdater {
      * @returns Average of the field values, or null if no documents match
      */
     avg(field: string): Promise<number | null>;
+    /**
+     * Get the minimum value of a numeric field from matching documents
+     * Uses orderBy + limit(1) since Firestore doesn't support min/max aggregation natively
+     * @param field - Field path to find the minimum value of
+     * @returns Minimum field value, or null if no documents match
+     */
+    min(field: string): Promise<any>;
+    /**
+     * Get the maximum value of a numeric field from matching documents
+     * Uses orderBy + limit(1) since Firestore doesn't support min/max aggregation natively
+     * @param field - Field path to find the maximum value of
+     * @returns Maximum field value, or null if no documents match
+     */
+    max(field: string): Promise<any>;
     /**
      * Get documents with cursor-based pagination
      * @param options - Pagination options (pageSize, startAfter cursor)
@@ -689,6 +703,12 @@ declare class BatchUpdater {
      * @returns Array of field values (null/undefined values are excluded)
      */
     pluck(field: string): Promise<any[]>;
+    /**
+     * Get an array of document IDs from matching documents
+     * Useful for passing IDs directly to bulkUpdate(), bulkDelete(), etc.
+     * @returns Array of document IDs
+     */
+    pluckIds(): Promise<string[]>;
     /**
      * Create multiple documents in batch
      * Note: This method does not work with collectionGroup()

package/dist/index.js

@@ -501,6 +501,52 @@ var BatchUpdater = class {
     });
     return result._avg;
   }
+  /**
+   * Get the minimum value of a numeric field from matching documents
+   * Uses orderBy + limit(1) since Firestore doesn't support min/max aggregation natively
+   * @param field - Field path to find the minimum value of
+   * @returns Minimum field value, or null if no documents match
+   */
+  async min(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field is required for min operation");
+    }
+    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);
+    }
+    query = query.orderBy(field, "asc").limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const value = this.getNestedValue(snapshot.docs[0].data(), field);
+    return value ?? null;
+  }
+  /**
+   * Get the maximum value of a numeric field from matching documents
+   * Uses orderBy + limit(1) since Firestore doesn't support min/max aggregation natively
+   * @param field - Field path to find the maximum value of
+   * @returns Maximum field value, or null if no documents match
+   */
+  async max(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field is required for max operation");
+    }
+    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);
+    }
+    query = query.orderBy(field, "desc").limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const value = this.getNestedValue(snapshot.docs[0].data(), field);
+    return value ?? null;
+  }
   /**
    * Get documents with cursor-based pagination
    * @param options - Pagination options (pageSize, startAfter cursor)
@@ -748,6 +794,17 @@ var BatchUpdater = class {
     }
     return values;
   }
+  /**
+   * Get an array of document IDs from matching documents
+   * Useful for passing IDs directly to bulkUpdate(), bulkDelete(), etc.
+   * @returns Array of document IDs
+   */
+  async pluckIds() {
+    this.validateSetup();
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    return snapshot.docs.map((doc) => doc.id);
+  }
   /**
    * Create multiple documents in batch
    * Note: This method does not work with collectionGroup()

package/dist/index.mjs

@@ -456,6 +456,52 @@ var BatchUpdater = class {
     });
     return result._avg;
   }
+  /**
+   * Get the minimum value of a numeric field from matching documents
+   * Uses orderBy + limit(1) since Firestore doesn't support min/max aggregation natively
+   * @param field - Field path to find the minimum value of
+   * @returns Minimum field value, or null if no documents match
+   */
+  async min(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field is required for min operation");
+    }
+    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);
+    }
+    query = query.orderBy(field, "asc").limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const value = this.getNestedValue(snapshot.docs[0].data(), field);
+    return value ?? null;
+  }
+  /**
+   * Get the maximum value of a numeric field from matching documents
+   * Uses orderBy + limit(1) since Firestore doesn't support min/max aggregation natively
+   * @param field - Field path to find the maximum value of
+   * @returns Maximum field value, or null if no documents match
+   */
+  async max(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field is required for max operation");
+    }
+    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);
+    }
+    query = query.orderBy(field, "desc").limit(1);
+    const snapshot = await query.get();
+    if (snapshot.empty) {
+      return null;
+    }
+    const value = this.getNestedValue(snapshot.docs[0].data(), field);
+    return value ?? null;
+  }
   /**
    * Get documents with cursor-based pagination
    * @param options - Pagination options (pageSize, startAfter cursor)
@@ -703,6 +749,17 @@ var BatchUpdater = class {
     }
     return values;
   }
+  /**
+   * Get an array of document IDs from matching documents
+   * Useful for passing IDs directly to bulkUpdate(), bulkDelete(), etc.
+   * @returns Array of document IDs
+   */
+  async pluckIds() {
+    this.validateSetup();
+    const query = this.buildQuery();
+    const snapshot = await query.get();
+    return snapshot.docs.map((doc) => doc.id);
+  }
   /**
    * 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.14.0",
+  "version": "1.16.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",