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

package/src/adapters/SearchAdapter/index.ts

@@ -0,0 +1,302 @@
+import {
+  IIdentifiable,
+  ReadSelectedComparisonOperator,
+  ReadSelectedDefinitionDto,
+  ReadSelectedLogicalOperator,
+  ReadSelectedOrderingDirection,
+  ReadSelectedPropertyType,
+  ReadSelectedSearchDefinitionDto,
+  ReadSelectedSearchPropertyDefinitionDto,
+} from '@data';
+import { ApiReadControllerClient } from '@services';
+
+export type SearchAdapterOptions<T> = {
+  controllerName: string;
+  typesToSearch: string[]; // provide known searchable types
+  multiselect: boolean;
+  searchTriggerMinLength: number;
+  searchDebounceDelay: number;
+  limitSearchToSelectedType: boolean; // when item is selected, limit results to items of same type
+  resultsLimit: number;
+  additionalSearchDefinitions?: ReadSelectedSearchDefinitionDto<T>[];
+};
+
+class SingularEventTarget<T> {
+  private _target = new EventTarget();
+
+  public addEventListener(callback: EventListenerOrEventListenerObject, options?: AddEventListenerOptions | boolean): void {
+    this._target.addEventListener('change', callback, options);
+  }
+
+  public dispatchEvent(value: T) {
+    this._target.dispatchEvent(new CustomEvent('change', { detail: value }));
+  }
+}
+
+export interface IGlobalSearchable<TKey> extends IIdentifiable<TKey> {
+  type: string;
+}
+
+export class SearchAdapter<TKey, TDto extends IGlobalSearchable<TKey>> {
+  public onChange = new SingularEventTarget<string>();
+  // inputs
+  private _readClient!: ApiReadControllerClient<TKey, TDto, TDto>;
+  public options!: SearchAdapterOptions<TDto>;
+  private _isLoading = false;
+  private _currentAbortController?: AbortController;
+  private _lastSearchedValue: string | undefined = undefined;
+  private _typesToSearch: string[] = [];
+  private _fetchResultsDataTimeout?: any;
+  private _fetchResultsPromises: {
+    resolve: (value: TDto[] | PromiseLike<TDto[]>) => void;
+    reject: (reason?: unknown) => void;
+  }[] = [];
+  private _totalCount = 0;
+
+  constructor(options: SearchAdapterOptions<TDto>) {
+    this.options = options;
+    this._readClient = new ApiReadControllerClient<TKey, TDto, TDto>(options.controllerName);
+  }
+
+  public get searchTriggerMinLength() {
+    return this.options.searchTriggerMinLength;
+  }
+
+  public get multiselect() {
+    return this.options.multiselect;
+  }
+
+  public get isLoading() {
+    return this._isLoading;
+  }
+
+  public get totalCount() {
+    return this._totalCount;
+  }
+
+  public get hasMoreRecords() {
+    return this._totalCount > this._searchResults.length;
+  }
+
+  private _searchText: string = '';
+
+  public get searchText() {
+    return this._searchText;
+  }
+
+  public set searchText(searchText: string) {
+    this._searchText = searchText;
+    this._trySearch();
+    this._emitChange();
+  }
+
+  private _searchResults: TDto[] = [];
+
+  public get searchResults() {
+    return this._searchResults;
+  }
+
+  protected set searchResults(searchResults: TDto[]) {
+    this._searchResults = [...searchResults];
+    this._emitChange();
+  }
+
+  private _selectedItems: TDto[] = [];
+
+  public get selectedItems() {
+    return this._selectedItems;
+  }
+
+  public set selectedItems(selectedItems: TDto[]) {
+    this._selectedItems = [...selectedItems];
+    this._emitChange();
+  }
+
+  public addToSelection(item: TDto): void {
+    if (!this._selectedItems) {
+      this.selectedItems = [];
+    }
+
+    // selection mode
+    if (this.options.multiselect) {
+      if (!this._selectedItems.find(s => s.id === item.id)) {
+        this.selectedItems = [...this.selectedItems, item];
+      }
+    } else {
+      // single-select mode - replace the item and return the old one to shown results
+      if (this._selectedItems.length > 0) {
+        this.searchResults = this._sortByName([...this._searchResults, ...this._selectedItems]); // return the to-be-replaced selected item back to shown results list
+      }
+      this.selectedItems = [item];
+    }
+    this.searchResults = this._sortByName(this._searchResults.filter(d => d.id !== item.id)); // remove the new selection from the shown results
+  }
+
+  public removeFromSelection(item: TDto): void {
+    if (!this._selectedItems) {
+      this.selectedItems = [];
+      return;
+    }
+
+    this.selectedItems = this._selectedItems.filter(s => s.id !== item.id);
+    this.searchResults = this._sortByName([...this._searchResults, item]);
+  }
+
+  private _emitChange() {
+    this.onChange.dispatchEvent('onChange');
+  }
+
+  private async _trySearch() {
+    const options = this.options;
+
+    this.searchResults = [];
+    if (this._searchText.length < options.searchTriggerMinLength) return;
+    if (this._searchText === this._lastSearchedValue) return;
+    this._lastSearchedValue = this._searchText;
+
+    this._typesToSearch =
+      options.limitSearchToSelectedType && this._selectedItems.length ? [(this._selectedItems[0] as TDto).type] : this.options.typesToSearch;
+
+    this.searchResults = this._sortByName(await this._fetchResults(options.searchDebounceDelay));
+  }
+
+  private async _fetchResults(debounceDelay: number): Promise<TDto[]> {
+    this._isLoading = true;
+
+    return new Promise((resolve, reject) => {
+      this._fetchResultsPromises.push({ resolve, reject });
+      if (this._fetchResultsDataTimeout !== undefined) {
+        clearTimeout(this._fetchResultsDataTimeout);
+      }
+      this._fetchResultsDataTimeout = setTimeout(async () => {
+        try {
+          const result = await this._fetchResultsDebounced();
+          const promises = this._fetchResultsPromises.splice(0, this._fetchResultsPromises.length);
+          for (const p of promises) p.resolve(result);
+        } catch (err) {
+          const promises = this._fetchResultsPromises.splice(0, this._fetchResultsPromises.length);
+          for (const p of promises) p.reject(err);
+        }
+      }, debounceDelay);
+    });
+  }
+
+  private async _fetchResultsDebounced(): Promise<TDto[]> {
+    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._parseToSearchDefinition();
+      const response = await this._readClient.readSelected(definition, abortController?.signal);
+
+      if (!response.ok) {
+        throw response.error;
+      }
+
+      // Update total count from response metadata
+      this._totalCount = response.metadata?.totalCount ?? response.result.length;
+
+      // Filter out selected items from new results
+      const selectedIds = new Set((this.selectedItems || []).map(item => item.id));
+      return response.result.filter(item => !selectedIds.has(item.id));
+    } 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;
+      }
+
+      // 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;
+      }
+    }
+  }
+
+  private _parseToSearchDefinition(): ReadSelectedDefinitionDto<TDto> {
+    const definition: ReadSelectedDefinitionDto<TDto> = {
+      paginationDefinition: {
+        skip: 0,
+        limit: this.options.resultsLimit,
+      },
+    };
+
+    // Apply ordering
+    definition.orderingDefinition = {
+      order: [
+        {
+          propertyPath: ['Name'],
+          direction: ReadSelectedOrderingDirection.Ascending,
+        },
+      ],
+    };
+
+    // Apply search
+    const propertyCriteria: ReadSelectedSearchPropertyDefinitionDto<TDto, keyof TDto>[] = [
+      {
+        propertyName: 'Name' as any,
+        comparisonOperator: ReadSelectedComparisonOperator.IContains,
+        valueType: ReadSelectedPropertyType.String,
+        value: this._searchText,
+      },
+    ];
+
+    definition.searchDefinition = {
+      logicalOperator: ReadSelectedLogicalOperator.And,
+      propertyCriteria: propertyCriteria,
+    } as ReadSelectedSearchDefinitionDto<TDto>;
+
+    if (this._typesToSearch !== undefined && this._typesToSearch.length > 0) {
+      definition.searchDefinition.searches = [
+        {
+          logicalOperator: ReadSelectedLogicalOperator.Or,
+          propertyCriteria: this._typesToSearch.map(
+            type =>
+              ({
+                propertyName: 'Type',
+                comparisonOperator: ReadSelectedComparisonOperator.IEqual,
+                valueType: ReadSelectedPropertyType.String,
+                value: type,
+              }) as ReadSelectedSearchPropertyDefinitionDto<TDto, keyof TDto>,
+          ),
+        },
+      ];
+    }
+
+    if (this.options.additionalSearchDefinitions && this.options.additionalSearchDefinitions.length > 0) {
+      definition.searchDefinition.searches = [...(definition.searchDefinition.searches ?? []), ...this.options.additionalSearchDefinitions];
+    }
+
+    return definition;
+  }
+
+  private _sortByName(array: TDto[]): TDto[] {
+    return array.sort((a, b) => {
+      const nameA = (a as any).name?.toLowerCase() || '';
+      const nameB = (b as any).name?.toLowerCase() || '';
+      return nameA.localeCompare(nameB);
+    });
+  }
+}

package/src/adapters/index.ts

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

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;
+};