@uploadista/client-core 0.0.3

package/dist/upload/upload-metrics.js

@@ -0,0 +1,236 @@
+export class UploadMetrics {
+    constructor(config = {}) {
+        this.chunkHistory = [];
+        this.currentSession = {};
+        this.sessionStartTime = 0;
+        this.config = {
+            maxChunkHistory: config.maxChunkHistory ?? 1000,
+            enableDetailedMetrics: config.enableDetailedMetrics ?? true,
+            performanceThresholds: {
+                slowSpeed: 100 * 1024, // 100 KB/s
+                fastSpeed: 5 * 1024 * 1024, // 5 MB/s
+                highRetryRate: 0.2, // 20%
+                ...config.performanceThresholds,
+            },
+        };
+    }
+    startSession(uploadId, totalSize, adaptiveChunkingEnabled) {
+        this.sessionStartTime = Date.now();
+        this.currentSession = {
+            uploadId,
+            totalSize,
+            chunksCompleted: 0,
+            chunksTotal: Math.ceil(totalSize / (1024 * 1024)), // rough estimate
+            totalDuration: 0,
+            totalRetries: 0,
+            adaptiveChunkingEnabled,
+            startTime: this.sessionStartTime,
+        };
+        this.chunkHistory = [];
+    }
+    recordChunk(metrics) {
+        const chunkMetrics = {
+            ...metrics,
+            timestamp: Date.now(),
+        };
+        this.chunkHistory.push(chunkMetrics);
+        // Keep history within limits
+        if (this.chunkHistory.length > this.config.maxChunkHistory) {
+            this.chunkHistory = this.chunkHistory.slice(-this.config.maxChunkHistory);
+        }
+        // Update session metrics
+        if (this.currentSession && chunkMetrics.success) {
+            this.currentSession.chunksCompleted =
+                (this.currentSession.chunksCompleted || 0) + 1;
+            this.currentSession.totalDuration =
+                (this.currentSession.totalDuration || 0) + chunkMetrics.duration;
+            this.currentSession.totalRetries =
+                (this.currentSession.totalRetries || 0) + chunkMetrics.retryCount;
+        }
+    }
+    endSession() {
+        if (!this.currentSession.uploadId) {
+            return null;
+        }
+        const endTime = Date.now();
+        const totalDuration = endTime - this.sessionStartTime;
+        const successfulChunks = this.chunkHistory.filter((chunk) => chunk.success);
+        if (successfulChunks.length === 0) {
+            return null;
+        }
+        const speeds = successfulChunks.map((chunk) => chunk.speed);
+        const averageSpeed = speeds.reduce((sum, speed) => sum + speed, 0) / speeds.length;
+        const peakSpeed = Math.max(...speeds);
+        const minSpeed = Math.min(...speeds);
+        const successRate = successfulChunks.length / this.chunkHistory.length;
+        const sessionMetrics = {
+            uploadId: this.currentSession.uploadId || "",
+            totalSize: this.currentSession.totalSize || 0,
+            totalDuration,
+            chunksCompleted: successfulChunks.length,
+            chunksTotal: this.chunkHistory.length,
+            averageSpeed,
+            peakSpeed,
+            minSpeed,
+            totalRetries: this.currentSession.totalRetries || 0,
+            successRate,
+            adaptiveChunkingEnabled: this.currentSession.adaptiveChunkingEnabled || false,
+            startTime: this.currentSession.startTime || 0,
+            endTime,
+        };
+        // Reset current session
+        this.currentSession = {};
+        return sessionMetrics;
+    }
+    getCurrentSessionMetrics() {
+        return { ...this.currentSession };
+    }
+    getChunkHistory(count) {
+        const history = this.chunkHistory.slice();
+        return count ? history.slice(-count) : history;
+    }
+    getPerformanceInsights() {
+        if (this.chunkHistory.length < 5) {
+            return {
+                overallEfficiency: 0,
+                chunkingEffectiveness: 0,
+                networkStability: 0,
+                recommendations: ["Insufficient data for analysis"],
+                optimalChunkSizeRange: { min: 256 * 1024, max: 2 * 1024 * 1024 },
+            };
+        }
+        const successfulChunks = this.chunkHistory.filter((chunk) => chunk.success);
+        const speeds = successfulChunks.map((chunk) => chunk.speed);
+        // Calculate metrics
+        const averageSpeed = speeds.length > 0
+            ? speeds.reduce((sum, speed) => sum + speed, 0) / speeds.length
+            : 0;
+        const speedVariance = this.calculateVariance(speeds);
+        const speedStdDev = Math.sqrt(speedVariance);
+        const coefficientOfVariation = speedStdDev / averageSpeed;
+        // Overall efficiency based on speed and retry rate
+        const successRate = successfulChunks.length / this.chunkHistory.length;
+        const speedScore = Math.min(1, averageSpeed / this.config.performanceThresholds.fastSpeed);
+        const overallEfficiency = speedScore * 0.7 + successRate * 0.3;
+        // Network stability (lower coefficient of variation = higher stability)
+        const networkStability = Math.max(0, 1 - Math.min(1, coefficientOfVariation));
+        // Chunking effectiveness based on how well chunk sizes correlate with performance
+        const chunkingEffectiveness = this.calculateChunkingEffectiveness(successfulChunks);
+        // Generate recommendations
+        const recommendations = this.generateRecommendations(averageSpeed, successRate, coefficientOfVariation);
+        // Calculate optimal chunk size range
+        const optimalChunkSizeRange = this.calculateOptimalChunkSizeRange(successfulChunks);
+        return {
+            overallEfficiency,
+            chunkingEffectiveness,
+            networkStability,
+            recommendations,
+            optimalChunkSizeRange,
+        };
+    }
+    exportMetrics() {
+        return {
+            session: this.getCurrentSessionMetrics(),
+            chunks: this.getChunkHistory(),
+            insights: this.getPerformanceInsights(),
+        };
+    }
+    reset() {
+        this.chunkHistory = [];
+        this.currentSession = {};
+        this.sessionStartTime = 0;
+    }
+    calculateVariance(values) {
+        if (values.length === 0)
+            return 0;
+        const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+        const squaredDifferences = values.map((value) => (value - mean) ** 2);
+        return (squaredDifferences.reduce((sum, diff) => sum + diff, 0) / values.length);
+    }
+    calculateChunkingEffectiveness(chunks) {
+        if (chunks.length < 3)
+            return 0.5;
+        // Look for correlation between chunk size and upload speed
+        // Better chunking should show consistent performance across different sizes
+        const sizeGroups = this.groupChunksBySize(chunks);
+        if (Object.keys(sizeGroups).length < 2)
+            return 0.5;
+        // Calculate coefficient of variation for each size group
+        const groupVariations = Object.values(sizeGroups).map((group) => {
+            const speeds = group.map((chunk) => chunk.speed);
+            const mean = speeds.reduce((sum, speed) => sum + speed, 0) / speeds.length;
+            const variance = this.calculateVariance(speeds);
+            return Math.sqrt(variance) / mean;
+        });
+        // Lower average variation indicates better chunking effectiveness
+        const averageVariation = groupVariations.reduce((sum, cv) => sum + cv, 0) / groupVariations.length;
+        return Math.max(0, 1 - Math.min(1, averageVariation));
+    }
+    groupChunksBySize(chunks) {
+        const groups = {};
+        chunks.forEach((chunk) => {
+            // Group by size ranges (64KB, 128KB, 256KB, 512KB, 1MB, 2MB, 4MB, 8MB+)
+            let sizeGroup;
+            if (chunk.size < 128 * 1024)
+                sizeGroup = "64KB";
+            else if (chunk.size < 256 * 1024)
+                sizeGroup = "128KB";
+            else if (chunk.size < 512 * 1024)
+                sizeGroup = "256KB";
+            else if (chunk.size < 1024 * 1024)
+                sizeGroup = "512KB";
+            else if (chunk.size < 2 * 1024 * 1024)
+                sizeGroup = "1MB";
+            else if (chunk.size < 4 * 1024 * 1024)
+                sizeGroup = "2MB";
+            else if (chunk.size < 8 * 1024 * 1024)
+                sizeGroup = "4MB";
+            else
+                sizeGroup = "8MB+";
+            if (!groups[sizeGroup])
+                groups[sizeGroup] = [];
+            const group = groups[sizeGroup];
+            if (group)
+                group.push(chunk);
+        });
+        return groups;
+    }
+    generateRecommendations(averageSpeed, successRate, coefficientOfVariation) {
+        const recommendations = [];
+        if (averageSpeed < this.config.performanceThresholds.slowSpeed) {
+            recommendations.push("Consider using smaller chunk sizes for better performance on slow connections");
+        }
+        if (averageSpeed > this.config.performanceThresholds.fastSpeed) {
+            recommendations.push("Network is fast - larger chunk sizes may improve efficiency");
+        }
+        if (successRate < 0.9) {
+            recommendations.push("High failure rate detected - consider more conservative chunking strategy");
+        }
+        if (coefficientOfVariation > 0.5) {
+            recommendations.push("Network appears unstable - smaller, more frequent chunks may be more reliable");
+        }
+        if (coefficientOfVariation < 0.2 &&
+            averageSpeed > this.config.performanceThresholds.slowSpeed) {
+            recommendations.push("Stable network detected - larger chunks may improve efficiency");
+        }
+        if (recommendations.length === 0) {
+            recommendations.push("Performance appears optimal with current configuration");
+        }
+        return recommendations;
+    }
+    calculateOptimalChunkSizeRange(chunks) {
+        if (chunks.length < 5) {
+            return { min: 256 * 1024, max: 2 * 1024 * 1024 };
+        }
+        // Find chunks with best performance (top 30% by speed)
+        const sortedBySpeed = chunks.slice().sort((a, b) => b.speed - a.speed);
+        const topPerformers = sortedBySpeed.slice(0, Math.ceil(chunks.length * 0.3));
+        const topSizes = topPerformers.map((chunk) => chunk.size);
+        const minOptimal = Math.min(...topSizes);
+        const maxOptimal = Math.max(...topSizes);
+        return {
+            min: Math.max(64 * 1024, minOptimal), // At least 64KB
+            max: Math.min(32 * 1024 * 1024, maxOptimal), // At most 32MB
+        };
+    }
+}

package/dist/upload/upload-storage.d.ts

@@ -0,0 +1,32 @@
+import type { IdGenerationService } from "../services/id-generation-service";
+import type { ClientStorage } from "../storage/client-storage";
+import type { PreviousUpload } from "../types/previous-upload";
+/**
+ * Find previous uploads by fingerprint
+ */
+export declare function findPreviousUploads(clientStorage: ClientStorage, fingerprint: string): Promise<PreviousUpload[]>;
+/**
+ * Resume from a previous upload
+ */
+export declare function resumeFromPreviousUpload(previousUpload: PreviousUpload): {
+    uploadId: string | null;
+    parallelUploadUrls: string[] | undefined;
+    clientStorageKey: string | null;
+};
+/**
+ * Add the upload URL to the URL storage, if possible.
+ */
+export declare function saveUploadInClientStorage({ clientStorage, fingerprint, size, metadata, clientStorageKey, storeFingerprintForResuming, generateId, }: {
+    clientStorage: ClientStorage;
+    fingerprint: string;
+    size: number;
+    metadata: Record<string, string | number | boolean>;
+    clientStorageKey: string | null;
+    storeFingerprintForResuming: boolean;
+    generateId: IdGenerationService;
+}): Promise<string | undefined>;
+/**
+ * Remove the entry in the URL storage, if it has been saved before.
+ */
+export declare function removeFromClientStorage(clientStorage: ClientStorage, clientStorageKey: string): Promise<void>;
+//# sourceMappingURL=upload-storage.d.ts.map

package/dist/upload/upload-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-storage.d.ts","sourceRoot":"","sources":["../../src/upload/upload-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,EAAE,CAAC,CAE3B;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,cAAc,GAAG;IACxE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kBAAkB,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACzC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAMA;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAAC,EAC9C,aAAa,EACb,WAAW,EACX,IAAI,EACJ,QAAQ,EACR,gBAAgB,EAChB,2BAA2B,EAC3B,UAAU,GACX,EAAE;IACD,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACpD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2BAA2B,EAAE,OAAO,CAAC;IACrC,UAAU,EAAE,mBAAmB,CAAC;CACjC,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA2B9B;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,aAAa,EAC5B,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/upload/upload-storage.js

@@ -0,0 +1,46 @@
+/**
+ * Find previous uploads by fingerprint
+ */
+export async function findPreviousUploads(clientStorage, fingerprint) {
+    return clientStorage.findUploadsByFingerprint(fingerprint);
+}
+/**
+ * Resume from a previous upload
+ */
+export function resumeFromPreviousUpload(previousUpload) {
+    return {
+        uploadId: previousUpload.uploadId ?? null,
+        parallelUploadUrls: previousUpload.parallelUploadUrls,
+        clientStorageKey: previousUpload.clientStorageKey,
+    };
+}
+/**
+ * Add the upload URL to the URL storage, if possible.
+ */
+export async function saveUploadInClientStorage({ clientStorage, fingerprint, size, metadata, clientStorageKey, storeFingerprintForResuming, generateId, }) {
+    // We do not store the upload key
+    // - if it was disabled in the option, or
+    // - if no fingerprint was calculated for the input (i.e. a stream), or
+    // - if the key is already stored.
+    if (!storeFingerprintForResuming ||
+        !fingerprint ||
+        clientStorageKey != null) {
+        return undefined;
+    }
+    const storedUpload = {
+        size,
+        metadata,
+        creationTime: new Date().toString(),
+        clientStorageKey: fingerprint,
+    };
+    const newClientStorageKey = await clientStorage.addUpload(fingerprint, storedUpload, { generateId });
+    return newClientStorageKey;
+}
+/**
+ * Remove the entry in the URL storage, if it has been saved before.
+ */
+export async function removeFromClientStorage(clientStorage, clientStorageKey) {
+    if (!clientStorageKey)
+        return;
+    await clientStorage.removeUpload(clientStorageKey);
+}

package/dist/upload/upload-strategy.d.ts

@@ -0,0 +1,66 @@
+import type { DataStoreCapabilities } from "@uploadista/core/types";
+import { type NegotiatedStrategy, UploadStrategyNegotiator } from "@uploadista/core/upload";
+import type { Logger } from "../logger";
+import { MockClientDataStore } from "../mock-data-store";
+import type { HttpClient } from "../services/http-client";
+export type UploadStrategyConfig = {
+    preferredStrategy?: "single" | "parallel" | "auto";
+    minFileSizeForParallel?: number;
+    enableCapabilityNegotiation?: boolean;
+    onStrategySelected?: (strategy: {
+        chosen: "single" | "parallel";
+        chunkSize: number;
+        parallelUploads: number;
+        reasoning: string[];
+        warnings: string[];
+    }) => void;
+};
+export type UploadClientOptions = {
+    baseUrl: string;
+    uploadBasePath?: string;
+    storageId: string;
+    retryDelays?: number[];
+    chunkSize: number;
+    parallelUploads?: number;
+    parallelChunkSize?: number;
+    uploadStrategy?: UploadStrategyConfig;
+};
+export declare function createUploadStrategyNegotiator(dataStore: MockClientDataStore): UploadStrategyNegotiator;
+/**
+ * Fetch capabilities from server
+ */
+export declare function fetchServerCapabilities(baseUrl: string, uploadBasePath: string, storageId: string, httpClient: HttpClient): Promise<DataStoreCapabilities>;
+/**
+ * Negotiate upload strategy based on capabilities and options
+ */
+export declare function negotiateUploadStrategy({ capabilities, fileSize, chunkSize, parallelUploads, uploadLengthDeferred, strategyConfig, logger, }: {
+    capabilities: DataStoreCapabilities;
+    fileSize: number | null;
+    chunkSize: number;
+    parallelUploads: number;
+    uploadLengthDeferred?: boolean;
+    strategyConfig?: UploadStrategyConfig;
+    logger: Logger;
+}): NegotiatedStrategy;
+/**
+ * Validate upload client configuration against data store capabilities
+ */
+export declare function validateConfiguration(options: UploadClientOptions, capabilities: DataStoreCapabilities | undefined, logger: Logger): {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+};
+/**
+ * Async configuration validation with server capabilities
+ */
+export declare function validateConfigurationAsync(options: UploadClientOptions, httpClient: HttpClient, logger: Logger): Promise<{
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    capabilities: DataStoreCapabilities;
+}>;
+/**
+ * Validate options and throw if invalid
+ */
+export declare function validateAndThrow(options: UploadClientOptions, logger: Logger): void;
+//# sourceMappingURL=upload-strategy.d.ts.map

package/dist/upload/upload-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-strategy.d.ts","sourceRoot":"","sources":["../../src/upload/upload-strategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EACL,KAAK,kBAAkB,EACvB,wBAAwB,EAEzB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAEL,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG;IACjC,iBAAiB,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACnD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE;QAC9B,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;QAC9B,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,CAAC;QACxB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,KAAK,IAAI,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,CAAC;AAEF,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,mBAAmB,GAC7B,wBAAwB,CAI1B;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,MAAM,GACP,EAAE;IACD,YAAY,EAAE,qBAAqB,CAAC;IACpC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,kBAAkB,CAyDrB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,mBAAmB,EAC5B,YAAY,EAAE,qBAAqB,YAA4B,EAC/D,MAAM,EAAE,MAAM,GACb;IACD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CA4DA;AAED;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IACT,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,qBAAqB,CAAC;CACrC,CAAC,CA8BD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,MAAM,GACb,IAAI,CAeN"}

package/dist/upload/upload-strategy.js

@@ -0,0 +1,171 @@
+import { UploadStrategyNegotiator, } from "@uploadista/core/upload";
+import { UploadistaError } from "../error";
+import { defaultClientCapabilities, MockClientDataStore, } from "../mock-data-store";
+export function createUploadStrategyNegotiator(dataStore) {
+    return new UploadStrategyNegotiator(dataStore.getCapabilities(), (strategy) => dataStore.validateUploadStrategy(strategy));
+}
+/**
+ * Fetch capabilities from server
+ */
+export async function fetchServerCapabilities(baseUrl, uploadBasePath, storageId, httpClient) {
+    const capabilitiesUrl = `${baseUrl}/${uploadBasePath}/capabilities?storageId=${encodeURIComponent(storageId)}`;
+    try {
+        const response = await httpClient.request(capabilitiesUrl, {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch capabilities: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.capabilities;
+    }
+    catch (_error) {
+        // Fall back to default capabilities if server fetch fails
+        return defaultClientCapabilities;
+    }
+}
+/**
+ * Negotiate upload strategy based on capabilities and options
+ */
+export function negotiateUploadStrategy({ capabilities, fileSize, chunkSize, parallelUploads, uploadLengthDeferred, strategyConfig, logger, }) {
+    if (strategyConfig?.enableCapabilityNegotiation !== false) {
+        // Use capability negotiation with server-fetched capabilities
+        const mockDataStore = new MockClientDataStore(capabilities);
+        const negotiator = createUploadStrategyNegotiator(mockDataStore);
+        const negotiationOptions = {
+            fileSize: fileSize || 0,
+            preferredStrategy: strategyConfig?.preferredStrategy === "auto"
+                ? undefined
+                : strategyConfig?.preferredStrategy,
+            preferredChunkSize: chunkSize,
+            parallelUploads,
+            minChunkSizeForParallel: strategyConfig?.minFileSizeForParallel || 10 * 1024 * 1024,
+        };
+        const negotiatedStrategy = negotiator.negotiateStrategy(negotiationOptions);
+        // Log negotiation results
+        logger.log(`Upload strategy negotiated: ${negotiatedStrategy.strategy}`);
+        for (const reason of negotiatedStrategy.reasoning) {
+            logger.log(`  - ${reason}`);
+        }
+        for (const warning of negotiatedStrategy.warnings) {
+            logger.log(`  Warning: ${warning}`);
+        }
+        // Notify client of strategy selection if callback provided
+        strategyConfig?.onStrategySelected?.({
+            chosen: negotiatedStrategy.strategy,
+            chunkSize: negotiatedStrategy.chunkSize,
+            parallelUploads: negotiatedStrategy.parallelUploads,
+            reasoning: negotiatedStrategy.reasoning,
+            warnings: negotiatedStrategy.warnings,
+        });
+        return negotiatedStrategy;
+    }
+    else {
+        // Fallback to legacy logic
+        const shouldUseParallelUpload = parallelUploads > 1 &&
+            fileSize &&
+            fileSize > (strategyConfig?.minFileSizeForParallel || 10 * 1024 * 1024) &&
+            !uploadLengthDeferred;
+        return {
+            strategy: shouldUseParallelUpload ? "parallel" : "single",
+            chunkSize,
+            parallelUploads: shouldUseParallelUpload ? parallelUploads : 1,
+            reasoning: [
+                `Legacy strategy selection: ${shouldUseParallelUpload ? "parallel" : "single"}`,
+            ],
+            warnings: [],
+        };
+    }
+}
+/**
+ * Validate upload client configuration against data store capabilities
+ */
+export function validateConfiguration(options, capabilities = defaultClientCapabilities, logger) {
+    const errors = [];
+    const warnings = [];
+    // Validate against capabilities
+    const mockDataStore = new MockClientDataStore(capabilities);
+    const negotiator = createUploadStrategyNegotiator(mockDataStore);
+    const validation = negotiator.validateConfiguration({
+        fileSize: 0, // Placeholder for validation
+        preferredStrategy: options.uploadStrategy?.preferredStrategy === "auto"
+            ? undefined
+            : options.uploadStrategy?.preferredStrategy,
+        preferredChunkSize: options.chunkSize,
+        parallelUploads: options.parallelUploads,
+    });
+    if (!validation.valid) {
+        errors.push(...validation.errors);
+    }
+    // Additional client-specific validations
+    if (options.parallelUploads && options.parallelUploads < 1) {
+        errors.push("parallelUploads must be at least 1");
+    }
+    if (options.chunkSize && options.chunkSize < 1024) {
+        warnings.push("Chunk size below 1KB may impact performance");
+    }
+    if (options.uploadStrategy?.preferredStrategy === "parallel" &&
+        !options.parallelUploads) {
+        warnings.push("Parallel strategy requested but parallelUploads not configured");
+    }
+    // Log validation results
+    if (errors.length > 0) {
+        logger.log("Configuration validation errors:");
+        for (const error of errors) {
+            logger.log(`  Error: ${error}`);
+        }
+    }
+    if (warnings.length > 0) {
+        logger.log("Configuration validation warnings:");
+        for (const warning of warnings) {
+            logger.log(`  Warning: ${warning}`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Async configuration validation with server capabilities
+ */
+export async function validateConfigurationAsync(options, httpClient, logger) {
+    const errors = [];
+    const warnings = [];
+    let capabilities;
+    try {
+        capabilities = await fetchServerCapabilities(options.baseUrl, options.uploadBasePath || "api/upload", options.storageId, httpClient);
+    }
+    catch (error) {
+        logger.log(`Failed to fetch server capabilities for validation: ${error}`);
+        capabilities = defaultClientCapabilities;
+        warnings.push("Using default capabilities for validation - server unavailable");
+    }
+    const validation = validateConfiguration(options, capabilities, logger);
+    errors.push(...validation.errors);
+    warnings.push(...validation.warnings);
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        capabilities,
+    };
+}
+/**
+ * Validate options and throw if invalid
+ */
+export function validateAndThrow(options, logger) {
+    const validationResult = validateConfiguration(options, defaultClientCapabilities, logger);
+    if (!validationResult.valid) {
+        const errorMessage = `Upload client configuration validation failed: ${validationResult.errors.join(", ")}`;
+        logger.log(errorMessage);
+        throw new UploadistaError({
+            name: "UPLOAD_SIZE_NOT_SPECIFIED", // Reusing existing error type
+            message: errorMessage,
+        });
+    }
+}

package/dist/upload/upload-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Encodes metadata for upload headers
+ */
+export declare function encodeMetadata(metadata: Record<string, string | null>): string;
+/**
+ * Checks whether a given status is in the range of the expected category.
+ * For example, only a status between 200 and 299 will satisfy the category 200.
+ */
+export declare function inStatusCategory(status: number, category: 100 | 200 | 300 | 400 | 500): boolean;
+export type CalculateFileSizeOptions = {
+    uploadLengthDeferred?: boolean;
+    uploadSize?: number;
+};
+/**
+ * Calculate the final file size for upload based on options
+ */
+export declare function calculateFileSize(originalSize: number | null, { uploadLengthDeferred, uploadSize }: CalculateFileSizeOptions): number | null;
+/**
+ * Calculate segments for parallel upload
+ */
+export declare function calculateSegments(fileSize: number, parallelUploads: number, parallelChunkSize?: number): {
+    startByte: number;
+    endByte: number;
+    segmentIndex: number;
+}[];
+//# sourceMappingURL=upload-utils.d.ts.map

package/dist/upload/upload-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-utils.d.ts","sourceRoot":"","sources":["../../src/upload/upload-utils.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GACtC,MAAM,CAIR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GACpC,OAAO,CAET;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,EAAE,oBAAoB,EAAE,UAAU,EAAE,EAAE,wBAAwB,GAC7D,MAAM,GAAG,IAAI,CAsBf;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,iBAAiB,CAAC,EAAE,MAAM,GACzB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAAE,CA8ChE"}

package/dist/upload/upload-utils.js

@@ -0,0 +1,80 @@
+import { Base64 } from "js-base64";
+import { UploadistaError } from "../error";
+/**
+ * Encodes metadata for upload headers
+ */
+export function encodeMetadata(metadata) {
+    return Object.entries(metadata)
+        .map(([key, value]) => `${key} ${Base64.encode(String(value))}`)
+        .join(",");
+}
+/**
+ * Checks whether a given status is in the range of the expected category.
+ * For example, only a status between 200 and 299 will satisfy the category 200.
+ */
+export function inStatusCategory(status, category) {
+    return status >= category && status < category + 100;
+}
+/**
+ * Calculate the final file size for upload based on options
+ */
+export function calculateFileSize(originalSize, { uploadLengthDeferred, uploadSize }) {
+    // First, we look at the uploadLengthDeferred option.
+    // Next, we check if the caller has supplied a manual upload size.
+    // Finally, we try to use the calculated size from the source object.
+    if (uploadLengthDeferred) {
+        return null;
+    }
+    if (uploadSize != null) {
+        return uploadSize;
+    }
+    const size = originalSize;
+    if (size == null) {
+        throw new UploadistaError({
+            name: "UPLOAD_SIZE_NOT_SPECIFIED",
+            message: "cannot automatically derive upload's size from input. Specify it manually using the `uploadSize` option or use the `uploadLengthDeferred` option",
+        });
+    }
+    return size;
+}
+/**
+ * Calculate segments for parallel upload
+ */
+export function calculateSegments(fileSize, parallelUploads, parallelChunkSize) {
+    if (parallelUploads <= 1) {
+        return [{ startByte: 0, endByte: fileSize, segmentIndex: 0 }];
+    }
+    // Use parallelChunkSize if provided, otherwise divide file equally
+    const segments = [];
+    if (parallelChunkSize) {
+        // Fixed segment size approach
+        let currentByte = 0;
+        let segmentIndex = 0;
+        while (currentByte < fileSize) {
+            const endByte = Math.min(currentByte + parallelChunkSize, fileSize);
+            segments.push({
+                startByte: currentByte,
+                endByte,
+                segmentIndex,
+            });
+            currentByte = endByte;
+            segmentIndex++;
+        }
+    }
+    else {
+        // Equal division approach
+        const segmentSize = Math.ceil(fileSize / parallelUploads);
+        for (let i = 0; i < parallelUploads; i++) {
+            const startByte = i * segmentSize;
+            const endByte = Math.min(startByte + segmentSize, fileSize);
+            if (startByte < fileSize) {
+                segments.push({
+                    startByte,
+                    endByte,
+                    segmentIndex: i,
+                });
+            }
+        }
+    }
+    return segments;
+}