@uploadista/client-browser 0.0.3

package/dist/services/id-generation/id-generation.js

@@ -0,0 +1,58 @@
+/**
+ * Creates a browser-specific ID generation service using the Web Crypto API.
+ *
+ * This service generates cryptographically secure random UUIDs (v4) using the
+ * browser's native `crypto.randomUUID()` method. These UUIDs are used throughout
+ * the Uploadista client for:
+ * - Upload session identifiers
+ * - Chunk identifiers
+ * - Request correlation IDs
+ * - Internal tracking
+ *
+ * The generated UUIDs conform to RFC 4122 version 4 (random) and provide
+ * strong uniqueness guarantees suitable for distributed systems.
+ *
+ * Browser compatibility: Requires support for `crypto.randomUUID()` (available
+ * in modern browsers). If you need to support older browsers, consider using a
+ * polyfill.
+ *
+ * @returns An IdGenerationService that generates cryptographically secure UUIDs
+ *
+ * @example
+ * ```typescript
+ * import { createBrowserIdGenerationService } from '@uploadista/client-browser';
+ *
+ * const idService = createBrowserIdGenerationService();
+ *
+ * // Generate a unique ID
+ * const id = idService.generate();
+ * console.log('Generated ID:', id);
+ * // Output: "550e8400-e29b-41d4-a716-446655440000" (example UUID v4)
+ *
+ * // Each call generates a new unique ID
+ * const id2 = idService.generate();
+ * console.log('Another ID:', id2);
+ * // Output: "7c9e6679-7425-40de-944b-e07fc1f90ae7" (different UUID)
+ * ```
+ */
+export function createBrowserIdGenerationService() {
+    return {
+        /**
+         * Generates a cryptographically secure random UUID (v4).
+         *
+         * Uses the Web Crypto API's `crypto.randomUUID()` method to generate
+         * a UUID conforming to RFC 4122 version 4. Each UUID is statistically
+         * unique and suitable for use as an identifier in distributed systems.
+         *
+         * @returns A UUID v4 string in the format "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
+         *
+         * @example
+         * ```typescript
+         * const service = createBrowserIdGenerationService();
+         * const uploadId = service.generate();
+         * console.log(uploadId); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+         * ```
+         */
+        generate: () => crypto.randomUUID(),
+    };
+}

package/dist/services/platform-service.d.ts

@@ -0,0 +1,38 @@
+import type { PlatformService } from "@uploadista/client-core";
+/**
+ * Creates a browser-specific platform service that provides environment capabilities.
+ *
+ * This service abstracts platform-specific functionality and provides a consistent
+ * interface for the Uploadista client to interact with browser APIs. It handles:
+ * - Timer management (setTimeout/clearTimeout)
+ * - Environment detection (browser vs. Node.js)
+ * - Network connectivity status
+ * - File object detection and metadata extraction
+ *
+ * This abstraction allows the core upload logic to remain platform-agnostic while
+ * still accessing browser-specific features when needed.
+ *
+ * @returns A PlatformService configured for browser environments
+ *
+ * @example
+ * ```typescript
+ * import { createBrowserPlatformService } from '@uploadista/client-browser';
+ *
+ * const platform = createBrowserPlatformService();
+ *
+ * // Check if running in browser
+ * console.log('Is browser:', platform.isBrowser()); // true
+ *
+ * // Check network status
+ * console.log('Is online:', platform.isOnline()); // true or false
+ *
+ * // Extract file metadata
+ * const fileInput = document.querySelector('input[type="file"]');
+ * const file = fileInput.files[0];
+ * console.log('File name:', platform.getFileName(file));
+ * console.log('File type:', platform.getFileType(file));
+ * console.log('File size:', platform.getFileSize(file));
+ * ```
+ */
+export declare function createBrowserPlatformService(): PlatformService;
+//# sourceMappingURL=platform-service.d.ts.map

package/dist/services/platform-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-service.d.ts","sourceRoot":"","sources":["../../src/services/platform-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAW,MAAM,yBAAyB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,CAiM9D"}

package/dist/services/platform-service.js

@@ -0,0 +1,221 @@
+/**
+ * Creates a browser-specific platform service that provides environment capabilities.
+ *
+ * This service abstracts platform-specific functionality and provides a consistent
+ * interface for the Uploadista client to interact with browser APIs. It handles:
+ * - Timer management (setTimeout/clearTimeout)
+ * - Environment detection (browser vs. Node.js)
+ * - Network connectivity status
+ * - File object detection and metadata extraction
+ *
+ * This abstraction allows the core upload logic to remain platform-agnostic while
+ * still accessing browser-specific features when needed.
+ *
+ * @returns A PlatformService configured for browser environments
+ *
+ * @example
+ * ```typescript
+ * import { createBrowserPlatformService } from '@uploadista/client-browser';
+ *
+ * const platform = createBrowserPlatformService();
+ *
+ * // Check if running in browser
+ * console.log('Is browser:', platform.isBrowser()); // true
+ *
+ * // Check network status
+ * console.log('Is online:', platform.isOnline()); // true or false
+ *
+ * // Extract file metadata
+ * const fileInput = document.querySelector('input[type="file"]');
+ * const file = fileInput.files[0];
+ * console.log('File name:', platform.getFileName(file));
+ * console.log('File type:', platform.getFileType(file));
+ * console.log('File size:', platform.getFileSize(file));
+ * ```
+ */
+export function createBrowserPlatformService() {
+    return {
+        /**
+         * Schedules a function to be executed after a specified delay.
+         *
+         * Wraps the browser's native `setTimeout` function.
+         *
+         * @param callback - Function to execute after the delay
+         * @param ms - Delay in milliseconds before executing the callback
+         * @returns A timeout ID that can be passed to clearTimeout
+         *
+         * @example
+         * ```typescript
+         * const timeoutId = platform.setTimeout(() => {
+         *   console.log('Executed after 1 second');
+         * }, 1000);
+         * ```
+         */
+        setTimeout: (callback, ms) => {
+            return globalThis.setTimeout(callback, ms);
+        },
+        /**
+         * Cancels a timeout previously scheduled with setTimeout.
+         *
+         * Wraps the browser's native `clearTimeout` function.
+         *
+         * @param id - The timeout ID returned by setTimeout
+         *
+         * @example
+         * ```typescript
+         * const timeoutId = platform.setTimeout(() => { }, 1000);
+         * platform.clearTimeout(timeoutId); // Cancel the timeout
+         * ```
+         */
+        clearTimeout: (id) => {
+            globalThis.clearTimeout(id);
+        },
+        /**
+         * Checks if the code is running in a browser environment.
+         *
+         * Detects browser by checking for the existence of the `window` object.
+         * This is useful for conditional logic that should only run in browsers.
+         *
+         * @returns `true` if running in a browser, `false` otherwise
+         *
+         * @example
+         * ```typescript
+         * if (platform.isBrowser()) {
+         *   // Browser-specific code
+         *   console.log('Running in browser');
+         * }
+         * ```
+         */
+        isBrowser: () => {
+            return typeof window !== "undefined";
+        },
+        /**
+         * Checks if the browser is currently online.
+         *
+         * Uses the Navigator Online Status API (`navigator.onLine`) to determine
+         * network connectivity. Note that this only indicates if the device has
+         * a network connection, not if it can reach the internet.
+         *
+         * @returns `true` if online, `false` if offline, defaults to `true` if not in browser
+         *
+         * @example
+         * ```typescript
+         * if (platform.isOnline()) {
+         *   // Proceed with upload
+         *   await client.upload(file);
+         * } else {
+         *   console.log('Waiting for network connection...');
+         * }
+         *
+         * // Listen for online/offline events
+         * window.addEventListener('online', () => {
+         *   console.log('Back online, resuming upload');
+         * });
+         * ```
+         */
+        isOnline: () => {
+            if (typeof navigator !== "undefined") {
+                return navigator.onLine;
+            }
+            return true;
+        },
+        /**
+         * Checks if a value is a File object.
+         *
+         * Type guard to determine if an unknown value is a browser File object.
+         * Useful for validating upload inputs and conditional file handling.
+         *
+         * @param value - The value to check
+         * @returns `true` if the value is a File instance, `false` otherwise
+         *
+         * @example
+         * ```typescript
+         * const input = getUploadInput(); // unknown type
+         *
+         * if (platform.isFileLike(input)) {
+         *   // TypeScript knows input is a File here
+         *   console.log('Uploading file:', input.name);
+         * }
+         * ```
+         */
+        isFileLike: (value) => {
+            return value instanceof File;
+        },
+        /**
+         * Extracts the file name from a File object.
+         *
+         * @param file - The file to extract the name from
+         * @returns The file name string, or `undefined` if not a File
+         *
+         * @example
+         * ```typescript
+         * const file = new File(['content'], 'document.pdf');
+         * const name = platform.getFileName(file);
+         * console.log(name); // "document.pdf"
+         * ```
+         */
+        getFileName: (file) => {
+            if (file instanceof File) {
+                return file.name;
+            }
+            return undefined;
+        },
+        /**
+         * Extracts the MIME type from a File object.
+         *
+         * @param file - The file to extract the type from
+         * @returns The MIME type string, or `undefined` if not a File
+         *
+         * @example
+         * ```typescript
+         * const file = new File(['content'], 'image.png', { type: 'image/png' });
+         * const type = platform.getFileType(file);
+         * console.log(type); // "image/png"
+         * ```
+         */
+        getFileType: (file) => {
+            if (file instanceof File) {
+                return file.type;
+            }
+            return undefined;
+        },
+        /**
+         * Extracts the file size in bytes from a File object.
+         *
+         * @param file - The file to extract the size from
+         * @returns The file size in bytes, or `undefined` if not a File
+         *
+         * @example
+         * ```typescript
+         * const file = new File(['Hello'], 'greeting.txt');
+         * const size = platform.getFileSize(file);
+         * console.log(size); // 5 (bytes)
+         * ```
+         */
+        getFileSize: (file) => {
+            if (file instanceof File) {
+                return file.size;
+            }
+            return undefined;
+        },
+        /**
+         * Extracts the last modified timestamp from a File object.
+         *
+         * @param file - The file to extract the timestamp from
+         * @returns The last modified timestamp in milliseconds since epoch, or `undefined` if not a File
+         *
+         * @example
+         * ```typescript
+         * const file = new File(['content'], 'data.txt');
+         * const lastModified = platform.getFileLastModified(file);
+         * console.log(new Date(lastModified)); // Date object of when file was last modified
+         * ```
+         */
+        getFileLastModified: (file) => {
+            if (file instanceof File) {
+                return file.lastModified;
+            }
+            return undefined;
+        },
+    };
+}

package/dist/services/storage/local-storage-service.d.ts

@@ -0,0 +1,55 @@
+import type { StorageService } from "@uploadista/client-core";
+/**
+ * Creates a browser storage service using localStorage for persistent data storage.
+ *
+ * This service provides a key-value storage interface backed by the browser's
+ * localStorage API. Data stored with this service persists across browser sessions
+ * and page reloads until explicitly deleted or cleared by the user.
+ *
+ * Use cases include:
+ * - Persisting upload state for resumable uploads
+ * - Caching file metadata and fingerprints
+ * - Storing user preferences and settings
+ * - Maintaining upload history
+ *
+ * **Important notes:**
+ * - localStorage has a typical limit of 5-10MB per origin
+ * - Data is stored as strings (objects are JSON-serialized)
+ * - localStorage is synchronous but this service wraps it in Promises for consistency
+ * - Data is scoped to the origin (protocol + domain + port)
+ * - Users can clear localStorage through browser settings
+ *
+ * @returns A StorageService backed by browser localStorage
+ *
+ * @example
+ * ```typescript
+ * import { createLocalStorageService } from '@uploadista/client-browser';
+ *
+ * const storage = createLocalStorageService();
+ *
+ * // Store upload state
+ * await storage.setItem('upload:123', JSON.stringify({
+ *   fileId: '123',
+ *   progress: 75,
+ *   uploadedChunks: [0, 1, 2]
+ * }));
+ *
+ * // Retrieve upload state
+ * const data = await storage.getItem('upload:123');
+ * if (data) {
+ *   const state = JSON.parse(data);
+ *   console.log('Resuming upload at', state.progress, '%');
+ * }
+ *
+ * // Find all uploads
+ * const uploads = await storage.find('upload:');
+ * console.log('Found', Object.keys(uploads).length, 'uploads');
+ *
+ * // Clean up completed upload
+ * await storage.removeItem('upload:123');
+ * ```
+ *
+ * @see {@link createSessionStorageService} for session-only storage
+ */
+export declare function createLocalStorageService(): StorageService;
+//# sourceMappingURL=local-storage-service.d.ts.map

package/dist/services/storage/local-storage-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-storage-service.d.ts","sourceRoot":"","sources":["../../../src/services/storage/local-storage-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,yBAAyB,IAAI,cAAc,CAoI1D"}

package/dist/services/storage/local-storage-service.js

@@ -0,0 +1,178 @@
+/**
+ * Creates a browser storage service using localStorage for persistent data storage.
+ *
+ * This service provides a key-value storage interface backed by the browser's
+ * localStorage API. Data stored with this service persists across browser sessions
+ * and page reloads until explicitly deleted or cleared by the user.
+ *
+ * Use cases include:
+ * - Persisting upload state for resumable uploads
+ * - Caching file metadata and fingerprints
+ * - Storing user preferences and settings
+ * - Maintaining upload history
+ *
+ * **Important notes:**
+ * - localStorage has a typical limit of 5-10MB per origin
+ * - Data is stored as strings (objects are JSON-serialized)
+ * - localStorage is synchronous but this service wraps it in Promises for consistency
+ * - Data is scoped to the origin (protocol + domain + port)
+ * - Users can clear localStorage through browser settings
+ *
+ * @returns A StorageService backed by browser localStorage
+ *
+ * @example
+ * ```typescript
+ * import { createLocalStorageService } from '@uploadista/client-browser';
+ *
+ * const storage = createLocalStorageService();
+ *
+ * // Store upload state
+ * await storage.setItem('upload:123', JSON.stringify({
+ *   fileId: '123',
+ *   progress: 75,
+ *   uploadedChunks: [0, 1, 2]
+ * }));
+ *
+ * // Retrieve upload state
+ * const data = await storage.getItem('upload:123');
+ * if (data) {
+ *   const state = JSON.parse(data);
+ *   console.log('Resuming upload at', state.progress, '%');
+ * }
+ *
+ * // Find all uploads
+ * const uploads = await storage.find('upload:');
+ * console.log('Found', Object.keys(uploads).length, 'uploads');
+ *
+ * // Clean up completed upload
+ * await storage.removeItem('upload:123');
+ * ```
+ *
+ * @see {@link createSessionStorageService} for session-only storage
+ */
+export function createLocalStorageService() {
+    /**
+     * Internal helper to find entries matching a prefix.
+     *
+     * Iterates through all localStorage keys and returns those that start
+     * with the specified prefix along with their values.
+     *
+     * @param prefix - Key prefix to filter by
+     * @returns Object mapping matching keys to their values
+     * @private
+     */
+    const findEntries = (prefix) => {
+        const results = {};
+        for (const key in localStorage) {
+            if (key.startsWith(prefix)) {
+                const item = localStorage.getItem(key);
+                if (item) {
+                    results[key] = item;
+                }
+            }
+        }
+        return results;
+    };
+    return {
+        /**
+         * Retrieves a value from localStorage by key.
+         *
+         * @param key - The key to retrieve
+         * @returns Promise resolving to the value, or null if the key doesn't exist
+         *
+         * @example
+         * ```typescript
+         * const value = await storage.getItem('user:preferences');
+         * if (value) {
+         *   const prefs = JSON.parse(value);
+         * }
+         * ```
+         */
+        async getItem(key) {
+            return localStorage.getItem(key);
+        },
+        /**
+         * Stores a value in localStorage.
+         *
+         * If the key already exists, its value will be overwritten.
+         * Values must be strings; use JSON.stringify() for objects.
+         *
+         * @param key - The key to store under
+         * @param value - The string value to store
+         *
+         * @throws {QuotaExceededError} If localStorage quota is exceeded
+         *
+         * @example
+         * ```typescript
+         * // Store string
+         * await storage.setItem('upload:status', 'completed');
+         *
+         * // Store object
+         * await storage.setItem('upload:metadata', JSON.stringify({
+         *   name: 'file.txt',
+         *   size: 1024
+         * }));
+         * ```
+         */
+        async setItem(key, value) {
+            localStorage.setItem(key, value);
+        },
+        /**
+         * Removes a value from localStorage by key.
+         *
+         * If the key doesn't exist, this is a no-op (no error is thrown).
+         *
+         * @param key - The key to remove
+         *
+         * @example
+         * ```typescript
+         * // Clean up completed upload
+         * await storage.removeItem('upload:123');
+         * ```
+         */
+        async removeItem(key) {
+            localStorage.removeItem(key);
+        },
+        /**
+         * Retrieves all entries from localStorage.
+         *
+         * Returns an object mapping every key in localStorage to its value.
+         * Use with caution as this can return a large amount of data.
+         *
+         * @returns Promise resolving to object with all key-value pairs
+         *
+         * @example
+         * ```typescript
+         * const all = await storage.findAll();
+         * console.log('Total items in storage:', Object.keys(all).length);
+         * ```
+         */
+        async findAll() {
+            return findEntries("");
+        },
+        /**
+         * Finds all entries with keys starting with a given prefix.
+         *
+         * Useful for querying related data or implementing namespacing.
+         * For example, use "upload:" prefix to find all upload-related entries.
+         *
+         * @param prefix - The key prefix to search for
+         * @returns Promise resolving to object with matching key-value pairs
+         *
+         * @example
+         * ```typescript
+         * // Find all uploads
+         * const uploads = await storage.find('upload:');
+         * for (const [key, value] of Object.entries(uploads)) {
+         *   console.log('Upload:', key, JSON.parse(value));
+         * }
+         *
+         * // Find user preferences
+         * const prefs = await storage.find('pref:');
+         * ```
+         */
+        async find(prefix) {
+            return findEntries(prefix);
+        },
+    };
+}

package/dist/services/storage/session-storage-service.d.ts

@@ -0,0 +1,55 @@
+import type { StorageService } from "@uploadista/client-core";
+/**
+ * Creates a browser storage service using sessionStorage for temporary data storage.
+ *
+ * This service provides a key-value storage interface backed by the browser's
+ * sessionStorage API. Unlike localStorage, data stored with sessionStorage is
+ * only available for the duration of the page session and is cleared when the
+ * browser tab or window is closed.
+ *
+ * Use cases include:
+ * - Temporary upload state during a session
+ * - One-time authentication tokens
+ * - Transient UI state
+ * - Session-specific preferences
+ *
+ * **Key differences from localStorage:**
+ * - Data persists only for the current browser tab/window session
+ * - Each tab has its own isolated sessionStorage
+ * - Data is cleared when the tab/window is closed
+ * - Page reloads preserve sessionStorage (unlike in-memory storage)
+ * - Same storage quota limits as localStorage (5-10MB)
+ *
+ * @returns A StorageService backed by browser sessionStorage
+ *
+ * @example
+ * ```typescript
+ * import { createSessionStorageService } from '@uploadista/client-browser';
+ *
+ * const storage = createSessionStorageService();
+ *
+ * // Store temporary upload state
+ * await storage.setItem('temp-upload:abc', JSON.stringify({
+ *   fileId: 'abc',
+ *   started: Date.now()
+ * }));
+ *
+ * // Retrieve within same session
+ * const data = await storage.getItem('temp-upload:abc');
+ * if (data) {
+ *   const state = JSON.parse(data);
+ *   console.log('Upload started at', new Date(state.started));
+ * }
+ *
+ * // Find all temporary uploads
+ * const tempUploads = await storage.find('temp-upload:');
+ *
+ * // Clean up
+ * await storage.removeItem('temp-upload:abc');
+ * // OR: Close tab/window to clear all sessionStorage
+ * ```
+ *
+ * @see {@link createLocalStorageService} for persistent storage
+ */
+export declare function createSessionStorageService(): StorageService;
+//# sourceMappingURL=session-storage-service.d.ts.map

package/dist/services/storage/session-storage-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage-service.d.ts","sourceRoot":"","sources":["../../../src/services/storage/session-storage-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,2BAA2B,IAAI,cAAc,CAqI5D"}