arangojs 9.2.0 → 10.0.0-alpha.1

package/CHANGELOG.md

@@ -14,6 +14,397 @@ 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.
 
+## [10.0.0-alpha.1] - 2024-12-09
+
+This is a major release and breaks backwards compatibility.
+
+See [the migration guide](./MIGRATING.md#v9-to-v10) for detailed instructions
+for upgrading your code to arangojs v10.
+
+### Changed
+
+- Renamed `CollectionDropOptions` type to `DropCollectionOptions`
+
+- Renamed `CollectionTruncateOptions` type to `TruncateCollectionOptions`
+
+- Renamed `Config` type to `ConfigOptions`
+
+- Renamed `path` option to `pathname` in `RequestOptions` type
+
+  This affects the `db.waitForPropagation` and `route.request` methods.
+
+- Removed `basePath` option from `RequestOptions` type
+
+  This affects the `db.waitForPropagation` and `route.request` methods.
+
+- Renamed `route.path` property to `route.pathname`
+
+- Changed error type constructor signatures
+
+  The `request` property is now always positional and the `options` property
+  is always optional.
+
+- Moved configuration related types to new `config` module
+
+  The following types were moved: `Config`, `LoadBalancingStrategy`,
+  `BasicAuthCredentials` and `BearerAuthCredentials`.
+
+- Moved `ArangoErrorResponse` type to `connection` module
+
+  The type is now also no longer marked as internal.
+
+- Moved configuration related types to new `configuration` module
+
+  The following types were moved: `ConfigOptions`, `LoadBalancingStrategy`,
+  `BasicAuthCredentials` and `BearerAuthCredentials`.
+
+- Moved internal utility functions to new `lib/util` module
+
+  These methods are all still marked as internal and should not be used
+  directly.
+
+- Closing a connection now closes all open requests
+
+  Previously in certain situations only the most recent request would be
+  closed per server. Note that this still merely aborts the requests but
+  does not guarantee the underlying connections are closed as these are
+  handled by Node.js or the browser natively.
+
+### Added
+
+- Restored support for Unix domain sockets
+
+  Using Unix domain sockets requires the `undici` library to be installed.
+
+- Restored support for `config.agentOptions`
+
+  The `config.agentOptions` option can now be used to create a custom `undici`
+  agent if the `undici` library is installed.
+
+## [10.0.0-alpha.0] - 2024-11-28
+
+This is a major release and breaks backwards compatibility.
+
+See [the migration guide](./MIGRATING.md#v9-to-v10) for detailed instructions
+for upgrading your code to arangojs v10.
+
+### Removed
+
+- Removed unused `CreateUserOptions` type
+
+  The actual type used by the `db.createUser` method is still `UserOptions`.
+
+- Removed unused `IndexDetails` type
+
+  This type was intended to be returned by `collection.indexes` when the
+  `withStats` option is set to `true` but the `figures` property is already
+  included in the current return type.
+
+### Changed
+
+- Changed `QueueTimeMetrics` type to an interface
+
+- Changed `CursorExtras` and `CursorStats` interfaces to types
+
+- Changed `GraphVertexCollection` and `GraphEdgeCollection` generic types to
+  take separate `EntryResultType` and `EntryInputType` type parameters
+
+- Changed `db.collection`, `db.createCollection` and `db.createEdgeCollection`
+  methods to take separate `EntryResultType` and `EntryInputType` type
+  parameters
+
+  These type parameters are used to narrow the the returned collection type.
+
+- Renamed `db.listServiceScripts` method to `db.getServiceScripts`
+- Renamed `db.listHotBackups` method to `db.getHotBackups`
+- Renamed `db.getLogMessages` method to `db.listLogMessages`
+- Renamed `db.listFunctions` method to `db.listUserFunctions`
+- Renamed `db.createFunction` method to `db.createUserFunction`
+- Renamed `db.dropFunction` method to `db.dropUserFunction`
+- Changed `db.removeUser` method to return `void`
+
+#### Module renaming
+
+- Renamed most modules to plural form for consistency
+
+  The following modules were renamed:
+
+  - `arangojs/analyzer` -> `arangojs/analyzers`
+  - `arangojs/collection` -> `arangojs/collections`
+  - `arangojs/cursor` -> `arangojs/cursors`
+  - `arangojs/database` -> `arangojs/databases`
+  - `arangojs/error` -> `arangojs/errors`
+  - `arangojs/graph` -> `arangojs/graphs`
+  - `arangojs/job` -> `arangojs/jobs`
+  - `arangojs/route` -> `arangojs/routes`
+  - `arangojs/transaction` -> `arangojs/transactions`
+  - `arangojs/view` -> `arangojs/views`
+
+#### Moved types
+
+- Moved document related types from `arangojs/collection` module to
+  `arangojs/documents` module
+
+  The following types were moved: `DocumentOperationFailure`,
+  `DocumentOperationMetadata`, `DocumentExistsOptions`, 
+  `CollectionReadOptions`, `CollectionBatchReadOptions`,
+  `CollectionInsertOptions`, `CollectionReplaceOptions`,
+  `CollectionUpdateOptions`, `CollectionRemoveOptions`,
+  `CollectionImportOptions`, `CollectionEdgesOptions`,
+  `CollectionImportResult` and `CollectionEdgesResult`
+
+- Moved index related types from `arangojs/collection` module to
+  `arangojs/indexes` module
+
+  The following types were moved: `IndexListOptions`.
+
+- Moved transaction related types from `arangojs/database` module to
+  `arangojs/transactions` module
+
+  The following types were moved: `TransactionCollections`,
+  `TransactionOptions` and `TransactionDetails`.
+
+- Moved cluster related types from `arangojs/database` module to new
+  `arangojs/clusters` module
+
+  The following types were moved: `ClusterImbalanceInfo`,
+  `ClusterRebalanceState`, `ClusterRebalanceOptions`, `ClusterRebalanceMove`
+  and `ClusterRebalanceResult`.
+
+- Moved hot backup related types from `arangojs/database` module to new
+  `arangojs/hot-backups` module
+
+  The following types were moved: `HotBackupOptions`, `HotBackupResult` and
+  `HotBackupList`.
+
+- Moved query related types from `arangojs/database` module to new
+  `arangojs/queries` module
+
+  The following types were moved: `QueryOptions`, `ExplainOptions`,
+  `ExplainPlan`, `ExplainStats`, `SingleExplainResult`, `MultiExplainResult`,
+  `AstNode`, `ParseResult`, `QueryOptimizerRule`, `QueryTracking`,
+  `QueryTrackingOptions`, `QueryInfo` and `AqlUserFunction`.
+
+- Moved service related types from `arangojs/database` module to new
+  `arangojs/services` module
+
+  The following types were moved: `InstallServiceOptions`,
+  `ReplaceServiceOptions`, `UpgradeServiceOptions`, `UninstallServiceOptions`,
+  `ServiceSummary`, `ServiceInfo`, `ServiceConfiguration`,
+  `SingleServiceDependency`, `MultiServiceDependency`, `ServiceTestStats`,
+  `ServiceTestStreamTest`, `ServiceTestStreamReport`, `ServiceTestSuiteTest`,
+  `ServiceTestSuite`, `ServiceTestSuiteReport`, `ServiceTestXunitTest`,
+  `ServiceTestXunitReport`, `ServiceTestTapReport`, `ServiceTestDefaultTest`,
+  `ServiceTestDefaultReport` and `SwaggerJson`.
+
+- Moved user related types from `arangojs/database` module to new
+  `arangojs/users` module
+
+  The following types were moved: `AccessLevel`, `ArangoUser`, `UserOptions`,
+  `UserAccessLevelOptions` and `CreateDatabaseUser`.
+
+- Moved server administration related types from `arangojs/database` module to
+  new `arangojs/administration` module
+
+  The following types were moved: `QueueTimeMetrics` and `VersionInfo`.
+
+#### Renamed types
+
+- Renamed `Index` types to `IndexDescription` for consistency
+
+  The specific index types were also renamed accordingly:
+
+  - `Index` -> `IndexDescription`
+  - `GeoIndex` -> `GeoIndexDescription`
+  - `PersistentIndex` -> `PersistentIndexDescription`
+  - `PrimaryIndex` -> `PrimaryIndexDescription`
+  - `TtlIndex` -> `TtlIndexDescription`
+  - `MdiIndex` -> `MdiIndexDescription`
+  - `InvertedIndex` -> `InvertedIndexDescription`
+  - `InternalArangosearchIndex` -> `ArangosearchIndexDescription`
+  - `InternalIndex` -> `InternalIndexDescription`
+  - `HiddenIndex` -> `HiddenIndexDescription`
+
+  Note that the "Internal" prefix was dropped from `ArangosearchIndexDescription`
+  to more accurately reflect the index type name. The index type still refers
+  to an internal index, however.
+
+- Renamed various types for consistency:
+
+  - `AqlUserFunction` -> `UserFunctionDescription`
+  - `CollectionMetadata` -> `CollectionDescription`
+  - `DatabaseInfo` -> `DatabaseDescription`
+  - `GraphInfo` -> `GraphDescription`
+  - `ServiceInfo` -> `ServiceDescription`
+  - `QueryInfo` -> `QueryDescription`
+  - `QueryTracking` -> `QueryTrackingInfo`
+  - `TransactionDetails` -> `TransactionInfo`
+  - `TransactionCollections` -> `TransactionCollectionOptions`
+  - `CreateDatabaseUser` -> `CreateDatabaseUserOptions`
+
+  - Index operations:
+    - `IndexListOptions` -> `ListIndexesOptions`
+
+  - Collection document operations:
+    - `DocumentExistsOptions` -> `DocumentExistsOptions`
+    - `CollectionReadOptions` -> `ReadDocumentOptions`
+    - `CollectionBatchReadOptions` -> `BulkReadDocumentsOptions`
+    - `CollectionInsertOptions` -> `InsertDocumentOptions`
+    - `CollectionReplaceOptions` -> `ReplaceDocumentOptions`
+    - `CollectionUpdateOptions` -> `UpdateDocumentOptions`
+    - `CollectionRemoveOptions` -> `RemoveDocumentOptions`
+    - `CollectionImportOptions` -> `ImportDocumentsOptions`
+    - `CollectionEdgesOptions` -> `DocumentEdgesOptions`
+    - `CollectionImportResult` -> `ImportDocumentsResult`
+    - `CollectionEdgesResult` -> `DocumentEdgesResult`
+
+  - Graph collection document operation:
+    - `GraphCollectionReadOptions` -> `ReadGraphDocumentOptions`
+    - `GraphCollectionInsertOptions` -> `CreateGraphDocumentOptions`
+    - `GraphCollectionReplaceOptions` -> `ReplaceGraphDocumentOptions`
+    - `GraphCollectionRemoveOptions` -> `RemoveGraphDocumentOptions`
+    - `ViewPatchPropertiesOptions` -> `UpdateViewPropertiesOptions`
+
+  - View operations:
+    - `ArangoSearchViewPatchPropertiesOptions` -> `UpdateArangoSearchViewPropertiesOptions`
+    - `SearchAliasViewPatchPropertiesOptions` -> `UpdateSearchAliasViewPropertiesOptions`
+    - `SearchAliasViewPatchIndexOptions` -> `UpdateSearchAliasViewIndexOptions`
+    - `ArangoSearchViewStoredValueOptions` -> `CreateArangoSearchViewStoredValueOptions`
+
+- Renamed `ArrayCursor` and `BatchedArrayCursor` classes to `Cursor` and
+  `BatchCursor` respectively
+
+  The previous name was misleading because it conflicted with how the ArangoDB
+  distinguishes between array cursors and streaming cursors in the interactive
+  shell. This distinction does not apply to the driver.
+
+- Renamed various types to reduce ambiguity:
+
+  - `ObjectWithId` (in `indexes` module) -> `ObjectWithIndexId`
+  - `ObjectWithId` (in `documents` module) -> `ObjectWithDocumentId`
+  - `ObjectWithKey` (in `documents` module) -> `ObjectWithDocumentKey`
+
+#### Error handling
+
+- 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 `BatchCursor#itemsView` property and `BatchCursorItemsView` interface
+
+  This property provides a low-level interface for consuming the items of the
+  cursor and is used by the regular item-wise `Cursor` class internally.
+
+- 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.
+
 ## [9.2.0] - 2024-11-27
 
 ### Added
@@ -66,6 +457,8 @@ This driver uses semantic versioning:
   This property is only available when fetching indexes with the `withHidden`
   option set to `true`.
 
+### Added
+
 - Added `HiddenIndex` type (DE-849)
 
   This type is used to represent an index returned by `collection.indexes` when
@@ -1962,6 +2355,8 @@ For a detailed list of changes between pre-release versions of v7 see the
 
   Graph methods now only return the relevant part of the response body.
 
+[10.0.0-alpha.1]: https://github.com/arangodb/arangojs/compare/v10.0.0-alpha.0...v10.0.0-alpha.1
+[10.0.0-alpha.0]: https://github.com/arangodb/arangojs/compare/v9.2.0...v10.0.0-alpha.0
 [9.2.0]: https://github.com/arangodb/arangojs/compare/v9.1.0...v9.2.0
 [9.1.0]: https://github.com/arangodb/arangojs/compare/v9.0.0...v9.1.0
 [9.0.0]: https://github.com/arangodb/arangojs/compare/v8.8.1...v9.0.0

package/MIGRATING.md

@@ -1,5 +1,55 @@
 # Migrating
 
+## v9 to v10
+
+Version 10 changes the error handling to make it easier to diagnose network
+issues and distinguish between different error conditions.
+
+If you previously inspected errors other than `ArangoError` and `HttpError`
+directly, you should now expect to see `NetworkError` or a subclass thereof
+instead. The originating error can be found using the `cause` property of the
+`NetworkError` error:
+
+```js
+try {
+  await db.collection("my-collection").get();
+} catch (err) {
+  if (err instanceof NetworkError) console.log(err.cause);
+}
+```
+
+### Module name changes
+
+Module names referring to resource types such as analyzers, collections,
+databases, or views have been changed to use the plural form:
+
+```diff
+-import { Database } from "arangojs/database";
++import { Database } from "arangojs/databases";
+```
+
+Note that the `aql` module and `foxx-manifest` modules have not been renamed
+as these are utility modules.
+
+### Type imports
+
+Types that were previously exported by the `database` module but are not
+related to managing databases have been moved to separate modules:
+
+```diff
+-import type {
+-  ParseResult,
+-  TransactionOptions,
+-  VersionInfo
+-} from "arangojs/database";
++import type { VersionInfo } from "arangojs/administration";
++import type { TransactionOptions } from "arangojs/transactions";
++import type { ParseResult } from "arangojs/queries";
+```
+
+Additionally, some types were renamed. For a full list of changes, see the
+[changelog](./CHANGELOG.md).
+
 ## v8 to v9
 
 Version 9 reverts the automatic NFC normalization introduced in v7.7.0. This

package/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
@@ -225,7 +255,7 @@ allowing arangojs to provide more meaningful stack traces at the cost of an
 impact to performance even when no error occurs.
 
 ```diff
-  const { Database } = require("arangojs");
+  import { Database } from "arangojs";
 
   const db = new Database({
     url: ARANGODB_SERVER,
@@ -239,15 +269,47 @@ that do not support the `stack` property on error objects, this option will
 still impact performance but not result in any additional information becoming
 available.
 
+### Unix domain sockets
+
+If you want to use Unix domain sockets, you need to install the `undici` module,
+which is an optional dependency of arangojs.
+
+```sh
+npm install --save undici
+```
+
+If the `undici` module is not installed and arangojs attempts to make a request
+over a Unix domain socket, the request will fail with a plain `Error` with a
+message indicating that the `undici` module is unavailable.
+
 ### Node.js with self-signed HTTPS certificates
 
-If you need to support self-signed HTTPS certificates in Node.js, you may have
-to override the global fetch agent. At the time of this writing, there is no
-official way to do this for the native `fetch` implementation in Node.js.
+If you need to support self-signed HTTPS certificates in Node.js, you will need
+to install the `undici` module, which is an optional dependency of arangojs.
 
-However as Node.js uses the `undici` module for its `fetch` implementation
-internally, you can override the global agent by adding `undici` as a
-dependency to your project and using its `setGlobalDispatcher` as follows:
+```sh
+npm install --save undici
+```
+
+You can instruct arangojs to use the `undici` module by setting the
+`config.agentOptions` option:
+
+```diff
+  import { Database } from "arangojs";
+
+  const db = new Database({
+    url: ARANGODB_SERVER,
++   agentOptions: {
++     ca: [
++       fs.readFileSync(".ssl/sub.class1.server.ca.pem"),
++       fs.readFileSync(".ssl/ca.pem"),
++     ],
++   },
+  });
+```
+
+To override the global fetch agent instead, you can use the `undici` module's
+`setGlobalDispatcher` method as follows:
 
 ```js
 import { Agent, setGlobalDispatcher } from "undici";
@@ -263,20 +325,22 @@ setGlobalDispatcher(
 ```
 
 Although this is **strongly discouraged**, it's also possible to disable
-HTTPS certificate validation entirely, but note this has
+HTTPS certificate validation entirely this way, but note this has
 **extremely dangerous** security implications:
 
-```js
-import { Agent, setGlobalDispatcher } from "undici";
+```diff
+  import { Database } from "arangojs";
 
-setGlobalDispatcher(
-  new Agent({
-    rejectUnauthorized: false,
-  })
-);
+  const db = new Database({
+    url: ARANGODB_SERVER,
++   agentOptions: {
++     rejectUnauthorized: false,
++   },
+  });
 ```
 
-This is a [known limitation](https://github.com/orgs/nodejs/discussions/44038#discussioncomment-5701073)
+The requirement to use the `undici` module to override these settings is a
+[known limitation](https://github.com/orgs/nodejs/discussions/44038#discussioncomment-5701073)
 of Node.js at the time of this writing.
 
 When using arangojs in the browser, self-signed HTTPS certificates need to