@api-client/ui 0.5.57 → 0.6.0

package/src/data/PatchableFileModel.ts

@@ -0,0 +1,293 @@
+import { Operation } from '@api-client/json/types.js'
+import diff from '@api-client/json/patch/diff.js'
+import apply from '@api-client/json/patch/apply.js'
+import { rebase } from '@api-client/json/patch/rebase.js'
+import { nanoid } from 'nanoid'
+import { Model } from '../core/Model.js'
+import type SdkService from '../services/SdkService.js'
+import type { MediaPatchInfo, MediaPatchRevision } from '@api-client/core/patch/types.js'
+import type { DependentModelSchema } from '@api-client/core/modeling/DependentModel.js'
+
+enum ModelState {
+  /**
+   * Not doing anything.
+   */
+  idle,
+  /**
+   * Currently querying for file data.
+   */
+  reading,
+  /**
+   * Data received and the result yielded no results or less than the limit.
+   */
+  ended,
+}
+
+export interface PatchableFileModelOptions<T> {
+  oid: string
+  fid: string
+  sdk: SdkService
+  initialize: (value: unknown, dependencies: unknown[] | undefined) => T
+  bufferDelay?: number
+}
+
+type WithJson = object & { toJSON(): unknown }
+
+/**
+ * A base class for models that represent patchable files.
+ * It provides methods to read, apply server patches, and handle changes.
+ * The model is designed to work with a file identified by an organization ID (oid)
+ * and a file ID (fid).
+ *
+ * @template T The type of the file content.
+ */
+export abstract class PatchableFileModel<T extends object> extends Model<T> {
+  /**
+   * This is essentially a snapshot of the document that is
+   * always consistent with the server (to our knowledge).
+   * It is used to:
+   * - compare with the current `value` to generate diff patches
+   * - apply server patches once they arrive and then rebased client patches.
+   * After that new revision has server and client patches.
+   */
+  private revision?: T
+
+  /**
+   * The current state of the model.
+   */
+  state: ModelState = ModelState.idle
+
+  private bufferTimeoutId: ReturnType<typeof setTimeout> | null = null
+  private readonly bufferDelay: number
+
+  protected oid: string
+  protected fid: string
+  protected sdk: SdkService
+  protected initCallback: (value: unknown, dependencies: unknown[] | undefined) => T
+
+  /**
+   * The current file media version.
+   */
+  protected version = 0
+
+  /**
+   * The dependencies of the media object.
+   * This is an array of objects that are referenced by the media object.
+   * If the media object has no dependencies, this will be `undefined`.
+   *
+   * This should be manually populated then the application adds a dependency
+   * to the media object. There's no way for us to know when a dependency is added
+   * or removed from the media object, so we leave it up to the application to
+   * manage this array.
+   *
+   * Note that dependencies are only fetched when the file is read for the first time.
+   */
+  dependencies: unknown[] | undefined
+
+  constructor(options: PatchableFileModelOptions<T>) {
+    super()
+    this.bufferDelay = options.bufferDelay || 500
+    this.oid = options.oid
+    this.fid = options.fid
+    this.sdk = options.sdk
+    this.initCallback = options.initialize
+  }
+
+  async read(): Promise<void> {
+    if (this.state !== ModelState.idle) {
+      return
+    }
+    this.state = ModelState.reading
+    try {
+      const result = await this.sdk.file.readMedia(this.oid, this.fid)
+      this.version = result.version
+      const media = result.media as T
+      this.dependencies = await this.readDependencies(media)
+      this.setupFile(this.initCallback(result.media as T, this.dependencies))
+    } catch (e) {
+      const err = e as Error
+      this.notifyError(new Error(`Unable to load the file. ${err.message}`))
+      this.state = ModelState.idle
+      throw err
+    }
+    this.dispatchEvent(new Event('querycomplete'))
+  }
+
+  /**
+   * Tests whether the media object has dependencies.
+   * If the media object has a `dependencyList` property that is an array
+   * and contains at least one item, it returns a promise that resolves to
+   * an array of dependencies. If the `dependencyList` is empty or not an array,
+   * it returns a promise that resolves to `undefined`.
+   * @param media The media object to read dependencies from.
+   */
+  async readDependencies(media: unknown): Promise<unknown[] | undefined> {
+    const typed = media as DependentModelSchema
+    if (!Array.isArray(typed.dependencyList) || !typed.dependencyList.length) {
+      return undefined
+    }
+    const result = await this.sdk.dataCatalog.listDependencies(typed.dependencyList)
+    return result.items.length ? result.items : undefined
+  }
+
+  /**
+   * Called when the file was downloaded and the content is ready to be setup.
+   * Add any listeners to the content here.
+   * @param content The file content to setup.
+   */
+  protected abstract setupFile(content: T): void
+
+  protected setupPreviousData(content: T): void {
+    const typed = content as WithJson
+    if (typeof typed.toJSON === 'function') {
+      this.revision = typed.toJSON() as T
+    } else {
+      this.revision = structuredClone(content)
+    }
+  }
+
+  /**
+   * Applies incoming server patches to the document and rebases client patches.
+   *
+   * This method integrates server-side changes into the document and reconciles
+   * them with any local changes made by the client. It ensures that client
+   * changes are applied on top of the latest server state.
+   *
+   * **Process:**
+   *
+   * 1.  Applies the `server` patches to the `revision`.
+   * 2.  Calculates the client's local changes (diff between `revision` and `value`).
+   * 3.  If there are local changes, rebases them against the server patches.
+   * 4.  Applies the rebased client patches to the `revision`.
+   * 5.  Updates the `value` to match the `revision`.
+   * 6. Dispatches `change` event.
+   *
+   * @param server - The server patches to be applied to the document.
+   * @returns The rebased **client** patches that were applied to the document.
+   *   These patches are safe to send to the server. Returns an empty array if there were no local changes.
+   * @throws {Error} If the local patches cannot be applied to the document after
+   *   server changes. This indicates a conflict that the client application
+   *   should handle (e.g., by notifying the user and refreshing the document).
+   *
+   * @example
+   * ```typescript
+   * const doc = new JsonDocument({ a: 1, b: [2, 3] });
+   *
+   * // Simulate local changes (UI edits)
+   * doc.value.a = 4;
+   * doc.value.b.push(5);
+   *
+   * // Simulate a server patch
+   * const serverPatch: Operation[] = [{ op: 'add', path: '/b/0', value: 0 }];
+   *
+   * // Apply the server patch and rebase local changes
+   * const rebasedClientPatches = doc.applyServer(serverPatch);
+   *
+   * console.log(doc.value); // Output: { a: 4, b: [0, 2, 3, 5] }
+   * console.log(rebasedClientPatches);
+   * // Output: [{ op: 'replace', path: '/a', value: 4 }, { op: 'add', path: '/b/3', value: 5 }]
+   * ```
+   */
+  applyServerPatch(info: MediaPatchRevision): Operation[] {
+    const { value } = this
+    if (typeof info.newVersion !== 'number') {
+      throw new Error('The server patch must contain a new version number.')
+    }
+    this.version = info.newVersion
+    if (!value) {
+      return []
+    }
+    const client = diff(this.revision, this.readValue())
+    const ar = apply(this.revision, info.patch)
+    let result: Operation[] = []
+    if (client.length) {
+      result = rebase(info.patch, client)
+      apply(ar.doc, result)
+    }
+    this.revision = ar.doc as T
+    const content = this.initCallback(ar.doc, this.dependencies)
+    this.setValue(content)
+    return result
+  }
+
+  /**
+   * Called when a change is made to the data object.
+   */
+  async handleChange(): Promise<void> {
+    this.scheduleSend()
+  }
+
+  /**
+   * Schedules sending the buffered patches to the server after a delay.
+   */
+  private scheduleSend(): void {
+    if (this.bufferTimeoutId !== null) {
+      clearTimeout(this.bufferTimeoutId)
+    }
+
+    this.bufferTimeoutId = setTimeout(() => {
+      this.send()
+      this.bufferTimeoutId = null
+    }, this.bufferDelay)
+  }
+
+  /**
+   * Sends the buffered patches to the server.
+   */
+  private async send(): Promise<void> {
+    const patch = diff(this.revision, this.readValue())
+    if (patch.length === 0) {
+      return
+    }
+    try {
+      await this.sendPatchToServer(patch)
+    } catch (e) {
+      const err = e as Error
+      this.notifyError(err)
+      this.state = ModelState.idle
+      throw err
+      // Retry logic or other error handling can be added here
+    }
+  }
+
+  private async sendPatchToServer(patch: Operation[]): Promise<void> {
+    const info: MediaPatchInfo = {
+      timestamp: Date.now(),
+      patch,
+      // app: 'quick-api',
+      // appVersion: 'v1',
+      id: nanoid(),
+      version: this.version,
+    }
+    const result = await this.sdk.file.patchMedia(this.oid, this.fid, info)
+    this.version = result.newVersion
+    // update revision so the current patches become a base.
+    this.revision = this.createRevision()
+  }
+
+  /**
+   * A function that creates a new revision of the current file.
+   */
+  protected abstract createRevision(): T
+
+  /**
+   * Returns the current value of the file.
+   */
+  protected abstract readValue(): T
+
+  /**
+   * Sets the value of the file.
+   * @param value The new value to set.
+   */
+  protected abstract setValue(value: T): void
+
+  /**
+   * Checks whether this contents is identified by the passed `oid` and `fid`
+   * @param oid The organization id
+   * @param fid The file id
+   * @returns Whether the current file is the same as the passed arguments.
+   */
+  isFile(oid: string, fid: string): boolean {
+    return this.oid === oid && this.fid === fid
+  }
+}

package/src/data/PatchableLiveDataContentModel.ts

@@ -0,0 +1,34 @@
+import { LiveData } from '../reactive/LiveData.js'
+import { PatchableFileModel } from './PatchableFileModel.js'
+
+export default class PatchableLiveDataContentModel<T extends object> extends PatchableFileModel<T> {
+  protected setupFile(content: T): void {
+    this.raw = new LiveData(content) as T
+    this.setupPreviousData(content)
+  }
+
+  protected override createRevision(): T {
+    const v = this.value as LiveData<T>
+    if (!v) {
+      throw new Error('LiveData value is not set.')
+    }
+    return JSON.parse(JSON.stringify(v.value)) as T
+  }
+
+  protected override readValue(): T {
+    const v = this.value as LiveData<T>
+    if (!v) {
+      throw new Error('LiveData value is not set.')
+    }
+    return v.value as T
+  }
+
+  protected override setValue(value: T): void {
+    const v = this.value as LiveData<T>
+    if (v) {
+      v.set(value)
+    } else {
+      this.raw = new LiveData(value) as T
+    }
+  }
+}

package/src/data/PatchableRawContentModel.ts

@@ -0,0 +1,43 @@
+import { PatchableFileModel, type PatchableFileModelOptions } from './PatchableFileModel.js'
+
+export default class PatchableRawContentModel<T extends object> extends PatchableFileModel<T> {
+  constructor(options: PatchableFileModelOptions<T>) {
+    super(options)
+    this.changeListener = this.changeListener.bind(this)
+  }
+
+  protected changeListener(): void {
+    this.handleChange()
+    this.dispatchEvent(new Event('change'))
+  }
+
+  protected setupFile(content: T): void {
+    this.raw = content
+    const typed = content as EventTarget
+    typed.addEventListener('change', this.changeListener)
+    this.setupPreviousData(content)
+  }
+
+  protected override createRevision(): T {
+    return JSON.parse(JSON.stringify(this.value)) as T
+  }
+
+  protected override readValue(): T {
+    const v = this.value as T
+    if (v) {
+      return JSON.parse(JSON.stringify(this.value)) as T
+    }
+    return v
+  }
+
+  protected override setValue(content: T): void {
+    if (this.value) {
+      const typed = this.value as EventTarget
+      typed.removeEventListener('change', this.changeListener)
+    }
+    const typed = content as EventTarget
+    typed.addEventListener('change', this.changeListener)
+    this.raw = content
+    this.changeListener()
+  }
+}

package/src/data/TrashModel.ts

@@ -0,0 +1,125 @@
+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 type { TrashEntry } from '@api-client/core/models/TrashEntry.js'
+import type { ContextListOptions, ContextListResult } from '@api-client/core/events/BaseEvents.js'
+
+enum ModelState {
+  /**
+   * Not doing anything.
+   */
+  idle,
+  /**
+   * Currently querying for breadcrumb data.
+   */
+  reading,
+  /**
+   * Data was received and the result yielded no results or less than the limit.
+   */
+  ended,
+}
+
+export default class TrashModel extends Model<TrashEntry[]> {
+  /**
+   * The current state of the model.
+   */
+  state: ModelState = ModelState.idle
+
+  /**
+   * The trash items
+   */
+  items: LiveData<TrashEntry[]> = new LiveData<TrashEntry[]>([])
+
+  /**
+   * The pagination cursor for files to use with the next query.
+   */
+  cursor?: string
+
+  constructor(
+    protected oid: string,
+    protected sdk: SdkService
+  ) {
+    super()
+  }
+
+  reset(): void {
+    this.state = ModelState.idle
+    this.cursor = undefined
+    this.items.set([])
+  }
+
+  scheduleQuery(): void {
+    this.debounce(this.#query)
+  }
+
+  async #query(): Promise<void> {
+    if (this.state !== ModelState.idle) {
+      return
+    }
+    this.state = ModelState.reading
+    const operation = async (): Promise<ContextListResult<TrashEntry>> => {
+      return this.sdk.trash.list(this.oid, this.getPageQueryOptions())
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      const result = await retry(operation, retryOptions)
+      this.#processTrashResults(result)
+    } catch (e) {
+      const err = fromError(e as Error)
+      this.notifyError(err)
+      this.state = ModelState.idle
+    }
+  }
+
+  #processTrashResults(result: ContextListResult<TrashEntry>): void {
+    const { items, cursor } = result
+    if (cursor) {
+      this.cursor = cursor
+    }
+    if (!items.length) {
+      this.state = ModelState.ended
+      return
+    }
+    this.items.set(this.items.value.concat(items))
+    this.state = ModelState.idle
+  }
+
+  getPageQueryOptions(): ContextListOptions {
+    const { cursor, limit } = this
+    const opts: ContextListOptions = {}
+    if (cursor) {
+      opts.cursor = cursor
+    }
+    if (typeof limit === 'number' && limit) {
+      opts.limit = limit
+    }
+    return opts
+  }
+
+  /**
+   * Finds a file by the key.
+   * @param key The key of the file to find
+   * @returns The file, if any
+   */
+  getItem(key: string): TrashEntry | undefined {
+    return this.items.value.find((i) => i.key === key)
+  }
+
+  delete(keys: string[]): Promise<void> {
+    return this.sdk.trash.delete(this.oid, keys)
+  }
+
+  restore(keys: string[]): Promise<void> {
+    return this.sdk.trash.restore(this.oid, keys)
+  }
+
+  removeItems(keys: string[]): void {
+    this.items.set(this.items.value.filter((item) => !keys.includes(item.key)))
+  }
+}

package/src/data/UserModel.ts

@@ -0,0 +1,102 @@
+import { type IUser } from '@api-client/core/models/store/User.js'
+import { Model } from '../core/Model.js'
+import { exponentialBackoffDelay, type RetryOptions, shouldRetryApiError, retry } from './retry_logic.js'
+import type SdkService from '../services/SdkService.js'
+
+export default class UserModel extends Model<IUser> {
+  /**
+   * The user ID this model is associated with.
+   * Note, this value must be set before calling `fetch()`.
+   */
+  uid?: string
+  /**
+   * The organization ID this model is associated with.
+   */
+  oid: string
+  /**
+   * A reference to the SDK service used to perform API calls.
+   */
+  sdk: SdkService
+  /**
+   * Whether the model is currently loading data.
+   */
+  loading = false
+
+  constructor(sdk: SdkService, oid: string) {
+    super()
+    this.sdk = sdk
+    this.oid = oid
+  }
+
+  async fetch(): Promise<IUser> {
+    const { uid, oid } = this
+    if (!uid) {
+      throw new Error('User ID (uid) is not set. Cannot fetch user data.')
+    }
+    this.loading = true
+    const operation = async (): Promise<IUser> => {
+      return this.sdk.organizations.users.read(oid, uid)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      this.raw = await retry(operation, retryOptions)
+    } finally {
+      this.loading = false
+    }
+    return this.raw
+  }
+
+  isActive(): boolean {
+    const { raw } = this
+    if (!raw) {
+      throw new Error('User data is not loaded. Cannot determine if user is active.')
+    }
+    return raw.status === 'active'
+  }
+
+  async deactivate(): Promise<void> {
+    const { uid, oid } = this
+    if (!uid) {
+      throw new Error('User ID (uid) is not set. Cannot deactivate user.')
+    }
+    this.loading = true
+    const operation = async (): Promise<IUser> => {
+      return this.sdk.organizations.users.deactivate(oid, uid)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      this.raw = await retry(operation, retryOptions)
+    } finally {
+      this.loading = false
+    }
+  }
+
+  async activate(): Promise<void> {
+    const { uid, oid } = this
+    if (!uid) {
+      throw new Error('User ID (uid) is not set. Cannot activate user.')
+    }
+    this.loading = true
+    const operation = async (): Promise<IUser> => {
+      return this.sdk.organizations.users.activate(oid, uid)
+    }
+    const retryOptions: RetryOptions = {
+      retries: this.retryCount,
+      delayMs: exponentialBackoffDelay,
+      shouldRetry: shouldRetryApiError as (error: Error) => boolean,
+    }
+    try {
+      this.raw = await retry(operation, retryOptions)
+    } finally {
+      this.loading = false
+    }
+  }
+}