From defd6aae86fe3ff0b4437c226870703a6709738e Mon Sep 17 00:00:00 2001 From: Alan Plum Date: Fri, 22 Nov 2024 15:33:39 +0100 Subject: [PATCH] Update README.md --- README.md | 82 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 42 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 58198807..5c48a172 100644 --- a/README.md +++ b/README.md @@ -139,30 +139,51 @@ 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 -### Missing functions or unexpected server errors +### Unexpected server errors Please make sure you are using the latest version of this driver and that the version of the arangojs documentation you are reading matches that version. -Changes in the major version number of arangojs (e.g. 7.x.y -> 8.0.0) indicate +Changes in the major version number of arangojs (e.g. 8.x.y -> 9.0.0) indicate backwards-incompatible changes in the arangojs API that may require changes in your code when upgrading your version of arangojs. @@ -170,19 +191,13 @@ 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. -**Note**: As of June 2018 ArangoDB 2.8 has reached its End of Life and is no -longer supported in arangojs 7 and later. If your code needs to work with -ArangoDB 2.8 you can continue using arangojs 6 and enable ArangoDB 2.8 -compatibility mode by setting the config option `arangoVersion: 20800` to -enable the ArangoDB 2.8 compatibility mode in arangojs 6. - You can install an older version of arangojs using `npm` or `yarn`: ```sh -# for version 6.x.x -yarn add arangojs@6 +# for version 8.x.x +yarn add arangojs@8 # - or - -npm install --save arangojs@6 +npm install --save arangojs@8 ``` ### No code intelligence when using require instead of import @@ -254,23 +269,6 @@ 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. -### Node.js `ReferenceError: window is not defined` - -If you compile your Node project using a build tool like Webpack, you may need -to tell it to -[target the correct environment](https://webpack.js.org/configuration/target/): - -```diff -// webpack.config.js -+ "target": "node", -``` - -To support use in both browser and Node environments arangojs uses the -[`package.json` `browser` field](https://github.com/defunctzombie/package-browser-field-spec), -to substitute browser-specific implementations for certain modules. -Build tools like Webpack will respect this field when targetting a browser -environment and may need to be explicitly told you are targetting Node instead. - ### Node.js with self-signed HTTPS certificates If you need to support self-signed HTTPS certificates in Node.js, you may have @@ -308,6 +306,9 @@ setGlobalDispatcher( ); ``` +This 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 be trusted by the browser or use a trusted root certificate. @@ -331,7 +332,8 @@ await trx.step(() => collection.save(doc1)); await trx.step(() => collection.save(doc2)); ``` -Please refer to the documentation of this method for additional examples. +Please refer to the [documentation of the `transaction.step` method](https://arangodb.github.io/arangojs/latest/classes/transaction.Transaction.html#step) +for additional examples. ### Streaming transactions timeout in cluster