tablor-core/lib/utils/items-utils.d.ts

Core features for data tables, grids, and advanced search, pagination, and sorting in Angular.

import { AugmentedItem, ImmutableAugmentedPartialRegularItem, ImmutableAugmentedItem, ImmutablePartialRegularItem, ImmutableRegularItem, Item } from '../stores/items-store/interfaces';
import { ProcessedField } from '../stores/fields-store/interfaces';
/**
 * Utility functions for working with items.
 *
 * @remarks
 * This class contains methods that are useful when working with items.
 * Items are the data records managed by the data table library.
 */
export declare class ItemsUtils {
    /**
     * Adds `tablorMeta` properties to each item in the items.
     * @param items - The items to extend.
     * @param getUuidAutoCounter - A function to generate unique UUIDs for items.
     * @returns Augmented items with added `tablorMeta` properties.
     */
    static augmentItems<T extends Item<T>>(items: Readonly<(ImmutableAugmentedItem<T> | ImmutableRegularItem<T>)[]>, getUuidAutoCounter: () => number): AugmentedItem<T>[];
    /**
     * Finds the difference between two items.
     * @param item1 - The first item.
     * @param item2 - The second item.
     * @returns The differences between the items.
     */
    static getItemUpdates<T extends Item<T>>(item1: Partial<T>, item2: AugmentedItem<T>): Partial<AugmentedItem<T>>;
    /**
     * Checks if two items are equal.
     * @param item1 - The first item.
     * @param item2 - The second item.
     * @returns `true` if items are equal, otherwise `false`.
     */
    static itemsAreEqual<T extends Item<T>>(item1: Readonly<T> | ImmutableAugmentedItem<T> | number | undefined, item2: Readonly<T> | ImmutableAugmentedItem<T> | number | undefined): boolean;
    /**
     * Merges a new item with an existing item, creating a new item.
     * @param item1 - The new item with updated properties.
     * @param item2 - The existing item to update.
     * @returns The updated item.
     */
    static mergeItemWith<T extends Item<T>>(item1: Partial<T>, item2: AugmentedItem<T>): AugmentedItem<T>;
    /**
     * Merges a new item with an existing item in place.
     * @param item1 - The new item with updated properties.
     * @param item2 - The existing item to update.
     */
    static mergeItemInPlace<T extends Item<T>>(item1: Partial<T>, item2: AugmentedItem<T>): void;
    /**
     * Replaces the current dataset with a new dataset.
     * @param dataRef - The reference to the existing dataset.
     * @param newDataSet - The new dataset to replace the existing one.
     * @param getUuidAutoCounter - A function to generate unique UUIDs for items.
     */
    static replaceItemsInPlace<T extends Item<T>>(dataRef: AugmentedItem<T>[], newDataSet: Readonly<ImmutableRegularItem<T>[]>, getUuidAutoCounter: () => number): void;
    /**
     * Removes items based on their UUIDs or data items.
     * @param dataSetRef - The dataset to update.
     * @param itemsOrUuids - The items or UUIDs to remove.
     * @param indexPicker - A function to determine the index of items to remove.
     * @returns The status of removals and removed items.
     */
    static removeItemsInPlace<T extends Item<T>>(dataSetRef: ImmutableAugmentedItem<T>[], itemsOrUuids: Readonly<(ImmutableAugmentedItem<T> | ImmutableRegularItem<T> | number | undefined)[]>, indexPicker: (item: ImmutableAugmentedItem<T> | ImmutableRegularItem<T> | number | undefined, i: number) => number): [boolean[], ImmutableAugmentedItem<T>[]];
    /**
     * Updates items in the dataset in place.
     * @param dataRef - The dataset to update.
     * @param itemIndexes - The indexes of items to update.
     * @param modificationsInItems - The modifications to apply.
     * @returns The status of modifications, modified items, and fields.
     */
    static updateItemsInPlace<T extends Item<T>>(dataRef: AugmentedItem<T>[], itemIndexes: number[], modificationsInItems: Readonly<(ImmutablePartialRegularItem<T> | undefined)[]>): [boolean[], AugmentedItem<T>[], Partial<AugmentedItem<T>>[]];
    /**
     * Filters an array of items by a specific field and value.
     * @param dataSetRef - The array of items to filter.
     * @param key - The field to check for the given value.
     * @param value - The value to compare the field against.
     * @returns An array of filtered items matching the key-value condition.
     */
    filterItemsBy<T extends Item<T>, K extends keyof T>(dataSetRef: ImmutableAugmentedItem<T>[], key: K, value: T[K]): ImmutableAugmentedItem<T>[];
    /**
     * Maps each item in the data to a new structure based on the provided field mappings.
     * @param data - The data to map.
     * @param fieldsArray - An array of fields that defines how to map each item.
     * @param markMissingItemsUndefined - Whether to set missing fields to `undefined`.
     * @returns A new array of mapped items.
     */
    static mapItemsPropsToFields<T extends Item<T>>(data: Readonly<(ImmutableRegularItem<T> | ImmutableAugmentedPartialRegularItem<T> | ImmutablePartialRegularItem<T>)[]>, fieldsArray: ProcessedField<T, keyof T>[], markMissingItemsUndefined: boolean): Readonly<(ImmutableRegularItem<T> | ImmutableAugmentedPartialRegularItem<T> | ImmutablePartialRegularItem<T>)[]>;
    /**
     * Finds the indexes of items that match the given UUIDs, items, or augmented items.
     * @param dataRef - Dataset to search in.
     * @param itemsOrUuids - Items or UUIDs to match against.
     * @returns Array of indexes of matching items, or -1 for no match.
     *
     * @remarks
     * - For UUIDs, matches are based on the `tablorMeta.uuid`.
     * - For augmented items, matching is done using the UUID in `tablorMeta`.
     * - For regular items, a deep equality check is performed.
     */
    static findIndexes<T extends Item<T>>(dataRef: ImmutableAugmentedItem<T>[], itemsOrUuids: Readonly<(ImmutableAugmentedItem<T> | ImmutableRegularItem<T> | ImmutableAugmentedPartialRegularItem<T> | number | undefined)[]>): number[];
    /**
     * Finds all matching indexes for the given UUIDs, items, or augmented items.
     * @param dataRef - Dataset to search in.
     * @param itemsOrUuids - UUIDs, items, or augmented items to match.
     * @returns An array of arrays, each containing matching indexes for each item.
     *
     * @remarks
     * - Matches all items with the given UUID.
     * - For augmented items, matching is based on UUIDs within `tablorMeta`.
     * - Regular items are matched using deep equality.
     * - For unmatched items, an empty array is returned.
     */
    static findAllIndexes<T extends Item<T>>(dataRef: ImmutableAugmentedItem<T>[], itemsOrUuids: Readonly<(ImmutableAugmentedItem<T> | ImmutableRegularItem<T> | ImmutableAugmentedPartialRegularItem<T> | number | undefined)[]>): number[][];
    /**
     * Wraps a method to manage loading state during its execution.
     * @param method - The method to wrap and handle the loading state for.
     * @param loadingSetter - Function to update the loading state (true/false).
     * @returns A wrapped method that manages the loading state.
     *
     * @remarks
     * - Sets loading state to `true` before the method runs, and `false` afterward.
     * - If an error occurs, loading state is set to `false`, and the error is thrown.
     */
    static handleLoading<T extends (...args: any[]) => any>(method: T, loadingSetter: (state: boolean) => void): (...args: Parameters<T>) => ReturnType<T>;
}