houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
353 lines (352 loc) • 11.4 kB
TypeScript
/**
* @module StorageUtils
* @description Utility functions for managing browser storage (localStorage, sessionStorage, cookies) with support for encryption, expiration, and type-safe operations. Includes methods for getting, setting, and removing values, as well as managing storage quotas and handling storage availability.
* @example
* ```typescript
* import { StorageUtils } from 'houser-js-utils';
*
* // Set and get values from localStorage
* StorageUtils.setLocal('user', { id: 1, name: 'John' });
* const user = StorageUtils.getLocal<{ id: number; name: string }>('user');
*
* // Set and get values from sessionStorage with encryption
* StorageUtils.setSession('token', 'secret-token', { encrypt: true });
* const token = StorageUtils.getSession<string>('token', { decrypt: true });
*
* // Set and get cookies with options
* StorageUtils.setCookie('theme', 'dark', { expires: 86400000, secure: true });
* const theme = StorageUtils.getCookie('theme');
*
* // Check storage availability
* if (StorageUtils.isStorageAvailable('localStorage')) {
* // Use localStorage
* }
* ```
*/
export declare const StorageUtils: {
/**
* Clears all cookies.
* @param options - Clear options
* @param options.exclude - Cookie names to exclude from clearing
* @param options.path - Cookie path
* @param options.domain - Cookie domain
* @example
* ```typescript
* // Clear all cookies
* StorageUtils.clearCookies();
*
* // Clear cookies except 'session'
* StorageUtils.clearCookies({ exclude: ['session'] });
* ```
*/
clearCookies(options?: {
exclude?: string[];
path?: string;
domain?: string;
}): void;
/**
* Clears all values from localStorage.
* @param options - Clear options
* @param options.exclude - Keys to exclude from clearing
* @example
* ```typescript
* // Clear all localStorage
* StorageUtils.clearLocal();
*
* // Clear localStorage except 'settings'
* StorageUtils.clearLocal({ exclude: ['settings'] });
* ```
*/
clearLocal(options?: {
exclude?: string[];
}): void;
/**
* Clears all values from sessionStorage.
* @param options - Clear options
* @param options.exclude - Keys to exclude from clearing
* @example
* ```typescript
* // Clear all sessionStorage
* StorageUtils.clearSession();
*
* // Clear sessionStorage except 'temp'
* StorageUtils.clearSession({ exclude: ['temp'] });
* ```
*/
clearSession(options?: {
exclude?: string[];
}): void;
/**
* Decrypts an encrypted string value.
* @param value - Value to decrypt
* @param key - Optional encryption key (defaults to a secure key)
* @returns Promise resolving to decrypted value
* @throws Error if decryption fails
* @example
* ```typescript
* const decrypted = await StorageUtils.decrypt(encryptedValue);
* ```
*/
decrypt(value: string, key?: string): Promise<string>;
/**
* Encrypts a string value.
* @param value - Value to encrypt
* @param key - Optional encryption key (defaults to a secure key)
* @returns Promise resolving to encrypted value
* @throws Error if encryption fails
* @example
* ```typescript
* const encrypted = await StorageUtils.encrypt('sensitive-data');
* ```
*/
encrypt(value: string, key?: string): Promise<string>;
/**
* Gets all cookies.
* @param options - Cookie options
* @param options.decrypt - Whether to decrypt the values
* @returns Object containing all cookies
* @example
* ```typescript
* // Get all cookies
* const cookies = StorageUtils.getAllCookies();
*
* // Get all cookies with decryption
* const decryptedCookies = await StorageUtils.getAllCookies({ decrypt: true });
* ```
*/
getAllCookies(options?: {
decrypt?: boolean;
}): Promise<Record<string, string>>;
/**
* Gets a cookie value.
* @param name - Cookie name
* @param options - Cookie options
* @param options.decrypt - Whether to decrypt the value
* @returns Cookie value or null if not found
* @example
* ```typescript
* // Get a cookie
* const value = StorageUtils.getCookie('theme');
*
* // Get and decrypt a cookie
* const decryptedValue = await StorageUtils.getCookie('token', { decrypt: true });
* ```
*/
getCookie(name: string, options?: {
decrypt?: boolean;
}): Promise<string | null>;
/**
* Gets or generates a crypto key for encryption/decryption.
* @param key - Optional encryption key
* @returns Promise resolving to CryptoKey
* @private
*/
getCryptoKey(key?: string): Promise<CryptoKey>;
/**
* Gets a value from localStorage.
* @template T
* @param key - Storage key
* @param options - Storage options
* @param options.decrypt - Whether to decrypt the value
* @param options.defaultValue - Default value if not found/expired
* @returns Stored value or null if not found/expired
* @example
* ```typescript
* // Get a value
* const value = StorageUtils.getLocal<string>('name');
*
* // Get and decrypt a value with default
* const decryptedValue = await StorageUtils.getLocal<string>('token', {
* decrypt: true,
* defaultValue: 'default-token'
* });
* ```
*/
getLocal<T>(key: string, options?: {
decrypt?: boolean;
defaultValue?: T;
}): Promise<T | null>;
/**
* Gets a value from sessionStorage.
* @template T
* @param key - Storage key
* @param options - Storage options
* @param options.decrypt - Whether to decrypt the value
* @param options.defaultValue - Default value if not found/expired
* @returns Stored value or null if not found/expired
* @example
* ```typescript
* // Get a value
* const value = StorageUtils.getSession<string>('temp');
*
* // Get and decrypt a value with default
* const decryptedValue = await StorageUtils.getSession<string>('token', {
* decrypt: true,
* defaultValue: 'default-token'
* });
* ```
*/
getSession<T>(key: string, options?: {
decrypt?: boolean;
defaultValue?: T;
}): Promise<T | null>;
/**
* Gets the storage quota and usage.
* @returns Promise resolving to object containing quota and usage information
* @example
* ```typescript
* const quota = await StorageUtils.getStorageQuota();
* console.log(`Usage: ${quota?.usage} / ${quota?.quota}`);
* ```
*/
getStorageQuota(): Promise<{
quota: number;
usage: number;
remaining: number;
} | null>;
/**
* Gets the size of a stored value.
* @param value - Value to measure
* @returns Size in bytes
* @example
* ```typescript
* const size = StorageUtils.getStorageSize({ data: 'large' });
* console.log(`Size: ${size} bytes`);
* ```
*/
getStorageSize(value: unknown): number;
/**
* Gets the total size of all stored values.
* @param type - Storage type ('localStorage' or 'sessionStorage')
* @returns Total size in bytes
* @example
* ```typescript
* const totalSize = StorageUtils.getTotalStorageSize('localStorage');
* console.log(`Total size: ${totalSize} bytes`);
* ```
*/
getTotalStorageSize(type: "localStorage" | "sessionStorage"): number;
/**
* Checks if storage is available.
* @param type - Storage type ('localStorage', 'sessionStorage', or 'cookie')
* @returns True if storage is available
* @example
* ```typescript
* if (StorageUtils.isStorageAvailable('localStorage')) {
* // Use localStorage
* }
* ```
*/
isStorageAvailable(type: "localStorage" | "sessionStorage" | "cookie"): boolean;
/**
* Removes a cookie.
* @param name - Cookie name
* @param options - Cookie options
* @param options.path - Cookie path
* @param options.domain - Cookie domain
* @example
* ```typescript
* StorageUtils.removeCookie('session');
* ```
*/
removeCookie(name: string, options?: {
path?: string;
domain?: string;
}): void;
/**
* Removes a value from localStorage.
* @param key - Storage key
* @example
* ```typescript
* StorageUtils.removeLocal('user');
* ```
*/
removeLocal(key: string): void;
/**
* Removes a value from sessionStorage.
* @param key - Storage key
* @example
* ```typescript
* StorageUtils.removeSession('temp');
* ```
*/
removeSession(key: string): void;
/**
* Sets a cookie.
* @param name - Cookie name
* @param value - Cookie value
* @param options - Cookie options
* @param options.expires - Expiration time in milliseconds or Date
* @param options.path - Cookie path
* @param options.domain - Cookie domain
* @param options.secure - Whether the cookie requires HTTPS
* @param options.sameSite - SameSite attribute
* @param options.encrypt - Whether to encrypt the value
* @example
* ```typescript
* // Set a basic cookie
* StorageUtils.setCookie('theme', 'dark');
*
* // Set a secure cookie with expiration
* StorageUtils.setCookie('token', 'secret', {
* expires: 86400000,
* secure: true,
* sameSite: 'Strict'
* });
* ```
*/
setCookie(name: string, value: string, options?: {
expires?: number | Date;
path?: string;
domain?: string;
secure?: boolean;
sameSite?: "Strict" | "Lax" | "None";
encrypt?: boolean;
}): Promise<void>;
/**
* Sets a value in localStorage.
* @param key - Storage key
* @param value - Value to store
* @param options - Storage options
* @param options.expires - Expiration time in milliseconds
* @param options.encrypt - Whether to encrypt the value
* @example
* ```typescript
* // Set a basic value
* StorageUtils.setLocal('user', { id: 1, name: 'John' });
*
* // Set an encrypted value with expiration
* StorageUtils.setLocal('token', 'secret', {
* expires: 3600000,
* encrypt: true
* });
* ```
*/
setLocal(key: string, value: unknown, options?: {
expires?: number;
encrypt?: boolean;
}): Promise<void>;
/**
* Sets a value in sessionStorage.
* @param key - Storage key
* @param value - Value to store
* @param options - Storage options
* @param options.expires - Expiration time in milliseconds
* @param options.encrypt - Whether to encrypt the value
* @example
* ```typescript
* // Set a basic value
* StorageUtils.setSession('temp', { id: 1 });
*
* // Set an encrypted value with expiration
* StorageUtils.setSession('token', 'secret', {
* expires: 3600000,
* encrypt: true
* });
* ```
*/
setSession(key: string, value: unknown, options?: {
expires?: number;
encrypt?: boolean;
}): Promise<void>;
};