import { Filter } from '../query';
import { StateRepository } from '../core';
/**
 * Repository for managing saved filter definitions.
 *
 * {@link FilterRepository} provides methods to create, update, and delete {@link Filter}
 * definitions. Filters are named, reusable query expressions that can be applied to
 * limetypes to define subsets of objects (e.g., "My Active Deals", "High Priority Tickets").
 *
 * Filters can be:
 * - System-wide (available to all users)
 * - User-specific (private to a single user when `iduser` is set)
 * - Referenced in {@link InFilterExpression}s for advanced queries
 *
 * The repository extends {@link StateRepository}, enabling:
 * - Reactive subscriptions to filter changes
 * - Automatic UI updates when filters are created or deleted
 * - Integration with state decorators
 *
 * @example Basic usage
 * ```ts
 * import {
 *     Filter,
 *     Operator,
 *     PlatformServiceName,
 * } from '@limetech/lime-web-components';
 *
 * const repository = platform.get(PlatformServiceName.FilterRepository);
 *
 * const highValueDeals: Filter = {
 *     id: 'high_value_deals',
 *     limetype: 'deal',
 *     name: { en: 'High Value Deals' },
 *     filter: {
 *         op: Operator.AND,
 *         exp: [
 *             { key: 'status', op: Operator.EQUALS, exp: 'active' },
 *             { key: 'value', op: Operator.GREATER_OR_EQUAL, exp: 100_000 },
 *         ],
 *     },
 * };
 *
 * await repository.save(highValueDeals);
 *
 * await repository.delete(highValueDeals);
 * ```
 *
 * @public
 * @group Filters
 * @see {@link Filter} for filter definition structure
 * @see {@link Expression} for building filter expressions
 * @see {@link InFilterExpression} for referencing filters in queries
 * @see {@link StateRepository} for subscription patterns
 */
export interface FilterRepository extends StateRepository {
    /**
     * Get a loaded filter by id.
     *
     * Reads from the filters the repository already holds, so it does not
     * make a request. Returns `undefined` if no filter has the id, or if
     * the filters have not been loaded yet.
     *
     * @param id - The `id` of the {@link Filter}
     * @returns The {@link Filter}, or `undefined` if not found
     *
     * @example Show the name of a filter
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const filters = platform.get(PlatformServiceName.FilterRepository);
     * const language = platform.get(PlatformServiceName.Application).getLanguage();
     *
     * const filter = filters.getFilter?.('high_value_deals');
     *
     * if (filter) {
     *     console.log('Filter:', filter.name[language]);
     * }
     * ```
     *
     * @beta
     */
    getFilter?(id: string): Filter | undefined;
    /**
     * Save a filter definition to the database.
     *
     * Creates a new filter or updates an existing one. The filter will be stored
     * persistently and become available for use in queries and filter expressions.
     *
     * If a filter with the same `id` already exists, it will be updated with the
     * new values. Otherwise, a new filter is created.
     *
     * @param filter - The {@link Filter} definition to save
     * @returns Promise that resolves when the filter is saved
     * @throws Error if save fails due to validation or permission issues
     *
     * @example Save a filter private to the current user
     * ```ts
     * import {
     *     Filter,
     *     Operator,
     *     PlatformServiceName,
     * } from '@limetech/lime-web-components';
     *
     * const filters = platform.get(PlatformServiceName.FilterRepository);
     * const application = platform.get(PlatformServiceName.Application);
     *
     * const currentUser = application.getCurrentUser();
     *
     * if (currentUser) {
     *     const myDeals: Filter = {
     *         id: 'my_deals',
     *         limetype: 'deal',
     *         name: { en: 'My Deals' },
     *         filter: {
     *             key: 'owner',
     *             op: Operator.EQUALS,
     *             exp: currentUser.id,
     *         },
     *         // Setting iduser keeps the filter private to this user.
     *         iduser: currentUser.id,
     *     };
     *
     *     await filters.save(myDeals);
     * }
     * ```
     *
     * @see {@link Filter} for the filter structure
     * @see {@link Expression} for building filter expressions
     * @see {@link delete} to remove a filter
     */
    save(filter: Filter): Promise<void>;
    /**
     * Delete a filter from the database.
     *
     * Permanently removes the specified filter. This operation cannot be undone.
     *
     * @param filter - The {@link Filter} to delete
     * @returns Promise that resolves when the filter is deleted
     * @throws Error if deletion fails due to permissions or other issues
     *
     * @example Delete a filter the component holds in state
     * ```ts
     * import { State } from '@stencil/core';
     * import {
     *     Filter,
     *     PlatformServiceName,
     *     SelectFilters,
     * } from '@limetech/lime-web-components';
     *
     * class MyComponent {
     *     @State()
     *     @SelectFilters({ limetype: 'deal' })
     *     private dealFilters: Filter[];
     *
     *     private async deleteFilter(id: string) {
     *         const filter = this.dealFilters.find(
     *             (candidate) => candidate.id === id
     *         );
     *
     *         if (!filter) {
     *             return;
     *         }
     *
     *         const repository = platform.get(PlatformServiceName.FilterRepository);
     *         await repository.delete(filter);
     *     }
     * }
     * ```
     *
     * @see {@link Filter} for the filter structure
     * @see {@link save} to create or update a filter
     */
    delete(filter: Filter): Promise<void>;
}