@api-client/ui 0.1.3 → 0.1.4

package/build/src/core/Model.d.ts

@@ -1,3 +1,43 @@
+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 declare function exponentialBackoffDelay(attempt: number, initialDelay?: number): number;
+/**
+ * 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 declare function shouldRetryApiError(error: Exception): boolean;
 /**
  * The base class for models.
  *
@@ -36,6 +76,10 @@ export declare abstract class Model<T> extends EventTarget {
      * @type A promise resolved when the debounced task finished.
      */
     get taskComplete(): Promise<void> | undefined;
+    /**
+     * A getter for the raw value.
+     */
+    get value(): T | undefined;
     /**
      * @param obj The source object to use.
      */
@@ -53,5 +97,28 @@ export declare abstract class Model<T> extends EventTarget {
     debounce(callback: (...args: unknown[]) => unknown): void;
     notifyError(error: Error): void;
     protected resolveTaskPromise(): void;
+    /**
+     * 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 retry<R>(operation: () => Promise<R>, options?: RetryOptions): Promise<R>;
 }
 //# sourceMappingURL=Model.d.ts.map

package/build/src/core/Model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Model.d.ts","sourceRoot":"","sources":["../../../src/core/Model.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AACH,8BAAsB,KAAK,CAAC,CAAC,CAAE,SAAQ,WAAW;;IAChD;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,CAAC,CAAA;IAEP;;;;OAIG;IACH,eAAe,SAAM;IAErB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAA;IAExC;;OAEG;IACH,KAAK,SAAK;IAiBV;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAE5C;IAED;;OAEG;gBACS,GAAG,CAAC,EAAE,CAAC;IAMnB;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpC,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI;IAqBzD,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAe/B,SAAS,CAAC,kBAAkB,IAAI,IAAI;CAUrC"}
+{"version":3,"file":"Model.d.ts","sourceRoot":"","sources":["../../../src/core/Model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0CAA0C,CAAA;AAEzE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;IAChD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAA;CACxC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,SAAO,GAAG,MAAM,CAIpF;AACD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAO7D;AACD;;;;;;;;;GASG;AACH,8BAAsB,KAAK,CAAC,CAAC,CAAE,SAAQ,WAAW;;IAChD;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,CAAC,CAAA;IAEP;;;;OAIG;IACH,eAAe,SAAM;IAErB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAA;IAExC;;OAEG;IACH,KAAK,SAAK;IAiBV;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAE5C;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,CAAC,GAAG,SAAS,CAEzB;IAED;;OAEG;gBACS,GAAG,CAAC,EAAE,CAAC;IAMnB;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpC,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI;IAqBzD,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAe/B,SAAS,CAAC,kBAAkB,IAAI,IAAI;IAWpC;;;;;;;;;;;;;;;;;;;;;OAqBG;cACa,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,CAAC,CAAC;CAmC9F"}

package/build/src/core/Model.js

@@ -1,4 +1,32 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * 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, initialDelay = 1000) {
+    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) {
+    const { status } = error;
+    if (status === 404) {
+        // Do not retry on 404 errors
+        return false;
+    }
+    return true;
+}
 /**
  * The base class for models.
  *
@@ -50,6 +78,12 @@ export class Model extends EventTarget {
     get taskComplete() {
         return this.#taskComplete;
     }
+    /**
+     * A getter for the raw value.
+     */
+    get value() {
+        return this.raw;
+    }
     /**
      * @param obj The source object to use.
      */
@@ -113,5 +147,60 @@ export class Model extends EventTarget {
             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;
+     * }
+     * ```
+     */
+    async retry(operation, options = {}) {
+        const { retries = 3, delayMs = 1000, shouldRetry = () => true } = options;
+        let lastError;
+        for (let attempt = 0; attempt < retries; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (e) {
+                lastError = e;
+                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;
+    }
 }
 //# sourceMappingURL=Model.js.map

package/build/src/core/Model.js.map

@@ -1 +1 @@
-{"version":3,"file":"Model.js","sourceRoot":"","sources":["../../../src/core/Model.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD;;;;;;;;;GASG;AACH,MAAM,OAAgB,KAAS,SAAQ,WAAW;IAChD;;;;;;OAMG;IACH,GAAG,CAAI;IAEP;;;;OAIG;IACH,eAAe,GAAG,GAAG,CAAA;IAErB;;OAEG;IACH,cAAc,CAA0B;IAExC;;OAEG;IACH,KAAK,GAAG,EAAE,CAAA;IAEV;;OAEG;IACH,sBAAsB,GAAG,KAAK,CAAA;IAE9B;;OAEG;IACH,aAAa,CAAgB;IAE7B;;OAEG;IACH,aAAa,CAAa;IAE1B;;OAEG;IACH,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAA;IAC3B,CAAC;IAED;;OAEG;IACH,YAAY,GAAO;QACjB,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;QACd,IAAI,CAAC,iBAAiB,EAAE,CAAA;IAC1B,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAgB;QACrB,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAA;IACrC,CAAC;IAED,QAAQ,CAAC,QAAyC;QAChD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QACnC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,CAAC;YACjC,IAAI,CAAC,iBAAiB,EAAE,CAAA;QAC1B,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE;YAC1C,IAAI,CAAC,cAAc,GAAG,SAAS,CAAA;YAC/B,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC3B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,GAAG,GAAG,CAAU,CAAA;gBACtB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;gBACrB,MAAM,GAAG,CAAA;YACX,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,kBAAkB,EAAE,CAAA;YAC3B,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAA;IAC1B,CAAC;IAED,WAAW,CAAC,KAAY;QACtB,IAAI,CAAC,aAAa,CAChB,IAAI,WAAW,CAAQ,OAAO,EAAE;YAC9B,MAAM,EAAE,KAAK;SACd,CAAC,CACH,CAAA;IACH,CAAC;IAED,iBAAiB;QACf,IAAI,CAAC,aAAa,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACjD,IAAI,CAAC,aAAa,GAAG,OAAO,CAAA;YAC5B,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAA;QACpC,CAAC,CAAC,CAAA;IACJ,CAAC;IAES,kBAAkB;QAC1B,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,CAAC;YACjC,OAAM;QACR,CAAC;QACD,IAAI,CAAC,sBAAsB,GAAG,KAAK,CAAA;QACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAA;QACnC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,EAAE,CAAA;QACZ,CAAC;IACH,CAAC;CACF","sourcesContent":["/* eslint-disable @typescript-eslint/no-unused-vars */\n/**\n * The base class for models.\n *\n * Models wrap a logic related to manipulating model data, querying for data from the API,\n * retry logic, cashing, refreshing of data, offline storage, pooling endpoints for new data, etc.\n *\n * The application should use these models in order to centralize object manipulation.\n *\n * @template T The underlying domain model.\n */\nexport abstract class Model<T> extends EventTarget {\n  /**\n   * The underlying raw object.\n   * Do not modify properties of the object directly.\n   * Use one of the methods provided by the model.\n   * Direct changes will not be reflected in the UI\n   * and may cause issues when processing the object.\n   */\n  raw?: T\n\n  /**\n   * The timeout for the query debouncer.\n   * When any property change this is the time the element will wait\n   * until the actual query is made.\n   */\n  debounceTimeout = 100\n\n  /**\n   * A reference to the current debouncer.\n   */\n  debouncerValue?: number | NodeJS.Timeout\n\n  /**\n   * Default limit for list queries.\n   */\n  limit = 30\n\n  /**\n   * A flag that helps to determine whether the `taskComplete` is setup.\n   */\n  #hasPendingTaskPromise = false\n\n  /**\n   * A hidden value for the `taskComplete` getter.\n   */\n  #taskComplete?: Promise<void>\n\n  /**\n   * The resolver to call when the debounced task completes.\n   */\n  #taskResolver?: () => void\n\n  /**\n   * @type A promise resolved when the debounced task finished.\n   */\n  get taskComplete(): Promise<void> | undefined {\n    return this.#taskComplete\n  }\n\n  /**\n   * @param obj The source object to use.\n   */\n  constructor(obj?: T) {\n    super()\n    this.raw = obj\n    this.#setUpdatePromise()\n  }\n\n  /**\n   * Creates a new instance of the data. It often invokes API call.\n   * This is what happens after the user triggers \"create new\" flow.\n   *\n   * After this method is calls, the `raw` object is set.\n   *\n   * @param data The partial data to create.\n   * @returns The created object.\n   */\n  create(data: Partial<T>): Promise<T> {\n    throw new Error(`Not implemented.`)\n  }\n\n  debounce(callback: (...args: unknown[]) => unknown): void {\n    if (this.debouncerValue) {\n      clearTimeout(this.debouncerValue)\n    }\n    if (!this.#hasPendingTaskPromise) {\n      this.#setUpdatePromise()\n    }\n    this.debouncerValue = setTimeout(async () => {\n      this.debouncerValue = undefined\n      try {\n        await callback.call(this)\n      } catch (e) {\n        const err = e as Error\n        this.notifyError(err)\n        throw err\n      } finally {\n        this.resolveTaskPromise()\n      }\n    }, this.debounceTimeout)\n  }\n\n  notifyError(error: Error): void {\n    this.dispatchEvent(\n      new CustomEvent<Error>('error', {\n        detail: error,\n      })\n    )\n  }\n\n  #setUpdatePromise(): void {\n    this.#taskComplete = new Promise<void>((resolve) => {\n      this.#taskResolver = resolve\n      this.#hasPendingTaskPromise = true\n    })\n  }\n\n  protected resolveTaskPromise(): void {\n    if (!this.#hasPendingTaskPromise) {\n      return\n    }\n    this.#hasPendingTaskPromise = false\n    const resolver = this.#taskResolver\n    if (resolver) {\n      resolver()\n    }\n  }\n}\n"]}
+{"version":3,"file":"Model.js","sourceRoot":"","sources":["../../../src/core/Model.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable @typescript-eslint/no-unused-vars */\n\nimport type { Exception } from '@api-client/core/exceptions/exception.js'\n\n/**\n * Defines the options for the retry mechanism.\n */\nexport interface RetryOptions {\n  /**\n   * The maximum number of retry attempts.\n   * Defaults to 3.\n   */\n  retries?: number\n  /**\n   * The delay in milliseconds before the next retry.\n   * Can be a fixed number or a function that returns a number (e.g., for exponential backoff).\n   * Defaults to 1000ms.\n   */\n  delayMs?: number | ((attempt: number) => number)\n  /**\n   * An optional function that determines if a retry should be attempted based on the error.\n   * If not provided, all errors will trigger a retry up to the maximum number of retries.\n   * @param error The error that occurred.\n   * @returns True if a retry should be attempted, false otherwise.\n   */\n  shouldRetry?: (error: Error) => boolean\n}\n\n/**\n * Calculates an exponential backoff delay for retry attempts.\n * The delay doubles with each attempt.\n *\n * @param attempt The current retry attempt number (should be 1-indexed).\n * @param initialDelay The initial delay in milliseconds. Defaults to 1000ms.\n * @returns The calculated delay in milliseconds.\n */\nexport function exponentialBackoffDelay(attempt: number, initialDelay = 1000): number {\n  if (attempt <= 0) return initialDelay\n  // For attempt 1, delay is initialDelay * 2^0 = initialDelay\n  return initialDelay * Math.pow(2, attempt - 1)\n}\n/**\n * Checks if the API error should be retried based on its status code.\n * If the status code is 404, it returns false (do not retry).\n * For other status codes, it returns true (retry).\n * @param error The error to check.\n */\nexport function shouldRetryApiError(error: Exception): boolean {\n  const { status } = error\n  if (status === 404) {\n    // Do not retry on 404 errors\n    return false\n  }\n  return true\n}\n/**\n * The base class for models.\n *\n * Models wrap a logic related to manipulating model data, querying for data from the API,\n * retry logic, cashing, refreshing of data, offline storage, pooling endpoints for new data, etc.\n *\n * The application should use these models in order to centralize object manipulation.\n *\n * @template T The underlying domain model.\n */\nexport abstract class Model<T> extends EventTarget {\n  /**\n   * The underlying raw object.\n   * Do not modify properties of the object directly.\n   * Use one of the methods provided by the model.\n   * Direct changes will not be reflected in the UI\n   * and may cause issues when processing the object.\n   */\n  raw?: T\n\n  /**\n   * The timeout for the query debouncer.\n   * When any property change this is the time the element will wait\n   * until the actual query is made.\n   */\n  debounceTimeout = 100\n\n  /**\n   * A reference to the current debouncer.\n   */\n  debouncerValue?: number | NodeJS.Timeout\n\n  /**\n   * Default limit for list queries.\n   */\n  limit = 30\n\n  /**\n   * A flag that helps to determine whether the `taskComplete` is setup.\n   */\n  #hasPendingTaskPromise = false\n\n  /**\n   * A hidden value for the `taskComplete` getter.\n   */\n  #taskComplete?: Promise<void>\n\n  /**\n   * The resolver to call when the debounced task completes.\n   */\n  #taskResolver?: () => void\n\n  /**\n   * @type A promise resolved when the debounced task finished.\n   */\n  get taskComplete(): Promise<void> | undefined {\n    return this.#taskComplete\n  }\n\n  /**\n   * A getter for the raw value.\n   */\n  get value(): T | undefined {\n    return this.raw\n  }\n\n  /**\n   * @param obj The source object to use.\n   */\n  constructor(obj?: T) {\n    super()\n    this.raw = obj\n    this.#setUpdatePromise()\n  }\n\n  /**\n   * Creates a new instance of the data. It often invokes API call.\n   * This is what happens after the user triggers \"create new\" flow.\n   *\n   * After this method is calls, the `raw` object is set.\n   *\n   * @param data The partial data to create.\n   * @returns The created object.\n   */\n  create(data: Partial<T>): Promise<T> {\n    throw new Error(`Not implemented.`)\n  }\n\n  debounce(callback: (...args: unknown[]) => unknown): void {\n    if (this.debouncerValue) {\n      clearTimeout(this.debouncerValue)\n    }\n    if (!this.#hasPendingTaskPromise) {\n      this.#setUpdatePromise()\n    }\n    this.debouncerValue = setTimeout(async () => {\n      this.debouncerValue = undefined\n      try {\n        await callback.call(this)\n      } catch (e) {\n        const err = e as Error\n        this.notifyError(err)\n        throw err\n      } finally {\n        this.resolveTaskPromise()\n      }\n    }, this.debounceTimeout)\n  }\n\n  notifyError(error: Error): void {\n    this.dispatchEvent(\n      new CustomEvent<Error>('error', {\n        detail: error,\n      })\n    )\n  }\n\n  #setUpdatePromise(): void {\n    this.#taskComplete = new Promise<void>((resolve) => {\n      this.#taskResolver = resolve\n      this.#hasPendingTaskPromise = true\n    })\n  }\n\n  protected resolveTaskPromise(): void {\n    if (!this.#hasPendingTaskPromise) {\n      return\n    }\n    this.#hasPendingTaskPromise = false\n    const resolver = this.#taskResolver\n    if (resolver) {\n      resolver()\n    }\n  }\n\n  /**\n   * Executes an asynchronous operation with a retry mechanism.\n   * @param operation A function that returns a Promise to be executed.\n   * @param options Optional retry configurations.\n   * @returns A Promise that resolves with the result of the operation or rejects if all retries fail.\n   * @example\n   * ```typescript\n   * override async create(data: Partial<IUser>): Promise<IUser> {\n   *   const operation = async (): Promise<UserData> => {\n   *     // ... perform API call to create user\n   *   }\n   *   const retryOptions: RetryOptions = {\n   *     retries: 5,\n   *     delayMs: exponentialBackoffDelay,\n   *     shouldRetry: shouldRetryApiError,\n   *   }\n   *   this.raw = await this.retry(operation)\n   *   this.dispatchEvent(new CustomEvent('data-changed', { detail: this.raw }))\n   *   return this.raw;\n   * }\n   * ```\n   */\n  protected async retry<R>(operation: () => Promise<R>, options: RetryOptions = {}): Promise<R> {\n    const { retries = 3, delayMs = 1000, shouldRetry = () => true } = options\n\n    let lastError: Error | undefined\n\n    for (let attempt = 0; attempt < retries; attempt++) {\n      try {\n        return await operation()\n      } catch (e) {\n        lastError = e as Error\n        if (!shouldRetry(lastError) || attempt === retries - 1) {\n          // Do not retry if shouldRetry returns false or if it's the last attempt\n          this.notifyError(lastError)\n          throw lastError\n        }\n\n        const delay = typeof delayMs === 'function' ? delayMs(attempt + 1) : delayMs\n        if (delay > 0) {\n          await new Promise((resolve) => setTimeout(resolve, delay))\n        }\n      }\n    }\n    // This part should ideally not be reached if retries > 0,\n    // as the loop would throw on the last attempt.\n    // However, to satisfy TypeScript and guard against retries = 0:\n    if (lastError) {\n      this.notifyError(lastError)\n      throw lastError\n    }\n    // Should not happen if operation is called at least once.\n    // Adding a generic error for completeness.\n    const err = new Error('Retry operation failed without a specific error.')\n    this.notifyError(err)\n    throw err\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api-client/ui",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Internal UI component library for the API Client ecosystem.",
   "license": "UNLICENSED",
   "main": "build/src/index.js",

package/src/core/Model.ts

@@ -1,4 +1,58 @@
 /* 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.
  *
@@ -58,6 +112,13 @@ export abstract class Model<T> extends EventTarget {
     return this.#taskComplete
   }
 
+  /**
+   * A getter for the raw value.
+   */
+  get value(): T | undefined {
+    return this.raw
+  }
+
   /**
    * @param obj The source object to use.
    */
@@ -126,4 +187,62 @@ export abstract class Model<T> extends EventTarget {
       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
+  }
 }