@njs-lib/select-query/dist/index.d.ts

Library for flexible querying and manipulation of object collections.

declare const operators: readonly ["===", "!==", "<", "<=", ">", ">=", "like", "^like", "like$"];
type Operator = typeof operators[number];
/**
 * SelectQuery provides utility methods for querying and manipulating collections of objects.
 * @template T - The type of objects in the collection.
 */
declare class SelectQuery<T extends object> {
    #private;
    /**
     * Gets the array of valid operators for comparisons.
     * @returns {Operator[]} - An array containing all valid operators for comparisons.
     * @description
     * This method returns an array of predefined operators that can be used for comparisons,
     * such as '===', '!==', '<', '<=', '>', '>=', 'like', '^like', and 'like$'.
     * These operators are useful in scenarios where you need to dynamically select
     * an operator for a comparison operation.
     */
    static getOperators(): typeof operators;
    /**
     * Creates a new SelectQuery instance with the given collection.
     * @param {T[]} collection - An array of objects to be used for querying.
     * @throws {Error} Throws an error if the input is not an array of objects.
     */
    constructor(collection: T[]);
    /**
     * Gets the first element of the collection.
     * @returns {T | undefined} - The first element of the collection, or undefined if the collection is empty.
     */
    first(): T | undefined;
    /**
     * Gets the last element of the collection.
     * @returns {T | undefined} - The last element of the collection, or undefined if the collection is empty.
     */
    last(): T | undefined;
    /**
     * Gets all elements in the collection.
     * @returns {T[]} - An array containing all elements in the collection.
     */
    get(): T[];
    /**
     * Gets the number of elements in the collection.
     * @returns {number} - The number of elements in the collection.
     */
    count(): number;
    /**
     * Limits the number of objects in the collection to a specified maximum.
     * @param {number} limit - The maximum number of objects to include in the collection.
     * @returns {SelectQuery<T>} - A new SelectQuery instance with a limited number of objects.
     */
    limit(limit: number): SelectQuery<T>;
    /**
     * Offsets the collection by a specified number of objects.
     * @param {number} offset - The number of objects to skip from the beginning of the collection.
     * @returns {SelectQuery<T>} - A new SelectQuery instance with objects after the specified offset.
     */
    offset(offset: number): SelectQuery<T>;
    /**
     * Paginates the collection based on a page number and page size.
     * @param {number} num - The page number (1-based).
     * @param {number} size - The number of objects per page.
     * @returns {SelectQuery<T>} - A new SelectQuery instance with objects for the specified page.
     */
    paginate(num: number, size: number): SelectQuery<T>;
    /**
     * Calculates the sum of the values for a specified property in the collection.
     * This method iterates over each object in the collection, accessing the value
     * of the specified property. It sums these values and returns the total. If a
     * property's value is `undefined`, `null` it will be ignored
     * (treated as 0) in the summation.
     * @template K - The type of the key.
     * @param {keyof T} key - The property key whose values are to be summed up.
     * @returns {number} The sum of the property values.
     * @throws {Error} Throws an error if any property value is not a number.
     */
    sum<K extends keyof T>(key: K): number;
    /**
     * Selects specific properties from each object in the collection and returns a new SelectQuery instance.
     * @template K - The keys to select from the objects in the collection.
     * @param {...K} keys - The keys (properties) to select.
     * @returns {SelectQuery<Pick<T, K>>} - A new SelectQuery instance with objects containing only the selected keys.
     */
    select<K extends keyof T>(...keys: K[]): SelectQuery<Pick<T, K>>;
    /**
     * Groups elements in a collection based on a specified key.
     * @template K - The type of the key.
     * @param {K} key - The key (property name) by which to group elements.
     * @returns {Record<T[K], T>} - An object with keys as unique values from the collection based on the specified key,
     * and values as the corresponding objects from the collection.
     */
    keyBy<K extends keyof T>(key: K): Record<T[K] & (string | number | symbol), T>;
    /**
     * Filters the collection based on a specified condition.
     * @template K - The type of the property to compare.
     * @param {keyof T} key - The key (property name) to compare.
     * @param {Operator} operator - The comparison operator.
     * @param {T[keyof T]} value - The value to compare against.
     * @returns {SelectQuery<T>} - A new SelectQuery instance with filtered elements.
     */
    where<K extends keyof T>(key: K, operator: Operator, value: T[K]): SelectQuery<T>;
}

export { SelectQuery };