svelte-firekit 0.0.25 → 0.1.1

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()
+        };
+    }
+}

package/dist/types/document.d.ts

@@ -0,0 +1,342 @@
+/**
+ * @fileoverview Document types and interfaces for FirekitDoc
+ * @module DocumentTypes
+ * @version 1.0.0
+ */
+/**
+ * Document state interface containing all reactive properties
+ */
+export interface DocumentState<T> {
+    /** Current document data */
+    data: T | null;
+    /** Whether document exists in Firestore */
+    exists: boolean;
+    /** Loading state indicator */
+    loading: boolean;
+    /** Current error state */
+    error: DocumentError | null;
+    /** Document ID */
+    id: string;
+}
+/**
+ * Configuration options for document subscriptions
+ */
+export interface DocumentOptions {
+    /** 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';
+    /** Retry configuration for failed operations */
+    retry?: {
+        enabled: boolean;
+        maxAttempts: number;
+        backoffMs: number;
+    };
+    /** Cache configuration */
+    cache?: {
+        enabled: boolean;
+        maxAge: number;
+    };
+}
+/**
+ * Document mutation options
+ */
+export interface MutationOptions {
+    /** Whether to include automatic timestamps */
+    timestamps?: boolean;
+    /** Whether to merge data in set operations */
+    merge?: boolean;
+    /** Custom document ID for add operations */
+    customId?: string;
+    /** Whether to validate data before mutation */
+    validate?: boolean;
+    /** Custom validation function */
+    validator?: (data: any) => boolean | string;
+}
+/**
+ * Document mutation response
+ */
+export interface MutationResponse<T> {
+    /** Operation success status */
+    success: boolean;
+    /** Document data */
+    data?: T;
+    /** Document ID */
+    id?: string;
+    /** Error details if operation failed */
+    error?: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+    /** Operation metadata */
+    metadata?: {
+        timestamp: Date;
+        source: string;
+        operation: string;
+    };
+}
+/**
+ * Batch operation interface
+ */
+export interface BatchOperation {
+    /** Operation type */
+    type: 'create' | 'update' | 'delete';
+    /** Document path */
+    path: string;
+    /** Data for create/update operations */
+    data?: any;
+    /** Options specific to this operation */
+    options?: MutationOptions;
+}
+/**
+ * Batch operation result
+ */
+export interface BatchResult {
+    /** Overall batch success status */
+    success: boolean;
+    /** Number of successful operations */
+    successCount: number;
+    /** Number of failed operations */
+    failureCount: number;
+    /** Individual operation results */
+    results: Array<{
+        operation: BatchOperation;
+        success: boolean;
+        error?: DocumentError;
+    }>;
+    /** Batch execution metadata */
+    metadata: {
+        startTime: Date;
+        endTime: Date;
+        duration: number;
+    };
+}
+/**
+ * Document listener configuration
+ */
+export interface ListenerConfig {
+    /** Whether to include metadata changes */
+    includeMetadata?: boolean;
+    /** Custom error handler */
+    onError?: (error: DocumentError) => void;
+    /** Custom data handler */
+    onData?: (data: any) => void;
+    /** Whether to automatically retry on connection issues */
+    autoRetry?: boolean;
+}
+/**
+ * Document cache entry
+ */
+export interface CacheEntry<T> {
+    /** Cached data */
+    data: T;
+    /** Cache timestamp */
+    timestamp: Date;
+    /** Data source */
+    source: CacheSource;
+    /** Expiration time */
+    expiresAt: Date;
+    /** Document metadata */
+    metadata?: {
+        lastModified: Date;
+        etag?: string;
+    };
+}
+export declare enum CacheSource {
+    SERVER = "server",
+    CACHE = "cache",
+    CLIENT = "client"
+}
+/**
+ * Document error codes enum
+ */
+export declare enum DocumentErrorCode {
+    FIRESTORE_UNAVAILABLE = "firestore/unavailable",
+    NETWORK_ERROR = "firestore/network-error",
+    TIMEOUT = "firestore/timeout",
+    CANCELLED = "firestore/cancelled",
+    PERMISSION_DENIED = "firestore/permission-denied",
+    UNAUTHENTICATED = "firestore/unauthenticated",
+    NOT_FOUND = "firestore/not-found",
+    ALREADY_EXISTS = "firestore/already-exists",
+    REFERENCE_UNAVAILABLE = "firestore/reference-unavailable",
+    INVALID_PATH = "firestore/invalid-path",
+    INVALID_DATA = "firestore/invalid-data",
+    DATA_LOSS = "firestore/data-loss",
+    FAILED_PRECONDITION = "firestore/failed-precondition",
+    ABORTED = "firestore/aborted",
+    OUT_OF_RANGE = "firestore/out-of-range",
+    UNIMPLEMENTED = "firestore/unimplemented",
+    INTERNAL_ERROR = "firestore/internal",
+    UNAVAILABLE = "firestore/unavailable",
+    VALIDATION_FAILED = "document/validation-failed",
+    REQUIRED_FIELD_MISSING = "document/required-field-missing",
+    INVALID_FIELD_TYPE = "document/invalid-field-type",
+    CACHE_MISS = "document/cache-miss",
+    CACHE_EXPIRED = "document/cache-expired",
+    UNKNOWN = "document/unknown"
+}
+/**
+ * Custom document error class
+ */
+export declare class DocumentError extends Error {
+    code: DocumentErrorCode;
+    originalError?: any | undefined;
+    context?: Record<string, any> | undefined;
+    constructor(code: DocumentErrorCode, message: string, 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 permissions
+     */
+    isPermissionError(): boolean;
+    /**
+     * Check if error is a validation error
+     */
+    isValidationError(): boolean;
+    /**
+     * Convert to JSON for logging/debugging
+     */
+    toJSON(): Record<string, any>;
+}
+/**
+ * Document field value types for special operations
+ */
+export type DocumentFieldValue = {
+    type: 'serverTimestamp';
+} | {
+    type: 'increment';
+    value: number;
+} | {
+    type: 'arrayUnion';
+    values: any[];
+} | {
+    type: 'arrayRemove';
+    values: any[];
+} | {
+    type: 'delete';
+};
+/**
+ * Document update data with field value support
+ */
+export type DocumentUpdateData<T> = {
+    [K in keyof T]?: T[K] | DocumentFieldValue;
+} & {
+    [key: string]: any | DocumentFieldValue;
+};
+/**
+ * Document metadata interface
+ */
+export interface DocumentMetadata {
+    /** Whether document has pending writes */
+    hasPendingWrites: boolean;
+    /** Whether document data is from cache */
+    fromCache: boolean;
+    /** Last update timestamp */
+    lastUpdateTime?: Date;
+    /** Document creation timestamp */
+    createTime?: Date;
+    /** Document update timestamp */
+    updateTime?: Date;
+}
+/**
+ * Document snapshot interface
+ */
+export interface DocumentSnapshot<T> {
+    /** Document ID */
+    id: string;
+    /** Document data */
+    data: T | null;
+    /** Whether document exists */
+    exists: boolean;
+    /** Document metadata */
+    metadata: DocumentMetadata;
+    /** Document reference */
+    ref: any;
+}
+/**
+ * Document query constraints for filtering
+ */
+export interface DocumentQueryConstraint {
+    type: 'where' | 'orderBy' | 'limit' | 'startAt' | 'endAt';
+    field?: string;
+    operator?: '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'not-in' | 'array-contains-any';
+    value?: any;
+    direction?: 'asc' | 'desc';
+    count?: number;
+}
+/**
+ * Document observer interface for watching changes
+ */
+export interface DocumentObserver<T> {
+    /** Called when document data changes */
+    next: (snapshot: DocumentSnapshot<T>) => void;
+    /** Called when an error occurs */
+    error?: (error: DocumentError) => void;
+    /** Called when observation completes */
+    complete?: () => void;
+}
+/**
+ * Document subscription interface
+ */
+export interface DocumentSubscription {
+    /** Unsubscribe from document changes */
+    unsubscribe: () => void;
+    /** Whether subscription is active */
+    active: boolean;
+    /** Subscription configuration */
+    config: ListenerConfig;
+}
+/**
+ * Document analytics data
+ */
+export interface DocumentAnalytics {
+    /** Number of reads */
+    readCount: number;
+    /** Number of writes */
+    writeCount: number;
+    /** Number of deletes */
+    deleteCount: number;
+    /** Cache hit rate */
+    cacheHitRate: number;
+    /** Average response time */
+    averageResponseTime: number;
+    /** Error rate */
+    errorRate: number;
+    /** Last activity timestamp */
+    lastActivity: Date;
+}
+/**
+ * Document performance metrics
+ */
+export interface DocumentPerformanceMetrics {
+    /** Time to first byte */
+    ttfb: number;
+    /** Total load time */
+    loadTime: number;
+    /** Cache performance */
+    cachePerformance: {
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /** Network performance */
+    networkPerformance: {
+        latency: number;
+        bandwidth: number;
+        connectionType: string;
+    };
+}

package/dist/types/document.js

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview Document types and interfaces for FirekitDoc
+ * @module DocumentTypes
+ * @version 1.0.0
+ */
+export var CacheSource;
+(function (CacheSource) {
+    CacheSource["SERVER"] = "server";
+    CacheSource["CACHE"] = "cache";
+    CacheSource["CLIENT"] = "client";
+})(CacheSource || (CacheSource = {}));
+/**
+ * Document error codes enum
+ */
+export var DocumentErrorCode;
+(function (DocumentErrorCode) {
+    // Connection errors
+    DocumentErrorCode["FIRESTORE_UNAVAILABLE"] = "firestore/unavailable";
+    DocumentErrorCode["NETWORK_ERROR"] = "firestore/network-error";
+    DocumentErrorCode["TIMEOUT"] = "firestore/timeout";
+    DocumentErrorCode["CANCELLED"] = "firestore/cancelled";
+    // Permission errors
+    DocumentErrorCode["PERMISSION_DENIED"] = "firestore/permission-denied";
+    DocumentErrorCode["UNAUTHENTICATED"] = "firestore/unauthenticated";
+    // Document errors
+    DocumentErrorCode["NOT_FOUND"] = "firestore/not-found";
+    DocumentErrorCode["ALREADY_EXISTS"] = "firestore/already-exists";
+    // Reference errors
+    DocumentErrorCode["REFERENCE_UNAVAILABLE"] = "firestore/reference-unavailable";
+    DocumentErrorCode["INVALID_PATH"] = "firestore/invalid-path";
+    // Data errors
+    DocumentErrorCode["INVALID_DATA"] = "firestore/invalid-data";
+    DocumentErrorCode["DATA_LOSS"] = "firestore/data-loss";
+    // Operation errors
+    DocumentErrorCode["FAILED_PRECONDITION"] = "firestore/failed-precondition";
+    DocumentErrorCode["ABORTED"] = "firestore/aborted";
+    DocumentErrorCode["OUT_OF_RANGE"] = "firestore/out-of-range";
+    DocumentErrorCode["UNIMPLEMENTED"] = "firestore/unimplemented";
+    DocumentErrorCode["INTERNAL_ERROR"] = "firestore/internal";
+    DocumentErrorCode["UNAVAILABLE"] = "firestore/unavailable";
+    // Validation errors
+    DocumentErrorCode["VALIDATION_FAILED"] = "document/validation-failed";
+    DocumentErrorCode["REQUIRED_FIELD_MISSING"] = "document/required-field-missing";
+    DocumentErrorCode["INVALID_FIELD_TYPE"] = "document/invalid-field-type";
+    // Cache errors
+    DocumentErrorCode["CACHE_MISS"] = "document/cache-miss";
+    DocumentErrorCode["CACHE_EXPIRED"] = "document/cache-expired";
+    // Unknown
+    DocumentErrorCode["UNKNOWN"] = "document/unknown";
+})(DocumentErrorCode || (DocumentErrorCode = {}));
+/**
+ * Custom document error class
+ */
+export class DocumentError extends Error {
+    code;
+    originalError;
+    context;
+    constructor(code, message, originalError, context) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.context = context;
+        this.name = 'DocumentError';
+    }
+    /**
+     * Get user-friendly error message
+     */
+    getFriendlyMessage() {
+        switch (this.code) {
+            case DocumentErrorCode.PERMISSION_DENIED:
+                return 'You do not have permission to access this document.';
+            case DocumentErrorCode.NOT_FOUND:
+                return 'The requested document was not found.';
+            case DocumentErrorCode.NETWORK_ERROR:
+                return 'Network connection error. Please check your internet connection.';
+            case DocumentErrorCode.TIMEOUT:
+                return 'Request timed out. Please try again.';
+            case DocumentErrorCode.UNAUTHENTICATED:
+                return 'Please sign in to access this document.';
+            case DocumentErrorCode.UNAVAILABLE:
+                return 'Service is temporarily unavailable. Please try again later.';
+            case DocumentErrorCode.VALIDATION_FAILED:
+                return 'The provided data is invalid.';
+            case DocumentErrorCode.ALREADY_EXISTS:
+                return 'A document with this ID already exists.';
+            case DocumentErrorCode.CACHE_EXPIRED:
+                return 'Cached data has expired. Refreshing...';
+            default:
+                return this.message || 'An unexpected error occurred.';
+        }
+    }
+    /**
+     * Check if error is retryable
+     */
+    isRetryable() {
+        const retryableCodes = [
+            DocumentErrorCode.NETWORK_ERROR,
+            DocumentErrorCode.TIMEOUT,
+            DocumentErrorCode.UNAVAILABLE,
+            DocumentErrorCode.CANCELLED,
+            DocumentErrorCode.INTERNAL_ERROR
+        ];
+        return retryableCodes.includes(this.code);
+    }
+    /**
+     * Check if error requires user authentication
+     */
+    requiresAuth() {
+        return this.code === DocumentErrorCode.UNAUTHENTICATED;
+    }
+    /**
+     * Check if error is related to permissions
+     */
+    isPermissionError() {
+        const permissionCodes = [
+            DocumentErrorCode.PERMISSION_DENIED,
+            DocumentErrorCode.UNAUTHENTICATED
+        ];
+        return permissionCodes.includes(this.code);
+    }
+    /**
+     * Check if error is a validation error
+     */
+    isValidationError() {
+        const validationCodes = [
+            DocumentErrorCode.VALIDATION_FAILED,
+            DocumentErrorCode.REQUIRED_FIELD_MISSING,
+            DocumentErrorCode.INVALID_FIELD_TYPE,
+            DocumentErrorCode.INVALID_DATA
+        ];
+        return validationCodes.includes(this.code);
+    }
+    /**
+     * Convert to JSON for logging/debugging
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            friendlyMessage: this.getFriendlyMessage(),
+            isRetryable: this.isRetryable(),
+            requiresAuth: this.requiresAuth(),
+            context: this.context,
+            timestamp: new Date().toISOString()
+        };
+    }
+}

package/dist/types/firebase.d.ts

@@ -0,0 +1,44 @@
+import type { FirebaseApp, FirebaseOptions } from 'firebase/app';
+import type { Firestore } from 'firebase/firestore';
+import type { Auth } from 'firebase/auth';
+import type { Functions } from 'firebase/functions';
+import type { Database } from 'firebase/database';
+import type { FirebaseStorage } from 'firebase/storage';
+/**
+ * Type definition for required Firebase environment variables
+ */
+export type FirebaseEnvVars = FirebaseOptions;
+/**
+ * Type guard to check if an object contains all required Firebase environment variables
+ */
+export declare function isValidFirebaseConfig(config: Partial<FirebaseEnvVars>): config is FirebaseEnvVars;
+/**
+ * Enum representing the initialization status of Firebase services
+ */
+export declare enum FirebaseServiceStatus {
+    UNINITIALIZED = "UNINITIALIZED",
+    INITIALIZING = "INITIALIZING",
+    INITIALIZED = "INITIALIZED",
+    ERROR = "ERROR"
+}
+/**
+ * Error class for Firebase service initialization failures
+ */
+export declare class FirebaseServiceError extends Error {
+    readonly service: string;
+    constructor(message: string, service: string);
+}
+/**
+ * Interface for Firebase service instance
+ */
+export interface FirebaseServiceInstance {
+    firebaseApp: FirebaseApp | null;
+    db: Firestore | null;
+    auth: Auth | null;
+    functions: Functions | null;
+    database: Database | null;
+    storage: FirebaseStorage | null;
+    status: FirebaseServiceStatus;
+    initializationError: Error | null;
+    isBrowser: boolean;
+}