svelte-firekit 0.0.25 → 0.1.1

package/dist/firestore/awaitable-doc.svelte.d.ts

@@ -1,141 +0,0 @@
-/**
- * @module FirekitAwaitableDoc
- */
-import { type DocumentReference, type DocumentData } from "firebase/firestore";
-/**
- * Provides real-time document subscription with state management.
- * Automatically handles document data updates, loading states, and error handling.
- *
- * @class
- * @template T Type of document data
- * @example
- * ```typescript
- * interface UserProfile {
- *   id: string;
- *   name: string;
- *   email: string;
- * }
- *
- * // Create document subscription
- * const userDoc = firekitAwaitableDoc<UserProfile>(
- *   'users/123',
- *   { id: '123', name: 'Loading...', email: '' }
- * );
- *
- * // Access reactive state
- * if (userDoc.loading) {
- *   console.log('Loading user data...');
- * } else if (userDoc.error) {
- *   console.error('Error:', userDoc.error);
- * } else {
- *   console.log('User data:', userDoc.data);
- * }
- *
- * // Get fresh data
- * const freshData = await userDoc.getData();
- * ```
- */
-declare class FirekitAwaitableDoc<T> {
-    /**
-     * Current document data.
-     * Uses SvelteKit's $state for reactivity.
-     * @private
-     */
-    private _data;
-    /**
-     * Loading state indicator.
-     * Uses SvelteKit's $state for reactivity.
-     * @private
-     */
-    private _loading;
-    /**
-     * Error state container.
-     * Uses SvelteKit's $state for reactivity.
-     * @private
-     */
-    private _error;
-    /**
-     * Firestore document reference.
-     * @private
-     */
-    private docRef;
-    /**
-     * Creates a document subscription.
-     * Initializes document subscription if in browser environment.
-     *
-     * @param {string | DocumentReference<T>} ref - Document path or reference
-     * @param {T} [startWith] - Initial data before fetch completes
-     *
-     * @example
-     * ```typescript
-     * const doc = new FirekitAwaitableDoc('users/123', defaultUser);
-     * ```
-     */
-    constructor(ref: string | DocumentReference<T>, startWith?: T);
-    /**
-     * Initializes document subscription.
-     * Sets up real-time updates and handles initial data fetch.
-     *
-     * @private
-     * @param {string | DocumentReference<T>} ref - Document path or reference
-     * @returns {Promise<void>}
-     *
-     * @throws {Error} If document initialization fails
-     */
-    private initializeDoc;
-    /**
-     * Fetches fresh document data.
-     * Makes a new request to Firestore instead of using cached data.
-     *
-     * @returns {Promise<T | null>} Document data or null if not found
-     *
-     * @example
-     * ```typescript
-     * const freshData = await doc.getData();
-     * if (freshData) {
-     *   console.log('Fresh data:', freshData);
-     * }
-     * ```
-     */
-    getData(): Promise<T | null>;
-    /**
-     * Gets current document data.
-     * @returns {T | null} Current document data or null if not loaded
-     */
-    get data(): T | null;
-    /**
-     * Gets current loading state.
-     * @returns {boolean} True if document is loading
-     */
-    get loading(): boolean;
-    /**
-     * Gets current error state.
-     * @returns {Error | null} Error object if an error occurred, null otherwise
-     */
-    get error(): Error | null;
-}
-/**
- * Creates a document subscription.
- * Factory function for creating FirekitAwaitableDoc instances.
- *
- * @template T Document data type
- * @param {string} path Document path
- * @param {T} [startWith] Initial data before fetch completes
- * @returns {FirekitAwaitableDoc<T>} Document subscription instance
- *
- * @example
- * ```typescript
- * interface UserProfile {
- *   id: string;
- *   name: string;
- *   email: string;
- * }
- *
- * const userDoc = firekitAwaitableDoc<UserProfile>(
- *   'users/123',
- *   { id: '123', name: 'Loading...', email: '' }
- * );
- * ```
- */
-export declare function firekitAwaitableDoc<T extends DocumentData>(path: string, startWith?: T): FirekitAwaitableDoc<T>;
-export {};

package/dist/firestore/awaitable-doc.svelte.js

@@ -1,183 +0,0 @@
-/**
- * @module FirekitAwaitableDoc
- */
-import { doc, getDoc, onSnapshot } from "firebase/firestore";
-import { firebaseService } from "../firebase.js";
-import { browser } from "$app/environment";
-/**
- * Provides real-time document subscription with state management.
- * Automatically handles document data updates, loading states, and error handling.
- *
- * @class
- * @template T Type of document data
- * @example
- * ```typescript
- * interface UserProfile {
- *   id: string;
- *   name: string;
- *   email: string;
- * }
- *
- * // Create document subscription
- * const userDoc = firekitAwaitableDoc<UserProfile>(
- *   'users/123',
- *   { id: '123', name: 'Loading...', email: '' }
- * );
- *
- * // Access reactive state
- * if (userDoc.loading) {
- *   console.log('Loading user data...');
- * } else if (userDoc.error) {
- *   console.error('Error:', userDoc.error);
- * } else {
- *   console.log('User data:', userDoc.data);
- * }
- *
- * // Get fresh data
- * const freshData = await userDoc.getData();
- * ```
- */
-class FirekitAwaitableDoc {
-    /**
-     * Current document data.
-     * Uses SvelteKit's $state for reactivity.
-     * @private
-     */
-    _data = $state(null);
-    /**
-     * Loading state indicator.
-     * Uses SvelteKit's $state for reactivity.
-     * @private
-     */
-    _loading = $state(true);
-    /**
-     * Error state container.
-     * Uses SvelteKit's $state for reactivity.
-     * @private
-     */
-    _error = $state(null);
-    /**
-     * Firestore document reference.
-     * @private
-     */
-    docRef = null;
-    /**
-     * Creates a document subscription.
-     * Initializes document subscription if in browser environment.
-     *
-     * @param {string | DocumentReference<T>} ref - Document path or reference
-     * @param {T} [startWith] - Initial data before fetch completes
-     *
-     * @example
-     * ```typescript
-     * const doc = new FirekitAwaitableDoc('users/123', defaultUser);
-     * ```
-     */
-    constructor(ref, startWith) {
-        this._data = startWith ?? null;
-        if (browser) {
-            this.initializeDoc(ref);
-        }
-    }
-    /**
-     * Initializes document subscription.
-     * Sets up real-time updates and handles initial data fetch.
-     *
-     * @private
-     * @param {string | DocumentReference<T>} ref - Document path or reference
-     * @returns {Promise<void>}
-     *
-     * @throws {Error} If document initialization fails
-     */
-    async initializeDoc(ref) {
-        try {
-            const firestore = firebaseService.getDbInstance();
-            this.docRef = typeof ref === "string"
-                ? doc(firestore, ref)
-                : ref;
-            // Initial fetch
-            const snapshot = await getDoc(this.docRef);
-            this._data = snapshot.exists() ? { id: snapshot.id, ...snapshot.data() } : null;
-            // Setup real-time updates
-            onSnapshot(this.docRef, (snapshot) => {
-                this._data = snapshot.exists() ? { id: snapshot.id, ...snapshot.data() } : null;
-                this._loading = false;
-                this._error = null;
-            }, (error) => {
-                this._error = error;
-                this._loading = false;
-            });
-        }
-        catch (error) {
-            this._error = error;
-            this._loading = false;
-        }
-    }
-    /**
-     * Fetches fresh document data.
-     * Makes a new request to Firestore instead of using cached data.
-     *
-     * @returns {Promise<T | null>} Document data or null if not found
-     *
-     * @example
-     * ```typescript
-     * const freshData = await doc.getData();
-     * if (freshData) {
-     *   console.log('Fresh data:', freshData);
-     * }
-     * ```
-     */
-    async getData() {
-        if (!this.docRef)
-            return null;
-        const snapshot = await getDoc(this.docRef);
-        return snapshot.exists() ? { id: snapshot.id, ...snapshot.data() } : null;
-    }
-    /**
-     * Gets current document data.
-     * @returns {T | null} Current document data or null if not loaded
-     */
-    get data() {
-        return this._data;
-    }
-    /**
-     * Gets current loading state.
-     * @returns {boolean} True if document is loading
-     */
-    get loading() {
-        return this._loading;
-    }
-    /**
-     * Gets current error state.
-     * @returns {Error | null} Error object if an error occurred, null otherwise
-     */
-    get error() {
-        return this._error;
-    }
-}
-/**
- * Creates a document subscription.
- * Factory function for creating FirekitAwaitableDoc instances.
- *
- * @template T Document data type
- * @param {string} path Document path
- * @param {T} [startWith] Initial data before fetch completes
- * @returns {FirekitAwaitableDoc<T>} Document subscription instance
- *
- * @example
- * ```typescript
- * interface UserProfile {
- *   id: string;
- *   name: string;
- *   email: string;
- * }
- *
- * const userDoc = firekitAwaitableDoc<UserProfile>(
- *   'users/123',
- *   { id: '123', name: 'Loading...', email: '' }
- * );
- * ```
- */
-export function firekitAwaitableDoc(path, startWith) {
-    return new FirekitAwaitableDoc(path, startWith);
-}

package/dist/firestore/batch-mutations.svelte.d.ts

@@ -1,140 +0,0 @@
-/**
- * @module FirekitBatchMutations
- */
-import { type DocumentData, type WithFieldValue } from 'firebase/firestore';
-/**
- * Response structure for batch operations
- * @interface BatchResponse
- */
-interface BatchResponse {
-    /** Operation success status */
-    success: boolean;
-    /** Number of processed items */
-    processedItems?: number;
-    /** Error details if operation failed */
-    error?: {
-        code: string;
-        message: string;
-    };
-}
-/**
- * Options for batch mutations
- * @interface BatchMutationOptions
- */
-interface BatchMutationOptions {
-    /** Whether to include timestamp fields */
-    timestamps?: boolean;
-    /** Whether to merge data in set operations */
-    merge?: boolean;
-    /** Batch size limit (default: 500) */
-    batchSize?: number;
-    /** Delay between batches in milliseconds (default: 3000) */
-    delayBetweenBatches?: number;
-}
-/**
- * Batch operation type
- * @type BatchOperation
- */
-type BatchOperation<T> = {
-    /** Operation type */
-    type: 'set' | 'update' | 'delete';
-    /** Document path */
-    path: string;
-    /** Document data */
-    data?: WithFieldValue<T>;
-    /** Operation options */
-    options?: BatchMutationOptions;
-};
-/**
- * Manages Firestore batch operations with automatic timestamps and error handling
- * @class
- */
-declare class FirekitBatchMutations {
-    /** Default batch size limit */
-    private readonly DEFAULT_BATCH_LIMIT;
-    /** Default delay between batches in milliseconds */
-    private readonly DEFAULT_BATCH_DELAY;
-    /**
-     * Generates timestamp data for document mutations
-     * @private
-     * @param {boolean} [isNew=true] Whether this is a new document
-     * @returns {Record<string, any>} Timestamp data
-     */
-    private getTimestampData;
-    /**
-     * Creates a delay between batch operations
-     * @private
-     * @param {number} ms Milliseconds to delay
-     * @returns {Promise<void>}
-     */
-    private delay;
-    /**
-     * Handles and formats batch operation errors
-     * @private
-     * @param {any} error Error object
-     * @returns {BatchResponse} Formatted error response
-     */
-    private handleError;
-    /**
-     * Executes multiple write operations as batches
-     * @template T Document data type
-     * @param {BatchOperation<T>[]} operations Array of batch operations
-     * @param {BatchMutationOptions} [options] Batch options
-     * @returns {Promise<BatchResponse>} Batch operation response
-     *
-     * @example
-     * ```typescript
-     * const operations = [
-     *   {
-     *     type: 'set',
-     *     path: 'cities/NYC',
-     *     data: { name: 'New York City' }
-     *   },
-     *   {
-     *     type: 'update',
-     *     path: 'cities/SF',
-     *     data: { population: 1000000 }
-     *   },
-     *   {
-     *     type: 'delete',
-     *     path: 'cities/LA'
-     *   }
-     * ];
-     *
-     * const result = await firekitBatchMutations.batch(operations);
-     * ```
-     */
-    batch<T extends DocumentData>(operations: BatchOperation<T>[], options?: BatchMutationOptions): Promise<BatchResponse>;
-    /**
-     * Inserts multiple items into a collection using batched writes
-     * @template T Document data type
-     * @param {string} collectionPath Collection path
-     * @param {T[]} items Array of items to insert
-     * @param {BatchMutationOptions} [options] Batch options
-     * @param {string} [idKey] Optional key to use as document ID from items
-     * @returns {Promise<BatchResponse>} Batch operation response
-     *
-     * @example
-     * ```typescript
-     * const items = [
-     *   { id: 'nyc', name: 'New York City' },
-     *   { id: 'sf', name: 'San Francisco' }
-     * ];
-     *
-     * const result = await firekitBatchMutations.batchInsert(
-     *   'cities',
-     *   items,
-     *   { timestamps: true },
-     *   'id'
-     * );
-     * ```
-     */
-    batchInsert<T extends DocumentData>(collectionPath: string, items: T[], options?: BatchMutationOptions, idKey?: string): Promise<BatchResponse>;
-}
-/**
- * Pre-initialized instance of FirekitBatchMutations
- * @const
- * @type {FirekitBatchMutations}
- */
-export declare const firekitBatchMutations: FirekitBatchMutations;
-export {};

package/dist/firestore/batch-mutations.svelte.js

@@ -1,218 +0,0 @@
-/**
- * @module FirekitBatchMutations
- */
-import { doc, collection, writeBatch, serverTimestamp } from 'firebase/firestore';
-import { firebaseService } from '../firebase.js';
-import { firekitUser } from '../auth/user.svelte.js';
-/**
- * Manages Firestore batch operations with automatic timestamps and error handling
- * @class
- */
-class FirekitBatchMutations {
-    /** Default batch size limit */
-    DEFAULT_BATCH_LIMIT = 500;
-    /** Default delay between batches in milliseconds */
-    DEFAULT_BATCH_DELAY = 3000;
-    /**
-     * Generates timestamp data for document mutations
-     * @private
-     * @param {boolean} [isNew=true] Whether this is a new document
-     * @returns {Record<string, any>} Timestamp data
-     */
-    getTimestampData(isNew = true) {
-        const timestamps = {
-            updatedAt: serverTimestamp(),
-            updatedBy: firekitUser.uid
-        };
-        if (isNew) {
-            timestamps.createdAt = serverTimestamp();
-            timestamps.createdBy = firekitUser.uid;
-        }
-        return timestamps;
-    }
-    /**
-     * Creates a delay between batch operations
-     * @private
-     * @param {number} ms Milliseconds to delay
-     * @returns {Promise<void>}
-     */
-    async delay(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
-    }
-    /**
-     * Handles and formats batch operation errors
-     * @private
-     * @param {any} error Error object
-     * @returns {BatchResponse} Formatted error response
-     */
-    handleError(error) {
-        console.error('Firestore batch operation error:', error);
-        return {
-            success: false,
-            error: {
-                code: error.code || 'unknown_error',
-                message: error.message || 'An unknown error occurred'
-            }
-        };
-    }
-    /**
-     * Executes multiple write operations as batches
-     * @template T Document data type
-     * @param {BatchOperation<T>[]} operations Array of batch operations
-     * @param {BatchMutationOptions} [options] Batch options
-     * @returns {Promise<BatchResponse>} Batch operation response
-     *
-     * @example
-     * ```typescript
-     * const operations = [
-     *   {
-     *     type: 'set',
-     *     path: 'cities/NYC',
-     *     data: { name: 'New York City' }
-     *   },
-     *   {
-     *     type: 'update',
-     *     path: 'cities/SF',
-     *     data: { population: 1000000 }
-     *   },
-     *   {
-     *     type: 'delete',
-     *     path: 'cities/LA'
-     *   }
-     * ];
-     *
-     * const result = await firekitBatchMutations.batch(operations);
-     * ```
-     */
-    async batch(operations, options = {}) {
-        try {
-            const firestore = firebaseService.getDbInstance();
-            let batch = writeBatch(firestore);
-            let batchCounter = 0;
-            const batchLimit = options.batchSize || this.DEFAULT_BATCH_LIMIT;
-            const batchDelay = options.delayBetweenBatches || this.DEFAULT_BATCH_DELAY;
-            for (const [index, operation] of operations.entries()) {
-                const docRef = doc(firestore, operation.path);
-                switch (operation.type) {
-                    case 'set': {
-                        if (!operation.data) {
-                            throw new Error('Data is required for set operation');
-                        }
-                        const dataToSet = {
-                            ...operation.data,
-                            ...(operation.options?.timestamps && this.getTimestampData()),
-                            id: docRef.id
-                        };
-                        batch.set(docRef, dataToSet, {
-                            merge: operation.options?.merge
-                        });
-                        break;
-                    }
-                    case 'update': {
-                        if (!operation.data) {
-                            throw new Error('Data is required for update operation');
-                        }
-                        const dataToUpdate = {
-                            ...operation.data,
-                            ...(operation.options?.timestamps && this.getTimestampData(false))
-                        };
-                        batch.update(docRef, dataToUpdate);
-                        break;
-                    }
-                    case 'delete': {
-                        batch.delete(docRef);
-                        break;
-                    }
-                    default:
-                        throw new Error(`Invalid operation type: ${operation.type}`);
-                }
-                batchCounter++;
-                // If batch limit reached or last item, commit and create new batch
-                if (batchCounter === batchLimit || index === operations.length - 1) {
-                    await batch.commit();
-                    console.log(`Batch committed at index ${index} of ${operations.length} operations.`);
-                    if (index < operations.length - 1) {
-                        batch = writeBatch(firestore);
-                        batchCounter = 0;
-                        await this.delay(batchDelay);
-                    }
-                }
-            }
-            return {
-                success: true,
-                processedItems: operations.length
-            };
-        }
-        catch (error) {
-            return this.handleError(error);
-        }
-    }
-    /**
-     * Inserts multiple items into a collection using batched writes
-     * @template T Document data type
-     * @param {string} collectionPath Collection path
-     * @param {T[]} items Array of items to insert
-     * @param {BatchMutationOptions} [options] Batch options
-     * @param {string} [idKey] Optional key to use as document ID from items
-     * @returns {Promise<BatchResponse>} Batch operation response
-     *
-     * @example
-     * ```typescript
-     * const items = [
-     *   { id: 'nyc', name: 'New York City' },
-     *   { id: 'sf', name: 'San Francisco' }
-     * ];
-     *
-     * const result = await firekitBatchMutations.batchInsert(
-     *   'cities',
-     *   items,
-     *   { timestamps: true },
-     *   'id'
-     * );
-     * ```
-     */
-    async batchInsert(collectionPath, items, options = { timestamps: true }, idKey) {
-        try {
-            const firestore = firebaseService.getDbInstance();
-            let batch = writeBatch(firestore);
-            let batchCounter = 0;
-            const batchLimit = options.batchSize || this.DEFAULT_BATCH_LIMIT;
-            const batchDelay = options.delayBetweenBatches || this.DEFAULT_BATCH_DELAY;
-            for (const [index, item] of items.entries()) {
-                const docRef = idKey && item[idKey]
-                    ? doc(firestore, collectionPath, item[idKey])
-                    : doc(collection(firestore, collectionPath));
-                const dataToSet = {
-                    ...item,
-                    ...(options.timestamps && this.getTimestampData()),
-                    id: docRef.id
-                };
-                batch.set(docRef, dataToSet, { merge: options.merge });
-                batchCounter++;
-                // If batch limit reached or last item, commit and create new batch
-                if (batchCounter === batchLimit || index === items.length - 1) {
-                    await batch.commit();
-                    console.log(`Batch committed at index ${index} of ${items.length} items.`);
-                    if (index < items.length - 1) {
-                        batch = writeBatch(firestore);
-                        batchCounter = 0;
-                        await this.delay(batchDelay);
-                    }
-                }
-            }
-            return {
-                success: true,
-                processedItems: items.length
-            };
-        }
-        catch (error) {
-            return this.handleError(error);
-        }
-    }
-}
-/**
- * Pre-initialized instance of FirekitBatchMutations
- * @const
- * @type {FirekitBatchMutations}
- */
-export const firekitBatchMutations = new FirekitBatchMutations();