@uploadista/client-core 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (235) hide show
  1. package/.turbo/turbo-build.log +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +100 -0
  4. package/dist/auth/auth-http-client.d.ts +50 -0
  5. package/dist/auth/auth-http-client.d.ts.map +1 -0
  6. package/dist/auth/auth-http-client.js +110 -0
  7. package/dist/auth/direct-auth.d.ts +38 -0
  8. package/dist/auth/direct-auth.d.ts.map +1 -0
  9. package/dist/auth/direct-auth.js +95 -0
  10. package/dist/auth/index.d.ts +6 -0
  11. package/dist/auth/index.d.ts.map +1 -0
  12. package/dist/auth/index.js +5 -0
  13. package/dist/auth/no-auth.d.ts +26 -0
  14. package/dist/auth/no-auth.d.ts.map +1 -0
  15. package/dist/auth/no-auth.js +33 -0
  16. package/dist/auth/saas-auth.d.ts +80 -0
  17. package/dist/auth/saas-auth.d.ts.map +1 -0
  18. package/dist/auth/saas-auth.js +167 -0
  19. package/dist/auth/types.d.ts +101 -0
  20. package/dist/auth/types.d.ts.map +1 -0
  21. package/dist/auth/types.js +8 -0
  22. package/dist/chunk-buffer.d.ts +209 -0
  23. package/dist/chunk-buffer.d.ts.map +1 -0
  24. package/dist/chunk-buffer.js +236 -0
  25. package/dist/client/create-uploadista-client.d.ts +369 -0
  26. package/dist/client/create-uploadista-client.d.ts.map +1 -0
  27. package/dist/client/create-uploadista-client.js +518 -0
  28. package/dist/client/index.d.ts +4 -0
  29. package/dist/client/index.d.ts.map +1 -0
  30. package/dist/client/index.js +3 -0
  31. package/dist/client/uploadista-api.d.ts +284 -0
  32. package/dist/client/uploadista-api.d.ts.map +1 -0
  33. package/dist/client/uploadista-api.js +444 -0
  34. package/dist/client/uploadista-websocket-manager.d.ts +110 -0
  35. package/dist/client/uploadista-websocket-manager.d.ts.map +1 -0
  36. package/dist/client/uploadista-websocket-manager.js +207 -0
  37. package/dist/error.d.ts +106 -0
  38. package/dist/error.d.ts.map +1 -0
  39. package/dist/error.js +69 -0
  40. package/dist/index.d.ts +9 -0
  41. package/dist/index.d.ts.map +1 -0
  42. package/dist/index.js +12 -0
  43. package/dist/logger.d.ts +70 -0
  44. package/dist/logger.d.ts.map +1 -0
  45. package/dist/logger.js +59 -0
  46. package/dist/mock-data-store.d.ts +30 -0
  47. package/dist/mock-data-store.d.ts.map +1 -0
  48. package/dist/mock-data-store.js +88 -0
  49. package/dist/network-monitor.d.ts +262 -0
  50. package/dist/network-monitor.d.ts.map +1 -0
  51. package/dist/network-monitor.js +291 -0
  52. package/dist/services/abort-controller-service.d.ts +19 -0
  53. package/dist/services/abort-controller-service.d.ts.map +1 -0
  54. package/dist/services/abort-controller-service.js +4 -0
  55. package/dist/services/checksum-service.d.ts +4 -0
  56. package/dist/services/checksum-service.d.ts.map +1 -0
  57. package/dist/services/checksum-service.js +1 -0
  58. package/dist/services/file-reader-service.d.ts +38 -0
  59. package/dist/services/file-reader-service.d.ts.map +1 -0
  60. package/dist/services/file-reader-service.js +4 -0
  61. package/dist/services/fingerprint-service.d.ts +4 -0
  62. package/dist/services/fingerprint-service.d.ts.map +1 -0
  63. package/dist/services/fingerprint-service.js +1 -0
  64. package/dist/services/http-client.d.ts +182 -0
  65. package/dist/services/http-client.d.ts.map +1 -0
  66. package/dist/services/http-client.js +1 -0
  67. package/dist/services/id-generation-service.d.ts +10 -0
  68. package/dist/services/id-generation-service.d.ts.map +1 -0
  69. package/dist/services/id-generation-service.js +1 -0
  70. package/dist/services/index.d.ts +11 -0
  71. package/dist/services/index.d.ts.map +1 -0
  72. package/dist/services/index.js +10 -0
  73. package/dist/services/platform-service.d.ts +48 -0
  74. package/dist/services/platform-service.d.ts.map +1 -0
  75. package/dist/services/platform-service.js +10 -0
  76. package/dist/services/service-container.d.ts +25 -0
  77. package/dist/services/service-container.d.ts.map +1 -0
  78. package/dist/services/service-container.js +1 -0
  79. package/dist/services/storage-service.d.ts +26 -0
  80. package/dist/services/storage-service.d.ts.map +1 -0
  81. package/dist/services/storage-service.js +1 -0
  82. package/dist/services/websocket-service.d.ts +36 -0
  83. package/dist/services/websocket-service.d.ts.map +1 -0
  84. package/dist/services/websocket-service.js +4 -0
  85. package/dist/smart-chunker.d.ts +72 -0
  86. package/dist/smart-chunker.d.ts.map +1 -0
  87. package/dist/smart-chunker.js +317 -0
  88. package/dist/storage/client-storage.d.ts +148 -0
  89. package/dist/storage/client-storage.d.ts.map +1 -0
  90. package/dist/storage/client-storage.js +62 -0
  91. package/dist/storage/in-memory-storage-service.d.ts +7 -0
  92. package/dist/storage/in-memory-storage-service.d.ts.map +1 -0
  93. package/dist/storage/in-memory-storage-service.js +24 -0
  94. package/dist/storage/index.d.ts +3 -0
  95. package/dist/storage/index.d.ts.map +1 -0
  96. package/dist/storage/index.js +2 -0
  97. package/dist/types/buffered-chunk.d.ts +6 -0
  98. package/dist/types/buffered-chunk.d.ts.map +1 -0
  99. package/dist/types/buffered-chunk.js +1 -0
  100. package/dist/types/chunk-metrics.d.ts +12 -0
  101. package/dist/types/chunk-metrics.d.ts.map +1 -0
  102. package/dist/types/chunk-metrics.js +1 -0
  103. package/dist/types/flow-result.d.ts +11 -0
  104. package/dist/types/flow-result.d.ts.map +1 -0
  105. package/dist/types/flow-result.js +1 -0
  106. package/dist/types/flow-upload-config.d.ts +54 -0
  107. package/dist/types/flow-upload-config.d.ts.map +1 -0
  108. package/dist/types/flow-upload-config.js +1 -0
  109. package/dist/types/flow-upload-item.d.ts +16 -0
  110. package/dist/types/flow-upload-item.d.ts.map +1 -0
  111. package/dist/types/flow-upload-item.js +1 -0
  112. package/dist/types/flow-upload-options.d.ts +41 -0
  113. package/dist/types/flow-upload-options.d.ts.map +1 -0
  114. package/dist/types/flow-upload-options.js +1 -0
  115. package/dist/types/index.d.ts +14 -0
  116. package/dist/types/index.d.ts.map +1 -0
  117. package/dist/types/index.js +13 -0
  118. package/dist/types/multi-flow-upload-options.d.ts +33 -0
  119. package/dist/types/multi-flow-upload-options.d.ts.map +1 -0
  120. package/dist/types/multi-flow-upload-options.js +1 -0
  121. package/dist/types/multi-flow-upload-state.d.ts +9 -0
  122. package/dist/types/multi-flow-upload-state.d.ts.map +1 -0
  123. package/dist/types/multi-flow-upload-state.js +1 -0
  124. package/dist/types/performance-insights.d.ts +11 -0
  125. package/dist/types/performance-insights.d.ts.map +1 -0
  126. package/dist/types/performance-insights.js +1 -0
  127. package/dist/types/previous-upload.d.ts +20 -0
  128. package/dist/types/previous-upload.d.ts.map +1 -0
  129. package/dist/types/previous-upload.js +9 -0
  130. package/dist/types/upload-options.d.ts +40 -0
  131. package/dist/types/upload-options.d.ts.map +1 -0
  132. package/dist/types/upload-options.js +1 -0
  133. package/dist/types/upload-response.d.ts +6 -0
  134. package/dist/types/upload-response.d.ts.map +1 -0
  135. package/dist/types/upload-response.js +1 -0
  136. package/dist/types/upload-result.d.ts +57 -0
  137. package/dist/types/upload-result.d.ts.map +1 -0
  138. package/dist/types/upload-result.js +1 -0
  139. package/dist/types/upload-session-metrics.d.ts +16 -0
  140. package/dist/types/upload-session-metrics.d.ts.map +1 -0
  141. package/dist/types/upload-session-metrics.js +1 -0
  142. package/dist/upload/chunk-upload.d.ts +40 -0
  143. package/dist/upload/chunk-upload.d.ts.map +1 -0
  144. package/dist/upload/chunk-upload.js +82 -0
  145. package/dist/upload/flow-upload.d.ts +48 -0
  146. package/dist/upload/flow-upload.d.ts.map +1 -0
  147. package/dist/upload/flow-upload.js +240 -0
  148. package/dist/upload/index.d.ts +3 -0
  149. package/dist/upload/index.d.ts.map +1 -0
  150. package/dist/upload/index.js +2 -0
  151. package/dist/upload/parallel-upload.d.ts +65 -0
  152. package/dist/upload/parallel-upload.d.ts.map +1 -0
  153. package/dist/upload/parallel-upload.js +231 -0
  154. package/dist/upload/single-upload.d.ts +118 -0
  155. package/dist/upload/single-upload.d.ts.map +1 -0
  156. package/dist/upload/single-upload.js +332 -0
  157. package/dist/upload/upload-manager.d.ts +30 -0
  158. package/dist/upload/upload-manager.d.ts.map +1 -0
  159. package/dist/upload/upload-manager.js +57 -0
  160. package/dist/upload/upload-metrics.d.ts +37 -0
  161. package/dist/upload/upload-metrics.d.ts.map +1 -0
  162. package/dist/upload/upload-metrics.js +236 -0
  163. package/dist/upload/upload-storage.d.ts +32 -0
  164. package/dist/upload/upload-storage.d.ts.map +1 -0
  165. package/dist/upload/upload-storage.js +46 -0
  166. package/dist/upload/upload-strategy.d.ts +66 -0
  167. package/dist/upload/upload-strategy.d.ts.map +1 -0
  168. package/dist/upload/upload-strategy.js +171 -0
  169. package/dist/upload/upload-utils.d.ts +26 -0
  170. package/dist/upload/upload-utils.d.ts.map +1 -0
  171. package/dist/upload/upload-utils.js +80 -0
  172. package/package.json +29 -0
  173. package/src/__tests__/smart-chunking.test.ts +399 -0
  174. package/src/auth/__tests__/auth-http-client.test.ts +327 -0
  175. package/src/auth/__tests__/direct-auth.test.ts +135 -0
  176. package/src/auth/__tests__/no-auth.test.ts +40 -0
  177. package/src/auth/__tests__/saas-auth.test.ts +337 -0
  178. package/src/auth/auth-http-client.ts +150 -0
  179. package/src/auth/direct-auth.ts +121 -0
  180. package/src/auth/index.ts +5 -0
  181. package/src/auth/no-auth.ts +39 -0
  182. package/src/auth/saas-auth.ts +218 -0
  183. package/src/auth/types.ts +105 -0
  184. package/src/chunk-buffer.ts +287 -0
  185. package/src/client/create-uploadista-client.ts +901 -0
  186. package/src/client/index.ts +3 -0
  187. package/src/client/uploadista-api.ts +857 -0
  188. package/src/client/uploadista-websocket-manager.ts +275 -0
  189. package/src/error.ts +149 -0
  190. package/src/index.ts +13 -0
  191. package/src/logger.ts +104 -0
  192. package/src/mock-data-store.ts +97 -0
  193. package/src/network-monitor.ts +445 -0
  194. package/src/services/abort-controller-service.ts +21 -0
  195. package/src/services/checksum-service.ts +3 -0
  196. package/src/services/file-reader-service.ts +44 -0
  197. package/src/services/fingerprint-service.ts +6 -0
  198. package/src/services/http-client.ts +229 -0
  199. package/src/services/id-generation-service.ts +9 -0
  200. package/src/services/index.ts +10 -0
  201. package/src/services/platform-service.ts +65 -0
  202. package/src/services/service-container.ts +24 -0
  203. package/src/services/storage-service.ts +29 -0
  204. package/src/services/websocket-service.ts +33 -0
  205. package/src/smart-chunker.ts +451 -0
  206. package/src/storage/client-storage.ts +186 -0
  207. package/src/storage/in-memory-storage-service.ts +33 -0
  208. package/src/storage/index.ts +2 -0
  209. package/src/types/buffered-chunk.ts +5 -0
  210. package/src/types/chunk-metrics.ts +11 -0
  211. package/src/types/flow-result.ts +14 -0
  212. package/src/types/flow-upload-config.ts +56 -0
  213. package/src/types/flow-upload-item.ts +16 -0
  214. package/src/types/flow-upload-options.ts +56 -0
  215. package/src/types/index.ts +13 -0
  216. package/src/types/multi-flow-upload-options.ts +39 -0
  217. package/src/types/multi-flow-upload-state.ts +9 -0
  218. package/src/types/performance-insights.ts +7 -0
  219. package/src/types/previous-upload.ts +22 -0
  220. package/src/types/upload-options.ts +56 -0
  221. package/src/types/upload-response.ts +6 -0
  222. package/src/types/upload-result.ts +60 -0
  223. package/src/types/upload-session-metrics.ts +15 -0
  224. package/src/upload/chunk-upload.ts +151 -0
  225. package/src/upload/flow-upload.ts +367 -0
  226. package/src/upload/index.ts +2 -0
  227. package/src/upload/parallel-upload.ts +387 -0
  228. package/src/upload/single-upload.ts +554 -0
  229. package/src/upload/upload-manager.ts +106 -0
  230. package/src/upload/upload-metrics.ts +340 -0
  231. package/src/upload/upload-storage.ts +87 -0
  232. package/src/upload/upload-strategy.ts +296 -0
  233. package/src/upload/upload-utils.ts +114 -0
  234. package/tsconfig.json +23 -0
  235. package/tsconfig.tsbuildinfo +1 -0
@@ -0,0 +1,262 @@
1
+ /**
2
+ * Assessment of current network conditions based on upload performance.
3
+ *
4
+ * Used by smart chunking algorithms to adapt chunk sizes based on network quality.
5
+ */
6
+ export interface NetworkCondition {
7
+ /**
8
+ * Classification of network speed and stability:
9
+ * - "slow": Average speed below slowThreshold (default 50 KB/s)
10
+ * - "fast": Average speed above fastThreshold (default 5 MB/s)
11
+ * - "unstable": High variance in upload speeds
12
+ * - "unknown": Insufficient data to determine condition
13
+ */
14
+ type: "slow" | "fast" | "unstable" | "unknown";
15
+ /**
16
+ * Confidence level in the assessment (0-1).
17
+ * Higher values indicate more samples and more reliable assessment.
18
+ */
19
+ confidence: number;
20
+ }
21
+ /**
22
+ * Aggregated network performance metrics.
23
+ *
24
+ * Provides a comprehensive view of upload performance over time,
25
+ * useful for debugging connectivity issues and optimizing upload strategies.
26
+ */
27
+ export interface NetworkMetrics {
28
+ /** Average upload speed in bytes per second */
29
+ averageSpeed: number;
30
+ /** Average network latency in milliseconds */
31
+ latency: number;
32
+ /** Ratio of successful uploads (0-1) */
33
+ successRate: number;
34
+ /** Ratio of failed uploads (0-1) */
35
+ errorRate: number;
36
+ /** Total number of upload requests made */
37
+ totalRequests: number;
38
+ /** Total bytes uploaded successfully */
39
+ totalBytes: number;
40
+ /** Total time spent uploading in milliseconds */
41
+ totalTime: number;
42
+ }
43
+ /**
44
+ * Individual upload sample for network analysis.
45
+ *
46
+ * Each successful or failed upload is recorded as a sample,
47
+ * which is used to calculate network metrics and conditions.
48
+ */
49
+ export interface UploadSample {
50
+ /** Size of the uploaded chunk in bytes */
51
+ size: number;
52
+ /** Time taken to upload in milliseconds */
53
+ duration: number;
54
+ /** Whether the upload succeeded */
55
+ success: boolean;
56
+ /** Unix timestamp when the upload occurred */
57
+ timestamp: number;
58
+ /** Optional network latency measurement in milliseconds */
59
+ latency?: number;
60
+ }
61
+ /**
62
+ * Configuration options for NetworkMonitor.
63
+ *
64
+ * Controls how network conditions are assessed and how upload samples
65
+ * are analyzed to determine optimal chunking strategies.
66
+ */
67
+ export interface NetworkMonitorConfig {
68
+ /** Maximum number of samples to keep in memory. Defaults to 100. */
69
+ maxSamples?: number;
70
+ /** Smoothing factor for exponential moving average (0-1). Defaults to 0.1. */
71
+ smoothingFactor?: number;
72
+ /** Minimum samples required before assessing network condition. Defaults to 5. */
73
+ minSamplesForCondition?: number;
74
+ /** Upload speed threshold for "slow" classification in bytes/second. Defaults to 50 KB/s. */
75
+ slowThreshold?: number;
76
+ /** Upload speed threshold for "fast" classification in bytes/second. Defaults to 5 MB/s. */
77
+ fastThreshold?: number;
78
+ /** Coefficient of variation threshold for "unstable" classification. Defaults to 0.5. */
79
+ unstableThreshold?: number;
80
+ }
81
+ /**
82
+ * Monitors network performance during uploads to enable adaptive chunking.
83
+ *
84
+ * Tracks upload samples over time and analyzes them to determine network conditions
85
+ * (slow, fast, unstable). This information is used by smart chunking algorithms to
86
+ * dynamically adjust chunk sizes for optimal upload performance.
87
+ *
88
+ * The monitor maintains a rolling window of recent samples and calculates various
89
+ * metrics including average speed, latency, success rate, and throughput stability.
90
+ *
91
+ * @example Basic usage with smart chunking
92
+ * ```typescript
93
+ * const monitor = new NetworkMonitor({
94
+ * maxSamples: 100,
95
+ * slowThreshold: 50 * 1024, // 50 KB/s
96
+ * fastThreshold: 5 * 1024 * 1024, // 5 MB/s
97
+ * });
98
+ *
99
+ * // Record each upload
100
+ * monitor.recordUpload(
101
+ * chunkSize, // bytes
102
+ * duration, // milliseconds
103
+ * true, // success
104
+ * latency // optional latency
105
+ * );
106
+ *
107
+ * // Get current network condition
108
+ * const condition = monitor.getNetworkCondition();
109
+ * if (condition.type === 'slow') {
110
+ * // Use smaller chunks
111
+ * chunkSize = 256 * 1024;
112
+ * } else if (condition.type === 'fast') {
113
+ * // Use larger chunks
114
+ * chunkSize = 5 * 1024 * 1024;
115
+ * }
116
+ * ```
117
+ *
118
+ * @example Monitoring network metrics
119
+ * ```typescript
120
+ * const monitor = new NetworkMonitor();
121
+ *
122
+ * // After some uploads
123
+ * const metrics = monitor.getCurrentMetrics();
124
+ * console.log(`Average speed: ${metrics.averageSpeed / 1024} KB/s`);
125
+ * console.log(`Success rate: ${metrics.successRate * 100}%`);
126
+ * console.log(`Average latency: ${metrics.latency}ms`);
127
+ * ```
128
+ */
129
+ export declare class NetworkMonitor {
130
+ private samples;
131
+ private config;
132
+ private _currentMetrics;
133
+ /**
134
+ * Creates a new NetworkMonitor instance.
135
+ *
136
+ * @param config - Optional configuration for thresholds and sample management
137
+ */
138
+ constructor(config?: NetworkMonitorConfig);
139
+ /**
140
+ * Adds a raw upload sample to the monitor.
141
+ *
142
+ * This is called internally by recordUpload but can also be used
143
+ * to add pre-constructed samples for testing or custom tracking.
144
+ *
145
+ * @param sample - The upload sample to add
146
+ */
147
+ addSample(sample: UploadSample): void;
148
+ /**
149
+ * Records an upload operation for network analysis.
150
+ *
151
+ * This is the primary method for tracking upload performance. Each chunk upload
152
+ * should be recorded to build an accurate picture of network conditions.
153
+ *
154
+ * @param size - Size of the uploaded chunk in bytes
155
+ * @param duration - Time taken to upload in milliseconds
156
+ * @param success - Whether the upload succeeded
157
+ * @param latency - Optional network latency measurement in milliseconds
158
+ *
159
+ * @example Recording successful upload
160
+ * ```typescript
161
+ * const startTime = Date.now();
162
+ * await uploadChunk(data);
163
+ * const duration = Date.now() - startTime;
164
+ * monitor.recordUpload(data.length, duration, true);
165
+ * ```
166
+ *
167
+ * @example Recording failed upload
168
+ * ```typescript
169
+ * try {
170
+ * const startTime = Date.now();
171
+ * await uploadChunk(data);
172
+ * monitor.recordUpload(data.length, Date.now() - startTime, true);
173
+ * } catch (error) {
174
+ * monitor.recordUpload(data.length, Date.now() - startTime, false);
175
+ * }
176
+ * ```
177
+ */
178
+ recordUpload(size: number, duration: number, success: boolean, latency?: number): void;
179
+ /**
180
+ * Returns the current network metrics.
181
+ *
182
+ * Provides aggregated statistics about all recorded uploads including
183
+ * average speed, latency, success rate, and totals.
184
+ *
185
+ * @returns A snapshot of current network performance metrics
186
+ *
187
+ * @example
188
+ * ```typescript
189
+ * const metrics = monitor.getCurrentMetrics();
190
+ * console.log(`Speed: ${(metrics.averageSpeed / 1024).toFixed(2)} KB/s`);
191
+ * console.log(`Success: ${(metrics.successRate * 100).toFixed(1)}%`);
192
+ * console.log(`Latency: ${metrics.latency.toFixed(0)}ms`);
193
+ * ```
194
+ */
195
+ getCurrentMetrics(): NetworkMetrics;
196
+ /**
197
+ * Analyzes recent upload samples to determine current network condition.
198
+ *
199
+ * Uses statistical analysis (coefficient of variation, average speed) to classify
200
+ * the network as slow, fast, unstable, or unknown. The confidence level indicates
201
+ * how reliable the assessment is based on the number of samples collected.
202
+ *
203
+ * @returns Current network condition with confidence level
204
+ *
205
+ * @example Adaptive chunking based on network condition
206
+ * ```typescript
207
+ * const condition = monitor.getNetworkCondition();
208
+ *
209
+ * if (condition.confidence > 0.7) {
210
+ * switch (condition.type) {
211
+ * case 'fast':
212
+ * chunkSize = 10 * 1024 * 1024; // 10MB
213
+ * break;
214
+ * case 'slow':
215
+ * chunkSize = 256 * 1024; // 256KB
216
+ * break;
217
+ * case 'unstable':
218
+ * chunkSize = 1 * 1024 * 1024; // 1MB, conservative
219
+ * break;
220
+ * }
221
+ * }
222
+ * ```
223
+ */
224
+ getNetworkCondition(): NetworkCondition;
225
+ /**
226
+ * Calculates the optimal upload throughput based on recent successful uploads.
227
+ *
228
+ * Uses a weighted average that gives more weight to recent samples,
229
+ * providing a responsive measure of current network capacity.
230
+ *
231
+ * @returns Optimal throughput in bytes per second, or 0 if no successful samples
232
+ *
233
+ * @example Using for chunk size calculation
234
+ * ```typescript
235
+ * const throughput = monitor.getOptimalThroughput();
236
+ * // Target 1 second per chunk
237
+ * const optimalChunkSize = Math.min(throughput, MAX_CHUNK_SIZE);
238
+ * ```
239
+ */
240
+ getOptimalThroughput(): number;
241
+ /**
242
+ * Resets all samples and metrics to initial state.
243
+ *
244
+ * Useful when network conditions change significantly or when
245
+ * starting a new upload session.
246
+ *
247
+ * @example Resetting between uploads
248
+ * ```typescript
249
+ * // Complete first upload
250
+ * await uploadFile1();
251
+ *
252
+ * // Reset metrics before starting a new upload
253
+ * monitor.reset();
254
+ * await uploadFile2();
255
+ * ```
256
+ */
257
+ reset(): void;
258
+ private getRecentSuccessfulSamples;
259
+ private updateMetrics;
260
+ private createEmptyMetrics;
261
+ }
262
+ //# sourceMappingURL=network-monitor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"network-monitor.d.ts","sourceRoot":"","sources":["../src/network-monitor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAE/C;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IAErB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IAEpB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAElB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IAEtB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IAEnB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IAEb,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IAEjB,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IAEjB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAElB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,kFAAkF;IAClF,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC,6FAA6F;IAC7F,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,eAAe,CAAiB;IAExC;;;;OAIG;gBACS,MAAM,GAAE,oBAAyB;IAa7C;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAWrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,IAAI;IAUP;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,IAAI,cAAc;IAInC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,mBAAmB,IAAI,gBAAgB;IA6CvC;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,IAAI,MAAM;IAkB9B;;;;;;;;;;;;;;;OAeG;IACH,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,0BAA0B;IAKlC,OAAO,CAAC,aAAa;IA8CrB,OAAO,CAAC,kBAAkB;CAW3B"}
@@ -0,0 +1,291 @@
1
+ /**
2
+ * Monitors network performance during uploads to enable adaptive chunking.
3
+ *
4
+ * Tracks upload samples over time and analyzes them to determine network conditions
5
+ * (slow, fast, unstable). This information is used by smart chunking algorithms to
6
+ * dynamically adjust chunk sizes for optimal upload performance.
7
+ *
8
+ * The monitor maintains a rolling window of recent samples and calculates various
9
+ * metrics including average speed, latency, success rate, and throughput stability.
10
+ *
11
+ * @example Basic usage with smart chunking
12
+ * ```typescript
13
+ * const monitor = new NetworkMonitor({
14
+ * maxSamples: 100,
15
+ * slowThreshold: 50 * 1024, // 50 KB/s
16
+ * fastThreshold: 5 * 1024 * 1024, // 5 MB/s
17
+ * });
18
+ *
19
+ * // Record each upload
20
+ * monitor.recordUpload(
21
+ * chunkSize, // bytes
22
+ * duration, // milliseconds
23
+ * true, // success
24
+ * latency // optional latency
25
+ * );
26
+ *
27
+ * // Get current network condition
28
+ * const condition = monitor.getNetworkCondition();
29
+ * if (condition.type === 'slow') {
30
+ * // Use smaller chunks
31
+ * chunkSize = 256 * 1024;
32
+ * } else if (condition.type === 'fast') {
33
+ * // Use larger chunks
34
+ * chunkSize = 5 * 1024 * 1024;
35
+ * }
36
+ * ```
37
+ *
38
+ * @example Monitoring network metrics
39
+ * ```typescript
40
+ * const monitor = new NetworkMonitor();
41
+ *
42
+ * // After some uploads
43
+ * const metrics = monitor.getCurrentMetrics();
44
+ * console.log(`Average speed: ${metrics.averageSpeed / 1024} KB/s`);
45
+ * console.log(`Success rate: ${metrics.successRate * 100}%`);
46
+ * console.log(`Average latency: ${metrics.latency}ms`);
47
+ * ```
48
+ */
49
+ export class NetworkMonitor {
50
+ /**
51
+ * Creates a new NetworkMonitor instance.
52
+ *
53
+ * @param config - Optional configuration for thresholds and sample management
54
+ */
55
+ constructor(config = {}) {
56
+ this.samples = [];
57
+ this.config = {
58
+ maxSamples: config.maxSamples ?? 100,
59
+ smoothingFactor: config.smoothingFactor ?? 0.1,
60
+ minSamplesForCondition: config.minSamplesForCondition ?? 5,
61
+ slowThreshold: config.slowThreshold ?? 50 * 1024, // 50 KB/s
62
+ fastThreshold: config.fastThreshold ?? 5 * 1024 * 1024, // 5 MB/s
63
+ unstableThreshold: config.unstableThreshold ?? 0.5, // 50% coefficient of variation
64
+ };
65
+ this._currentMetrics = this.createEmptyMetrics();
66
+ }
67
+ /**
68
+ * Adds a raw upload sample to the monitor.
69
+ *
70
+ * This is called internally by recordUpload but can also be used
71
+ * to add pre-constructed samples for testing or custom tracking.
72
+ *
73
+ * @param sample - The upload sample to add
74
+ */
75
+ addSample(sample) {
76
+ this.samples.push(sample);
77
+ // Keep only the most recent samples
78
+ if (this.samples.length > this.config.maxSamples) {
79
+ this.samples = this.samples.slice(-this.config.maxSamples);
80
+ }
81
+ this.updateMetrics();
82
+ }
83
+ /**
84
+ * Records an upload operation for network analysis.
85
+ *
86
+ * This is the primary method for tracking upload performance. Each chunk upload
87
+ * should be recorded to build an accurate picture of network conditions.
88
+ *
89
+ * @param size - Size of the uploaded chunk in bytes
90
+ * @param duration - Time taken to upload in milliseconds
91
+ * @param success - Whether the upload succeeded
92
+ * @param latency - Optional network latency measurement in milliseconds
93
+ *
94
+ * @example Recording successful upload
95
+ * ```typescript
96
+ * const startTime = Date.now();
97
+ * await uploadChunk(data);
98
+ * const duration = Date.now() - startTime;
99
+ * monitor.recordUpload(data.length, duration, true);
100
+ * ```
101
+ *
102
+ * @example Recording failed upload
103
+ * ```typescript
104
+ * try {
105
+ * const startTime = Date.now();
106
+ * await uploadChunk(data);
107
+ * monitor.recordUpload(data.length, Date.now() - startTime, true);
108
+ * } catch (error) {
109
+ * monitor.recordUpload(data.length, Date.now() - startTime, false);
110
+ * }
111
+ * ```
112
+ */
113
+ recordUpload(size, duration, success, latency) {
114
+ this.addSample({
115
+ size,
116
+ duration,
117
+ success,
118
+ timestamp: Date.now(),
119
+ latency,
120
+ });
121
+ }
122
+ /**
123
+ * Returns the current network metrics.
124
+ *
125
+ * Provides aggregated statistics about all recorded uploads including
126
+ * average speed, latency, success rate, and totals.
127
+ *
128
+ * @returns A snapshot of current network performance metrics
129
+ *
130
+ * @example
131
+ * ```typescript
132
+ * const metrics = monitor.getCurrentMetrics();
133
+ * console.log(`Speed: ${(metrics.averageSpeed / 1024).toFixed(2)} KB/s`);
134
+ * console.log(`Success: ${(metrics.successRate * 100).toFixed(1)}%`);
135
+ * console.log(`Latency: ${metrics.latency.toFixed(0)}ms`);
136
+ * ```
137
+ */
138
+ getCurrentMetrics() {
139
+ return { ...this._currentMetrics };
140
+ }
141
+ /**
142
+ * Analyzes recent upload samples to determine current network condition.
143
+ *
144
+ * Uses statistical analysis (coefficient of variation, average speed) to classify
145
+ * the network as slow, fast, unstable, or unknown. The confidence level indicates
146
+ * how reliable the assessment is based on the number of samples collected.
147
+ *
148
+ * @returns Current network condition with confidence level
149
+ *
150
+ * @example Adaptive chunking based on network condition
151
+ * ```typescript
152
+ * const condition = monitor.getNetworkCondition();
153
+ *
154
+ * if (condition.confidence > 0.7) {
155
+ * switch (condition.type) {
156
+ * case 'fast':
157
+ * chunkSize = 10 * 1024 * 1024; // 10MB
158
+ * break;
159
+ * case 'slow':
160
+ * chunkSize = 256 * 1024; // 256KB
161
+ * break;
162
+ * case 'unstable':
163
+ * chunkSize = 1 * 1024 * 1024; // 1MB, conservative
164
+ * break;
165
+ * }
166
+ * }
167
+ * ```
168
+ */
169
+ getNetworkCondition() {
170
+ if (this.samples.length < this.config.minSamplesForCondition) {
171
+ return { type: "unknown", confidence: 0 };
172
+ }
173
+ const recentSamples = this.getRecentSuccessfulSamples();
174
+ if (recentSamples.length < this.config.minSamplesForCondition) {
175
+ return { type: "unknown", confidence: 0.3 };
176
+ }
177
+ const speeds = recentSamples.map((sample) => sample.size / (sample.duration / 1000));
178
+ const avgSpeed = speeds.reduce((sum, speed) => sum + speed, 0) / speeds.length;
179
+ // Calculate coefficient of variation for stability assessment
180
+ const variance = speeds.reduce((sum, speed) => sum + (speed - avgSpeed) ** 2, 0) /
181
+ speeds.length;
182
+ const stdDev = Math.sqrt(variance);
183
+ const coefficientOfVariation = stdDev / avgSpeed;
184
+ // Determine network condition
185
+ const confidence = Math.min(1, this.samples.length / (this.config.minSamplesForCondition * 2));
186
+ if (coefficientOfVariation > this.config.unstableThreshold) {
187
+ return { type: "unstable", confidence };
188
+ }
189
+ if (avgSpeed < this.config.slowThreshold) {
190
+ return { type: "slow", confidence };
191
+ }
192
+ if (avgSpeed > this.config.fastThreshold) {
193
+ return { type: "fast", confidence };
194
+ }
195
+ // Default to slow for conservative chunking
196
+ return { type: "slow", confidence: confidence * 0.7 };
197
+ }
198
+ /**
199
+ * Calculates the optimal upload throughput based on recent successful uploads.
200
+ *
201
+ * Uses a weighted average that gives more weight to recent samples,
202
+ * providing a responsive measure of current network capacity.
203
+ *
204
+ * @returns Optimal throughput in bytes per second, or 0 if no successful samples
205
+ *
206
+ * @example Using for chunk size calculation
207
+ * ```typescript
208
+ * const throughput = monitor.getOptimalThroughput();
209
+ * // Target 1 second per chunk
210
+ * const optimalChunkSize = Math.min(throughput, MAX_CHUNK_SIZE);
211
+ * ```
212
+ */
213
+ getOptimalThroughput() {
214
+ const recentSamples = this.getRecentSuccessfulSamples(10);
215
+ if (recentSamples.length === 0)
216
+ return 0;
217
+ // Calculate weighted average with recent samples having higher weight
218
+ let totalWeight = 0;
219
+ let weightedSum = 0;
220
+ recentSamples.forEach((sample, index) => {
221
+ const weight = index + 1; // More recent samples get higher weight
222
+ const throughput = sample.size / (sample.duration / 1000);
223
+ weightedSum += throughput * weight;
224
+ totalWeight += weight;
225
+ });
226
+ return totalWeight > 0 ? weightedSum / totalWeight : 0;
227
+ }
228
+ /**
229
+ * Resets all samples and metrics to initial state.
230
+ *
231
+ * Useful when network conditions change significantly or when
232
+ * starting a new upload session.
233
+ *
234
+ * @example Resetting between uploads
235
+ * ```typescript
236
+ * // Complete first upload
237
+ * await uploadFile1();
238
+ *
239
+ * // Reset metrics before starting a new upload
240
+ * monitor.reset();
241
+ * await uploadFile2();
242
+ * ```
243
+ */
244
+ reset() {
245
+ this.samples = [];
246
+ this._currentMetrics = this.createEmptyMetrics();
247
+ }
248
+ getRecentSuccessfulSamples(count) {
249
+ const successful = this.samples.filter((sample) => sample.success);
250
+ return count ? successful.slice(-count) : successful;
251
+ }
252
+ updateMetrics() {
253
+ const successfulSamples = this.samples.filter((sample) => sample.success);
254
+ const totalRequests = this.samples.length;
255
+ const totalSuccessful = successfulSamples.length;
256
+ if (totalRequests === 0) {
257
+ this._currentMetrics = this.createEmptyMetrics();
258
+ return;
259
+ }
260
+ const totalBytes = successfulSamples.reduce((sum, sample) => sum + sample.size, 0);
261
+ const totalTime = successfulSamples.reduce((sum, sample) => sum + sample.duration, 0);
262
+ const averageSpeed = totalTime > 0 ? totalBytes / (totalTime / 1000) : 0;
263
+ const successRate = totalSuccessful / totalRequests;
264
+ const errorRate = 1 - successRate;
265
+ // Calculate average latency from samples that have latency data
266
+ const samplesWithLatency = this.samples.filter((sample) => sample.latency !== undefined);
267
+ const averageLatency = samplesWithLatency.length > 0
268
+ ? samplesWithLatency.reduce((sum, sample) => sum + (sample.latency || 0), 0) / samplesWithLatency.length
269
+ : 0;
270
+ this._currentMetrics = {
271
+ averageSpeed,
272
+ latency: averageLatency,
273
+ successRate,
274
+ errorRate,
275
+ totalRequests,
276
+ totalBytes,
277
+ totalTime,
278
+ };
279
+ }
280
+ createEmptyMetrics() {
281
+ return {
282
+ averageSpeed: 0,
283
+ latency: 0,
284
+ successRate: 0,
285
+ errorRate: 0,
286
+ totalRequests: 0,
287
+ totalBytes: 0,
288
+ totalTime: 0,
289
+ };
290
+ }
291
+ }
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Platform-agnostic AbortController interface
3
+ */
4
+ export interface AbortControllerLike {
5
+ readonly signal: AbortSignalLike;
6
+ abort(reason?: unknown): void;
7
+ }
8
+ export interface AbortSignalLike {
9
+ readonly aborted: boolean;
10
+ addEventListener(type: "abort", listener: () => void): void;
11
+ removeEventListener(type: "abort", listener: () => void): void;
12
+ }
13
+ export interface AbortControllerFactory {
14
+ /**
15
+ * Create a new AbortController instance
16
+ */
17
+ create(): AbortControllerLike;
18
+ }
19
+ //# sourceMappingURL=abort-controller-service.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"abort-controller-service.d.ts","sourceRoot":"","sources":["../../src/services/abort-controller-service.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChE;AAED,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,IAAI,mBAAmB,CAAC;CAC/B"}
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Platform-agnostic AbortController interface
3
+ */
4
+ export {};
@@ -0,0 +1,4 @@
1
+ export interface ChecksumService {
2
+ computeChecksum(data: Uint8Array): Promise<string>;
3
+ }
4
+ //# sourceMappingURL=checksum-service.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"checksum-service.d.ts","sourceRoot":"","sources":["../../src/services/checksum-service.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpD"}
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Platform-agnostic file reader service
3
+ */
4
+ export type SliceResult = {
5
+ done: true;
6
+ value: null;
7
+ size: null;
8
+ } | {
9
+ done: boolean;
10
+ value: Uint8Array;
11
+ size: number;
12
+ };
13
+ export interface FileSource {
14
+ input: unknown;
15
+ size: number | null;
16
+ name: string | null;
17
+ type: string | null;
18
+ lastModified: number | null;
19
+ slice: (start: number, end: number) => Promise<SliceResult>;
20
+ close: () => void;
21
+ }
22
+ export interface FileReaderService<UploadInput> {
23
+ /**
24
+ * Open a file for reading
25
+ */
26
+ openFile(input: UploadInput, chunkSize: number): Promise<FileSource>;
27
+ }
28
+ export interface Base64Service {
29
+ /**
30
+ * Encode data to base64
31
+ */
32
+ toBase64(data: ArrayBuffer): string;
33
+ /**
34
+ * Decode base64 to data
35
+ */
36
+ fromBase64(data: string): ArrayBuffer;
37
+ }
38
+ //# sourceMappingURL=file-reader-service.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-reader-service.d.ts","sourceRoot":"","sources":["../../src/services/file-reader-service.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,WAAW,GACnB;IACE,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,IAAI,CAAC;IACZ,IAAI,EAAE,IAAI,CAAC;CACZ,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEN,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5D,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB,CAAC,WAAW;IAC5C;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC;IAEpC;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;CACvC"}
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Platform-agnostic file reader service
3
+ */
4
+ export {};
@@ -0,0 +1,4 @@
1
+ export interface FingerprintService<UploadInput> {
2
+ computeFingerprint(file: UploadInput, endpoint: string): Promise<string | null>;
3
+ }
4
+ //# sourceMappingURL=fingerprint-service.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fingerprint-service.d.ts","sourceRoot":"","sources":["../../src/services/fingerprint-service.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB,CAAC,WAAW;IAC7C,kBAAkB,CAChB,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3B"}
@@ -0,0 +1 @@
1
+ export {};