@uploadista/client-browser 0.0.3

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> @uploadista/client-browser@0.0.2 build /Users/denislaboureyras/Documents/uploadista/dev/uploadista-workspace/uploadista-sdk/packages/clients/browser
+> tsc -b
+

package/.turbo/turbo-check.log

@@ -0,0 +1,130 @@
+
+> @uploadista/client@ check /Users/denislaboureyras/Documents/uploadista/dev/uploadista/packages/uploadista/clients/client
+> biome check --write ./src
+
+src/examples/connection-pooling-example.ts:83:22 lint/style/useTemplate  FIXABLE  ━━━━━━━━━━━━━━━━━━
+
+  i Template literals are preferred over string concatenation.
+  
+    81 │         console.log("Connection metrics:", {
+    82 │           activeConnections: connectionMetrics.activeConnections,
+  > 83 │           reuseRate: Math.round(connectionMetrics.reuseRate * 100) + "%",
+       │                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    84 │           averageConnectionTime:
+    85 │             Math.round(connectionMetrics.averageConnectionTime) + "ms",
+  
+  i Unsafe fix: Use a template literal.
+  
+     81  81 │           console.log("Connection metrics:", {
+     82  82 │             activeConnections: connectionMetrics.activeConnections,
+     83     │ - ··········reuseRate:·Math.round(connectionMetrics.reuseRate·*·100)·+·"%",
+         83 │ + ··········reuseRate:·`${Math.round(connectionMetrics.reuseRate·*·100)}%`,
+     84  84 │             averageConnectionTime:
+     85  85 │               Math.round(connectionMetrics.averageConnectionTime) + "ms",
+  
+
+src/examples/connection-pooling-example.ts:85:13 lint/style/useTemplate  FIXABLE  ━━━━━━━━━━━━━━━━━━
+
+  i Template literals are preferred over string concatenation.
+  
+    83 │           reuseRate: Math.round(connectionMetrics.reuseRate * 100) + "%",
+    84 │           averageConnectionTime:
+  > 85 │             Math.round(connectionMetrics.averageConnectionTime) + "ms",
+       │             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    86 │         });
+    87 │       },
+  
+  i Unsafe fix: Use a template literal.
+  
+     83  83 │             reuseRate: Math.round(connectionMetrics.reuseRate * 100) + "%",
+     84  84 │             averageConnectionTime:
+     85     │ - ············Math.round(connectionMetrics.averageConnectionTime)·+·"ms",
+         85 │ + ············`${Math.round(connectionMetrics.averageConnectionTime)}ms`,
+     86  86 │           });
+     87  87 │         },
+  
+
+src/examples/connection-pooling-example.ts:95:22 lint/style/useTemplate  FIXABLE  ━━━━━━━━━━━━━━━━━━
+
+  i Template literals are preferred over string concatenation.
+  
+    93 │         console.log("Final connection pooling performance:", {
+    94 │           totalConnections: finalMetrics.totalConnections,
+  > 95 │           reuseRate: Math.round(finalMetrics.reuseRate * 100) + "%",
+       │                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    96 │           averageSpeed:
+    97 │             Math.round(finalMetrics.averageConnectionTime) + "ms per request",
+  
+  i Unsafe fix: Use a template literal.
+  
+     93  93 │           console.log("Final connection pooling performance:", {
+     94  94 │             totalConnections: finalMetrics.totalConnections,
+     95     │ - ··········reuseRate:·Math.round(finalMetrics.reuseRate·*·100)·+·"%",
+         95 │ + ··········reuseRate:·`${Math.round(finalMetrics.reuseRate·*·100)}%`,
+     96  96 │             averageSpeed:
+     97  97 │               Math.round(finalMetrics.averageConnectionTime) + "ms per request",
+  
+
+src/examples/connection-pooling-example.ts:97:13 lint/style/useTemplate  FIXABLE  ━━━━━━━━━━━━━━━━━━
+
+  i Template literals are preferred over string concatenation.
+  
+    95 │           reuseRate: Math.round(finalMetrics.reuseRate * 100) + "%",
+    96 │           averageSpeed:
+  > 97 │             Math.round(finalMetrics.averageConnectionTime) + "ms per request",
+       │             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    98 │         });
+    99 │       },
+  
+  i Unsafe fix: Use a template literal.
+  
+     95  95 │             reuseRate: Math.round(finalMetrics.reuseRate * 100) + "%",
+     96  96 │             averageSpeed:
+     97     │ - ············Math.round(finalMetrics.averageConnectionTime)·+·"ms·per·request",
+         97 │ + ············`${Math.round(finalMetrics.averageConnectionTime)}ms·per·request`,
+     98  98 │           });
+     99  99 │         },
+  
+
+src/examples/advanced-connection-pooling-example.ts:201:9 lint/correctness/noUnusedVariables  FIXABLE  ━━━━━━━━━━
+
+  ! This variable chunkingInsights is unused.
+  
+    199 │   const detailedMetrics = uploadClient.getDetailedConnectionMetrics();
+    200 │   const networkMetrics = uploadClient.getNetworkMetrics();
+  > 201 │   const chunkingInsights = uploadClient.getChunkingInsights();
+        │         ^^^^^^^^^^^^^^^^
+    202 │ 
+    203 │   // Performance Summary
+  
+  i Unused variables are often the result of an incomplete refactoring, typos, or other sources of bugs.
+  
+  i Unsafe fix: If this is intentional, prepend chunkingInsights with an underscore.
+Skipped 5 suggested fixes.
+If you wish to apply the suggested (unsafe) fixes, use the command biome check --write --unsafe
+  
+
+Checked 35 files in 109ms. No fixes applied.
+    199 199 │     const detailedMetrics = uploadClient.getDetailedConnectionMetrics();
+Found 2 warnings.
+    200 200 │     const networkMetrics = uploadClient.getNetworkMetrics();
+    201     │ - ··const·chunkingInsights·=·uploadClient.getChunkingInsights();
+        201 │ + ··const·_chunkingInsights·=·uploadClient.getChunkingInsights();
+    202 202 │   
+    203 203 │     // Performance Summary
+  
+
+src/examples/advanced-connection-pooling-example.ts:293:22 lint/correctness/noUnusedVariables ━━━━━━━━━━
+
+  ! This variable abortUpload is unused.
+  
+    291 │     // The upload will automatically negotiate the best strategy
+    292 │     try {
+  > 293 │       const { abort: abortUpload } = await uploadClient.upload(file, {
+        │                      ^^^^^^^^^^^
+    294 │         onProgress: (uploadId, bytes, total) => {
+    295 │           const percentage = Math.round((bytes / (total ?? 1)) * 100);
+  
+  i Unused variables are often the result of an incomplete refactoring, typos, or other sources of bugs.
+  
+

package/AUTO_CAPABILITIES.md

@@ -0,0 +1,98 @@
+✅ Data Store Capability Discovery Implementation Complete
+
+  I have successfully implemented a comprehensive data store capability discovery
+  system that enables intelligent upload strategy selection based on actual data store
+  capabilities. Here's what was accomplished:
+
+  🔧 Core Infrastructure
+
+  1. DataStoreCapabilities Interface
+  (@packages/uploadista/core/src/types/data-store.ts)
+  - Added DataStoreCapabilities type with properties for parallel uploads,
+  concatenation, deferred length, resumable uploads, transactional uploads, concurrency
+   limits, and chunk size constraints
+  - Extended DataStore interface with getCapabilities() and validateUploadStrategy()
+  methods
+  - Added UploadStrategy type for "single" | "parallel" strategies
+
+  2. Upload Strategy Negotiator
+  (@packages/uploadista/core/src/upload/upload-strategy-negotiator.ts)
+  - Created UploadStrategyNegotiator class for intelligent strategy selection
+  - Implements capability-based validation and automatic strategy optimization
+  - Considers file size, data store constraints, and client preferences
+  - Provides detailed reasoning and warnings for strategy decisions
+
+  🏪 Data Store Implementations
+
+  1. S3 Store - Full parallel upload capabilities:
+  - ✅ Parallel uploads with up to 60 concurrent parts
+  - ✅ Native concatenation through multipart completion
+  - ✅ 5MiB-5GiB chunk size limits, 10K parts maximum
+  - ✅ Transactional uploads with rollback support
+
+  2. GCS Store - Limited parallel support:
+  - ❌ No native parallel uploads (uses file combination)
+  - ✅ Concatenation through bucket.combine()
+  - ✅ Sequential operations with patch-based resumption
+  - ⚠️ Requires ordered chunks
+
+  3. Filesystem Store - Basic sequential operations:
+  - ❌ No parallel upload support
+  - ❌ No concatenation capabilities
+  - ✅ Offset-based resumable uploads only
+  - ⚠️ Sequential write operations only
+
+  🚀 Client-Side Integration
+
+  1. Enhanced Upload Client
+  (@packages/uploadista/clients/client/src/upload/create-upload-client.ts)
+  - Added UploadStrategyConfig for fine-grained strategy control
+  - Integrated capability negotiation into upload workflow
+  - Automatic strategy selection with detailed logging
+  - Configuration validation on client creation
+  - New client methods: validateConfiguration(), getCapabilities()
+
+  2. Mock Data Store (@packages/uploadista/clients/client/src/mock-data-store.ts)
+  - Client-side capability simulation for strategy negotiation
+  - Predefined capability sets for S3, GCS, and filesystem backends
+  - Enables intelligent client-side strategy decisions
+
+  📝 Enhanced Examples
+
+  1. Connection Pooling Example - Updated with:
+  - Capability-aware client configuration
+  - Backend-specific optimization examples (S3, GCS, filesystem)
+  - Strategy comparison demonstrations
+  - Configuration validation examples
+
+  2. Advanced Example - Added:
+  - Capability negotiation demonstrations
+  - Backend adaptation scenarios
+  - Real-world strategy selection examples
+
+  🎯 Key Benefits
+
+  For Developers:
+  - Automatic Optimization: System automatically selects the best upload strategy based
+   on data store capabilities
+  - Configuration Validation: Early validation prevents runtime errors and suboptimal
+  configurations
+  - Backend Agnostic: Same client code works optimally across different storage
+  backends
+  - Intelligent Fallbacks: Graceful degradation when preferred strategies aren't
+  supported
+
+  For Different Backends:
+  - S3: Leverages full multipart upload capabilities with high concurrency
+  - GCS: Uses sequential uploads with file combination for optimal performance
+  - Filesystem: Employs offset-based resumable uploads with proper error handling
+
+  Additional Important Capabilities:
+  - Deferred Length Uploads: For streaming scenarios where file size is unknown upfront
+  - Transactional Uploads: With rollback capabilities for data integrity
+  - Resumable Uploads: Cross-session upload continuation
+  - Smart Chunking Integration: Chunk sizes optimized per data store constraints
+
+  The implementation provides a robust foundation for upload optimization that adapts
+  to the capabilities of any storage backend, ensuring optimal performance and
+  reliability across different deployment scenarios.

package/FRAMEWORK_INTEGRATION.md

@@ -0,0 +1,407 @@
+# Framework Integration Guide
+
+This guide explains how to wrap `@uploadista/client` in a framework-specific client package (React, Vue, Angular, Svelte, etc.).
+
+## Overview
+
+The `@uploadista/client` package is designed to be framework-agnostic. It provides:
+
+- **UploadistaClient**: Core client for uploads and flow management
+- **Event-based architecture**: Plain JavaScript callbacks, no framework coupling
+- **Type-safe API**: Full TypeScript support
+- **WebSocket management**: Unified WebSocket handling for upload and flow events
+- **Authentication**: Flexible auth strategies
+
+## Architecture Pattern
+
+Framework clients should wrap the base client with framework-specific primitives:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                Framework Client Layer                        │
+│  - Framework-specific state management (hooks/composables)  │
+│  - Component library                                         │
+│  - Dependency injection (Context/Provide-Inject/Services)   │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│            Base Client (@uploadista/client)                  │
+│  - UploadistaClient (framework-agnostic)                    │
+│  - Event handlers (plain callbacks)                          │
+│  - WebSocket management                                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Integration Points
+
+### 1. Client Instance Management
+
+**Challenge**: Share a single client instance across the application.
+
+**Solutions**:
+- **React**: Context API + `useContext` hook
+- **Vue**: Plugin + `provide`/`inject`
+- **Angular**: Injectable service
+- **Svelte**: Context API
+
+**Example (React)**:
+```typescript
+import { createContext, useContext } from 'react'
+import { createUploadistaClient, type UploadistaClient } from '@uploadista/client'
+
+const UploadistaContext = createContext<UploadistaClient | null>(null)
+
+export function UploadistaProvider({ children, options }) {
+  const client = useMemo(() => createUploadistaClient(options), [options])
+  return <UploadistaContext.Provider value={client}>{children}</UploadistaContext.Provider>
+}
+
+export function useUploadistaClient() {
+  const client = useContext(UploadistaContext)
+  if (!client) throw new Error('useUploadistaClient must be used within UploadistaProvider')
+  return client
+}
+```
+
+**Example (Vue)**:
+```typescript
+import { inject, type App } from 'vue'
+import { createUploadistaClient, type UploadistaClient } from '@uploadista/client'
+
+const UPLOADISTA_CLIENT_KEY = Symbol('uploadista-client')
+
+export function createUploadistaPlugin(options: UploadistaOptions) {
+  return {
+    install(app: App) {
+      const client = createUploadistaClient(options)
+      app.provide(UPLOADISTA_CLIENT_KEY, client)
+    }
+  }
+}
+
+export function useUploadistaClient(): UploadistaClient {
+  const client = inject(UPLOADISTA_CLIENT_KEY)
+  if (!client) throw new Error('useUploadistaClient must be used within app with uploadista plugin')
+  return client
+}
+```
+
+### 2. State Management
+
+**Challenge**: Expose upload/flow state reactively using framework primitives.
+
+**Approach**:
+1. Wrap client methods with framework state
+2. Subscribe to client events using callbacks
+3. Update reactive state on events
+4. Clean up subscriptions on unmount
+
+**Example (React)**:
+```typescript
+import { useState, useCallback, useEffect } from 'react'
+import { useUploadistaClient } from './useUploadistaClient'
+
+export function useUpload(options?: UseUploadOptions) {
+  const client = useUploadistaClient()
+  const [state, setState] = useState<UploadState>({
+    status: 'idle',
+    progress: 0,
+    // ...
+  })
+
+  const upload = useCallback(async (file: File) => {
+    setState(prev => ({ ...prev, status: 'uploading' }))
+
+    try {
+      const result = await client.upload(file, {
+        onProgress: (_, bytesUploaded, totalBytes) => {
+          setState(prev => ({
+            ...prev,
+            progress: totalBytes ? (bytesUploaded / totalBytes) * 100 : 0,
+            bytesUploaded,
+            totalBytes
+          }))
+        }
+      })
+
+      setState(prev => ({ ...prev, status: 'success', result }))
+    } catch (error) {
+      setState(prev => ({ ...prev, status: 'error', error }))
+    }
+  }, [client])
+
+  return { state, upload }
+}
+```
+
+**Example (Vue)**:
+```typescript
+import { reactive, readonly } from 'vue'
+import { useUploadistaClient } from './useUploadistaClient'
+
+export function useUpload(options?: UseUploadOptions) {
+  const client = useUploadistaClient()
+  const state = reactive<UploadState>({
+    status: 'idle',
+    progress: 0,
+    // ...
+  })
+
+  const upload = async (file: File) => {
+    state.status = 'uploading'
+
+    try {
+      const result = await client.upload(file, {
+        onProgress: (_, bytesUploaded, totalBytes) => {
+          state.progress = totalBytes ? (bytesUploaded / totalBytes) * 100 : 0
+          state.bytesUploaded = bytesUploaded
+          state.totalBytes = totalBytes
+        }
+      })
+
+      state.status = 'success'
+      state.result = result
+    } catch (error) {
+      state.status = 'error'
+      state.error = error
+    }
+  }
+
+  return { state: readonly(state), upload }
+}
+```
+
+### 3. Event Handling
+
+**Event System**: The base client uses plain callback functions for events.
+
+**Event Types**:
+- `onProgress`: Upload progress updates `(uploadId, bytesUploaded, totalBytes) => void`
+- `onComplete`: Upload completion `(uploadId, result) => void`
+- `onError`: Upload error `(uploadId, error) => void`
+- `onAbort`: Upload aborted `(uploadId) => void`
+
+**WebSocket Events**:
+- `UploadEvent`: Upload-related events (progress, complete, error)
+- `FlowEvent`: Flow execution events (node start, node complete, job complete)
+
+**Integration Pattern**:
+```typescript
+// Framework wrapper should:
+1. Accept event callbacks from user
+2. Call base client methods with callbacks
+3. Update framework state in callbacks
+4. Clean up on unmount
+
+// Example:
+const upload = async (file: File) => {
+  await client.upload(file, {
+    onProgress: (id, bytes, total) => {
+      // Update framework state
+      updateState({ progress: (bytes / total) * 100 })
+      // Call user callback if provided
+      options?.onProgress?.(id, bytes, total)
+    }
+  })
+}
+```
+
+### 4. Lifecycle Management
+
+**Challenge**: Clean up resources when components unmount.
+
+**Resources to clean up**:
+- WebSocket connections
+- Ongoing uploads (optionally abort)
+- Event listeners
+- Timers/intervals
+
+**Example (React)**:
+```typescript
+useEffect(() => {
+  // Setup
+  const ws = client.openUploadWebSocket(uploadId)
+
+  // Cleanup
+  return () => {
+    client.closeUploadWebSocket(uploadId)
+  }
+}, [uploadId])
+```
+
+**Example (Vue)**:
+```typescript
+import { onUnmounted } from 'vue'
+
+export function useFlowUpload() {
+  // Setup
+  const ws = await client.openFlowWebSocket(jobId)
+
+  // Cleanup
+  onUnmounted(() => {
+    client.closeFlowWebSocket(jobId)
+  })
+}
+```
+
+### 5. TypeScript Integration
+
+**Import types from base client**:
+```typescript
+import type {
+  UploadistaClient,
+  UploadOptions,
+  UploadResult,
+  FlowUploadOptions,
+  FlowResult
+} from '@uploadista/client'
+```
+
+**Extend types for framework-specific needs**:
+```typescript
+// Add framework-specific options
+export interface UseUploadOptions extends UploadOptions {
+  onMounted?: () => void
+  suspense?: boolean
+}
+```
+
+### 6. Component Library (Optional)
+
+Framework clients can provide basic unstyled components:
+
+**Recommended components**:
+- `UploadZone`: File input + drag-drop area
+- `UploadList`: Display upload progress for multiple files
+- `FlowUploadZone`: Upload through flow
+- `FlowUploadList`: Display flow upload progress
+
+**Principles**:
+- Keep components unstyled or minimally styled
+- Use slots/render props for customization
+- Expose underlying composables/hooks
+- Focus on functionality, not aesthetics
+
+## Testing Strategy
+
+### Unit Tests
+- Mock base client responses
+- Test state updates
+- Verify cleanup logic
+- Test error handling
+
+### Integration Tests
+- Test with real base client
+- Verify event propagation
+- Test WebSocket connections (mocked)
+- Validate lifecycle management
+
+## Framework-Specific Considerations
+
+### React
+- Use hooks for state management
+- Memoize callbacks with `useCallback`
+- Memoize derived state with `useMemo`
+- Clean up in `useEffect` return
+- Consider React 18+ features (Suspense, Transitions)
+
+### Vue
+- Use Composition API (`ref`, `reactive`, `computed`)
+- Clean up in `onUnmounted`
+- Use `readonly` to prevent external mutations
+- Consider SSR with Nuxt.js
+- Vue DevTools integration for debugging
+
+### Angular
+- Use Injectable services
+- RxJS observables for events
+- OnDestroy lifecycle hook for cleanup
+- Angular Signals for reactive state
+- Zone.js considerations
+
+### Svelte
+- Use stores for shared state
+- Context API for client sharing
+- `onDestroy` for cleanup
+- Reactive statements for derived state
+- SvelteKit SSR considerations
+
+## Common Patterns
+
+### Pattern 1: Multiple Upload Management
+
+Track array of uploads with aggregate state:
+
+```typescript
+// Pseudo-code
+const uploads = reactive([])
+const aggregate = computed(() => ({
+  totalProgress: average(uploads.map(u => u.progress)),
+  allComplete: uploads.every(u => u.status === 'success'),
+  hasErrors: uploads.some(u => u.status === 'error')
+}))
+```
+
+### Pattern 2: Retry with Exponential Backoff
+
+Implement retry logic in framework wrapper:
+
+```typescript
+const retry = async (file: File, attempt = 0) => {
+  try {
+    await upload(file)
+  } catch (error) {
+    if (attempt < maxRetries) {
+      await delay(2 ** attempt * 1000)
+      return retry(file, attempt + 1)
+    }
+    throw error
+  }
+}
+```
+
+### Pattern 3: Resumable Upload Recovery
+
+Recover previous uploads on mount:
+
+```typescript
+// On mount
+const previousUploads = await client.listPreviousUploads()
+if (previousUploads.length > 0) {
+  // Prompt user to resume or clear
+}
+```
+
+## Checklist for New Framework Integration
+
+- [ ] Client instance sharing mechanism (Context/Plugin/Service)
+- [ ] Composables/Hooks for all upload patterns
+  - [ ] Single upload
+  - [ ] Multiple uploads
+  - [ ] Flow upload
+  - [ ] Multiple flow uploads
+  - [ ] Drag and drop
+  - [ ] Upload metrics
+- [ ] WebSocket lifecycle management
+- [ ] Cleanup on unmount
+- [ ] TypeScript types for all public APIs
+- [ ] Basic unstyled components
+- [ ] Comprehensive example application
+- [ ] Unit tests (>80% coverage)
+- [ ] Integration tests
+- [ ] Documentation (README, API reference)
+- [ ] Migration guide (from other frameworks)
+
+## Resources
+
+- [Base Client Source](./src/)
+- [React Client Example](../react/)
+- [Vue Client Example](../vue/)
+- [Framework Utilities](./src/framework-utils.ts)
+
+## Support
+
+For questions about framework integration, please:
+1. Check existing framework clients for patterns
+2. Review this guide
+3. Open an issue with the `framework-integration` label

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 uploadista
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.