svelte-firekit 0.1.8 → 0.2.0

package/dist/types/mutations.d.ts

@@ -1,171 +1,81 @@
-/**
- * @fileoverview Document mutation types and interfaces for FirekitDocumentMutations
- * @module MutationTypes
- * @version 1.0.0
- */
 import type { FieldValue, Timestamp } from 'firebase/firestore';
 import { CacheSource } from './document.js';
-/**
- * Response structure for document mutations
- */
-export interface MutationResponse<T = any> {
-    /** Operation success status */
+export interface MutationResponse<T = unknown> {
     success: boolean;
-    /** Document data */
     data?: T;
-    /** Document ID */
     id?: string;
-    /** Error details if operation failed */
     error?: MutationError;
-    /** Operation metadata */
     metadata?: MutationMetadata;
 }
-/**
- * Metadata for mutation operations
- */
 export interface MutationMetadata {
-    /** Operation timestamp */
     timestamp: Date;
-    /** Operation type */
     operation: MutationOperationType;
-    /** Data source */
     source: CacheSource;
-    /** User who performed the operation */
     performedBy?: string;
-    /** Duration of operation in milliseconds */
     duration?: number;
-    /** Whether operation was cached */
     fromCache?: boolean;
 }
-/**
- * Options for document mutations
- */
 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 */
+    /** User ID stamped on createdBy / updatedBy when timestamps is true. */
+    userId?: string;
     validate?: boolean;
-    /** Custom validation function */
-    validator?: (data: any) => ValidationResult;
-    /** Retry configuration */
+    validator?: (data: unknown) => ValidationResult;
     retry?: RetryConfig;
-    /** Whether to perform optimistic updates */
     optimistic?: boolean;
-    /** Custom metadata to include */
-    customMetadata?: Record<string, any>;
-    /** Transaction options */
+    customMetadata?: Record<string, unknown>;
     transaction?: TransactionOptions;
 }
-/**
- * Validation result interface
- */
 export interface ValidationResult {
-    /** Whether validation passed */
     valid: boolean;
-    /** Validation error message if failed */
     message?: string;
-    /** Field-specific errors */
     fieldErrors?: Record<string, string>;
 }
-/**
- * Retry configuration for failed operations
- */
 export interface RetryConfig {
-    /** Whether retry is enabled */
     enabled: boolean;
-    /** Maximum number of retry attempts */
     maxAttempts: number;
-    /** Base delay between retries in milliseconds */
     baseDelay: number;
-    /** Backoff strategy */
     strategy: 'linear' | 'exponential';
-    /** Maximum delay between retries */
     maxDelay?: number;
-    /** Custom retry condition function */
     shouldRetry?: (error: MutationError, attempt: number) => boolean;
 }
-/**
- * Transaction options
- */
 export interface TransactionOptions {
-    /** Maximum number of transaction attempts */
     maxAttempts?: number;
-    /** Whether to use batch writes instead of transactions */
     useBatch?: boolean;
-    /** Custom transaction timeout */
     timeout?: number;
 }
-/**
- * Batch operation interface
- */
-export interface BatchOperation<T = any> {
-    /** Operation type */
+export interface BatchOperation<T = unknown> {
     type: MutationOperationType;
-    /** Document path */
     path: string;
-    /** Data for create/update operations */
     data?: T;
-    /** Options specific to this operation */
     options?: MutationOptions;
-    /** Custom ID for operation tracking */
     operationId?: string;
 }
-/**
- * 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: BatchOperationResult[];
-    /** Batch execution metadata */
     metadata: BatchMetadata;
 }
-/**
- * Individual batch operation result
- */
 export interface BatchOperationResult {
-    /** The original operation */
     operation: BatchOperation;
-    /** Operation success status */
     success: boolean;
-    /** Result data if successful */
-    data?: any;
-    /** Document ID if applicable */
+    data?: unknown;
     id?: string;
-    /** Error if failed */
     error?: MutationError;
-    /** Operation execution time */
     duration?: number;
 }
-/**
- * Batch operation metadata
- */
 export interface BatchMetadata {
-    /** Batch execution start time */
     startTime: Date;
-    /** Batch execution end time */
     endTime: Date;
-    /** Total execution duration */
     duration: number;
-    /** Batch size */
     operationCount: number;
-    /** User who executed the batch */
     executedBy?: string;
-    /** Batch execution strategy */
     strategy: 'parallel' | 'sequential';
 }
-/**
- * Mutation operation types
- */
 export declare enum MutationOperationType {
     CREATE = "create",
     SET = "set",
@@ -177,84 +87,20 @@ export declare enum MutationOperationType {
     TRANSACTION = "transaction",
     READ = "read"
 }
-/**
- * Document timestamp fields
- */
 export interface TimestampFields {
-    /** Document creation timestamp */
     createdAt?: Timestamp | FieldValue;
-    /** Document last update timestamp */
     updatedAt?: Timestamp | FieldValue;
-    /** User who created the document */
     createdBy?: string;
-    /** User who last updated the document */
     updatedBy?: string;
 }
-/**
- * Field value operations for special Firestore operations
- */
-export interface FieldValueOperations {
-    /** Server timestamp */
-    serverTimestamp(): FieldValue;
-    /** Increment numeric value */
-    increment(value: number): FieldValue;
-    /** Add elements to array */
-    arrayUnion(...elements: any[]): FieldValue;
-    /** Remove elements from array */
-    arrayRemove(...elements: any[]): FieldValue;
-    /** Delete field */
-    deleteField(): FieldValue;
-}
-/**
- * Document existence check result
- */
-export interface ExistenceCheckResult {
-    /** Whether document exists */
-    exists: boolean;
-    /** Document ID if exists */
-    id?: string;
-    /** Last modified timestamp */
-    lastModified?: Date;
-    /** Document metadata */
-    metadata?: {
-        size: number;
-        updateTime: Date;
-        createTime: Date;
-    };
-}
-/**
- * Bulk mutation configuration
- */
 export interface BulkMutationConfig {
-    /** Batch size for bulk operations */
     batchSize?: number;
-    /** Whether to run operations in parallel */
     parallel?: boolean;
-    /** Maximum concurrency for parallel operations */
     maxConcurrency?: number;
-    /** Whether to stop on first error */
     failFast?: boolean;
-    /** Progress callback */
     onProgress?: (completed: number, total: number) => void;
-    /** Error callback */
     onError?: (error: MutationError, operation: BatchOperation) => void;
 }
-/**
- * Optimistic update configuration
- */
-export interface OptimisticUpdateConfig {
-    /** Whether optimistic updates are enabled */
-    enabled: boolean;
-    /** Rollback strategy on failure */
-    rollbackStrategy: 'automatic' | 'manual';
-    /** Timeout for confirming optimistic update */
-    confirmationTimeout?: number;
-    /** Custom rollback function */
-    rollbackFn?: (originalData: any) => void;
-}
-/**
- * Mutation error codes enum
- */
 export declare enum MutationErrorCode {
     PERMISSION_DENIED = "mutations/permission-denied",
     NOT_FOUND = "mutations/not-found",
@@ -288,78 +134,18 @@ export declare enum MutationErrorCode {
     QUOTA_EXCEEDED = "mutations/quota-exceeded",
     UNKNOWN = "mutations/unknown"
 }
-/**
- * Custom mutation error class
- */
 export declare class MutationError extends Error {
     code: MutationErrorCode;
     operation?: MutationOperationType | undefined;
     path?: string | undefined;
-    originalError?: any | undefined;
-    context?: Record<string, any> | undefined;
-    constructor(code: MutationErrorCode, message: string, operation?: MutationOperationType | undefined, path?: string | undefined, originalError?: any | undefined, context?: Record<string, any> | undefined);
-    /**
-     * Get user-friendly error message
-     */
+    originalError?: unknown | undefined;
+    context?: Record<string, unknown> | undefined;
+    constructor(code: MutationErrorCode, message: string, operation?: MutationOperationType | undefined, path?: string | undefined, originalError?: unknown | undefined, context?: Record<string, unknown> | undefined);
     getFriendlyMessage(): string;
-    /**
-     * Check if error is retryable
-     */
     isRetryable(): boolean;
-    /**
-     * Check if error requires user authentication
-     */
     requiresAuth(): boolean;
-    /**
-     * Check if error is a validation error
-     */
     isValidationError(): boolean;
-    /**
-     * Check if error is permanent (not retryable)
-     */
     isPermanent(): boolean;
-    /**
-     * Get suggested action for the error
-     */
     getSuggestedAction(): string;
-    /**
-     * Convert to JSON for logging/debugging
-     */
-    toJSON(): Record<string, any>;
-}
-/**
- * Mutation event types for tracking operations
- */
-/**
- * Mutation analytics data
- */
-export interface MutationAnalytics {
-    /** Total number of mutations */
-    totalMutations: number;
-    /** Number of successful mutations */
-    successfulMutations: number;
-    /** Number of failed mutations */
-    failedMutations: number;
-    /** Success rate percentage */
-    successRate: number;
-    /** Average mutation duration */
-    averageDuration: number;
-    /** Most common error codes */
-    commonErrors: Array<{
-        code: MutationErrorCode;
-        count: number;
-        percentage: number;
-    }>;
-    /** Performance metrics by operation type */
-    performanceByOperation: Record<MutationOperationType, {
-        count: number;
-        averageDuration: number;
-        successRate: number;
-    }>;
-    /** Retry statistics */
-    retryStats: {
-        totalRetries: number;
-        retriesPerMutation: number;
-        retrySuccessRate: number;
-    };
+    toJSON(): Record<string, unknown>;
 }

package/dist/types/mutations.js

@@ -1,12 +1,4 @@
-/**
- * @fileoverview Document mutation types and interfaces for FirekitDocumentMutations
- * @module MutationTypes
- * @version 1.0.0
- */
 import { CacheSource } from './document.js';
-/**
- * Mutation operation types
- */
 export var MutationOperationType;
 (function (MutationOperationType) {
     MutationOperationType["CREATE"] = "create";
@@ -19,12 +11,8 @@ export var MutationOperationType;
     MutationOperationType["TRANSACTION"] = "transaction";
     MutationOperationType["READ"] = "read";
 })(MutationOperationType || (MutationOperationType = {}));
-/**
- * Mutation error codes enum
- */
 export var MutationErrorCode;
 (function (MutationErrorCode) {
-    // Firebase errors
     MutationErrorCode["PERMISSION_DENIED"] = "mutations/permission-denied";
     MutationErrorCode["NOT_FOUND"] = "mutations/not-found";
     MutationErrorCode["ALREADY_EXISTS"] = "mutations/already-exists";
@@ -38,33 +26,25 @@ export var MutationErrorCode;
     MutationErrorCode["UNAUTHENTICATED"] = "mutations/unauthenticated";
     MutationErrorCode["RESOURCE_EXHAUSTED"] = "mutations/resource-exhausted";
     MutationErrorCode["CANCELLED"] = "mutations/cancelled";
-    // Validation errors
     MutationErrorCode["VALIDATION_FAILED"] = "mutations/validation-failed";
     MutationErrorCode["REQUIRED_FIELD_MISSING"] = "mutations/required-field-missing";
     MutationErrorCode["INVALID_FIELD_TYPE"] = "mutations/invalid-field-type";
     MutationErrorCode["INVALID_FIELD_VALUE"] = "mutations/invalid-field-value";
     MutationErrorCode["FIELD_TOO_LARGE"] = "mutations/field-too-large";
     MutationErrorCode["DOCUMENT_TOO_LARGE"] = "mutations/document-too-large";
-    // Operation errors
     MutationErrorCode["INVALID_PATH"] = "mutations/invalid-path";
     MutationErrorCode["INVALID_DOCUMENT_ID"] = "mutations/invalid-document-id";
     MutationErrorCode["BATCH_TOO_LARGE"] = "mutations/batch-too-large";
     MutationErrorCode["TRANSACTION_FAILED"] = "mutations/transaction-failed";
     MutationErrorCode["RETRY_EXHAUSTED"] = "mutations/retry-exhausted";
     MutationErrorCode["OPTIMISTIC_LOCK_FAILED"] = "mutations/optimistic-lock-failed";
-    // Network errors
     MutationErrorCode["NETWORK_ERROR"] = "mutations/network-error";
     MutationErrorCode["TIMEOUT"] = "mutations/timeout";
     MutationErrorCode["OFFLINE"] = "mutations/offline";
-    // Service errors
     MutationErrorCode["SERVICE_UNAVAILABLE"] = "mutations/service-unavailable";
     MutationErrorCode["QUOTA_EXCEEDED"] = "mutations/quota-exceeded";
-    // Unknown
     MutationErrorCode["UNKNOWN"] = "mutations/unknown";
 })(MutationErrorCode || (MutationErrorCode = {}));
-/**
- * Custom mutation error class
- */
 export class MutationError extends Error {
     code;
     operation;
@@ -80,9 +60,6 @@ export class MutationError extends Error {
         this.context = context;
         this.name = 'MutationError';
     }
-    /**
-     * Get user-friendly error message
-     */
     getFriendlyMessage() {
         switch (this.code) {
             case MutationErrorCode.PERMISSION_DENIED:
@@ -115,9 +92,6 @@ export class MutationError extends Error {
                 return this.message || 'An unexpected error occurred.';
         }
     }
-    /**
-     * Check if error is retryable
-     */
     isRetryable() {
         const retryableCodes = [
             MutationErrorCode.NETWORK_ERROR,
@@ -130,16 +104,10 @@ export class MutationError extends Error {
         ];
         return retryableCodes.includes(this.code);
     }
-    /**
-     * Check if error requires user authentication
-     */
     requiresAuth() {
-        const authCodes = [MutationErrorCode.UNAUTHENTICATED, MutationErrorCode.PERMISSION_DENIED];
-        return authCodes.includes(this.code);
+        return (this.code === MutationErrorCode.UNAUTHENTICATED ||
+            this.code === MutationErrorCode.PERMISSION_DENIED);
     }
-    /**
-     * Check if error is a validation error
-     */
     isValidationError() {
         const validationCodes = [
             MutationErrorCode.VALIDATION_FAILED,
@@ -151,9 +119,6 @@ export class MutationError extends Error {
         ];
         return validationCodes.includes(this.code);
     }
-    /**
-     * Check if error is permanent (not retryable)
-     */
     isPermanent() {
         const permanentCodes = [
             MutationErrorCode.PERMISSION_DENIED,
@@ -164,27 +129,17 @@ export class MutationError extends Error {
         ];
         return permanentCodes.includes(this.code);
     }
-    /**
-     * Get suggested action for the error
-     */
     getSuggestedAction() {
-        if (this.requiresAuth()) {
+        if (this.requiresAuth())
             return 'Please sign in and try again.';
-        }
-        if (this.isValidationError()) {
+        if (this.isValidationError())
             return 'Please check your data and try again.';
-        }
-        if (this.isRetryable()) {
+        if (this.isRetryable())
             return 'This appears to be a temporary issue. Please try again.';
-        }
-        if (this.isPermanent()) {
+        if (this.isPermanent())
             return 'Please check your request and contact support if the issue persists.';
-        }
         return 'Please try again or contact support if the issue persists.';
     }
-    /**
-     * Convert to JSON for logging/debugging
-     */
     toJSON() {
         return {
             name: this.name,