svelte-firekit 0.0.25 → 0.1.1

package/dist/services/mutations.d.ts

@@ -0,0 +1,336 @@
+/**
+ * @fileoverview FirekitDocumentMutations - Optimized document mutation service for Svelte
+ * @module FirekitDocumentMutations
+ * @version 1.0.0
+ */
+import { type DocumentData, type WithFieldValue, type PartialWithFieldValue } from 'firebase/firestore';
+import { type MutationResponse, type MutationOptions, type BatchOperation, type BatchResult, type ExistenceCheckResult, type BulkMutationConfig, type MutationEventCallback, type MutationAnalytics } from '../types/mutations.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);
+ * });
+ * ```
+ */
+declare class FirekitDocumentMutations {
+    private eventListeners;
+    private analytics;
+    private defaultOptions;
+    /**
+     * Initialize analytics object
+     */
+    private initializeAnalytics;
+    /**
+     * Generate timestamp data for document mutations
+     */
+    private getTimestampData;
+    /**
+     * Validate data using custom validator or basic validation
+     */
+    private validateData;
+    /**
+     * Handle and format mutation errors
+     */
+    private handleError;
+    /**
+     * Map Firestore error codes to MutationErrorCode
+     */
+    private mapFirestoreErrorCode;
+    /**
+     * Update error analytics
+     */
+    private updateErrorAnalytics;
+    /**
+     * Emit event to all listeners
+     */
+    private emitEvent;
+    /**
+     * Execute operation with retry logic
+     */
+    private executeWithRetry;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    add<T extends DocumentData>(collectionPath: string, data: WithFieldValue<T>, options?: MutationOptions): Promise<MutationResponse<T>>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    set<T extends DocumentData>(path: string, data: WithFieldValue<T>, options?: MutationOptions): Promise<MutationResponse<T>>;
+    /**
+     * 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()
+     * });
+     * ```
+     */
+    update<T extends DocumentData>(path: string, data: PartialWithFieldValue<T>, options?: MutationOptions): Promise<MutationResponse<Partial<T>>>;
+    /**
+     * 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');
+     * }
+     * ```
+     */
+    delete(path: string, options?: MutationOptions): Promise<MutationResponse<void>>;
+    /**
+     * 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
+     */
+    increment(path: string, field: string, value: number, options?: MutationOptions): Promise<MutationResponse<any>>;
+    /**
+     * 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
+     */
+    arrayUnion(path: string, field: string, elements: any[], options?: MutationOptions): Promise<MutationResponse<any>>;
+    /**
+     * 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
+     */
+    arrayRemove(path: string, field: string, elements: any[], options?: MutationOptions): Promise<MutationResponse<any>>;
+    /**
+     * Delete a field from document
+     *
+     * @param path Document path
+     * @param field Field name
+     * @param options Mutation options
+     * @returns Promise resolving to mutation response
+     */
+    deleteField(path: string, field: string, options?: MutationOptions): Promise<MutationResponse<any>>;
+    /**
+     * 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}`)
+     * });
+     * ```
+     */
+    batch(operations: BatchOperation[], config?: BulkMutationConfig): Promise<BatchResult>;
+    /**
+     * Add operation to batch writer
+     */
+    private addOperationToBatch;
+    /**
+     * Chunk array into smaller arrays
+     */
+    private chunkArray;
+    /**
+     * 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');
+     * }
+     * ```
+     */
+    exists(path: string): Promise<ExistenceCheckResult>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    getDoc<T extends DocumentData>(path: string): Promise<MutationResponse<T>>;
+    /**
+     * Update operation analytics
+     */
+    private updateOperationAnalytics;
+    /**
+     * 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: MutationEventCallback): () => void;
+    /**
+     * Remove all event listeners
+     */
+    clearEventListeners(): void;
+    /**
+     * Get current mutation analytics
+     *
+     * @returns Current analytics data
+     */
+    getAnalytics(): MutationAnalytics;
+    /**
+     * Reset analytics data
+     */
+    resetAnalytics(): void;
+    /**
+     * Create server timestamp field value
+     */
+    static serverTimestamp(): import("@firebase/firestore").FieldValue;
+    /**
+     * Create increment field value
+     */
+    static increment(value: number): import("@firebase/firestore").FieldValue;
+    /**
+     * Create array union field value
+     */
+    static arrayUnion(...elements: any[]): import("@firebase/firestore").FieldValue;
+    /**
+     * Create array remove field value
+     */
+    static arrayRemove(...elements: any[]): import("@firebase/firestore").FieldValue;
+    /**
+     * Create delete field value
+     */
+    static deleteField(): import("@firebase/firestore").FieldValue;
+}
+/**
+ * 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 declare const firekitDocMutations: FirekitDocumentMutations;
+export {};