ts-prorm-orm 1.1.0 → 1.2.1

package/dist/nosql/arangodb/index.d.ts

@@ -0,0 +1,285 @@
+/**
+ * ArangoDB store implementation.
+ *
+ * ArangoDB is a multi-model database: it stores JSON documents (like a
+ * document store), lets those documents form named graphs (vertices/edges),
+ * and queries both shapes through a single query language, AQL. None of
+ * that fits the SQL-shaped `Dialect` interface (no `JOIN`, no relational
+ * schema, no `query(sql)` returning rows in the SQL sense), so this class
+ * implements the minimal `NoSqlStore` marker interface and exposes
+ * ArangoDB's real surface directly: collection management, document CRUD,
+ * parameterized AQL queries with cursor-based iteration, graph/edge
+ * operations (including AQL graph traversal), and index management.
+ *
+ * Uses the official `arangojs` driver (v10).
+ */
+import type { Database } from 'arangojs';
+import type { ConfigOptions } from 'arangojs/configuration';
+import type { CreateCollectionOptions as ArangoCreateCollectionOptions, CollectionDescription, DropCollectionOptions } from 'arangojs/collections';
+import type { Document as ArangoDocument, DocumentData, DocumentMetadata, DocumentOperationFailure, DocumentOperationMetadata, DocumentSelector, InsertDocumentOptions, Patch, ReadDocumentOptions, RemoveDocumentOptions, ReplaceDocumentOptions, UpdateDocumentOptions } from 'arangojs/documents';
+import type { Cursor } from 'arangojs/cursors';
+import type { QueryOptions } from 'arangojs/queries';
+import type { CreateGraphOptions, EdgeDefinitionOptions, GraphDescription } from 'arangojs/graphs';
+import type { IndexDescription, IndexSelector } from 'arangojs/indexes';
+import { NoSqlStore } from '../store';
+/**
+ * Connection options for `ArangoStore`.
+ *
+ * This is `arangojs`'s own `ConfigOptions` passed straight through: `url`
+ * (single URL or a list, for cluster/load-balanced setups), `databaseName`
+ * (defaults to `"_system"`), `auth` (`{ username, password }` or
+ * `{ token }`), plus pool size, load-balancing strategy, and fetch options.
+ */
+export type ArangoStoreOptions = ConfigOptions;
+/** Options for `createCollection()`/`createEdgeCollection()` (collection `type` is set by the method you call). */
+export type ArangoCollectionOptions = Omit<ArangoCreateCollectionOptions, 'type'>;
+/**
+ * Index types accepted by `createIndex()`.
+ *
+ * `"hash"` and `"skiplist"` are historical ArangoDB index type names that
+ * modern ArangoDB (3.12+) treats as aliases for `"persistent"` - both are
+ * accepted here and normalized to `"persistent"` before being sent to the
+ * server, so existing code/config referring to them by their old names
+ * keeps working.
+ */
+export type ArangoIndexType = 'persistent' | 'hash' | 'skiplist' | 'geo' | 'fulltext' | 'ttl';
+/** Options for `createIndex()`. Which fields are meaningful depends on `type`. */
+export interface CreateIndexOptions {
+    type: ArangoIndexType;
+    /** Document fields the index covers (e.g. `['email']`, `['location']`). */
+    fields: string[];
+    /** Explicit index name. Auto-generated by the server if omitted. */
+    name?: string;
+    /** `persistent`/`hash`/`skiplist`: enforce uniqueness of the indexed field(s). */
+    unique?: boolean;
+    /** `persistent`/`hash`/`skiplist`/`geo`: exclude documents missing the indexed field(s). */
+    sparse?: boolean;
+    /** `geo`: interpret the indexed field as a GeoJSON object rather than `[lat, lon]`. */
+    geoJson?: boolean;
+    /** `fulltext`: minimum word length to index. */
+    minLength?: number;
+    /** `ttl`: seconds after the indexed timestamp field at which documents expire. */
+    expireAfter?: number;
+    /** Build the index without blocking other operations on the collection. */
+    inBackground?: boolean;
+}
+/** Direction of an AQL graph traversal. */
+export type TraverseDirection = 'OUTBOUND' | 'INBOUND' | 'ANY';
+/** Options for `traverse()`. */
+export interface TraverseOptions {
+    /** Traversal direction relative to the start vertex. Default `'OUTBOUND'`. */
+    direction?: TraverseDirection;
+    /** Minimum traversal depth (1 = direct neighbors). Default `1`. */
+    minDepth?: number;
+    /** Maximum traversal depth. Default `1`. */
+    maxDepth?: number;
+    /**
+     * Raw AQL boolean expression appended as a `FILTER` clause, evaluated
+     * per visited path with `v` (vertex), `e` (edge), and `p` (path) bound as
+     * in a normal AQL graph traversal (e.g. `'v.active == true'`).
+     * Interpolated directly into the query - do not build this from
+     * unsanitized user input.
+     */
+    filter?: string;
+    /** Cap the number of visited paths returned. */
+    limit?: number;
+}
+/** One visited path from `traverse()`: the vertex reached, the edge taken to reach it (`null` at depth 0), and the full path. */
+export interface TraversalResult<V = Record<string, unknown>, E = Record<string, unknown>> {
+    vertex: V;
+    edge: E | null;
+    path: {
+        vertices: V[];
+        edges: E[];
+    };
+}
+/** One `[field, direction]` ordering term, e.g. `['createdAt', 'DESC']`. */
+export type OrderTerm = [string, 'ASC' | 'DESC'] | string;
+/** Options for {@link ArangoStore.findAll}/{@link ArangoStore.findOne}. */
+export interface ArangoFindOptions {
+    /** Ordering terms applied in sequence. A bare string sorts ascending. */
+    order?: OrderTerm | OrderTerm[];
+    /** Maximum number of documents to return. */
+    limit?: number;
+    /** Number of leading documents to skip (offset). */
+    offset?: number;
+}
+/** A group-aggregation request for {@link ArangoStore.aggregate}. */
+export interface ArangoAggregateOptions {
+    /** ORM `where` filter applied before grouping. */
+    where?: Record<string | symbol, unknown>;
+    /** Field(s) to group by. Omit for a single whole-collection group. */
+    groupBy?: string | string[];
+    /** Emit a `count` per group. */
+    count?: boolean;
+    /** Fields to `sum` per group, keyed by output name → source field. */
+    sum?: Record<string, string>;
+    /** Fields to `avg` per group, keyed by output name → source field. */
+    avg?: Record<string, string>;
+    /** Fields to `min` per group, keyed by output name → source field. */
+    min?: Record<string, string>;
+    /** Fields to `max` per group, keyed by output name → source field. */
+    max?: Record<string, string>;
+}
+/**
+ * `ArangoStore` wraps the official `arangojs` driver's `Database`/
+ * `Collection`/`Graph`/`Cursor` API in a typed, promise-based convenience
+ * layer covering document CRUD, AQL queries, graphs, and indexes.
+ */
+export declare class ArangoStore implements NoSqlStore {
+    readonly name = "arangodb";
+    readonly library = "arangojs";
+    private readonly options;
+    private db;
+    private connected;
+    constructor(options?: ArangoStoreOptions);
+    /**
+     * `arangojs`'s `Database` is a thin HTTP client wrapper with no persistent
+     * socket to open, so "connecting" here means constructing it and making
+     * one real request (`version()`) to fail fast on a bad URL/host/auth
+     * instead of only discovering the problem on the first real operation.
+     */
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `arangojs` `Database` instance for anything not wrapped here. */
+    getClient(): Database;
+    private requireDb;
+    private exec;
+    /** Create a document collection. */
+    createCollection(collectionName: string, options?: ArangoCollectionOptions): Promise<CollectionDescription>;
+    /** Create an edge collection (documents store `_from`/`_to` and can be traversed as graph edges). */
+    createEdgeCollection(collectionName: string, options?: ArangoCollectionOptions): Promise<CollectionDescription>;
+    /** Drop a collection (document or edge). */
+    dropCollection(collectionName: string, options?: DropCollectionOptions): Promise<boolean>;
+    /** Whether a collection with this name exists. */
+    collectionExists(collectionName: string): Promise<boolean>;
+    /** List collections in the database (excludes system collections like `_users` by default). */
+    listCollections(excludeSystem?: boolean): Promise<CollectionDescription[]>;
+    /** Remove all documents from a collection without dropping the collection itself. */
+    truncateCollection(collectionName: string): Promise<void>;
+    /** Number of documents currently in a collection. */
+    collectionCount(collectionName: string): Promise<number>;
+    /** Insert a single document. Pass `_key` in `data` to choose the key explicitly; otherwise ArangoDB generates one. */
+    insert<T extends Record<string, unknown> = Record<string, unknown>>(collectionName: string, data: DocumentData<T>, options?: InsertDocumentOptions): Promise<DocumentOperationMetadata & {
+        new?: ArangoDocument<T>;
+    }>;
+    /** Insert multiple documents in one request. Per-document failures (e.g. duplicate `_key`) come back as entries with `error: true` rather than throwing. */
+    insertMany<T extends Record<string, unknown> = Record<string, unknown>>(collectionName: string, data: Array<DocumentData<T>>, options?: InsertDocumentOptions): Promise<Array<(DocumentOperationMetadata & {
+        new?: ArangoDocument<T>;
+    }) | DocumentOperationFailure>>;
+    /** Fetch a single document by key/id. Returns `null` if it does not exist (rather than throwing). */
+    getDocument<T extends Record<string, unknown> = Record<string, unknown>>(collectionName: string, selector: DocumentSelector, options?: Omit<ReadDocumentOptions, 'graceful'>): Promise<ArangoDocument<T> | null>;
+    /** Fetch multiple documents by key/id. Entries for documents that don't exist come back as `null`. */
+    getDocuments<T extends Record<string, unknown> = Record<string, unknown>>(collectionName: string, selectors: string[]): Promise<Array<ArangoDocument<T> | null>>;
+    /** Whether a document with this key/id exists in the collection. */
+    documentExists(collectionName: string, selector: DocumentSelector): Promise<boolean>;
+    /** Partially update a document (shallow/deep merge of `patch` into the existing document, per ArangoDB's `PATCH` semantics). */
+    updateDocument<T extends Record<string, unknown> = Record<string, unknown>>(collectionName: string, selector: DocumentSelector, patch: Patch<DocumentData<T>>, options?: UpdateDocumentOptions): Promise<DocumentOperationMetadata & {
+        new?: ArangoDocument<T>;
+        old?: ArangoDocument<T>;
+    }>;
+    /** Fully replace a document's content (unlike `updateDocument`, unspecified fields are dropped). */
+    replaceDocument<T extends Record<string, unknown> = Record<string, unknown>>(collectionName: string, selector: DocumentSelector, data: DocumentData<T>, options?: ReplaceDocumentOptions): Promise<DocumentOperationMetadata & {
+        new?: ArangoDocument<T>;
+        old?: ArangoDocument<T>;
+    }>;
+    /** Delete a single document by key/id. */
+    removeDocument(collectionName: string, selector: DocumentSelector, options?: RemoveDocumentOptions): Promise<DocumentMetadata>;
+    /** Delete multiple documents by key/id in one request. */
+    removeDocuments(collectionName: string, selectors: string[]): Promise<Array<DocumentMetadata | DocumentOperationFailure>>;
+    /**
+     * Run a parameterized AQL query and return the (cursor-based) result
+     * set as a native `arangojs` `Cursor` - iterate it with `for await`,
+     * `cursor.next()`, or `cursor.all()` to page through large result sets
+     * without loading everything into memory at once. Use `@name` in `query`
+     * for bind parameters and supply their values via `bindVars` (never
+     * string-interpolate untrusted values into `query` itself).
+     */
+    query<T = unknown>(query: string, bindVars?: Record<string, unknown>, options?: QueryOptions): Promise<Cursor<T>>;
+    /** Convenience wrapper around `query()` that depletes the cursor and returns all results as an array. */
+    queryAll<T = unknown>(query: string, bindVars?: Record<string, unknown>, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Fetch all documents in `collectionName` matching an ORM `where` clause,
+     * with optional ordering, offset, and limit. The `where` object accepts the
+     * full ORM operator surface (`Op.gt`, `Op.in`, `Op.between`, `Op.like`,
+     * `Op.and`/`Op.or`, ...), compiled to a parameterized AQL `FILTER` (values
+     * and field names are always bound, never interpolated) - so standard
+     * queries never require hand-written AQL.
+     */
+    findAll<T = Record<string, unknown>>(collectionName: string, where?: Record<string | symbol, unknown>, options?: ArangoFindOptions): Promise<T[]>;
+    /** Fetch the first document in `collectionName` matching an ORM `where` clause (respecting `order`), or `null`. */
+    findOne<T = Record<string, unknown>>(collectionName: string, where?: Record<string | symbol, unknown>, options?: Omit<ArangoFindOptions, 'limit'>): Promise<T | null>;
+    /** Count documents in `collectionName` matching an ORM `where` clause. */
+    count(collectionName: string, where?: Record<string | symbol, unknown>): Promise<number>;
+    /**
+     * Update every document in `collectionName` matching an ORM `where` clause,
+     * merging `patch` into each. Returns the updated documents (`RETURN NEW`).
+     */
+    updateWhere<T = Record<string, unknown>>(collectionName: string, where: Record<string | symbol, unknown>, patch: Record<string, unknown>): Promise<T[]>;
+    /**
+     * Remove every document in `collectionName` matching an ORM `where` clause.
+     * Returns the removed documents (`RETURN OLD`).
+     */
+    removeWhere<T = Record<string, unknown>>(collectionName: string, where: Record<string | symbol, unknown>): Promise<T[]>;
+    /**
+     * Native AQL `UPSERT`: find a document matching `search`; if none exists
+     * insert `insert`, otherwise update the match with `update` (defaults to
+     * `insert`). Returns the resulting document (`RETURN NEW`).
+     */
+    upsert<T = Record<string, unknown>>(collectionName: string, search: Record<string, unknown>, insert: Record<string, unknown>, update?: Record<string, unknown>): Promise<T | null>;
+    /**
+     * Grouped aggregation over `collectionName` using AQL's native
+     * `COLLECT ... AGGREGATE` (`count`/`sum`/`avg`/`min`/`max`), with an optional
+     * ORM `where` pre-filter. Returns one entry per group: `{ group, ...aggregates }`
+     * (`group` is `null` when no `groupBy` is given).
+     */
+    aggregate(collectionName: string, options?: ArangoAggregateOptions): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Create a named graph over one or more edge definitions (each mapping
+     * an edge collection to the vertex collection(s) it connects `from` and
+     * `to`). Collections referenced by the edge definitions that don't exist
+     * yet are created automatically by ArangoDB.
+     */
+    createGraph(graphName: string, edgeDefinitions: EdgeDefinitionOptions[], options?: CreateGraphOptions): Promise<GraphDescription>;
+    /** Drop a graph. If `dropCollections` is `true`, also drops the graph's vertex/edge collections (as long as they aren't used by another graph). */
+    dropGraph(graphName: string, dropCollections?: boolean): Promise<boolean>;
+    /** Whether a graph with this name exists. */
+    graphExists(graphName: string): Promise<boolean>;
+    /** List all graphs in the database. */
+    listGraphs(): Promise<GraphDescription[]>;
+    /** Add an existing (or new) vertex collection to a graph as an orphan collection (not tied to a specific edge definition). */
+    addVertexCollection(graphName: string, collectionName: string): Promise<GraphDescription>;
+    /** Add a new edge definition to an existing graph. */
+    addEdgeDefinition(graphName: string, edgeDefinition: EdgeDefinitionOptions): Promise<GraphDescription>;
+    /** Insert an edge document into an edge collection, connecting `from` and `to` (each a document `_id`, e.g. `'people/alice'`). */
+    insertEdge<T extends Record<string, unknown> = Record<string, unknown>>(edgeCollectionName: string, from: string, to: string, data?: T, options?: InsertDocumentOptions): Promise<DocumentOperationMetadata & {
+        new?: ArangoDocument<T>;
+    }>;
+    /**
+     * Traverse a named graph from a start vertex using AQL's
+     * `FOR v, e, p IN min..max DIRECTION start GRAPH graphName` syntax,
+     * returning each visited vertex (`v`), the edge that reached it (`e`,
+     * `null` at depth 0), and the full path (`p`) as vertex/edge arrays.
+     *
+     * @param startVertexId - Start vertex `_id`, e.g. `'people/alice'`.
+     * @param graphName - Name of a graph created with `createGraph()`.
+     */
+    traverse<V extends Record<string, unknown> = Record<string, unknown>, E extends Record<string, unknown> = Record<string, unknown>>(startVertexId: string, graphName: string, options?: TraverseOptions): Promise<TraversalResult<V, E>[]>;
+    /** Create an index on a collection. `type: 'hash'`/`'skiplist'` are normalized to `'persistent'` (see `ArangoIndexType`). */
+    createIndex(collectionName: string, options: CreateIndexOptions): Promise<IndexDescription>;
+    /** Drop an index by id or name. */
+    dropIndex(collectionName: string, selector: IndexSelector): Promise<boolean>;
+    /** List all indexes on a collection (including the automatic primary/edge indexes). */
+    listIndexes(collectionName: string): Promise<IndexDescription[]>;
+    /** Fetch a single index's description by id or name. */
+    getIndex(collectionName: string, selector: IndexSelector): Promise<IndexDescription>;
+    /**
+     * Resolve a `{ name }`-only `IndexSelector` to an `{ id }` one by looking
+     * it up via `listIndexes()` first. String selectors and selectors that
+     * already carry an `id` are passed through unchanged - see
+     * `isNameOnlySelector()` for why this is necessary.
+     */
+    private resolveIndexSelector;
+}
+export default ArangoStore;

package/dist/nosql/arangodb/index.js

@@ -16,8 +16,25 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArangoStore = void 0;
-const arangojs_1 = require("arangojs");
+// Lazily-loaded `arangojs` driver. Required only when a connection is opened,
+// so importing this ORM never loads the arangojs driver.
+let arangojsModule = null;
+function loadArangoJs() {
+    if (!arangojsModule) {
+        try {
+            arangojsModule = require('arangojs');
+        }
+        catch (err) {
+            throw new Error("The 'arangojs' package is required to use the ArangoDB store but could not be loaded. " +
+                'Install it with `npm install arangojs`. Original error: ' +
+                (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    return arangojsModule;
+}
 const errors_1 = require("../../errors");
+const operators_1 = require("../../operators");
+const where_1 = require("./where");
 function wrapConnectionError(err, url) {
     const parent = err instanceof Error ? err : new Error(String(err));
     const host = Array.isArray(url) ? url[0] : url;
@@ -35,6 +52,145 @@ function wrapDatabaseError(err, message) {
     const combined = message ? `${message}: ${parent.message}` : parent.message;
     return errors_1.DatabaseError.from(parent, { message: combined });
 }
+/**
+ * Accumulates AQL bind variables while building a query, minting unique
+ * `@vN` names so untrusted values (and dynamic field names) are always sent
+ * as bind parameters rather than string-interpolated into the query.
+ */
+class AqlBinder {
+    constructor() {
+        this.counter = 0;
+        this.bindVars = {};
+    }
+    /** Bind a value and return its `@vN` placeholder for interpolation into the query. */
+    add(value) {
+        const name = `v${this.counter++}`;
+        this.bindVars[name] = value;
+        return `@${name}`;
+    }
+}
+/** Escape a literal for an AQL `LIKE` pattern (`%`, `_`, and `\` are special). */
+function escapeAqlLike(s) {
+    return s.replace(/[\\%_]/g, '\\$&');
+}
+/**
+ * Render a {@link WhereNode} tree into an AQL boolean expression over the loop
+ * variable `docVar` (e.g. `doc`), binding all values/field names through
+ * `binder`. This is what lets callers pass ORM `where` clauses instead of
+ * hand-writing AQL FILTER expressions.
+ */
+function buildAqlFilter(node, docVar, binder) {
+    switch (node.kind) {
+        case 'true':
+            return 'true';
+        case 'and': {
+            const parts = node.nodes.map((n) => buildAqlFilter(n, docVar, binder));
+            return parts.length ? `(${parts.join(' AND ')})` : 'true';
+        }
+        case 'or': {
+            const parts = node.nodes.map((n) => buildAqlFilter(n, docVar, binder));
+            return parts.length ? `(${parts.join(' OR ')})` : 'false';
+        }
+        case 'not':
+            return `NOT (${buildAqlFilter(node.node, docVar, binder)})`;
+        case 'cmp':
+            return buildAqlCmp(node.field, node.op, node.value, docVar, binder);
+    }
+}
+function buildAqlCmp(field, op, value, docVar, binder) {
+    // Dynamic, injection-safe attribute access: doc[@vN] with field name bound.
+    const lhs = `${docVar}[${binder.add(field)}]`;
+    switch (op) {
+        case operators_1.Op.eq:
+            return `${lhs} == ${binder.add(value)}`;
+        case operators_1.Op.ne:
+            return `${lhs} != ${binder.add(value)}`;
+        case operators_1.Op.gt:
+            return `${lhs} > ${binder.add(value)}`;
+        case operators_1.Op.gte:
+            return `${lhs} >= ${binder.add(value)}`;
+        case operators_1.Op.lt:
+            return `${lhs} < ${binder.add(value)}`;
+        case operators_1.Op.lte:
+            return `${lhs} <= ${binder.add(value)}`;
+        case operators_1.Op.in:
+            return `${lhs} IN ${binder.add(value)}`;
+        case operators_1.Op.notIn:
+            return `${lhs} NOT IN ${binder.add(value)}`;
+        case operators_1.Op.between: {
+            const [lo, hi] = value;
+            return `(${lhs} >= ${binder.add(lo)} AND ${lhs} <= ${binder.add(hi)})`;
+        }
+        case operators_1.Op.notBetween: {
+            const [lo, hi] = value;
+            return `NOT (${lhs} >= ${binder.add(lo)} AND ${lhs} <= ${binder.add(hi)})`;
+        }
+        case operators_1.Op.isNull:
+            return `${lhs} == null`;
+        case operators_1.Op.isNotNull:
+            return `${lhs} != null`;
+        case operators_1.Op.like:
+            return `LIKE(${lhs}, ${binder.add(value)}, false)`;
+        case operators_1.Op.iLike:
+            return `LIKE(${lhs}, ${binder.add(value)}, true)`;
+        case operators_1.Op.notLike:
+            return `NOT LIKE(${lhs}, ${binder.add(value)}, false)`;
+        case operators_1.Op.notILike:
+            return `NOT LIKE(${lhs}, ${binder.add(value)}, true)`;
+        case operators_1.Op.startsWith:
+            return `LIKE(${lhs}, ${binder.add(`${escapeAqlLike(String(value))}%`)}, false)`;
+        case operators_1.Op.endsWith:
+            return `LIKE(${lhs}, ${binder.add(`%${escapeAqlLike(String(value))}`)}, false)`;
+        case operators_1.Op.substring:
+        case operators_1.Op.contains:
+            return `LIKE(${lhs}, ${binder.add(`%${escapeAqlLike(String(value))}%`)}, false)`;
+        case operators_1.Op.regexp:
+            return `REGEX_TEST(${lhs}, ${binder.add(String(value))}, false)`;
+        case operators_1.Op.iRegexp:
+            return `REGEX_TEST(${lhs}, ${binder.add(String(value))}, true)`;
+        case operators_1.Op.notRegexp:
+            return `NOT REGEX_TEST(${lhs}, ${binder.add(String(value))}, false)`;
+        case operators_1.Op.notIRegexp:
+            return `NOT REGEX_TEST(${lhs}, ${binder.add(String(value))}, true)`;
+        default:
+            throw new errors_1.DatabaseError(`ArangoDB: unsupported where operator "${op.toString()}"`, {
+                code: errors_1.ErrorCodes.QUERY_ERROR,
+            });
+    }
+}
+/** Build an AQL `SORT` clause from ordering terms, binding field names safely. */
+function buildAqlSort(order, docVar, binder) {
+    if (order === undefined)
+        return '';
+    const single = Array.isArray(order) && order.length === 2 && typeof order[0] === 'string' && (order[1] === 'ASC' || order[1] === 'DESC');
+    const terms = (Array.isArray(order) && !single ? order : [order]);
+    const parts = terms.map((term) => {
+        if (typeof term === 'string')
+            return `${docVar}[${binder.add(term)}] ASC`;
+        return `${docVar}[${binder.add(term[0])}] ${term[1] === 'DESC' ? 'DESC' : 'ASC'}`;
+    });
+    return parts.length ? `SORT ${parts.join(', ')}` : '';
+}
+/**
+ * Validate an aggregate output alias is a safe AQL identifier before it is
+ * interpolated as a `COLLECT ... AGGREGATE` variable and result key (aliases
+ * are identifiers, not values, so they cannot be bind parameters).
+ */
+function sanitizeAlias(alias) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+        throw new errors_1.DatabaseError(`ArangoDB: invalid aggregate alias "${alias}" (must be a valid identifier)`, {
+            code: errors_1.ErrorCodes.QUERY_ERROR,
+        });
+    }
+    return alias;
+}
+/** Validate that a value is a non-negative integer (for inlining into AQL `LIMIT`). */
+function requireNonNegInt(value, label) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new errors_1.DatabaseError(`ArangoDB: ${label} must be a non-negative integer`, { code: errors_1.ErrorCodes.QUERY_ERROR });
+    }
+    return value;
+}
 /** Normalize `"hash"`/`"skiplist"` (legacy names) to `"persistent"`, the type ArangoDB 3.12+ actually stores them as. */
 function normalizeIndexType(type) {
     return type === 'hash' || type === 'skiplist' ? 'persistent' : type;
@@ -81,7 +237,7 @@ class ArangoStore {
             return;
         }
         try {
-            const db = new arangojs_1.Database(this.options);
+            const db = new (loadArangoJs().Database)(this.options);
             await db.version();
             this.db = db;
             this.connected = true;
@@ -235,6 +391,122 @@ class ArangoStore {
         return cursor.all();
     }
     // ---------------------------------------------------------------------
+    // ORM-shaped queries (no hand-written AQL required)
+    // ---------------------------------------------------------------------
+    /**
+     * Fetch all documents in `collectionName` matching an ORM `where` clause,
+     * with optional ordering, offset, and limit. The `where` object accepts the
+     * full ORM operator surface (`Op.gt`, `Op.in`, `Op.between`, `Op.like`,
+     * `Op.and`/`Op.or`, ...), compiled to a parameterized AQL `FILTER` (values
+     * and field names are always bound, never interpolated) - so standard
+     * queries never require hand-written AQL.
+     */
+    async findAll(collectionName, where = {}, options = {}) {
+        const binder = new AqlBinder();
+        binder.bindVars['@col'] = collectionName;
+        const filter = buildAqlFilter((0, where_1.parseWhere)(where), 'doc', binder);
+        const sort = buildAqlSort(options.order, 'doc', binder);
+        let limitClause = '';
+        if (typeof options.limit === 'number' || typeof options.offset === 'number') {
+            const offset = requireNonNegInt(options.offset ?? 0, 'offset');
+            const limit = requireNonNegInt(options.limit ?? Number.MAX_SAFE_INTEGER, 'limit');
+            limitClause = `LIMIT ${offset}, ${limit}`;
+        }
+        const aql = `FOR doc IN @@col FILTER ${filter} ${sort} ${limitClause} RETURN doc`;
+        return this.queryAll(aql, binder.bindVars);
+    }
+    /** Fetch the first document in `collectionName` matching an ORM `where` clause (respecting `order`), or `null`. */
+    async findOne(collectionName, where = {}, options = {}) {
+        const rows = await this.findAll(collectionName, where, { ...options, limit: 1 });
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /** Count documents in `collectionName` matching an ORM `where` clause. */
+    async count(collectionName, where = {}) {
+        const binder = new AqlBinder();
+        binder.bindVars['@col'] = collectionName;
+        const filter = buildAqlFilter((0, where_1.parseWhere)(where), 'doc', binder);
+        const aql = `FOR doc IN @@col FILTER ${filter} COLLECT WITH COUNT INTO n RETURN n`;
+        const rows = await this.queryAll(aql, binder.bindVars);
+        return rows[0] ?? 0;
+    }
+    /**
+     * Update every document in `collectionName` matching an ORM `where` clause,
+     * merging `patch` into each. Returns the updated documents (`RETURN NEW`).
+     */
+    async updateWhere(collectionName, where, patch) {
+        const binder = new AqlBinder();
+        binder.bindVars['@col'] = collectionName;
+        const filter = buildAqlFilter((0, where_1.parseWhere)(where), 'doc', binder);
+        const patchRef = binder.add(patch);
+        const aql = `FOR doc IN @@col FILTER ${filter} UPDATE doc WITH ${patchRef} IN @@col RETURN NEW`;
+        return this.queryAll(aql, binder.bindVars);
+    }
+    /**
+     * Remove every document in `collectionName` matching an ORM `where` clause.
+     * Returns the removed documents (`RETURN OLD`).
+     */
+    async removeWhere(collectionName, where) {
+        const binder = new AqlBinder();
+        binder.bindVars['@col'] = collectionName;
+        const filter = buildAqlFilter((0, where_1.parseWhere)(where), 'doc', binder);
+        const aql = `FOR doc IN @@col FILTER ${filter} REMOVE doc IN @@col RETURN OLD`;
+        return this.queryAll(aql, binder.bindVars);
+    }
+    /**
+     * Native AQL `UPSERT`: find a document matching `search`; if none exists
+     * insert `insert`, otherwise update the match with `update` (defaults to
+     * `insert`). Returns the resulting document (`RETURN NEW`).
+     */
+    async upsert(collectionName, search, insert, update) {
+        const binder = new AqlBinder();
+        binder.bindVars['@col'] = collectionName;
+        const searchRef = binder.add(search);
+        const insertRef = binder.add(insert);
+        const updateRef = binder.add(update ?? insert);
+        const aql = `UPSERT ${searchRef} INSERT ${insertRef} UPDATE ${updateRef} IN @@col RETURN NEW`;
+        const rows = await this.queryAll(aql, binder.bindVars);
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /**
+     * Grouped aggregation over `collectionName` using AQL's native
+     * `COLLECT ... AGGREGATE` (`count`/`sum`/`avg`/`min`/`max`), with an optional
+     * ORM `where` pre-filter. Returns one entry per group: `{ group, ...aggregates }`
+     * (`group` is `null` when no `groupBy` is given).
+     */
+    async aggregate(collectionName, options = {}) {
+        const binder = new AqlBinder();
+        binder.bindVars['@col'] = collectionName;
+        const filter = buildAqlFilter((0, where_1.parseWhere)(options.where ?? {}), 'doc', binder);
+        const groupFields = options.groupBy
+            ? Array.isArray(options.groupBy)
+                ? options.groupBy
+                : [options.groupBy]
+            : [];
+        const collectParts = groupFields.map((f, i) => `g${i} = doc[${binder.add(f)}]`);
+        const aggParts = [];
+        const hasOtherAgg = !!(options.sum || options.avg || options.min || options.max);
+        if (options.count || !hasOtherAgg)
+            aggParts.push('count = LENGTH(doc)');
+        for (const [out, src] of Object.entries(options.sum ?? {}))
+            aggParts.push(`${sanitizeAlias(out)} = SUM(doc[${binder.add(src)}])`);
+        for (const [out, src] of Object.entries(options.avg ?? {}))
+            aggParts.push(`${sanitizeAlias(out)} = AVERAGE(doc[${binder.add(src)}])`);
+        for (const [out, src] of Object.entries(options.min ?? {}))
+            aggParts.push(`${sanitizeAlias(out)} = MIN(doc[${binder.add(src)}])`);
+        for (const [out, src] of Object.entries(options.max ?? {}))
+            aggParts.push(`${sanitizeAlias(out)} = MAX(doc[${binder.add(src)}])`);
+        const collectClause = collectParts.length ? `COLLECT ${collectParts.join(', ')}` : 'COLLECT';
+        const aggregateClause = aggParts.length ? `AGGREGATE ${aggParts.join(', ')}` : '';
+        const groupExpr = groupFields.length === 0
+            ? 'null'
+            : groupFields.length === 1
+                ? 'g0'
+                : `[${groupFields.map((_, i) => `g${i}`).join(', ')}]`;
+        const returnFields = ['group: ' + groupExpr, ...aggParts.map((p) => p.split(' = ')[0]).map((a) => `${a}: ${a}`)];
+        const aql = `FOR doc IN @@col FILTER ${filter} ${collectClause} ${aggregateClause} RETURN { ${returnFields.join(', ')} }`;
+        return this.queryAll(aql, binder.bindVars);
+    }
+    // ---------------------------------------------------------------------
     // Graphs
     // ---------------------------------------------------------------------
     /**

package/dist/nosql/arangodb/where.d.ts

@@ -0,0 +1,38 @@
+/** A single field comparison, e.g. `age >= 18`. */
+export interface CmpNode {
+    kind: 'cmp';
+    field: string;
+    op: symbol;
+    value: unknown;
+}
+/** A normalized boolean tree produced by {@link parseWhere}. */
+export type WhereNode = CmpNode | {
+    kind: 'and';
+    nodes: WhereNode[];
+} | {
+    kind: 'or';
+    nodes: WhereNode[];
+} | {
+    kind: 'not';
+    node: WhereNode;
+} | {
+    kind: 'true';
+};
+/**
+ * Parse an ORM `where` object into a {@link WhereNode} tree.
+ *
+ * - String keys are field conditions: a scalar means equality, an array means
+ *   `Op.in`, and a nested `{ [Op.*]: value }` object expands to one comparison
+ *   per operator.
+ * - `Op.and`/`Op.or` take an array of sub-`where` objects; `Op.not` negates a
+ *   single sub-`where`.
+ */
+export declare function parseWhere(where: Record<string | symbol, unknown> | undefined | null): WhereNode;
+/** Escape a string for safe inclusion in a regular expression. */
+export declare function escapeRegex(s: string): string;
+/**
+ * Translate a SQL `LIKE`/`ILIKE` pattern into an anchored regular expression
+ * (`%` → `.*`, `_` → `.`), so stores that only speak regex can honor ORM
+ * `Op.like` queries without the caller hand-writing a pattern.
+ */
+export declare function likeToRegex(pattern: string, caseInsensitive?: boolean): string;