All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
This driver uses semantic versioning:
Changed the default for agentOptions.scheduling
to "lifo"
This is already the default in Node v15.6 but can reduce latency caused by sockets expiring, especially with larger connection pools and infrequent requests.
Added db.waitForPropagation
method
This method helps with setting up databases in a cluster scenario by waiting for a request to succeed on every known coordinator.
This is a maintenance release and contains no bugfixes or features.
Fixed incorrect HTTP method call in patch
method (#687)
Fixed empty query results containing [undefined]
(#683)
Fixed updateByExample
and replaceByExample
new value parameter name
Note that these methods are still deprecated. Previously the newValue
parameter was incorrectly called newData
, which prevented the methods from
working at all.
This is a maintenance release because the initial v7 release did not include a README file.
This is a major release and breaks backwards compatibility.
See the migration guide for detailed instructions for upgrading your code to arangojs v7.
For a detailed list of changes between pre-release versions of v7 see the Changelog of the final v7 release candidate.
Removed ArangoDB 2.8 support
ArangoDB 2.8 has reached End of Life since mid 2018. Version 7 and above of arangojs will no longer support ArangoDB 2.8 and earlier.
Removed Node.js 6/8 support
As of version 7 arangojs now requires language support for async/await. This means arangojs requires Node.js 10 (LTS) or newer to function correctly.
Removed support for absolute endpoint URLs
This removes the isAbsolute
option from the arangojs configuration.
Removed ArangoError
re-export
The type can still be imported directly from the error
module.
Removed statusCode
properties of ArangoError
and HttpError
Both of these error types still expose the HTTP status code as the code
property. For ArangoError
the true HTTP status code may be different and
can still be accessed using the response.statusCode
property.
Removed db.edgeCollection
method
As arangojs 7 uses the same implementation for document and edge collections,
this method is no longer necessary. Generic collection objects can still be
cast to DocumentCollection
or EdgeCollection
types in TypeScript.
Removed db.truncate
convenience method
This was a wrapper around db.listCollections
and collection.truncate
.
The behavior of db.truncate
can still be emulated by calling these methods
directly.
Removed collection createCapConstraint
, createHashIndex
,
createSkipList
, createPersistentIndex
, createGeoIndex
and
createFulltextIndex
methods
These methods are no longer part of the official ArangoDB API and can be
replaced by using the collection.ensureIndex
method.
Removed save(fromId, toId, edgeData)
method variants
Methods for creating edges now require the _to
and _from
attributes to
be specified in the edge (document) data and no longer accept these values
as positional arguments.
Removed collection.bulkUpdate
method
The new method collection.updateAll
now provides this functionality.
Removed collection.edge
method
This method was previously an alias for collection.document
.
The method graphEdgeCollection.edge
is unaffected by this change.
Removed graphName
option for edgeCollection.traversal
Graph traversals can still be performed via graph.traversal
.
Removed generic collection methods from GraphVertexCollection
All methods that are not part of the graph API have been removed.
The underlying collection can still be accessed from the collection
property.
Removed generic collection methods from GraphEdgeCollection
All methods that are not part of the graph API have been removed.
The underlying collection can still be accessed from the collection
property.
Removed cursor.some
and cursor.every
methods
These methods encouraged overfetching and should be replaced with more efficient AQL queries.
The behavior can still be implemented by using the next
method directly
or iterating over the cursor using the forEach
method or the for await
syntax.
Removed ViewResponse
type
The type ViewDescription
represents the same structure.
Removed ArangoSearchViewPropertiesResponse
type
The type ArangoSearchViewProperties & ViewDescription
can be used
to represent the same structure.
Deprecated db.useDatabase
method
Using this method will affect Collection
, Graph
and other objects
already created for the given database and change which database these
refer to, which may cause unexpected behavior.
As of arangojs 7 the db.database
method can be used instead to create a
new, separate Database
object using the same connection pool.
Deprecated Collection
methods for simple queries: list
, all
, any
,
byExample
, firstExample
, removeByExample
, replaceByExample
,
updateByExample
, lookupByKeys
, removeByKeys
, fulltext
These methods were deprecated in ArangoDB 3.4 and should no longer be used. They will still behave correctly with versions of ArangoDB supporting these methods but may be removed in a future ArangoDB release.
Their behavior can be emulated using AQL queries.
Deprecated graph.traversal
and collection.traversal
These methods were deprecated in ArangoDB 3.4 and should no longer be used. They will still behave correctly with versions of ArangoDB supporting these methods but may be removed in a future ArangoDB release.
Their behavior can be emulated using AQL graph traversal.
Multiple Database
objects can now share a single Connection
All arangojs objects now reference a Database
object rather than accessing
the underlying Connection
directly. This allows multiple Database
objects
to be created by using the db.database
method while still allowing the
creation of separate database objects with separate connection pools if
desired.
Memoized Database
, Collection
, Graph
, View
and Analyzer
Database objects are now memoized per-connection and the other object types
are memoized per-database. Using useDatabase
de-memoizes the database
object to prevent unexpected behavior.
Added support for View
in aql
templates (#667)
View
(or ArangoSearchView
) objects can now be passed into aql
templates
like ArangoCollection
objects.
Moved collectionToString
helper into collection
module
Moved Dict
type into connection
module
Moved Patch
type into documents
module
Removed Errback
type from public API
Renamed util/foxx-manifest
module to foxx-manifest
Renamed method db.arangoSearchView
to db.view
Renamed method db.createArangoSearchView
to db.createView
Replaced methods db.enableServiceDevelopmentMode
and
db.disableServiceDevelopmentMode
with db.setServiceDevelopmentMode
Flattened database query
method options
argument
The optional options
argument previously contained an additional options
object with additional query options. These options are now specified on the
options
argument itself directly.
Before:
db.query(aql`FOR doc IN ${collection} RETURN doc`, {
cache: false,
options: { fullCount: true },
});
After:
db.query(aql`FOR doc IN ${collection} RETURN doc`, {
cache: false,
fullCount: true,
});
Changed db.listServices
option excludeSystem
default to true
To be more consistent with the equivalent options in other methods,
the default value has been changed from false
to true
.
Changed db.createDatabase
return type to Database
Renamed database.setQueryTracking
to database.queryTracking
The method will now return the existing query tracking properties or set the new query tracking properties depending on whether an argument is provided.
Method db.transaction
no longer acts as an alias for executeTransaction
The method now only allows looking up transactions by ID. Previously it would
wrap executeTransaction
if passed the arguments expected by that method.
Merged DocumentCollection
and EdgeCollection
APIs
All collections are now implemented as generic Collection
objects.
In TypeScript the generic collection object can still be explicitly cast to
DocumentCollection
or EdgeCollection
for stricter type safety.
Renamed collection.setProperties
to collection.properties
The method will now return the existing properties or set the properties depending on whether an argument is provided.
Removed CollectionMetadata
fields from CollectionProperties
type
Methods that previously returned CollectionProperties
now return
CollectionMetadata & CollectionProperties
.
Collection methods save
, update
, replace
and remove
no longer take
arrays as input
The array versions have been renamed to saveAll
, updateAll
, replaceAll
and removeAll
to reduce the likelihood of mistakes and provide more helpful
type signatures.
Collection methods will now throw errors when passed documents or document IDs from different collections where a document key or ID for a document in the same collection is expected
For example the following code will now result in an error rather than the document from a different collection being returned:
const aliceId = "alice/123"; // Document from collection "alice"
const bobCol = db.collection("bob"); // Collection "bob"
const doc = await bobCol.document(aliceId); // THROWS
Changed collection.import
option type
behavior
Previously this option would always default to "auto"
.
When passing a string
, Buffer
or Blob
as data, the option now defaults
to undefined
. This matches the behavior in previous versions of setting
the option explicitly to null
.
Additionally, the value "array"
has been replaced with "list"
.
When passing an array as data, the option is now no longer supported as the corresponding value will be inferred from the array’s contents:
If the array’s first item is also an array, it will match the behavior in
previous versions of setting the option explicitly to null
.
Otherwise it will match the behavior in previous versions of setting the
option explicitly to "documents"
or "auto"
, or omitting it entirely.
Changed collection.list
return type to ArrayCursor
Graph methods now also accept ArangoCollection
instances instead of names
This brings these methods behavior in line with that of the beginTransaction
and executeTransaction
methods of Database
objects.
Graph create
method (and db.createGraph
) signature changed
The graph.create
method now takes an array of edge definitions as the
first argument and any additional options (not just the waitForSync
option) as the second argument.
Before:
await graph.create(
{
edgeDefinitions: [{ collection: "edges", from: ["a"], to: ["b"] }],
isSmart: true,
},
{ waitForSync: true }
);
After:
await graph.create([{ collection: "edges", from: ["a"], to: ["b"] }], {
isSmart: true,
waitForSync: true,
});
First argument to graph.replaceEdgeDefinition
is now optional
Since the new edge definition already includes the edge collection name that identifies the edge definition, it is now possible to specify only the new edge definition object without additionally specifying the collection name as the first argument.
Before:
await graph.replaceEdgeDefinition("edges", {
collection: "edges", // This is a bit redundant
from: ["a"],
to: ["b"],
});
After:
await graph.replaceEdgeDefinition({
collection: "edges",
from: ["a"],
to: ["b"],
});
Graph collection return values now contain old
and new
properties when
returnOld
or returnNew
options are used
This behavior represents a compromise between remaining consistent with the behavior of the regular collection method equivalents and remaining compatible with the ArangoDB HTTP API response object quirks.
Replaced ArrayCursor
methods hasNext
and hasMore
with getters
Renamed ArrayCursor
method each
to forEach
Renamed cursor.nextBatch
to cursor.batches.next
Renamed cursor.hasMore
to cursor.batches.hasMore
In TypeScript ArrayCursor
is now a generic type
TypeScript users can now cast cursor instances to use a specific type for
its values rather than any
to aid type safety.
Renamed view.setProperties
to view.updateProperties
Renamed type ArangoView
to View
ArangoAnalyzer
to Analyzer
Renamed type ArangoTransaction
to Transaction
Renamed transaction.run
to transaction.step
This should hopefully make it more obvious that sequential calls to arangojs methods should be split into separate calls of this method.
Added databaseName
configuration option
Setting this option to a database name will result in the initial Database
object using this database instead of the default _system
database.
Added auth
configuration option
It is now possible to pass authentication credentials using the auth
option in addition to calling db.useBasicAuth
or db.useBearerAuth
.
Added precaptureStackTraces
configuration option (#599)
This option can be used to get more useful stack traces but results in a performance hit on every request.
Added before
and after
to the agentOptions
configuration option (#585)
These methods can be used to track performance metrics for outgoing requests.
Improved type signatures for TypeScript and inline documentation
Most methods should now provide full type signatures for options and response objects and provide inline documentation in IDEs and editors that support this feature in TypeScript and JavaScript.
Added db.database
method
This method replaces the use case for the deprecated db.useDatabase
method.
Added support for extended options in db.createDatabase
This method now supports passing an extended options object instead of passing the users array directly.
Added db.createCollection
and db.createEdgeCollection
methods
These are convenience methods wrapping collection.create
. In TypeScript
createEdgeCollection
will return a collection cast to the EdgeCollection
type.
Added db.createGraph
method
This is a convenience method wrapping graph.create
.
Added db.createArangoSearchView
method
This is a convenience method wrapping view.create
.
Added db.createAnalyzer
method
This is a convenience method wrapping analyzer.create
.
Added support for db.createFunction
option isDeterministic
Added support for db.listServices
option excludeSystem
Added collection saveAll
, updateAll
, replaceAll
and removeAll
methods
These methods replace the respective array versions of the collection
methods save
, update
, replace
and remove
, which no longer accept
arrays as inputs.
Added collection.documentId
method
The method takes a document or a document key and returns a fully qualified document ID string for the document in the current collection.
Added support for values "ignore"
and "conflict"
in overwriteMode
option when saving documents using the Collection API
Added graphVertexCollection.vertexExists
and
graphEdgeCollection.edgeExists
methods
These mimic the behavior of the collection.documentExists
method but using
the Graph API.
Added graphVertexCollection.collection
and graphEdgeCollection.collection
These properties now provide access to regular (non-graph) collection objects for these graph collections. These objects can be used to perform operations not available within the context of a graph (e.g. bulk imports or modifying the collection itself).
Added support for isDisjoint
option in Graph API
Added cursor.flatMap
method
This method behaves similarly to the Array
method flatMap
but operates
on the cursor directly like cursor.map
does.
Added cursor.batches
to provide a batch-wise cursor API
Added support for for await
in ArrayCursor
(#616)
It is now possible to use for await
to iterate over each item in a cursor
asynchronously.
primarySortCompression
and storedValues
options in
View APIRemoved TypeScript dependency on dom
library
If you are using arangojs in Node.js, you no longer need to add the dom
library to your tsconfig.json
configuration.
Fixed db.dropFunction
option group
being ignored
Fixed documentation of db.runServiceTests
Previously the documentation incorrectly indicated that the default value
of the idiomatic
option is true
. The correct default value is false
.
Added uuid
and padded
to legal KeyGeneratorType
values in TypeScript (#656)
Added overwrite
to InsertOptions
type in TypeScript (#657)
db.listTransactions
and db.transactions
methodsEmpty querystring parameters are now omitted
In some cases ArangoDB would be unable to correctly handle querystring
parameters without values. Any paremeters set to undefined
will now
no longer be added to the querystring.
This does not affect parameters set to empty string values.
maxRuntime
option to db.query
methodReplaced linkedlist
dependency with x3-linkedlist
(#601)
The linkedlist
dependency had a memory leak and was no longer maintained.
The replacement should fix this issue.
Added cursor.kill
method
Cursors that have not yet been fully depleted can now be killed using the
cursor.kill
method. Note that this method has no effect if the cursor
is already depleted.
Added cursor.nextBatch
method
Cursors normally fetch additional batches as necessary while iterating over the individual results, this method allows consuming an entire batch at a time.
Fixed View properties not being passed correctly when creating Views (#621)
Renamed internal response.host
attribute to response.arangojsHostId
(#604)
In some environments the host
attribute is already present and read-only.
This should avoid a TypeError
being thrown when a value is assigned by
arangojs.
Renamed db.transaction
to db.executeTransaction
The method for executing server-side transactions is now called
executeTransaction
and the params
argument now must be passed via the
options
object.
For backwards-compatibility the new db.transaction
method will continue to
behave like before when passed an action
string as the second argument.
Note that this behavior is deprecated and will be removed in arangojs 7.
Added support for ArangoDB 3.5 streaming transactions
New streaming transactions can be created using db.beginTransaction
and
existing streaming transactions can be accessed by passing the transaction ID
to db.transaction
.
See the documentation of the transaction.run
method for examples of using
streaming transactions with arangojs.
Added support for ArangoDB 3.5 Analyzers API
See the documentation of the database.analyzer
method and the Analyzer
instances for information on using this API.
Added collection.getResponsibleShard
method
Added support for new ArangoDB 3.5 collection properties
Added support for new ArangoDB 3.5 View properties
Fixed a problem causing empty nested AQL expressions to be converted to bind variables
Nesting an empty AQL expression like the result of calling aql.join
with an empty
array would previously result in the AQL expression not being recognized and being
converted to an object bind variable instead.
Changed Views API to match 3.4 GA implementation
This release updates the Views API to the version implemented in the final ArangoDB 3.4 GA release. Please note that these changes may break code written for earlier ArangoDB 3.4 release candidates.
Added timeout
option to db.query
and request methods (#572)
Note that this merely cancels the request. Queries will still be executed and ArangoDB will still continue processing the request, this will merely result in the socket being forcefully disconnected.
Added query management API (#474)
This implements most endpoints of the HTTP Interface for AQL Queries.
Restored support for credentials in URLs
If the server URL includes credentials, arangojs will now use them instead of
the default username “root” and an empty password. Any credentials explicitly
set using useBasicAuth
or useBearerAuth
will still override the default
credentials as before.
Added any[]
to allowed types for AQL bind parameters
This should help in some cases where the previous TypeScript annotation was too restrictive.
Added support for UNIX socket URLs (#405)
In addition to the unix:///socket/path
and http+unix:///socket/path
URL formats recognized by ArangoDB, arangojs also supports the format
http://unix:/socket/path
commonly supported in the Node ecosystem and
automatically converts ArangoDB endpoint URLs between them.
No longer emitting undefined
values in aql
template strings
Previously using undefined
values in an aql template string would result
in a bind parameter being added with no value, which would always lead to an
error response when ArangoDB executes the query.
Now undefined values will simply be omitted, also easing the conditional
insertion of query fragments.
Changed experimental Views API
This release updates the experimental support for the Views API to the version implemented in the ArangoDB 3.4 release candidate. Please note that this API is still subject to change and may indeed still change until the 3.4.0 GA release.
Updated TypeScript to version 3
This may result in type signatures that are incompatible with TypeScript 2 being added in future releases (including patch releases).
Added nesting support for aql
template strings (#481)
It is now possible to use aql queries as values in aql
template strings:
function createQuery(flowers, color) {
const filter = color ? aql`FILTER flower.color == ${color}` : undefined;
return aql`FOR flower IN ${flowers} ${filter} RETURN flower`;
}
createQuery(db.collection("flowers", "green"));
// FOR flower IN @@value0 FILTER @value1 RETURN flower
// {"@value0": "flowers", "value1": "green"}
createQuery(db.collection("flowers"));
// FOR flower IN @@value0 RETURN flower
// {"@value0": "flowers"}
Previously aql fragments could only be created with aql.literal
, which
does not support bind parameters:
aql.literal("FILTER flower.color == " + JSON.stringify(color));
// Note that we had to rely on JSON.stringify to correctly escape the value
// because the value is part of the literal, not a bind parameter
Added support for undefined
and AQL literals to aql.literal
Passing undefined to aql.literal
will now result in an empty literal as
would be expected. Passing an AQL literal back into aql.literal
will return
the existing literal rather than the string [object Object]
.
Added aql.join
function
The function aql.join
can be used to convert an array of aql
queries into
a combined query:
const users = db.collection("users");
const keys = ["a", "b", "c"];
const fragments = keys.map((key) => aql`DOCUMENT(${users}, ${key})`);
const combined = aql`[${aql.join(fragments, ", ")}]`;
// [DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2), \
// DOCUMENT(@@value0, @value3)]
// {"@value0": "users", "value1": "a", "value2": "b", "value3": "c"}
const query = aql`FOR user IN ${combined} RETURN user.email`;
// FOR user IN [DOCUMENT(@@value0, @value1), DOCUMENT(@@value0, @value2), \
// DOCUMENT(@@value0, @value3)] RETURN user.email
// {"@value0": "users", "value1": "a", "value2": "b", "value3": "c"}
Added allowDirtyRead
option to db.query
and collection.document
Dirty reads are supported in leader/follower replication setups and require ArangoDB 3.4 or later. When performing a request that permits dirty reads, arangojs will load balance across all know leaders and followers and instruct ArangoDB to allow responding with stale or dirty response data. Note that data returned from a dirty read may be out of date or inconsistent.
Re-implemented collection.import
The previous implementation was broken. The new implementation should be backwards-compatible in cases where it previously wasn’t broken but is more flexible and also handles buffers.
Added missing dependency on @types/node
(#567)
This should solve TypeScript errors when the dependency was not already added.
Fixed edgeCollection.save
not respecting options (#554)
Fixed database.createDatabase
TypeScript signature (#561)
Requests that fail because a server can not be reached are now automatically retried if other servers are available
This behavior can be controlled using the maxRetries
option.
Renamed EdgeCollection#edge
to EdgeCollection#document
EdgeCollection#edge
is now an alias for the document
method.
Renamed GraphEdgeCollection#edge
to GraphEdgeCollection#document
GraphEdgeCollection#edge
is now an alias for the document
method.
Renamed GraphVertexCollection#vertex
to GraphVertexCollection#document
GraphVertexCollection#vertex
is now an alias for the document
method.
Added maxRetries
option to configuration to control retry behavior
Added collection.documentExists
method
Added graceful
option to collection.document
opts
in DocumentCollection#save
Added ArangoError
and CollectionType
to public exports
Added database.close
method
Added opts
parameter to EdgeCollection#save
Added database.version
method
Added database.login
method
Added database.exists
method
Added collection.exists
method
Added graph.exists
method
Added aql.literal
function
Exposed typings for collections and graphs (@samrg472 in #538)
Fixed synchronous errors during request creation not being handled
Internal errors thrown while a request is created (e.g. malformed URIs) would result in unhandled errors, which could result in termination of the process or promises never being rejected. These errors are now handled normally and will result in async rejections as expected.
res.body
is an empty string instead of null in the browser versionFixed collection.update(documentHandle, newValue, opts)
missing return value
Fixed collection.removeByKeys(keys, options)
missing return value
Fixed collection.replaceByExample(example, newValue, opts)
missing return value
Fixed collection.updateByExample(example, newValue, opts)
missing return value
Replaced Object.values
use to improve Node version compatibility
This allows using arangojs in Node.js 6 LTS without a polyfill.
Moved most documentation out of the README (#123)
This is a necessary step to integrate arangojs with the Drivers book in the official ArangoDB documentation.
Replaced internal use of async functions with callbacks
This removes some unnecessary layers of indirection, which should increase overall performance.
Extended db.transaction
arguments (@f5io in #494)
It’s now possible to pass additional transaction options.
Fixed a typo (@lodestone in #506)
Fixed graphEdgeCollection.edge
return value (@Hunter21007 in #501)
Fixed graph API sending incorrect requests resulting in HTTP 400 errors (@casdevs in #513)
Removed ES modules build
This should solve compatibility problems with es6-error
. The cjs
build now should also work with emulated ES module imports.
Use cpy-cli
for build process
Should help with cross-platform compatibility.
Fixed db.uninstallService(mount, opts)
opts default value
Fixed db.getServiceConfiguration(mount, minimal)
minimal representation
Fixed db.getServiceDependencies(mount, minimal)
minimal representation
Fixed db.updateServiceConfiguration(mount, cfg, minimal)
non-minimal representation
Fixed db.replaceServiceConfiguration(mount, cfg, minimal)
non-minimal representation
Fixed db.updateServiceDependencies(mount, cfg, minimal)
non-minimal representation
Fixed db.replaceServiceDependencies(mount, cfg, minimal)
non-minimal representation
Fixed handling of non-json responses
Use rimraf
for build process
Should help with cross-platform compatibility.
Fixed some imports broken during the TypeScript rewrite
If you were previously seeing errors involving a default
property,
this should make those go away.
Removed retryConnection
config.
It is not possible to reliably determine whether retrying a request is safe or not at the driver level. If you need automatic retry, you should implement your own logic, e.g. using the retry package.
Removed promise
config.
If you want to use an alternative promise implementation
you need to overwrite the Promise
global variable directly.
Asynchronous functions no longer support node-style callbacks.
All asynchronous functions now return promises.
Removed support for credentials in url
config.
Use db.useBasicAuth
or db.useBearerAuth
to pass credentials instead.
Removed bower support.
Use yarn/npm instead.
Removed lib
path prefix
All arangojs files can now be imported directly by name.
Before:
import { DocumentCollection } from "arangojs/lib/collection";
After:
import { DocumentCollection } from "arangojs/collection";
The url
config can now also be an array of URLs.
The behavior depends on the load balancing strategy (see API docs).
The databaseName
config has been replaced with isAbsolute
.
If you previously used databaseName: false
, the same behavior can now
be achieved using isAbsolute: true
. If you want to use a specific
database you can still switch databases with db.useDatabase
at any time.
Browser: maximum number of parallel connections behaves differently.
As keep-alive does not work reliably in the browser, the maximum number
of parallel connections now matches agentOptions.maxSockets
exactly.
TypeScript: ported arangojs to TypeScript.
The generated typings are now included in the NPM release and should be more reliable than the community maintained typings included with earlier versions of arangojs. See also #480.
Added ES Modules and browser build to NPM release.
lib/esm/
lib/cjs/
lib/web.js
Added support for load balancing and failover.
See API documentation for details.
Added acquireHostList
method.
See API documentation for details.
Added support for leader/follower failover.
Connections to a follower responding with an endpoint redirect will now be transparently redirected to the indicated leader.
Fixed #354
Graph methods now only return the relevant part of the response body.