@warp-drive/legacy 5.9.0-beta.0 → 5.9.0-beta.2

package/dist/error-CzkyXr1Q.d.ts

@@ -0,0 +1,435 @@
+import { ApiError } from "@warp-drive/core/types/spec/error";
+//#region src/adapter/error.d.ts
+/**
+ * The shape of the errors thrown/returned by {@link AdapterError} and its subclasses.
+ */
+interface AdapterRequestError<T extends string = string> extends Error {
+  /**
+   * A property signifying that an Error uses the {@link AdapterRequestError} interface.
+   */
+  isAdapterError: true;
+  /**
+   * A short code identifying the kind of error, e.g. `'NotFoundError'`.
+   */
+  code: T;
+  /**
+   * The {json:api} formatted errors associated with the request.
+   */
+  errors: ApiError[];
+}
+/**
+ * The static interface shared by {@link AdapterError} and its subclasses,
+ * allowing further subclassing via {@link AdapterRequestErrorConstructor.extend | extend}.
+ */
+interface AdapterRequestErrorConstructor<Instance extends AdapterRequestError = AdapterRequestError> {
+  new (errors?: unknown[], message?: string): Instance;
+  /**
+   * Creates a new {@link AdapterRequestErrorConstructor} that inherits from this one.
+   */
+  extend(options: {
+    message: string;
+  }): AdapterRequestErrorConstructor;
+}
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link AdapterError} constructor.
+ */
+type AdapterError = AdapterRequestError<"AdapterError">;
+/**
+ * :::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
+ */
+declare const AdapterError: AdapterRequestErrorConstructor<AdapterError>;
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link InvalidError} constructor.
+ */
+type InvalidError = AdapterRequestError<"InvalidError">;
+/**
+ * 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
+ */
+declare const InvalidError: AdapterRequestErrorConstructor<InvalidError>;
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link TimeoutError} constructor.
+ */
+type TimeoutError = AdapterRequestError<"TimeoutError">;
+/**
+ * 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
+ */
+declare const TimeoutError: AdapterRequestErrorConstructor<TimeoutError>;
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link AbortError} constructor.
+ */
+type AbortError = AdapterRequestError<"AbortError">;
+/**
+ * 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
+ */
+declare const AbortError: AdapterRequestErrorConstructor<AbortError>;
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link UnauthorizedError} constructor.
+ */
+type UnauthorizedError = AdapterRequestError<"UnauthorizedError">;
+/**
+ * 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
+ */
+declare const UnauthorizedError: AdapterRequestErrorConstructor<UnauthorizedError>;
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link ForbiddenError} constructor.
+ */
+type ForbiddenError = AdapterRequestError<"ForbiddenError">;
+/**
+ * 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
+ */
+declare const ForbiddenError: AdapterRequestErrorConstructor<ForbiddenError>;
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link NotFoundError} constructor.
+ */
+type NotFoundError = AdapterRequestError<"NotFoundError">;
+/**
+ * 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
+ */
+declare const NotFoundError: AdapterRequestErrorConstructor<NotFoundError>;
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link ConflictError} constructor.
+ */
+type ConflictError = AdapterRequestError<"ConflictError">;
+/**
+ * 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
+ */
+declare const ConflictError: AdapterRequestErrorConstructor<ConflictError>;
+/**
+ * The {@link AdapterRequestError} shape thrown by the {@link ServerError} constructor.
+ */
+type ServerError = AdapterRequestError<"ServerError">;
+/**
+ * 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
+ */
+declare const ServerError: AdapterRequestErrorConstructor<ServerError>;
+//#endregion
+export { ConflictError as a, NotFoundError as c, UnauthorizedError as d, AdapterRequestErrorConstructor as i, ServerError as l, AdapterError as n, ForbiddenError as o, AdapterRequestError as r, InvalidError as s, AbortError as t, TimeoutError as u };
+//# sourceMappingURL=error-CzkyXr1Q.d.ts.map

package/dist/error-CzkyXr1Q.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-CzkyXr1Q.d.ts","names":[],"sources":["../src/adapter/error.ts"],"mappings":";;;;;UAuCiB,oBAAoB,mCAAmC;;;;EAItE;;;;EAIA,MAAM;;;;EAIN,QAAQ;;;;;;UAMO,+BAA+B,iBAAiB,sBAAsB;OAChF,oBAAoB,mBAAmB;;;;EAI5C,OAAO;IAAW;MAAoB;;;;;KAW5B,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmGd,cAAc,+BAA+B;;;;KA8B9C,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA0Dd,cAAc,+BAA+B;;;;KAS9C,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4Bd,cAAc,+BAA+B;;;;KAS9C,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8BZ,YAAY,+BAA+B;;;;KAS5C,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6BnB,mBAAmB,+BAA+B;;;;KASnD,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BhB,gBAAgB,+BAA+B;;;;KAShD,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgCf,eAAe,+BAA+B;;;;KAS/C,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6Bf,eAAe,+BAA+B;;;;KAS/C,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4Bb,aAAa,+BAA+B"}