arangojs/esm/collections.js

The official ArangoDB JavaScript driver.

/**
 * ```ts
 * import type {
 *   DocumentCollection,
 *   EdgeCollection,
 * } from "arangojs/collections";
 * ```
 *
 * The "collections" module provides collection related types and interfaces
 * for TypeScript.
 *
 * @packageDocumentation
 */
import * as aql from "./aql.js";
import * as documents from "./documents.js";
import * as errors from "./errors.js";
import * as indexes from "./indexes.js";
import { COLLECTION_NOT_FOUND, DOCUMENT_NOT_FOUND } from "./lib/codes.js";
//#region ArangoCollection interface
/**
 * Indicates whether the given value represents an {@link ArangoCollection}.
 *
 * @param collection - A value that might be a collection.
 */
export function isArangoCollection(collection) {
    return Boolean(collection && collection.isArangoCollection);
}
/**
 * Coerces the given collection name or {@link ArangoCollection} object to
 * a string representing the collection name.
 *
 * @param collection - Collection name or {@link ArangoCollection} object.
 */
export function collectionToString(collection) {
    if (isArangoCollection(collection)) {
        return String(collection.name);
    }
    else
        return String(collection);
}
//#endregion
//#region Shared types
/**
 * Integer values indicating the collection type.
 */
export var CollectionType;
(function (CollectionType) {
    CollectionType[CollectionType["DOCUMENT_COLLECTION"] = 2] = "DOCUMENT_COLLECTION";
    CollectionType[CollectionType["EDGE_COLLECTION"] = 3] = "EDGE_COLLECTION";
})(CollectionType || (CollectionType = {}));
/**
 * Integer values indicating the collection loading status.
 */
export var CollectionStatus;
(function (CollectionStatus) {
    CollectionStatus[CollectionStatus["NEWBORN"] = 1] = "NEWBORN";
    CollectionStatus[CollectionStatus["UNLOADED"] = 2] = "UNLOADED";
    CollectionStatus[CollectionStatus["LOADED"] = 3] = "LOADED";
    CollectionStatus[CollectionStatus["UNLOADING"] = 4] = "UNLOADING";
    CollectionStatus[CollectionStatus["DELETED"] = 5] = "DELETED";
    CollectionStatus[CollectionStatus["LOADING"] = 6] = "LOADING";
})(CollectionStatus || (CollectionStatus = {}));
//#endregion
//#region Collection class
/**
 * @internal
 */
export class Collection {
    _name;
    _db;
    /**
     * @internal
     */
    constructor(db, name) {
        this._name = name;
        this._db = db;
    }
    get isArangoCollection() {
        return true;
    }
    get database() {
        return this._db;
    }
    get name() {
        return this._name;
    }
    //#region Collection operations
    get() {
        return this._db.request({
            pathname: `/_api/collection/${encodeURIComponent(this._name)}`,
        });
    }
    async exists() {
        try {
            await this.get();
            return true;
        }
        catch (err) {
            if (errors.isArangoError(err) && err.errorNum === COLLECTION_NOT_FOUND) {
                return false;
            }
            throw err;
        }
    }
    create(options = {}) {
        const { waitForSyncReplication = undefined, enforceReplicationFactor = undefined, ...opts } = options;
        if (opts.computedValues) {
            opts.computedValues = opts.computedValues.map((computedValue) => {
                if (aql.isAqlLiteral(computedValue.expression)) {
                    return {
                        ...computedValue,
                        expression: computedValue.expression.toAQL(),
                    };
                }
                if (aql.isAqlQuery(computedValue.expression)) {
                    return {
                        ...computedValue,
                        expression: computedValue.expression.query,
                    };
                }
                return computedValue;
            });
        }
        const search = {};
        if (typeof waitForSyncReplication === "boolean") {
            search.waitForSyncReplication = waitForSyncReplication ? 1 : 0;
        }
        if (typeof enforceReplicationFactor === "boolean") {
            search.enforceReplicationFactor = enforceReplicationFactor ? 1 : 0;
        }
        return this._db.request({
            method: "POST",
            pathname: "/_api/collection",
            search,
            body: {
                ...opts,
                name: this._name,
            },
        });
    }
    properties(properties) {
        if (!properties) {
            return this._db.request({
                pathname: `/_api/collection/${encodeURIComponent(this._name)}/properties`,
            });
        }
        return this._db.request({
            method: "PUT",
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/properties`,
            body: properties,
        });
    }
    count() {
        return this._db.request({
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/count`,
        });
    }
    async recalculateCount() {
        return this._db.request({
            method: "PUT",
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/recalculateCount`,
        }, (res) => res.parsedBody.result);
    }
    figures(details = false) {
        return this._db.request({
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/figures`,
            search: { details },
        });
    }
    revision() {
        return this._db.request({
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/revision`,
        });
    }
    checksum(options) {
        return this._db.request({
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/checksum`,
            search: options,
        });
    }
    shards(details) {
        return this._db.request({
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/shards`,
            search: { details },
        });
    }
    async rename(newName) {
        const result = await this._db.renameCollection(this._name, newName);
        this._name = newName;
        return result;
    }
    truncate(options) {
        return this._db.request({
            method: "PUT",
            pathname: `/_api/collection/${this._name}/truncate`,
            search: options,
        });
    }
    drop(options) {
        return this._db.request({
            method: "DELETE",
            pathname: `/_api/collection/${encodeURIComponent(this._name)}`,
            search: options,
        });
    }
    compact() {
        return this._db.request({
            method: "PUT",
            pathname: `/_api/collection/${this._name}/compact`,
        });
    }
    //#endregion
    //#region Document operations
    getResponsibleShard(document) {
        return this._db.request({
            method: "PUT",
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/responsibleShard`,
            body: document,
        }, (res) => res.parsedBody.shardId);
    }
    documentId(selector) {
        return documents._documentHandle(selector, this._name);
    }
    async documentExists(selector, options = {}) {
        const { ifMatch = undefined, ifNoneMatch = undefined } = options;
        const headers = {};
        if (ifMatch)
            headers["if-match"] = ifMatch;
        if (ifNoneMatch)
            headers["if-none-match"] = ifNoneMatch;
        try {
            return await this._db.request({
                method: "HEAD",
                pathname: `/_api/document/${encodeURI(documents._documentHandle(selector, this._name))}`,
                headers,
            }, (res) => {
                if (ifNoneMatch && res.status === 304) {
                    throw new errors.HttpError(res);
                }
                return true;
            });
        }
        catch (err) {
            if (err.code === 404) {
                return false;
            }
            throw err;
        }
    }
    documents(selectors, options = {}) {
        const { allowDirtyRead = undefined } = options;
        return this._db.request({
            method: "PUT",
            pathname: `/_api/document/${encodeURIComponent(this._name)}`,
            search: { onlyget: true },
            allowDirtyRead,
            body: selectors,
        });
    }
    async document(selector, options = {}) {
        if (typeof options === "boolean") {
            options = { graceful: options };
        }
        const { allowDirtyRead = undefined, graceful = false, ifMatch = undefined, ifNoneMatch = undefined, } = options;
        const headers = {};
        if (ifMatch)
            headers["if-match"] = ifMatch;
        if (ifNoneMatch)
            headers["if-none-match"] = ifNoneMatch;
        const result = this._db.request({
            pathname: `/_api/document/${encodeURI(documents._documentHandle(selector, this._name))}`,
            headers,
            allowDirtyRead,
        }, (res) => {
            if (ifNoneMatch && res.status === 304) {
                throw new errors.HttpError(res);
            }
            return res.parsedBody;
        });
        if (!graceful)
            return result;
        try {
            return await result;
        }
        catch (err) {
            if (errors.isArangoError(err) && err.errorNum === DOCUMENT_NOT_FOUND) {
                return null;
            }
            throw err;
        }
    }
    save(data, options) {
        return this._db.request({
            method: "POST",
            pathname: `/_api/document/${encodeURIComponent(this._name)}`,
            body: data,
            search: options,
        }, (res) => (options?.silent ? undefined : res.parsedBody));
    }
    saveAll(data, options) {
        return this._db.request({
            method: "POST",
            pathname: `/_api/document/${encodeURIComponent(this._name)}`,
            body: data,
            search: options,
        }, (res) => (options?.silent ? undefined : res.parsedBody));
    }
    replace(selector, newData, options = {}) {
        const { ifMatch = undefined, ...opts } = options;
        const headers = {};
        if (ifMatch)
            headers["if-match"] = ifMatch;
        return this._db.request({
            method: "PUT",
            pathname: `/_api/document/${encodeURI(documents._documentHandle(selector, this._name))}`,
            headers,
            body: newData,
            search: opts,
        }, (res) => (options?.silent ? undefined : res.parsedBody));
    }
    replaceAll(newData, options) {
        return this._db.request({
            method: "PUT",
            pathname: `/_api/document/${encodeURIComponent(this._name)}`,
            body: newData,
            search: options,
        }, (res) => (options?.silent ? undefined : res.parsedBody));
    }
    update(selector, newData, options = {}) {
        const { ifMatch = undefined, ...opts } = options;
        const headers = {};
        if (ifMatch)
            headers["if-match"] = ifMatch;
        return this._db.request({
            method: "PATCH",
            pathname: `/_api/document/${encodeURI(documents._documentHandle(selector, this._name))}`,
            headers,
            body: newData,
            search: opts,
        }, (res) => (options?.silent ? undefined : res.parsedBody));
    }
    updateAll(newData, options) {
        return this._db.request({
            method: "PATCH",
            pathname: `/_api/document/${encodeURIComponent(this._name)}`,
            body: newData,
            search: options,
        }, (res) => (options?.silent ? undefined : res.parsedBody));
    }
    remove(selector, options = {}) {
        const { ifMatch = undefined, ...opts } = options;
        const headers = {};
        if (ifMatch)
            headers["if-match"] = ifMatch;
        return this._db.request({
            method: "DELETE",
            pathname: `/_api/document/${encodeURI(documents._documentHandle(selector, this._name))}`,
            headers,
            search: opts,
        }, (res) => (options?.silent ? undefined : res.parsedBody));
    }
    removeAll(selectors, options) {
        return this._db.request({
            method: "DELETE",
            pathname: `/_api/document/${encodeURIComponent(this._name)}`,
            body: selectors,
            search: options,
        }, (res) => (options?.silent ? undefined : res.parsedBody));
    }
    import(data, options = {}) {
        const search = { ...options, collection: this._name };
        if (Array.isArray(data)) {
            search.type = Array.isArray(data[0]) ? undefined : "documents";
            const lines = data;
            data = lines.map((line) => JSON.stringify(line)).join("\r\n") + "\r\n";
        }
        return this._db.request({
            method: "POST",
            pathname: "/_api/import",
            body: data,
            isBinary: true,
            search,
        });
    }
    //#endregion
    //#region Edge operations
    _edges(selector, options = {}, direction) {
        const { allowDirtyRead = undefined } = options;
        return this._db.request({
            pathname: `/_api/edges/${encodeURIComponent(this._name)}`,
            allowDirtyRead,
            search: {
                direction,
                vertex: documents._documentHandle(selector, this._name, false),
            },
        });
    }
    edges(vertex, options) {
        return this._edges(vertex, options);
    }
    inEdges(vertex, options) {
        return this._edges(vertex, options, "in");
    }
    outEdges(vertex, options) {
        return this._edges(vertex, options, "out");
    }
    //#endregion
    //#region Index operations
    async loadIndexes() {
        return this._db.request({
            method: "PUT",
            pathname: `/_api/collection/${encodeURIComponent(this._name)}/loadIndexesIntoMemory`,
        }, (res) => res.parsedBody.result);
    }
    indexes(options) {
        return this._db.request({
            pathname: "/_api/index",
            search: { collection: this._name, ...options },
        }, (res) => res.parsedBody.indexes);
    }
    index(selector) {
        return this._db.request({
            pathname: `/_api/index/${encodeURI(indexes._indexHandle(selector, this._name))}`,
        });
    }
    ensureIndex(options) {
        return this._db.request({
            method: "POST",
            pathname: "/_api/index",
            body: options,
            search: { collection: this._name },
        });
    }
    dropIndex(selector) {
        return this._db.request({
            method: "DELETE",
            pathname: `/_api/index/${encodeURI(indexes._indexHandle(selector, this._name))}`,
        });
    }
}
//#endregion
//# sourceMappingURL=collections.js.map