import { StateRepository } from '../core';
/**
 * Service for storing and retrieving user-specific data that persists between sessions
 *
 * The UserDataRepository provides a key-value store for saving user preferences,
 * UI state, component settings, and other data that should persist across browser
 * sessions. This is useful for remembering user choices, UI customizations, and
 * component-specific settings.
 *
 * Data is stored per user and persists on the server, so users will see their
 * saved data regardless of which device or browser they use.
 *
 * Since UserDataRepository extends {@link StateRepository}, components can use the
 * {@link SelectUserData} decorator to automatically re-render when user data
 * changes.
 *
 * @example Storing and retrieving user preferences
 * ```ts
 * import {
 *     PlatformServiceName,
 *     UserDataRepository,
 * } from '@limetech/lime-web-components';
 *
 * class MySettingsPanel {
 *     private userData: UserDataRepository;
 *
 *     componentWillLoad() {
 *         this.userData = platform.get(PlatformServiceName.UserDataRepository);
 *
 *         if (this.userData.has('theme')) {
 *             this.applyTheme(this.userData.get<string>('theme'));
 *         }
 *     }
 *
 *     private async saveTheme(theme: string) {
 *         await this.userData.set('theme', theme);
 *         this.applyTheme(theme);
 *     }
 *
 *     private applyTheme(theme: string) {
 *         document.body.dataset['theme'] = theme;
 *     }
 * }
 * ```
 *
 * @example Re-rendering when user data changes
 * ```ts
 * import { State } from '@stencil/core';
 * import {
 *     PlatformServiceName,
 *     SelectUserData,
 * } from '@limetech/lime-web-components';
 *
 * class MyViewSelector {
 *     // Set again by the platform every time the saved view changes, so the
 *     // component re-renders without any subscription code of its own
 *     @State()
 *     @SelectUserData({ key: 'selectedView' })
 *     private selectedView: string;
 *
 *     private async setView(view: string) {
 *         const userData = platform.get(PlatformServiceName.UserDataRepository);
 *
 *         await userData.set('selectedView', view);
 *     }
 * }
 * ```
 *
 * @public
 * @group User data
 * @see {@link StateRepository} for subscription patterns
 */
export interface UserDataRepository extends StateRepository {
    /**
     * Check if user data exists for a given key
     *
     * Use this method to determine whether data has been previously saved
     * under a specific key before attempting to retrieve it.
     *
     * @param key - The key to check for stored data
     * @returns `true` if data exists under the key, `false` otherwise
     *
     * @example Check before reading
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const userData = platform.get(PlatformServiceName.UserDataRepository);
     *
     * // Offer the reset only when there is a saved layout to reset to
     * const canResetLayout = userData.has('dashboardLayout');
     * ```
     *
     * @see {@link UserDataRepository.get} to read stored data
     * @see {@link UserDataRepository.set} to store data
     */
    has(key: string): boolean;
    /**
     * Retrieve user data stored under a specific key
     *
     * Returns the value previously saved with {@link UserDataRepository.set}.
     *
     * @param key - The key identifying the data to retrieve
     * @returns The stored data, or `undefined` if no data exists for the key
     *
     * @typeParam T - The expected type of the stored data
     *
     * @example Retrieving typed data
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * interface UserSettings {
     *     notifications: boolean;
     *     autoSave: boolean;
     * }
     *
     * const userData = platform.get(PlatformServiceName.UserDataRepository);
     *
     * const settings = userData.get<UserSettings>('settings');
     *
     * // Nothing has been saved yet the first time the user opens the component, so
     * // read the values defensively
     * const notificationsEnabled = settings?.notifications === true;
     * const fontSize = userData.get<number>('fontSize') || 14;
     * ```
     *
     * @see {@link UserDataRepository.has} to check that a key exists
     * @see {@link UserDataRepository.set} to store data
     */
    get<T = any>(key: string): T;
    /**
     * Store user data under a specific key
     *
     * Saves the provided data to the server, where it will persist between
     * sessions. The data is automatically serialized to JSON.
     *
     * To delete previously saved data, pass `undefined` as the data parameter.
     *
     * @param key - The key under which to store the data
     * @param data - The data to save. Pass `undefined` to delete existing data
     * @returns A promise that resolves when the data has been saved to the server
     * @throws An error if the request to the server fails
     *
     * @typeParam T - The type of data being stored
     *
     * @example Saving user data
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * interface FilterSettings {
     *     status: string[];
     *     dateRange: { from: string; to: string };
     * }
     *
     * const userData = platform.get(PlatformServiceName.UserDataRepository);
     *
     * await userData.set('fontSize', 16);
     * await userData.set('showWelcome', false);
     *
     * const filters: FilterSettings = {
     *     status: ['active', 'pending'],
     *     dateRange: { from: '2024-01-01', to: '2024-12-31' },
     * };
     *
     * await userData.set('filters', filters);
     * ```
     *
     * @example Deleting saved data
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const userData = platform.get(PlatformServiceName.UserDataRepository);
     *
     * // Passing undefined as the value deletes the saved data
     * await userData.set('mySettings', undefined);
     *
     * console.log(userData.has('mySettings')); // false
     * ```
     *
     * @see {@link UserDataRepository.get} to read stored data
     * @see {@link UserDataRepository.has} to check that a key exists
     */
    set<T = any>(key: string, data?: T): Promise<void>;
}