svelte-firekit 0.0.22 → 0.0.24

package/README.md

@@ -1,221 +1,213 @@
----
-slug: docs
-title: Welcome to Svelte Firekit
-description: a comprehensive library integrating SvelteKit and Firebase for building robust micro SaaS applications.
----
- 
-## Introduction to Svelte Firekit
- 
-Svelte Firekit is a powerful Firebase toolkit for SvelteKit applications, providing a comprehensive set of utilities, stores, and components for seamless Firebase integration. Whether you're building a micro SaaS, web application, or any Firebase-powered project, Svelte Firekit streamlines your development process.
- 
-## Installation
- 
-```bash
-npm install firebase svelte-firekit
-```
- 
-## Configuration
- 
-Svelte Firekit automatically manages your Firebase configuration through environment variables. Create a `.env` file in your project root with the following variables:
- 
-```env
-PUBLIC_FIREBASE_API_KEY=your_api_key
-PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
-PUBLIC_FIREBASE_PROJECT_ID=your_project_id
-PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
-PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
-PUBLIC_FIREBASE_APP_ID=your_app_id
-PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id
-```
- 
-The configuration is automatically handled by Firekit - no manual setup required. If any required environment variables are missing, Firekit will throw a helpful error indicating which variables need to be set.
- 
-## Usage Example
- 
-Here's a simple example showing how to display the current user's name:
- 
-```svelte
-<script>
-  import { firekitUser } from 'svelte-firekit';
-</script>
- 
-Hello {firekitUser.displayName}
-```
- 
-The `firekitUser` store provides access to the current user's information and authentication state.
- 
-## Core Features
- 
-### 🔥 Firebase Integration
-- Zero-config Firebase setup through environment variables
-- Automatic initialization and app management
-- Built-in error handling and connection state management
-- Type-safe configuration management
- 
-### 🔐 Authentication
-- Complete authentication system with built-in components
-- Support for multiple authentication providers:
-  - Email/Password
-  - Google
-  - GitHub
-  - Custom providers
-- User state management and persistence through `firekitUser` store
- 
-### 📚 Firestore Integration
-- Reactive data stores for real-time updates
-- Simplified CRUD operations
-- Batch operations and transactions
-- Type-safe document references
-- Automatic data serialization/deserialization
- 
-### 📦 Storage Management
-- File upload and download utilities
-- Progress tracking and status updates
-- Storage security rules helpers
-- Image optimization utilities
- 
-### ⚡ Server-Side Rendering
-- Full SSR compatibility
-- Hydration support
-- Server-side data fetching
-- SEO-friendly rendering
- 
-### 🎯 Type Safety
-- Built with TypeScript
-- Complete type definitions
-- Intelligent autocomplete
-- Runtime type checking
-- Type-safe Firestore operations
- 
-## Why Svelte Firekit?
- 
-- **Zero Configuration**: Automatic Firebase setup through environment variables
-- **Type Safety**: Full TypeScript support with built-in type checking
-- **Rapid Development**: Get your Firebase-powered SvelteKit application up and running in minutes
-- **Best Practices**: Built following Firebase and SvelteKit best practices
-- **Production Ready**: Battle-tested in production environments
-- **Active Community**: Regular updates and active community support
-- **Extensible**: Easy to customize and extend for your specific needs
- 
-## Next Steps
- 
-- Check out our [Getting Started](/getting-started) guide
-- Explore the [API Reference](/api)
-- View [Examples](/examples)
-- Join our [Community](/community)
- 
-## Contributing
- 
-We welcome contributions! Please see our [Contributing Guide](/contributing) for more details.
- 
-## License
- 
-Svelte Firekit is released under the MIT License. See the [LICENSE](/license) file for more details.
- 
-# Authentication
- 
-Svelte Firekit provides a comprehensive authentication system through the `firekitAuth` singleton, offering various authentication methods and user management features.
- 
-## Basic Usage
- 
-```typescript
-import { firekitAuth } from 'svelte-firekit';
-```
- 
-## Authentication Methods
- 
-### Google Authentication
- 
-```typescript
-await firekitAuth.signInWithGoogle();
-```
- 
-### Email/Password Authentication
- 
-```typescript
-// Sign in
-await firekitAuth.signInWithEmail(email, password);
- 
-// Register
-await firekitAuth.registerWithEmail(email, password, displayName);
- 
-// Sign out
-await firekitAuth.logOut();
-```
- 
-## User Management
- 
-### Password Management
- 
-```typescript
-// Send password reset email
-await firekitAuth.sendPasswordReset(email);
- 
-// Update password (requires reauthentication)
-await firekitAuth.updateUserPassword(newPassword, currentPassword);
-```
- 
-### Profile Management
- 
-```typescript
-// Update user profile
-await firekitAuth.updateUserProfile({
-  displayName: "New Name",
-  photoURL: "https://example.com/photo.jpg"
-});
-```
- 
-### Email Verification
- 
-```typescript
-// Send verification email
-await firekitAuth.sendEmailVerificationToUser();
-```
- 
-### Account Deletion
- 
-```typescript
-// Delete user account
-await firekitAuth.deleteUserAccount();
-```
- 
-## Automatic Firestore Integration
- 
-The authentication system automatically maintains a user document in Firestore with the following information:
-- User ID
-- Email
-- Email verification status
-- Display name
-- Photo URL
-- Authentication provider information
-- Anonymous status
- 
-## Error Handling
- 
-All methods include proper error handling and return appropriate error messages. For example, password updates will return:
- 
-```typescript
-{
-  success: boolean;
-  message: string;
-  code?: string; // In case of errors
-}
-```
- 
-## Features
- 
-- 🔐 Multiple authentication providers
-- 📝 Automatic user profile management
-- 🔄 Password reset and update functionality
-- ✉️ Email verification
-- 🗑️ Account deletion
-- 🔄 Reauthentication support
-- 📚 Automatic Firestore user document management
-- ⚡ Type-safe operations
- 
-## Important Notes
- 
-1. User data is automatically synchronized with Firestore
-2. Password updates require current password verification
-3. Account deletion removes both authentication and Firestore data
+Svelte Firekit is a powerful Firebase toolkit for SvelteKit applications, providing a comprehensive set of utilities, stores, and components for seamless Firebase integration. Whether you're building a micro SaaS, web application, or any Firebase-powered project, Svelte Firekit streamlines your development process.
+ 
+## Installation
+ 
+```bash
+npm install firebase svelte-firekit
+```
+ 
+## Configuration
+ 
+Svelte Firekit automatically manages your Firebase configuration through environment variables. Create a `.env` file in your project root with the following variables:
+ 
+```env
+PUBLIC_FIREBASE_API_KEY=your_api_key
+PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
+PUBLIC_FIREBASE_PROJECT_ID=your_project_id
+PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
+PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
+PUBLIC_FIREBASE_APP_ID=your_app_id
+PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id
+```
+ 
+The configuration is automatically handled by Firekit - no manual setup required. If any required environment variables are missing, Firekit will throw a helpful error indicating which variables need to be set.
+ 
+## Usage Example
+ 
+Here's a simple example showing how to display the current user's name:
+ 
+```svelte
+<script>
+  import { firekitUser } from 'svelte-firekit';
+</script>
+ 
+Hello {firekitUser.displayName}
+```
+ 
+The `firekitUser` store provides access to the current user's information and authentication state.
+ 
+## Core Features
+ 
+### 🔥 Firebase Integration
+- Zero-config Firebase setup through environment variables
+- Automatic initialization and app management
+- Built-in error handling and connection state management
+- Type-safe configuration management
+ 
+### 🔐 Authentication
+- Complete authentication system with built-in components
+- Support for multiple authentication providers:
+  - Email/Password
+  - Google
+  - GitHub
+  - Custom providers
+- User state management and persistence through `firekitUser` store
+ 
+### 📚 Firestore Integration
+- Reactive data stores for real-time updates
+- Simplified CRUD operations
+- Batch operations and transactions
+- Type-safe document references
+- Automatic data serialization/deserialization
+ 
+### 📦 Storage Management
+- File upload and download utilities
+- Progress tracking and status updates
+- Storage security rules helpers
+- Image optimization utilities
+ 
+### ⚡ Server-Side Rendering
+- Full SSR compatibility
+- Hydration support
+- Server-side data fetching
+- SEO-friendly rendering
+ 
+### 🎯 Type Safety
+- Built with TypeScript
+- Complete type definitions
+- Intelligent autocomplete
+- Runtime type checking
+- Type-safe Firestore operations
+ 
+## Why Svelte Firekit?
+ 
+- **Zero Configuration**: Automatic Firebase setup through environment variables
+- **Type Safety**: Full TypeScript support with built-in type checking
+- **Rapid Development**: Get your Firebase-powered SvelteKit application up and running in minutes
+- **Best Practices**: Built following Firebase and SvelteKit best practices
+- **Production Ready**: Battle-tested in production environments
+- **Active Community**: Regular updates and active community support
+- **Extensible**: Easy to customize and extend for your specific needs
+ 
+## Next Steps
+ 
+- Check out our [Getting Started](/getting-started) guide
+- Explore the [API Reference](/api)
+- View [Examples](/examples)
+- Join our [Community](/community)
+ 
+## Contributing
+ 
+We welcome contributions! Please see our [Contributing Guide](/contributing) for more details.
+ 
+## License
+ 
+Svelte Firekit is released under the MIT License. See the [LICENSE](/license) file for more details.
+ 
+# Authentication
+ 
+Svelte Firekit provides a comprehensive authentication system through the `firekitAuth` singleton, offering various authentication methods and user management features.
+ 
+## Basic Usage
+ 
+```typescript
+import { firekitAuth } from 'svelte-firekit';
+```
+ 
+## Authentication Methods
+ 
+### Google Authentication
+ 
+```typescript
+await firekitAuth.signInWithGoogle();
+```
+ 
+### Email/Password Authentication
+ 
+```typescript
+// Sign in
+await firekitAuth.signInWithEmail(email, password);
+ 
+// Register
+await firekitAuth.registerWithEmail(email, password, displayName);
+ 
+// Sign out
+await firekitAuth.logOut();
+```
+ 
+## User Management
+ 
+### Password Management
+ 
+```typescript
+// Send password reset email
+await firekitAuth.sendPasswordReset(email);
+ 
+// Update password (requires reauthentication)
+await firekitAuth.updateUserPassword(newPassword, currentPassword);
+```
+ 
+### Profile Management
+ 
+```typescript
+// Update user profile
+await firekitAuth.updateUserProfile({
+  displayName: "New Name",
+  photoURL: "https://example.com/photo.jpg"
+});
+```
+ 
+### Email Verification
+ 
+```typescript
+// Send verification email
+await firekitAuth.sendEmailVerificationToUser();
+```
+ 
+### Account Deletion
+ 
+```typescript
+// Delete user account
+await firekitAuth.deleteUserAccount();
+```
+ 
+## Automatic Firestore Integration
+ 
+The authentication system automatically maintains a user document in Firestore with the following information:
+- User ID
+- Email
+- Email verification status
+- Display name
+- Photo URL
+- Authentication provider information
+- Anonymous status
+ 
+## Error Handling
+ 
+All methods include proper error handling and return appropriate error messages. For example, password updates will return:
+ 
+```typescript
+{
+  success: boolean;
+  message: string;
+  code?: string; // In case of errors
+}
+```
+ 
+## Features
+ 
+- 🔐 Multiple authentication providers
+- 📝 Automatic user profile management
+- 🔄 Password reset and update functionality
+- ✉️ Email verification
+- 🗑️ Account deletion
+- 🔄 Reauthentication support
+- 📚 Automatic Firestore user document management
+- ⚡ Type-safe operations
+ 
+## Important Notes
+ 
+1. User data is automatically synchronized with Firestore
+2. Password updates require current password verification
+3. Account deletion removes both authentication and Firestore data
 4. All operations are fully typed for TypeScript support 

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

@@ -0,0 +1,140 @@
+/**
+ * @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.svelte.js

@@ -0,0 +1,218 @@
+/**
+ * @module FirekitBatchMutations
+ */
+import { doc, setDoc, updateDoc, deleteDoc, getDoc, 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();

package/dist/firestore/collection-group.svelte.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @module FirekitCollectionGroup
+ */
+import { type Query, type DocumentData, type QueryConstraint } from "firebase/firestore";
+/**
+ * Manages real-time Firestore collection group subscriptions with reactive state
+ * @class
+ * @template T Collection document type
+ *
+ * @example
+ * ```typescript
+ * interface Task {
+ *   id: string;
+ *   title: string;
+ *   status: string;
+ * }
+ *
+ * // Create collection group subscription
+ * const allTasks = firekitCollectionGroup<Task>('tasks',
+ *   where('status', '==', 'active'),
+ *   orderBy('title')
+ * );
+ * ```
+ */
+declare class FirekitCollectionGroup<T> {
+    /** Current collection group data */
+    private _data;
+    /** Loading state */
+    private _loading;
+    /** Error state */
+    private _error;
+    /** Query reference */
+    private queryRef;
+    /**
+     * Creates a collection group subscription
+     * @param {string} collectionId Collection ID to query across all documents
+     * @param {...QueryConstraint[]} queryConstraints Query constraints (where, orderBy, limit, etc.)
+     */
+    constructor(collectionId: string, ...queryConstraints: QueryConstraint[]);
+    /** Gets current collection group data */
+    get data(): T[];
+    /** Gets loading state */
+    get loading(): boolean;
+    /** Gets error state */
+    get error(): Error | null;
+    /** Checks if collection group is empty */
+    get empty(): boolean;
+    /** Gets number of documents in collection group */
+    get size(): number;
+    /**
+     * Gets query reference
+     * @throws {Error} If query reference is not available
+     */
+    get ref(): Query<T>;
+}
+/**
+ * Creates a collection group subscription
+ * @template T Collection document type
+ * @param {string} collectionId Collection ID to query across all documents
+ * @param {...QueryConstraint[]} queryConstraints Query constraints
+ * @returns {FirekitCollectionGroup<T>} Collection group subscription instance
+ *
+ * @example
+ * ```typescript
+ * interface Comment {
+ *   id: string;
+ *   text: string;
+ *   userId: string;
+ * }
+ *
+ * const allComments = firekitCollectionGroup<Comment>('comments',
+ *   where('userId', '==', currentUserId),
+ *   orderBy('createdAt', 'desc')
+ * );
+ * ```
+ */
+export declare function firekitCollectionGroup<T extends DocumentData>(collectionId: string, ...queryConstraints: QueryConstraint[]): FirekitCollectionGroup<T>;
+export {};

package/dist/firestore/collection-group.svelte.js

@@ -0,0 +1,120 @@
+/**
+ * @module FirekitCollectionGroup
+ */
+import { collectionGroup, query, onSnapshot } from "firebase/firestore";
+import { firebaseService } from "../firebase.js";
+import { browser } from "$app/environment";
+/**
+ * Manages real-time Firestore collection group subscriptions with reactive state
+ * @class
+ * @template T Collection document type
+ *
+ * @example
+ * ```typescript
+ * interface Task {
+ *   id: string;
+ *   title: string;
+ *   status: string;
+ * }
+ *
+ * // Create collection group subscription
+ * const allTasks = firekitCollectionGroup<Task>('tasks',
+ *   where('status', '==', 'active'),
+ *   orderBy('title')
+ * );
+ * ```
+ */
+class FirekitCollectionGroup {
+    /** Current collection group data */
+    _data = $state([]);
+    /** Loading state */
+    _loading = $state(true);
+    /** Error state */
+    _error = $state(null);
+    /** Query reference */
+    queryRef = null;
+    /**
+     * Creates a collection group subscription
+     * @param {string} collectionId Collection ID to query across all documents
+     * @param {...QueryConstraint[]} queryConstraints Query constraints (where, orderBy, limit, etc.)
+     */
+    constructor(collectionId, ...queryConstraints) {
+        if (browser) {
+            try {
+                const firestore = firebaseService.getDbInstance();
+                const groupRef = collectionGroup(firestore, collectionId);
+                this.queryRef = query(groupRef, ...queryConstraints);
+                onSnapshot(this.queryRef, (snapshot) => {
+                    this._data = snapshot.docs.map(doc => ({
+                        id: doc.id,
+                        path: doc.ref.path,
+                        ...doc.data()
+                    }));
+                    this._loading = false;
+                    this._error = null;
+                }, (error) => {
+                    this._error = error;
+                    this._loading = false;
+                });
+            }
+            catch (error) {
+                this._error = error;
+                this._loading = false;
+            }
+        }
+    }
+    /** Gets current collection group data */
+    get data() {
+        return this._data;
+    }
+    /** Gets loading state */
+    get loading() {
+        return this._loading;
+    }
+    /** Gets error state */
+    get error() {
+        return this._error;
+    }
+    /** Checks if collection group is empty */
+    get empty() {
+        return this._data.length === 0;
+    }
+    /** Gets number of documents in collection group */
+    get size() {
+        return this._data.length;
+    }
+    /**
+     * Gets query reference
+     * @throws {Error} If query reference is not available
+     */
+    get ref() {
+        if (!this.queryRef) {
+            throw new Error("Query reference is not available");
+        }
+        return this.queryRef;
+    }
+}
+/**
+ * Creates a collection group subscription
+ * @template T Collection document type
+ * @param {string} collectionId Collection ID to query across all documents
+ * @param {...QueryConstraint[]} queryConstraints Query constraints
+ * @returns {FirekitCollectionGroup<T>} Collection group subscription instance
+ *
+ * @example
+ * ```typescript
+ * interface Comment {
+ *   id: string;
+ *   text: string;
+ *   userId: string;
+ * }
+ *
+ * const allComments = firekitCollectionGroup<Comment>('comments',
+ *   where('userId', '==', currentUserId),
+ *   orderBy('createdAt', 'desc')
+ * );
+ * ```
+ */
+export function firekitCollectionGroup(collectionId, ...queryConstraints) {
+    return new FirekitCollectionGroup(collectionId, ...queryConstraints);
+}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { firekitAwaitableDoc } from './firestore/awaitable-doc.svelte.js';
 export { firekitDocMutations } from './firestore/document-mutations.svelte.js';
 export { firekitCollection } from './firestore/collection.svelte.js';
 export { firekitDoc } from './firestore/doc.svelte.js';
+export { firekitCollectionGroup } from './firestore/collection-group.svelte.js';
 export { firekitRealtimeDB } from './realtime/realtime.svelte.js';
 export { firekitDownloadUrl } from './storage/download-url.svelte.js';
 export { firekitStorageList } from './storage/storage-list.svelte.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export { firekitAwaitableDoc } from './firestore/awaitable-doc.svelte.js';
 export { firekitDocMutations } from './firestore/document-mutations.svelte.js';
 export { firekitCollection } from './firestore/collection.svelte.js';
 export { firekitDoc } from './firestore/doc.svelte.js';
+export { firekitCollectionGroup } from './firestore/collection-group.svelte.js';
 // realtime services
 export { firekitRealtimeDB } from './realtime/realtime.svelte.js';
 // Storage services

package/package.json

@@ -1,65 +1,65 @@
-{
-	"name": "svelte-firekit",
-	"version": "0.0.22",
-	"license": "MIT",
-	"scripts": {
-		"dev": "vite dev",
-		"build": "vite build && npm run package",
-		"preview": "vite preview",
-		"package": "svelte-kit sync && svelte-package && publint",
-		"prepublishOnly": "npm run package",
-		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
-		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
-		"format": "prettier --write .",
-		"lint": "prettier --check ."
-	},
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/code-gio/svelte-firekit.git"
-	},
-	"description": "A Svelte library for Firebase integration",
-	"keywords": [
-		"svelte",
-		"firebase",
-		"library",
-		"frontend"
-	],
-	"author": "Giovani Rodriguez",
-	"files": [
-		"dist",
-		"!dist/**/*.test.*",
-		"!dist/**/*.spec.*"
-	],
-	"sideEffects": [
-		"**/*.css"
-	],
-	"svelte": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"type": "module",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"svelte": "./dist/index.js"
-		}
-	},
-	"peerDependencies": {
-		"firebase": "^11.0.1",
-		"svelte": "^5.0.0"
-	},
-	"devDependencies": {
-		"@sveltejs/adapter-auto": "^3.0.0",
-		"@sveltejs/kit": "^2.9.0",
-		"@sveltejs/package": "^2.0.0",
-		"@sveltejs/vite-plugin-svelte": "^5.0.0",
-		"prettier": "^3.3.2",
-		"prettier-plugin-svelte": "^3.2.6",
-		"publint": "^0.2.0",
-		"svelte": "^5.0.0",
-		"svelte-check": "^4.0.0",
-		"typescript": "^5.0.0",
-		"vite": "^6.0.0"
-	},
-	"dependencies": {
-		"firebase": "^11.0.2"
-	}
+{
+	"name": "svelte-firekit",
+	"version": "0.0.24",
+	"license": "MIT",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && npm run package",
+		"preview": "vite preview",
+		"package": "svelte-kit sync && svelte-package && publint",
+		"prepublishOnly": "npm run package",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"format": "prettier --write .",
+		"lint": "prettier --check ."
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/code-gio/svelte-firekit.git"
+	},
+	"description": "A Svelte library for Firebase integration",
+	"keywords": [
+		"svelte",
+		"firebase",
+		"library",
+		"frontend"
+	],
+	"author": "Giovani Rodriguez",
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"firebase": "^11.0.1",
+		"svelte": "^5.0.0"
+	},
+	"devDependencies": {
+		"@sveltejs/adapter-auto": "^3.0.0",
+		"@sveltejs/kit": "^2.9.0",
+		"@sveltejs/package": "^2.0.0",
+		"@sveltejs/vite-plugin-svelte": "^5.0.0",
+		"prettier": "^3.3.2",
+		"prettier-plugin-svelte": "^3.2.6",
+		"publint": "^0.2.0",
+		"svelte": "^5.0.0",
+		"svelte-check": "^4.0.0",
+		"typescript": "^5.0.0",
+		"vite": "^6.0.0"
+	},
+	"dependencies": {
+		"firebase": "^11.0.2"
+	}
 }