svelte-firekit 0.0.25 → 0.1.1

package/dist/services/mutations.js

@@ -0,0 +1,1079 @@
+/**
+ * @fileoverview FirekitDocumentMutations - Optimized document mutation service for Svelte
+ * @module FirekitDocumentMutations
+ * @version 1.0.0
+ */
+import { addDoc, setDoc, updateDoc, deleteDoc, doc, getDoc, collection, serverTimestamp, increment, arrayUnion, arrayRemove, deleteField, writeBatch, runTransaction } from 'firebase/firestore';
+import { firebaseService } from '../firebase.js';
+import { firekitUser } from './user.svelte.js';
+import { MutationOperationType, MutationErrorCode, MutationError } from '../types/mutations.js';
+import { CacheSource } from '../types/document.js';
+/**
+ * Comprehensive Firestore document mutation service with advanced features.
+ * Handles CRUD operations, batch processing, validation, error handling, and analytics.
+ *
+ * @class FirekitDocumentMutations
+ * @example
+ * ```typescript
+ * import { firekitDocMutations } from 'svelte-firekit';
+ *
+ * // Add a new document
+ * const result = await firekitDocMutations.add('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * }, {
+ *   timestamps: true,
+ *   validate: true
+ * });
+ *
+ * // Batch operations
+ * const batchResult = await firekitDocMutations.batch([
+ *   { type: 'create', path: 'users', data: userData },
+ *   { type: 'update', path: 'profiles/123', data: profileUpdate }
+ * ]);
+ *
+ * // Listen to mutation events
+ * const unsubscribe = firekitDocMutations.addEventListener((event) => {
+ *   console.log('Mutation event:', event.type, event.data);
+ * });
+ * ```
+ */
+class FirekitDocumentMutations {
+    eventListeners = new Set();
+    analytics = this.initializeAnalytics();
+    defaultOptions = {
+        timestamps: true,
+        merge: false,
+        validate: false,
+        optimistic: false,
+        retry: {
+            enabled: true,
+            maxAttempts: 3,
+            baseDelay: 1000,
+            strategy: 'exponential'
+        }
+    };
+    /**
+     * Initialize analytics object
+     */
+    initializeAnalytics() {
+        return {
+            totalMutations: 0,
+            successfulMutations: 0,
+            failedMutations: 0,
+            successRate: 0,
+            averageDuration: 0,
+            commonErrors: [],
+            performanceByOperation: {},
+            retryStats: {
+                totalRetries: 0,
+                retriesPerMutation: 0,
+                retrySuccessRate: 0
+            }
+        };
+    }
+    /**
+     * Generate timestamp data for document mutations
+     */
+    getTimestampData(isNew = true) {
+        const timestamps = {
+            updatedAt: serverTimestamp(),
+            updatedBy: firekitUser.uid || 'anonymous'
+        };
+        if (isNew) {
+            timestamps.createdAt = serverTimestamp();
+            timestamps.createdBy = firekitUser.uid || 'anonymous';
+        }
+        return timestamps;
+    }
+    /**
+     * Validate data using custom validator or basic validation
+     */
+    validateData(data, validator) {
+        if (validator) {
+            return validator(data);
+        }
+        // Basic validation
+        if (!data || typeof data !== 'object') {
+            return {
+                valid: false,
+                message: 'Data must be a valid object'
+            };
+        }
+        // Check for null/undefined values in top-level fields
+        const invalidFields = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (value === null || value === undefined) {
+                invalidFields[key] = 'Field cannot be null or undefined';
+            }
+        }
+        if (Object.keys(invalidFields).length > 0) {
+            return {
+                valid: false,
+                message: 'Some fields contain invalid values',
+                fieldErrors: invalidFields
+            };
+        }
+        return { valid: true };
+    }
+    /**
+     * Handle and format mutation errors
+     */
+    handleError(error, operation, path) {
+        let mutationError;
+        if (error instanceof MutationError) {
+            mutationError = error;
+        }
+        else {
+            // Map Firestore errors to MutationError
+            const code = this.mapFirestoreErrorCode(error.code);
+            mutationError = new MutationError(code, error.message || 'An unknown error occurred', operation, path, error);
+        }
+        // Update analytics
+        this.analytics.failedMutations++;
+        this.updateErrorAnalytics(mutationError);
+        // Emit error event
+        this.emitEvent({
+            type: 'mutation_error',
+            error: mutationError,
+            timestamp: new Date(),
+            userId: firekitUser.uid ?? 'anonymous'
+        });
+        console.error('FirekitDocumentMutations error:', mutationError);
+        return mutationError;
+    }
+    /**
+     * Map Firestore error codes to MutationErrorCode
+     */
+    mapFirestoreErrorCode(firestoreCode) {
+        switch (firestoreCode) {
+            case 'permission-denied':
+                return MutationErrorCode.PERMISSION_DENIED;
+            case 'not-found':
+                return MutationErrorCode.NOT_FOUND;
+            case 'already-exists':
+                return MutationErrorCode.ALREADY_EXISTS;
+            case 'failed-precondition':
+                return MutationErrorCode.FAILED_PRECONDITION;
+            case 'aborted':
+                return MutationErrorCode.ABORTED;
+            case 'out-of-range':
+                return MutationErrorCode.OUT_OF_RANGE;
+            case 'unimplemented':
+                return MutationErrorCode.UNIMPLEMENTED;
+            case 'internal':
+                return MutationErrorCode.INTERNAL_ERROR;
+            case 'unavailable':
+                return MutationErrorCode.UNAVAILABLE;
+            case 'deadline-exceeded':
+                return MutationErrorCode.DEADLINE_EXCEEDED;
+            case 'unauthenticated':
+                return MutationErrorCode.UNAUTHENTICATED;
+            case 'resource-exhausted':
+                return MutationErrorCode.RESOURCE_EXHAUSTED;
+            case 'cancelled':
+                return MutationErrorCode.CANCELLED;
+            default:
+                return MutationErrorCode.UNKNOWN;
+        }
+    }
+    /**
+     * Update error analytics
+     */
+    updateErrorAnalytics(error) {
+        const existingError = this.analytics.commonErrors.find((e) => e.code === error.code);
+        if (existingError) {
+            existingError.count++;
+        }
+        else {
+            this.analytics.commonErrors.push({
+                code: error.code,
+                count: 1,
+                percentage: 0
+            });
+        }
+        // Recalculate percentages
+        const totalErrors = this.analytics.commonErrors.reduce((sum, e) => sum + e.count, 0);
+        this.analytics.commonErrors.forEach((e) => {
+            e.percentage = (e.count / totalErrors) * 100;
+        });
+        // Sort by count
+        this.analytics.commonErrors.sort((a, b) => b.count - a.count);
+    }
+    /**
+     * Emit event to all listeners
+     */
+    emitEvent(event) {
+        this.eventListeners.forEach((callback) => {
+            try {
+                callback(event);
+            }
+            catch (error) {
+                console.error('Error in mutation event listener:', error);
+            }
+        });
+    }
+    /**
+     * Execute operation with retry logic
+     */
+    async executeWithRetry(operation, options, operationName, path) {
+        const retryConfig = { ...this.defaultOptions.retry, ...options.retry };
+        let lastError;
+        let attempt = 0;
+        while (attempt < retryConfig.maxAttempts) {
+            try {
+                if (attempt > 0) {
+                    this.emitEvent({
+                        type: 'mutation_retry',
+                        data: { attempt, maxAttempts: retryConfig.maxAttempts, operation: operationName, path },
+                        timestamp: new Date(),
+                        userId: firekitUser.uid ?? 'anonymous'
+                    });
+                    this.analytics.retryStats.totalRetries++;
+                }
+                const result = await operation();
+                if (attempt > 0) {
+                    // Successful retry
+                    this.analytics.retryStats.retrySuccessRate =
+                        (this.analytics.retryStats.retrySuccessRate + 1) / 2;
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = this.handleError(error, operationName, path);
+                if (!lastError.isRetryable() ||
+                    (retryConfig.shouldRetry && !retryConfig.shouldRetry(lastError, attempt))) {
+                    break;
+                }
+                attempt++;
+                if (attempt < retryConfig.maxAttempts) {
+                    const delay = retryConfig.strategy === 'exponential'
+                        ? Math.min(retryConfig.baseDelay * Math.pow(2, attempt), retryConfig.maxDelay || 30000)
+                        : retryConfig.baseDelay;
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+            }
+        }
+        throw lastError;
+    }
+    // ========================================
+    // CRUD OPERATIONS
+    // ========================================
+    /**
+     * Add a new document to a collection
+     *
+     * @template T Document data type
+     * @param collectionPath Collection path
+     * @param data Document data
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.add('users', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }, {
+     *   timestamps: true,
+     *   customId: 'custom-user-id',
+     *   validate: true
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Created document:', result.id);
+     * }
+     * ```
+     */
+    async add(collectionPath, data, options = {}) {
+        const startTime = Date.now();
+        const mergedOptions = { ...this.defaultOptions, ...options };
+        try {
+            // Emit start event
+            this.emitEvent({
+                type: 'mutation_start',
+                data: { operation: 'create', path: collectionPath, data },
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            // Validate data if requested
+            if (mergedOptions.validate) {
+                const validation = this.validateData(data, mergedOptions.validator);
+                if (!validation.valid) {
+                    throw new MutationError(MutationErrorCode.VALIDATION_FAILED, validation.message || 'Validation failed', MutationOperationType.CREATE, collectionPath, null, { fieldErrors: validation.fieldErrors });
+                }
+            }
+            const result = await this.executeWithRetry(async () => {
+                const firestore = firebaseService.getDbInstance();
+                if (!firestore) {
+                    throw new MutationError(MutationErrorCode.SERVICE_UNAVAILABLE, 'Firestore service not available');
+                }
+                const colRef = collection(firestore, collectionPath);
+                let dataToAdd = {
+                    ...data,
+                    ...(mergedOptions.timestamps && this.getTimestampData())
+                };
+                let docRef;
+                if (mergedOptions.customId) {
+                    docRef = doc(colRef, mergedOptions.customId);
+                    dataToAdd = { ...dataToAdd, id: docRef.id };
+                    await setDoc(docRef, dataToAdd);
+                }
+                else {
+                    docRef = (await addDoc(colRef, dataToAdd));
+                    dataToAdd = { ...dataToAdd, id: docRef.id };
+                    await setDoc(docRef, dataToAdd);
+                }
+                return {
+                    success: true,
+                    id: docRef.id,
+                    data: { ...dataToAdd, id: docRef.id },
+                    metadata: {
+                        timestamp: new Date(),
+                        operation: MutationOperationType.CREATE,
+                        source: CacheSource.CLIENT,
+                        performedBy: firekitUser.uid ?? 'anonymous',
+                        duration: Date.now() - startTime
+                    }
+                };
+            }, mergedOptions, MutationOperationType.CREATE, collectionPath);
+            // Update analytics
+            this.analytics.totalMutations++;
+            this.analytics.successfulMutations++;
+            this.updateOperationAnalytics(MutationOperationType.CREATE, Date.now() - startTime, true);
+            // Emit success event
+            this.emitEvent({
+                type: 'mutation_success',
+                data: { operation: 'create', path: collectionPath, result },
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            return result;
+        }
+        catch (error) {
+            this.analytics.totalMutations++;
+            const mutationError = error instanceof MutationError
+                ? error
+                : this.handleError(error, MutationOperationType.CREATE, collectionPath);
+            this.updateOperationAnalytics(MutationOperationType.CREATE, Date.now() - startTime, false);
+            return {
+                success: false,
+                error: mutationError,
+                metadata: {
+                    timestamp: new Date(),
+                    operation: MutationOperationType.CREATE,
+                    source: CacheSource.CLIENT,
+                    performedBy: firekitUser.uid ?? 'anonymous' ?? 'anonymous',
+                    duration: Date.now() - startTime
+                }
+            };
+        }
+    }
+    /**
+     * Set document data at specified path
+     *
+     * @template T Document data type
+     * @param path Document path
+     * @param data Document data
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.set('users/123', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }, {
+     *   merge: true,
+     *   timestamps: true
+     * });
+     * ```
+     */
+    async set(path, data, options = {}) {
+        const startTime = Date.now();
+        const mergedOptions = { ...this.defaultOptions, ...options };
+        try {
+            this.emitEvent({
+                type: 'mutation_start',
+                data: { operation: 'set', path, data },
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            if (mergedOptions.validate) {
+                const validation = this.validateData(data, mergedOptions.validator);
+                if (!validation.valid) {
+                    throw new MutationError(MutationErrorCode.VALIDATION_FAILED, validation.message || 'Validation failed', MutationOperationType.SET, path, null, { fieldErrors: validation.fieldErrors });
+                }
+            }
+            const result = await this.executeWithRetry(async () => {
+                const firestore = firebaseService.getDbInstance();
+                if (!firestore) {
+                    throw new MutationError(MutationErrorCode.SERVICE_UNAVAILABLE, 'Firestore service not available');
+                }
+                const docRef = doc(firestore, path);
+                const dataToSet = {
+                    ...data,
+                    ...(mergedOptions.timestamps && this.getTimestampData()),
+                    id: docRef.id
+                };
+                await setDoc(docRef, dataToSet, { merge: mergedOptions.merge });
+                return {
+                    success: true,
+                    id: docRef.id,
+                    data: dataToSet,
+                    metadata: {
+                        timestamp: new Date(),
+                        operation: MutationOperationType.SET,
+                        source: CacheSource.CLIENT,
+                        performedBy: firekitUser.uid ?? 'anonymous' ?? 'anonymous',
+                        duration: Date.now() - startTime
+                    }
+                };
+            }, mergedOptions, MutationOperationType.SET, path);
+            this.analytics.totalMutations++;
+            this.analytics.successfulMutations++;
+            this.updateOperationAnalytics(MutationOperationType.SET, Date.now() - startTime, true);
+            this.emitEvent({
+                type: 'mutation_success',
+                data: { operation: 'set', path, result },
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            return result;
+        }
+        catch (error) {
+            this.analytics.totalMutations++;
+            const mutationError = error instanceof MutationError
+                ? error
+                : this.handleError(error, MutationOperationType.SET, path);
+            this.updateOperationAnalytics(MutationOperationType.SET, Date.now() - startTime, false);
+            return {
+                success: false,
+                error: mutationError,
+                metadata: {
+                    timestamp: new Date(),
+                    operation: MutationOperationType.SET,
+                    source: CacheSource.CLIENT,
+                    performedBy: firekitUser.uid ?? 'anonymous' ?? 'anonymous',
+                    duration: Date.now() - startTime
+                }
+            };
+        }
+    }
+    /**
+     * Update a document at specified path
+     *
+     * @template T Document data type
+     * @param path Document path
+     * @param data Update data
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.update('users/123', {
+     *   name: 'Jane Doe',
+     *   lastLogin: serverTimestamp()
+     * });
+     * ```
+     */
+    async update(path, data, options = {}) {
+        const startTime = Date.now();
+        const mergedOptions = { ...this.defaultOptions, ...options };
+        try {
+            this.emitEvent({
+                type: 'mutation_start',
+                data: { operation: 'update', path, data },
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            if (mergedOptions.validate) {
+                const validation = this.validateData(data, mergedOptions.validator);
+                if (!validation.valid) {
+                    throw new MutationError(MutationErrorCode.VALIDATION_FAILED, validation.message || 'Validation failed', MutationOperationType.UPDATE, path, null, { fieldErrors: validation.fieldErrors });
+                }
+            }
+            const result = await this.executeWithRetry(async () => {
+                const firestore = firebaseService.getDbInstance();
+                if (!firestore) {
+                    throw new MutationError(MutationErrorCode.SERVICE_UNAVAILABLE, 'Firestore service not available');
+                }
+                const docRef = doc(firestore, path);
+                const dataToUpdate = {
+                    ...data,
+                    ...(mergedOptions.timestamps && this.getTimestampData(false))
+                };
+                await updateDoc(docRef, dataToUpdate);
+                return {
+                    success: true,
+                    id: docRef.id,
+                    data: dataToUpdate,
+                    metadata: {
+                        timestamp: new Date(),
+                        operation: MutationOperationType.UPDATE,
+                        source: CacheSource.CLIENT,
+                        performedBy: firekitUser.uid ?? 'anonymous' ?? 'anonymous',
+                        duration: Date.now() - startTime
+                    }
+                };
+            }, mergedOptions, MutationOperationType.UPDATE, path);
+            this.analytics.totalMutations++;
+            this.analytics.successfulMutations++;
+            this.updateOperationAnalytics(MutationOperationType.UPDATE, Date.now() - startTime, true);
+            this.emitEvent({
+                type: 'mutation_success',
+                data: { operation: 'update', path, result },
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            return result;
+        }
+        catch (error) {
+            this.analytics.totalMutations++;
+            const mutationError = error instanceof MutationError
+                ? error
+                : this.handleError(error, MutationOperationType.UPDATE, path);
+            this.updateOperationAnalytics(MutationOperationType.UPDATE, Date.now() - startTime, false);
+            return {
+                success: false,
+                error: mutationError,
+                metadata: {
+                    timestamp: new Date(),
+                    operation: MutationOperationType.UPDATE,
+                    source: CacheSource.CLIENT,
+                    performedBy: firekitUser.uid ?? 'anonymous' ?? 'anonymous',
+                    duration: Date.now() - startTime
+                }
+            };
+        }
+    }
+    /**
+     * Delete a document at specified path
+     *
+     * @param path Document path
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.delete('users/123');
+     * if (result.success) {
+     *   console.log('Document deleted');
+     * }
+     * ```
+     */
+    async delete(path, options = {}) {
+        const startTime = Date.now();
+        const mergedOptions = { ...this.defaultOptions, ...options };
+        try {
+            this.emitEvent({
+                type: 'mutation_start',
+                data: { operation: 'delete', path },
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            const result = await this.executeWithRetry(async () => {
+                const firestore = firebaseService.getDbInstance();
+                if (!firestore) {
+                    throw new MutationError(MutationErrorCode.SERVICE_UNAVAILABLE, 'Firestore service not available');
+                }
+                const docRef = doc(firestore, path);
+                await deleteDoc(docRef);
+                return {
+                    success: true,
+                    id: docRef.id,
+                    metadata: {
+                        timestamp: new Date(),
+                        operation: MutationOperationType.DELETE,
+                        source: CacheSource.CLIENT,
+                        performedBy: firekitUser.uid ?? 'anonymous' ?? 'anonymous',
+                        duration: Date.now() - startTime
+                    }
+                };
+            }, mergedOptions, MutationOperationType.DELETE, path);
+            this.analytics.totalMutations++;
+            this.analytics.successfulMutations++;
+            this.updateOperationAnalytics(MutationOperationType.DELETE, Date.now() - startTime, true);
+            this.emitEvent({
+                type: 'mutation_success',
+                data: { operation: 'delete', path, result },
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            return result;
+        }
+        catch (error) {
+            this.analytics.totalMutations++;
+            const mutationError = error instanceof MutationError
+                ? error
+                : this.handleError(error, MutationOperationType.DELETE, path);
+            this.updateOperationAnalytics(MutationOperationType.DELETE, Date.now() - startTime, false);
+            return {
+                success: false,
+                error: mutationError,
+                metadata: {
+                    timestamp: new Date(),
+                    operation: MutationOperationType.DELETE,
+                    source: CacheSource.CLIENT,
+                    performedBy: firekitUser.uid ?? 'anonymous' ?? 'anonymous',
+                    duration: Date.now() - startTime
+                }
+            };
+        }
+    }
+    // ========================================
+    // FIELD VALUE OPERATIONS
+    // ========================================
+    /**
+     * Increment a numeric field
+     *
+     * @param path Document path
+     * @param field Field name
+     * @param value Increment value
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     */
+    async increment(path, field, value, options = {}) {
+        return this.update(path, { [field]: increment(value) }, options);
+    }
+    /**
+     * Add elements to an array field
+     *
+     * @param path Document path
+     * @param field Field name
+     * @param elements Elements to add
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     */
+    async arrayUnion(path, field, elements, options = {}) {
+        return this.update(path, { [field]: arrayUnion(...elements) }, options);
+    }
+    /**
+     * Remove elements from an array field
+     *
+     * @param path Document path
+     * @param field Field name
+     * @param elements Elements to remove
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     */
+    async arrayRemove(path, field, elements, options = {}) {
+        return this.update(path, { [field]: arrayRemove(...elements) }, options);
+    }
+    /**
+     * Delete a field from document
+     *
+     * @param path Document path
+     * @param field Field name
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     */
+    async deleteField(path, field, options = {}) {
+        return this.update(path, { [field]: deleteField() }, options);
+    }
+    // ========================================
+    // BATCH OPERATIONS
+    // ========================================
+    /**
+     * Execute multiple operations in a batch
+     *
+     * @param operations Array of batch operations
+     * @param config Bulk mutation configuration
+     * @returns Promise resolving to batch result
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.batch([
+     *   { type: 'create', path: 'users', data: userData },
+     *   { type: 'update', path: 'profiles/123', data: profileUpdate },
+     *   { type: 'delete', path: 'temp/456' }
+     * ], {
+     *   batchSize: 500,
+     *   failFast: false,
+     *   onProgress: (completed, total) => console.log(`${completed}/${total}`)
+     * });
+     * ```
+     */
+    async batch(operations, config = {}) {
+        const startTime = Date.now();
+        const batchConfig = {
+            batchSize: 500,
+            parallel: false,
+            failFast: true,
+            ...config
+        };
+        this.emitEvent({
+            type: 'batch_start',
+            data: { operationCount: operations.length, config: batchConfig },
+            timestamp: new Date(),
+            userId: firekitUser.uid ?? 'anonymous'
+        });
+        try {
+            const firestore = firebaseService.getDbInstance();
+            if (!firestore) {
+                throw new MutationError(MutationErrorCode.SERVICE_UNAVAILABLE, 'Firestore service not available');
+            }
+            const results = [];
+            const batches = this.chunkArray(operations, batchConfig.batchSize);
+            let successCount = 0;
+            let failureCount = 0;
+            for (let i = 0; i < batches.length; i++) {
+                const batch = batches[i];
+                const batchWriter = writeBatch(firestore);
+                const batchResults = [];
+                for (const operation of batch) {
+                    try {
+                        await this.addOperationToBatch(batchWriter, operation);
+                        batchResults.push({
+                            operation,
+                            success: true,
+                            duration: 0 // Will be updated after batch commit
+                        });
+                    }
+                    catch (error) {
+                        const mutationError = this.handleError(error, operation.type, operation.path);
+                        batchResults.push({
+                            operation,
+                            success: false,
+                            error: mutationError,
+                            duration: 0
+                        });
+                        failureCount++;
+                        if (batchConfig.failFast) {
+                            throw mutationError;
+                        }
+                    }
+                }
+                // Commit batch
+                const batchStartTime = Date.now();
+                await batchWriter.commit();
+                const batchDuration = Date.now() - batchStartTime;
+                // Update durations
+                batchResults.forEach((result) => {
+                    result.duration = batchDuration / batch.length;
+                    if (result.success)
+                        successCount++;
+                });
+                results.push(...batchResults);
+                // Emit progress
+                const completed = (i + 1) * batchConfig.batchSize;
+                this.emitEvent({
+                    type: 'batch_progress',
+                    data: { completed: Math.min(completed, operations.length), total: operations.length },
+                    timestamp: new Date(),
+                    userId: firekitUser.uid ?? 'anonymous'
+                });
+                batchConfig.onProgress?.(Math.min(completed, operations.length), operations.length);
+            }
+            const batchResult = {
+                success: failureCount === 0,
+                successCount,
+                failureCount,
+                results,
+                metadata: {
+                    startTime: new Date(startTime),
+                    endTime: new Date(),
+                    duration: Date.now() - startTime,
+                    operationCount: operations.length,
+                    executedBy: firekitUser.uid ?? 'anonymous',
+                    strategy: batchConfig.parallel ? 'parallel' : 'sequential'
+                }
+            };
+            this.emitEvent({
+                type: 'batch_complete',
+                data: batchResult,
+                timestamp: new Date(),
+                userId: firekitUser.uid ?? 'anonymous'
+            });
+            return batchResult;
+        }
+        catch (error) {
+            const mutationError = error instanceof MutationError ? error : this.handleError(error, 'batch');
+            throw mutationError;
+        }
+    }
+    /**
+     * Add operation to batch writer
+     */
+    async addOperationToBatch(batch, operation) {
+        const firestore = firebaseService.getDbInstance();
+        if (!firestore)
+            throw new Error('Firestore not available');
+        const options = { ...this.defaultOptions, ...operation.options };
+        switch (operation.type) {
+            case 'create':
+            case 'set': {
+                const docRef = doc(firestore, operation.path);
+                let data = operation.data || {};
+                if (options.timestamps) {
+                    data = { ...data, ...this.getTimestampData() };
+                }
+                if (options.validate && operation.data) {
+                    const validation = this.validateData(operation.data, options.validator);
+                    if (!validation.valid) {
+                        throw new MutationError(MutationErrorCode.VALIDATION_FAILED, validation.message || 'Validation failed', operation.type, operation.path);
+                    }
+                }
+                batch.set(docRef, { ...data, id: docRef.id }, { merge: options.merge });
+                break;
+            }
+            case 'update': {
+                const docRef = doc(firestore, operation.path);
+                let data = operation.data || {};
+                if (options.timestamps) {
+                    data = { ...data, ...this.getTimestampData(false) };
+                }
+                if (options.validate && operation.data) {
+                    const validation = this.validateData(operation.data, options.validator);
+                    if (!validation.valid) {
+                        throw new MutationError(MutationErrorCode.VALIDATION_FAILED, validation.message || 'Validation failed', operation.type, operation.path);
+                    }
+                }
+                batch.update(docRef, data);
+                break;
+            }
+            case 'delete': {
+                const docRef = doc(firestore, operation.path);
+                batch.delete(docRef);
+                break;
+            }
+            default:
+                throw new MutationError(MutationErrorCode.UNIMPLEMENTED, `Operation type ${operation.type} not supported in batch`);
+        }
+    }
+    /**
+     * Chunk array into smaller arrays
+     */
+    chunkArray(array, chunkSize) {
+        const chunks = [];
+        for (let i = 0; i < array.length; i += chunkSize) {
+            chunks.push(array.slice(i, i + chunkSize));
+        }
+        return chunks;
+    }
+    // ========================================
+    // UTILITY METHODS
+    // ========================================
+    /**
+     * Check if a document exists at specified path
+     *
+     * @param path Document path
+     * @returns Promise resolving to existence check result
+     *
+     * @example
+     * ```typescript
+     * const checkResult = await firekitDocMutations.exists('users/123');
+     * if (checkResult.exists) {
+     *   console.log('Document exists');
+     * }
+     * ```
+     */
+    async exists(path) {
+        try {
+            const firestore = firebaseService.getDbInstance();
+            if (!firestore) {
+                throw new MutationError(MutationErrorCode.SERVICE_UNAVAILABLE, 'Firestore service not available');
+            }
+            const docRef = doc(firestore, path);
+            const docSnap = await getDoc(docRef);
+            return {
+                exists: docSnap.exists(),
+                id: docSnap.exists() ? docSnap.id : undefined,
+                lastModified: docSnap.exists()
+                    ? docSnap.metadata.fromCache
+                        ? undefined
+                        : new Date()
+                    : undefined,
+                metadata: docSnap.exists()
+                    ? {
+                        size: JSON.stringify(docSnap.data()).length,
+                        updateTime: docSnap.metadata.fromCache ? new Date() : new Date(),
+                        createTime: docSnap.metadata.fromCache ? new Date() : new Date()
+                    }
+                    : undefined
+            };
+        }
+        catch (error) {
+            console.error('Error checking document existence:', error);
+            return { exists: false };
+        }
+    }
+    /**
+     * Get a document at specified path
+     *
+     * @template T Document data type
+     * @param path Document path
+     * @returns Promise resolving to mutation response with document data
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitDocMutations.getDoc<UserData>('users/123');
+     * if (result.success && result.data) {
+     *   console.log('User data:', result.data);
+     * }
+     * ```
+     */
+    async getDoc(path) {
+        try {
+            const firestore = firebaseService.getDbInstance();
+            if (!firestore) {
+                throw new MutationError(MutationErrorCode.SERVICE_UNAVAILABLE, 'Firestore service not available');
+            }
+            const docRef = doc(firestore, path);
+            const docSnap = await getDoc(docRef);
+            if (!docSnap.exists()) {
+                return {
+                    success: false,
+                    error: new MutationError(MutationErrorCode.NOT_FOUND, 'Document does not exist', undefined, path)
+                };
+            }
+            return {
+                success: true,
+                id: docSnap.id,
+                data: { id: docSnap.id, ...docSnap.data() },
+                metadata: {
+                    timestamp: new Date(),
+                    operation: MutationOperationType.READ,
+                    source: docSnap.metadata.fromCache ? CacheSource.CACHE : CacheSource.SERVER,
+                    performedBy: firekitUser.uid ?? 'anonymous',
+                    fromCache: docSnap.metadata.fromCache
+                }
+            };
+        }
+        catch (error) {
+            const mutationError = this.handleError(error, 'read', path);
+            return {
+                success: false,
+                error: mutationError
+            };
+        }
+    }
+    /**
+     * Update operation analytics
+     */
+    updateOperationAnalytics(operation, duration, success) {
+        if (!this.analytics.performanceByOperation[operation]) {
+            this.analytics.performanceByOperation[operation] = {
+                count: 0,
+                averageDuration: 0,
+                successRate: 0
+            };
+        }
+        const stats = this.analytics.performanceByOperation[operation];
+        stats.count++;
+        stats.averageDuration = (stats.averageDuration * (stats.count - 1) + duration) / stats.count;
+        if (success) {
+            stats.successRate = (stats.successRate * (stats.count - 1) + 100) / stats.count;
+        }
+        else {
+            stats.successRate = (stats.successRate * (stats.count - 1)) / stats.count;
+        }
+        // Update overall analytics
+        this.analytics.successRate =
+            (this.analytics.successfulMutations / this.analytics.totalMutations) * 100;
+        this.analytics.averageDuration =
+            (this.analytics.averageDuration * (this.analytics.totalMutations - 1) + duration) /
+                this.analytics.totalMutations;
+    }
+    // ========================================
+    // EVENT MANAGEMENT
+    // ========================================
+    /**
+     * Add event listener for mutation events
+     *
+     * @param callback Event callback function
+     * @returns Cleanup function to remove listener
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = firekitDocMutations.addEventListener((event) => {
+     *   console.log('Mutation event:', event.type, event.data);
+     * });
+     *
+     * // Clean up when done
+     * unsubscribe();
+     * ```
+     */
+    addEventListener(callback) {
+        this.eventListeners.add(callback);
+        return () => this.eventListeners.delete(callback);
+    }
+    /**
+     * Remove all event listeners
+     */
+    clearEventListeners() {
+        this.eventListeners.clear();
+    }
+    /**
+     * Get current mutation analytics
+     *
+     * @returns Current analytics data
+     */
+    getAnalytics() {
+        return { ...this.analytics };
+    }
+    /**
+     * Reset analytics data
+     */
+    resetAnalytics() {
+        this.analytics = this.initializeAnalytics();
+    }
+    // ========================================
+    // STATIC FIELD VALUE HELPERS
+    // ========================================
+    /**
+     * Create server timestamp field value
+     */
+    static serverTimestamp() {
+        return serverTimestamp();
+    }
+    /**
+     * Create increment field value
+     */
+    static increment(value) {
+        return increment(value);
+    }
+    /**
+     * Create array union field value
+     */
+    static arrayUnion(...elements) {
+        return arrayUnion(...elements);
+    }
+    /**
+     * Create array remove field value
+     */
+    static arrayRemove(...elements) {
+        return arrayRemove(...elements);
+    }
+    /**
+     * Create delete field value
+     */
+    static deleteField() {
+        return deleteField();
+    }
+}
+/**
+ * Pre-initialized singleton instance of FirekitDocumentMutations.
+ *
+ * @example
+ * ```typescript
+ * import { firekitDocMutations } from 'svelte-firekit';
+ *
+ * // Add document
+ * const result = await firekitDocMutations.add('users', userData);
+ *
+ * // Update document
+ * await firekitDocMutations.update('users/123', { name: 'New Name' });
+ *
+ * // Batch operations
+ * const batchResult = await firekitDocMutations.batch([
+ *   { type: 'create', path: 'users', data: userData },
+ *   { type: 'update', path: 'profiles/123', data: updateData }
+ * ]);
+ *
+ * // Listen to events
+ * const unsubscribe = firekitDocMutations.addEventListener((event) => {
+ *   console.log('Mutation:', event.type, event.data);
+ * });
+ * ```
+ */
+export const firekitDocMutations = new FirekitDocumentMutations();