@intellegens/cornerstone-client 0.0.9999-alpha-8 → 0.0.9999-alpha-10

package/src/adapters/CollectionViewAdapter/index.ts

@@ -0,0 +1,390 @@
+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>> {
+  private _readClient: ApiReadControllerClient<TKey, TDto>;
+
+  private _isLoading = false;
+  private _pageData: 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>(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();
+  }
+
+  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;
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1 @@
+export * from './CollectionViewAdapter';

package/src/data/api/dto/PropertyPathDto.ts

@@ -0,0 +1,4 @@
+/**
+ * Array of properties that when combined form a path to a property.
+ */
+export type PropertyPathDto = string[];

package/src/data/api/dto/ReadOptionsDto.ts

@@ -0,0 +1,8 @@
+/**
+ * Options for configuring read operations.
+ *
+ * @property {boolean} includeTotalCount - Whether to include the total count of items in the response.
+ */
+export type ReadOptionsDto = {
+  includeTotalCount: boolean;
+};

package/src/data/api/dto/ReadResultDto.ts

@@ -0,0 +1,13 @@
+import { ReadResultMetadataDto } from './ReadResultMetadataDto';
+
+/**
+ * Represents a read result containing a collection of results and metadata.
+ *
+ * @template T The type of result in the collection.
+ * @property {T[]} items - The collection of results returned.
+ * @property {ReadResultMetadata} metadata - Metadata about the paginated result.
+ */
+export type ReadResultDto<T> = {
+  results: T[];
+  metadata: ReadResultMetadataDto;
+};

package/src/data/api/dto/ReadResultMetadataDto.ts

@@ -0,0 +1,8 @@
+/**
+ * Metadata associated with a paginated read result.
+ *
+ * @property {number} [totalCount]   - The total number of items available.
+ */
+export type ReadResultMetadataDto = {
+  totalCount?: number;
+};

package/src/data/api/dto/crud/CrudMetadataDto.ts

@@ -0,0 +1,4 @@
+/**
+ * Metadata associated with a crud result.
+ */
+export type CrudMetadataDto = object;

package/src/data/api/dto/crud/index.ts

@@ -0,0 +1 @@
+export * from './CrudMetadataDto';

package/src/data/api/dto/index.ts

@@ -0,0 +1,4 @@
+export * from './response';
+export * from './read';
+export * from './crud';
+export * from './PropertyPathDto';

package/src/data/api/dto/read/ReadMetadataDto.ts

@@ -0,0 +1,8 @@
+/**
+ * Metadata associated with a read result.
+ *
+ * @property {number} [totalCount] - The total number of items available.
+ */
+export type ReadMetadataDto = {
+  totalCount?: number;
+};

package/src/data/api/dto/read/ReadSelectedDefinitionDto.ts

@@ -0,0 +1,21 @@
+import { ReadSelectedPaginationDefinitionDto, ReadSelectedOrderingDefinitionDto, ReadSelectedSearchDefinitionDto } from '@data';
+
+/**
+ * Defines the selection criteria for a controller to fetch multiple records
+ */
+export type ReadSelectedDefinitionDto<T> = {
+  /**
+   * Pagination definition
+   */
+  paginationDefinition?: ReadSelectedPaginationDefinitionDto;
+
+  /**
+   * Ordering definition
+   */
+  orderingDefinition?: ReadSelectedOrderingDefinitionDto;
+
+  /**
+   * Search definition (supports both simple search and nested logical groups)
+   */
+  searchDefinition?: ReadSelectedSearchDefinitionDto<T>;
+};

package/src/data/api/dto/read/ReadSelectedNestedCollectionCriteriaDto.ts

@@ -0,0 +1,25 @@
+import { ReadSelectedCollectionOperator, ReadSelectedSearchDefinitionDto } from '@data';
+
+/**
+ * Defines criteria for searching within a collection navigation property using quantifiers (Any/All).
+ *
+ * This DTO allows navigation into a collection property and applying search criteria
+ * with a quantifier to determine if any or all elements match.
+ */
+export type ReadSelectedNestedCollectionCriteriaDto<T, TPropertyName extends keyof T> = {
+  /**
+   * The name of the collection navigation property to navigate into.
+   */
+  propertyName: TPropertyName;
+
+  /**
+   * The quantifier operator determining whether any or all elements must match.
+   */
+  collectionOperator: ReadSelectedCollectionOperator;
+
+  /**
+   * The search criteria to apply to elements in the collection.
+   * Type should be ReadSelectedSearchDefinitionDto of the collection element type.
+   */
+  criteria: ReadSelectedSearchDefinitionDto<unknown>;
+};

package/src/data/api/dto/read/ReadSelectedNestedCriteriaDto.ts

@@ -0,0 +1,20 @@
+import {ReadSelectedSearchDefinitionDto} from '@data';
+
+/**
+ * Defines criteria for searching within a nested object property.
+ *
+ * This DTO allows navigation into a nested object property and applying search criteria
+ * to that nested object. The property name must refer to a navigation property (not a collection).
+ */
+export type ReadSelectedNestedCriteriaDto<T, TPropertyName extends keyof T> = {
+    /**
+     * The name of the navigation property to navigate into.
+     */
+    propertyName: TPropertyName;
+
+    /**
+     * The search criteria to apply to the nested object.
+     * Type should be ReadSelectedSearchDefinitionDto of the nested object type.
+     */
+    criteria: ReadSelectedSearchDefinitionDto<unknown>;
+};

package/src/data/api/dto/read/ReadSelectedOrderingDefinitionDto.ts

@@ -0,0 +1,8 @@
+import { ReadSelectedOrderingPropertyDefinitionDto } from '@data';
+
+/**
+ * Represents the ordering definition for a controller.
+ */
+export type ReadSelectedOrderingDefinitionDto = {
+  order: ReadSelectedOrderingPropertyDefinitionDto[];
+};

package/src/data/api/dto/read/ReadSelectedOrderingPropertyDefinitionDto.ts

@@ -0,0 +1,16 @@
+import { PropertyPathDto, ReadSelectedOrderingDirection } from '@data';
+
+/**
+ * Defines the ordering property for a controller.
+ */
+export type ReadSelectedOrderingPropertyDefinitionDto = {
+  /**
+   * Gets or sets the property path.
+   */
+  propertyPath: PropertyPathDto;
+
+  /**
+   * Gets or sets the ordering direction.
+   */
+  direction: ReadSelectedOrderingDirection;
+};

package/src/data/api/dto/read/ReadSelectedPaginationDefinitionDto.ts

@@ -0,0 +1,13 @@
+/**
+ * Defines the pagination parameters for a controller.
+ */
+export type ReadSelectedPaginationDefinitionDto = {
+  /**
+   * Pagination offset
+   */
+  skip: number;
+  /**
+   * Pagination limit
+   */
+  limit: number;
+};

package/src/data/api/dto/read/ReadSelectedSearchDefinitionDto.ts

@@ -0,0 +1,43 @@
+import {
+    ReadSelectedLogicalOperator,
+    ReadSelectedNestedCollectionCriteriaDto,
+    ReadSelectedNestedCriteriaDto,
+    ReadSelectedSearchPropertyDefinitionDto,
+} from '@data';
+
+/**
+ * Defines the search criteria for a controller using a recursive structure.
+ *
+ * This DTO supports complex search queries with:
+ * - Logical operators (AND/OR) to combine multiple criteria
+ * - Direct property value comparisons via `propertyCriteria`
+ * - Nested searches via `searches` for recursive query composition
+ * - Navigation into nested objects via `nestedCriteria`
+ * - Collection quantifier queries (Any/All) via `nestedCollectionCriteria`
+ */
+export type ReadSelectedSearchDefinitionDto<T> = {
+    /**
+     * The logical operator to combine all criteria at this level.
+     */
+    logicalOperator: ReadSelectedLogicalOperator;
+
+    /**
+     * Recursive nested search definitions combined with the logical operator.
+     */
+    searches?: ReadSelectedSearchDefinitionDto<T>[];
+
+    /**
+     * Direct property value comparison criteria.
+     */
+    propertyCriteria?: ReadSelectedSearchPropertyDefinitionDto<T, keyof T>[];
+
+    /**
+     * Criteria for searching within nested object properties.
+     */
+    nestedCriteria?: ReadSelectedNestedCriteriaDto<T, keyof T>[];
+
+    /**
+     * Criteria for searching within collection properties using Any/All quantifiers.
+     */
+    nestedCollectionCriteria?: ReadSelectedNestedCollectionCriteriaDto<T, keyof T>[];
+};