shelving/util/query.d.ts

Toolkit for using data in JavaScript.

import type { ImmutableArray } from "./array.js";
import type { Data, LeafData, LeafKey } from "./data.js";
/** Query that can be applied to a list of data objects. */
export type Query<T extends Data> = {
    readonly [K in LeafKey<T> as `${K}` | `!${K}`]?: LeafData<T>[K] | ImmutableArray<LeafData<T>[K]> | undefined;
} & {
    readonly [K in LeafKey<T> as `${K}<` | `${K}<=` | `${K}>` | `${K}>=`]?: LeafData<T>[K] | undefined;
} & {
    readonly [K in LeafKey<T> as `${K}[]`]?: LeafData<T>[K] extends ImmutableArray<infer X> ? X | undefined : never;
} & {
    readonly $order?: `${LeafKey<T>}` | `!${LeafKey<T>}` | undefined | ImmutableArray<`${LeafKey<T>}` | `!${LeafKey<T>}` | undefined>;
    readonly $limit?: number | undefined;
};
/** A single filter that can be applied to a list of data objects. */
export type Filter = {
    key: string;
    operator: "is";
    value: unknown;
} | {
    key: string;
    operator: "not";
    value: unknown;
} | {
    key: string;
    operator: "in";
    value: ImmutableArray;
} | {
    key: string;
    operator: "out";
    value: ImmutableArray;
} | {
    key: string;
    operator: "contains";
    value: unknown;
} | {
    key: string;
    operator: "lt";
    value: unknown;
} | {
    key: string;
    operator: "lte";
    value: unknown;
} | {
    key: string;
    operator: "gt";
    value: unknown;
} | {
    key: string;
    operator: "gte";
    value: unknown;
};
/** A single sort order that can be applied to a list of data objects. */
export type Order = {
    key: string;
    direction: "asc" | "desc";
};
/** Get the `Filter` objects for a query. */
export declare function getFilters<T extends Data>(query: Query<T>): ImmutableArray<Filter>;
/** Get the `Order` objects for a query. */
export declare function getOrders<T extends Data>({ $order }: Query<T>): ImmutableArray<Order>;
/** Get the limit for a query. */
export declare function getLimit<T extends Data>({ $limit }: Query<T>): number | undefined;
/** Query a set of data items using a query. */
export declare function queryItems<T extends Data>(items: Iterable<T>, query: Query<T>): Iterable<T>;
/**
 * Query a set of data items for writing using a query.
 * - If no limit is set on the data sorting can be avoided too for performance reasons.
 */
export declare function queryWritableItems<T extends Data>(items: Iterable<T>, query: Query<T>): Iterable<T>;
/** Match a single data item againt a set of filters. */
export declare function matchQueryItem<T extends Data>(item: T, filters: ImmutableArray<Filter>): boolean;
/**  Filter a set of data items using a set of filters. */
export declare function filterQueryItems<T extends Data>(items: Iterable<T>, filters: ImmutableArray<Filter>): Iterable<T>;
/** Compare two data items using a set of orders. */
export declare function compareQueryItems<T extends Data>(left: T, right: T, orders: ImmutableArray<Order>): number;
/**  Sort a set of data items using a set of orders. */
export declare function sortQueryItems<T extends Data>(items: Iterable<T>, orders: ImmutableArray<Order>): Iterable<T>;
/** LImit a set of data items using a set of limit. */
export declare function limitQueryItems<T extends Data>(items: ImmutableArray<T> | Iterable<T>, limit: number | undefined): Iterable<T>;
/** Get a query for items that appear before a specified item. */
export declare function getBeforeQuery<T extends Data>(query: Query<T>, item: T): Query<T>;
/** Get a query for items that appear after a specified item. */
export declare function getAfterQuery<T extends Data>(query: Query<T>, item: T): Query<T>;