@stacksjs/stx/dist/composables/use-storage.d.ts

A performant UI Framework. Powered by Bun.

/**
 * Create a reactive storage reference
 *
 * @example
 * ```ts
 * // Simple usage
 * const theme = useStorage('theme', 'light')
 * theme.value = 'dark' // Automatically persists
 *
 * // With options
 * const user = useStorage<User>('user', null, {
 *   storage: 'session',
 *   mergeDefaults: true
 * })
 *
 * // Subscribe to changes
 * theme.subscribe((newValue) => console.log('Theme changed:', newValue))
 * ```
 */
export declare function useStorage<T>(key: string, defaultValue: T, options?: UseStorageOptions<T>): StorageRef<T>;
/**
 * Shorthand for useStorage with localStorage
 */
export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): void;
/**
 * Shorthand for useStorage with sessionStorage
 */
export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): void;
/**
 * Clear all items from storage
 */
export declare function clearStorage(type?: StorageType): void;
/**
 * Get all keys from storage
 */
export declare function getStorageKeys(type?: StorageType): string[];
/**
 * Get storage size in bytes (approximate)
 */
export declare function getStorageSize(type?: StorageType): number;
export declare interface UseStorageOptions<T> {
  storage?: StorageType
  default?: T
  serializer?: {
    read: (value: string) => T
    write: (value: T) => string
  }
  mergeDefaults?: boolean
  listenToStorageChanges?: boolean
}
export declare interface StorageRef<T> {
  value: T
  get: () => T
  set: (value: T) => void
  remove: () => void
  subscribe: (callback: (value: T, prev: T | undefined) => void) => () => void
}
/**
 * useStorage - Reactive localStorage/sessionStorage composable
 *
 * Similar to Nuxt's useStorage but for STX applications.
 * Provides a reactive, type-safe wrapper around Web Storage APIs.
 */
export type StorageType = 'local' | 'session'