or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

administration.mdaql-queries.mddatabase-connection.mddocument-collections.mdgraph-operations.mdindex.mdquery-execution.mdtransactions.mdviews-search.md
tile.json

index.mddocs/

ArangoJS

ArangoJS is the official JavaScript/TypeScript client driver for ArangoDB, a multi-model NoSQL database. It provides comprehensive support for document operations, graph queries, and AQL (ArangoDB Query Language) execution with modern async/await patterns, full TypeScript support, and advanced features like connection pooling, transaction management, and streaming capabilities.

Package Information

  • Package Name: arangojs
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install arangojs

Core Imports

import { Database, aql } from "arangojs";

For CommonJS:

const { Database, aql } = require("arangojs");

For type-only imports:

import type { ArangoError, HttpError } from "arangojs/errors";
import type { Cursor, BatchCursor } from "arangojs/cursors";
import type { Transaction } from "arangojs/transactions";

Basic Usage

import { Database, aql } from "arangojs";

// Create database connection
const db = new Database({
  url: "http://127.0.0.1:8529",
  databaseName: "myDatabase",
  auth: { username: "root", password: "password" }
});

// Work with collections
const collection = db.collection("users");

// Execute AQL queries with type safety
const users = await db.query(aql`
  FOR user IN ${collection}
  FILTER user.active == true
  RETURN user
`);

// Iterate through results
for await (const user of users) {
  console.log(user.name);
}

Architecture

ArangoJS is built around several key architectural components:

  • Database Class: Central connection manager providing access to all ArangoDB features
  • AQL Template System: Type-safe query builder with SQL injection protection via aql tagged templates
  • Collection Abstractions: Separate interfaces for document and edge collections with full CRUD operations
  • Graph API: Native support for graph databases with vertex and edge collection management
  • Transaction Support: Both streaming transactions and single-operation transactions
  • Connection Management: Built-in connection pooling, load balancing, and failover handling
  • Type System: Comprehensive TypeScript definitions for all operations and data structures

Capabilities

Database Connection and Management

Core database connection, authentication, and database lifecycle management functionality.

function arangojs(config?: ConfigOptions): Database;
function arangojs(url: string | string[], name?: string): Database;

class Database {
  constructor(config?: ConfigOptions | string | string[], name?: string);
  useBasicAuth(username?: string, password?: string): this;
  useBearerAuth(token: string): this;
  close(): void;
}

interface ConfigOptions {
  url?: string | string[];
  databaseName?: string;
  auth?: BasicAuthCredentials | BearerAuthCredentials;
  loadBalancingStrategy?: LoadBalancingStrategy;
}

Database Connection

AQL Query Language

AQL (ArangoDB Query Language) template system for building type-safe, injection-protected queries.

function aql<T = any>(
  templateStrings: TemplateStringsArray,
  ...args: AqlValue[]
): AqlQuery<T>;

interface AqlQuery<T = any> {
  query: string;
  bindVars: Record<string, any>;
}

function literal(value: string | number | boolean | null | undefined): AqlLiteral;
function join(values: AqlValue[], sep?: string): AqlQuery;

AQL Queries

Document Collections

Document storage and retrieval operations for working with JSON documents in collections.

interface DocumentCollection<T = any, U = T> extends ArangoCollection {
  exists(): Promise<boolean>;
  document(selector: DocumentSelector, options?: ReadDocumentOptions): Promise<Document<T>>;
  save(data: DocumentData<U>, options?: InsertDocumentOptions): Promise<DocumentOperationResult<T>>;
  replace(selector: DocumentSelector, data: DocumentData<U>, options?: ReplaceDocumentOptions): Promise<DocumentOperationResult<T>>;
  update(selector: DocumentSelector, data: Patch<U>, options?: UpdateDocumentOptions): Promise<DocumentOperationResult<T>>;
  remove(selector: DocumentSelector, options?: RemoveDocumentOptions): Promise<DocumentOperationResult<T>>;
}

Document Collections

Graph Operations

Graph database operations for managing vertices, edges, and graph structures.

class Graph {
  exists(): Promise<boolean>;
  get(): Promise<GraphDescription>;
  create(edgeDefinitions: EdgeDefinitionOptions[], options?: CreateGraphOptions): Promise<GraphDescription>;
  vertexCollection(name: string): GraphVertexCollection;
  edgeCollection(name: string): GraphEdgeCollection;
}

interface GraphVertexCollection<T = any, U = T> {
  vertex(selector: DocumentSelector, options?: ReadGraphDocumentOptions): Promise<Document<T>>;
  save(data: DocumentData<U>, options?: InsertGraphDocumentOptions): Promise<DocumentOperationResult<T>>;
}

Graph Operations

Query Execution and Cursors

Query execution with cursor-based result iteration for handling large result sets efficiently.

class Database {
  query<T>(query: AqlQuery<T>, options?: QueryOptions): Promise<Cursor<T>>;
  explain(query: AqlQuery, options?: ExplainOptions): Promise<ExplainResult>;
}

class Cursor<ItemType> {
  readonly hasNext: boolean;
  readonly count: number;
  next(): Promise<ItemType | undefined>;
  all(): Promise<ItemType[]>;
}

Query Execution

Transaction Management

Database transaction support for ensuring data consistency across multiple operations.

class Database {
  beginTransaction(collections: TransactionCollectionOptions, options?: TransactionOptions): Promise<Transaction>;
  executeTransaction<T>(action: string | TransactionFunction<T>, options?: TransactionOptions): Promise<T>;
}

class Transaction {
  commit(options?: TransactionCommitOptions): Promise<TransactionInfo>;
  abort(options?: TransactionAbortOptions): Promise<TransactionInfo>;
  step<T>(callback: () => Promise<T>): Promise<T>;
}

Transactions

Views and Search

ArangoSearch views and full-text search capabilities for advanced querying and indexing.

class View {
  exists(): Promise<boolean>;
  create(options: CreateViewOptions): Promise<ViewDescription>;
  properties(properties?: ViewPropertiesOptions): Promise<ViewProperties>;
}

interface CreateViewOptions {
  type: "arangosearch" | "search-alias";
  links?: Record<string, any>;
  primarySort?: any[];
}

Views and Search

Administration and Management

Database administration, user management, and system operations.

class Database {
  createDatabase(databaseName: string, options?: CreateDatabaseOptions): Promise<Database>;
  listDatabases(): Promise<string[]>;
  createUser(username: string, options?: UserOptions): Promise<User>;
  collections(excludeSystem?: boolean): Promise<Collection[]>;
}

Administration

Error Handling

Comprehensive error classes for handling different types of failures and exceptions.

class ArangoError extends Error {
  readonly name: "ArangoError";
  readonly errorNum: number;
  readonly code?: number;
  readonly isSafeToRetry: boolean | null;
}

class NetworkError extends Error {
  readonly name: "NetworkError";
  readonly isSafeToRetry: boolean | null;
  readonly request: globalThis.Request;
}

class HttpError extends NetworkError {
  readonly name: "HttpError";
  readonly code: number;
  readonly response: ProcessedResponse;
}

class PropagationTimeoutError extends Error {
  readonly name: "PropagationTimeoutError";
}

class ResponseTimeoutError extends NetworkError {
  readonly name: "ResponseTimeoutError";
}

class RequestAbortedError extends NetworkError {
  readonly name: "RequestAbortedError";
}

class FetchFailedError extends NetworkError {
  readonly name: "FetchFailedError";
}

function isArangoError(error: any): error is ArangoError;
function isNetworkError(error: any): error is NetworkError;

Usage Examples:

try {
  const result = await db.query(aql`FOR doc IN ${collection} RETURN doc`);
} catch (error) {
  if (isArangoError(error)) {
    console.error("ArangoDB error:", error.code, error.message);
  } else if (isNetworkError(error)) {
    console.error("Network error:", error.message);
  } else {
    console.error("Unknown error:", error);
  }
}

Types

interface LoadBalancingStrategy {
  "NONE" | "ROUND_ROBIN" | "ONE_RANDOM"
}

interface BasicAuthCredentials {
  username: string;
  password?: string;
}

interface BearerAuthCredentials {
  token: string;
}

interface ProcessedResponse {
  request: globalThis.Request;
  status: number;
  statusText: string;
  body: any;
}

interface DocumentMetadata {
  _key: string;
  _id: string;
  _rev: string;
}

interface EdgeMetadata extends DocumentMetadata {
  _from: string;
  _to: string;
}

type Document<T = any> = T & DocumentMetadata;
type Edge<T = any> = T & EdgeMetadata;
type DocumentData<T = any> = T & Partial<DocumentMetadata>;
type DocumentSelector = string | DocumentMetadata;