Required dependencies

npm install arangojs
npm install --save-dev @types/node

No native modules, no pod install, no prebuild steps. The driver works in Node.js 18+ and modern browsers with ESM support.

Project setup

1. Copy source: Place the source/ directory anywhere in your project, e.g. src/vendor/arangojs/.

2. TypeScript config — ensure your tsconfig.json resolves .js extensions from .ts files (required by the source's internal imports):

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2022",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true
  }
}

3. Path alias (optional) — add a path alias so you can import cleanly:

{
  "compilerOptions": {
    "paths": {
      "arangojs/*": ["./src/vendor/arangojs/*"]
    }
  }
}

4. Environment variables — configure via .env or process environment; no required env vars, but recommended to externalize credentials:

ARANGO_URL=http://127.0.0.1:8529
ARANGO_DB=myDatabase
ARANGO_USER=admin
ARANGO_PASSWORD=hunter2

5. Import from index.ts or directly from sub-modules:

import { arangojs, Database, aql } from "./vendor/arangojs/index.js";

Public API

arangojs()

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

Factory function that creates a Database instance with its own connection pool. Use this as the top-level entry point when you want a quick setup. Equivalent to new Database(config). Useful when you want CommonJS-compatible default-export behavior.

Database

class Database {
  constructor(config?: ConfigOptions | string | string[]);
  useBasicAuth(username: string, password?: string): this;
  collection<T extends Record<string, unknown> = any>(name: string): DocumentCollection<T> & EdgeCollection<T>;
  query<T = any>(query: AqlQuery | string, bindVars?: Record<string, any>, options?: QueryOptions): Promise<ArrayCursor<T>>;
  createDatabase(name: string, options?: CreateDatabaseOptions): Promise<Database>;
  listDatabases(): Promise<string[]>;
  graph(name: string): Graph;
  // ... many more methods
}

The central class for all ArangoDB interaction. Every operation—queries, collection management, user management, transactions—goes through a Database instance. Use one instance per logical database connection; it manages an internal connection pool automatically.

aql

function aql(strings: TemplateStringsArray, ...args: any[]): AqlQuery;

Tagged template literal for building AQL queries with safe bind variable injection. Always use aql instead of string concatenation to prevent injection and to correctly reference collection objects. Arguments are automatically converted to bind variables; ArangoCollection objects become collection bind vars (@@collection).

isArangoCollection()

function isArangoCollection(collection: any): collection is ArangoCollection;

Type guard that checks whether a value is an ArangoCollection. Use this when writing generic helpers that accept either a collection name string or a collection object, to branch correctly before calling collectionToString().

Working examples

Scenario - Connect and run an AQL query

Connect to a local ArangoDB instance, select a collection, and iterate query results using the aql template tag and async cursor iteration.

import { Database, aql } from "./vendor/arangojs/index.js";

const db = new Database({
  url: process.env.ARANGO_URL ?? "http://127.0.0.1:8529",
  databaseName: process.env.ARANGO_DB ?? "_system",
  auth: {
    username: process.env.ARANGO_USER ?? "root",
    password: process.env.ARANGO_PASSWORD ?? "",
  },
});

async function findActiveUsers(): Promise<void> {
  const users = db.collection("users");
  const cursor = await db.query<{ name: string; email: string }>(aql`
    FOR u IN ${users}
    FILTER u.active == true
    SORT u.name ASC
    RETURN { name: u.name, email: u.email }
  `);
  for await (const user of cursor) {
    console.log(user.name, user.email);
  }
}

findActiveUsers().catch(console.error);

Scenario - Create a collection and insert documents

Programmatically create a document collection if it does not exist, then insert records.

import { Database } from "./vendor/arangojs/index.js";
import type { DocumentCollection } from "./vendor/arangojs/collections.js";

const db = new Database({ url: "http://127.0.0.1:8529" });

interface Product {
  sku: string;
  name: string;
  price: number;
}

async function seedProducts(): Promise<void> {
  let col: DocumentCollection<Product>;
  try {
    col = await db.createCollection<Product>("products");
  } catch {
    col = db.collection<Product>("products");
  }

  await col.save({ sku: "ABC-1", name: "Widget", price: 9.99 });
  await col.save({ sku: "ABC-2", name: "Gadget", price: 24.99 });
  console.log("Products seeded.");
}

seedProducts().catch(console.error);

Scenario - Graph traversal

Create a named graph with edge and vertex collections, then query it with a traversal.

import { Database, aql } from "./vendor/arangojs/index.js";

const db = new Database({ url: "http://127.0.0.1:8529", databaseName: "social" });

async function findFriends(startId: string): Promise<void> {
  const graph = db.graph("friendships");

  // Create graph if it doesn't exist (first run only)
  try {
    await graph.create([
      { collection: "knows", from: ["people"], to: ["people"] },
    ]);
  } catch {
    // already exists
  }

  const people = db.collection("people");
  const cursor = await db.query(aql`
    FOR v, e, p IN 1..2 OUTBOUND ${startId}
    GRAPH "friendships"
    RETURN v
  `);
  for await (const person of cursor) {
    console.log(person._key, person.name);
  }
}

findFriends("people/alice").catch(console.error);

File walkthrough

• index.ts - Re-exports everything; the arangojs() factory lives here. Start here for the default import.
• databases.ts - Defines Database with all database, collection, graph, user, view, and query methods.
• collections.ts - DocumentCollection and EdgeCollection classes plus isArangoCollection and collectionToString utilities.
• graphs.ts - Graph, GraphVertexCollection, GraphEdgeCollection; handles Gharial API edge definitions.
• documents.ts - Type definitions for Document<T>, Edge<T>, DocumentMetadata, and patch/replace helpers.
• aql.ts - aql template tag and AqlQuery/AqlLiteral types; used everywhere queries are built.
• cursors.ts - ArrayCursor and BatchedArrayCursor wrapping server-side cursors; supports for await.
• analyzers.ts - Analyzer class for creating/deleting/listing ArangoSearch analyzers.
• views.ts - ArangoSearchView and SearchAliasView management.
• indexes.ts - Index descriptor types and collection index management methods.
• transactions.ts - Transaction class for begin/commit/abort of streaming transactions.
• queries.ts - Query listing, killing, and explain/profile support.
• users.ts - User CRUD and database/collection permission management.
• services.ts - Foxx service installation, upgrade, and configuration.
• routes.ts - Route class for direct HTTP calls to Foxx endpoints.
• jobs.ts - Async job result retrieval and cancellation.
• logs.ts - Server and topic log retrieval.
• cluster.ts - Cluster health, DB-Server management, and rebalancing.
• administration.ts - Engine info, shutdown, license, and metrics.
• hot-backups.ts - Hot backup creation, listing, restore, and deletion.
• errors.ts - ArangoError, HttpError, and isArangoError predicate.
• configuration.ts - ConfigOptions interface for URL, auth, timeouts, TLS, agent settings.
• connection.ts - Internal fetch-based connection pool; exports ArangoApiResponse.
• foxx-manifest.ts - Foxx manifest schema types.
• lib/codes.ts - Numeric ArangoDB error code constants (e.g. DOCUMENT_NOT_FOUND).
• lib/util.ts - Internal URL and header utilities.
• lib/x3-linkedlist.ts - Internal doubly-linked list for connection pool management.

Common pitfalls and fixes

• ESM .js extension in imports: The source uses import ... from "./foo.js" which is correct for Node ESM, but bundlers like webpack may need resolve.extensionAlias: { ".js": [".ts", ".js"] } configured.
• moduleResolution must be NodeNext or Bundler: Using "moduleResolution": "node" in tsconfig breaks the .js-extension imports; switch to NodeNext or Bundler.
• CommonJS interop: The index.ts sets module.exports = arangojs for CJS; if you require() the compiled output, the default export is the function, not the module namespace. Destructure with const { Database, aql } = require("./index.js").
• Connection refused on localhost: ArangoDB default port is 8529, not 5432 or 3306. Ensure the server is running and the URL includes the port: http://127.0.0.1:8529.
• Cursor exhausted after single iteration: ArrayCursor is single-pass. Call cursor.all() to collect all results into an array, or use for await exactly once; create a new query to re-iterate.
• @types/node required at compile time: Even for browser targets, the source references Node types for conditional logic. Install @types/node as a dev dependency or the TypeScript compiler will error on module/exports globals.

Vibe-coding prompt template

I have vendored the user@example.com TypeScript source into my project at src/vendor/arangojs/.
The integration guide is in src/vendor/arangojs/USAGE.md.

Please help me integrate this into my existing Node.js/TypeScript project step by step:

1. Read USAGE.md and the source files in src/vendor/arangojs/ to understand the real exported symbols.
2. Update my tsconfig.json to use moduleResolution: NodeNext and add any needed path aliases.
3. Create a src/lib/db.ts module that initializes a Database instance using environment variables
   (ARANGO_URL, ARANGO_DB, ARANGO_USER, ARANGO_PASSWORD) and exports it as a singleton.
4. Show me how to write a typed query using the `aql` template tag from src/vendor/arangojs/aql.ts
   against one of my existing collections (I'll tell you the collection name).
5. Show me how to handle ArangoError from src/vendor/arangojs/errors.ts in my Express error middleware.
6. Do not invent any API methods; only use symbols visible in USAGE.md and the source excerpts.

License and credit

arangojs is released under the Apache 2.0 License. See the upstream repository and source/LICENSE if present for the full license text.

Upstream package: arangojs on npm | GitHub | API Docs

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free