{"id":30201616,"url":"https://github.com/code-gio/svelte-firebase-upload","last_synced_at":"2026-01-20T17:31:18.251Z","repository":{"id":304045529,"uuid":"1017540727","full_name":"code-gio/svelte-firebase-upload","owner":"code-gio","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-11T04:02:37.000Z","size":174,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-11T05:31:43.317Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/code-gio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-10T17:34:04.000Z","updated_at":"2025-08-11T04:02:40.000Z","dependencies_parsed_at":"2025-07-11T02:33:16.539Z","dependency_job_id":"9765d3ef-0090-4a69-bbd8-4feb84f818f1","html_url":"https://github.com/code-gio/svelte-firebase-upload","commit_stats":null,"previous_names":["code-gio/svelte-firebase-upload"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/code-gio/svelte-firebase-upload","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-gio%2Fsvelte-firebase-upload","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-gio%2Fsvelte-firebase-upload/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-gio%2Fsvelte-firebase-upload/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-gio%2Fsvelte-firebase-upload/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/code-gio","download_url":"https://codeload.github.com/code-gio/svelte-firebase-upload/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-gio%2Fsvelte-firebase-upload/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270228440,"owners_count":24548818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-13T10:51:31.850Z","updated_at":"2026-01-20T17:31:18.218Z","avatar_url":"https://github.com/code-gio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Svelte Firebase Upload\n\nA powerful, enterprise-grade file upload manager for Svelte applications with Firebase Storage integration. Features concurrent uploads, resumable transfers, smart queue management, comprehensive validation, health monitoring, and an extensible plugin system.\n\n## ✨ Features\n\n### Core Upload Features\n- **🚀 Concurrent Uploads** - Upload multiple files simultaneously with configurable limits\n- **📊 Real-time Progress** - Track upload progress, speed, and time estimates\n- **🔄 Resumable Uploads** - Automatic retry and resumption for interrupted transfers\n- **⚡ Smart Scheduling** - Prioritizes smaller files for quick user feedback\n- **📦 Batch Processing** - Efficiently handles large file sets (1000+ files)\n\n### Advanced Capabilities\n- **🔍 File Validation** - Size, type, and custom validation rules with duplicate detection\n- **🏥 Health Monitoring** - Periodic checks for network, storage, and permissions\n- **🌐 Network Adaptation** - Bandwidth throttling and network quality detection\n- **💾 Memory Management** - Virtual queuing for large file sets to prevent memory issues\n- **🔌 Plugin System** - Extensible architecture with built-in plugins for logging, analytics, and processing\n\n### Developer Experience\n- **📝 TypeScript Support** - Full type definitions for better development experience\n- **🎯 Svelte 5 Ready** - Built with Svelte 5's latest reactivity system\n- **🛠️ Configuration Validation** - Runtime validation with helpful warnings\n- **📈 Performance Metrics** - Built-in analytics and monitoring capabilities\n\n## 📦 Installation\n\nInstall the package and its peer dependencies:\n\n```bash\nnpm install svelte-firebase-upload firebase\n```\n\n### Peer Dependencies\n- `firebase` ^11.10.0\n- `svelte` ^5.0.0\n\n## 🚀 Quick Start\n\n### 1. Initialize Firebase\n\n```typescript\nimport { initializeApp } from 'firebase/app';\nimport { getStorage } from 'firebase/storage';\n\nconst firebaseConfig = {\n  // Your Firebase configuration\n  apiKey: \"your-api-key\",\n  authDomain: \"your-project.firebaseapp.com\",\n  projectId: \"your-project-id\",\n  storageBucket: \"your-project.appspot.com\",\n  messagingSenderId: \"your-sender-id\",\n  appId: \"your-app-id\"\n};\n\nconst app = initializeApp(firebaseConfig);\nconst storage = getStorage(app);\n```\n\n### 2. Basic Usage\n\n```svelte\n\u003cscript lang=\"ts\"\u003e\n  import { FirebaseUploadManager } from 'svelte-firebase-upload';\n  import { getStorage } from 'firebase/storage';\n\n  let fileInput: HTMLInputElement;\n  let manager: FirebaseUploadManager;\n\n  $effect(() =\u003e {\n    // Initialize the upload manager\n    manager = new FirebaseUploadManager({\n      maxConcurrentUploads: 3,\n      chunkSize: 2 * 1024 * 1024, // 2MB chunks\n      autoStart: true,\n      enableSmartScheduling: true,\n      enableHealthChecks: true\n    });\n\n    // Set your Firebase Storage instance\n    manager.setStorage(getStorage());\n  });\n\n  async function handleFileSelect(event: Event) {\n    const files = (event.target as HTMLInputElement).files;\n    if (files) {\n      await manager.addFiles(files, {\n        path: 'user-uploads/',\n        metadata: { uploadedBy: 'user123' }\n      });\n    }\n  }\n\u003c/script\u003e\n\n\u003cinput bind:this={fileInput} type=\"file\" multiple on:change={handleFileSelect} /\u003e\n\n{#if manager}\n  \u003cdiv class=\"upload-stats\"\u003e\n    \u003cdiv\u003eProgress: {manager.totalProgress.toFixed(1)}%\u003c/div\u003e\n    \u003cdiv\u003eSpeed: {(manager.currentSpeed / 1024 / 1024).toFixed(2)} MB/s\u003c/div\u003e\n    \u003cdiv\u003eFiles: {manager.successCount}/{manager.totalFiles}\u003c/div\u003e\n  \u003c/div\u003e\n\n  {#if manager.hasQueuedFiles}\n    \u003cdiv\u003eQueued: {manager.queue.length} files\u003c/div\u003e\n  {/if}\n\n  {#if manager.hasFailedFiles}\n    \u003cdiv\u003eFailed: {manager.failureCount} files\u003c/div\u003e\n    \u003cbutton on:click={() =\u003e manager.retryFailed()}\u003eRetry Failed\u003c/button\u003e\n  {/if}\n{/if}\n```\n\n## 🔧 Configuration\n\n### UploadManagerConfig\n\n```typescript\ninterface UploadManagerConfig {\n  maxConcurrentUploads: number;    // Default: 4\n  chunkSize: number;               // Default: 1MB (1024 * 1024)\n  retryAttempts: number;           // Default: 3\n  retryDelay: number;              // Default: 1000ms\n  autoStart: boolean;              // Default: true\n  maxBandwidthMbps?: number;       // Default: 10\n  adaptiveBandwidth?: boolean;     // Default: true\n  maxMemoryItems?: number;         // Default: 1000\n  enablePersistence?: boolean;     // Default: false\n  enableSmartScheduling: boolean;  // Default: true\n}\n```\n\n### UploadManagerOptions (per upload)\n\n```typescript\ninterface UploadManagerOptions {\n  path?: string;                   // Storage path\n  metadata?: Record\u003cstring, any\u003e;  // Custom metadata\n  priority?: number;               // Upload priority\n  // ... additional options\n}\n```\n\n## 📖 API Reference\n\n### Core Methods\n\n```typescript\n// File Management\nawait manager.addFiles(fileList: FileList | File[], options?: UploadManagerOptions): Promise\u003cnumber\u003e\nawait manager.addFilesWithValidation(files: File[], options?: ValidationOptions): Promise\u003cValidationResult\u003e\n\n// Upload Control\nawait manager.start(): Promise\u003cvoid\u003e\nawait manager.pause(): Promise\u003cvoid\u003e\nawait manager.resume(): Promise\u003cvoid\u003e\nawait manager.stop(): Promise\u003cvoid\u003e\nawait manager.destroy(): Promise\u003cvoid\u003e\n\n// File Operations\nawait manager.removeFile(fileId: string): Promise\u003cvoid\u003e\nmanager.retryFailed(): void\nawait manager.clearCompleted(): Promise\u003cvoid\u003e\nmanager.clearFailed(): void\n\n// Queries\nmanager.getFile(fileId: string): UploadItem | undefined\nmanager.getAllFiles(statusFilter?: UploadStatus): UploadItem[]\n```\n\n### Validation \u0026 Processing\n\n```typescript\n// File Validation\nawait manager.validateFiles(files: File[], rules?: ValidationRule): Promise\u003cMap\u003cFile, ValidationResult\u003e\u003e\nawait manager.validateFile(file: File, rules?: ValidationRule): Promise\u003cValidationResult\u003e\nawait manager.detectDuplicates(files: File[]): Promise\u003cMap\u003cstring, File[]\u003e\u003e\n\n// Metadata\nawait manager.getFileMetadata(file: File): Promise\u003cFileMetadata\u003e\n```\n\n### Health \u0026 Monitoring\n\n```typescript\n// Health Checks\nawait manager.performHealthCheck(): Promise\u003cHealthCheckResult\u003e\nawait manager.startWithHealthCheck(): Promise\u003c{ canStart: boolean; healthResult: HealthCheckResult }\u003e\nmanager.getHealthStatus(): HealthStatus\n\n// Performance\nmanager.getBandwidthStats(): BandwidthStats\nmanager.getNetworkQuality(): 'excellent' | 'good' | 'poor' | 'unknown'\nmanager.getRecommendedSettings(): RecommendedSettings\n```\n\n### Plugin System\n\n```typescript\n// Plugin Management\nawait manager.registerPlugin(plugin: UploadPlugin, config?: PluginConfig): Promise\u003cvoid\u003e\nawait manager.unregisterPlugin(pluginName: string): Promise\u003cvoid\u003e\nmanager.getAllPlugins(): PluginInfo[]\nmanager.getEnabledPlugins(): PluginInfo[]\nawait manager.setPluginEnabled(pluginName: string, enabled: boolean): Promise\u003cvoid\u003e\n```\n\n## 🔌 Plugin System\n\nThe upload manager includes a powerful plugin system for extending functionality. Several production-ready plugins are included:\n\n### Example Plugins\n\nThe library includes comprehensive example plugins that demonstrate the plugin system capabilities. These are provided as documentation and examples to copy/customize for your needs:\n\n**Available Examples:**\n- **LoggingPlugin** - Debug and monitor uploads with configurable log levels\n- **AnalyticsPlugin** - Track performance metrics and success rates  \n- **FileProcessingPlugin** - Compress and resize images before upload\n- **ValidationEnhancementPlugin** - Advanced security checks with file signature validation\n- **QueueOptimizationPlugin** - Optimize upload order for better user experience\n\n**Usage:**\nCopy the plugin code from `src/lib/plugins/example-plugins.svelte.ts` in the repository and customize for your needs:\n\n```typescript\n// Copy and customize from the examples\nclass MyCustomLoggingPlugin implements UploadPlugin {\n  name = 'my-logging';\n  version = '1.0.0';\n  description = 'My custom logging implementation';\n\n  // Copy implementation from LoggingPlugin example and customize...\n}\n\nawait manager.registerPlugin(new MyCustomLoggingPlugin());\n```\n\n### Creating Custom Plugins\n\n```typescript\nimport type { UploadPlugin, UploadItem } from 'svelte-firebase-upload';\n\nexport class CustomPlugin implements UploadPlugin {\n  name = 'custom-plugin';\n  version = '1.0.0';\n  description = 'My custom plugin';\n\n  async onInitialize(manager: UploadManagerInterface): Promise\u003cvoid\u003e {\n    console.log('Plugin initialized');\n  }\n\n  async onUploadComplete(item: UploadItem, result: any): Promise\u003cvoid\u003e {\n    console.log(`Upload completed: ${item.file.name}`);\n    // Custom logic here\n  }\n\n  async onUploadError(item: UploadItem, error: Error): Promise\u003cvoid\u003e {\n    console.log(`Upload failed: ${item.file.name}`, error);\n    // Custom error handling\n  }\n}\n\n// Register your plugin\nawait manager.registerPlugin(new CustomPlugin());\n```\n\n## 🎯 Advanced Usage\n\n### Validation with Custom Rules\n\n```typescript\nconst validationResult = await manager.addFilesWithValidation(files, {\n  validate: true,\n  validationRules: {\n    maxSize: 50 * 1024 * 1024, // 50MB\n    allowedTypes: ['image/jpeg', 'image/png', 'application/pdf'],\n    customValidator: async (file: File) =\u003e {\n      // Custom validation logic\n      return file.name.length \u003c 100;\n    }\n  },\n  skipDuplicates: true,\n  checkResume: true\n});\n\nconsole.log(`Added: ${validationResult.added}, Duplicates: ${validationResult.duplicates}`);\n```\n\n### Resumable Uploads\n\n```typescript\n// Check for resumable uploads on initialization\nawait manager.resumeIncompleteUploads();\n\n// Check specific file\nconst resumeState = await manager.checkForResumableUpload(file);\nif (resumeState) {\n  console.log(`Can resume upload: ${resumeState.uploadedBytes}/${resumeState.fileSize} bytes`);\n}\n```\n\n### Memory-Efficient Large Batches\n\n```typescript\n// Automatically handles large file sets efficiently\nconst files = Array.from(document.querySelector('input[type=\"file\"]')!.files!);\nif (files.length \u003e 1000) {\n  // Uses virtual queuing automatically\n  await manager.addFiles(files, {\n    path: 'bulk-upload/',\n    maxMemoryItems: 500 // Process in batches of 500\n  });\n}\n```\n\n### Health Monitoring\n\n```typescript\n// Check health before starting critical uploads\nconst { canStart, healthResult } = await manager.startWithHealthCheck();\nif (!canStart) {\n  console.warn('Health issues detected:', healthResult.status.issues);\n  // Handle health issues\n}\n\n// Monitor health during uploads\nconst healthStatus = manager.getHealthStatus();\nif (!healthStatus.healthy) {\n  console.warn('Upload health degraded:', healthStatus.issues);\n}\n```\n\n## 🏗️ Architecture\n\n### Core Components\n\n1. **FirebaseUploadManager** - Main upload orchestrator\n2. **MemoryManager** - Virtual queuing for large file sets\n3. **NetworkManager** - Network monitoring and retry logic  \n4. **BandwidthManager** - Adaptive bandwidth throttling\n5. **FileValidator** - Comprehensive file validation\n6. **UploadResumer** - Resumable upload state management\n7. **PluginSystem** - Extensible plugin architecture\n\n### State Management\n\nThe manager uses Svelte 5's reactive system with `$state()` and `$derived()`:\n\n```typescript\n// Reactive properties\nmanager.totalProgress    // Derived from uploaded/total size\nmanager.isActive         // Derived from active uploads\nmanager.hasQueuedFiles   // Derived from queue length\nmanager.averageSpeed     // Derived from speed samples\n```\n\n### Memory Management\n\nFor large file sets (\u003e100 files), the manager automatically:\n- Uses virtual queuing to prevent memory exhaustion\n- Processes files in configurable batches\n- Persists state to localStorage when enabled\n- Lazily loads file metadata as needed\n\n## 🧪 Testing\n\n```bash\nnpm test        # Run test suite\nnpm run test:watch    # Watch mode\nnpm run test:coverage # Coverage report\n```\n\n## 🚀 Building\n\n```bash\nnpm run build   # Build library\nnpm run package # Create distributable package\n```\n\n## 📄 TypeScript Support\n\nFull TypeScript support with comprehensive type definitions:\n\n```typescript\nimport type {\n  FirebaseUploadManager,\n  UploadManagerConfig,\n  UploadManagerOptions,\n  UploadItem,\n  UploadStatus,\n  ValidationRule,\n  ValidationResult,\n  HealthCheckResult,\n  UploadPlugin,\n  PluginConfig\n} from 'svelte-firebase-upload';\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/code-gio/svelte-firebase-upload.git\ncd svelte-firebase-upload\nnpm install\nnpm run dev\n```\n\n## 📝 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Firebase team for the excellent Storage SDK\n- Svelte team for the amazing framework\n- Contributors and community feedback\n\n## 📞 Support\n\n- 🐛 **Issues**: [GitHub Issues](https://github.com/code-gio/svelte-firebase-upload/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/code-gio/svelte-firebase-upload/discussions)\n- 📧 **Email**: [support@your-domain.com](mailto:support@your-domain.com)\n\n---\n\n**Made with ❤️ for the Svelte community**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-gio%2Fsvelte-firebase-upload","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcode-gio%2Fsvelte-firebase-upload","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-gio%2Fsvelte-firebase-upload/lists"}