arangojs 7.8.0 → 8.0.0

package/CHANGELOG.md

@@ -14,6 +14,266 @@ 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.
 
+## [8.0.0] - 2022-10-25
+
+This is a major release and breaks backwards compatibility.
+
+See [the migration guide](./MIGRATING.md#v7-to-v8) for detailed instructions
+for upgrading your code to arangojs v8.
+
+### Removed
+
+- Removed Node.js 10 and Node.js 12 support
+
+  With Node.js 10 and 12 having reached their end of life, arangojs will no
+  longer support these versions of Node.js going forward.
+
+- Removed Internet Explorer and older browser support
+
+  As of version 8 arangojs uses the [Browserlist `defaults`](https://browsersl.ist/#q=defaults)
+  list to generate the pre-built browser bundle, which excludes older browsers
+  and specifically all versions of Internet Explorer.
+
+  You may still be able to use arangojs in some of the excluded browsers when
+  bundling arangojs yourself but this may require polyfills and additional
+  transformations.
+
+- Removed `Dict` type from `connection` module
+
+  The `Dict<T>` type was identical to `Record<string, T>` and has been replaced
+  with this built-in type across arangojs.
+
+- Removed workaround for ArangoDB pre-3.2.8 Foxx HTTP API responses
+
+  When fetching or modifying the configuration or dependencies of a Foxx
+  service using ArangoDB 3.2.7 and earlier, arangojs would perform additional
+  operations to convert the server response to a compatible format. All
+  affected versions of ArangoDB have reached End of Life since December 2018.
+
+- Removed deprecated `db.useDatabase` method
+
+  The method was previously deprecated and can be replaced with `db.database`,
+  which returns a new `Database` object instead of modifying the existing one.
+
+- Removed deprecated MMFiles methods and types
+
+  The MMFiles storage engine was removed in ArangoDB 3.7.
+
+- Removed deprecated `minReplicationFactor` option from collection and
+  database related types
+
+  This option was renamed to `writeConcern` in ArangoDB 3.6.
+
+- Removed deprecated `overwrite` option from `CollectionInsertOptions` type
+
+  This option was deprecated in ArangoDB 3.7 and should be replaced with the
+  `overwriteMode` option.
+
+- Removed internal `request.host` attribute
+
+  This attribute has been replaced with `request.hostUrl`.
+
+- Removed internal `response.arangojsHostId` attribute
+
+  This attribute has been replaced with `response.arangojsHostUrl`.
+
+- Removed `CollectionStatus` and `CollectionType` enum re-exports
+
+  Previously these would be re-exported by the arangojs module for backwards
+  compatibility. If you still need to access these enums, you can import them
+  from the `collection` sub-module instead. Note that the `ViewType` enum
+  has been removed completely.
+
+### Changed
+
+- Changed default URL to `http://127.0.0.1:8529` to match ArangoDB default
+
+  Previously arangojs would use `localhost` which on some systems resolves to
+  the IPv6 address `::1` instead, resulting in confusing connection errors.
+
+- Changed TypeScript compilation target to ES2020
+
+  Since all evergreen browsers including Firefox ESR and all active Node.js LTS
+  releases fully support ES2020, the compilation target for the browser bundle
+  and Node.js has been moved from ES2016 and ES2018 respectively to ES2020.
+
+- Updated TypeScript to version 4.8
+
+  This may result in type signatures that are incompatible with TypeScript 3
+  being added in future releases (including patch releases).
+
+- Changed default behavior of _internal_ `db.request` method
+
+  Previously this method would always return the full response object if no
+  `transform` callback was provided. The method now defaults to a `transform`
+  callback that extracts the response body instead. The previous behavior can
+  still be forced by passing `false` instead of a callback function.
+
+  This change has no effect on other methods like `route.request`.
+
+- Replaced node core module polyfills with native APIs in browser build
+
+  As part of upgrading to webpack 5, arangojs now no longer requires node core
+  modules to be polyfilled to work in the browser. This also drastically
+  reduces the file size of the pre-built browser bundle `arangojs/web`.
+
+- `db.query` now supports a generic return type ([#764](https://github.com/arangodb/arangojs/issues/764))
+
+  This allows explictly setting the item type of the `ArrayCursor` returned by
+  the query without using a type assertion on the promise result. Note that
+  arangojs can make no guarantees that the type matches the actual data
+  returned by the query.
+
+  ```ts
+  const numbers = await db.query<{ index: number; squared: number }>(aql`
+    FOR i IN 1..1000
+    RETURN {
+      index: i,
+      squared: i * i
+    }
+  `);
+  const first = await numbers.next();
+  console.log(first.index, first.squared); // 1 1
+  ```
+
+- Moved `aql.literal` and `aql.join` into `aql` module
+
+  Previously these were available as methods on the `aql` function. Now they
+  need to be imported from the `aql` module.
+
+- Changed return values of `db.getUserAccessLevel` and `db.getUserDatabases`
+  to match documented return types
+
+- Retry requests resulting in status 503 `ArangoError` ([#710](https://github.com/arangodb/arangojs/issues/710))
+
+  Unless retries are explicitly disabled by setting `config.maxRetries` to
+  `false`, requests will now also be retried if the server responded with a
+  503 `ArangoError`, which ArangoDB uses to indicate the server is running in
+  maintenance mode. Previously this would always result in an error.
+
+- Extended `CursorExtras` type in TypeScript
+
+  The types of the attributes `plan`, `profile`, and `stats` are now defined
+  more explicitly.
+
+- Changed behavior of `collection.removeAll` for non-string arrays
+
+  Previously `collection.removeAll` would always convert its argument into an
+  array of document IDs and fail with an error if passed any documents had an
+  ID not matching the collection name. Now the selector argument is passed
+  as-is, bypassing this validation but allowing `ignoreRevs` to be respected
+  by the server.
+
+- Extracted type `ArangoSearchViewLinkOptions` from `ArangoSearchViewLink`
+
+  Note that `ArangoSearchViewLink` now represents the type of the value
+  returned by the server, marking several properties as required.
+
+- Extracted type `CreateArangoSearchView` from
+  `ArangoSearchViewPropertiesOptions`
+
+  Note that `ArangoSearchViewPropertiesOptions` now includes only those options
+  that can be updated/replaced whereas `CreateArangoSearchView` also includes
+  options that can only be set during creation of a view.
+
+- Renamed type `GraphCreateOptions` to `CreateGraphOptions`
+
+- Renamed type `PrimarySortCompression` to `Compression`
+
+- Replaced type `AnalyzerInfo` and all its constituent types
+
+  Previously each type of Analyzer was represented by an `AnalyzerInfo` type
+  and (where relevant) an `AnalyzerProperties` type, which were used for both
+  creating and fetching Analyzers. The new types more closely follow the
+  pattern already used for index types, providing pairs of
+  `CreateAnalyzerOptions` and `AnalyzerDescription` types.
+
+- Removed enum `ViewType`, type `ArangoSearchView` and changed `View` class to
+  be non-generic
+
+  The `View` class now behaves analogous to the `Analyzer` class. The various
+  types related to different view types have been restructured to more closely
+  follow the pattern used for indexes and analyzers.
+
+### Deprecated
+
+- Deprecated `EnsureFulltextIndexOptions` and `FulltextIndex` types
+
+  Fulltext indexes have been deprecated in ArangoDB 3.10 and should be replaced
+  with ArangoSearch.
+
+- Deprecated `BytesAccumConsolidationPolicy` type
+
+  The `bytes_accum` consolidation policy for views was deprecated in
+  ArangoDB 3.7 and should be replaced with the `tier` consolidation policy.
+  The type is also no longer supported in `ArangoSearchViewPropertiesOptions`.
+
+### Added
+
+- Added `toJSON` method to system errors
+
+  ArangoJS already adds the `request` object to system errors encountered
+  while attempting to make network requests. This change makes it easier
+  to serialize these error objects to JSON the same way `ArangoError` and
+  `HttpError` objects can already be serialized.
+
+- Added `allowDirtyRead` option to `db.beginTransaction`, `trx.commit`,
+  `trx.abort`, `collection.edges`, `collection.inEdges`, `collection.outEdges`
+
+  The option is only respected by read-only requests.
+
+- Added support for `ifMatch` and `ifNoneMatch` options ([#707](https://github.com/arangodb/arangojs/issues/707))
+
+- Added `overwrite` option to `db.acquireHostList` ([#711](https://github.com/arangodb/arangojs/issues/711))
+
+  Setting this option to `true` will replace the current host list, removing any
+  hosts no longer present in the cluster.
+
+- Added new ArangoDB 3.10 `legacyPolygons` option to `EnsureGeoIndexOptions`
+  and `GeoIndex` types
+
+  Geo indexes created in ArangoDB pre-3.10 will implicitly default this option
+  to `true`. ArangoDB 3.10 and later will default to `false` and use the new
+  parsing rules for geo indexes.
+
+- Added support for new ArangoDB 3.10 `cacheEnabled` and `storedValues` options
+  in persistent indexes
+
+- Added support for new ArangoDB 3.10 computed values in collections
+
+- Added support for new ArangoDB 3.10 `InvertedIndex` type
+
+- Added support for new ArangoDB 3.10 `offset` Analyzer feature
+
+- Added support for new ArangoDB 3.10 `minhash`, `classification` and
+  `nearest_neighbors` Analyzer types
+
+- Added missing `replicationFactor` and `writeConcern` options to
+  `CollectionPropertiesOptions` type
+
+- Added missing `commitIntervalMsec` option to `ArangoSearchViewProperties`
+  type
+
+- Added missing `deduplicate` option to `EnsurePersistentIndexOptions` type
+  ([#771](https://github.com/arangodb/arangojs/issues/771))
+
+- Added missing `unique` option to `EnsureZkdIndexOptions` type
+
+- Added missing `deduplicate` and `estimates` fields to `PersistentIndex` type
+
+- Added new ArangoDB 3.10 `db.queryRules` method
+
+- Added support for `Analyzer` in `aql` templates
+
+  `Analyzer` objects can now be passed into `aql` templates like `View` and
+  `ArangoCollection` objects.
+
+- Added `retryOnConflict` option to `Config`
+
+  If set to any number, this value will be used as the default value for all
+  requests unless explicitly overridden when using `db.query` or
+  `route.request`.
+
 ## [7.8.0] - 2022-05-19
 
 ### Added
@@ -100,11 +360,11 @@ This driver uses semantic versioning:
 
 ### Fixed
 
-- Added missing `hex` flag to `StopwordsAnalyzer` type ([#732](https://github.com/arangodb/arangojs/issues/732))
+- Added missing `hex` option to `StopwordsAnalyzer` type ([#732](https://github.com/arangodb/arangojs/issues/732))
 
-- Added missing `details` flag to `collection.figures` ([#728](https://github.com/arangodb/arangojs/issues/728))
+- Added missing `details` option to `collection.figures` ([#728](https://github.com/arangodb/arangojs/issues/728))
 
-- Added missing `inBackground` flag to index options ([#734](https://github.com/arangodb/arangojs/issues/734))
+- Added missing `inBackground` option to index options ([#734](https://github.com/arangodb/arangojs/issues/734))
 
 ## [7.5.0] - 2021-04-22
 
@@ -1292,6 +1552,7 @@ 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.
 
+[8.0.0]: https://github.com/arangodb/arangojs/compare/v7.8.0...v8.0.0
 [7.8.0]: https://github.com/arangodb/arangojs/compare/v7.7.0...v7.8.0
 [7.7.0]: https://github.com/arangodb/arangojs/compare/v7.6.1...v7.7.0
 [7.6.1]: https://github.com/arangodb/arangojs/compare/v7.6.0...v7.6.1

package/CONTRIBUTING.md

@@ -20,7 +20,7 @@ yarn test
 ```
 
 By default the tests will be run against a server listening on
-`http://localhost:8529` (using username `root` with no password). To
+`http://127.0.0.1:8529` (using username `root` with no password). To
 override this, you can set the environment variable `TEST_ARANGODB_URL` to
 something different:
 

package/MIGRATING.md

@@ -1,5 +1,129 @@
 # Migrating
 
+## v7 to v8
+
+Version 8 drops support for Internet Explorer 11 and Node.js 10 and 12. If you
+need to continue supporting Internet Explorer, you can try transpiling arangojs
+as a dependency using Babel with the relevant polyfills.
+
+### General
+
+In TypeScript the type `Dict<T>` has been removed from the `connection` module.
+The built-in type `Record<string, T>` can be used as a replacement:
+
+```diff
+ import { Database } from "arangojs";
+-import type { Dict } from "arangojs/connection";
+
+ const db = new Database();
+-let deps: Dict<string | string[] | undefined>;
++let deps: Record<string, string | string[] | undefined>;
+ deps = await db.getServiceDependencies("/my-foxx-service", true);
+```
+
+### Default URL
+
+The default URL has been changed to `http://127.0.0.1:8529` to match the ArangoDB
+default. Previously the default URL was `http://localhost:8529`, which on some
+systems would resolve to the IPv6 address `::1` instead.
+
+If you don't want to use the IPv4 address `127.0.0.1` and instead want to continue
+letting the operating system resolve `localhost`, you can pass the URL explicitly:
+
+```diff
+ import { Database } from "arangojs";
+
+ const db = new Database({
++  url: "http://localhost:8529"
+ });
+```
+
+### Databases
+
+Previously arangojs allowed changing the database using the deprecated
+`db.useDatabase` method. This could make it difficult to remember which
+database you were interacting with. Instead, you should create a new `Database`
+instance for each database you want to interact with using the `db.database`
+method:
+
+```diff
+ import { Database } from "arangojs";
+
+ const db = new Database();
+-db.useDatabase("database2");
++const db2 = db.database("database2");
+```
+
+### Queries
+
+The functions `aql.literal` and `aql.join` are no longer available as methods
+on the `aql` template handler and need to be imported separately:
+
+```diff
+ import { aql } from "arangojs";
++import { join } from "arangojs/aql";
+
+-const filters = aql.join([
++const filters = join([
+   aql`FILTER size == 'big'`,
+   aql`FILTER color == 'yellow'`
+ ]);
+```
+
+### Users
+
+The return values of `db.getUserDatabases` and `db.getUserAccessLevel` have
+been changed to match the documented return types:
+
+```diff
+ import { Database } from "arangojs";
+
+ const db = new Database();
+-const dbs = (await db.getUserDatabases("ash")).result;
++const dbs = await db.getUserDatabases("ash");
+for (const [db, obj] of Object.entries(dbs)) {
+  console.log(`${db}: ${obj.permission}`);
+  for (const [col, access] of Object.entries(obj.collections)) {
+    console.log(`${db}/${col}: ${access}`);
+  }
+}
+
+-const access = (await db.getUserAccessLevel("ash", "pokemons")).result;
++const access = await db.getUserAccessLevel("ash", "pokemons");
+ if (access === "rw") {
+   db.collection("pokemons").save({ name: "Pikachu" });
+ }
+```
+
+### Graphs
+
+In TypeScript the type `GraphCreateOptions` has been renamed to
+`CreateGraphOptions`:
+
+```diff
+-import type { GraphCreateOptions } from "arangojs/graph";
++import type { CreateGraphOptions } from "arangojs/graph";
+```
+
+### Enum re-exports
+
+Previously the `CollectionStatus`, `CollectionType` and `ViewType` enums
+were re-exported by the arangojs main module and could be imported from the
+`arangojs` package:
+
+```diff
+-import { CollectionStatus, CollectionType } from "arangojs";
++import { CollectionStatus, CollectionType } from "arangojs/collection";
+```
+
+Note that the `ViewType` enum has been removed completely:
+
+````diff
+-import { ViewType } from "arangojs";
+-
+-const ArangoSearchViewType = ViewType.ARANGOSEARCH_VIEW;
++const ArangoSearchViewType = "arangosearch";
+
 ## v6 to v7
 
 ### Configuration changes
@@ -12,11 +136,11 @@ arangojs instance. The database name can now be specified using the
 
 ```diff
  const db = new Database({
-   url: "http://localhost:8529",
+   url: "http://127.0.0.1:8529",
 +  databaseName: "my_database",
  });
 -db.useDatabase("my_database");
-```
+````
 
 ### Shared connection pool
 

package/README.md

@@ -31,7 +31,7 @@ When using modern JavaScript tooling with a bundler and compiler (e.g. Babel),
 arangojs can be installed using `npm` or `yarn` like any other dependency.
 
 For use without a compiler, the npm release comes with a precompiled browser
-build for evergreen browsers and Internet Explorer 11:
+build for evergreen browsers:
 
 ```js
 var arangojs = require("arangojs/web");
@@ -40,24 +40,19 @@ var arangojs = require("arangojs/web");
 You can also use [unpkg](https://unpkg.com) during development:
 
 ```html
-< !-- note the path includes the version number (e.g. 7.0.0) -- >
-<script src="https://unpkg.com/arangojs@7.0.0/web.js"></script>
+< !-- note the path includes the version number (e.g. 8.0.0) -- >
+<script src="https://unpkg.com/arangojs@8.0.0/web.js"></script>
 <script>
   var db = new arangojs.Database();
   // ...
 </script>
 ```
 
-If you are targetting browsers older than Internet Explorer 11 you may want to
-use [babel](https://babeljs.io) with a
-[polyfill](https://babeljs.io/docs/usage/polyfill) to provide missing
-functionality needed to use arangojs.
-
 When loading the browser build with a script tag make sure to load the polyfill first:
 
 ```html
 <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/6.26.0/polyfill.js"></script>
-<script src="https://unpkg.com/arangojs@7.0.0/web.js"></script>
+<script src="https://unpkg.com/arangojs@8.0.0/web.js"></script>
 ```
 
 ## Basic usage example
@@ -94,13 +89,12 @@ Using a different database:
 
 ```js
 const db = new Database({
-  url: "http://localhost:8529",
+  url: "http://127.0.0.1:8529",
   databaseName: "pancakes",
   auth: { username: "root", password: "hunter2" },
 });
 
-// The database can be swapped at any time
-db.useDatabase("waffles");
+// The credentials can be swapped at any time
 db.useBasicAuth("admin", "maplesyrup");
 ```
 
@@ -175,7 +169,7 @@ receiving a response, the underlying system error will be thrown instead.
 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. 6.x.y -> 7.0.0) indicate
+Changes in the major version number of arangojs (e.g. 7.x.y -> 8.0.0) indicate
 backwards-incompatible changes in the arangojs API that may require changes in
 your code when upgrading your version of arangojs.