Update devel docs via 7938a14

CHANGELOG.md

@@ -19,6 +19,154 @@ This driver uses semantic versioning:
 - A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates _breaking_
   changes that require changes in your code to upgrade.
 
+## [Unreleased]
+
+### Changed
+
+- Errors encountered before a request completes are now wrapped in a `NetworkError`
+
+  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` type
+
+  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 `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` error type
+
+  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` error type
+
+  This error extends `NetworkError` and is thrown when a request deliberately
+  times out using the `timeout` option.
+
+- Added `RequestAbortedError` error type
+
+  This error extends `NetworkError` and is thrown when a request is aborted
+  by using the `db.close` method.
+
+- Added `FetchFailedError` error type
+
+  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` error type
+
+  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 `request` property to `ArangoError`
+
+  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.
+
+- Added `allowDirtyRead` option to `DocumentExistsOptions` type (DE-945)
+
+  This option was previously missing from the type.
+
+- Added `ignoreRevs` option to `CollectionBatchReadOptions` type (DE-947)
+
+  This option was previously missing from the type.
+
+- Added `options` argument to `CollectionTruncateOptions` type (DE-940)
+
+  There was previously no way to pass options to the `truncate` method.
+
+- Added `database` property to `Analyzer`, `ArrayCursor`, `BatchedArrayCursor`,
+  `Collection`, `Graph`, `Job`, `Route`, `Transaction` and `View` types (DE-935)
+
+  This property can be used to access the database instance a given object
+  belongs to.
+
+- Added `headers` and `path` properties to `Route` type
+
+  These properties can be used to access the headers and path used when creating
+  the route.
+
+- Added `id` property to `ArrayCursor` and `BatchedArrayCursor` types (DE-936)
+
+  This property can be used to access the ID of the cursor.
+
 ## [9.1.0] - 2024-09-25
 
 ### Changed

devel/assets/highlight.css

@@ -9,30 +9,28 @@
     --dark-hl-3: #569CD6;
     --light-hl-4: #008000;
     --dark-hl-4: #6A9955;
-    --light-hl-5: #001080;
-    --dark-hl-5: #9CDCFE;
-    --light-hl-6: #CD3131;
-    --dark-hl-6: #F44747;
-    --light-hl-7: #800000;
-    --dark-hl-7: #808080;
-    --light-hl-8: #800000;
-    --dark-hl-8: #569CD6;
-    --light-hl-9: #000000FF;
-    --dark-hl-9: #D4D4D4;
-    --light-hl-10: #E50000;
-    --dark-hl-10: #9CDCFE;
-    --light-hl-11: #0000FF;
-    --dark-hl-11: #CE9178;
+    --light-hl-5: #800000;
+    --dark-hl-5: #808080;
+    --light-hl-6: #800000;
+    --dark-hl-6: #569CD6;
+    --light-hl-7: #000000FF;
+    --dark-hl-7: #D4D4D4;
+    --light-hl-8: #E50000;
+    --dark-hl-8: #9CDCFE;
+    --light-hl-9: #0000FF;
+    --dark-hl-9: #CE9178;
+    --light-hl-10: #AF00DB;
+    --dark-hl-10: #C586C0;
+    --light-hl-11: #001080;
+    --dark-hl-11: #9CDCFE;
     --light-hl-12: #0070C1;
     --dark-hl-12: #4FC1FF;
-    --light-hl-13: #AF00DB;
-    --dark-hl-13: #C586C0;
-    --light-hl-14: #098658;
-    --dark-hl-14: #B5CEA8;
-    --light-hl-15: #267F99;
-    --dark-hl-15: #4EC9B0;
-    --light-hl-16: #EE0000;
-    --dark-hl-16: #D7BA7D;
+    --light-hl-13: #098658;
+    --dark-hl-13: #B5CEA8;
+    --light-hl-14: #267F99;
+    --dark-hl-14: #4EC9B0;
+    --light-hl-15: #EE0000;
+    --dark-hl-15: #D7BA7D;
     --light-code-background: #FFFFFF;
     --dark-code-background: #1E1E1E;
 }
@@ -54,7 +52,6 @@
     --hl-13: var(--light-hl-13);
     --hl-14: var(--light-hl-14);
     --hl-15: var(--light-hl-15);
-    --hl-16: var(--light-hl-16);
     --code-background: var(--light-code-background);
 } }
 
@@ -75,7 +72,6 @@
     --hl-13: var(--dark-hl-13);
     --hl-14: var(--dark-hl-14);
     --hl-15: var(--dark-hl-15);
-    --hl-16: var(--dark-hl-16);
     --code-background: var(--dark-code-background);
 } }
 
@@ -96,7 +92,6 @@
     --hl-13: var(--light-hl-13);
     --hl-14: var(--light-hl-14);
     --hl-15: var(--light-hl-15);
-    --hl-16: var(--light-hl-16);
     --code-background: var(--light-code-background);
 }
 
@@ -117,7 +112,6 @@
     --hl-13: var(--dark-hl-13);
     --hl-14: var(--dark-hl-14);
     --hl-15: var(--dark-hl-15);
-    --hl-16: var(--dark-hl-16);
     --code-background: var(--dark-code-background);
 }
 
@@ -137,5 +131,4 @@
 .hl-13 { color: var(--hl-13); }
 .hl-14 { color: var(--hl-14); }
 .hl-15 { color: var(--hl-15); }
-.hl-16 { color: var(--hl-16); }
 pre, code { background: var(--code-background); }