@api-client/ui 0.5.58 → 0.6.0

package/src/core/Model.ts

@@ -1,58 +1,4 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
-
-import type { Exception } from '@api-client/core/exceptions/exception.js'
-
-/**
- * Defines the options for the retry mechanism.
- */
-export interface RetryOptions {
-  /**
-   * The maximum number of retry attempts.
-   * Defaults to 3.
-   */
-  retries?: number
-  /**
-   * The delay in milliseconds before the next retry.
-   * Can be a fixed number or a function that returns a number (e.g., for exponential backoff).
-   * Defaults to 1000ms.
-   */
-  delayMs?: number | ((attempt: number) => number)
-  /**
-   * An optional function that determines if a retry should be attempted based on the error.
-   * If not provided, all errors will trigger a retry up to the maximum number of retries.
-   * @param error The error that occurred.
-   * @returns True if a retry should be attempted, false otherwise.
-   */
-  shouldRetry?: (error: Error) => boolean
-}
-
-/**
- * Calculates an exponential backoff delay for retry attempts.
- * The delay doubles with each attempt.
- *
- * @param attempt The current retry attempt number (should be 1-indexed).
- * @param initialDelay The initial delay in milliseconds. Defaults to 1000ms.
- * @returns The calculated delay in milliseconds.
- */
-export function exponentialBackoffDelay(attempt: number, initialDelay = 1000): number {
-  if (attempt <= 0) return initialDelay
-  // For attempt 1, delay is initialDelay * 2^0 = initialDelay
-  return initialDelay * Math.pow(2, attempt - 1)
-}
-/**
- * Checks if the API error should be retried based on its status code.
- * If the status code is 404, it returns false (do not retry).
- * For other status codes, it returns true (retry).
- * @param error The error to check.
- */
-export function shouldRetryApiError(error: Exception): boolean {
-  const { status } = error
-  if (status === 404) {
-    // Do not retry on 404 errors
-    return false
-  }
-  return true
-}
 /**
  * The base class for models.
  *
@@ -61,6 +7,11 @@ export function shouldRetryApiError(error: Exception): boolean {
  *
  * The application should use these models in order to centralize object manipulation.
  *
+ * Note that the preferred way to get data from the model is through calling the `debounce` method.
+ * This ensures that multiple changes to the model properties will result in a single query after
+ * the `debounceTimeout` period. If you are not plannig to use the debouncer, make sure to call the
+ * `resolveTaskPromise` method after the operation completes to properly manage the `taskComplete` promise.
+ *
  * @template T The underlying domain model.
  */
 export abstract class Model<T> extends EventTarget {
@@ -85,6 +36,11 @@ export abstract class Model<T> extends EventTarget {
    */
   debouncerValue?: number | NodeJS.Timeout
 
+  /**
+   * Map of debounce timers keyed by argument signature for parameter-aware debouncing.
+   */
+  #debouncedTimers = new Map<string, number | NodeJS.Timeout>()
+
   /**
    * Default limit for list queries.
    */
@@ -119,6 +75,11 @@ export abstract class Model<T> extends EventTarget {
     return this.raw
   }
 
+  /**
+   * The number of retry attempts for operations.
+   */
+  retryCount = 3
+
   /**
    * @param obj The source object to use.
    */
@@ -141,25 +102,55 @@ export abstract class Model<T> extends EventTarget {
     throw new Error(`Not implemented.`)
   }
 
-  debounce(callback: (...args: unknown[]) => unknown): void {
-    if (this.debouncerValue) {
-      clearTimeout(this.debouncerValue)
+  /**
+   * Debounces the given callback for the `debounceTimeout` period.
+   * Multiple calls with the same arguments will reset the timeout for that argument set.
+   * Calls with different arguments will each have their own debounce timer.
+   * Only the last call for each unique set of arguments is executed.
+   * @param callback The function to execute.
+   * @param args Optional arguments to pass to the callback and use for debounce comparison.
+   */
+  debounce(callback: (...args: unknown[]) => unknown, ...args: unknown[]): void {
+    const argsKey = this.#getArgsKey(args)
+
+    // Clear the existing timer for this argument set if it exists
+    const existingTimer = this.#debouncedTimers.get(argsKey)
+    if (existingTimer) {
+      clearTimeout(existingTimer)
     }
+
+    // Set up a new promise if there isn't one
     if (!this.#hasPendingTaskPromise) {
       this.#setUpdatePromise()
     }
-    this.debouncerValue = setTimeout(async () => {
-      this.debouncerValue = undefined
+
+    // Create a new timer for this argument set
+    const timer = setTimeout(async () => {
+      this.#debouncedTimers.delete(argsKey)
       try {
-        await callback.call(this)
+        await callback.call(this, ...args)
       } catch (e) {
         const err = e as Error
         this.notifyError(err)
-        throw err
+        // I don't think we want to re-throw here as it would be unhandled
+        // throw err
       } finally {
         this.resolveTaskPromise()
       }
     }, this.debounceTimeout)
+
+    this.#debouncedTimers.set(argsKey, timer)
+  }
+
+  /**
+   * Converts arguments array to a JSON string key for use in the debounce timer map.
+   */
+  #getArgsKey(args: unknown[]): string {
+    try {
+      return JSON.stringify(args)
+    } catch {
+      return 'error'
+    }
   }
 
   notifyError(error: Error): void {
@@ -183,66 +174,9 @@ export abstract class Model<T> extends EventTarget {
     }
     this.#hasPendingTaskPromise = false
     const resolver = this.#taskResolver
+    this.#taskResolver = undefined
     if (resolver) {
       resolver()
     }
   }
-
-  /**
-   * Executes an asynchronous operation with a retry mechanism.
-   * @param operation A function that returns a Promise to be executed.
-   * @param options Optional retry configurations.
-   * @returns A Promise that resolves with the result of the operation or rejects if all retries fail.
-   * @example
-   * ```typescript
-   * override async create(data: Partial<IUser>): Promise<IUser> {
-   *   const operation = async (): Promise<UserData> => {
-   *     // ... perform API call to create user
-   *   }
-   *   const retryOptions: RetryOptions = {
-   *     retries: 5,
-   *     delayMs: exponentialBackoffDelay,
-   *     shouldRetry: shouldRetryApiError,
-   *   }
-   *   this.raw = await this.retry(operation)
-   *   this.dispatchEvent(new CustomEvent('data-changed', { detail: this.raw }))
-   *   return this.raw;
-   * }
-   * ```
-   */
-  protected async retry<R>(operation: () => Promise<R>, options: RetryOptions = {}): Promise<R> {
-    const { retries = 3, delayMs = 1000, shouldRetry = () => true } = options
-
-    let lastError: Error | undefined
-
-    for (let attempt = 0; attempt < retries; attempt++) {
-      try {
-        return await operation()
-      } catch (e) {
-        lastError = e as Error
-        if (!shouldRetry(lastError) || attempt === retries - 1) {
-          // Do not retry if shouldRetry returns false or if it's the last attempt
-          this.notifyError(lastError)
-          throw lastError
-        }
-
-        const delay = typeof delayMs === 'function' ? delayMs(attempt + 1) : delayMs
-        if (delay > 0) {
-          await new Promise((resolve) => setTimeout(resolve, delay))
-        }
-      }
-    }
-    // This part should ideally not be reached if retries > 0,
-    // as the loop would throw on the last attempt.
-    // However, to satisfy TypeScript and guard against retries = 0:
-    if (lastError) {
-      this.notifyError(lastError)
-      throw lastError
-    }
-    // Should not happen if operation is called at least once.
-    // Adding a generic error for completeness.
-    const err = new Error('Retry operation failed without a specific error.')
-    this.notifyError(err)
-    throw err
-  }
 }

package/src/core/ServiceManager.ts

@@ -44,5 +44,6 @@ export class ServiceManager<KnownBindings extends Record<string, Service>> {
       await service.stop()
       await service.destroy()
     }
+    this.#bindings = new Map()
   }
 }

package/src/data/BreadcrumbsModel.ts

@@ -0,0 +1,85 @@
+import type { FileBreadcrumb } from '@api-client/core/models/store/File.js'
+import { Model } from '../core/Model.js'
+import { exponentialBackoffDelay, type RetryOptions, shouldRetryApiError, retry } from './retry_logic.js'
+import { fromError } from '../exceptions/builder.js'
+import { LiveData } from '../reactive/LiveData.js'
+import type SdkService from '../services/SdkService.js'
+import { ContextListResult } from '@api-client/core/events/BaseEvents.js'
+
+export enum ModelState {
+  /**
+   * Not doing anything.
+   */
+  idle,
+  /**
+   * Currently querying for breadcrumb data.
+   */
+  reading,
+}
+
+export default class BreadcrumbsModel extends Model<FileBreadcrumb[]> {
+  /**
+   * The current state of the model.
+   */
+  state: ModelState = ModelState.idle
+
+  /**
+   * The current breadcrumbs
+   */
+  breadcrumbs: LiveData<FileBreadcrumb[]> = new LiveData<FileBreadcrumb[]>([])
+
+  /**
+   * A reference to the SDK service used to perform API calls.
+   */
+  sdk: SdkService
+
+  /**
+   * The current Organization ID.
+   */
+  oid: string
+
+  constructor(sdk: SdkService, oid: string) {
+    super()
+    this.sdk = sdk
+    this.oid = oid
+  }
+
+  reset(): void {
+    this.state = ModelState.idle
+    this.breadcrumbs.set([])
+  }
+
+  async scheduleQuery(parent?: string): Promise<void> {
+    this.debounce(() => this.#query(parent), parent)
+    await this.taskComplete
+  }
+
+  async #query(parent?: string): Promise<void> {
+    if (this.state !== ModelState.idle) {
+      // This should not happen due to debouncing, but just in case
+      return
+    }
+    if (!parent) {
+      this.breadcrumbs.set([])
+      return
+    }
+    this.state = ModelState.reading
+    const operation = async (): Promise<ContextListResult<FileBreadcrumb>> => {
+      return this.sdk.file.breadcrumbs(this.oid, parent)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      const br = await retry(operation, retryOptions)
+      this.breadcrumbs.set(br.items)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+    } finally {
+      this.state = ModelState.idle
+    }
+  }
+}

package/src/data/DataCatalogModel.ts

@@ -0,0 +1,199 @@
+import type { AtomicFilter, ContextListResult } from '@api-client/core/events/BaseEvents.js'
+import type { DataCatalogListOptions } from '@api-client/core/sdk/DataCatalogSdk.js'
+import type { DataCatalogScope, DataCatalogSchemaWithVersion } from '@api-client/core/models/DataCatalog.js'
+import type { DataCatalogLifecycle } from '@api-client/core/models/DataCatalogVersion.js'
+import { Model } from '../core/Model.js'
+import { exponentialBackoffDelay, type RetryOptions, shouldRetryApiError, retry } from './retry_logic.js'
+import { fromError } from '../exceptions/builder.js'
+import services from '../services/api_service.js'
+import { LiveData } from '../reactive/LiveData.js'
+import type SdkService from '../services/SdkService.js'
+
+export enum ModelState {
+  /**
+   * Not doing anything.
+   */
+  idle,
+  /**
+   * Currently querying for file data.
+   */
+  reading,
+  /**
+   * Data was received and the result yielded no results or less than the limit.
+   */
+  ended,
+}
+
+export class DataCatalogModel extends Model<LiveData<DataCatalogSchemaWithVersion[]>> {
+  /**
+   * The current state of the model.
+   */
+  state: ModelState = ModelState.idle
+  /**
+   * The pagination cursor for files to use with the next query.
+   */
+  cursor?: string
+
+  /**
+   * Optional organization ID to filter the data catalog by.
+   */
+  oid?: string
+
+  /**
+   * The SDK service instance.
+   */
+  sdk: SdkService
+
+  /**
+   * When set, the model will only return files that match this query.
+   */
+  #query?: string
+
+  get query(): string | undefined {
+    return this.#query
+  }
+
+  set query(value: string | undefined) {
+    if (this.#query === value) {
+      return
+    }
+    this.#query = value
+    this.resetPageState()
+  }
+
+  #scope: DataCatalogScope = 'public'
+
+  get scope(): DataCatalogScope {
+    return this.#scope
+  }
+
+  set scope(value: DataCatalogScope) {
+    if (this.#scope === value) {
+      return
+    }
+    this.#scope = value
+    this.resetPageState()
+  }
+
+  #sort?: 'lifecycle' | 'updated_at' | 'published_at'
+
+  get sort(): 'lifecycle' | 'updated_at' | 'published_at' | undefined {
+    return this.#sort
+  }
+
+  set sort(value: 'lifecycle' | 'updated_at' | 'published_at' | undefined) {
+    if (this.#sort === value) {
+      return
+    }
+    this.#sort = value
+    this.resetPageState()
+  }
+
+  #lifecycle: DataCatalogLifecycle = 'stable'
+
+  get lifecycle(): DataCatalogLifecycle {
+    return this.#lifecycle
+  }
+
+  set lifecycle(value: DataCatalogLifecycle) {
+    if (this.#lifecycle === value) {
+      return
+    }
+    this.#lifecycle = value
+    this.resetPageState()
+  }
+
+  override get value(): LiveData<DataCatalogSchemaWithVersion[]> {
+    return this.raw as LiveData<DataCatalogSchemaWithVersion[]>
+  }
+
+  constructor(sdk: SdkService, oid?: string) {
+    super()
+    this.oid = oid
+    this.sdk = sdk
+    this.raw = new LiveData<DataCatalogSchemaWithVersion[]>([])
+  }
+
+  resetPageState(): void {
+    this.cursor = undefined
+    this.state = ModelState.idle
+    this.value.set([])
+  }
+
+  async scheduleQuery(): Promise<void> {
+    this.debounce(this.#runQuery)
+    await this.taskComplete
+  }
+
+  async #runQuery(): Promise<void> {
+    if (this.state !== ModelState.idle) {
+      return
+    }
+    this.state = ModelState.reading
+    try {
+      const result = await this.#listFiles()
+      this.#processResults(result)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      this.state = ModelState.idle
+    }
+    this.dispatchEvent(new Event('querycomplete'))
+  }
+
+  async #listFiles(): Promise<ContextListResult<DataCatalogSchemaWithVersion>> {
+    const sdk = await services.get('sdk')
+    const operation = async (): Promise<ContextListResult<DataCatalogSchemaWithVersion>> => {
+      const opts = this.getPageQueryOptions()
+      return sdk.dataCatalog.list(opts)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError,
+    }
+    return retry(operation, retryOptions)
+  }
+
+  getPageQueryOptions(): DataCatalogListOptions {
+    const result: DataCatalogListOptions = {
+      cursor: this.cursor,
+      limit: this.limit,
+      oid: this.oid,
+      scope: this.scope,
+    }
+    if (this.sort) {
+      result.sort = this.sort
+    }
+    const { lifecycle, query } = this
+    const filters: AtomicFilter[] = []
+    if (query) {
+      filters.push({ field: 'name', value: query, operator: 'con' })
+    }
+    if (lifecycle) {
+      filters.push({ field: 'lifecycle', value: lifecycle, operator: 'eq' })
+    }
+    if (filters.length === 1) {
+      result.filter = filters[0]
+    } else if (filters.length > 1) {
+      result.filter = {
+        op: 'AND',
+        filters,
+      }
+    }
+    return result
+  }
+
+  #processResults(result: ContextListResult<DataCatalogSchemaWithVersion>): void {
+    const { items, cursor } = result
+    if (cursor) {
+      this.cursor = cursor
+    }
+    if (!items.length) {
+      this.state = ModelState.ended
+      return
+    }
+    this.value.set(this.value.value.concat(items))
+    this.state = ModelState.idle
+  }
+}

package/src/data/DomainBrowserModel.ts

@@ -0,0 +1,118 @@
+import { Model } from '../core/Model.js'
+import { bound } from '../decorators/bound.js'
+import { DomainEntityKind, DomainModelKind, DomainNamespaceKind } from '@api-client/core/models/kinds.js'
+import type {
+  DomainBrowseRecentItem,
+  DomainBrowseRecentItems,
+  DomainBrowserPickItem,
+  DomainRenameEventDetail,
+} from '../modeling/types.js'
+import type ConfigurationService from '../services/ConfigurationService.js'
+
+export const RECENT_ITEMS_KEY = 'com.api-client.schema.recent.items'
+export const RECENT_ITEMS_MAX = 10
+
+/**
+ * Model for browsing domain entities, models, and namespaces.
+ * Has the logic related to storing "recently browsed items" in the local storage.
+ */
+export class DomainBrowserModel extends Model<string[]> {
+  /**
+   * The key of the domain that is currently being browsed.
+   * This is used to filter the recent items to only those that belong to the current domain.
+   * If the domain is not set, it means that the recent items are not filtered by the domain.
+   */
+  public domainKey?: string
+
+  /**
+   * The key of the recent items list that is used to store the recent items in the local storage.
+   */
+  get key(): string {
+    const { domainKey } = this
+    if (!domainKey) {
+      throw new Error('Domain key is not set. Please set the domain key before using the model.')
+    }
+    return `${RECENT_ITEMS_KEY}.${domainKey}`
+  }
+
+  config: ConfigurationService
+
+  constructor(config: ConfigurationService) {
+    super()
+    this.config = config
+  }
+
+  @bound
+  handleEntityRename(e: Event): void {
+    const event = e as CustomEvent<DomainRenameEventDetail>
+    const { key, label, namespace, kind } = event.detail
+    // Update the recent items when an entity is renamed
+    this.updateRecentItem(key, label, namespace, kind)
+  }
+
+  async read(): Promise<DomainBrowseRecentItems> {
+    if (!this.domainKey) {
+      return { items: [], updated: Date.now() }
+    }
+    const recent = (await this.config.local.get(this.key)) as DomainBrowseRecentItems | undefined
+    if (!recent) {
+      return { items: [], updated: Date.now() }
+    }
+    return recent
+  }
+
+  filterRecentItems(items: DomainBrowseRecentItem[], allowed: DomainBrowserPickItem[]): DomainBrowseRecentItem[] {
+    if (allowed.length) {
+      return items.filter((item) => {
+        if (item.kind === DomainEntityKind && allowed.includes(DomainEntityKind)) {
+          return true
+        }
+        if (item.kind === DomainModelKind && allowed.includes(DomainModelKind)) {
+          return true
+        }
+        if (item.kind === DomainNamespaceKind && allowed.includes(DomainNamespaceKind)) {
+          return true
+        }
+        return false
+      })
+    }
+    return items
+  }
+
+  sort(a: DomainBrowseRecentItem, b: DomainBrowseRecentItem): number {
+    return b.used - a.used
+  }
+
+  async addRecentItem(item: DomainBrowseRecentItem): Promise<DomainBrowseRecentItems> {
+    const recent = await this.read()
+    if (!recent) {
+      const newRecent: DomainBrowseRecentItems = {
+        items: [item],
+        updated: Date.now(),
+      }
+      await this.config.local.set(this.key, newRecent)
+      return newRecent
+    }
+    const existingIndex = recent.items.findIndex((i) => i.key === item.key)
+    if (existingIndex !== -1) {
+      recent.items.splice(existingIndex, 1)
+    }
+    recent.items.unshift(item)
+    if (recent.items.length > RECENT_ITEMS_MAX) {
+      recent.items.pop()
+    }
+    recent.updated = Date.now()
+    await this.config.local.set(this.key, recent)
+    return recent
+  }
+
+  async updateRecentItem(key: string, label: string, domain: string, kind: string): Promise<void> {
+    const recent = await this.read()
+    const item = recent.items.find((i) => i.key === key && i.domain === domain && i.kind === kind)
+    if (!item) {
+      return
+    }
+    item.label = label
+    await this.config.local.set(this.key, recent)
+  }
+}

package/src/data/FileModel.ts

@@ -0,0 +1,76 @@
+import { type IFile } from '@api-client/core/models/store/File.js'
+import { Model } from '../core/Model.js'
+import { exponentialBackoffDelay, type RetryOptions, shouldRetryApiError, retry } from './retry_logic.js'
+import { fromError } from '../exceptions/builder.js'
+import { LiveData } from '../reactive/LiveData.js'
+import type SdkService from '../services/SdkService.js'
+
+export enum ModelState {
+  /**
+   * Not doing anything.
+   */
+  idle,
+  /**
+   * Currently querying for file data.
+   */
+  reading,
+  /**
+   * Data was received and the result yielded no results or less than the limit.
+   */
+  ended,
+}
+
+export default class FileModel extends Model<LiveData<IFile>> {
+  /**
+   * The current state of the model.
+   */
+  state: ModelState = ModelState.idle
+
+  /**
+   * A reference to the SDK service used to perform API calls.
+   */
+  sdk: SdkService
+
+  /**
+   * The current Organization ID.
+   */
+  oid: string
+
+  constructor(sdk: SdkService, oid: string) {
+    super()
+    this.sdk = sdk
+    this.oid = oid
+  }
+
+  async read(key: string): Promise<LiveData<IFile>> {
+    this.debounce(this.#read.bind(this, key), key)
+    await this.taskComplete
+    return this.value as LiveData<IFile>
+  }
+
+  async #read(key: string): Promise<void> {
+    if (this.state !== ModelState.idle) {
+      return
+    }
+    this.state = ModelState.reading
+    const retryOptions: RetryOptions = {
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError,
+      retries: this.retryCount,
+    }
+    const operation = async (): Promise<IFile> => {
+      return this.sdk.file.read(this.oid, key)
+    }
+    try {
+      const result = await retry(operation, retryOptions)
+      this.raw = new LiveData(result)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      throw err
+    } finally {
+      this.state = ModelState.idle
+    }
+    this.dispatchEvent(new Event('querycomplete'))
+  }
+}