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

package/src/adapters/CollectionViewAdapter/index.ts

@@ -0,0 +1,477 @@
+import { IIdentifiable, PropertyPathDto, ReadSelectedDefinitionDto, ReadSelectedOrderingDirection, ReadSelectedSearchDefinitionDto } from '@data';
+import { toPascalCase } from '@utils';
+import { ApiReadControllerClient } from '@services';
+
+/**
+ * Used with CollectionViewAdapter, a simplified configuration object for handling reading/writing from/to ReadSelectedDefinitionDto.
+ *
+ * @template TDto The type of the collection being sorted/filtered/paginated.
+ *
+ * @property {object} pagination - Pagination configuration
+ * @property {boolean} pagination.useTotalItemCount - Used for last page related logic of the paginator.
+ * Set to true if the total count for the collection is available; false assumes the last page is not known
+ * and adapts the pagination display accordingly.
+ * @property {number} [pagination.pageSize] - Number of items/rows to be fetched for the current page.
+ * @property {number} [pagination.pageNumber] - Current page index (skips fetching `(n-1) * pageSize` items/rows).
+ *
+ * @property {object} ordering - Ordering configuration
+ * @property {string[]} [ordering.orderByPath] - Array of column/property names that are sortable.
+ * @property {ReadSelectedOrderingDirection} [ordering.orderDirection] - Enum for ascending/descending sort order.
+ *
+ * @property {object} search - Search configuration
+ * @property {(keyof TDto)[]} [search.textSearchableProperties] - Array of column/property names that are searchable where the value type is string.
+ * @property {(keyof TDto)[]} [search.numericSearchableProperties] - Array of column/property names that are searchable where the value type is number.
+ * @property {ReadSelectedSearchDefinitionDto<TDto>} [search.searchDefinition] - The search definition by which the collection will be filtered.
+ */
+export type CollectionViewAdapterOptions<TDto> = {
+  pagination: {
+    useTotalItemCount: boolean;
+    pageSize?: number;
+    pageNumber?: number;
+  };
+  ordering: {
+    maxActiveOrderingColumns: number;
+    orderByPaths: {
+      orderByPath: PropertyPathDto;
+      orderDirection: ReadSelectedOrderingDirection;
+    }[];
+  };
+  search: {
+    textSearchableProperties?: (keyof TDto)[];
+    numericSearchableProperties?: (keyof TDto)[];
+    searchDefinition?: ReadSelectedSearchDefinitionDto<TDto>;
+  };
+};
+
+/**
+ * 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<TKey, TDto extends IIdentifiable<TKey>, TDetailsDto extends IIdentifiable<TKey>> {
+  private _readClient: ApiReadControllerClient<TKey, TDto, TDetailsDto>;
+
+  private _isLoading = false;
+  private _pageData: TDto[] = [];
+  private _selectedItems: TDto[] = [];
+
+  private _defaultOptions: CollectionViewAdapterOptions<TDto> = {
+    pagination: {
+      useTotalItemCount: false,
+      pageSize: 10,
+      pageNumber: 1,
+    },
+    ordering: {
+      maxActiveOrderingColumns: 1,
+      orderByPaths: [],
+    },
+    search: {
+      textSearchableProperties: [],
+      numericSearchableProperties: [],
+    },
+  };
+
+  private _initialOptions: CollectionViewAdapterOptions<TDto>;
+  private _currentOptions: CollectionViewAdapterOptions<TDto>;
+
+  constructor(
+    controllerName: string,
+    dataChangedCallback: (isLoading: boolean, data: TDto[] | undefined, error: string | undefined) => void,
+    options?: CollectionViewAdapterOptions<TDto>,
+  ) {
+    this._readClient = new ApiReadControllerClient<TKey, TDto, TDetailsDto>(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 ...)
+   */
+  public setSearchDefinition(searchDefinition: ReadSelectedSearchDefinitionDto<TDto>) {
+    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
+   */
+  private _arePropertyPathsEqual(path1: PropertyPathDto, path2: PropertyPathDto): boolean {
+    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
+   */
+  public setOrdering(propertyPath: PropertyPathDto, orderDirection: ReadSelectedOrderingDirection) {
+    // 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
+   */
+  public getCurrentOrdering() {
+    return this._currentOptions.ordering.orderByPaths;
+  }
+  //#endregion
+
+  //#region PAGINATION
+
+  /**
+   * Returns the current page's page number
+   */
+  public get currentPage() {
+    return this._currentOptions.pagination.pageNumber;
+  }
+
+  /**
+   * Sets the current page to `pageNumber` and triggers data re-fetch
+   *
+   * @param pageNumber
+   */
+  public jumpToPage(pageNumber: number) {
+    this._currentOptions.pagination.pageNumber = pageNumber;
+    return this._fetchCurrentPageData();
+  }
+
+  /**
+   * Returns the currently set page size value
+   */
+  public 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
+   */
+  public setPageSize(pageSize: number) {
+    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
+   */
+  public refreshData() {
+    return this._fetchCurrentPageData();
+  }
+
+  private _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()`.
+   */
+  public get totalItemCount() {
+    return this._totalItemCount;
+  }
+
+  //#endregion
+
+  /**
+   * Callback function invoked whenever data changes.
+   * Receives a loading state flag and the updated data collection.
+   */
+  private readonly _dataChangedCallback!: (isLoading: boolean, data: TDto[] | undefined, errorMessage: string | undefined) => void;
+
+  /**
+   * Timeout reference used to debounce calls to `_fetchCurrentPageData`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private _fetchCurrentPageDataTimeout?: any;
+
+  /**
+   * Queue of pending promises waiting for `_fetchCurrentPageData` to resolve or reject.
+   */
+  private _fetchCurrentPageDataPromises: { resolve: (value: TDto[] | PromiseLike<TDto[]>) => void; reject: (reason?: unknown) => void }[] = [];
+
+  /**
+   * Tracks the current in-flight request controller to allow cancellation when a new fetch starts.
+   */
+  private _currentAbortController?: AbortController;
+
+  /**
+   * 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.
+   */
+  private async _fetchCurrentPageData(): Promise<TDto[]> {
+    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.
+   */
+  private async _fetchCurrentPageDataDebounced(): Promise<TDto[]> {
+    this._isLoading = true;
+    this._dataChangedCallback(this._isLoading, undefined, undefined);
+    let abortController: AbortController | undefined;
+    let caughtError: unknown;
+
+    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: unknown) {
+      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: string | undefined;
+      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
+   */
+  private _parseOptionsToDefinition(): ReadSelectedDefinitionDto<TDto> {
+    const definition: ReadSelectedDefinitionDto<TDto> = {
+      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)) as PropertyPathDto,
+          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
+   */
+  private _calculateTotal(pageSize: number, currentPageNumber: number, itemsOnCurrentPageCount: number, previousTotal: number): number {
+    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.
+   */
+  public toggleItemSelected(item: TDto) {
+    // 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);
+    }
+  }
+
+  public clearSelectedItems() {
+    this._selectedItems = [];
+  }
+
+  public selectItems(item: TDto) {
+    if (!this._selectedItems.find(x => x.id === item.id)) {
+      this._selectedItems.push(item);
+    }
+  }
+
+  public deselectItem(item: TDto) {
+    this._selectedItems = this._selectedItems.filter(x => x.id !== item.id);
+  }
+
+  /**
+   * Returns the currently selected items
+   */
+  public get selectedItems(): TDto[] {
+    return this._selectedItems;
+  }
+
+  /**
+   * Checks if an item is currently selected
+   * @param item - The item to check
+   */
+  public isItemSelected(item: TDto): boolean {
+    return this._selectedItems.some(x => x.id === item.id);
+  }
+
+  /**
+   * Selects all items on the current page
+   */
+  public selectAllItemsOnCurrentPage() {
+    for (const item of this._pageData) {
+      if (!this.isItemSelected(item)) {
+        this._selectedItems.push(item);
+      }
+    }
+  }
+
+  /**
+   * Deselects all items on the current page
+   */
+  public 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
+   */
+  public areAllItemsOnCurrentPageSelected(): boolean {
+    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
+   */
+  public areSomeItemsOnCurrentPageSelected(): boolean {
+    if (this._pageData.length === 0) return false;
+    const selectedCount = this._pageData.filter(item => this.isItemSelected(item)).length;
+    return selectedCount > 0 && selectedCount < this._pageData.length;
+  }
+}