arangojs
Version:
The official ArangoDB JavaScript driver.
1,428 lines • 119 kB
TypeScript
/// <reference types="node" resolution-mode="require"/>
/// <reference types="node" resolution-mode="require"/>
/// <reference types="node" resolution-mode="require"/>
/**
* ```js
* import { Database } from "arangojs/databases";
* ```
*
* The "databases" module provides the {@link Database} class and associated
* types and interfaces for TypeScript.
*
* The Database class is also re-exported by the "index" module.
*
* @packageDocumentation
*/
import * as administration from "./administration.js";
import * as analyzers from "./analyzers.js";
import * as aql from "./aql.js";
import * as cluster from "./cluster.js";
import * as collections from "./collections.js";
import * as configuration from "./configuration.js";
import * as connection from "./connection.js";
import * as cursors from "./cursors.js";
import * as graphs from "./graphs.js";
import * as hotBackups from "./hot-backups.js";
import * as jobs from "./jobs.js";
import * as logs from "./logs.js";
import * as queries from "./queries.js";
import * as routes from "./routes.js";
import * as services from "./services.js";
import * as transactions from "./transactions.js";
import * as users from "./users.js";
import * as views from "./views.js";
/**
* Options for creating a database.
*
* See {@link Database#createDatabase}.
*/
export type CreateDatabaseOptions = {
/**
* Database users to create with the database.
*/
users?: users.CreateDatabaseUserOptions[];
/**
* (Cluster only.) The sharding method to use for new collections in the
* database.
*/
sharding?: "" | "flexible" | "single";
/**
* (Cluster only.) Default replication factor for new collections in this
* database.
*
* Setting this to `1` disables replication. Setting this to `"satellite"`
* will replicate to every DBServer.
*/
replicationFactor?: "satellite" | number;
/**
* (Cluster only.) Default write concern for new collections created in this
* database.
*/
writeConcern?: number;
};
/**
* Object describing a database.
*
* See {@link Database#get}.
*/
export type DatabaseDescription = {
/**
* Name of the database.
*/
name: string;
/**
* Unique identifier of the database.
*/
id: string;
/**
* File system path of the database.
*/
path: string;
/**
* Whether the database is the system database.
*/
isSystem: boolean;
/**
* (Cluster only.) The sharding method to use for new collections in the
* database.
*/
sharding?: "" | "flexible" | "single";
/**
* (Cluster only.) Default replication factor for new collections in this
* database.
*/
replicationFactor?: "satellite" | number;
/**
* (Cluster only.) Default write concern for new collections created in this
* database.
*/
writeConcern?: number;
};
/**
* @internal
*/
type TrappedError = {
error: true;
};
/**
* @internal
*/
type TrappedRequest<T = any> = {
error?: false;
jobId: string;
onResolve: (res: connection.ProcessedResponse<T>) => void;
onReject: (error: any) => void;
};
/**
* Indicates whether the given value represents a {@link Database}.
*
* @param database - A value that might be a database.
*/
export declare function isArangoDatabase(database: any): database is Database;
/**
* An object representing a single ArangoDB database. All arangojs collections,
* cursors, analyzers and so on are linked to a `Database` object.
*/
export declare class Database {
protected _connection: connection.Connection;
protected _name: string;
protected _analyzers: Map<string, analyzers.Analyzer>;
protected _collections: Map<string, collections.Collection<any, any>>;
protected _graphs: Map<string, graphs.Graph>;
protected _views: Map<string, views.View>;
protected _trapRequest?: (trapped: TrappedError | TrappedRequest<any>) => void;
/**
* Creates a new `Database` instance with its own connection pool.
*
* See also {@link Database#database}.
*
* @param config - An object with configuration options.
*
* @example
* ```js
* const db = new Database({
* url: "http://127.0.0.1:8529",
* databaseName: "my_database",
* auth: { username: "admin", password: "hunter2" },
* });
* ```
*/
constructor(config?: configuration.ConfigOptions);
/**
* Creates a new `Database` instance with its own connection pool.
*
* See also {@link Database#database}.
*
* @param url - Base URL of the ArangoDB server or list of server URLs.
* Equivalent to the `url` option in {@link configuration.ConfigOptions}.
*
* @example
* ```js
* const db = new Database("http://127.0.0.1:8529", "my_database");
* db.useBasicAuth("admin", "hunter2");
* ```
*/
constructor(url: string | string[], name?: string);
/**
* @internal
*/
constructor(database: Database, name?: string);
/**
* @internal
*
* Indicates that this object represents an ArangoDB database.
*/
get isArangoDatabase(): true;
/**
* Name of the ArangoDB database this instance represents.
*/
get name(): string;
/**
* Returns a new {@link routes.Route} instance for the given path (relative to the
* database) that can be used to perform arbitrary HTTP requests.
*
* @param path - The database-relative URL of the route. Defaults to the
* database API root.
* @param headers - Default headers that should be sent with each request to
* the route.
*
* @example
* ```js
* const db = new Database();
* const myFoxxService = db.route("my-foxx-service");
* const response = await myFoxxService.post("users", {
* username: "admin",
* password: "hunter2"
* });
* // response.body is the result of
* // POST /_db/_system/my-foxx-service/users
* // with JSON request body '{"username": "admin", "password": "hunter2"}'
* ```
*/
route(path?: string, headers?: Headers | Record<string, string>): routes.Route;
/**
* @internal
*
* Performs an arbitrary HTTP request against the database.
*
* @param BodyType - Type of the expected response body.
* @param ReturnType - Type the response body will be transformed to.
* @param options - Options for this request.
* @param transform - An optional function to transform the low-level
* response object to a more useful return value.
*/
request<BodyType = any, ReturnType = BodyType>(options: connection.RequestOptions, transform?: (res: connection.ProcessedResponse<BodyType>) => ReturnType): Promise<ReturnType>;
/**
* @internal
*
* Performs an arbitrary HTTP request against the database.
*
* @param BodyType - Type of the expected response body.
* @param options - Options for this request.
* @param transform - If set to `false`, the raw response object will be
* returned.
*/
request<BodyType = any>(options: connection.RequestOptions, transform: false): Promise<connection.ProcessedResponse<BodyType>>;
/**
* Updates the URL list by requesting a list of all coordinators in the
* cluster and adding any endpoints not initially specified in the
* {@link configuration.ConfigOptions}.
*
* For long-running processes communicating with an ArangoDB cluster it is
* recommended to run this method periodically (e.g. once per hour) to make
* sure new coordinators are picked up correctly and can be used for
* fail-over or load balancing.
*
* @param overwrite - If set to `true`, the existing host list will be
* replaced instead of extended.
*
* @example
* ```js
* const db = new Database();
* const interval = setInterval(
* () => db.acquireHostList(),
* 5 * 60 * 1000 // every 5 minutes
* );
*
* // later
* clearInterval(interval);
* system.close();
* ```
*/
acquireHostList(overwrite?: boolean): Promise<void>;
/**
* Closes all active connections of this database instance.
*
* Can be used to clean up idling connections during longer periods of
* inactivity.
*
* **Note**: This method currently has no effect in the browser version of
* arangojs.
*
* @example
* ```js
* const db = new Database();
* const sessions = db.collection("sessions");
* // Clean up expired sessions once per hour
* setInterval(async () => {
* await db.query(aql`
* FOR session IN ${sessions}
* FILTER session.expires < DATE_NOW()
* REMOVE session IN ${sessions}
* `);
* // Making sure to close the connections because they're no longer used
* system.close();
* }, 1000 * 60 * 60);
* ```
*/
close(): void;
/**
* Performs a request against every known coordinator and returns when the
* request has succeeded against every coordinator or the timeout is reached.
*
* **Note**: This method is primarily intended to make database setup easier
* in cluster scenarios and requires all coordinators to be known to arangojs
* before the method is invoked. The method is not useful in single-server or
* leader-follower replication scenarios.
*
* @example
* ```js
* const db = new Database({ loadBalancingStrategy: "ROUND_ROBIN" });
* await system.acquireHostList();
* const analyzer = db.analyzer("my-analyzer");
* await analyzer.create();
* await db.waitForPropagation(
* { pathname: `/_api/analyzer/${encodeURIComponent(analyzer.name)}` },
* 30000
* );
* // Analyzer has been propagated to all coordinators and can safely be used
* ```
*
* @param request - Request to perform against each known coordinator.
* @param timeout - Maximum number of milliseconds to wait for propagation.
*/
waitForPropagation(request: connection.RequestOptions, timeout?: number): Promise<void>;
/**
* Methods for accessing the server-reported queue times of the mostly
* recently received responses.
*/
get queueTime(): administration.QueueTimeMetrics;
/**
* Sets the limit for the number of values of the most recently received
* server-reported queue times that can be accessed using
* {@link Database#queueTime}.
*
* @param responseQueueTimeSamples - Number of values to maintain.
*/
setResponseQueueTimeSamples(responseQueueTimeSamples: number): void;
/**
* Updates the underlying connection's `authorization` header to use Basic
* authentication with the given `username` and `password`, then returns
* itself.
*
* @param username - The username to authenticate with.
* @param password - The password to authenticate with.
*
* @example
* ```js
* const db = new Database();
* db.useBasicAuth("admin", "hunter2");
* // with the username "admin" and password "hunter2".
* ```
*/
useBasicAuth(username?: string, password?: string): this;
/**
* Updates the underlying connection's `authorization` header to use Bearer
* authentication with the given authentication `token`, then returns itself.
*
* @param token - The token to authenticate with.
*
* @example
* ```js
* const db = new Database();
* db.useBearerAuth("keyboardcat");
* // The database instance now uses Bearer authentication.
* ```
*/
useBearerAuth(token: string): this;
/**
* Validates the given database credentials and exchanges them for an
* authentication token, then uses the authentication token for future
* requests and returns it.
*
* @param username - The username to authenticate with.
* @param password - The password to authenticate with.
*
* @example
* ```js
* const db = new Database();
* await db.login("admin", "hunter2");
* // with an authentication token for the "admin" user.
* ```
*/
login(username?: string, password?: string): Promise<string>;
/**
* Attempts to renew the authentication token passed to {@link Database#useBearerAuth}
* or returned and used by {@link Database#login}. If a new authentication
* token is issued, it will be used for future requests and returned.
*
* @example
* ```js
* const db = new Database();
* await db.login("admin", "hunter2");
* // ... later ...
* const newToken = await db.renewAuthToken();
* if (!newToken) // no new token issued
* ```
*/
renewAuthToken(): Promise<string | null>;
/**
* Fetches version information from the ArangoDB server.
*
* @param details - If set to `true`, additional information about the
* ArangoDB server will be available as the `details` property.
*
* @example
* ```js
* const db = new Database();
* const version = await db.version();
* // the version object contains the ArangoDB version information.
* // license: "community" or "enterprise"
* // version: ArangoDB version number
* // server: description of the server
* ```
*/
version(details?: boolean): Promise<administration.VersionInfo>;
/**
* Fetches storage engine information from the ArangoDB server.
*
* @example
* ```js
* const db = new Database();
* const engine = await db.engine();
* // the engine object contains the storage engine information, e.g.
* // name: name of the storage engine
* ```
*/
engine(): Promise<administration.EngineInfo>;
/**
* Fetches detailed storage engine performance and resource usage information
* from the ArangoDB server.
*
* @example
* ```js
* const db = new Database();
* const stats = await db.engineStats();
* // the stats object contains the storage engine stats
* ```
*/
engineStats(): Promise<administration.EngineStatsInfo>;
/**
* Retrives the server's current system time in milliseconds with microsecond
* precision.
*/
time(): Promise<number>;
/**
* Fetches information about the server status.
*
* @example
* ```js
* const status = await db.status();
* // the status object contains the ArangoDB status information, e.g.
* // version: ArangoDB version number
* // host: host identifier of the server
* // serverInfo: detailed information about the server
* ```
*/
status(): Promise<administration.ServerStatusInfo>;
/**
* Fetches availability information about the server.
*
* @param graceful - If set to `true`, the method will always return `false`
* instead of throwing an error; otherwise `false` will only be returned
* when the server responds with a 503 status code or an ArangoDB error with
* a code of 503, such as during shutdown.
*
* @example
* ```js
* const availability = await db.availability();
* // availability is either "default", "readonly", or false
* ```
*/
availability(graceful?: boolean): Promise<administration.ServerAvailability>;
/**
* Fetches deployment information about the server for support purposes.
*
* Note that this API may reveal sensitive data about the deployment.
*/
supportInfo(): Promise<administration.SingleServerSupportInfo | administration.ClusterSupportInfo>;
/**
* Fetches the license information and status of an Enterprise Edition server.
*/
getLicense(): Promise<administration.LicenseInfo>;
/**
* Set a new license for an Enterprise Edition server.
*
* @param license - The license as a base 64 encoded string.
* @param force - If set to `true`, the license will be changed even if it
* expires sooner than the current license.
*/
setLicense(license: string, force?: boolean): Promise<void>;
/**
* Compacts all databases on the server.
*
* @param options - Options for compacting the databases.
*/
compact(options?: administration.CompactOptions): Promise<void>;
/**
* Attempts to initiate a clean shutdown of the server.
*/
shutdown(): Promise<void>;
/**
* Computes the current cluster imbalance.
*
* @example
* ```js
* const db = new Database();
* const imbalance = await db.getClusterImbalance();
* ```
*/
getClusterImbalance(): Promise<cluster.ClusterRebalanceState>;
/**
* Computes a set of move shard operations to rebalance the cluster.
*
* @example
* ```js
* const db = new Database();
* const result = await db.computerClusterRebalance({
* moveLeaders: true,
* moveFollowers: true
* });
* if (result.moves.length) {
* await db.executeClusterRebalance(result.moves);
* }
* ```
*/
computeClusterRebalance(options: cluster.ClusterRebalanceOptions): Promise<cluster.ClusterRebalanceResult>;
/**
* Executes the given cluster move shard operations.
*
* @example
* ```js
* const db = new Database();
* const result = await db.computerClusterRebalance({
* moveLeaders: true,
* moveFollowers: true
* });
* if (result.moves.length) {
* await db.executeClusterRebalance(result.moves);
* }
* ```
*/
executeClusterRebalance(moves: cluster.ClusterRebalanceMove[]): Promise<unknown>;
/**
* Computes a set of move shard operations to rebalance the cluster and
* executes them.
*
* @param options - Options for rebalancing the cluster.
*
* @example
* ```js
* const db = new Database();
* const result = await db.rebalanceCluster({
* moveLeaders: true,
* moveFollowers: true
* });
* // The cluster is now rebalanced.
* ```
*/
rebalanceCluster(options: cluster.ClusterRebalanceOptions): Promise<cluster.ClusterRebalanceResult>;
/**
* Creates a new `Database` instance for the given `databaseName` that
* shares this database's connection pool.
*
* See also {@link Database:constructor}.
*
* @param databaseName - Name of the database.
*
* @example
* ```js
* const systemDb = new Database();
* const myDb = systemDb.database("my_database");
* ```
*/
database(databaseName: string): Database;
/**
* Fetches the database description for the active database from the server.
*
* @example
* ```js
* const db = new Database();
* const info = await db.get();
* // the database exists
* ```
*/
get(): Promise<DatabaseDescription>;
/**
* Checks whether the database exists.
*
* @example
* ```js
* const db = new Database();
* const result = await db.exists();
* // result indicates whether the database exists
* ```
*/
exists(): Promise<boolean>;
/**
* Creates a new database with the given `databaseName` with the given
* `options` and returns a `Database` instance for that database.
*
* @param databaseName - Name of the database to create.
* @param options - Options for creating the database.
*
* @example
* ```js
* const db = new Database();
* const info = await db.createDatabase("mydb", {
* users: [{ username: "root" }]
* });
* // the database has been created
* ```
*/
createDatabase(databaseName: string, options?: CreateDatabaseOptions): Promise<Database>;
/**
* Creates a new database with the given `databaseName` with the given
* `users` and returns a `Database` instance for that database.
*
* @param databaseName - Name of the database to create.
* @param users - Database users to create with the database.
*
* @example
* ```js
* const db = new Database();
* const info = await db.createDatabase("mydb", [{ username: "root" }]);
* // the database has been created
* ```
*/
createDatabase(databaseName: string, users: users.CreateDatabaseUserOptions[]): Promise<Database>;
/**
* Fetches all databases from the server and returns an array of their names.
*
* See also {@link Database#databases} and
* {@link Database#listUserDatabases}.
*
* @example
* ```js
* const db = new Database();
* const names = await db.listDatabases();
* // databases is an array of database names
* ```
*/
listDatabases(): Promise<string[]>;
/**
* Fetches all databases accessible to the active user from the server and
* returns an array of their names.
*
* See also {@link Database#userDatabases} and
* {@link Database#listDatabases}.
*
* @example
* ```js
* const db = new Database();
* const names = await db.listUserDatabases();
* // databases is an array of database names
* ```
*/
listUserDatabases(): Promise<string[]>;
/**
* Fetches all databases from the server and returns an array of `Database`
* instances for those databases.
*
* See also {@link Database#listDatabases} and
* {@link Database#userDatabases}.
*
* @example
* ```js
* const db = new Database();
* const names = await db.databases();
* // databases is an array of databases
* ```
*/
databases(): Promise<Database[]>;
/**
* Fetches all databases accessible to the active user from the server and
* returns an array of `Database` instances for those databases.
*
* See also {@link Database#listUserDatabases} and
* {@link Database#databases}.
*
* @example
* ```js
* const db = new Database();
* const names = await db.userDatabases();
* // databases is an array of databases
* ```
*/
userDatabases(): Promise<Database[]>;
/**
* Deletes the database with the given `databaseName` from the server.
*
* @param databaseName - Name of the database to delete.
*
* @example
* ```js
* const db = new Database();
* await db.dropDatabase("mydb");
* // database "mydb" no longer exists
* ```
*/
dropDatabase(databaseName: string): Promise<boolean>;
/**
* Returns a `Collection` instance for the given collection name.
*
* In TypeScript the collection implements both the
* {@link collections.DocumentCollection} and {@link collections.EdgeCollection}
* interfaces and can be cast to either type to enforce a stricter API.
*
* @param EntryResultType - Type to represent document contents returned by
* the server (including computed properties).
* @param EntryInputType - Type to represent document contents passed when
* inserting or replacing documents (without computed properties).
* @param collectionName - Name of the edge collection.
*
* @example
* ```js
* const db = new Database();
* const collection = db.collection("potatoes");
* ```
*
* @example
* ```ts
* interface Person {
* name: string;
* }
* const db = new Database();
* const persons = db.collection<Person>("persons");
* ```
*
* @example
* ```ts
* interface Person {
* name: string;
* }
* interface Friend {
* startDate: number;
* endDate?: number;
* }
* const db = new Database();
* const documents = db.collection("persons") as DocumentCollection<Person>;
* const edges = db.collection("friends") as EdgeCollection<Friend>;
* ```
*/
collection<EntryResultType extends Record<string, any> = any, EntryInputType extends Record<string, any> = EntryResultType>(collectionName: string): collections.DocumentCollection<EntryResultType, EntryInputType> & collections.EdgeCollection<EntryResultType, EntryInputType>;
/**
* Creates a new collection with the given `collectionName` and `options`,
* then returns a {@link collections.DocumentCollection} instance for the new collection.
*
* @param EntryResultType - Type to represent document contents returned by
* the server (including computed properties).
* @param EntryInputType - Type to represent document contents passed when
* inserting or replacing documents (without computed properties).
* @param collectionName - Name of the new collection.
* @param options - Options for creating the collection.
*
* @example
* ```ts
* const db = new Database();
* const documents = db.createCollection("persons");
* ```
*
* @example
* ```ts
* interface Person {
* name: string;
* }
* const db = new Database();
* const documents = db.createCollection<Person>("persons");
* ```
*/
createCollection<EntryResultType extends Record<string, any> = any, EntryInputType extends Record<string, any> = EntryResultType>(collectionName: string, options?: collections.CreateCollectionOptions & {
type?: collections.CollectionType.DOCUMENT_COLLECTION;
}): Promise<collections.DocumentCollection<EntryResultType, EntryInputType>>;
/**
* Creates a new edge collection with the given `collectionName` and
* `options`, then returns an {@link collections.EdgeCollection} instance for the new
* edge collection.
*
* @param EntryResultType - Type to represent edge document contents returned
* by the server (including computed properties).
* @param EntryInputType - Type to represent edge document contents passed
* when inserting or replacing documents (without computed properties).
* @param collectionName - Name of the new collection.
* @param options - Options for creating the collection.
*
* @example
* ```js
* const db = new Database();
* const edges = db.createCollection("friends", {
* type: CollectionType.EDGE_COLLECTION
* });
* ```
*
* @example
* ```ts
* interface Friend {
* startDate: number;
* endDate?: number;
* }
* const db = new Database();
* const edges = db.createCollection<Friend>("friends", {
* type: CollectionType.EDGE_COLLECTION
* });
* ```
*/
createCollection<EntryResultType extends Record<string, any> = any, EntryInputType extends Record<string, any> = EntryResultType>(collectionName: string, options: collections.CreateCollectionOptions & {
type: collections.CollectionType.EDGE_COLLECTION;
}): Promise<collections.EdgeCollection<EntryResultType, EntryInputType>>;
/**
* Creates a new edge collection with the given `collectionName` and
* `options`, then returns an {@link collections.EdgeCollection} instance for the new
* edge collection.
*
* This is a convenience method for calling {@link Database#createCollection}
* with `options.type` set to `EDGE_COLLECTION`.
*
* @param EntryResultType - Type to represent edge document contents returned
* by the server (including computed properties).
* @param EntryInputType - Type to represent edge document contents passed
* when inserting or replacing documents (without computed properties).
* @param collectionName - Name of the new collection.
* @param options - Options for creating the collection.
*
* @example
* ```js
* const db = new Database();
* const edges = db.createEdgeCollection("friends");
* ```
*
* @example
* ```ts
* interface Friend {
* startDate: number;
* endDate?: number;
* }
* const db = new Database();
* const edges = db.createEdgeCollection<Friend>("friends");
* ```
*/
createEdgeCollection<EntryResultType extends Record<string, any> = any, EntryInputType extends Record<string, any> = EntryResultType>(collectionName: string, options?: collections.CreateCollectionOptions): Promise<collections.EdgeCollection<EntryResultType, EntryInputType>>;
/**
* Renames the collection `collectionName` to `newName`.
*
* Additionally removes any stored `Collection` instance for
* `collectionName` from the `Database` instance's internal cache.
*
* **Note**: Renaming collections may not be supported when ArangoDB is
* running in a cluster configuration.
*
* @param collectionName - Current name of the collection.
* @param newName - The new name of the collection.
*/
renameCollection(collectionName: string, newName: string): Promise<connection.ArangoApiResponse<collections.CollectionDescription>>;
/**
* Fetches all collections from the database and returns an array of
* collection descriptions.
*
* See also {@link Database#collections}.
*
* @param excludeSystem - Whether system collections should be excluded.
*
* @example
* ```js
* const db = new Database();
* const collections = await db.listCollections();
* // collections is an array of collection descriptions
* // not including system collections
* ```
*
* @example
* ```js
* const db = new Database();
* const collections = await db.listCollections(false);
* // collections is an array of collection descriptions
* // including system collections
* ```
*/
listCollections(excludeSystem?: boolean): Promise<collections.CollectionDescription[]>;
/**
* Fetches all collections from the database and returns an array of
* `Collection` instances.
*
* In TypeScript these instances implement both the
* {@link collections.DocumentCollection} and {@link collections.EdgeCollection}
* interfaces and can be cast to either type to enforce a stricter API.
*
* See also {@link Database#listCollections}.
*
* @param excludeSystem - Whether system collections should be excluded.
*
* @example
* ```js
* const db = new Database();
* const collections = await db.collections();
* // collections is an array of DocumentCollection and EdgeCollection
* // instances not including system collections
* ```
*
* @example
* ```js
* const db = new Database();
* const collections = await db.collections(false);
* // collections is an array of DocumentCollection and EdgeCollection
* // instances including system collections
* ```
*/
collections(excludeSystem?: boolean): Promise<Array<collections.DocumentCollection & collections.EdgeCollection>>;
/**
* Returns a {@link graphs.Graph} instance representing the graph with the given
* `graphName`.
*
* @param graphName - Name of the graph.
*
* @example
* ```js
* const db = new Database();
* const graph = db.graph("some-graph");
* ```
*/
graph(graphName: string): graphs.Graph;
/**
* Creates a graph with the given `graphName` and `edgeDefinitions`, then
* returns a {@link graphs.Graph} instance for the new graph.
*
* @param graphName - Name of the graph to be created.
* @param edgeDefinitions - An array of edge definitions.
* @param options - An object defining the properties of the graph.
*/
createGraph(graphName: string, edgeDefinitions: graphs.EdgeDefinitionOptions[], options?: graphs.CreateGraphOptions): Promise<graphs.Graph>;
/**
* Fetches all graphs from the database and returns an array of graph
* descriptions.
*
* See also {@link Database#graphs}.
*
* @example
* ```js
* const db = new Database();
* const graphs = await db.listGraphs();
* // graphs is an array of graph descriptions
* ```
*/
listGraphs(): Promise<graphs.GraphDescription[]>;
/**
* Fetches all graphs from the database and returns an array of {@link graphs.Graph}
* instances for those graphs.
*
* See also {@link Database#listGraphs}.
*
* @example
* ```js
* const db = new Database();
* const graphs = await db.graphs();
* // graphs is an array of Graph instances
* ```
*/
graphs(): Promise<graphs.Graph[]>;
/**
* Returns a {@link views.View} instance for the given `viewName`.
*
* @param viewName - Name of the ArangoSearch or SearchAlias View.
*
* @example
* ```js
* const db = new Database();
* const view = db.view("potatoes");
* ```
*/
view(viewName: string): views.View;
/**
* Creates a new View with the given `viewName` and `options`, then returns a
* {@link views.View} instance for the new View.
*
* @param viewName - Name of the View.
* @param options - An object defining the properties of the View.
*
* @example
* ```js
* const db = new Database();
* const view = await db.createView("potatoes", { type: "arangosearch" });
* // the ArangoSearch View "potatoes" now exists
* ```
*/
createView(viewName: string, options: views.CreateViewOptions): Promise<views.View>;
/**
* Renames the view `viewName` to `newName`.
*
* Additionally removes any stored {@link views.View} instance for `viewName` from
* the `Database` instance's internal cache.
*
* **Note**: Renaming views may not be supported when ArangoDB is running in
* a cluster configuration.
*
* @param viewName - Current name of the view.
* @param newName - The new name of the view.
*/
renameView(viewName: string, newName: string): Promise<connection.ArangoApiResponse<views.ViewDescription>>;
/**
* Fetches all Views from the database and returns an array of View
* descriptions.
*
* See also {@link Database#views}.
*
* @example
* ```js
* const db = new Database();
*
* const views = await db.listViews();
* // views is an array of View descriptions
* ```
*/
listViews(): Promise<views.ViewDescription[]>;
/**
* Fetches all Views from the database and returns an array of
* {@link views.View} instances
* for the Views.
*
* See also {@link Database#listViews}.
*
* @example
* ```js
* const db = new Database();
* const views = await db.views();
* // views is an array of ArangoSearch View instances
* ```
*/
views(): Promise<views.View[]>;
/**
* Returns an {@link analyzers.Analyzer} instance representing the Analyzer with the
* given `analyzerName`.
*
* @example
* ```js
* const db = new Database();
* const analyzer = db.analyzer("some-analyzer");
* const info = await analyzer.get();
* ```
*/
analyzer(analyzerName: string): analyzers.Analyzer;
/**
* Creates a new Analyzer with the given `analyzerName` and `options`, then
* returns an {@link analyzers.Analyzer} instance for the new Analyzer.
*
* @param analyzerName - Name of the Analyzer.
* @param options - An object defining the properties of the Analyzer.
*
* @example
* ```js
* const db = new Database();
* const analyzer = await db.createAnalyzer("potatoes", { type: "identity" });
* // the identity Analyzer "potatoes" now exists
* ```
*/
createAnalyzer(analyzerName: string, options: analyzers.CreateAnalyzerOptions): Promise<analyzers.Analyzer>;
/**
* Fetches all Analyzers visible in the database and returns an array of
* Analyzer descriptions.
*
* See also {@link Database#analyzers}.
*
* @example
* ```js
* const db = new Database();
* const analyzers = await db.listAnalyzers();
* // analyzers is an array of Analyzer descriptions
* ```
*/
listAnalyzers(): Promise<analyzers.AnalyzerDescription[]>;
/**
* Fetches all Analyzers visible in the database and returns an array of
* {@link analyzers.Analyzer} instances for those Analyzers.
*
* See also {@link Database#listAnalyzers}.
*
* @example
* ```js
* const db = new Database();
* const analyzers = await db.analyzers();
* // analyzers is an array of Analyzer instances
* ```
*/
analyzers(): Promise<analyzers.Analyzer[]>;
/**
* Fetches all ArangoDB users visible to the authenticated user and returns
* an array of user objects.
*
* @example
* ```js
* const db = new Database();
* const users = await db.listUsers();
* // users is an array of user objects
* ```
*/
listUsers(): Promise<users.ArangoUser[]>;
/**
* Fetches the user data of a single ArangoDB user.
*
* @param username - Name of the ArangoDB user to fetch.
*
* @example
* ```js
* const db = new Database();
* const user = await db.getUser("steve");
* // user is the user object for the user named "steve"
* ```
*/
getUser(username: string): Promise<connection.ArangoApiResponse<users.ArangoUser>>;
/**
* Creates a new ArangoDB user with the given password.
*
* @param username - Name of the ArangoDB user to create.
* @param passwd - Password of the new ArangoDB user.
*
* @example
* ```js
* const db = new Database();
* const user = await db.createUser("steve", "hunter2");
* // The user "steve" has been created
* ```
*/
createUser(username: string, passwd: string): Promise<connection.ArangoApiResponse<users.ArangoUser>>;
/**
* Creates a new ArangoDB user with the given options.
*
* @param username - Name of the ArangoDB user to create.
* @param options - Additional options for creating the ArangoDB user.
*
* @example
* ```js
* const db = new Database();
* const user = await db.createUser("steve", { passwd: "hunter2" });
* // The user "steve" has been created
* ```
*/
createUser(username: string, options: users.UserOptions): Promise<connection.ArangoApiResponse<users.ArangoUser>>;
/**
* Sets the password of a given ArangoDB user to the new value.
*
* @param username - Name of the ArangoDB user to change the password for.
* @param passwd - New password for the ArangoDB user.
*
* @example
* ```js
* const db = new Database();
* const user = await db.updateUser("steve", "hunter2");
* // The user "steve" has received a new password
* ```
*/
updateUser(username: string, passwd: string): Promise<connection.ArangoApiResponse<users.ArangoUser>>;
/**
* Updates the ArangoDB user with the new options.
*
* @param username - Name of the ArangoDB user to modify.
* @param options - Options of the ArangoDB user to modify.
*
* @example
* ```js
* const db = new Database();
* const user = await db.updateUser("steve", { active: false });
* // The user "steve" has been set to inactive
* ```
*/
updateUser(username: string, options: Partial<users.UserOptions>): Promise<connection.ArangoApiResponse<users.ArangoUser>>;
/**
* Replaces the ArangoDB user's option with the new options.
*
* @param username - Name of the ArangoDB user to modify.
* @param options - New options to replace the user's existing options.
*
* @example
* ```js
* const db = new Database();
* const user = await db.replaceUser("steve", { passwd: "", active: false });
* // The user "steve" has been set to inactive with an empty password
* ```
*/
replaceUser(username: string, options: users.UserOptions): Promise<connection.ArangoApiResponse<users.ArangoUser>>;
/**
* Removes the ArangoDB user with the given username from the server.
*
* @param username - Name of the ArangoDB user to remove.
*
* @example
* ```js
* const db = new Database();
* await db.removeUser("steve");
* // The user "steve" has been removed
* ```
*/
removeUser(username: string): Promise<void>;
/**
* Fetches the given ArangoDB user's access level for the database, or the
* given collection in the given database.
*
* @param username - Name of the ArangoDB user to fetch the access level for.
* @param options - Collection and/or database to fetch the access level for.
*
* @example
* ```js
* const db = new Database();
* const accessLevel = await db.getUserAccessLevel("steve");
* // The access level of the user "steve" has been fetched for the current
* // database.
* ```
*
* @example
* ```js
* const db = new Database();
* const accessLevel = await db.getUserAccessLevel("steve", {
* database: "staging"
* });
* // The access level of the user "steve" has been fetched for the "staging"
* // database.
* ```
*
* @example
* ```js
* const db = new Database();
* const accessLevel = await db.getUserAccessLevel("steve", {
* collection: "pokemons"
* });
* // The access level of the user "steve" has been fetched for the
* // "pokemons" collection in the current database.
* ```
*
* @example
* ```js
* const db = new Database();
* const accessLevel = await db.getUserAccessLevel("steve", {
* database: "staging",
* collection: "pokemons"
* });
* // The access level of the user "steve" has been fetched for the
* // "pokemons" collection in the "staging" database.
* ```
*
* @example
* ```js
* const db = new Database();
* const staging = db.database("staging");
* const accessLevel = await db.getUserAccessLevel("steve", {
* database: staging
* });
* // The access level of the user "steve" has been fetched for the "staging"
* // database.
* ```
*
* @example
* ```js
* const db = new Database();
* const staging = db.database("staging");
* const accessLevel = await db.getUserAccessLevel("steve", {
* collection: staging.collection("pokemons")
* });
* // The access level of the user "steve" has been fetched for the
* // "pokemons" collection in database "staging".
* ```
*/
getUserAccessLevel(username: string, options: users.UserAccessLevelOptions): Promise<users.AccessLevel>;
/**
* Sets the given ArangoDB user's access level for the database, or the
* given collection in the given database.
*
* @param username - Name of the ArangoDB user to set the access level for.
* @param options - Database and/or collection to set the access level for.
* @param grant - Access level to set for the given user.
*
* @example
* ```js
* const db = new Database();
* await db.setUserAccessLevel("steve", { grant: "rw" });
* // The user "steve" now has read-write access to the current database.
* ```
*
* @example
* ```js
* const db = new Database();
* await db.setUserAccessLevel("steve", {
* database: "staging",
* grant: "rw"
* });
* // The user "steve" now has read-write access to the "staging" database.
* ```
*
* @example
* ```js
* const db = new Database();
* await db.setUserAccessLevel("steve", {
* collection: "pokemons",
* grant: "rw"
* });
* // The user "steve" now has read-write access to the "pokemons" collection
* // in the current database.
* ```
*
* @example
* ```js
* const db = new Database();
* await db.setUserAccessLevel("steve", {
* database: "staging",
* collection: "pokemons",
* grant: "rw"
* });
* // The user "steve" now has read-write access to the "pokemons" collection
* // in the "staging" database.
* ```
*
* @example
* ```js
* const db = new Database();
* const staging = db.database("staging");
* await db.setUserAccessLevel("steve", {
* database: staging,
* grant: "rw"
* });
* // The user "steve" now has read-write access to the "staging" database.
* ```
*
* @example
* ```js
* const db = new Database();
* const staging = db.database("staging");
* await db.setUserAccessLevel("steve", {
* collection: staging.collection("pokemons"),
* grant: "rw"
* });
* // The user "steve" now has read-write access to the "pokemons" collection
* // in database "staging".
* ```
*/
setUserAccessLevel(username: string, options: users.UserAccessLevelOptions, grant: users.AccessLevel): Promise<connection.ArangoApiResponse<Record<string, users.AccessLevel>>>;
/**
* Clears the given ArangoDB user's access level for the database, or the
* given collection in the given database.
*
* @param username - Name of the ArangoDB user to clear the access level for.
* @param options - Database and/or collection to clear the access level for.
*
* @example
* ```js
* const db = new Database();
* await db.clearUserAccessLevel("steve");
* // The access level of the user "steve" has been cleared for the current
* // database.
* ```
*
* @example
* ```js
* const db = new Database();
* await db.clearUserAccessLevel("steve", { database: "staging" });
* // The access level of the user "steve" has been cleared for the "staging"
* // database.
* ```
*
* @example
* ```js
* const db = new Database();
* await db.clearUserAccessLevel("steve", { collection: "pokemons" });
* // The access level of the user "steve" has been cleared for the
* // "pokemons" collection in the current database.
* ```
*
* @example
* ```js
* const db = new Database();
* await db.clearUserAccessLevel("steve", {
* database: "staging",
* collection: "pokemons"
* });
* // The access level of the user "steve" has been cleared for the
* // "pokemons" collection in the "staging" database.
* ```
*
* @example
* ```js
* const db = new Database();
* const staging = db.database("staging");
* await db.clearUserAccessLevel("steve", { database: staging });
* // The access level of the user "steve" has been cleared for the "staging"
* // database.
* ```
*
* @example
* ```js
* const db = new Database();
* const staging = db.database("staging");
* await db.clearUserAccessLevel("steve", {
* collection: staging.collection("pokemons")
* });
* // The access level of the user "steve" has been cleared for the
* // "pokemons" collection in database "staging".
* ```
*/
clearUserAccessLevel(username: string, options: users.UserAccessLevelOptions): Promise<connection.ArangoApiResponse<Record<string, users.AccessLevel>>>;
/**
* Fetches an object mapping names of databases to the access level of the
* given ArangoDB user for those databases.
*
* @param username - Name of the ArangoDB user to fetch the access levels for.
* @param full - Whether access levels for collections should be included.
*
* @example
* ```js
* const db = new Database();
* const accessLevels = await db.getUserDatabases("steve");
* for (const [databaseName, accessLevel] of Object.entries(accessLevels)) {
* console.log(`${databaseName}: ${accessLevel}`);
* }
* ```
*/
getUserDatabases(username: string, full?: false): Promise<Record<string, users.AccessLevel>>;
/**
* Fetches an object mapping names of databases to the access level of the
* given ArangoDB user for those databases and the collections within each
* database.
*
* @param username - Name of the ArangoDB user to fetch the access levels for.
* @param full - Whether access levels for collections should be included.
*
* @example
* ```js
* const db = new Database();
* const accessLevels = await db.getUserDatabases("steve", true);
* for (const [databaseName, obj] of Object.entries(accessLevels)) {
* console.log(`${databaseName}: ${obj.permission}`);
* for (const [collectionName, accessLevel] of Object.entries(obj.collections)) {
* console.log(`${databaseName}/${collectionName}: ${accessLevel}`);
* }
* }
* ```
*/
getUserDatabases(username: string, full: true): Promise<Record<string, {
permission: users.AccessLevel;
collections: Record<string, users.AccessLevel | "undefined">;
}>>;
/**
* Performs a server-side JavaScript transaction and returns its return
* value.
*
* Collections can be specified as collection names (strings) or objects
* implementing the {@link collections.ArangoCollection} interface: `Collection`,
* {@link graphs.GraphVertexCollection}, {@link graphs.GraphEdgeCollection} as well as
* (in TypeScript) {@link collections.DocumentCollection} and {@link collections.EdgeCollection}.
*
* **Note**: The `action` function will be evaluated and executed on the
* server inside ArangoDB's embedded JavaScript environment and can not
* access any values other than those passed via the `params` option.
*
* See the offi