@uploadista/client-browser 0.0.3

package/src/services/platform-service.ts

@@ -0,0 +1,231 @@
+import type { PlatformService, Timeout } 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 function createBrowserPlatformService(): PlatformService {
+  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: () => void, ms: number | undefined) => {
+      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: Timeout) => {
+      globalThis.clearTimeout(id as number);
+    },
+
+    /**
+     * 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: unknown) => {
+      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: unknown) => {
+      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: unknown) => {
+      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: unknown) => {
+      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: unknown) => {
+      if (file instanceof File) {
+        return file.lastModified;
+      }
+      return undefined;
+    },
+  };
+}

package/src/services/storage/local-storage-service.ts

@@ -0,0 +1,187 @@
+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 function createLocalStorageService(): StorageService {
+  /**
+   * 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: string): Record<string, string> => {
+    const results: Record<string, string> = {};
+
+    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: string): Promise<string | null> {
+      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: string, value: string): Promise<void> {
+      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: string): Promise<void> {
+      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(): Promise<Record<string, string>> {
+      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: string): Promise<Record<string, string>> {
+      return findEntries(prefix);
+    },
+  };
+}

package/src/services/storage/session-storage-service.ts

@@ -0,0 +1,188 @@
+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 function createSessionStorageService(): StorageService {
+  /**
+   * Internal helper to find entries matching a prefix.
+   *
+   * Iterates through all sessionStorage 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: string): Record<string, string> => {
+    const results: Record<string, string> = {};
+
+    for (const key in sessionStorage) {
+      if (key.startsWith(prefix)) {
+        const item = sessionStorage.getItem(key);
+        if (item) {
+          results[key] = item;
+        }
+      }
+    }
+
+    return results;
+  };
+
+  return {
+    /**
+     * Retrieves a value from sessionStorage 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 token = await storage.getItem('session:auth-token');
+     * if (token) {
+     *   // Use token for requests
+     * }
+     * ```
+     */
+    async getItem(key: string): Promise<string | null> {
+      return sessionStorage.getItem(key);
+    },
+
+    /**
+     * Stores a value in sessionStorage.
+     *
+     * If the key already exists, its value will be overwritten.
+     * Values must be strings; use JSON.stringify() for objects.
+     * Data will be cleared when the browser tab/window is closed.
+     *
+     * @param key - The key to store under
+     * @param value - The string value to store
+     *
+     * @throws {QuotaExceededError} If sessionStorage quota is exceeded
+     *
+     * @example
+     * ```typescript
+     * // Store temporary state
+     * await storage.setItem('wizard:step', '2');
+     *
+     * // Store temporary object
+     * await storage.setItem('temp:upload', JSON.stringify({
+     *   progress: 50,
+     *   paused: false
+     * }));
+     * ```
+     */
+    async setItem(key: string, value: string): Promise<void> {
+      sessionStorage.setItem(key, value);
+    },
+
+    /**
+     * Removes a value from sessionStorage 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 temporary data
+     * await storage.removeItem('temp:upload:123');
+     * ```
+     */
+    async removeItem(key: string): Promise<void> {
+      sessionStorage.removeItem(key);
+    },
+
+    /**
+     * Retrieves all entries from sessionStorage.
+     *
+     * Returns an object mapping every key in sessionStorage to its value.
+     * This only includes data for the current tab/window.
+     *
+     * @returns Promise resolving to object with all key-value pairs
+     *
+     * @example
+     * ```typescript
+     * const all = await storage.findAll();
+     * console.log('Session items:', Object.keys(all).length);
+     * ```
+     */
+    async findAll(): Promise<Record<string, string>> {
+      return findEntries("");
+    },
+
+    /**
+     * Finds all entries with keys starting with a given prefix.
+     *
+     * Useful for querying related session data. For example, use "temp:"
+     * prefix to find all temporary entries.
+     *
+     * @param prefix - The key prefix to search for
+     * @returns Promise resolving to object with matching key-value pairs
+     *
+     * @example
+     * ```typescript
+     * // Find all temporary uploads in this session
+     * const tempUploads = await storage.find('temp-upload:');
+     * for (const [key, value] of Object.entries(tempUploads)) {
+     *   console.log('Temp upload:', key, JSON.parse(value));
+     * }
+     *
+     * // Find wizard state
+     * const wizardState = await storage.find('wizard:');
+     * ```
+     */
+    async find(prefix: string): Promise<Record<string, string>> {
+      return findEntries(prefix);
+    },
+  };
+}