firestore-batch-updater 1.15.0 → 1.17.0

package/README.ko.md

@@ -21,6 +21,7 @@
 - 전체 문서 조회 - `getAll()`로 매칭되는 모든 문서 데이터 조회
 - 집계 쿼리 - `aggregate()`로 서버 사이드 `sum`, `average`, `count` 연산
 - 간편 집계 - `sum()`, `avg()`, `min()`, `max()`로 단일 필드 간편 집계
+- 통합 통계 - `fieldStats()`로 sum/avg/min/max/count 한 번에 조회
 - 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
 - ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
 - 벌크 작업 - `bulkCreate()`, `bulkUpdate()`, `bulkDelete()`로 여러 문서에 각기 다른 데이터로 효율적 처리
@@ -31,6 +32,7 @@
 - 그룹별 개수 조회 - `countBy()`로 특정 필드 값별 문서 수 집계
 - 랜덤 샘플링 - `sample()`로 쿼리 결과에서 랜덤 문서 추출
 - 필드 값 추출 - `pluck()`로 특정 필드 값만 간단하게 배열로 추출
+- 문서 ID 추출 - `pluckIds()`로 매칭 문서의 ID만 배열로 추출
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -120,6 +122,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `avg(field)` | 숫자 필드 평균 조회 | `number \| null` |
 | `min(field)` | 필드 최소값 조회 | `any` |
 | `max(field)` | 필드 최대값 조회 | `any` |
+| `fieldStats(field)` | sum/avg/min/max/count 한 번에 조회 | `FieldStatsResult` |
 | `paginate(options)` | 커서 기반 페이지네이션 | `PaginateResult` |
 | `bulkCreate(docs, options?)` | 여러 문서를 각기 다른 데이터로 생성 | `BulkCreateResult` |
 | `bulkUpdate(updates, options?)` | 여러 문서에 각기 다른 데이터 업데이트 | `BulkUpdateResult` |
@@ -129,6 +132,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` |
@@ -180,6 +184,7 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `UpsertResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `DeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
 | `AggregateResult` | `{ [alias]: number \| null }` |
+| `FieldStatsResult` | `sum`, `avg`, `min`, `max`, `count` |
 | `PaginateResult` | `docs[]`, `nextCursor`, `hasMore` |
 | `BulkCreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
@@ -567,6 +572,26 @@ const maxScore = await updater
 
 > 참고: 한 필드에 `where()`를 걸고 다른 필드에 `min()/max()`를 사용할 경우 Firestore 복합 인덱스가 필요할 수 있습니다. `FAILED_PRECONDITION` 오류가 발생하면 오류 메시지의 링크를 통해 인덱스를 생성하세요.
 
+### 통합 필드 통계
+
+```typescript
+// 한 필드의 sum, avg, min, max, count를 한 번에 조회
+const stats = await updater.collection("products").fieldStats("price");
+console.log(stats);
+// { sum: 12500, avg: 250, min: 50, max: 500, count: 50 }
+
+// 대시보드에서 유용
+const orderStats = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .fieldStats("amount");
+
+console.log(`총 매출: ${orderStats.sum}원`);
+console.log(`평균 주문액: ${orderStats.avg}원`);
+console.log(`주문 수: ${orderStats.count}건`);
+console.log(`범위: ${orderStats.min}원 - ${orderStats.max}원`);
+```
+
 ### 커서 기반 페이지네이션
 
 ```typescript
@@ -827,6 +852,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

@@ -21,6 +21,7 @@ English | [한국어](./README.ko.md)
 - 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()`, `avg()`, `min()`, `max()` for simple single-field aggregation
+- 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
 - Bulk operations - Use `bulkCreate()`, `bulkUpdate()`, `bulkDelete()` for efficient multi-document operations with different data each
@@ -31,6 +32,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
@@ -120,6 +122,7 @@ console.log(`Updated ${result.successCount} documents`);
 | `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` |
+| `fieldStats(field)` | Get sum/avg/min/max/count for a field in one call | `FieldStatsResult` |
 | `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` |
@@ -129,6 +132,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` |
@@ -180,6 +184,7 @@ All write operations support an optional `options` parameter:
 | `UpsertResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `DeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
 | `AggregateResult` | `{ [alias]: number \| null }` |
+| `FieldStatsResult` | `sum`, `avg`, `min`, `max`, `count` |
 | `PaginateResult` | `docs[]`, `nextCursor`, `hasMore` |
 | `BulkCreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
@@ -591,6 +596,26 @@ const maxScore = await updater
 
 > 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.
 
+### Combined Field Stats
+
+```typescript
+// Get sum, avg, min, max, count for a single field in one call
+const stats = await updater.collection("products").fieldStats("price");
+console.log(stats);
+// { sum: 12500, avg: 250, min: 50, max: 500, count: 50 }
+
+// Useful for dashboards
+const orderStats = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .fieldStats("amount");
+
+console.log(`Total revenue: $${orderStats.sum}`);
+console.log(`Average order: $${orderStats.avg}`);
+console.log(`Order count: ${orderStats.count}`);
+console.log(`Range: $${orderStats.min} - $${orderStats.max}`);
+```
+
 ### Cursor-Based Pagination
 
 ```typescript
@@ -840,6 +865,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

@@ -455,6 +455,17 @@ interface CopyToResult {
     copiedIds: string[];
     failedDocIds?: string[];
 }
+/**
+ * Result of fieldStats operation
+ * Combined statistics for a single field
+ */
+interface FieldStatsResult {
+    sum: number | null;
+    avg: number | null;
+    min: any;
+    max: any;
+    count: number;
+}
 /**
  * Result of countBy operation
  */
@@ -669,6 +680,13 @@ declare class BatchUpdater {
      * @returns Maximum field value, or null if no documents match
      */
     max(field: string): Promise<any>;
+    /**
+     * Get combined statistics (sum, avg, min, max, count) for a single field
+     * Convenience method that runs aggregate + min + max in parallel
+     * @param field - Field path to compute statistics for
+     * @returns Object with sum, avg, min, max, count
+     */
+    fieldStats(field: string): Promise<FieldStatsResult>;
     /**
      * Get documents with cursor-based pagination
      * @param options - Pagination options (pageSize, startAfter cursor)
@@ -703,6 +721,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()
@@ -891,4 +915,4 @@ declare function isValidUpdateData(value: any): value is Record<string, any>;
  */
 declare function formatError(error: unknown, context?: string): string;
 
-export { type AggregateResult, type AggregateSpec, BatchUpdater, type BulkCreateInput, type BulkCreateOptions, type BulkCreateResult, type BulkDeleteOptions, type BulkDeleteResult, type BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CopyToOptions, type CopyToResult, type CountByResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type FromJSONOptions, type FromJSONResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type ToJSONOptions, type ToJSONResult, type TransformFn, type TransformOptions, type TransformResult, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };
+export { type AggregateResult, type AggregateSpec, BatchUpdater, type BulkCreateInput, type BulkCreateOptions, type BulkCreateResult, type BulkDeleteOptions, type BulkDeleteResult, type BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CopyToOptions, type CopyToResult, type CountByResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldStatsResult, type FieldValueResult, type FromJSONOptions, type FromJSONResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type ToJSONOptions, type ToJSONResult, type TransformFn, type TransformOptions, type TransformResult, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };

package/dist/index.d.ts

@@ -455,6 +455,17 @@ interface CopyToResult {
     copiedIds: string[];
     failedDocIds?: string[];
 }
+/**
+ * Result of fieldStats operation
+ * Combined statistics for a single field
+ */
+interface FieldStatsResult {
+    sum: number | null;
+    avg: number | null;
+    min: any;
+    max: any;
+    count: number;
+}
 /**
  * Result of countBy operation
  */
@@ -669,6 +680,13 @@ declare class BatchUpdater {
      * @returns Maximum field value, or null if no documents match
      */
     max(field: string): Promise<any>;
+    /**
+     * Get combined statistics (sum, avg, min, max, count) for a single field
+     * Convenience method that runs aggregate + min + max in parallel
+     * @param field - Field path to compute statistics for
+     * @returns Object with sum, avg, min, max, count
+     */
+    fieldStats(field: string): Promise<FieldStatsResult>;
     /**
      * Get documents with cursor-based pagination
      * @param options - Pagination options (pageSize, startAfter cursor)
@@ -703,6 +721,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()
@@ -891,4 +915,4 @@ declare function isValidUpdateData(value: any): value is Record<string, any>;
  */
 declare function formatError(error: unknown, context?: string): string;
 
-export { type AggregateResult, type AggregateSpec, BatchUpdater, type BulkCreateInput, type BulkCreateOptions, type BulkCreateResult, type BulkDeleteOptions, type BulkDeleteResult, type BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CopyToOptions, type CopyToResult, type CountByResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type FromJSONOptions, type FromJSONResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type ToJSONOptions, type ToJSONResult, type TransformFn, type TransformOptions, type TransformResult, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };
+export { type AggregateResult, type AggregateSpec, BatchUpdater, type BulkCreateInput, type BulkCreateOptions, type BulkCreateResult, type BulkDeleteOptions, type BulkDeleteResult, type BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CopyToOptions, type CopyToResult, type CountByResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldStatsResult, type FieldValueResult, type FromJSONOptions, type FromJSONResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type ToJSONOptions, type ToJSONResult, type TransformFn, type TransformOptions, type TransformResult, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };

package/dist/index.js

@@ -547,6 +547,34 @@ var BatchUpdater = class {
     const value = this.getNestedValue(snapshot.docs[0].data(), field);
     return value ?? null;
   }
+  /**
+   * Get combined statistics (sum, avg, min, max, count) for a single field
+   * Convenience method that runs aggregate + min + max in parallel
+   * @param field - Field path to compute statistics for
+   * @returns Object with sum, avg, min, max, count
+   */
+  async fieldStats(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field is required for fieldStats operation");
+    }
+    const [aggResult, minVal, maxVal] = await Promise.all([
+      this.aggregate({
+        _sum: { op: "sum", field },
+        _avg: { op: "average", field },
+        _count: { op: "count" }
+      }),
+      this.min(field),
+      this.max(field)
+    ]);
+    return {
+      sum: aggResult._sum,
+      avg: aggResult._avg,
+      min: minVal,
+      max: maxVal,
+      count: aggResult._count ?? 0
+    };
+  }
   /**
    * Get documents with cursor-based pagination
    * @param options - Pagination options (pageSize, startAfter cursor)
@@ -794,6 +822,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

@@ -502,6 +502,34 @@ var BatchUpdater = class {
     const value = this.getNestedValue(snapshot.docs[0].data(), field);
     return value ?? null;
   }
+  /**
+   * Get combined statistics (sum, avg, min, max, count) for a single field
+   * Convenience method that runs aggregate + min + max in parallel
+   * @param field - Field path to compute statistics for
+   * @returns Object with sum, avg, min, max, count
+   */
+  async fieldStats(field) {
+    this.validateSetup();
+    if (!field || typeof field !== "string") {
+      throw new Error("Field is required for fieldStats operation");
+    }
+    const [aggResult, minVal, maxVal] = await Promise.all([
+      this.aggregate({
+        _sum: { op: "sum", field },
+        _avg: { op: "average", field },
+        _count: { op: "count" }
+      }),
+      this.min(field),
+      this.max(field)
+    ]);
+    return {
+      sum: aggResult._sum,
+      avg: aggResult._avg,
+      min: minVal,
+      max: maxVal,
+      count: aggResult._count ?? 0
+    };
+  }
   /**
    * Get documents with cursor-based pagination
    * @param options - Pagination options (pageSize, startAfter cursor)
@@ -749,6 +777,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.15.0",
+  "version": "1.17.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",