firestore-batch-updater 1.16.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()`로 여러 문서에 각기 다른 데이터로 효율적 처리
@@ -121,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` |
@@ -182,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?` |
@@ -569,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

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
@@ -121,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` |
@@ -182,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?` |
@@ -593,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

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)
@@ -897,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)
@@ -897,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)

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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firestore-batch-updater",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Batch update Firestore documents with query-based filtering and preview",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",