svelte-firekit 0.1.8 → 0.2.0

package/dist/services/mutations.d.ts

@@ -1,304 +1,81 @@
+import { type DocumentReference, type Transaction, type FieldValue } from 'firebase/firestore';
+import type { MutationOptions } from '../types/mutations.js';
 /**
- * @fileoverview FirekitDocumentMutations - Optimized document mutation service for Svelte
- * @module FirekitDocumentMutations
- * @version 1.0.0
+ * A single mutation operation for use in batchOps().
+ * (Named FirekitBatchOp to avoid conflict with the richer BatchOperation type in types/mutations.)
  */
-import { type DocumentData, type WithFieldValue, type PartialWithFieldValue } from 'firebase/firestore';
-import { type MutationResponse, type MutationOptions, type BatchOperation, type BatchResult, type ExistenceCheckResult, type BulkMutationConfig, type MutationAnalytics } from '../types/mutations.js';
+export interface FirekitBatchOp {
+    type: 'set' | 'update' | 'delete';
+    path: string;
+    id?: string;
+    data?: Record<string, unknown>;
+    merge?: boolean;
+}
+/**
+ * Result of a batchOps() call.
+ */
+export interface FirekitBatchResult {
+    success: boolean;
+    count: number;
+    error?: Error;
+}
 /**
- * Comprehensive Firestore document mutation service with advanced features.
- * Handles CRUD operations, batch processing, validation, error handling, and analytics.
+ * Firestore document mutations — add, set, update, delete, batch, transaction.
  *
- * @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 }
- * ]);
+ * ```ts
+ * import { firekitMutations } from 'svelte-firekit';
+ * await firekitMutations.add('users', { name: 'Alice' });
+ * await firekitMutations.update('users/uid123', { name: 'Bob' });
  * ```
  */
 declare class FirekitDocumentMutations {
-    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;
-    /**
-     * 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>>;
+    private static instance;
+    private constructor();
+    static getInstance(): FirekitDocumentMutations;
+    private buildTimestamps;
+    private resolveRef;
+    /** Generates a new Firestore document ID for a given collection path. */
+    generateId(collectionPath: string): string;
     /**
-     * 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
+     * Adds a new document to a collection with an auto-generated ID.
+     * Returns the new document reference.
      */
-    arrayUnion(path: string, field: string, elements: any[], options?: MutationOptions): Promise<MutationResponse<any>>;
+    add<T extends Record<string, unknown>>(collectionPath: string, data: T, options?: MutationOptions): Promise<DocumentReference>;
     /**
-     * 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
+     * Sets (overwrites or merges) a document at the given path.
      */
-    arrayRemove(path: string, field: string, elements: any[], options?: MutationOptions): Promise<MutationResponse<any>>;
+    set<T extends Record<string, unknown>>(pathOrRef: string | DocumentReference, data: T, options?: MutationOptions): Promise<void>;
     /**
-     * Delete a field from document
-     *
-     * @param path Document path
-     * @param field Field name
-     * @param options Mutation options
-     * @returns Promise resolving to mutation response
+     * Updates specific fields of an existing document.
      */
-    deleteField(path: string, field: string, options?: MutationOptions): Promise<MutationResponse<any>>;
+    update<T extends Record<string, unknown>>(pathOrRef: string | DocumentReference, data: Partial<T> & Record<string, unknown>, options?: MutationOptions): Promise<void>;
     /**
-     * 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}`)
-     * });
-     * ```
+     * Deletes a document.
      */
-    batch(operations: BatchOperation[], config?: BulkMutationConfig): Promise<BatchResult>;
+    delete(pathOrRef: string | DocumentReference, options?: MutationOptions): Promise<void>;
+    /** Returns true if a document exists at the given path. */
+    exists(pathOrRef: string | DocumentReference): Promise<boolean>;
+    /** Fetches a document snapshot and returns its data, or null if it doesn't exist. */
+    fetch<T>(pathOrRef: string | DocumentReference): Promise<T | null>;
     /**
-     * Add operation to batch writer
+     * Executes a batch of mutations, automatically chunked into groups of 500.
      */
-    private addOperationToBatch;
+    batchOps(operations: FirekitBatchOp[], options?: MutationOptions): Promise<FirekitBatchResult>;
     /**
-     * Generate a unique document ID (Firestore-style)
+     * Runs a Firestore transaction.
      */
-    private generateDocumentId;
-    /**
-     * 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;
-    /**
-     * 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;
+    transaction<T>(fn: (transaction: Transaction) => Promise<T>): Promise<T>;
+    /** Firestore server timestamp sentinel. */
+    serverTimestamp(): FieldValue;
+    /** Firestore increment sentinel. */
+    increment(n: number): FieldValue;
+    /** Firestore arrayUnion sentinel. */
+    arrayUnion(...elements: unknown[]): FieldValue;
+    /** Firestore arrayRemove sentinel. */
+    arrayRemove(...elements: unknown[]): FieldValue;
+    /** Firestore deleteField sentinel. */
+    deleteField(): 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 }
- * ]);
- * ```
- */
-export declare const firekitDocMutations: FirekitDocumentMutations;
+export declare const firekitMutations: FirekitDocumentMutations;
 export {};