firestore-batch-updater 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,316 @@
+import { WhereFilterOp, Firestore } from 'firebase-admin/firestore';
+
+/**
+ * Firestore Batch Updater Type Definitions
+ */
+
+/**
+ * Progress information during batch operations
+ */
+interface ProgressInfo {
+    current: number;
+    total: number;
+    percentage: number;
+}
+/**
+ * Options for update operations
+ */
+interface UpdateOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+    /**
+     * Batch size for pagination (optional)
+     * When set, documents are processed in batches to prevent memory issues with large collections
+     * When not set, all documents are loaded at once
+     */
+    batchSize?: number;
+}
+/**
+ * Result of batch update operation
+ */
+interface UpdateResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
+/**
+ * Document snapshot showing before/after state
+ */
+interface DocumentSnapshot {
+    id: string;
+    before: Record<string, any>;
+    after: Record<string, any>;
+}
+/**
+ * Preview result before executing update
+ */
+interface PreviewResult {
+    affectedCount: number;
+    samples: DocumentSnapshot[];
+    affectedFields: string[];
+}
+/**
+ * Where clause condition
+ */
+interface WhereCondition {
+    field: string;
+    operator: WhereFilterOp;
+    value: any;
+}
+/**
+ * Field value result
+ */
+interface FieldValue {
+    id: string;
+    value: any;
+}
+/**
+ * Input for creating a single document
+ */
+interface CreateDocumentInput {
+    id?: string;
+    data: Record<string, any>;
+}
+/**
+ * Options for create operations
+ */
+interface CreateOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+}
+/**
+ * Result of batch create operation
+ */
+interface CreateResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    createdIds: string[];
+    failedDocIds?: string[];
+}
+/**
+ * Options for upsert operations
+ */
+interface UpsertOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+    /**
+     * Batch size for pagination (optional)
+     * When set, documents are processed in batches to prevent memory issues with large collections
+     * When not set, all documents are loaded at once
+     */
+    batchSize?: number;
+}
+/**
+ * Result of batch upsert operation
+ */
+interface UpsertResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
+/**
+ * Log options for batch operations
+ */
+interface LogOptions {
+    enabled: boolean;
+    path?: string;
+    filename?: string;
+}
+/**
+ * Log entry for a single document operation
+ */
+interface LogEntry {
+    timestamp: string;
+    documentId: string;
+    status: "success" | "failure";
+    error?: string;
+}
+/**
+ * Complete log data for an operation
+ */
+interface OperationLog {
+    operation: "update" | "create" | "upsert";
+    collection: string;
+    startedAt: string;
+    completedAt: string;
+    conditions?: WhereCondition[];
+    updateData?: Record<string, any>;
+    summary: {
+        totalCount: number;
+        successCount: number;
+        failureCount: number;
+    };
+    entries: LogEntry[];
+}
+
+/**
+ * BatchUpdater - Core class for batch operations on Firestore
+ */
+
+/**
+ * BatchUpdater class for efficient batch operations
+ */
+declare class BatchUpdater {
+    private firestore;
+    private collectionPath?;
+    private conditions;
+    /**
+     * Create a new BatchUpdater instance
+     * @param firestore - Initialized Firestore instance from firebase-admin
+     */
+    constructor(firestore: Firestore);
+    /**
+     * Select a collection to operate on
+     * @param path - Collection path
+     * @returns This instance for chaining
+     */
+    collection(path: string): this;
+    /**
+     * Add a where condition to filter documents
+     * @param field - Field path
+     * @param operator - Comparison operator
+     * @param value - Value to compare
+     * @returns This instance for chaining
+     */
+    where(field: string, operator: WhereFilterOp, value: any): this;
+    /**
+     * Preview changes before executing update
+     * @param updateData - Data to update
+     * @returns Preview result with affected count and samples
+     */
+    preview(updateData: Record<string, any>): Promise<PreviewResult>;
+    /**
+     * Execute batch update operation
+     * @param updateData - Data to update
+     * @param options - Update options (e.g., progress callback, log options, batchSize for pagination)
+     * @returns Update result with success/failure counts and optional log file path
+     */
+    update(updateData: Record<string, any>, options?: UpdateOptions): Promise<UpdateResult & {
+        logFilePath?: string;
+    }>;
+    /**
+     * Get specific field values from matching documents
+     * @param fieldPath - Field path to retrieve
+     * @returns Array of field values with document IDs
+     */
+    getFields(fieldPath: string): Promise<FieldValue[]>;
+    /**
+     * Create multiple documents in batch
+     * @param documents - Array of documents to create
+     * @param options - Create options (e.g., progress callback, log options)
+     * @returns Create result with success/failure counts, created IDs, and optional log file path
+     */
+    create(documents: CreateDocumentInput[], options?: CreateOptions): Promise<CreateResult & {
+        logFilePath?: string;
+    }>;
+    /**
+     * Upsert documents matching query conditions
+     * Updates existing documents or creates them if they don't exist
+     * @param updateData - Data to set/merge
+     * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination)
+     * @returns Upsert result with success/failure counts and optional log file path
+     */
+    upsert(updateData: Record<string, any>, options?: UpsertOptions): Promise<UpsertResult & {
+        logFilePath?: string;
+    }>;
+    /**
+     * Validate that collection is set
+     * @private
+     */
+    private validateSetup;
+    /**
+     * Build Firestore query with all conditions
+     * @private
+     */
+    private buildQuery;
+    /**
+     * Get nested value from object using dot notation
+     * @private
+     */
+    private getNestedValue;
+}
+
+/**
+ * Logger utility for Firestore Batch Updater
+ */
+
+/**
+ * Format operation log to string
+ */
+declare function formatOperationLog(log: OperationLog): string;
+/**
+ * Write operation log to file
+ */
+declare function writeOperationLog(log: OperationLog, options: LogOptions): string;
+/**
+ * Create a log collector for tracking operation entries
+ */
+declare function createLogCollector(operation: "update" | "create" | "upsert", collection: string, conditions?: WhereCondition[], updateData?: Record<string, any>): {
+    addEntry: (documentId: string, status: "success" | "failure", error?: string) => void;
+    finalize: (options: LogOptions) => string;
+    getLog: () => OperationLog;
+};
+
+/**
+ * Utility functions for Firestore Batch Updater
+ */
+
+/**
+ * Calculate progress information
+ * @param current - Number of documents processed so far
+ * @param total - Total number of documents to process
+ * @returns Progress information with percentage
+ */
+declare function calculateProgress(current: number, total: number): ProgressInfo;
+/**
+ * Extract field names from update data
+ * @param updateData - Data to be updated
+ * @returns Array of field names that will be affected
+ */
+declare function getAffectedFields(updateData: Record<string, any>): string[];
+/**
+ * Merge update data with existing document data
+ * @param existingData - Current document data
+ * @param updateData - Data to update
+ * @returns Merged data (shallow merge)
+ */
+declare function mergeUpdateData(existingData: Record<string, any>, updateData: Record<string, any>): Record<string, any>;
+/**
+ * Check if a value is a valid update data object
+ * @param value - Value to check
+ * @returns True if value is a valid update data object
+ */
+declare function isValidUpdateData(value: any): value is Record<string, any>;
+/**
+ * Format error message for failed operations
+ * @param error - Error object
+ * @param context - Additional context (e.g., document ID)
+ * @returns Formatted error message
+ */
+declare function formatError(error: unknown, context?: string): string;
+
+export { BatchUpdater, type CreateDocumentInput, type CreateOptions, type CreateResult, type DocumentSnapshot, type FieldValue, type LogEntry, type LogOptions, type OperationLog, 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

@@ -0,0 +1,316 @@
+import { WhereFilterOp, Firestore } from 'firebase-admin/firestore';
+
+/**
+ * Firestore Batch Updater Type Definitions
+ */
+
+/**
+ * Progress information during batch operations
+ */
+interface ProgressInfo {
+    current: number;
+    total: number;
+    percentage: number;
+}
+/**
+ * Options for update operations
+ */
+interface UpdateOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+    /**
+     * Batch size for pagination (optional)
+     * When set, documents are processed in batches to prevent memory issues with large collections
+     * When not set, all documents are loaded at once
+     */
+    batchSize?: number;
+}
+/**
+ * Result of batch update operation
+ */
+interface UpdateResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
+/**
+ * Document snapshot showing before/after state
+ */
+interface DocumentSnapshot {
+    id: string;
+    before: Record<string, any>;
+    after: Record<string, any>;
+}
+/**
+ * Preview result before executing update
+ */
+interface PreviewResult {
+    affectedCount: number;
+    samples: DocumentSnapshot[];
+    affectedFields: string[];
+}
+/**
+ * Where clause condition
+ */
+interface WhereCondition {
+    field: string;
+    operator: WhereFilterOp;
+    value: any;
+}
+/**
+ * Field value result
+ */
+interface FieldValue {
+    id: string;
+    value: any;
+}
+/**
+ * Input for creating a single document
+ */
+interface CreateDocumentInput {
+    id?: string;
+    data: Record<string, any>;
+}
+/**
+ * Options for create operations
+ */
+interface CreateOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+}
+/**
+ * Result of batch create operation
+ */
+interface CreateResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    createdIds: string[];
+    failedDocIds?: string[];
+}
+/**
+ * Options for upsert operations
+ */
+interface UpsertOptions {
+    /**
+     * Callback function for progress updates
+     * @param progress - Current progress information
+     */
+    onProgress?: (progress: ProgressInfo) => void;
+    /**
+     * Log file generation options
+     */
+    log?: LogOptions;
+    /**
+     * Batch size for pagination (optional)
+     * When set, documents are processed in batches to prevent memory issues with large collections
+     * When not set, all documents are loaded at once
+     */
+    batchSize?: number;
+}
+/**
+ * Result of batch upsert operation
+ */
+interface UpsertResult {
+    successCount: number;
+    failureCount: number;
+    totalCount: number;
+    failedDocIds?: string[];
+}
+/**
+ * Log options for batch operations
+ */
+interface LogOptions {
+    enabled: boolean;
+    path?: string;
+    filename?: string;
+}
+/**
+ * Log entry for a single document operation
+ */
+interface LogEntry {
+    timestamp: string;
+    documentId: string;
+    status: "success" | "failure";
+    error?: string;
+}
+/**
+ * Complete log data for an operation
+ */
+interface OperationLog {
+    operation: "update" | "create" | "upsert";
+    collection: string;
+    startedAt: string;
+    completedAt: string;
+    conditions?: WhereCondition[];
+    updateData?: Record<string, any>;
+    summary: {
+        totalCount: number;
+        successCount: number;
+        failureCount: number;
+    };
+    entries: LogEntry[];
+}
+
+/**
+ * BatchUpdater - Core class for batch operations on Firestore
+ */
+
+/**
+ * BatchUpdater class for efficient batch operations
+ */
+declare class BatchUpdater {
+    private firestore;
+    private collectionPath?;
+    private conditions;
+    /**
+     * Create a new BatchUpdater instance
+     * @param firestore - Initialized Firestore instance from firebase-admin
+     */
+    constructor(firestore: Firestore);
+    /**
+     * Select a collection to operate on
+     * @param path - Collection path
+     * @returns This instance for chaining
+     */
+    collection(path: string): this;
+    /**
+     * Add a where condition to filter documents
+     * @param field - Field path
+     * @param operator - Comparison operator
+     * @param value - Value to compare
+     * @returns This instance for chaining
+     */
+    where(field: string, operator: WhereFilterOp, value: any): this;
+    /**
+     * Preview changes before executing update
+     * @param updateData - Data to update
+     * @returns Preview result with affected count and samples
+     */
+    preview(updateData: Record<string, any>): Promise<PreviewResult>;
+    /**
+     * Execute batch update operation
+     * @param updateData - Data to update
+     * @param options - Update options (e.g., progress callback, log options, batchSize for pagination)
+     * @returns Update result with success/failure counts and optional log file path
+     */
+    update(updateData: Record<string, any>, options?: UpdateOptions): Promise<UpdateResult & {
+        logFilePath?: string;
+    }>;
+    /**
+     * Get specific field values from matching documents
+     * @param fieldPath - Field path to retrieve
+     * @returns Array of field values with document IDs
+     */
+    getFields(fieldPath: string): Promise<FieldValue[]>;
+    /**
+     * Create multiple documents in batch
+     * @param documents - Array of documents to create
+     * @param options - Create options (e.g., progress callback, log options)
+     * @returns Create result with success/failure counts, created IDs, and optional log file path
+     */
+    create(documents: CreateDocumentInput[], options?: CreateOptions): Promise<CreateResult & {
+        logFilePath?: string;
+    }>;
+    /**
+     * Upsert documents matching query conditions
+     * Updates existing documents or creates them if they don't exist
+     * @param updateData - Data to set/merge
+     * @param options - Upsert options (e.g., progress callback, log options, batchSize for pagination)
+     * @returns Upsert result with success/failure counts and optional log file path
+     */
+    upsert(updateData: Record<string, any>, options?: UpsertOptions): Promise<UpsertResult & {
+        logFilePath?: string;
+    }>;
+    /**
+     * Validate that collection is set
+     * @private
+     */
+    private validateSetup;
+    /**
+     * Build Firestore query with all conditions
+     * @private
+     */
+    private buildQuery;
+    /**
+     * Get nested value from object using dot notation
+     * @private
+     */
+    private getNestedValue;
+}
+
+/**
+ * Logger utility for Firestore Batch Updater
+ */
+
+/**
+ * Format operation log to string
+ */
+declare function formatOperationLog(log: OperationLog): string;
+/**
+ * Write operation log to file
+ */
+declare function writeOperationLog(log: OperationLog, options: LogOptions): string;
+/**
+ * Create a log collector for tracking operation entries
+ */
+declare function createLogCollector(operation: "update" | "create" | "upsert", collection: string, conditions?: WhereCondition[], updateData?: Record<string, any>): {
+    addEntry: (documentId: string, status: "success" | "failure", error?: string) => void;
+    finalize: (options: LogOptions) => string;
+    getLog: () => OperationLog;
+};
+
+/**
+ * Utility functions for Firestore Batch Updater
+ */
+
+/**
+ * Calculate progress information
+ * @param current - Number of documents processed so far
+ * @param total - Total number of documents to process
+ * @returns Progress information with percentage
+ */
+declare function calculateProgress(current: number, total: number): ProgressInfo;
+/**
+ * Extract field names from update data
+ * @param updateData - Data to be updated
+ * @returns Array of field names that will be affected
+ */
+declare function getAffectedFields(updateData: Record<string, any>): string[];
+/**
+ * Merge update data with existing document data
+ * @param existingData - Current document data
+ * @param updateData - Data to update
+ * @returns Merged data (shallow merge)
+ */
+declare function mergeUpdateData(existingData: Record<string, any>, updateData: Record<string, any>): Record<string, any>;
+/**
+ * Check if a value is a valid update data object
+ * @param value - Value to check
+ * @returns True if value is a valid update data object
+ */
+declare function isValidUpdateData(value: any): value is Record<string, any>;
+/**
+ * Format error message for failed operations
+ * @param error - Error object
+ * @param context - Additional context (e.g., document ID)
+ * @returns Formatted error message
+ */
+declare function formatError(error: unknown, context?: string): string;
+
+export { BatchUpdater, type CreateDocumentInput, type CreateOptions, type CreateResult, type DocumentSnapshot, type FieldValue, type LogEntry, type LogOptions, type OperationLog, type PreviewResult, type ProgressInfo, type UpdateOptions, type UpdateResult, type UpsertOptions, type UpsertResult, type WhereCondition, calculateProgress, createLogCollector, formatError, formatOperationLog, getAffectedFields, isValidUpdateData, mergeUpdateData, writeOperationLog };