@intellegens/cornerstone-client 0.0.0-experimental-upgrade-20260302-1

package/dist/adapters/CollectionViewAdapter/index.integration.test.js

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { CollectionViewAdapter } from '.';
+import { ReadSelectedComparisonOperator, ReadSelectedOrderingDirection, ReadSelectedPropertyType } from '../../data';
+import { dateInterval, searchTerm } from '../../utils';
+describe('CollectionViewAdapter', () => {
+    let data;
+    let error;
+    let isLoading;
+    const callback = vi.fn((_isLoading, _data, _error) => {
+        isLoading = _isLoading;
+        data = _data;
+        error = _error;
+    });
+    const options = {
+        pagination: { useTotalItemCount: true, pageSize: 5, pageNumber: 1 },
+        ordering: { maxActiveOrderingColumns: 1, orderByPaths: [] },
+        search: { textSearchableProperties: ['name'], numericSearchableProperties: ['id'] },
+    };
+    let adapter;
+    const waitForData = async (timeout = 2000) => {
+        const start = Date.now();
+        while (isLoading !== false && Date.now() - start < timeout) {
+            await new Promise(res => setTimeout(res, 50));
+        }
+    };
+    const resetAdapterState = () => {
+        data = undefined;
+        error = undefined;
+        isLoading = undefined;
+    };
+    beforeEach(() => {
+        data = undefined;
+        error = undefined;
+        isLoading = undefined;
+    });
+    it('callback returns correct loading status and collection data', async () => {
+        options.pagination.useTotalItemCount = true;
+        adapter = new CollectionViewAdapter('AnythingManuallyMappedRead', callback, options);
+        await waitForData();
+        expect(callback).toHaveBeenNthCalledWith(1, true, undefined, undefined);
+        expect(callback).toHaveBeenLastCalledWith(false, data, undefined);
+        expect(data).toBeDefined();
+    });
+    it('adapter options set correct ordering', async () => {
+        adapter = new CollectionViewAdapter('AnythingManuallyMappedRead', callback, options);
+        await waitForData();
+        resetAdapterState();
+        adapter.setOrdering(['name'], ReadSelectedOrderingDirection.Descending);
+        await waitForData();
+        expect(adapter.getCurrentOrdering()).toEqual([
+            {
+                orderByPath: ['name'],
+                orderDirection: ReadSelectedOrderingDirection.Descending,
+            },
+        ]);
+    });
+    it('text search is applied to adapter', async () => {
+        const searchDefinition = searchTerm('Flu', ['name'], ['id']);
+        if (!searchDefinition)
+            throw new Error('searchDefinition is undefined');
+        adapter = new CollectionViewAdapter('AnythingManuallyMappedRead', callback, options);
+        await waitForData();
+        resetAdapterState();
+        adapter.setSearchDefinition(searchDefinition);
+        await waitForData();
+        expect(data).toBeDefined();
+        expect(data.length).toBeGreaterThan(0);
+        for (const item of data) {
+            expect(item.name).toMatch(/flu/i);
+        }
+    });
+    it('numeric search is applied to adapter', async () => {
+        const searchDefinition = searchTerm('10000001', ['id'], ['id']);
+        if (!searchDefinition)
+            throw new Error('searchDefinition is undefined');
+        adapter = new CollectionViewAdapter('AnythingManuallyMappedRead', callback, options);
+        await waitForData();
+        resetAdapterState();
+        adapter.setSearchDefinition(searchDefinition);
+        await waitForData();
+        expect(data).toBeDefined();
+        expect(data.length).toBe(1);
+        for (const item of data) {
+            expect(item.id).toBe(10000001);
+        }
+    });
+    it('applies date range filter from-to on the same date type property', async () => {
+        adapter = new CollectionViewAdapter('PetsSlim', callback, options);
+        const from = new Date('2017-01-01T00:00:00.000Z');
+        const to = new Date('2017-12-31T00:00:00.000Z');
+        const searchDefinition = dateInterval(from, to, ReadSelectedComparisonOperator.GreaterOrEqual, ReadSelectedComparisonOperator.LessOrEqual, ReadSelectedPropertyType.DateOnly, 'dateOfBirth');
+        if (!searchDefinition)
+            throw new Error('searchDefinition is undefined');
+        await waitForData();
+        resetAdapterState();
+        adapter.setSearchDefinition(searchDefinition);
+        await waitForData();
+        expect(data).toBeDefined();
+    });
+    it('applies pagination: page size and jump to page set skip/limit', async () => {
+        adapter = new CollectionViewAdapter('AnythingManuallyMappedRead', callback, options);
+        await waitForData();
+        const firstPageData = data;
+        resetAdapterState();
+        adapter.jumpToPage(3);
+        await waitForData();
+        expect(data).toBeDefined();
+        expect(data.length).toBe(5);
+        // Check that data is different from first page
+        expect(data).not.toEqual(firstPageData);
+    });
+    it('calculates total when useTotalItemCount=false and last page is partial', async () => {
+        options.pagination.useTotalItemCount = false;
+        options.pagination.pageSize = 10;
+        adapter = new CollectionViewAdapter('AnythingManuallyMappedRead', callback, options);
+        await waitForData();
+        const firstPageData = data;
+        resetAdapterState();
+        adapter.jumpToPage(2);
+        await waitForData();
+        expect(adapter.totalItemCount).toBe(firstPageData.length + data.length);
+    });
+    it('setOrdering correctly handles PropertyPathDto array comparison and limits columns', async () => {
+        options.ordering.maxActiveOrderingColumns = 2;
+        // Add first ordering
+        adapter = new CollectionViewAdapter('AnythingManuallyMappedRead', callback, options);
+        adapter.setOrdering(['name'], ReadSelectedOrderingDirection.Descending);
+        await waitForData();
+        expect(adapter.getCurrentOrdering()).toEqual([
+            {
+                orderByPath: ['name'],
+                orderDirection: ReadSelectedOrderingDirection.Descending,
+            },
+        ]);
+        // Add second ordering
+        adapter.setOrdering(['id'], ReadSelectedOrderingDirection.Ascending);
+        await waitForData();
+        // Should have both orderings, with 'id' first (most recent)
+        expect(adapter.getCurrentOrdering()).toEqual([
+            {
+                orderByPath: ['id'],
+                orderDirection: ReadSelectedOrderingDirection.Ascending,
+            },
+            {
+                orderByPath: ['name'],
+                orderDirection: ReadSelectedOrderingDirection.Descending,
+            },
+        ]);
+        // // Add third ordering - should remove the oldest one (name)
+        adapter.setOrdering(['description'], ReadSelectedOrderingDirection.Descending);
+        await waitForData();
+        expect(adapter.getCurrentOrdering()).toEqual([
+            {
+                orderByPath: ['description'],
+                orderDirection: ReadSelectedOrderingDirection.Descending,
+            },
+            {
+                orderByPath: ['id'],
+                orderDirection: ReadSelectedOrderingDirection.Ascending,
+            },
+        ]);
+    });
+});

package/dist/adapters/CollectionViewAdapter/index.js

@@ -0,0 +1,381 @@
+import { toPascalCase } from '../../utils';
+import { ApiReadControllerClient } from '../../services';
+/**
+ * TS class for handling ordering, filtering and paginating collections
+ *
+ * @param controllerName - specify the target endpoint controller name.
+ * @param dataChangedCallback - Function invoked whenever the data changes.
+ * Receives a loading state flag and the updated data collection.
+ * @param options - Optional settings of type CollectionViewAdapter to customize the behavior of the adapter.
+ */
+export class CollectionViewAdapter {
+    _readClient;
+    _isLoading = false;
+    _pageData = [];
+    _selectedItems = [];
+    _defaultOptions = {
+        pagination: {
+            useTotalItemCount: false,
+            pageSize: 10,
+            pageNumber: 1,
+        },
+        ordering: {
+            maxActiveOrderingColumns: 1,
+            orderByPaths: [],
+        },
+        search: {
+            textSearchableProperties: [],
+            numericSearchableProperties: [],
+        },
+    };
+    _initialOptions;
+    _currentOptions;
+    constructor(controllerName, dataChangedCallback, options) {
+        this._readClient = new ApiReadControllerClient(controllerName);
+        this._initialOptions = {
+            pagination: {
+                ...this._defaultOptions.pagination,
+                ...options?.pagination,
+            },
+            ordering: {
+                ...this._defaultOptions.ordering,
+                ...options?.ordering,
+            },
+            search: {
+                ...this._defaultOptions.search,
+                ...options?.search,
+            },
+        };
+        this._currentOptions = {
+            pagination: { ...this._initialOptions.pagination },
+            ordering: { ...this._initialOptions.ordering },
+            search: { ...this._initialOptions.search },
+        };
+        this._dataChangedCallback = dataChangedCallback;
+        this._fetchCurrentPageData();
+    }
+    //#region SEARCH
+    /**
+     * Allows for adding any filtering criteria. Label is required to distinguish custom search categories (e.g. searchTerm, dateRange, anyCustom ...)
+     */
+    setSearchDefinition(searchDefinition) {
+        this._currentOptions.search.searchDefinition = searchDefinition;
+        this._currentOptions.pagination.pageNumber = 1; // Reset to first page
+        return this._fetchCurrentPageData();
+    }
+    //#endregion
+    //#region ORDERING
+    /**
+     * Compares two PropertyPathDto arrays for equality
+     */
+    _arePropertyPathsEqual(path1, path2) {
+        if (path1.length !== path2.length)
+            return false;
+        return path1.every((segment, index) => segment === path2[index]);
+    }
+    /**
+     * Public method for ordering the collection by property path / column name.
+     *
+     * @param propertyPath - must match camel-cased property/column name being sorted
+     * @param orderDirection - use `ReadSelectedOrderingDirection` enum choices
+     */
+    setOrdering(propertyPath, orderDirection) {
+        // Remove any existing ordering for this property path
+        this._currentOptions.ordering.orderByPaths = this._currentOptions.ordering.orderByPaths.filter(p => !this._arePropertyPathsEqual(p.orderByPath, propertyPath));
+        // Add the new ordering at the beginning
+        this._currentOptions.ordering.orderByPaths.unshift({
+            orderByPath: propertyPath,
+            orderDirection: orderDirection,
+        });
+        // Limit to maxActiveOrderingColumns
+        if (this._currentOptions.ordering.orderByPaths.length > this._currentOptions.ordering.maxActiveOrderingColumns) {
+            this._currentOptions.ordering.orderByPaths = this._currentOptions.ordering.orderByPaths.slice(0, this._currentOptions.ordering.maxActiveOrderingColumns);
+        }
+        this._currentOptions.pagination.pageNumber = 1; // Reset to first page
+        return this._fetchCurrentPageData();
+    }
+    /**
+     * Returns the property name of the current columns/properties on which ordering is applied, along with the `ReadSelectedOrderingDirection` direction
+     */
+    getCurrentOrdering() {
+        return this._currentOptions.ordering.orderByPaths;
+    }
+    //#endregion
+    //#region PAGINATION
+    /**
+     * Returns the current page's page number
+     */
+    get currentPage() {
+        return this._currentOptions.pagination.pageNumber;
+    }
+    /**
+     * Sets the current page to `pageNumber` and triggers data re-fetch
+     *
+     * @param pageNumber
+     */
+    jumpToPage(pageNumber) {
+        this._currentOptions.pagination.pageNumber = pageNumber;
+        return this._fetchCurrentPageData();
+    }
+    /**
+     * Returns the currently set page size value
+     */
+    get pageSize() {
+        return this._currentOptions.pagination.pageSize;
+    }
+    /**
+     * Page size dictates the number of items or rows being fetched in a single API call
+     *
+     * @param pageSize
+     */
+    setPageSize(pageSize) {
+        this._currentOptions.pagination.pageSize = pageSize;
+        this._currentOptions.pagination.pageNumber = 1; // Reset to first page
+        return this._fetchCurrentPageData();
+    }
+    /**
+     * Refreshes the data by re-fetching the current page
+     */
+    refreshData() {
+        return this._fetchCurrentPageData();
+    }
+    _totalItemCount = -1;
+    /**
+     * Returns the total count value of the collection.
+     *
+     * If `CollectionViewAdapterOptions` has set `pagination.useTotalItemCount` to `true`, the API will return this value along with the collection and it will be set automatically.
+     * Else this adapter will attempt to dynamically calculate this value via `_calculateTotal()`.
+     */
+    get totalItemCount() {
+        return this._totalItemCount;
+    }
+    //#endregion
+    /**
+     * Callback function invoked whenever data changes.
+     * Receives a loading state flag and the updated data collection.
+     */
+    _dataChangedCallback;
+    /**
+     * Timeout reference used to debounce calls to `_fetchCurrentPageData`.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _fetchCurrentPageDataTimeout;
+    /**
+     * Queue of pending promises waiting for `_fetchCurrentPageData` to resolve or reject.
+     */
+    _fetchCurrentPageDataPromises = [];
+    /**
+     * Tracks the current in-flight request controller to allow cancellation when a new fetch starts.
+     */
+    _currentAbortController;
+    /**
+     * Fetches the current page of data with debouncing support.
+     * Consolidates multiple concurrent calls into a single execution,
+     * resolving all queued promises with the same result.
+     *
+     * @returns A promise resolving to the fetched page of data.
+     */
+    async _fetchCurrentPageData() {
+        return new Promise((resolve, reject) => {
+            this._fetchCurrentPageDataPromises.push({ resolve, reject });
+            if (this._fetchCurrentPageDataTimeout !== undefined) {
+                clearTimeout(this._fetchCurrentPageDataTimeout);
+            }
+            this._fetchCurrentPageDataTimeout = setTimeout(async () => {
+                try {
+                    const result = await this._fetchCurrentPageDataDebounced();
+                    const promises = this._fetchCurrentPageDataPromises.splice(0, this._fetchCurrentPageDataPromises.length);
+                    for (const p of promises)
+                        p.resolve(result);
+                }
+                catch (err) {
+                    const promises = this._fetchCurrentPageDataPromises.splice(0, this._fetchCurrentPageDataPromises.length);
+                    for (const p of promises)
+                        p.reject(err);
+                }
+            }, 50);
+        });
+    }
+    /**
+     * Executes the actual data fetch operation after debounce delay.
+     * Updates the loading state, triggers data change callbacks,
+     * and handles total item count calculation if pagination is enabled.
+     *
+     * @returns A promise resolving to the fetched page of data.
+     */
+    async _fetchCurrentPageDataDebounced() {
+        this._isLoading = true;
+        this._dataChangedCallback(this._isLoading, undefined, undefined);
+        let abortController;
+        let caughtError;
+        try {
+            // Cancel any in-flight request before starting a new one
+            if (this._currentAbortController) {
+                try {
+                    this._currentAbortController.abort();
+                }
+                catch {
+                    // Ignore abort errors as they are expected when debouncing
+                }
+            }
+            abortController = new AbortController();
+            this._currentAbortController = abortController;
+            const definition = this._parseOptionsToDefinition();
+            const response = await this._readClient.readSelected(definition, abortController?.signal);
+            if (!response.ok) {
+                throw response.error;
+            }
+            this._pageData = response.result;
+            if (this._currentOptions.pagination.useTotalItemCount && response.metadata.totalCount !== undefined) {
+                this._totalItemCount = response.metadata.totalCount;
+            }
+            else {
+                const pageSize = this._currentOptions.pagination.pageSize;
+                const currentPageNumber = this._currentOptions.pagination.pageNumber;
+                const itemsOnCurrentPageCount = this._pageData.length;
+                this._totalItemCount = this._calculateTotal(pageSize, currentPageNumber, itemsOnCurrentPageCount, this._totalItemCount);
+            }
+            return this._pageData;
+        }
+        catch (error) {
+            caughtError = error;
+            // Do not log abort-related errors as they are expected when debouncing
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                return Promise.reject(error);
+            }
+            console.error('Error fetching data:', error);
+            return Promise.reject(error);
+        }
+        finally {
+            this._isLoading = false;
+            let errorName;
+            if (caughtError && !(caughtError instanceof DOMException && caughtError.name === 'AbortError')) {
+                errorName = caughtError instanceof Error ? caughtError.name : undefined;
+            }
+            this._dataChangedCallback(this._isLoading, this._pageData, errorName);
+            // Clear the abort controller only if it belongs to this request (avoid racing with a newer one)
+            if (abortController && this._currentAbortController === abortController) {
+                this._currentAbortController = undefined;
+            }
+        }
+    }
+    /**
+     * Takes current `CollectionViewAdapterOptions` and parses to `ReadSelectedDefinitionDto` which the cornerstone API expects.
+     *
+     * @returns - `ReadSelectedDefinitionDto` object
+     */
+    _parseOptionsToDefinition() {
+        const definition = {
+            paginationDefinition: {
+                skip: (this._currentOptions.pagination.pageNumber - 1) * this._currentOptions.pagination.pageSize,
+                limit: this._currentOptions.pagination.pageSize,
+            },
+        };
+        // Apply ordering
+        const orderByPaths = this._currentOptions.ordering.orderByPaths;
+        if (orderByPaths && orderByPaths.length > 0) {
+            definition.orderingDefinition = {
+                order: orderByPaths.map(orderPath => ({
+                    propertyPath: orderPath.orderByPath.map(x => toPascalCase(x)),
+                    direction: orderPath.orderDirection,
+                })),
+            };
+        }
+        // Apply search
+        definition.searchDefinition = this._currentOptions.search.searchDefinition;
+        return definition;
+    }
+    /**
+     * Calculates the total item count given pagination inputs.
+     *
+     * For example, with 10 items per page, on page 2 with 3 items, total = 13.
+     * If the total cannot be inferred (e.g., a full page is returned), the previous total is returned unchanged.
+     *
+     * @param pageSize - Number of items per page
+     * @param currentPageNumber - Current page number (1-based)
+     * @param itemsOnCurrentPageCount - Number of items in the fetched page
+     * @param previousTotal - Previous known total to preserve when indeterminate
+     * @returns The computed total item count
+     */
+    _calculateTotal(pageSize, currentPageNumber, itemsOnCurrentPageCount, previousTotal) {
+        if (itemsOnCurrentPageCount < pageSize && itemsOnCurrentPageCount !== 0) {
+            return pageSize * (currentPageNumber - 1) + itemsOnCurrentPageCount;
+        }
+        else if (itemsOnCurrentPageCount === 0 && pageSize === 0) {
+            return 0;
+        }
+        return previousTotal;
+    }
+    /**
+     * Selects or deselects an item based on its ID.
+     * @param item - The item to select or deselect.
+     */
+    toggleItemSelected(item) {
+        // if item with the same id is not already selected, add it
+        // if item with the same id is already selected, remove it
+        if (this._selectedItems.find(x => x.id === item.id)) {
+            this._selectedItems = this._selectedItems.filter(x => x.id !== item.id);
+        }
+        else {
+            this._selectedItems.push(item);
+        }
+    }
+    clearSelectedItems() {
+        this._selectedItems = [];
+    }
+    selectItems(item) {
+        if (!this._selectedItems.find(x => x.id === item.id)) {
+            this._selectedItems.push(item);
+        }
+    }
+    deselectItem(item) {
+        this._selectedItems = this._selectedItems.filter(x => x.id !== item.id);
+    }
+    /**
+     * Returns the currently selected items
+     */
+    get selectedItems() {
+        return this._selectedItems;
+    }
+    /**
+     * Checks if an item is currently selected
+     * @param item - The item to check
+     */
+    isItemSelected(item) {
+        return this._selectedItems.some(x => x.id === item.id);
+    }
+    /**
+     * Selects all items on the current page
+     */
+    selectAllItemsOnCurrentPage() {
+        for (const item of this._pageData) {
+            if (!this.isItemSelected(item)) {
+                this._selectedItems.push(item);
+            }
+        }
+    }
+    /**
+     * Deselects all items on the current page
+     */
+    deselectAllItemsOnCurrentPage() {
+        const pageItemIds = this._pageData.map(item => item.id);
+        this._selectedItems = this._selectedItems.filter(item => !pageItemIds.includes(item.id));
+    }
+    /**
+     * Checks if all items on the current page are selected
+     */
+    areAllItemsOnCurrentPageSelected() {
+        if (this._pageData.length === 0)
+            return false;
+        return this._pageData.every(item => this.isItemSelected(item));
+    }
+    /**
+     * Checks if some (but not all) items on the current page are selected
+     */
+    areSomeItemsOnCurrentPageSelected() {
+        if (this._pageData.length === 0)
+            return false;
+        const selectedCount = this._pageData.filter(item => this.isItemSelected(item)).length;
+        return selectedCount > 0 && selectedCount < this._pageData.length;
+    }
+}

package/dist/adapters/SearchAdapter/index.d.ts

@@ -0,0 +1,55 @@
+import { IIdentifiable, ReadSelectedSearchDefinitionDto } from '../../data';
+export type SearchAdapterOptions<T> = {
+    controllerName: string;
+    typesToSearch: string[];
+    multiselect: boolean;
+    searchTriggerMinLength: number;
+    searchDebounceDelay: number;
+    limitSearchToSelectedType: boolean;
+    resultsLimit: number;
+    additionalSearchDefinitions?: ReadSelectedSearchDefinitionDto<T>[];
+};
+declare class SingularEventTarget<T> {
+    private _target;
+    addEventListener(callback: EventListenerOrEventListenerObject, options?: AddEventListenerOptions | boolean): void;
+    dispatchEvent(value: T): void;
+}
+export interface IGlobalSearchable<TKey> extends IIdentifiable<TKey> {
+    type: string;
+}
+export declare class SearchAdapter<TKey, TDto extends IGlobalSearchable<TKey>> {
+    onChange: SingularEventTarget<string>;
+    private _readClient;
+    options: SearchAdapterOptions<TDto>;
+    private _isLoading;
+    private _currentAbortController?;
+    private _lastSearchedValue;
+    private _typesToSearch;
+    private _fetchResultsDataTimeout?;
+    private _fetchResultsPromises;
+    private _totalCount;
+    constructor(options: SearchAdapterOptions<TDto>);
+    get searchTriggerMinLength(): number;
+    get multiselect(): boolean;
+    get isLoading(): boolean;
+    get totalCount(): number;
+    get hasMoreRecords(): boolean;
+    private _searchText;
+    get searchText(): string;
+    set searchText(searchText: string);
+    private _searchResults;
+    get searchResults(): TDto[];
+    protected set searchResults(searchResults: TDto[]);
+    private _selectedItems;
+    get selectedItems(): TDto[];
+    set selectedItems(selectedItems: TDto[]);
+    addToSelection(item: TDto): void;
+    removeFromSelection(item: TDto): void;
+    private _emitChange;
+    private _trySearch;
+    private _fetchResults;
+    private _fetchResultsDebounced;
+    private _parseToSearchDefinition;
+    private _sortByName;
+}
+export {};