tiny-essentials 1.18.1 → 1.19.0

package/dist/v1/libs/TinyLocalStorage.d.mts

@@ -0,0 +1,407 @@
+export default TinyLocalStorage;
+/**
+ * A function that encodes a value into a serializable JSON-compatible format.
+ */
+export type EncodeFn = (value: any, encodeSpecialJson: encodeSpecialJson) => any;
+/**
+ * An object that defines how to check and decode a specific serialized type.
+ */
+export type DecodeFn = {
+    /**
+     * - Checks if the value matches the custom encoded structure.
+     */
+    check: (value: any) => any;
+    /**
+     * - Decodes the structure back into its original form.
+     */
+    decode: (value: any, decodeSpecialJson: decodeSpecialJson) => any;
+};
+/**
+ * Encodes extended JSON-compatible structures recursively.
+ */
+export type encodeSpecialJson = (value: any) => any;
+/**
+ * Decodes extended JSON-compatible structures recursively.
+ */
+export type decodeSpecialJson = (value: any) => any;
+/**
+ * Represents a value that can be safely stored and restored using JSON in `localStorage`,
+ * including structures like arrays, plain objects, Map and Set.
+ *
+ * - `Record<string|number|symbol, any>` → plain object (e.g., `{ key: value }`)
+ * - `any[]` → array of any JSON-serializable values
+ * - `Map<string|number|symbol, any>` → converted to `{ __map__: true, data: [[k, v], ...] }`
+ * - `Set<any>` → converted to `{ __set__: true, data: [v1, v2, ...] }`
+ *
+ * These conversions allow complex structures to be restored after JSON serialization.
+ */
+export type LocalStorageJsonValue = (Record<string | number | symbol, any> | any[] | Map<string | number | symbol, any> | Set<any>);
+/**
+ * A function that encodes a value into a serializable JSON-compatible format.
+ *
+ * @callback EncodeFn
+ * @param {any} value - The value to encode.
+ * @param {encodeSpecialJson} encodeSpecialJson - Recursive encoder helper.
+ * @returns {any} The encoded value.
+ */
+/**
+ * An object that defines how to check and decode a specific serialized type.
+ *
+ * @typedef {Object} DecodeFn
+ * @property {(value: any) => any} check - Checks if the value matches the custom encoded structure.
+ * @property {(value: any, decodeSpecialJson: decodeSpecialJson) => any} decode - Decodes the structure back into its original form.
+ */
+/**
+ * Encodes extended JSON-compatible structures recursively.
+ * @callback encodeSpecialJson
+ * @param {any} value
+ * @returns {any}
+ */
+/**
+ * Decodes extended JSON-compatible structures recursively.
+ * @callback decodeSpecialJson
+ * @param {any} value
+ * @returns {any}
+ */
+/**
+ * Represents a value that can be safely stored and restored using JSON in `localStorage`,
+ * including structures like arrays, plain objects, Map and Set.
+ *
+ * - `Record<string|number|symbol, any>` → plain object (e.g., `{ key: value }`)
+ * - `any[]` → array of any JSON-serializable values
+ * - `Map<string|number|symbol, any>` → converted to `{ __map__: true, data: [[k, v], ...] }`
+ * - `Set<any>` → converted to `{ __set__: true, data: [v1, v2, ...] }`
+ *
+ * These conversions allow complex structures to be restored after JSON serialization.
+ *
+ * @typedef {(Record<string|number|symbol, any> | any[] | Map<string|number|symbol, any> | Set<any>)} LocalStorageJsonValue
+ */
+/**
+ * A powerful wrapper for Web Storage (`localStorage` or `sessionStorage`) that supports
+ * type-safe methods and full JSON-like structure encoding and decoding.
+ *
+ * `TinyLocalStorage` allows storing and retrieving complex types such as:
+ * - `Map`, `Set`
+ * - `Date`, `RegExp`
+ * - `BigInt`, `Symbol`
+ * - `undefined`, `null`
+ * - Plain objects and arrays
+ *
+ * Includes:
+ * - Type-specific `set` and `get` methods (`setDate`, `getBool`, etc.)
+ * - `getValue()` to retrieve any structure regardless of type
+ * - Auto-encoding/decoding with support for custom types via `registerJsonType`
+ * - Built-in event system (`TinyEvents`) to listen for changes
+ * - Optional fallback values on decoding errors
+ *
+ * Supports registering and unregistering custom types via:
+ * - `registerJsonType(...)`
+ * - `deleteJsonType(...)`
+ *
+ * This class is suitable for applications that require structured persistence in the browser.
+ */
+declare class TinyLocalStorage {
+    /**
+     * Registers a new JSON-serializable type with its encoder and decoder.
+     *
+     * @param {any} type - The type or primitive type name (e.g. `"bigint"`, `"symbol"`, etc).
+     * @param {EncodeFn} encodeFn - The function that encodes the value.
+     * @param {DecodeFn} decodeFn - An object with `check` and `decode` methods for restoring the value.
+     */
+    static registerJsonType(type: any, encodeFn: EncodeFn, decodeFn: DecodeFn): void;
+    /**
+     * Removes a previously registered custom type from the encoding/decoding system.
+     *
+     * @param {string} type - The primitive name or constructor reference used in registration.
+     */
+    static deleteJsonType(type: string): void;
+    static encodeSpecialJson(value: any): any;
+    static decodeSpecialJson(value: any): any;
+    /**
+     * Enables or disables throwing an error when the maximum number of listeners is exceeded.
+     *
+     * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
+     */
+    setThrowOnMaxListeners(shouldThrow: boolean): void;
+    /**
+     * Checks whether an error will be thrown when the max listener limit is exceeded.
+     *
+     * @returns {boolean} True if an error will be thrown, false if only a warning is shown.
+     */
+    getThrowOnMaxListeners(): boolean;
+    /**
+     * Adds a listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {handler} handler - The callback function.
+     */
+    prependListener(event: string, handler: import("./TinyEvents.mjs").handler): void;
+    /**
+     * Adds a one-time listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {handler} handler - The callback function.
+     * @returns {handler} - The wrapped handler used internally.
+     */
+    prependListenerOnce(event: string, handler: import("./TinyEvents.mjs").handler): import("./TinyEvents.mjs").handler;
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - Callback function to be called when event fires.
+     */
+    appendListener(event: string, handler: import("./TinyEvents.mjs").handler): void;
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - The callback function to run on event.
+     * @returns {handler} - The wrapped version of the handler.
+     */
+    appendListenerOnce(event: string, handler: import("./TinyEvents.mjs").handler): import("./TinyEvents.mjs").handler;
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - Callback function to be called when event fires.
+     */
+    on(event: string, handler: import("./TinyEvents.mjs").handler): void;
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - The callback function to run on event.
+     * @returns {handler} - The wrapped version of the handler.
+     */
+    once(event: string, handler: import("./TinyEvents.mjs").handler): import("./TinyEvents.mjs").handler;
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param {string} event - The name of the event to remove the handler from.
+     * @param {handler} handler - The specific callback function to remove.
+     */
+    off(event: string, handler: import("./TinyEvents.mjs").handler): void;
+    /**
+     * Removes all event listeners of a specific type from the element.
+     *
+     * @param {string} event - The event type to remove (e.g. 'onScrollBoundary').
+     */
+    offAll(event: string): void;
+    /**
+     * Removes all event listeners of all types from the element.
+     */
+    offAllTypes(): void;
+    /**
+     * Returns the number of listeners for a given event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {number} Number of listeners for the event.
+     */
+    listenerCount(event: string): number;
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {handler[]} Array of listener functions.
+     */
+    listeners(event: string): import("./TinyEvents.mjs").handler[];
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {handler[]} Array of listener functions.
+     */
+    onceListeners(event: string): import("./TinyEvents.mjs").handler[];
+    /**
+     * Returns a copy of the internal listeners array for the specified event,
+     * including wrapper functions like those used by `.once()`.
+     * @param {string | symbol} event - The event name.
+     * @returns {handler[]} An array of raw listener functions.
+     */
+    allListeners(event: string | symbol): import("./TinyEvents.mjs").handler[];
+    /**
+     * Returns an array of event names for which there are registered listeners.
+     *
+     * @returns {string[]} Array of registered event names.
+     */
+    eventNames(): string[];
+    /**
+     * Emits an event, triggering all registered handlers for that event.
+     *
+     * @param {string} event - The event name to emit.
+     * @param {...any} payload - Optional data to pass to each handler.
+     * @returns {boolean} True if any listeners were called, false otherwise.
+     */
+    emit(event: string, ...payload: any[]): boolean;
+    /**
+     * Sets the maximum number of listeners per event before a warning is shown.
+     *
+     * @param {number} n - The maximum number of listeners.
+     */
+    setMaxListeners(n: number): void;
+    /**
+     * Gets the maximum number of listeners allowed per event.
+     *
+     * @returns {number} The maximum number of listeners.
+     */
+    getMaxListeners(): number;
+    /**
+     * Defines a custom storage interface (e.g. `sessionStorage`).
+     *
+     * @param {Storage} localstorage - A valid Storage object (localStorage or sessionStorage).
+     */
+    setLocalStorage(localstorage: Storage): void;
+    /**
+     * Checks if `localStorage` is supported by the current environment.
+     *
+     * @returns {boolean} True if `localStorage` exists, false otherwise.
+     */
+    localStorageExists(): boolean;
+    /**
+     * Stores a JSON-compatible value in `localStorage`.
+     *
+     * Automatically serializes nested `Map` and `Set` instances.
+     *
+     * @param {string} name - The key under which to store the data.
+     * @param {LocalStorageJsonValue} data - The data to be serialized and stored.
+     */
+    setJson(name: string, data: LocalStorageJsonValue): void;
+    /**
+     * Retrieves and parses a JSON value from `localStorage`.
+     *
+     * Automatically restores nested `Map` and `Set` instances.
+     *
+     * @param {string} name - The key to retrieve.
+     * @param {'array'|'obj'|'map'|'set'|'null'} [defaultData] - Default fallback format if value is invalid.
+     * @returns {LocalStorageJsonValue|null} The parsed object or fallback.
+     */
+    getJson(name: string, defaultData?: "array" | "obj" | "map" | "set" | "null"): LocalStorageJsonValue | null;
+    /**
+     * Stores a Date in localStorage.
+     * @param {string} name
+     * @param {Date} data
+     */
+    setDate(name: string, data: Date): void;
+    /**
+     * Retrieves a Date from localStorage.
+     * @param {string} name
+     * @returns {Date|null}
+     */
+    getDate(name: string): Date | null;
+    /**
+     * Stores a RegExp in localStorage.
+     * @param {string} name
+     * @param {RegExp} data
+     */
+    setRegExp(name: string, data: RegExp): void;
+    /**
+     * Retrieves a RegExp from localStorage.
+     * @param {string} name
+     * @returns {RegExp|null}
+     */
+    getRegExp(name: string): RegExp | null;
+    /**
+     * Stores a BigInt in localStorage.
+     * @param {string} name
+     * @param {bigint} data
+     */
+    setBigInt(name: string, data: bigint): void;
+    /**
+     * Retrieves a BigInt from localStorage.
+     * @param {string} name
+     * @returns {bigint|null}
+     */
+    getBigInt(name: string): bigint | null;
+    /**
+     * Stores a Symbol in localStorage.
+     * Only global symbols (`Symbol.for`) will preserve the key.
+     * @param {string} name
+     * @param {symbol} data
+     */
+    setSymbol(name: string, data: symbol): void;
+    /**
+     * Retrieves a Symbol from localStorage.
+     * @param {string} name
+     * @returns {symbol|null}
+     */
+    getSymbol(name: string): symbol | null;
+    /**
+     * Retrieves a value from `localStorage`.
+     *
+     * @param {string} name - The key to retrieve.
+     * @returns {any} The stored value or null if not found.
+     */
+    getValue(name: string): any;
+    /**
+     * Stores a raw string value in `localStorage`.
+     *
+     * @param {string} name - The key to use.
+     * @param {any} data - The data to store.
+     */
+    setItem(name: string, data: any): void;
+    /**
+     * Retrieves a raw string value from `localStorage`.
+     *
+     * @param {string} name - The key to retrieve.
+     * @returns {string|null} The stored value or null if not found.
+     */
+    getItem(name: string): string | null;
+    /**
+     * Stores a string in `localStorage`, ensuring the data is a valid string.
+     *
+     * @param {string} name - The key to store the string under.
+     * @param {string} data - The string to store.
+     */
+    setString(name: string, data: string): void;
+    /**
+     * Retrieves a string value from `localStorage`.
+     *
+     * @param {string} name - The key to retrieve.
+     * @returns {string|null} The string if valid, or null.
+     */
+    getString(name: string): string | null;
+    /**
+     * Stores a number value in `localStorage`.
+     *
+     * @param {string} name - The key to use.
+     * @param {number} data - The number to store.
+     */
+    setNumber(name: string, data: number): void;
+    /**
+     * Retrieves a number from `localStorage`.
+     *
+     * @param {string} name - The key to retrieve.
+     * @returns {number|null} The number or null if invalid.
+     */
+    getNumber(name: string): number | null;
+    /**
+     * Stores a boolean value in `localStorage`.
+     *
+     * @param {string} name - The key to use.
+     * @param {boolean} data - The boolean value to store.
+     */
+    setBool(name: string, data: boolean): void;
+    /**
+     * Retrieves a boolean value from `localStorage`.
+     *
+     * @param {string} name - The key to retrieve.
+     * @returns {boolean|null} The boolean or null if invalid.
+     */
+    getBool(name: string): boolean | null;
+    /**
+     * Removes a value from `localStorage`.
+     *
+     * @param {string} name - The key to remove.
+     */
+    removeItem(name: string): void;
+    /**
+     * Clears all data from `localStorage`.
+     */
+    clearLocalStorage(): void;
+    /**
+     * Destroys the storage instance by removing the storage event listener.
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=TinyLocalStorage.d.mts.map