firestore-batch-updater 1.4.0 → 1.6.0

package/README.ko.md

@@ -15,9 +15,13 @@
 - 일괄 생성/Upsert/삭제 - 여러 문서를 한 번에 생성, upsert 또는 삭제
 - 정렬 및 제한 - `orderBy()`와 `limit()`으로 정밀한 제어
 - 필드 선택 - `select()`로 필요한 필드만 로드 (메모리 및 비용 절약)
-- 단일 문서 작업 - `findOne()`, `updateOne()`, `deleteOne()`으로 효율적인 단일 문서 처리
+- 단일 문서 작업 - `findOne()`, `createOne()`, `updateOne()`, `deleteOne()`으로 효율적인 단일 문서 처리
 - 존재 여부 확인 - `exists()`로 매칭 문서 존재 여부 빠르게 확인
 - 전체 문서 조회 - `getAll()`로 매칭되는 모든 문서 데이터 조회
+- 집계 쿼리 - `aggregate()`로 서버 사이드 `sum`, `average`, `count` 연산
+- 커서 페이지네이션 - `paginate()`로 메모리 효율적인 페이지 단위 조회
+- ID 직접 조회 - `getOne()`으로 문서 ID로 빠른 조회
+- 벌크 업데이트 - `bulkUpdate()`로 여러 문서에 각기 다른 데이터 업데이트
 - FieldValue 지원 - `increment()`, `arrayUnion()`, `delete()`, `serverTimestamp()` 등 사용 가능
 - 서브컬렉션 & 컬렉션 그룹 - 서브컬렉션 쿼리 또는 동일 이름의 모든 컬렉션 쿼리
 - Dry Run 모드 - 실제 변경 없이 작업 시뮬레이션
@@ -91,14 +95,19 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `count()` | 매칭되는 문서 개수 조회 | `CountResult` |
 | `exists()` | 매칭되는 문서 존재 여부 확인 | `boolean` |
 | `findOne()` | 첫 번째 매칭 문서 조회 | `{ id, data } \| null` |
+| `getOne(id)` | ID로 문서 직접 조회 | `{ id, data } \| null` |
 | `getAll()` | 모든 매칭 문서 조회 | `{ id, data }[]` |
 | `preview(data)` | 업데이트 전 미리보기 | `PreviewResult` |
 | `update(data, options?)` | 매칭되는 문서 업데이트 | `UpdateResult` |
 | `updateOne(data)` | 첫 번째 매칭 문서 업데이트 | `{ success, id }` |
 | `create(docs, options?)` | 새 문서 생성 | `CreateResult` |
+| `createOne(data, id?)` | 단일 문서 생성 | `{ success, id }` |
 | `upsert(data, options?)` | 업데이트 또는 생성 (set with merge) | `UpsertResult` |
 | `delete(options?)` | 매칭되는 문서 삭제 | `DeleteResult` |
 | `deleteOne()` | 첫 번째 매칭 문서 삭제 | `{ success, id }` |
+| `aggregate(spec)` | sum/average/count 집계 쿼리 | `AggregateResult` |
+| `paginate(options)` | 커서 기반 페이지네이션 | `PaginateResult` |
+| `bulkUpdate(updates, options?)` | 여러 문서에 각기 다른 데이터 업데이트 | `BulkUpdateResult` |
 | `getFields(field)` | 특정 필드 값 조회 | `FieldValueResult[]` |
 
 ### 옵션
@@ -146,6 +155,9 @@ console.log(`${result.successCount}개 문서 업데이트 완료`);
 | `CreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `UpsertResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `DeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
+| `AggregateResult` | `{ [alias]: number \| null }` |
+| `PaginateResult` | `docs[]`, `nextCursor`, `hasMore` |
+| `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `FieldValueResult` | `id`, `value` |
 
 ## 사용 예시
@@ -443,6 +455,123 @@ if (result.success) {
 }
 ```
 
+### 단일 문서 생성
+
+```typescript
+// 자동 생성 ID로 문서 생성
+const result = await updater
+  .collection("users")
+  .createOne({ name: "Alice", status: "active", score: 100 });
+
+console.log(`문서 생성 완료: ${result.id}`);
+
+// 커스텀 ID로 문서 생성
+const result2 = await updater
+  .collection("users")
+  .createOne({ name: "Bob", status: "active" }, "custom-bob-id");
+```
+
+### 집계 쿼리
+
+```typescript
+// 매칭 문서에 대해 sum, average, count 집계
+const stats = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .aggregate({
+    totalAmount: { op: "sum", field: "amount" },
+    avgAmount: { op: "average", field: "amount" },
+    orderCount: { op: "count" },
+  });
+
+console.log(`총액: ${stats.totalAmount}원`);
+console.log(`평균: ${stats.avgAmount}원`);
+console.log(`주문 수: ${stats.orderCount}건`);
+```
+
+### 커서 기반 페이지네이션
+
+```typescript
+// 페이지 단위로 효율적으로 문서 조회
+let nextCursor = undefined;
+
+do {
+  const page = await updater
+    .collection("users")
+    .orderBy("createdAt", "desc")
+    .paginate({ pageSize: 20, startAfter: nextCursor });
+
+  page.docs.forEach((doc) => {
+    console.log(`${doc.id}: ${doc.data.name}`);
+  });
+
+  nextCursor = page.nextCursor;
+} while (nextCursor);
+
+// select와 함께 사용하여 메모리 효율 극대화
+const page = await updater
+  .collection("users")
+  .select("name", "email")
+  .orderBy("name")
+  .paginate({ pageSize: 50 });
+```
+
+### ID로 문서 조회
+
+```typescript
+// 문서 ID로 직접 조회 (쿼리 필터 없이 가장 빠름)
+const user = await updater.collection("users").getOne("user-123");
+
+if (user) {
+  console.log(`찾음: ${user.data.name} (${user.data.email})`);
+} else {
+  console.log("사용자를 찾을 수 없음");
+}
+
+// select와 함께 사용하여 특정 필드만 가져오기
+const userBasic = await updater
+  .collection("users")
+  .select("name", "email")
+  .getOne("user-123");
+
+// 서브컬렉션에서 문서 조회
+const order = await updater
+  .collection("users/user-123/orders")
+  .getOne("order-456");
+```
+
+### 벌크 업데이트
+
+```typescript
+// 여러 문서를 각각 다른 데이터로 업데이트
+const result = await updater.collection("users").bulkUpdate([
+  { id: "user-1", data: { name: "Alice", age: 30 } },
+  { id: "user-2", data: { name: "Bob", status: "active" } },
+  { id: "user-3", data: { email: "charlie@example.com" } },
+]);
+
+console.log(`성공: ${result.successCount}, 실패: ${result.failureCount}`);
+
+// 진행 상황 콜백과 함께 사용
+const result = await updater.collection("products").bulkUpdate(
+  [
+    { id: "prod-1", data: { price: 29.99, stock: 100 } },
+    { id: "prod-2", data: { price: 49.99, stock: 50 } },
+    // ... 더 많은 업데이트
+  ],
+  {
+    onProgress: (progress) => {
+      console.log(`${progress.processedCount}/${progress.totalCount} 처리됨`);
+    },
+  }
+);
+
+// 실패 처리
+if (result.failureCount > 0) {
+  console.log("실패한 문서 ID:", result.failedDocIds);
+}
+```
+
 ### Dry Run 모드
 
 ```typescript

package/README.md

@@ -15,9 +15,13 @@ English | [한국어](./README.ko.md)
 - Batch create/upsert/delete - Create, upsert, or delete multiple documents at once
 - Sorting and limiting - Use `orderBy()` and `limit()` for precise control
 - Field selection - Use `select()` to load only needed fields (saves memory and costs)
-- Single document operations - Use `findOne()`, `updateOne()`, `deleteOne()` for efficient single-doc ops
+- Single document operations - Use `findOne()`, `createOne()`, `updateOne()`, `deleteOne()` for efficient single-doc ops
 - Existence check - Use `exists()` to quickly check if matching documents exist
 - Get all documents - Use `getAll()` to retrieve all matching documents with data
+- Aggregation - Use `aggregate()` for server-side `sum`, `average`, and `count` operations
+- Cursor pagination - Use `paginate()` for memory-efficient page-by-page iteration
+- Direct ID lookup - Use `getOne()` for fast document retrieval by ID
+- Bulk updates - Use `bulkUpdate()` to update multiple documents with different data each
 - 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
@@ -91,14 +95,19 @@ console.log(`Updated ${result.successCount} documents`);
 | `count()` | Count matching documents | `CountResult` |
 | `exists()` | Check if matching documents exist | `boolean` |
 | `findOne()` | Find first matching document | `{ id, data } \| null` |
+| `getOne(id)` | Get document by ID directly | `{ id, data } \| null` |
 | `getAll()` | Get all matching documents | `{ id, data }[]` |
 | `preview(data)` | Preview changes before update | `PreviewResult` |
 | `update(data, options?)` | Update matching documents | `UpdateResult` |
 | `updateOne(data)` | Update first matching document | `{ success, id }` |
 | `create(docs, options?)` | Create new documents | `CreateResult` |
+| `createOne(data, id?)` | Create a single document | `{ success, id }` |
 | `upsert(data, options?)` | Update or create (set with merge) | `UpsertResult` |
 | `delete(options?)` | Delete matching documents | `DeleteResult` |
 | `deleteOne()` | Delete first matching document | `{ success, id }` |
+| `aggregate(spec)` | Run sum/average/count queries | `AggregateResult` |
+| `paginate(options)` | Cursor-based pagination | `PaginateResult` |
+| `bulkUpdate(updates, options?)` | Update multiple docs with different data | `BulkUpdateResult` |
 | `getFields(field)` | Get specific field values | `FieldValueResult[]` |
 
 ### Options
@@ -146,6 +155,9 @@ All write operations support an optional `options` parameter:
 | `CreateResult` | `successCount`, `failureCount`, `totalCount`, `createdIds[]`, `failedDocIds?`, `logFilePath?` |
 | `UpsertResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `DeleteResult` | `successCount`, `failureCount`, `totalCount`, `deletedIds[]`, `failedDocIds?`, `logFilePath?` |
+| `AggregateResult` | `{ [alias]: number \| null }` |
+| `PaginateResult` | `docs[]`, `nextCursor`, `hasMore` |
+| `BulkUpdateResult` | `successCount`, `failureCount`, `totalCount`, `failedDocIds?`, `logFilePath?` |
 | `FieldValueResult` | `id`, `value` |
 
 ## Usage Examples
@@ -442,6 +454,112 @@ if (result.success) {
 }
 ```
 
+### Create Single Document
+
+```typescript
+// Create with auto-generated ID
+const result = await updater
+  .collection("users")
+  .createOne({ name: "Alice", status: "active", score: 100 });
+
+console.log(`Created document: ${result.id}`);
+
+// Create with custom ID
+const result2 = await updater
+  .collection("users")
+  .createOne({ name: "Bob", status: "active" }, "custom-bob-id");
+```
+
+### Aggregate Queries
+
+```typescript
+// Sum, average, count on matching documents
+const stats = await updater
+  .collection("orders")
+  .where("status", "==", "completed")
+  .aggregate({
+    totalAmount: { op: "sum", field: "amount" },
+    avgAmount: { op: "average", field: "amount" },
+    orderCount: { op: "count" },
+  });
+
+console.log(`Total: $${stats.totalAmount}`);
+console.log(`Average: $${stats.avgAmount}`);
+console.log(`Orders: ${stats.orderCount}`);
+```
+
+### Cursor-Based Pagination
+
+```typescript
+// Page through documents efficiently
+let nextCursor = undefined;
+
+do {
+  const page = await updater
+    .collection("users")
+    .orderBy("createdAt", "desc")
+    .paginate({ pageSize: 20, startAfter: nextCursor });
+
+  page.docs.forEach((doc) => {
+    console.log(`${doc.id}: ${doc.data.name}`);
+  });
+
+  nextCursor = page.nextCursor;
+} while (nextCursor);
+
+// Works with select for memory efficiency
+const page = await updater
+  .collection("users")
+  .select("name", "email")
+  .orderBy("name")
+  .paginate({ pageSize: 50 });
+```
+
+### Get Document by ID
+
+```typescript
+// Fast lookup when you know the document ID
+const user = await updater.collection("users").getOne("user-123");
+
+if (user) {
+  console.log(`Found: ${user.data.name}`);
+} else {
+  console.log("User not found");
+}
+
+// Works with select for field filtering
+const profile = await updater
+  .collection("users")
+  .select("name", "avatar")
+  .getOne("user-123");
+```
+
+### Bulk Update with Different Data
+
+```typescript
+// Update multiple documents with different data for each
+const result = await updater.collection("users").bulkUpdate([
+  { id: "user-1", data: { score: 100, rank: 1 } },
+  { id: "user-2", data: { score: 85, rank: 2 } },
+  { id: "user-3", data: { score: 70, rank: 3 } },
+]);
+
+console.log(`Updated ${result.successCount} documents`);
+
+// With progress tracking
+const result2 = await updater.collection("products").bulkUpdate(
+  [
+    { id: "prod-1", data: { price: 29.99, stock: 100 } },
+    { id: "prod-2", data: { price: 49.99, stock: 50 } },
+  ],
+  {
+    onProgress: (progress) => {
+      console.log(`${progress.percentage}% complete`);
+    },
+  }
+);
+```
+
 ### Dry Run Mode
 
 ```typescript

package/dist/index.d.mts

@@ -260,6 +260,78 @@ interface OperationLog {
     };
     entries: LogEntry[];
 }
+/**
+ * Result of createOne operation
+ */
+interface CreateOneResult {
+    success: boolean;
+    id: string;
+}
+/**
+ * Aggregate operation specification
+ * Each key is the alias for the result, value defines the operation
+ */
+interface AggregateSpec {
+    [alias: string]: {
+        op: "sum" | "average" | "count";
+        field?: string;
+    };
+}
+/**
+ * Result of aggregate operation
+ * Keys match the aliases from AggregateSpec
+ */
+interface AggregateResult {
+    [alias: string]: number | null;
+}
+/**
+ * Options for paginate operation
+ */
+interface PaginateOptions {
+    pageSize: number;
+    startAfter?: unknown;
+}
+/**
+ * Result of paginate operation
+ */
+interface PaginateResult {
+    docs: {
+        id: string;
+        data: Record<string, any>;
+    }[];
+    nextCursor: unknown | null;
+    hasMore: boolean;
+}
+/**
+ * Input for bulk update operation
+ */
+interface BulkUpdateInput {
+    id: string;
+    data: Record<string, any>;
+}
+/**
+ * Options for bulk update operation
+ */
+interface BulkUpdateOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+}
+/**
+ * Result of bulk update operation
+ */
+interface BulkUpdateResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
 
 /**
  * BatchUpdater - Core class for batch operations on Firestore
@@ -347,6 +419,15 @@ declare class BatchUpdater {
         id: string;
         data: Record<string, any>;
     }[]>;
+    /**
+     * Get a document by its ID directly (faster than findOne with where)
+     * @param id - Document ID
+     * @returns Document with id and data, or null if not found
+     */
+    getOne(id: string): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update
@@ -364,6 +445,28 @@ declare class BatchUpdater {
         success: boolean;
         id: string | null;
     }>;
+    /**
+     * Create a single document in the collection
+     * @param data - Document data
+     * @param id - Optional document ID (auto-generated if not provided)
+     * @returns Result with success status and document id
+     */
+    createOne(data: Record<string, any>, id?: string): Promise<{
+        success: boolean;
+        id: string;
+    }>;
+    /**
+     * Run aggregate queries (sum, average, count) on matching documents
+     * @param spec - Aggregate specification defining operations and fields
+     * @returns Object with alias keys and numeric results
+     */
+    aggregate(spec: AggregateSpec): Promise<AggregateResult>;
+    /**
+     * Get documents with cursor-based pagination
+     * @param options - Pagination options (pageSize, startAfter cursor)
+     * @returns Page of documents with cursor for next page
+     */
+    paginate(options: PaginateOptions): Promise<PaginateResult>;
     /**
      * Preview changes before executing update
      * @param updateData - Data to update
@@ -395,6 +498,15 @@ declare class BatchUpdater {
     create(documents: CreateDocumentInput[], options?: CreateOptions): Promise<CreateResult & {
         logFilePath?: string;
     }>;
+    /**
+     * Update multiple documents with different data for each
+     * @param updates - Array of { id, data } objects specifying updates for each document
+     * @param options - Bulk update options (e.g., progress callback, log options)
+     * @returns Bulk update result with success/failure counts and optional log file path
+     */
+    bulkUpdate(updates: BulkUpdateInput[], options?: BulkUpdateOptions): Promise<BulkUpdateResult & {
+        logFilePath?: string;
+    }>;
     /**
      * Upsert documents matching query conditions
      * Updates existing documents or creates them if they don't exist
@@ -490,4 +602,4 @@ declare function isValidUpdateData(value: any): value is Record<string, any>;
  */
 declare function formatError(error: unknown, context?: string): string;
 
-export { BatchUpdater, type CountResult, type CreateDocumentInput, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PreviewResult, type ProgressInfo, 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 BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };

package/dist/index.d.ts

@@ -260,6 +260,78 @@ interface OperationLog {
     };
     entries: LogEntry[];
 }
+/**
+ * Result of createOne operation
+ */
+interface CreateOneResult {
+    success: boolean;
+    id: string;
+}
+/**
+ * Aggregate operation specification
+ * Each key is the alias for the result, value defines the operation
+ */
+interface AggregateSpec {
+    [alias: string]: {
+        op: "sum" | "average" | "count";
+        field?: string;
+    };
+}
+/**
+ * Result of aggregate operation
+ * Keys match the aliases from AggregateSpec
+ */
+interface AggregateResult {
+    [alias: string]: number | null;
+}
+/**
+ * Options for paginate operation
+ */
+interface PaginateOptions {
+    pageSize: number;
+    startAfter?: unknown;
+}
+/**
+ * Result of paginate operation
+ */
+interface PaginateResult {
+    docs: {
+        id: string;
+        data: Record<string, any>;
+    }[];
+    nextCursor: unknown | null;
+    hasMore: boolean;
+}
+/**
+ * Input for bulk update operation
+ */
+interface BulkUpdateInput {
+    id: string;
+    data: Record<string, any>;
+}
+/**
+ * Options for bulk update operation
+ */
+interface BulkUpdateOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+}
+/**
+ * Result of bulk update operation
+ */
+interface BulkUpdateResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
 
 /**
  * BatchUpdater - Core class for batch operations on Firestore
@@ -347,6 +419,15 @@ declare class BatchUpdater {
         id: string;
         data: Record<string, any>;
     }[]>;
+    /**
+     * Get a document by its ID directly (faster than findOne with where)
+     * @param id - Document ID
+     * @returns Document with id and data, or null if not found
+     */
+    getOne(id: string): Promise<{
+        id: string;
+        data: Record<string, any>;
+    } | null>;
     /**
      * Update the first document matching the query conditions
      * @param updateData - Data to update
@@ -364,6 +445,28 @@ declare class BatchUpdater {
         success: boolean;
         id: string | null;
     }>;
+    /**
+     * Create a single document in the collection
+     * @param data - Document data
+     * @param id - Optional document ID (auto-generated if not provided)
+     * @returns Result with success status and document id
+     */
+    createOne(data: Record<string, any>, id?: string): Promise<{
+        success: boolean;
+        id: string;
+    }>;
+    /**
+     * Run aggregate queries (sum, average, count) on matching documents
+     * @param spec - Aggregate specification defining operations and fields
+     * @returns Object with alias keys and numeric results
+     */
+    aggregate(spec: AggregateSpec): Promise<AggregateResult>;
+    /**
+     * Get documents with cursor-based pagination
+     * @param options - Pagination options (pageSize, startAfter cursor)
+     * @returns Page of documents with cursor for next page
+     */
+    paginate(options: PaginateOptions): Promise<PaginateResult>;
     /**
      * Preview changes before executing update
      * @param updateData - Data to update
@@ -395,6 +498,15 @@ declare class BatchUpdater {
     create(documents: CreateDocumentInput[], options?: CreateOptions): Promise<CreateResult & {
         logFilePath?: string;
     }>;
+    /**
+     * Update multiple documents with different data for each
+     * @param updates - Array of { id, data } objects specifying updates for each document
+     * @param options - Bulk update options (e.g., progress callback, log options)
+     * @returns Bulk update result with success/failure counts and optional log file path
+     */
+    bulkUpdate(updates: BulkUpdateInput[], options?: BulkUpdateOptions): Promise<BulkUpdateResult & {
+        logFilePath?: string;
+    }>;
     /**
      * Upsert documents matching query conditions
      * Updates existing documents or creates them if they don't exist
@@ -490,4 +602,4 @@ declare function isValidUpdateData(value: any): value is Record<string, any>;
  */
 declare function formatError(error: unknown, context?: string): string;
 
-export { BatchUpdater, type CountResult, type CreateDocumentInput, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PreviewResult, type ProgressInfo, 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 BulkUpdateInput, type BulkUpdateOptions, type BulkUpdateResult, type CountResult, type CreateDocumentInput, type CreateOneResult, type CreateOptions, type CreateResult, type DeleteOptions, type DeleteResult, type DocumentSnapshot, type DryRunResult, type FieldValueResult, type LogEntry, type LogOptions, type OperationLog, type OrderByCondition, type PaginateOptions, type PaginateResult, type PreviewResult, type ProgressInfo, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };

package/dist/index.js

@@ -31,7 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BatchUpdater: () => BatchUpdater,
-  FieldValue: () => import_firestore.FieldValue,
+  FieldValue: () => import_firestore2.FieldValue,
   calculateProgress: () => calculateProgress,
   createLogCollector: () => createLogCollector,
   formatError: () => formatError,
@@ -43,6 +43,9 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/core/batch-updater.ts
+var import_firestore = require("firebase-admin/firestore");
+
 // src/utils/logger.ts
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
@@ -329,6 +332,38 @@ var BatchUpdater = class {
       data: doc.data()
     }));
   }
+  /**
+   * Get a document by its ID directly (faster than findOne with where)
+   * @param id - Document ID
+   * @returns Document with id and data, or null if not found
+   */
+  async getOne(id) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "getOne() cannot be used with collectionGroup(). Use findOne() with where conditions instead."
+      );
+    }
+    const docRef = this.firestore.collection(this.collectionPath).doc(id);
+    let docSnapshot;
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      const query = this.firestore.collection(this.collectionPath).where("__name__", "==", docRef).select(...this.selectedFields);
+      const snapshot = await query.get();
+      if (snapshot.empty) {
+        return null;
+      }
+      docSnapshot = snapshot.docs[0];
+    } else {
+      docSnapshot = await docRef.get();
+      if (!docSnapshot.exists) {
+        return null;
+      }
+    }
+    return {
+      id: docSnapshot.id,
+      data: docSnapshot.data()
+    };
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update
@@ -363,6 +398,95 @@ var BatchUpdater = class {
     await doc.ref.delete();
     return { success: true, id: doc.id };
   }
+  /**
+   * Create a single document in the collection
+   * @param data - Document data
+   * @param id - Optional document ID (auto-generated if not provided)
+   * @returns Result with success status and document id
+   */
+  async createOne(data, id) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "createOne() cannot be used with collectionGroup(). Use collection() with a specific path instead."
+      );
+    }
+    if (!isValidUpdateData(data)) {
+      throw new Error("Document data must be a non-empty object");
+    }
+    const collection = this.firestore.collection(this.collectionPath);
+    const docRef = id ? collection.doc(id) : collection.doc();
+    await docRef.set(data);
+    return { success: true, id: docRef.id };
+  }
+  /**
+   * Run aggregate queries (sum, average, count) on matching documents
+   * @param spec - Aggregate specification defining operations and fields
+   * @returns Object with alias keys and numeric results
+   */
+  async aggregate(spec) {
+    this.validateSetup();
+    if (!spec || Object.keys(spec).length === 0) {
+      throw new Error("Aggregate spec must be a non-empty object");
+    }
+    const query = this.buildQuery();
+    const aggregateFields = {};
+    for (const [alias, definition] of Object.entries(spec)) {
+      switch (definition.op) {
+        case "sum":
+          if (!definition.field) {
+            throw new Error(`Field is required for sum operation (alias: ${alias})`);
+          }
+          aggregateFields[alias] = import_firestore.AggregateField.sum(definition.field);
+          break;
+        case "average":
+          if (!definition.field) {
+            throw new Error(`Field is required for average operation (alias: ${alias})`);
+          }
+          aggregateFields[alias] = import_firestore.AggregateField.average(definition.field);
+          break;
+        case "count":
+          aggregateFields[alias] = import_firestore.AggregateField.count();
+          break;
+        default:
+          throw new Error(`Unknown aggregate operation: ${definition.op}`);
+      }
+    }
+    const snapshot = await query.aggregate(aggregateFields).get();
+    const data = snapshot.data();
+    const result = {};
+    for (const alias of Object.keys(spec)) {
+      result[alias] = data[alias] ?? null;
+    }
+    return result;
+  }
+  /**
+   * Get documents with cursor-based pagination
+   * @param options - Pagination options (pageSize, startAfter cursor)
+   * @returns Page of documents with cursor for next page
+   */
+  async paginate(options) {
+    this.validateSetup();
+    if (!options.pageSize || options.pageSize <= 0) {
+      throw new Error("pageSize must be a positive number");
+    }
+    let query = this.buildQuery().limit(options.pageSize + 1);
+    if (options.startAfter) {
+      query = query.startAfter(options.startAfter);
+    }
+    const snapshot = await query.get();
+    const hasMore = snapshot.docs.length > options.pageSize;
+    const docs = snapshot.docs.slice(0, options.pageSize).map((doc) => ({
+      id: doc.id,
+      data: doc.data()
+    }));
+    const lastDoc = snapshot.docs.length > 0 ? snapshot.docs[Math.min(snapshot.docs.length - 1, options.pageSize - 1)] : null;
+    return {
+      docs,
+      nextCursor: hasMore ? lastDoc : null,
+      hasMore
+    };
+  }
   /**
    * Preview changes before executing update
    * @param updateData - Data to update
@@ -629,6 +753,81 @@ var BatchUpdater = class {
     }
     return result;
   }
+  /**
+   * Update multiple documents with different data for each
+   * @param updates - Array of { id, data } objects specifying updates for each document
+   * @param options - Bulk update options (e.g., progress callback, log options)
+   * @returns Bulk update result with success/failure counts and optional log file path
+   */
+  async bulkUpdate(updates, options = {}) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "bulkUpdate() cannot be used with collectionGroup(). Use collection() with a specific path instead."
+      );
+    }
+    if (!Array.isArray(updates) || updates.length === 0) {
+      throw new Error("Updates array must be non-empty");
+    }
+    for (const update of updates) {
+      if (!update.id || typeof update.id !== "string") {
+        throw new Error("Each update must have a valid id");
+      }
+      if (!isValidUpdateData(update.data)) {
+        throw new Error("Each update must have valid data");
+      }
+    }
+    const totalCount = updates.length;
+    let successCount = 0;
+    let failureCount = 0;
+    const failedDocIds = [];
+    const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath) : null;
+    const bulkWriter = this.firestore.bulkWriter();
+    const collection = this.firestore.collection(this.collectionPath);
+    let processedCount = 0;
+    const docIdMap = /* @__PURE__ */ new Map();
+    for (const update of updates) {
+      const docRef = collection.doc(update.id);
+      docIdMap.set(docRef.path, update.id);
+    }
+    bulkWriter.onWriteResult((ref) => {
+      successCount++;
+      processedCount++;
+      const docId = docIdMap.get(ref.path) || ref.id;
+      logCollector?.addEntry(docId, "success");
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+    });
+    bulkWriter.onWriteError((error) => {
+      failureCount++;
+      processedCount++;
+      const docId = error.documentRef?.id || "unknown";
+      failedDocIds.push(docId);
+      logCollector?.addEntry(docId, "failure", error.message);
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+      return false;
+    });
+    for (const update of updates) {
+      const docRef = collection.doc(update.id);
+      bulkWriter.update(docRef, update.data);
+    }
+    await bulkWriter.close();
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
   /**
    * Upsert documents matching query conditions
    * Updates existing documents or creates them if they don't exist
@@ -973,7 +1172,7 @@ var BatchUpdater = class {
 };
 
 // src/index.ts
-var import_firestore = require("firebase-admin/firestore");
+var import_firestore2 = require("firebase-admin/firestore");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BatchUpdater,

package/dist/index.mjs

@@ -1,3 +1,6 @@
+// src/core/batch-updater.ts
+import { AggregateField } from "firebase-admin/firestore";
+
 // src/utils/logger.ts
 import * as fs from "fs";
 import * as path from "path";
@@ -284,6 +287,38 @@ var BatchUpdater = class {
       data: doc.data()
     }));
   }
+  /**
+   * Get a document by its ID directly (faster than findOne with where)
+   * @param id - Document ID
+   * @returns Document with id and data, or null if not found
+   */
+  async getOne(id) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "getOne() cannot be used with collectionGroup(). Use findOne() with where conditions instead."
+      );
+    }
+    const docRef = this.firestore.collection(this.collectionPath).doc(id);
+    let docSnapshot;
+    if (this.selectedFields && this.selectedFields.length > 0) {
+      const query = this.firestore.collection(this.collectionPath).where("__name__", "==", docRef).select(...this.selectedFields);
+      const snapshot = await query.get();
+      if (snapshot.empty) {
+        return null;
+      }
+      docSnapshot = snapshot.docs[0];
+    } else {
+      docSnapshot = await docRef.get();
+      if (!docSnapshot.exists) {
+        return null;
+      }
+    }
+    return {
+      id: docSnapshot.id,
+      data: docSnapshot.data()
+    };
+  }
   /**
    * Update the first document matching the query conditions
    * @param updateData - Data to update
@@ -318,6 +353,95 @@ var BatchUpdater = class {
     await doc.ref.delete();
     return { success: true, id: doc.id };
   }
+  /**
+   * Create a single document in the collection
+   * @param data - Document data
+   * @param id - Optional document ID (auto-generated if not provided)
+   * @returns Result with success status and document id
+   */
+  async createOne(data, id) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "createOne() cannot be used with collectionGroup(). Use collection() with a specific path instead."
+      );
+    }
+    if (!isValidUpdateData(data)) {
+      throw new Error("Document data must be a non-empty object");
+    }
+    const collection = this.firestore.collection(this.collectionPath);
+    const docRef = id ? collection.doc(id) : collection.doc();
+    await docRef.set(data);
+    return { success: true, id: docRef.id };
+  }
+  /**
+   * Run aggregate queries (sum, average, count) on matching documents
+   * @param spec - Aggregate specification defining operations and fields
+   * @returns Object with alias keys and numeric results
+   */
+  async aggregate(spec) {
+    this.validateSetup();
+    if (!spec || Object.keys(spec).length === 0) {
+      throw new Error("Aggregate spec must be a non-empty object");
+    }
+    const query = this.buildQuery();
+    const aggregateFields = {};
+    for (const [alias, definition] of Object.entries(spec)) {
+      switch (definition.op) {
+        case "sum":
+          if (!definition.field) {
+            throw new Error(`Field is required for sum operation (alias: ${alias})`);
+          }
+          aggregateFields[alias] = AggregateField.sum(definition.field);
+          break;
+        case "average":
+          if (!definition.field) {
+            throw new Error(`Field is required for average operation (alias: ${alias})`);
+          }
+          aggregateFields[alias] = AggregateField.average(definition.field);
+          break;
+        case "count":
+          aggregateFields[alias] = AggregateField.count();
+          break;
+        default:
+          throw new Error(`Unknown aggregate operation: ${definition.op}`);
+      }
+    }
+    const snapshot = await query.aggregate(aggregateFields).get();
+    const data = snapshot.data();
+    const result = {};
+    for (const alias of Object.keys(spec)) {
+      result[alias] = data[alias] ?? null;
+    }
+    return result;
+  }
+  /**
+   * Get documents with cursor-based pagination
+   * @param options - Pagination options (pageSize, startAfter cursor)
+   * @returns Page of documents with cursor for next page
+   */
+  async paginate(options) {
+    this.validateSetup();
+    if (!options.pageSize || options.pageSize <= 0) {
+      throw new Error("pageSize must be a positive number");
+    }
+    let query = this.buildQuery().limit(options.pageSize + 1);
+    if (options.startAfter) {
+      query = query.startAfter(options.startAfter);
+    }
+    const snapshot = await query.get();
+    const hasMore = snapshot.docs.length > options.pageSize;
+    const docs = snapshot.docs.slice(0, options.pageSize).map((doc) => ({
+      id: doc.id,
+      data: doc.data()
+    }));
+    const lastDoc = snapshot.docs.length > 0 ? snapshot.docs[Math.min(snapshot.docs.length - 1, options.pageSize - 1)] : null;
+    return {
+      docs,
+      nextCursor: hasMore ? lastDoc : null,
+      hasMore
+    };
+  }
   /**
    * Preview changes before executing update
    * @param updateData - Data to update
@@ -584,6 +708,81 @@ var BatchUpdater = class {
     }
     return result;
   }
+  /**
+   * Update multiple documents with different data for each
+   * @param updates - Array of { id, data } objects specifying updates for each document
+   * @param options - Bulk update options (e.g., progress callback, log options)
+   * @returns Bulk update result with success/failure counts and optional log file path
+   */
+  async bulkUpdate(updates, options = {}) {
+    this.validateSetup();
+    if (this.isCollectionGroup) {
+      throw new Error(
+        "bulkUpdate() cannot be used with collectionGroup(). Use collection() with a specific path instead."
+      );
+    }
+    if (!Array.isArray(updates) || updates.length === 0) {
+      throw new Error("Updates array must be non-empty");
+    }
+    for (const update of updates) {
+      if (!update.id || typeof update.id !== "string") {
+        throw new Error("Each update must have a valid id");
+      }
+      if (!isValidUpdateData(update.data)) {
+        throw new Error("Each update must have valid data");
+      }
+    }
+    const totalCount = updates.length;
+    let successCount = 0;
+    let failureCount = 0;
+    const failedDocIds = [];
+    const logCollector = options.log?.enabled ? createLogCollector("update", this.collectionPath) : null;
+    const bulkWriter = this.firestore.bulkWriter();
+    const collection = this.firestore.collection(this.collectionPath);
+    let processedCount = 0;
+    const docIdMap = /* @__PURE__ */ new Map();
+    for (const update of updates) {
+      const docRef = collection.doc(update.id);
+      docIdMap.set(docRef.path, update.id);
+    }
+    bulkWriter.onWriteResult((ref) => {
+      successCount++;
+      processedCount++;
+      const docId = docIdMap.get(ref.path) || ref.id;
+      logCollector?.addEntry(docId, "success");
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+    });
+    bulkWriter.onWriteError((error) => {
+      failureCount++;
+      processedCount++;
+      const docId = error.documentRef?.id || "unknown";
+      failedDocIds.push(docId);
+      logCollector?.addEntry(docId, "failure", error.message);
+      if (options.onProgress) {
+        const progress = calculateProgress(processedCount, totalCount);
+        options.onProgress(progress);
+      }
+      return false;
+    });
+    for (const update of updates) {
+      const docRef = collection.doc(update.id);
+      bulkWriter.update(docRef, update.data);
+    }
+    await bulkWriter.close();
+    const result = {
+      successCount,
+      failureCount,
+      totalCount,
+      failedDocIds: failedDocIds.length > 0 ? failedDocIds : void 0
+    };
+    if (logCollector && options.log) {
+      result.logFilePath = logCollector.finalize(options.log);
+    }
+    return result;
+  }
   /**
    * Upsert documents matching query conditions
    * Updates existing documents or creates them if they don't exist

package/package.json

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