svelte-firekit 0.0.25 → 0.1.0

package/dist/types/auth.js

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Authentication types and interfaces for FirekitAuth
+ * @module AuthTypes
+ * @version 1.0.0
+ */
+/**
+ * Authentication error codes enum
+ */
+export var AuthErrorCode;
+(function (AuthErrorCode) {
+    AuthErrorCode["EMAIL_ALREADY_IN_USE"] = "auth/email-already-in-use";
+    AuthErrorCode["INVALID_EMAIL"] = "auth/invalid-email";
+    AuthErrorCode["USER_NOT_FOUND"] = "auth/user-not-found";
+    AuthErrorCode["WRONG_PASSWORD"] = "auth/wrong-password";
+    AuthErrorCode["WEAK_PASSWORD"] = "auth/weak-password";
+    AuthErrorCode["TOO_MANY_REQUESTS"] = "auth/too-many-requests";
+    AuthErrorCode["POPUP_CLOSED"] = "auth/popup-closed-by-user";
+    AuthErrorCode["NETWORK_REQUEST_FAILED"] = "auth/network-request-failed";
+    AuthErrorCode["USER_DISABLED"] = "auth/user-disabled";
+    AuthErrorCode["OPERATION_NOT_ALLOWED"] = "auth/operation-not-allowed";
+    AuthErrorCode["INVALID_VERIFICATION_CODE"] = "auth/invalid-verification-code";
+    AuthErrorCode["INVALID_VERIFICATION_ID"] = "auth/invalid-verification-id";
+    AuthErrorCode["REQUIRES_RECENT_LOGIN"] = "auth/requires-recent-login";
+    AuthErrorCode["EXPIRED_ACTION_CODE"] = "auth/expired-action-code";
+    AuthErrorCode["INVALID_ACTION_CODE"] = "auth/invalid-action-code";
+    AuthErrorCode["MISSING_EMAIL"] = "auth/missing-email";
+    AuthErrorCode["MISSING_PASSWORD"] = "auth/missing-password";
+    AuthErrorCode["INVALID_PHONE_NUMBER"] = "auth/invalid-phone-number";
+    AuthErrorCode["MISSING_PHONE_NUMBER"] = "auth/missing-phone-number";
+    AuthErrorCode["QUOTA_EXCEEDED"] = "auth/quota-exceeded";
+    AuthErrorCode["APP_NOT_AUTHORIZED"] = "auth/app-not-authorized";
+    AuthErrorCode["KEYBOARD_NOT_SUPPORTED"] = "auth/keychain-error";
+    AuthErrorCode["INTERNAL_ERROR"] = "auth/internal-error";
+})(AuthErrorCode || (AuthErrorCode = {}));
+/**
+ * Custom authentication error class
+ */
+export class FirekitAuthError extends Error {
+    code;
+    originalError;
+    constructor(code, message, originalError) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = 'FirekitAuthError';
+    }
+    /**
+     * Get user-friendly error message
+     */
+    getFriendlyMessage() {
+        switch (this.code) {
+            case AuthErrorCode.EMAIL_ALREADY_IN_USE:
+                return 'An account with this email already exists.';
+            case AuthErrorCode.INVALID_EMAIL:
+                return 'Please enter a valid email address.';
+            case AuthErrorCode.USER_NOT_FOUND:
+                return 'No account found with this email address.';
+            case AuthErrorCode.WRONG_PASSWORD:
+                return 'Incorrect password. Please try again.';
+            case AuthErrorCode.WEAK_PASSWORD:
+                return 'Password should be at least 6 characters long.';
+            case AuthErrorCode.TOO_MANY_REQUESTS:
+                return 'Too many failed attempts. Please try again later.';
+            case AuthErrorCode.POPUP_CLOSED:
+                return 'Sign-in was cancelled. Please try again.';
+            case AuthErrorCode.NETWORK_REQUEST_FAILED:
+                return 'Network error. Please check your connection.';
+            case AuthErrorCode.USER_DISABLED:
+                return 'This account has been disabled.';
+            case AuthErrorCode.REQUIRES_RECENT_LOGIN:
+                return 'Please sign in again to complete this action.';
+            case AuthErrorCode.EXPIRED_ACTION_CODE:
+                return 'This action code has expired. Please request a new one.';
+            case AuthErrorCode.INVALID_ACTION_CODE:
+                return 'Invalid action code. Please check and try again.';
+            case AuthErrorCode.MISSING_EMAIL:
+                return 'Email address is required.';
+            case AuthErrorCode.MISSING_PASSWORD:
+                return 'Password is required.';
+            case AuthErrorCode.INVALID_PHONE_NUMBER:
+                return 'Please enter a valid phone number.';
+            case AuthErrorCode.MISSING_PHONE_NUMBER:
+                return 'Phone number is required.';
+            case AuthErrorCode.QUOTA_EXCEEDED:
+                return 'SMS quota exceeded. Please try again later.';
+            case AuthErrorCode.APP_NOT_AUTHORIZED:
+                return 'This app is not authorized to use Firebase Authentication.';
+            case AuthErrorCode.INTERNAL_ERROR:
+                return 'An internal error occurred. Please try again.';
+            default:
+                return this.message;
+        }
+    }
+    /**
+     * Check if error is retryable
+     */
+    isRetryable() {
+        const retryableCodes = [
+            AuthErrorCode.NETWORK_REQUEST_FAILED,
+            AuthErrorCode.TOO_MANY_REQUESTS,
+            AuthErrorCode.QUOTA_EXCEEDED,
+            AuthErrorCode.INTERNAL_ERROR
+        ];
+        return retryableCodes.includes(this.code);
+    }
+}

package/dist/types/collection.d.ts

@@ -0,0 +1,360 @@
+/**
+ * @fileoverview Collection types and interfaces for FirekitCollection
+ * @module CollectionTypes
+ * @version 1.0.0
+ */
+import type { QueryConstraint } from 'firebase/firestore';
+/**
+ * Collection state interface containing all reactive properties
+ */
+export interface CollectionState<T> {
+    /** Array of documents in the collection */
+    data: T[];
+    /** Loading state indicator */
+    loading: boolean;
+    /** Whether collection has been initialized */
+    initialized: boolean;
+    /** Current error state */
+    error: CollectionError | null;
+    /** Whether collection is empty */
+    empty: boolean;
+    /** Number of documents */
+    size: number;
+    /** Last update timestamp */
+    lastUpdated: Date | null;
+}
+/**
+ * Collection configuration options
+ */
+export interface CollectionOptions {
+    /** Enable real-time updates (default: true) */
+    realtime?: boolean;
+    /** Include metadata changes in updates (default: false) */
+    includeMetadata?: boolean;
+    /** Data source preference (default: 'default') */
+    source?: 'default' | 'server' | 'cache';
+    /** Transform function for documents */
+    transform?: (doc: any) => any;
+    /** Filter function for documents */
+    filter?: (doc: any) => boolean;
+    /** Sort function for documents */
+    sort?: (a: any, b: any) => number;
+    /** Pagination settings */
+    pagination?: PaginationConfig;
+    /** Cache configuration */
+    cache?: CacheConfig;
+    /** Error handling configuration */
+    errorHandling?: ErrorHandlingConfig;
+}
+/**
+ * Pagination configuration
+ */
+export interface PaginationConfig {
+    /** Enable pagination */
+    enabled: boolean;
+    /** Page size */
+    pageSize: number;
+    /** Current page number */
+    currentPage: number;
+    /** Auto-load next page when scrolling */
+    autoLoad?: boolean;
+    /** Cursor for pagination */
+    cursor?: any;
+}
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+    /** Enable caching */
+    enabled: boolean;
+    /** Cache duration in milliseconds */
+    ttl: number;
+    /** Maximum cache size */
+    maxSize?: number;
+    /** Cache key strategy */
+    keyStrategy?: 'path' | 'query' | 'custom';
+    /** Custom cache key function */
+    customKey?: (path: string, constraints: QueryConstraint[]) => string;
+}
+/**
+ * Error handling configuration
+ */
+export interface ErrorHandlingConfig {
+    /** Enable automatic retry on errors */
+    autoRetry?: boolean;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+    /** Retry delay in milliseconds */
+    retryDelay?: number;
+    /** Custom error handler */
+    onError?: (error: CollectionError) => void;
+}
+/**
+ * Query constraint builder interface
+ */
+export interface QueryBuilder<T> {
+    /** Add where constraint */
+    where(field: string, operator: FirestoreOperator, value: any): QueryBuilder<T>;
+    /** Add orderBy constraint */
+    orderBy(field: string, direction?: 'asc' | 'desc'): QueryBuilder<T>;
+    /** Add limit constraint */
+    limit(count: number): QueryBuilder<T>;
+    /** Add startAt constraint */
+    startAt(...values: any[]): QueryBuilder<T>;
+    /** Add startAfter constraint */
+    startAfter(...values: any[]): QueryBuilder<T>;
+    /** Add endAt constraint */
+    endAt(...values: any[]): QueryBuilder<T>;
+    /** Add endBefore constraint */
+    endBefore(...values: any[]): QueryBuilder<T>;
+    /** Build the query */
+    build(): QueryConstraint[];
+}
+/**
+ * Firestore query operators
+ */
+export type FirestoreOperator = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in';
+/**
+ * Collection change types
+ */
+export type CollectionChangeType = 'added' | 'modified' | 'removed';
+/**
+ * Document change information
+ */
+export interface DocumentChange<T> {
+    /** Type of change */
+    type: CollectionChangeType;
+    /** Document data */
+    doc: T;
+    /** Old index in collection */
+    oldIndex: number;
+    /** New index in collection */
+    newIndex: number;
+    /** Change timestamp */
+    timestamp: Date;
+}
+/**
+ * Collection event types
+ */
+export type CollectionEventType = 'data_changed' | 'document_added' | 'document_modified' | 'document_removed' | 'error' | 'loading_started' | 'loading_finished' | 'query_changed' | 'cache_hit' | 'cache_miss';
+/**
+ * Collection event interface
+ */
+export interface CollectionEvent<T> {
+    /** Event type */
+    type: CollectionEventType;
+    /** Event data */
+    data?: any;
+    /** Document changes */
+    changes?: DocumentChange<T>[];
+    /** Error if applicable */
+    error?: CollectionError;
+    /** Event timestamp */
+    timestamp: Date;
+    /** Collection path */
+    path?: string;
+}
+/**
+ * Collection event callback function type
+ */
+export type CollectionEventCallback<T> = (event: CollectionEvent<T>) => void;
+/**
+ * Collection metadata interface
+ */
+export interface CollectionMetadata {
+    /** Whether data is from cache */
+    fromCache: boolean;
+    /** Whether there are pending writes */
+    hasPendingWrites: boolean;
+    /** Sync state */
+    syncState: 'synced' | 'local' | 'unknown';
+    /** Last sync timestamp */
+    lastSyncTime?: Date;
+}
+/**
+ * Collection statistics
+ */
+export interface CollectionStats {
+    /** Total number of documents */
+    totalDocuments: number;
+    /** Number of read operations */
+    readCount: number;
+    /** Number of write operations */
+    writeCount: number;
+    /** Cache hit rate */
+    cacheHitRate: number;
+    /** Average query time */
+    averageQueryTime: number;
+    /** Last activity timestamp */
+    lastActivity: Date;
+    /** Memory usage in bytes */
+    memoryUsage: number;
+}
+/**
+ * Collection error codes enum
+ */
+export declare enum CollectionErrorCode {
+    PERMISSION_DENIED = "collection/permission-denied",
+    NOT_FOUND = "collection/not-found",
+    ALREADY_EXISTS = "collection/already-exists",
+    RESOURCE_EXHAUSTED = "collection/resource-exhausted",
+    FAILED_PRECONDITION = "collection/failed-precondition",
+    ABORTED = "collection/aborted",
+    OUT_OF_RANGE = "collection/out-of-range",
+    UNIMPLEMENTED = "collection/unimplemented",
+    INTERNAL_ERROR = "collection/internal",
+    UNAVAILABLE = "collection/unavailable",
+    DATA_LOSS = "collection/data-loss",
+    UNAUTHENTICATED = "collection/unauthenticated",
+    DEADLINE_EXCEEDED = "collection/deadline-exceeded",
+    CANCELLED = "collection/cancelled",
+    NETWORK_ERROR = "collection/network-error",
+    OFFLINE = "collection/offline",
+    INVALID_QUERY = "collection/invalid-query",
+    QUERY_TOO_COMPLEX = "collection/query-too-complex",
+    MISSING_INDEX = "collection/missing-index",
+    INVALID_ARGUMENT = "collection/invalid-argument",
+    COLLECTION_UNAVAILABLE = "collection/collection-unavailable",
+    REFERENCE_UNAVAILABLE = "collection/reference-unavailable",
+    LISTENER_ERROR = "collection/listener-error",
+    CACHE_ERROR = "collection/cache-error",
+    CACHE_FULL = "collection/cache-full",
+    CACHE_CORRUPTED = "collection/cache-corrupted",
+    PAGINATION_ERROR = "collection/pagination-error",
+    INVALID_CURSOR = "collection/invalid-cursor",
+    TRANSFORM_ERROR = "collection/transform-error",
+    FILTER_ERROR = "collection/filter-error",
+    UNKNOWN = "collection/unknown"
+}
+/**
+ * Custom collection error class
+ */
+export declare class CollectionError extends Error {
+    code: CollectionErrorCode;
+    path?: string | undefined;
+    query?: QueryConstraint[] | undefined;
+    originalError?: any | undefined;
+    context?: Record<string, any> | undefined;
+    constructor(code: CollectionErrorCode, message: string, path?: string | undefined, query?: QueryConstraint[] | undefined, originalError?: any | undefined, context?: Record<string, any> | undefined);
+    /**
+     * Get user-friendly error message
+     */
+    getFriendlyMessage(): string;
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Check if error requires user authentication
+     */
+    requiresAuth(): boolean;
+    /**
+     * Check if error is related to query issues
+     */
+    isQueryError(): boolean;
+    /**
+     * Check if error is network related
+     */
+    isNetworkError(): boolean;
+    /**
+     * Convert to JSON for logging/debugging
+     */
+    toJSON(): Record<string, any>;
+}
+/**
+ * Collection subscription interface
+ */
+export interface CollectionSubscription {
+    /** Unsubscribe from collection changes */
+    unsubscribe: () => void;
+    /** Whether subscription is active */
+    active: boolean;
+    /** Subscription configuration */
+    config: CollectionOptions;
+    /** Subscription statistics */
+    stats: CollectionStats;
+}
+/**
+ * Collection query result interface
+ */
+export interface CollectionQueryResult<T> {
+    /** Query result documents */
+    docs: T[];
+    /** Query metadata */
+    metadata: CollectionMetadata;
+    /** Total count (if available) */
+    totalCount?: number;
+    /** Whether there are more documents */
+    hasMore?: boolean;
+    /** Next page cursor */
+    nextCursor?: any;
+    /** Previous page cursor */
+    prevCursor?: any;
+}
+/**
+ * Collection aggregation result
+ */
+export interface CollectionAggregation {
+    /** Count of documents */
+    count?: number;
+    /** Sum of numeric field */
+    sum?: number;
+    /** Average of numeric field */
+    average?: number;
+    /** Minimum value */
+    min?: any;
+    /** Maximum value */
+    max?: any;
+    /** Custom aggregation results */
+    custom?: Record<string, any>;
+}
+/**
+ * Real-time collection listener configuration
+ */
+export interface ListenerConfig {
+    /** Include metadata changes */
+    includeMetadata?: boolean;
+    /** Custom error handler */
+    onError?: (error: CollectionError) => void;
+    /** Custom data handler */
+    onData?: (data: any[]) => void;
+    /** Custom change handler */
+    onChange?: (changes: DocumentChange<any>[]) => void;
+    /** Whether to automatically retry on connection issues */
+    autoRetry?: boolean;
+    /** Retry configuration */
+    retryConfig?: {
+        maxAttempts: number;
+        baseDelay: number;
+        maxDelay: number;
+    };
+}
+/**
+ * Collection performance metrics
+ */
+export interface CollectionPerformanceMetrics {
+    /** Query execution time in milliseconds */
+    queryTime: number;
+    /** Network latency */
+    networkLatency: number;
+    /** Cache performance */
+    cachePerformance: {
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /** Memory usage */
+    memoryUsage: {
+        current: number;
+        peak: number;
+        average: number;
+    };
+    /** Document processing time */
+    processingTime: number;
+    /** Listener performance */
+    listenerPerformance: {
+        updateFrequency: number;
+        averageUpdateTime: number;
+        totalUpdates: number;
+    };
+}

package/dist/types/collection.js

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Collection types and interfaces for FirekitCollection
+ * @module CollectionTypes
+ * @version 1.0.0
+ */
+/**
+ * Collection error codes enum
+ */
+export var CollectionErrorCode;
+(function (CollectionErrorCode) {
+    // Firestore errors
+    CollectionErrorCode["PERMISSION_DENIED"] = "collection/permission-denied";
+    CollectionErrorCode["NOT_FOUND"] = "collection/not-found";
+    CollectionErrorCode["ALREADY_EXISTS"] = "collection/already-exists";
+    CollectionErrorCode["RESOURCE_EXHAUSTED"] = "collection/resource-exhausted";
+    CollectionErrorCode["FAILED_PRECONDITION"] = "collection/failed-precondition";
+    CollectionErrorCode["ABORTED"] = "collection/aborted";
+    CollectionErrorCode["OUT_OF_RANGE"] = "collection/out-of-range";
+    CollectionErrorCode["UNIMPLEMENTED"] = "collection/unimplemented";
+    CollectionErrorCode["INTERNAL_ERROR"] = "collection/internal";
+    CollectionErrorCode["UNAVAILABLE"] = "collection/unavailable";
+    CollectionErrorCode["DATA_LOSS"] = "collection/data-loss";
+    CollectionErrorCode["UNAUTHENTICATED"] = "collection/unauthenticated";
+    CollectionErrorCode["DEADLINE_EXCEEDED"] = "collection/deadline-exceeded";
+    CollectionErrorCode["CANCELLED"] = "collection/cancelled";
+    // Network errors
+    CollectionErrorCode["NETWORK_ERROR"] = "collection/network-error";
+    CollectionErrorCode["OFFLINE"] = "collection/offline";
+    // Query errors
+    CollectionErrorCode["INVALID_QUERY"] = "collection/invalid-query";
+    CollectionErrorCode["QUERY_TOO_COMPLEX"] = "collection/query-too-complex";
+    CollectionErrorCode["MISSING_INDEX"] = "collection/missing-index";
+    CollectionErrorCode["INVALID_ARGUMENT"] = "collection/invalid-argument";
+    // Collection errors
+    CollectionErrorCode["COLLECTION_UNAVAILABLE"] = "collection/collection-unavailable";
+    CollectionErrorCode["REFERENCE_UNAVAILABLE"] = "collection/reference-unavailable";
+    CollectionErrorCode["LISTENER_ERROR"] = "collection/listener-error";
+    // Cache errors
+    CollectionErrorCode["CACHE_ERROR"] = "collection/cache-error";
+    CollectionErrorCode["CACHE_FULL"] = "collection/cache-full";
+    CollectionErrorCode["CACHE_CORRUPTED"] = "collection/cache-corrupted";
+    // Pagination errors
+    CollectionErrorCode["PAGINATION_ERROR"] = "collection/pagination-error";
+    CollectionErrorCode["INVALID_CURSOR"] = "collection/invalid-cursor";
+    // Transform/Filter errors
+    CollectionErrorCode["TRANSFORM_ERROR"] = "collection/transform-error";
+    CollectionErrorCode["FILTER_ERROR"] = "collection/filter-error";
+    // Unknown
+    CollectionErrorCode["UNKNOWN"] = "collection/unknown";
+})(CollectionErrorCode || (CollectionErrorCode = {}));
+/**
+ * Custom collection error class
+ */
+export class CollectionError extends Error {
+    code;
+    path;
+    query;
+    originalError;
+    context;
+    constructor(code, message, path, query, originalError, context) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.query = query;
+        this.originalError = originalError;
+        this.context = context;
+        this.name = 'CollectionError';
+    }
+    /**
+     * Get user-friendly error message
+     */
+    getFriendlyMessage() {
+        switch (this.code) {
+            case CollectionErrorCode.PERMISSION_DENIED:
+                return 'You do not have permission to access this collection.';
+            case CollectionErrorCode.NOT_FOUND:
+                return 'The requested collection was not found.';
+            case CollectionErrorCode.NETWORK_ERROR:
+                return 'Network connection error. Please check your internet connection.';
+            case CollectionErrorCode.OFFLINE:
+                return 'You are currently offline. Data may not be up to date.';
+            case CollectionErrorCode.UNAUTHENTICATED:
+                return 'Please sign in to access this collection.';
+            case CollectionErrorCode.UNAVAILABLE:
+                return 'Service is temporarily unavailable. Please try again later.';
+            case CollectionErrorCode.MISSING_INDEX:
+                return 'Database index is missing. Please contact support.';
+            case CollectionErrorCode.QUERY_TOO_COMPLEX:
+                return 'Query is too complex. Please simplify your search.';
+            case CollectionErrorCode.INVALID_QUERY:
+                return 'Invalid query parameters. Please check your search criteria.';
+            case CollectionErrorCode.DEADLINE_EXCEEDED:
+                return 'Request timed out. Please try again.';
+            case CollectionErrorCode.RESOURCE_EXHAUSTED:
+                return 'Too many requests. Please wait a moment and try again.';
+            case CollectionErrorCode.CACHE_ERROR:
+                return 'Cache error occurred. Data will be refreshed.';
+            default:
+                return this.message || 'An unexpected error occurred.';
+        }
+    }
+    /**
+     * Check if error is retryable
+     */
+    isRetryable() {
+        const retryableCodes = [
+            CollectionErrorCode.NETWORK_ERROR,
+            CollectionErrorCode.UNAVAILABLE,
+            CollectionErrorCode.DEADLINE_EXCEEDED,
+            CollectionErrorCode.ABORTED,
+            CollectionErrorCode.INTERNAL_ERROR,
+            CollectionErrorCode.CANCELLED
+        ];
+        return retryableCodes.includes(this.code);
+    }
+    /**
+     * Check if error requires user authentication
+     */
+    requiresAuth() {
+        const authCodes = [CollectionErrorCode.UNAUTHENTICATED, CollectionErrorCode.PERMISSION_DENIED];
+        return authCodes.includes(this.code);
+    }
+    /**
+     * Check if error is related to query issues
+     */
+    isQueryError() {
+        const queryCodes = [
+            CollectionErrorCode.INVALID_QUERY,
+            CollectionErrorCode.QUERY_TOO_COMPLEX,
+            CollectionErrorCode.MISSING_INDEX,
+            CollectionErrorCode.INVALID_ARGUMENT,
+            CollectionErrorCode.OUT_OF_RANGE
+        ];
+        return queryCodes.includes(this.code);
+    }
+    /**
+     * Check if error is network related
+     */
+    isNetworkError() {
+        const networkCodes = [
+            CollectionErrorCode.NETWORK_ERROR,
+            CollectionErrorCode.OFFLINE,
+            CollectionErrorCode.DEADLINE_EXCEEDED,
+            CollectionErrorCode.UNAVAILABLE
+        ];
+        return networkCodes.includes(this.code);
+    }
+    /**
+     * Convert to JSON for logging/debugging
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            friendlyMessage: this.getFriendlyMessage(),
+            path: this.path,
+            query: this.query?.map((c) => c.toString()),
+            isRetryable: this.isRetryable(),
+            requiresAuth: this.requiresAuth(),
+            isQueryError: this.isQueryError(),
+            isNetworkError: this.isNetworkError(),
+            context: this.context,
+            timestamp: new Date().toISOString()
+        };
+    }
+}