Revert "Revert "Change request/error handling""

This reverts commit 8914dab.

Author: pluma

CHANGELOG.md

@@ -16,6 +16,59 @@ This driver uses semantic versioning:
 
 ## [9.2.0] - 2024-11-27
 
+### Changed
+
+- Errors encountered before a request completes are now wrapped in a
+  `NetworkError` or a subclass thereof
+
+  This should help making it easier to diagnose network issues and distinguish
+  the relevant error conditions.
+
+  The originating error can still be accessed using the `cause` property of the
+  `NetworkError` error.
+
+- `HttpError` now extends the `NetworkError` class
+
+  This allows treating all non-`ArangoError` errors as one category of errors,
+  even when there is no server response available.
+
+- `db.waitForPropagation` now throws a `PropagationTimeoutError` error when
+  invoked with a `timeout` option and the timeout duration is exceeded
+
+  The method would previously throw the most recent error encountered while
+  waiting for replication. The originating error can still be accessed using
+  the `cause` property of the `PropagationTimeoutError` error.
+
+- `db.waitForPropagation` now respects the `timeout` option more strictly
+
+  Previously the method would only time out if the timeout duration was
+  exceeded after the most recent request failed. Now the timeout is
+  recalculated and passed on to each request, preventing it from exceeding
+  the specified duration.
+
+  If the propagation timed out due to an underlying request exceeding the
+  timeout duration, the `cause` property of the `PropagationTimeoutError`
+  error will be a `ResponseTimeoutError` error.
+
+- `config.beforeRequest` and `config.afterResponse` callbacks can now return
+  promises
+
+  If the callback returns a promise, it will be awaited before the request
+  and response cycle proceeds. If either callback throws an error or returns
+  a promise that is rejected, that error will be thrown instead.
+
+- `config.afterResponse` callback signature changed
+
+  The callback signature previously used the internal `ArangojsResponse` type.
+  The new signature uses the `Response` type of the Fetch API with an
+  additional `request` property to more accurately represent the actual value
+  it receives as the `parsedBody` property will never be present.
+
+- `response` property on `ArangoError` is now optional
+
+  This property should always be present but this allows using the error in
+  situations where a response might not be available.
+
 ### Added
 
 - Added `database.availability` method
@@ -26,6 +79,67 @@ This driver uses semantic versioning:
 
 - Added `database.supportInfo` method
 
+- Added `onError` option to `Config` (DE-955)
+
+  This option can be used to specify a callback function that will be invoked
+  whenever a request results in an error. Unlike `afterResponse`, this callback
+  will be invoked even if the request completed but returned an error status.
+  In this case the error will be the `HttpError` or `ArangoError` representing
+  the error response.
+
+  If the `onError` callback throws an error or returns a promise that is
+  rejected, that error will be thrown instead.
+
+- Added `NetworkError` class
+
+  This is the common base class for all errors (including `HttpError`) that
+  occur while making a request. The originating error can be accessed using the
+  `cause` property. The request object can be accessed using the `request`
+  property.
+
+  Note that `ArangoError` and the new `PropagationTimeoutError` error type
+  do not extend `NetworkError` but may wrap an underlying error, which can
+  be accessed using the `cause` property.
+
+- Added `ResponseTimeoutError` class
+
+  This error extends `NetworkError` and is thrown when a request deliberately
+  times out using the `timeout` option.
+
+- Added `RequestAbortedError` class
+
+  This error extends `NetworkError` and is thrown when a request is aborted
+  by using the `db.close` method.
+
+- Added `FetchFailedError` class
+
+  This error extends `NetworkError` and is thrown when a request fails because
+  the underlying `fetch` call fails (usually with a `TypeError`).
+
+  In Node.js the root cause of this error (e.g. a network failure) can often be
+  found in the `cause` property of the originating error, i.e. the `cause`
+  property of the `cause` property of this error.
+
+  In browsers the root cause is usually not exposed directly but can often
+  be diagnosed by examining the developer console or network tab.
+
+- Added `PropagationTimeoutError` class
+
+  This error does not extend `NetworkError` but wraps the most recent error
+  encountered while waiting for replication, which can be accessed using the
+  `cause` property. This error is only thrown when `db.waitForPropagation`
+  is invoked with a `timeout` option and the timeout duration is exceeded.
+
+- Added `ProcessedResponse` type
+
+  This type replaces the previously internal `ArangojsResponse` type and
+  extends the native `Response` type with additional properties.
+
+- Added optional `ArangoError#request` property
+
+  This property is always present if the error has a `response` property. In
+  normal use this should always be the case.
+
 - Added `keepNull` option to `CollectionInsertOptions` type (DE-946)
 
   This option was previously missing from the type.

README.md

@@ -139,21 +139,42 @@ and [the `db` object](https://www.arangodb.com/docs/stable/appendix-references-d
 
 ## Error responses
 
-If arangojs encounters an API error, it will throw an `ArangoError` with
-an `errorNum` property indicating the ArangoDB error code and the `code`
-property indicating the HTTP status code from the response body.
+If the server returns an ArangoDB error response, arangojs will throw an
+`ArangoError` with an `errorNum` property indicating the ArangoDB error code
+and expose the response body as the `response` property of the error object.
 
-For any other non-ArangoDB error responses (4xx/5xx status code), it will throw
-an `HttpError` error with the status code indicated by the `code` property.
+For all other errors during the request/response cycle, arangojs will throw a
+`NetworkError` or a more specific subclass thereof and expose the originating
+request object as the `request` property of the error object.
 
-If the server response did not indicate an error but the response body could
-not be parsed, a regular `SyntaxError` may be thrown instead.
+If the server responded with a non-2xx status code, this `NetworkError` will
+be an `HttpError` with a `code` property indicating the HTTP status code of the
+response and a `response` property containing the response object itself.
 
-In all of these cases the server response object will be exposed as the
-`response` property on the error object.
+If the error is caused by an exception, the originating exception will be
+available as the `cause` property of the error object thrown by arangojs. For
+network errors, this will often be a `TypeError`.
 
-If the request failed at a network level or the connection was closed without
-receiving a response, the underlying system error will be thrown instead.
+### Node.js network errors
+
+In Node.js, network errors caused by a `TypeError` will often have a `cause`
+property containing a more detailed exception.
+
+Specifically, these are often either system errors (represented by regular
+`Error` objects with additional properties) or errors from the `undici` module
+Node.js uses internally for its native `fetch` implementation.
+
+Node.js system error objects provide a `code` property containing the specific
+string error code, a `syscall` property identifying the underlying system call
+that triggered the error (e.g. `connect`), as well as other helpful properties.
+
+For more details on Node.js system errors, see the Node.js documentation of the
+[`SystemError` interface](https://nodejs.org/api/errors.html#class-systemerror)
+as well as the section on
+[Node.js error codes](https://nodejs.org/api/errors.html#nodejs-error-codes).
+
+For more details on the errors thrown by `undici`, see the
+[undici errors documentation](https://undici.nodejs.org/#/docs/api/Errors.md).
 
 ## Common issues
 
@@ -170,6 +191,15 @@ Additionally please ensure that your version of Node.js (or browser) and
 ArangoDB are supported by the version of arangojs you are trying to use. See
 the [compatibility section](#compatibility) for additional information.
 
+You can install an older version of arangojs using `npm` or `yarn`:
+
+```sh
+# for version 8.x.x
+yarn add arangojs@8
+# - or -
+npm install --save arangojs@8
+```
+
 ### No code intelligence when using require instead of import
 
 If you are using `require` to import the `arangojs` module in JavaScript, the