@warp-drive/legacy 5.9.0-alpha.2 → 5.9.0-alpha.21

package/dist/adapter/error.js

@@ -5,70 +5,6 @@ import { macroCondition, getGlobalConfig } from '@embroider/macros';
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 
-/**
-  ## Overview
-
-  :::danger
-    ⚠️ **This is LEGACY documentation** for a feature that is no longer encouraged to be used.
-    If starting a new app or thinking of implementing a new adapter, consider writing a
-    {@link Handler} instead to be used with the {@link RequestManager}
-  :::
-
-  An `AdapterError` is used by an adapter to signal that an error occurred
-  during a request to an external API. It indicates a generic error, and
-  subclasses are used to indicate specific error states.
-
-  To create a custom error to signal a specific error state in communicating
-  with an external API, extend the `AdapterError`. For example, if the
-  external API exclusively used HTTP `503 Service Unavailable` to indicate
-  it was closed for maintenance:
-
-  ```js [app/adapters/maintenance-error.js]
-  import AdapterError from '@warp-drive/legacy/adapter/error';
-
-  export default AdapterError.extend({ message: "Down for maintenance." });
-  ```
-
-  This error would then be returned by an adapter's `handleResponse` method:
-
-  ```js [app/adapters/application.js]
-  import JSONAPIAdapter from '@warp-drive/legacy/adapter/json-api';
-  import MaintenanceError from './maintenance-error';
-
-  export default class ApplicationAdapter extends JSONAPIAdapter {
-    handleResponse(status) {
-      if (503 === status) {
-        return new MaintenanceError();
-      }
-
-      return super.handleResponse(...arguments);
-    }
-  }
-  ```
-
-  And can then be detected in an application and used to send the user to an
-  `under-maintenance` route:
-
-  ```js [app/routes/application.js]
-  import MaintenanceError from '../adapters/maintenance-error';
-
-  export default class ApplicationRoute extends Route {
-    actions: {
-      error(error, transition) {
-        if (error instanceof MaintenanceError) {
-          this.transitionTo('under-maintenance');
-          return;
-        }
-
-        // ...other error handling logic
-      }
-    }
-  }
-  ```
-
-  @class AdapterError
-  @public
-*/
 function _AdapterError(errors, message = 'Adapter operation failed') {
   this.isAdapterError = true;
   const error = Error.call(this, message);
@@ -90,9 +26,122 @@ function _AdapterError(errors, message = 'Adapter operation failed') {
     detail: message
   }];
 }
+
+/**
+ * The shape of the errors thrown/returned by {@link AdapterError} and its subclasses.
+ */
+
+/**
+ * The static interface shared by {@link AdapterError} and its subclasses,
+ * allowing further subclassing via {@link AdapterRequestErrorConstructor.extend | extend}.
+ */
+
 _AdapterError.prototype = Object.create(Error.prototype);
 _AdapterError.prototype.code = 'AdapterError';
 _AdapterError.extend = extendFn(_AdapterError);
+
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link AdapterError} constructor.
+ */
+
+/**
+ * :::danger
+ * ⚠️ **This is LEGACY documentation** for a feature that is no longer encouraged to be used.
+ * If starting a new app or thinking of implementing a new adapter, consider writing a
+ * {@link Handler} instead to be used with the {@link RequestManager}
+ * :::
+ *
+ * An `AdapterError` is used by an adapter to signal that an error occurred
+ * during a request to an external API. It indicates a generic error, and
+ * subclasses are used to indicate specific error states.
+ *
+ * To create a custom error to signal a specific error state in communicating
+ * with an external API, extend the `AdapterError`. For example, if the
+ * external API exclusively used HTTP `503 Service Unavailable` to indicate
+ * it was closed for maintenance:
+ *
+ * ```js [app/adapters/maintenance-error.js]
+ * import AdapterError from '@warp-drive/legacy/adapter/error';
+ *
+ * export default AdapterError.extend({ message: "Down for maintenance." });
+ * ```
+ *
+ * This error would then be returned by an adapter's `handleResponse` method:
+ *
+ * ```js [app/adapters/application.js]
+ * import JSONAPIAdapter from '@warp-drive/legacy/adapter/json-api';
+ * import MaintenanceError from './maintenance-error';
+ *
+ * export default class ApplicationAdapter extends JSONAPIAdapter {
+ *   handleResponse(status) {
+ *     if (503 === status) {
+ *       return new MaintenanceError();
+ *     }
+ *
+ *     return super.handleResponse(...arguments);
+ *   }
+ * }
+ * ```
+ *
+ * And can then be detected in an application and used to send the user to an
+ * `under-maintenance` route:
+ *
+ * ```js [app/routes/application.js]
+ * import MaintenanceError from '../adapters/maintenance-error';
+ *
+ * export default class ApplicationRoute extends Route {
+ *   actions: {
+ *     error(error, transition) {
+ *       if (error instanceof MaintenanceError) {
+ *         this.transitionTo('under-maintenance');
+ *         return;
+ *       }
+ *
+ *       // ...other error handling logic
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Signaling an Error Without Extending `AdapterError`
+ *
+ * Extending `AdapterError` (or one of its subclasses) is a convenience, not
+ * a requirement. WarpDrive only inspects an error for the {@link AdapterRequestError}
+ * shape: an `isAdapterError` flag, a `code`, and an {json:api}-formatted
+ * `errors` array. Any object satisfying that shape — including a plain
+ * `Error` with those properties attached — will be handled identically to
+ * an instance created via `new AdapterError()` or one of its subclasses.
+ *
+ * This is useful when you'd rather not introduce a class hierarchy, or
+ * when the error needs to be constructed from data you don't control
+ * (for example, re-throwing an error surfaced by a third-party library):
+ *
+ * ```js [app/adapters/application.js]
+ * import JSONAPIAdapter from '@warp-drive/legacy/adapter/json-api';
+ *
+ * export default class ApplicationAdapter extends JSONAPIAdapter {
+ *   handleResponse(status, headers, payload) {
+ *     if (status === 503) {
+ *       const error = new Error('Down for maintenance.');
+ *       error.isAdapterError = true;
+ *       error.code = 'MaintenanceError';
+ *       error.errors = [{ title: 'Service Unavailable', detail: 'Down for maintenance.' }];
+ *       return error;
+ *     }
+ *
+ *     return super.handleResponse(status, headers, payload);
+ *   }
+ * }
+ * ```
+ *
+ * Because `code` is just a string you control, `error instanceof AdapterError`
+ * checks won't match a plain object built this way — consumers should
+ * instead branch on `error.isAdapterError && error.code === 'MaintenanceError'`,
+ * or on whichever of the {@link AdapterError} subclasses' `code` values
+ * (e.g. `'InvalidError'`, `'NotFoundError'`) the error's `code` matches.
+ *
+ * @public
+ */
 const AdapterError = getOrSetGlobal('AdapterError', _AdapterError);
 function extendFn(ErrorClass) {
   return function ({
@@ -117,220 +166,316 @@ function extend(ParentErrorClass, defaultMessage) {
 }
 
 /**
-  A `InvalidError` is used by an adapter to signal the external API
-  was unable to process a request because the content was not
-  semantically correct or meaningful per the API. Usually, this means a
-  record failed some form of server-side validation. When a promise
-  from an adapter is rejected with a `InvalidError` the record will
-  transition to the `invalid` state and the errors will be set to the
-  `errors` property on the record.
-
-  For WarpDrive to correctly map errors to their corresponding
-  properties on the model, WarpDrive expects each error to be
-  a valid JSON-API error object with a `source/pointer` that matches
-  the property name. For example, if you had a Post model that
-  looked like this.
-
-  ```js [app/models/post.js]
-  import { Model, attr } from '@warp-drive/legacy/model';
-
-  export default class PostModel extends Model {
-    @attr('string') title;
-    @attr('string') content;
-  }
-  ```
-
-  To show an error from the server related to the `title` and
-  `content` properties your adapter could return a promise that
-  rejects with a `InvalidError` object that looks like this:
-
-  ```js [app/adapters/post.js]
-  import RSVP from 'RSVP';
-  import RESTAdapter from '@warp-drive/legacy/adapter/rest';
-  import { InvalidError } from '@warp-drive/legacy/adapter/error';
-
-  export default class ApplicationAdapter extends RESTAdapter {
-    updateRecord() {
-      // Fictional adapter that always rejects
-      return RSVP.reject(new InvalidError([
-        {
-          detail: 'Must be unique',
-          source: { pointer: '/data/attributes/title' }
-        },
-        {
-          detail: 'Must not be blank',
-          source: { pointer: '/data/attributes/content'}
-        }
-      ]));
-    }
-  }
-  ```
-
-  Your backend may use different property names for your records the
-  store will attempt to extract and normalize the errors using the
-  serializer's `extractErrors` method before the errors get added to
-  the model. As a result, it is safe for the `InvalidError` to
-  wrap the error payload unaltered.
-
-  @class InvalidError
-  @public
-*/
+ * The {@link AdapterRequestError} shape thrown by the {@link InvalidError} constructor.
+ */
 // TODO @deprecate extractError documentation
 
+/**
+ * An `InvalidError` is used by an adapter to signal that the external API
+ * was unable to process a request because the content was not semantically
+ * correct or meaningful per the API. Usually, this means a record failed
+ * some form of server-side validation. When a promise from an adapter is
+ * rejected with an `InvalidError` the record will transition to the
+ * `invalid` state and the errors will be set to the `errors` property on
+ * the record.
+ *
+ * For WarpDrive to correctly map errors to their corresponding properties
+ * on the model, WarpDrive expects each error to be a valid {json:api} error
+ * object with a `source.pointer` that matches the property name. For
+ * example, if you had a `Post` model that looked like this:
+ *
+ * ```js [app/models/post.js]
+ * import { Model, attr } from '@warp-drive/legacy/model';
+ *
+ * export default class PostModel extends Model {
+ *   @attr('string') title;
+ *   @attr('string') content;
+ * }
+ * ```
+ *
+ * To show an error from the server related to the `title` and `content`
+ * properties your adapter could return a promise that rejects with an
+ * `InvalidError` that looks like this:
+ *
+ * ```js [app/adapters/post.js]
+ * import RSVP from 'RSVP';
+ * import RESTAdapter from '@warp-drive/legacy/adapter/rest';
+ * import { InvalidError } from '@warp-drive/legacy/adapter/error';
+ *
+ * export default class ApplicationAdapter extends RESTAdapter {
+ *   updateRecord() {
+ *     // Fictional adapter that always rejects
+ *     return RSVP.reject(new InvalidError([
+ *       {
+ *         detail: 'Must be unique',
+ *         source: { pointer: '/data/attributes/title' }
+ *       },
+ *       {
+ *         detail: 'Must not be blank',
+ *         source: { pointer: '/data/attributes/content' }
+ *       }
+ *     ]));
+ *   }
+ * }
+ * ```
+ *
+ * Your backend may use different property names for your records; the
+ * store will attempt to extract and normalize the errors using the
+ * serializer's `extractErrors` method before the errors get added to the
+ * model. As a result, it is safe for the `InvalidError` to wrap the error
+ * payload unaltered.
+ *
+ * @public
+ */
 const InvalidError = getOrSetGlobal('InvalidError', extend(AdapterError, 'The adapter rejected the commit because it was invalid'));
 InvalidError.prototype.code = 'InvalidError';
 
 /**
-  A `TimeoutError` is used by an adapter to signal that a request
-  to the external API has timed out. I.e. no response was received from
-  the external API within an allowed time period.
-
-  An example use case would be to warn the user to check their internet
-  connection if an adapter operation has timed out:
-
-  ```js [app/routes/application.js]
-  import { TimeoutError } from '@warp-drive/legacy/adapter/error';
-
-  export default class ApplicationRoute extends Route {
-    @action
-    error(error, transition) {
-      if (error instanceof TimeoutError) {
-        // alert the user
-        alert('Are you still connected to the Internet?');
-        return;
-      }
-
-      // ...other error handling logic
-    }
-  }
-  ```
-
-  @class TimeoutError
-  @public
-*/
+ * The {@link AdapterRequestError} shape thrown by the {@link TimeoutError} constructor.
+ */
 
+/**
+ * A `TimeoutError` is used by an adapter to signal that a request to the
+ * external API has timed out, i.e. no response was received from the
+ * external API within an allowed time period.
+ *
+ * An example use case would be to warn the user to check their internet
+ * connection if an adapter operation has timed out:
+ *
+ * ```js [app/routes/application.js]
+ * import { TimeoutError } from '@warp-drive/legacy/adapter/error';
+ *
+ * export default class ApplicationRoute extends Route {
+ *   @action
+ *   error(error, transition) {
+ *     if (error instanceof TimeoutError) {
+ *       // alert the user
+ *       alert('Are you still connected to the Internet?');
+ *       return;
+ *     }
+ *
+ *     // ...other error handling logic
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 const TimeoutError = getOrSetGlobal('TimeoutError', extend(AdapterError, 'The adapter operation timed out'));
 TimeoutError.prototype.code = 'TimeoutError';
 
 /**
-  A `AbortError` is used by an adapter to signal that a request to
-  the external API was aborted. For example, this can occur if the user
-  navigates away from the current page after a request to the external API
-  has been initiated but before a response has been received.
-
-  @class AbortError
-  @public
-*/
+ * The {@link AdapterRequestError} shape thrown by the {@link AbortError} constructor.
+ */
 
+/**
+ * An `AbortError` is used by an adapter to signal that a request to the
+ * external API was aborted. For example, this can occur if the user
+ * navigates away from the current page after a request to the external API
+ * has been initiated but before a response has been received.
+ *
+ * Because an aborted request is typically expected (the user chose to
+ * navigate away, or a newer request superseded this one) rather than
+ * exceptional, an example use case would be to silently ignore it instead
+ * of surfacing an error to the user:
+ *
+ * ```js [app/routes/application.js]
+ * import { AbortError } from '@warp-drive/legacy/adapter/error';
+ *
+ * export default class ApplicationRoute extends Route {
+ *   @action
+ *   error(error, transition) {
+ *     if (error instanceof AbortError) {
+ *       // the request was aborted, nothing to report
+ *       return;
+ *     }
+ *
+ *     // ...other error handling logic
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 const AbortError = getOrSetGlobal('AbortError', extend(AdapterError, 'The adapter operation was aborted'));
 AbortError.prototype.code = 'AbortError';
 
 /**
-  A `UnauthorizedError` equates to a HTTP `401 Unauthorized` response
-  status. It is used by an adapter to signal that a request to the external
-  API was rejected because authorization is required and has failed or has not
-  yet been provided.
-
-  An example use case would be to redirect the user to a login route if a
-  request is unauthorized:
-
-  ```js [app/routes/application.js]
-  import { UnauthorizedError } from '@warp-drive/legacy/adapter/error';
-
-  export default class ApplicationRoute extends Route {
-    @action
-    error(error, transition) {
-      if (error instanceof UnauthorizedError) {
-        // go to the login route
-        this.transitionTo('login');
-        return;
-      }
-
-      // ...other error handling logic
-    }
-  }
-  ```
-
-  @class UnauthorizedError
-  @public
-*/
+ * The {@link AdapterRequestError} shape thrown by the {@link UnauthorizedError} constructor.
+ */
 
+/**
+ * A `UnauthorizedError` equates to an HTTP `401 Unauthorized` response
+ * status. It is used by an adapter to signal that a request to the external
+ * API was rejected because authorization is required and has failed or has
+ * not yet been provided.
+ *
+ * An example use case would be to redirect the user to a login route if a
+ * request is unauthorized:
+ *
+ * ```js [app/routes/application.js]
+ * import { UnauthorizedError } from '@warp-drive/legacy/adapter/error';
+ *
+ * export default class ApplicationRoute extends Route {
+ *   @action
+ *   error(error, transition) {
+ *     if (error instanceof UnauthorizedError) {
+ *       // go to the login route
+ *       this.transitionTo('login');
+ *       return;
+ *     }
+ *
+ *     // ...other error handling logic
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 const UnauthorizedError = getOrSetGlobal('UnauthorizedError', extend(AdapterError, 'The adapter operation is unauthorized'));
 UnauthorizedError.prototype.code = 'UnauthorizedError';
 
 /**
-  A `ForbiddenError` equates to a HTTP `403 Forbidden` response status.
-  It is used by an adapter to signal that a request to the external API was
-  valid but the server is refusing to respond to it. If authorization was
-  provided and is valid, then the authenticated user does not have the
-  necessary permissions for the request.
-
-  @class ForbiddenError
-  @public
-*/
+ * The {@link AdapterRequestError} shape thrown by the {@link ForbiddenError} constructor.
+ */
 
+/**
+ * A `ForbiddenError` equates to an HTTP `403 Forbidden` response status.
+ * It is used by an adapter to signal that a request to the external API was
+ * valid but the server is refusing to respond to it. If authorization was
+ * provided and is valid, then the authenticated user does not have the
+ * necessary permissions for the request.
+ *
+ * Unlike an {@link UnauthorizedError}, retrying the request with different
+ * credentials will not help; the currently authenticated user simply lacks
+ * permission. An example use case would be to show the user a "you don't
+ * have access to this" message rather than redirecting them to log in:
+ *
+ * ```js [app/routes/application.js]
+ * import { ForbiddenError } from '@warp-drive/legacy/adapter/error';
+ *
+ * export default class ApplicationRoute extends Route {
+ *   @action
+ *   error(error, transition) {
+ *     if (error instanceof ForbiddenError) {
+ *       this.transitionTo('forbidden');
+ *       return;
+ *     }
+ *
+ *     // ...other error handling logic
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 const ForbiddenError = getOrSetGlobal('ForbiddenError', extend(AdapterError, 'The adapter operation is forbidden'));
 ForbiddenError.prototype.code = 'ForbiddenError';
 
 /**
-  A `NotFoundError` equates to a HTTP `404 Not Found` response status.
-  It is used by an adapter to signal that a request to the external API
-  was rejected because the resource could not be found on the API.
-
-  An example use case would be to detect if the user has entered a route
-  for a specific model that does not exist. For example:
-
-  ```js [app/routes/post.js]
-  import { NotFoundError } from '@warp-drive/legacy/adapter/error';
-
-  export default class PostRoute extends Route {
-    @service store;
-    model(params) {
-      return this.store.findRecord('post', params.post_id);
-    }
-    @action
-    error(error, transition) {
-      if (error instanceof NotFoundError) {
-        // redirect to a list of all posts instead
-        this.transitionTo('posts');
-      } else {
-        // otherwise let the error bubble
-        return true;
-      }
-    }
-  }
-  ```
-
-  @class NotFoundError
-  @public
-*/
+ * The {@link AdapterRequestError} shape thrown by the {@link NotFoundError} constructor.
+ */
 
+/**
+ * A `NotFoundError` equates to an HTTP `404 Not Found` response status.
+ * It is used by an adapter to signal that a request to the external API
+ * was rejected because the resource could not be found on the API.
+ *
+ * An example use case would be to detect if the user has entered a route
+ * for a specific model that does not exist. For example:
+ *
+ * ```js [app/routes/post.js]
+ * import { NotFoundError } from '@warp-drive/legacy/adapter/error';
+ *
+ * export default class PostRoute extends Route {
+ *   @service store;
+ *   model(params) {
+ *     return this.store.findRecord('post', params.post_id);
+ *   }
+ *   @action
+ *   error(error, transition) {
+ *     if (error instanceof NotFoundError) {
+ *       // redirect to a list of all posts instead
+ *       this.transitionTo('posts');
+ *     } else {
+ *       // otherwise let the error bubble
+ *       return true;
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 const NotFoundError = getOrSetGlobal('NotFoundError', extend(AdapterError, 'The adapter could not find the resource'));
 NotFoundError.prototype.code = 'NotFoundError';
 
 /**
-  A `ConflictError` equates to a HTTP `409 Conflict` response status.
-  It is used by an adapter to indicate that the request could not be processed
-  because of a conflict in the request. An example scenario would be when
-  creating a record with a client-generated ID but that ID is already known
-  to the external API.
-
-  @class ConflictError
-  @public
-*/
+ * The {@link AdapterRequestError} shape thrown by the {@link ConflictError} constructor.
+ */
 
+/**
+ * A `ConflictError` equates to an HTTP `409 Conflict` response status.
+ * It is used by an adapter to indicate that the request could not be
+ * processed because of a conflict in the request. An example scenario
+ * would be when creating a record with a client-generated ID but that ID
+ * is already known to the external API.
+ *
+ * An example use case would be to surface a conflict-specific message so
+ * the user can retry with different input:
+ *
+ * ```js [app/routes/application.js]
+ * import { ConflictError } from '@warp-drive/legacy/adapter/error';
+ *
+ * export default class ApplicationRoute extends Route {
+ *   @action
+ *   error(error, transition) {
+ *     if (error instanceof ConflictError) {
+ *       alert('That identifier is already in use, please choose another.');
+ *       return;
+ *     }
+ *
+ *     // ...other error handling logic
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 const ConflictError = getOrSetGlobal('ConflictError', extend(AdapterError, 'The adapter operation failed due to a conflict'));
 ConflictError.prototype.code = 'ConflictError';
 
 /**
-  A `ServerError` equates to a HTTP `500 Internal Server Error` response
-  status. It is used by the adapter to indicate that a request has failed
-  because of an error in the external API.
-
-  @class ServerError
-  @public
-*/
+ * The {@link AdapterRequestError} shape thrown by the {@link ServerError} constructor.
+ */
 
+/**
+ * A `ServerError` equates to an HTTP `500 Internal Server Error` response
+ * status. It is used by the adapter to indicate that a request has failed
+ * because of an error in the external API, and is unlikely to succeed if
+ * retried immediately.
+ *
+ * An example use case would be to show a generic "something went wrong on
+ * our end" message rather than one implying the user made a mistake:
+ *
+ * ```js [app/routes/application.js]
+ * import { ServerError } from '@warp-drive/legacy/adapter/error';
+ *
+ * export default class ApplicationRoute extends Route {
+ *   @action
+ *   error(error, transition) {
+ *     if (error instanceof ServerError) {
+ *       alert('Something went wrong on our end. Please try again later.');
+ *       return;
+ *     }
+ *
+ *     // ...other error handling logic
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 const ServerError = getOrSetGlobal('ServerError', extend(AdapterError, 'The adapter operation failed due to a server error'));
 ServerError.prototype.code = 'ServerError';
 export { AbortError, AdapterError, ConflictError, ForbiddenError, InvalidError, NotFoundError, ServerError, TimeoutError, UnauthorizedError };