/**
 * Unified list search / filter query contract for table list APIs.
 * Used by server routes + web clients (buildListQueryString).
 */
export type ListSortOrder = 'asc' | 'desc';
export type ListQuery = {
    /** Free-text search (trimmed; empty = no text filter) */
    q: string;
    /** Named dimension filters (role, runtime, status, …) */
    filters: Record<string, string>;
    sort?: string;
    order: ListSortOrder;
    /** 1-based page; ignored when limit is 0 (return all matched) */
    page: number;
    /**
     * Page size. 0 = return all matched items (capped by maxAll).
     * Default 0 for host-panel sized datasets unless caller sets a page size.
     */
    limit: number;
};
export type ListMeta = {
    total: number;
    page: number;
    limit: number;
    q: string;
    filters: Record<string, string>;
    sort?: string;
    order: ListSortOrder;
    /** Counts per facet key → value, after text filter (before dimension filter on that key optional) */
    facets?: Record<string, Record<string, number>>;
    /** Unfiltered collection size (before q / dimension filters) */
    allTotal?: number;
};
export type ListResponse<T> = {
    items: T[];
    meta: ListMeta;
};
export type ParseListQueryOptions = {
    /** Allowed enum values per filter key; unknown values are dropped */
    enums?: Record<string, readonly string[]>;
    /** Extra free-form filter keys (any non-empty string kept) */
    freeFilters?: readonly string[];
    /** Allowed sort field names */
    sortFields?: readonly string[];
    defaultSort?: string;
    defaultOrder?: ListSortOrder;
    defaultLimit?: number;
    /** Max page size when limit > 0 (default 200) */
    maxLimit?: number;
    /** When limit=0, hard cap on returned rows (default 5000) */
    maxAll?: number;
    /** Query keys reserved (never treated as filters) */
    reserved?: readonly string[];
};
/**
 * Parse URL search params into ListQuery.
 * Accepts URL | URLSearchParams | Record-like get(name) objects.
 */
export declare function parseListQuery(source: URL | URLSearchParams | {
    searchParams: URLSearchParams;
}, opts?: ParseListQueryOptions): ListQuery;
/**
 * Build query string (without leading ?) from ListQuery-like state.
 */
export declare function buildListQueryString(input: {
    q?: string;
    filters?: Record<string, string | undefined | null>;
    sort?: string;
    order?: ListSortOrder;
    page?: number;
    limit?: number;
}): string;
export declare function emptyListMeta(query: ListQuery, total?: number): ListMeta;
//# sourceMappingURL=list-query.d.ts.map