@arex95/vue-core 1.1.43 → 3.0.0

package/dist/utils/files.d.ts

@@ -1,46 +1,54 @@
 /**
- * Converts a FormData object to a plain JavaScript object.
- * @param {FormData} formData The FormData object to convert.
- * @returns {Record<string, any>} The plain JavaScript object.
+ * Converts a `FormData` object into a regular JavaScript object. It correctly handles
+ * multiple values for the same key by creating an array for that key.
+ *
+ * @param {FormData} formData - The `FormData` object to convert.
+ * @returns {Record<string, any>} A plain JavaScript object representation of the FormData.
  */
 export declare function formDataToObject(formData: FormData): Record<string, any>;
 /**
- * Reads a file as text.
- * @param {File} file The file to read.
- * @returns {Promise<string>} A promise that resolves with the file content.
+ * Asynchronously reads the content of a `File` object as a text string.
+ *
+ * @param {File} file - The `File` object to read.
+ * @returns {Promise<string>} A promise that resolves with the text content of the file.
  */
 export declare function readFileAsText(file: File): Promise<string>;
 /**
- * Reads a file as a Data URL.
- * @param {File} file The file to read.
- * @returns {Promise<string>} A promise that resolves with the Data URL.
+ * Asynchronously reads the content of a `File` object as a Base64-encoded Data URL.
+ *
+ * @param {File} file - The `File` object to read.
+ * @returns {Promise<string>} A promise that resolves with the Data URL representing the file's content.
  */
 export declare function readFileAsDataURL(file: File): Promise<string>;
 /**
- * Creates a Blob from a string.
- * @param {string} content The string content for the Blob.
- * @param {string} [type='text/plain'] The MIME type of the Blob.
- * @returns {Blob} The Blob object.
+ * Creates a `Blob` object from a string.
+ *
+ * @param {string} content - The string content to be put into the Blob.
+ * @param {string} [type='text/plain'] - The MIME type of the Blob.
+ * @returns {Blob} A new `Blob` object.
  */
 export declare function stringToBlob(content: string, type?: string): Blob;
 /**
- * Creates a Blob from an ArrayBuffer.
- * @param {ArrayBuffer} buffer The ArrayBuffer to convert.
- * @param {string} [type='application/octet-stream'] The MIME type of the Blob.
- * @returns {Blob} The Blob object.
+ * Creates a `Blob` object from an `ArrayBuffer`.
+ *
+ * @param {ArrayBuffer} buffer - The `ArrayBuffer` to be put into the Blob.
+ * @param {string} [type='application/octet-stream'] - The MIME type of the Blob.
+ * @returns {Blob} A new `Blob` object.
  */
 export declare function bufferToBlob(buffer: ArrayBuffer, type?: string): Blob;
 /**
- * Creates and downloads a file from Blob data.
- * @param {Blob} blob The Blob containing the file data.
- * @param {string} fileName The name of the file to create.
+ * Triggers a browser download for a file created from a `Blob` object.
+ *
+ * @param {Blob} blob - The `Blob` containing the file data.
+ * @param {string} fileName - The desired name for the downloaded file.
  */
 export declare function downloadBlob(blob: Blob, fileName: string): void;
 /**
- * Creates a FormData object containing a Blob.
- * @param {Blob} blob The Blob to include in the FormData.
- * @param {string} name The name of the form field.
- * @param {string} [fileName='file'] The file name for the Blob.
- * @returns {FormData} The FormData object.
+ * Appends a `Blob` to a new `FormData` object.
+ *
+ * @param {Blob} blob - The `Blob` to append.
+ * @param {string} name - The name of the field to append the blob as.
+ * @param {string} [fileName='file'] - The filename to associate with the blob in the `FormData`.
+ * @returns {FormData} A new `FormData` object containing the blob.
  */
 export declare function blobToFormData(blob: Blob, name: string, fileName?: string): FormData;

package/dist/utils/index.d.ts

@@ -11,3 +11,6 @@ export * from '../services/credentials';
 export * from './storage';
 export * from './encryption';
 export * from './errors';
+export * from './retry';
+export * from './ssr';
+export type { CookieOptions } from './ssr';

package/dist/utils/io.d.ts

@@ -1,42 +1,46 @@
 /**
- * Disables the right-click context menu on the window.
+ * Disables the default right-click context menu on the entire window.
  */
 export declare function disableRightClick(): void;
 export declare namespace disableRightClick {
     var handler: any;
 }
 /**
- * Enables the right-click context menu on the window.
+ * Re-enables the right-click context menu if it was previously disabled by `disableRightClick`.
  */
 export declare function enableRightClick(): void;
 /**
- * Disables specific mouse buttons.
- * @param {Array<number>} buttons Array of mouse button codes to disable (0 for left, 1 for middle, 2 for right).
+ * Prevents the default action for specific mouse buttons on the `mousedown` event.
+ *
+ * @param {number[]} buttons - An array of mouse button codes to disable (0 for left, 1 for middle, 2 for right).
  */
 export declare function disableMouseButtons(buttons: number[]): void;
 export declare namespace disableMouseButtons {
     var handlers: ((event: MouseEvent) => void)[];
 }
 /**
- * Enables all previously disabled mouse buttons.
+ * Re-enables all mouse buttons that were previously disabled by `disableMouseButtons`.
  */
 export declare function enableMouseButtons(): void;
 /**
- * Adds a double-click event listener to a specific element.
- * @param {HTMLElement} element The target element.
- * @param {(event: MouseEvent) => void} callback The callback function to execute on double click.
+ * Attaches a `dblclick` event listener to a specified HTML element.
+ *
+ * @param {HTMLElement} element - The DOM element to attach the listener to.
+ * @param {(event: MouseEvent) => void} callback - The function to execute when the element is double-clicked.
  */
 export declare function addDoubleClickListener(element: HTMLElement, callback: (event: MouseEvent) => void): void;
 /**
- * Removes a double-click event listener from a specific element.
- * @param {HTMLElement} element The target element.
- * @param {(event: MouseEvent) => void} callback The callback function to remove.
+ * Removes a `dblclick` event listener from a specified HTML element.
+ *
+ * @param {HTMLElement} element - The DOM element to remove the listener from.
+ * @param {(event: MouseEvent) => void} callback - The callback function that was originally added.
  */
 export declare function removeDoubleClickListener(element: HTMLElement, callback: (event: MouseEvent) => void): void;
 /**
- * Detects a click outside a specific element and triggers a callback.
- * @param {HTMLElement} element The element to detect clicks outside of.
- * @param {() => void} callback The callback function to execute when a click outside is detected.
+ * Sets up a global click listener to detect when a user clicks outside of a specified element.
+ *
+ * @param {HTMLElement} element - The element to monitor for outside clicks.
+ * @param {() => void} callback - The function to execute when a click outside the element is detected.
  */
 export declare function clickOutside(element: HTMLElement, callback: () => void): void;
 export declare namespace clickOutside {
@@ -46,53 +50,60 @@ export declare namespace clickOutside {
     }[];
 }
 /**
- * Removes the click outside listener for a specific element.
- * @param {HTMLElement} element The element to stop detecting clicks outside of.
+ * Removes the "click outside" event listener for a specific element that was added by `clickOutside`.
+ *
+ * @param {HTMLElement} element - The element for which to remove the listener.
  */
 export declare function removeClickOutside(element: HTMLElement): void;
 /**
- * Disables the F12 key and certain key combinations for developer tools.
+ * Disables the F12 key and common developer tool shortcuts (Ctrl+Shift+I, Ctrl+Shift+J)
+ * to prevent users from easily opening the browser's developer console.
  */
 export declare function disableF12Key(): void;
 /**
- * Enables or disables the tab navigation (Tab key) on the page.
- * @param {boolean} enable Whether to enable or disable tab navigation.
+ * Enables or disables the ability to navigate through focusable elements using the Tab key.
+ *
+ * @param {boolean} enable - If `true`, tab navigation is enabled; if `false`, it is disabled.
  */
 export declare function toggleTabNavigation(enable: boolean): void;
 /**
- * Disables the copy (Ctrl + C) functionality on the page.
+ * Prevents users from copying content from the page by intercepting the `copy` event.
  */
 export declare function disableCopy(): void;
 /**
- * Adds a custom keyboard shortcut to execute a given callback function.
- * @param {string} key The key to trigger the callback.
- * @param {Function} callback The function to execute on the key press.
- * @param {boolean} [ctrlKey=false] Whether Ctrl key should be pressed.
- * @param {boolean} [shiftKey=false] Whether Shift key should be pressed.
+ * Registers a global keyboard shortcut that triggers a callback when a specific key combination is pressed.
+ *
+ * @param {string} key - The main key for the shortcut (e.g., 'S', 'F1').
+ * @param {() => void} callback - The function to execute when the shortcut is pressed.
+ * @param {boolean} [ctrlKey=false] - If `true`, the Ctrl key must be pressed.
+ * @param {boolean} [shiftKey=false] - If `true`, the Shift key must be pressed.
  */
 export declare function addCustomKeyboardShortcut(key: string, callback: () => void, ctrlKey?: boolean, shiftKey?: boolean): void;
 /**
- * Removes a custom keyboard shortcut by key and modifiers.
- * @param {string} key The key to trigger the callback.
- * @param {boolean} [ctrlKey=false] Whether Ctrl key should be pressed.
- * @param {boolean} [shiftKey=false] Whether Shift key should be pressed.
+ * Removes a global keyboard shortcut that was previously added.
+ *
+ * @param {string} key - The main key of the shortcut to remove.
+ * @param {boolean} [ctrlKey=false] - The Ctrl key modifier of the shortcut.
+ * @param {boolean} [shiftKey=false] - The Shift key modifier of the shortcut.
  */
 export declare function removeCustomKeyboardShortcut(key: string, ctrlKey?: boolean, shiftKey?: boolean): void;
 /**
- * Disables specific keys or key combinations.
- * @param {Array<string>} keys Array of key names to disable (e.g., ['F1', 'F5', 'Control+S']).
+ * Disables a list of specified keys or key combinations.
+ *
+ * @param {string[]} keys - An array of key names or combinations (e.g., 'F1', 'Control+S') to disable.
  */
 export declare function disableSpecificKeys(keys: string[]): void;
 export declare namespace disableSpecificKeys {
     var handlers: ((event: KeyboardEvent) => void)[];
 }
 /**
- * Enables keys that were previously disabled using disableSpecificKeys.
+ * Re-enables all keys that were previously disabled by `disableSpecificKeys`.
  */
 export declare function enableSpecificKeys(): void;
 /**
- * Registers multiple keyboard shortcuts with their respective callback functions.
- * @param {Array<{ key: string, ctrlKey?: boolean, shiftKey?: boolean, altKey?: boolean, callback: Function }>} shortcuts Array of shortcut objects.
+ * Registers multiple keyboard shortcuts from an array of shortcut configurations.
+ *
+ * @param {Array<{ key: string; ctrlKey?: boolean; shiftKey?: boolean; altKey?: boolean; callback: () => void }>} shortcuts - An array of shortcut objects.
  */
 export declare function registerKeyboardShortcuts(shortcuts: {
     key: string;
@@ -105,47 +116,51 @@ export declare namespace registerKeyboardShortcuts {
     var handlers: ((event: KeyboardEvent) => void)[];
 }
 /**
- * Unregisters all keyboard shortcuts that were registered with registerKeyboardShortcuts.
+ * Removes all keyboard shortcuts that were registered using `registerKeyboardShortcuts`.
  */
 export declare function unregisterKeyboardShortcuts(): void;
 /**
- * Adds a listener for a specific key to trigger a custom event.
- * @param {string} key The key to listen for (e.g., 'Enter', 'Escape').
- * @param {Function} callback The function to execute when the key is pressed.
+ * Adds a global `keydown` listener for a specific key.
+ *
+ * @param {string} key - The key to listen for (e.g., 'Enter', 'Escape').
+ * @param {() => void} callback - The function to execute when the key is pressed.
  */
 export declare function addKeyListener(key: string, callback: () => void): void;
 export declare namespace addKeyListener {
     var handlers: ((event: KeyboardEvent) => void)[];
 }
 /**
- * Removes all custom key listeners added by addKeyListener.
+ * Removes all key listeners that were added using `addKeyListener`.
  */
 export declare function removeKeyListeners(): void;
 /**
- * Detects if a specific key is held down.
- * @param {string} key The key to detect (e.g., 'Shift', 'Control', 'Alt', 'a').
- * @param {Function} onHold Callback function to execute while the key is held down.
+ * Executes a callback function repeatedly while a specific key is held down.
+ *
+ * @param {string} key - The key to monitor.
+ * @param {() => void} onHold - The callback function to execute on each `keydown` event for the specified key.
  */
 export declare function detectKeyHold(key: string, onHold: () => void): void;
 export declare namespace detectKeyHold {
     var handlers: ((event: KeyboardEvent) => void)[];
 }
 /**
- * Stops detecting if a specific key is held down.
+ * Removes all key hold listeners that were added by `detectKeyHold`.
  */
 export declare function stopDetectingKeyHold(): void;
 /**
- * Tracks currently pressed keys and provides a map of active keys.
- * @returns {Set<string>} A set of currently pressed keys.
+ * Creates and maintains a `Set` of currently pressed keys.
+ *
+ * @returns {Set<string>} A `Set` that dynamically updates with the keys being pressed.
  */
 export declare function createKeyMap(): Set<string>;
 export declare namespace createKeyMap {
     var clearListeners: () => void;
 }
 /**
- * Sets up custom keyboard shortcuts with flexible order.
- * @param {Array<string>} keys The combination of keys for the shortcut.
- * @param {Function} callback The callback function to execute when the combination is detected.
+ * Sets up a keyboard shortcut that triggers a callback when a specific combination of keys is held down, regardless of order.
+ *
+ * @param {string[]} keys - An array of keys that constitute the shortcut.
+ * @param {() => void} callback - The function to execute when the key combination is active.
  */
 export declare function customShortcut(keys: string[], callback: () => void): void;
 export declare namespace customShortcut {
@@ -155,14 +170,15 @@ export declare namespace customShortcut {
     }[];
 }
 /**
- * Removes all custom keyboard shortcuts added by customShortcut.
+ * Removes all keyboard shortcut listeners that were added by `customShortcut`.
  */
 export declare function removeCustomShortcuts(): void;
 /**
- * Simulates a key press event.
- * @param {string} key The key to simulate (e.g., 'Enter', 'a').
- * @param {boolean} ctrlKey If true, include Ctrl key in the event.
- * @param {boolean} shiftKey If true, include Shift key in the event.
- * @param {boolean} altKey If true, include Alt key in the event.
+ * Programmatically dispatches a `keydown` event to simulate a key press.
+ *
+ * @param {string} key - The key to simulate (e.g., 'Enter', 'a').
+ * @param {boolean} [ctrlKey=false] - Whether to simulate the Ctrl key being pressed.
+ * @param {boolean} [shiftKey=false] - Whether to simulate the Shift key being pressed.
+ * @param {boolean} [altKey=false] - Whether to simulate the Alt key being pressed.
  */
 export declare function simulateKeyPress(key: string, ctrlKey?: boolean, shiftKey?: boolean, altKey?: boolean): void;

package/dist/utils/objects.d.ts

@@ -1,109 +1,127 @@
 /**
- * Converts a Proxy object to a plain object.
- * @param {ProxyConstructor} proxy The Proxy object to convert.
- * @returns {Object} The plain object.
+ * Converts a Proxy object into a plain JavaScript object.
+ *
+ * @param {ProxyConstructor} proxy - The Proxy object to convert.
+ * @returns {any} A new object containing the properties of the Proxy.
  */
 export declare function proxyToPlainObject(proxy: ProxyConstructor): any;
 /**
- * Compares two objects to check if they have the same keys.
- * @param {Object} object1 The first object to compare.
- * @param {Object} object2 The second object to compare.
- * @returns {boolean} True if the objects have the same keys, otherwise false.
+ * Performs a shallow comparison to check if two objects have the same keys.
+ *
+ * @param {Record<string, any>} object1 - The first object.
+ * @param {Record<string, any>} object2 - The second object.
+ * @returns {boolean} `true` if both objects have the exact same set of keys, otherwise `false`.
  */
 export declare function compareObject(object1: Record<string, any>, object2: Record<string, any>): boolean;
 /**
- * Deeply compares two objects to check if they are equal.
- * @param {Object} object1 The first object to compare.
- * @param {Object} object2 The second object to compare.
- * @returns {boolean} True if the objects are deeply equal, otherwise false.
+ * Performs a deep comparison between two objects to determine if they are structurally and value-wise equal.
+ *
+ * @param {Record<string, any>} object1 - The first object.
+ * @param {Record<string, any>} object2 - The second object.
+ * @returns {boolean} `true` if the objects are deeply equal, otherwise `false`.
  */
 export declare function deepEqual(object1: Record<string, any>, object2: Record<string, any>): boolean;
 /**
- * Deeply clones an object.
- * @param {Object} obj The object to clone.
- * @returns {Object} The cloned object.
+ * Creates a deep clone of a given object, including nested objects and arrays.
+ *
+ * @template T - The type of the object being cloned.
+ * @param {T} obj - The object to clone.
+ * @returns {T} A new object that is a deep clone of the original.
+ * @throws {Error} If the object contains a type that cannot be cloned.
  */
 export declare function deepClone<T>(obj: T): T;
 /**
- * Converts an object to a query string.
- * @param {Object} obj The object to convert.
- * @returns {string} The query string.
+ * Converts a flat object into a URL query string.
+ *
+ * @param {Record<string, any>} obj - The object to convert.
+ * @returns {string} The resulting URL query string.
  */
 export declare function objectToQueryString(obj: Record<string, any>): string;
 /**
- * Gets the differences between two objects.
- * @param {Object} object1 The first object.
- * @param {Object} object2 The second object.
- * @returns {Object} An object containing the differences.
+ * Compares two objects and returns an object containing the keys where their values differ.
+ *
+ * @param {Record<string, any>} object1 - The first object.
+ * @param {Record<string, any>} object2 - The second object.
+ * @returns {Record<string, any>} An object where each key represents a difference, and the value contains the differing values from both objects.
  */
 export declare function getObjectDifferences(object1: Record<string, any>, object2: Record<string, any>): Record<string, any>;
 /**
- * Filters an object by a list of keys.
- * @param {Object} obj The object to filter.
- * @param {Array<string>} keys The keys to keep.
- * @returns {Object} The filtered object.
+ * Creates a new object containing only the specified keys from the original object.
+ *
+ * @param {Record<string, any>} obj - The source object.
+ * @param {string[]} keys - An array of keys to include in the new object.
+ * @returns {Record<string, any>} A new object with the filtered properties.
  */
 export declare function filterObjectByKeys(obj: Record<string, any>, keys: string[]): Record<string, any>;
 /**
- * Deeply merges two objects.
- * @param {Object} target The target object to merge into.
- * @param {Object} source The source object to merge from.
- * @returns {Object} The merged object.
+ * Recursively merges the properties of a source object into a target object.
+ *
+ * @template T - The type of the target object.
+ * @param {T} target - The object to merge properties into.
+ * @param {Partial<T>} source - The object from which to merge properties.
+ * @returns {T} The modified target object.
  */
 export declare function deepMerge<T>(target: T, source: Partial<T>): T;
 /**
- * Checks if an object is empty.
- * @param {Object} obj The object to check.
- * @returns {boolean} True if the object is empty, otherwise false.
+ * Checks if an object has no own enumerable properties.
+ *
+ * @param {Record<string, any>} obj - The object to check.
+ * @returns {boolean} `true` if the object is empty, otherwise `false`.
  */
 export declare function isEmptyObject(obj: Record<string, any>): boolean;
 /**
- * Safely accesses nested properties in an object.
- * @param {Object} obj The object to access.
- * @param {Array<string>} keys The array of keys representing the path.
- * @returns {any} The value at the nested path, or undefined if not found.
+ * Safely retrieves a nested property from an object using an array of keys as the path.
+ *
+ * @param {Record<string, any>} obj - The object to query.
+ * @param {string[]} keys - An array of keys representing the path to the nested property.
+ * @returns {*} The value of the nested property, or `undefined` if the path is not valid.
  */
 export declare function safeGet(obj: Record<string, any>, keys: string[]): any;
 /**
- * Removes empty properties (null, undefined, or empty string) from an object.
- * @param {Object} obj The object to clean.
- * @returns {Object} A new object without empty properties.
+ * Creates a new object with all properties that have `null`, `undefined`, or empty string values removed.
+ *
+ * @param {Record<string, any>} obj - The source object.
+ * @returns {Record<string, any>} A new object containing only the non-empty properties.
  */
 export declare function removeEmptyProperties(obj: Record<string, any>): Record<string, any>;
 /**
- * Retrieves all keys of an object as an array.
- * @param {Object} obj The object to retrieve keys from.
- * @returns {Array<string>} The array of keys.
+ * Returns an array of an object's own enumerable property names.
+ *
+ * @param {Record<string, any>} obj - The object to get the keys from.
+ * @returns {string[]} An array of string keys.
  */
 export declare function getObjectKeys(obj: Record<string, any>): string[];
 /**
- * Checks if an object has nested properties.
- * @param {Object} obj The object to check.
- * @returns {boolean} True if there are nested properties, false otherwise.
+ * Checks if any of the object's properties are themselves objects (and not null).
+ *
+ * @param {Record<string, any>} obj - The object to inspect.
+ * @returns {boolean} `true` if the object contains at least one nested object, otherwise `false`.
  */
 export declare function hasNestedProperties(obj: Record<string, any>): boolean;
 /**
- * Converts an object to FormData, handling nested objects.
- * @param {Object} obj The object to convert.
- * @param {FormData} [formData] The FormData object to append to.
- * @param {string} [parentKey] The parent key for nested objects.
- * @returns {FormData} The FormData object.
+ * Recursively converts a nested object into a `FormData` object.
+ *
+ * @param {Record<string, any>} obj - The object to convert.
+ * @param {FormData} [formData=new FormData()] - An existing `FormData` object to append to.
+ * @param {string} [parentKey=''] - The base key for nested properties.
+ * @returns {FormData} The resulting `FormData` object.
  */
 export declare function objectToFormDataEnhanced(obj: Record<string, any>, formData?: FormData, parentKey?: string): FormData;
 /**
- * Converts a JavaScript object into FormData.
+ * Recursively converts a JavaScript object into a `FormData` object, handling nested objects and boolean conversion.
  *
- * @param obj - The object to be converted.
- * @param form - An optional FormData instance to use.
- * @param namespace - An optional namespace to use for nested objects.
- * @returns The FormData instance with the object's key-value pairs.
+ * @param {any} obj - The object to convert.
+ * @param {FormData} [form] - An optional existing `FormData` object to append to.
+ * @param {string} [namespace] - An optional namespace for keys of nested properties.
+ * @returns {FormData} The resulting `FormData` object.
  */
 export declare const objectToFormData: (obj: any, form?: FormData, namespace?: string) => FormData;
 /**
- * Flattens a nested object, bringing all properties to the top level.
- * @param {Object} obj The object to flatten.
- * @param {string} [parentKey] The parent key for nested properties.
- * @param {Object} [result] The resulting flattened object.
- * @returns {Object} The flattened object.
+ * Flattens a nested object into a single-level object with dot-separated keys.
+ *
+ * @param {Record<string, any>} obj - The object to flatten.
+ * @param {string} [parentKey=''] - The prefix to use for the keys of the flattened properties.
+ * @param {Record<string, any>} [result={}] - An object to merge the flattened properties into.
+ * @returns {Record<string, any>} The flattened object.
  */
 export declare function flattenObject(obj: Record<string, any>, parentKey?: string, result?: Record<string, any>): Record<string, any>;

package/dist/utils/retry.d.ts

@@ -0,0 +1,8 @@
+export interface RetryConfig {
+    retries?: number;
+    retryDelay?: number;
+    retryCondition?: (error: unknown) => boolean;
+    maxRetryDelay?: number;
+    backoffMultiplier?: number;
+}
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;

package/dist/utils/ssr.d.ts

@@ -0,0 +1,27 @@
+export declare const isServer: boolean;
+export declare const isClient: boolean;
+export declare function getStorage(): Storage | null;
+export declare function getSessionStorage(): Storage | null;
+export interface CookieOptions {
+    expires?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    httpOnly?: boolean;
+}
+export interface CookieStorage {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string, options?: CookieOptions) => void;
+    removeItem: (key: string, options?: {
+        path?: string;
+        domain?: string;
+    }) => void;
+}
+export declare function getCookieStorage(): CookieStorage;
+export interface PreferredStorage {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+}
+export declare function getPreferredStorage(): PreferredStorage;

package/dist/utils/storage.d.ts

@@ -1,20 +1,26 @@
 import { LocationPreference } from "@/types";
+import { CookieOptions } from "./ssr";
 /**
- * Encrypts and stores an item in local or session storage.
- * Assumes the `window` environment is available.
- * @param key The key under which to store the value.
- * @param value The value to encrypt and store.
- * @param secretKey The secret key for encryption.
- * @param location Determines where the item is stored: 'local' for localStorage, 'session' for sessionStorage.
- * @returns A promise that resolves when the item is stored. Throws an error if it fails.
+ * Encrypts and stores a key-value pair in either `localStorage`, `sessionStorage`, or cookies.
+ * Cookies are automatically used in SSR environments and can be explicitly requested.
+ * Cookies include security options: Secure (HTTPS only), SameSite (CSRF protection), and encryption.
+ *
+ * @param {string} key - The key for the storage item.
+ * @param {string} value - The string value to encrypt and store.
+ * @param {string} secretKey - The secret key to use for encryption.
+ * @param {LocationPreference} location - The storage location: 'local' for `localStorage`, 'session' for `sessionStorage`, 'cookie' for cookies, or 'any' for retrieval.
+ * @param {CookieOptions} [cookieOptions] - Optional cookie-specific options (only used when location is 'cookie').
+ * @returns {Promise<void>} A promise that resolves when the item has been stored.
  */
-export declare function storeEncryptedItem(key: string, value: string, secretKey: string, location: LocationPreference): Promise<void>;
+export declare function storeEncryptedItem(key: string, value: string, secretKey: string, location: LocationPreference, cookieOptions?: CookieOptions): Promise<void>;
 /**
- * Retrieves and decrypts a value from local or session storage.
- * Assumes the `window` environment is available.
- * @param key The key of the item to retrieve.
- * @param secretKey The secret key for decryption.
- * @param location Specifies where to search for the item: 'local' for localStorage, 'session' for sessionStorage, or 'any' to check both (session first).
- * @returns A promise that resolves with the decrypted value or null if not found or decryption fails.
+ * Retrieves and decrypts an item from `localStorage`, `sessionStorage`, or cookies.
+ * When location is 'any', checks in order: sessionStorage, localStorage, cookies.
+ * Cookies are automatically checked in SSR environments.
+ *
+ * @param {string} key - The key of the item to retrieve.
+ * @param {string} secretKey - The secret key to use for decryption.
+ * @param {LocationPreference} location - The storage location to search: 'local', 'session', 'cookie', or 'any' (checks session, local, cookie in that order).
+ * @returns {Promise<string | null>} A promise that resolves with the decrypted value, or `null` if the item is not found or decryption fails.
  */
 export declare function getDecryptedItem(key: string, secretKey: string, location: LocationPreference): Promise<string | null>;