arangojs 8.4.1 → 8.6.0

package/database.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Database = exports.isArangoDatabase = void 0;
+exports.Database = exports.LogLevel = exports.isArangoDatabase = void 0;
 const analyzer_1 = require("./analyzer");
 const aql_1 = require("./aql");
 const collection_1 = require("./collection");
@@ -8,6 +8,7 @@ const connection_1 = require("./connection");
 const cursor_1 = require("./cursor");
 const error_1 = require("./error");
 const graph_1 = require("./graph");
+const job_1 = require("./job");
 const codes_1 = require("./lib/codes");
 const multipart_1 = require("./lib/multipart");
 const route_1 = require("./route");
@@ -58,6 +59,17 @@ function coerceTransactionCollections(collections) {
     }
     return cols;
 }
+/**
+ * Numeric representation of the logging level of a log entry.
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["FATAL"] = 0] = "FATAL";
+    LogLevel[LogLevel["ERROR"] = 1] = "ERROR";
+    LogLevel[LogLevel["WARNING"] = 2] = "WARNING";
+    LogLevel[LogLevel["INFO"] = 3] = "INFO";
+    LogLevel[LogLevel["DEBUG"] = 4] = "DEBUG";
+})(LogLevel = exports.LogLevel || (exports.LogLevel = {}));
 /**
  * An object representing a single ArangoDB database. All arangojs collections,
  * cursors, analyzers and so on are linked to a `Database` object.
@@ -124,6 +136,15 @@ class Database {
             qs: { details },
         });
     }
+    /**
+     * Retrives the server's current system time in milliseconds with microsecond
+     * precision.
+     */
+    time() {
+        return this.request({
+            path: "/_admin/time",
+        }, (res) => res.body.time * 1000);
+    }
     /**
      * Returns a new {@link route.Route} instance for the given path (relative to the
      * database) that can be used to perform arbitrary HTTP requests.
@@ -149,10 +170,78 @@ class Database {
     route(path, headers) {
         return new route_1.Route(this, path, headers);
     }
-    request({ absolutePath = false, basePath, ...opts }, transform = (res) => res.body) {
+    /**
+     * Creates an async job by executing the given callback function. The first
+     * database request performed by the callback will be marked for asynchronous
+     * execution and its result will be made available as an async job.
+     *
+     * Returns a {@link Job} instance that can be used to retrieve the result
+     * of the callback function once the request has been executed.
+     *
+     * @param callback - Callback function to execute as an async job.
+     *
+     * @example
+     * ```js
+     * const db = new Database();
+     * const job = await db.createJob(() => db.collections());
+     * while (!job.isLoaded) {
+     *  await timeout(1000);
+     *  await job.load();
+     * }
+     * // job.result is a list of Collection instances
+     * ```
+     */
+    async createJob(callback) {
+        const trap = new Promise((resolveTrap) => {
+            this._trapRequest = (trapped) => resolveTrap(trapped);
+        });
+        const eventualResult = callback();
+        const trapped = await trap;
+        if (trapped.error)
+            return eventualResult;
+        const { jobId, onResolve, onReject } = trapped;
+        return new job_1.Job(this, jobId, (res) => {
+            onResolve(res);
+            return eventualResult;
+        }, (e) => {
+            onReject(e);
+            return eventualResult;
+        });
+    }
+    async request({ absolutePath = false, basePath, ...opts }, transform = (res) => res.body) {
         if (!absolutePath) {
             basePath = `/_db/${encodeURIComponent(this._name)}${basePath || ""}`;
         }
+        if (this._trapRequest) {
+            const trap = this._trapRequest;
+            this._trapRequest = undefined;
+            return new Promise(async (resolveRequest, rejectRequest) => {
+                const options = { ...opts };
+                options.headers = { ...options.headers, "x-arango-async": "store" };
+                let jobRes;
+                try {
+                    jobRes = await this._connection.request({ basePath, ...options });
+                }
+                catch (e) {
+                    trap({ error: true });
+                    rejectRequest(e);
+                    return;
+                }
+                const jobId = jobRes.headers["x-arango-async-id"];
+                trap({
+                    jobId,
+                    onResolve: (res) => {
+                        const result = transform ? transform(res) : res;
+                        resolveRequest(result);
+                        return result;
+                    },
+                    onReject: (err) => {
+                        rejectRequest(err);
+                        throw err;
+                    },
+                });
+            });
+        }
         return this._connection.request({ basePath, ...opts }, transform || undefined);
     }
     /**
@@ -218,6 +307,15 @@ class Database {
     close() {
         this._connection.close();
     }
+    /**
+     * Attempts to initiate a clean shutdown of the server.
+     */
+    shutdown() {
+        return this.request({
+            method: "DELETE",
+            path: "/_admin/shutdown",
+        }, () => undefined);
+    }
     async waitForPropagation({ basePath, ...request }, timeout) {
         await this._connection.waitForPropagation({
             ...request,
@@ -974,7 +1072,6 @@ class Database {
         return analyzers.map((data) => this.analyzer(data.name));
     }
     //#endregion
-    //#region users
     /**
      * Fetches all ArangoDB users visible to the authenticated user and returns
      * an array of user objects.
@@ -2107,6 +2204,241 @@ class Database {
             qs: { replace },
         }, () => undefined);
     }
+    //#endregion
+    //#region hot backups
+    /**
+     * (Enterprise Edition only.) Creates a hot backup of the entire ArangoDB
+     * deployment including all databases, collections, etc.
+     *
+     * Returns an object describing the backup result.
+     *
+     * @param options - Options for creating the backup.
+     *
+     * @example
+     * ```js
+     * const info = await db.createHotBackup();
+     * // a hot backup has been created
+     * ```
+     */
+    createHotBackup(options = {}) {
+        return this.request({
+            method: "POST",
+            path: "/_admin/backup/create",
+            body: options,
+        }, (res) => res.body.result);
+    }
+    /**
+     * (Enterprise Edition only.) Retrieves a list of all locally found hot
+     * backups.
+     *
+     * @param id - If specified, only the backup with the given ID will be
+     * returned.
+     *
+     * @example
+     * ```js
+     * const backups = await db.listHotBackups();
+     * for (const backup of backups) {
+     *   console.log(backup.id);
+     * }
+     * ```
+     */
+    listHotBackups(id) {
+        return this.request({
+            method: "POST",
+            path: "/_admin/backup/list",
+            body: id ? { id } : undefined,
+        }, (res) => res.body.result);
+    }
+    /**
+     * (Enteprise Edition only.) Restores a consistent local hot backup.
+     *
+     * Returns the directory path of the restored backup.
+     *
+     * @param id - The ID of the backup to restore.
+     *
+     * @example
+     * ```js
+     * await db.restoreHotBackup("2023-09-19T15.38.21Z_example");
+     * // the backup has been restored
+     * ```
+     */
+    restoreHotBackup(id) {
+        return this.request({
+            method: "POST",
+            path: "/_admin/backup/restore",
+            body: { id },
+        }, (res) => res.body.result.previous);
+    }
+    /**
+     * (Enterprise Edition only.) Deletes a local hot backup.
+     *
+     * @param id - The ID of the backup to delete.
+     *
+     * @example
+     * ```js
+     * await db.deleteHotBackup("2023-09-19T15.38.21Z_example");
+     * // the backup has been deleted
+     * ```
+     */
+    deleteHotBackup(id) {
+        return this.request({
+            method: "POST",
+            path: "/_admin/backup/delete",
+            body: { id },
+        }, () => undefined);
+    }
+    //#endregion
+    //#region logs
+    /**
+     * Retrieves the log messages from the server's global log.
+     *
+     * @param options - Options for retrieving the log entries.
+     *
+     * @example
+     * ```js
+     * const log = await db.getLogEntries();
+     * for (let i = 0; i < log.totalAmount; i++) {
+     *   console.log(`${
+     *     new Date(log.timestamp[i] * 1000).toISOString()
+     *   } - [${LogLevel[log.level[i]]}] ${log.text[i]} (#${log.lid[i]})`);
+     * }
+     * ```
+     */
+    getLogEntries(options) {
+        return this.request({
+            path: "/_admin/log",
+            qs: options,
+        }, (res) => res.body);
+    }
+    /**
+     * Retrieves the log messages from the server's global log.
+     *
+     * @param options - Options for retrieving the log entries.
+     *
+     * @example
+     * ```js
+     * const messages = await db.getLogMessages();
+     * for (const m of messages) {
+     *   console.log(`${m.date} - [${m.level}] ${m.message} (#${m.id})`);
+     * }
+     * ```
+     */
+    getLogMessages(options) {
+        return this.request({
+            path: "/_admin/log",
+            qs: options,
+        }, (res) => res.body.messages);
+    }
+    /**
+     * Retrieves the server's current log level for each topic.
+     *
+     * @example
+     * ```js
+     * const levels = await db.getLogLevel();
+     * console.log(levels.request); // log level for incoming requests
+     * ```
+     */
+    getLogLevel() {
+        return this.request({
+            path: "/_admin/log/level",
+        });
+    }
+    /**
+     * Sets the server's log level for each of the given topics to the given level.
+     *
+     * Any omitted topics will be left unchanged.
+     *
+     * @param levels - An object mapping topic names to log levels.
+     *
+     * @example
+     * ```js
+     * await db.setLogLevel({ request: "debug" });
+     * // Debug information will now be logged for each request
+     * ```
+     */
+    setLogLevel(levels) {
+        return this.request({
+            method: "PUT",
+            path: "/_admin/log/level",
+            body: levels,
+        });
+    }
+    //#endregion
+    //#region async jobs
+    /**
+     * Returns a {@link job.Job} instance for the given `jobId`.
+     *
+     * @param jobId - ID of the async job.
+     *
+     * @example
+     * ```js
+     * const db = new Database();
+     * const job = db.job("12345");
+     * ```
+     */
+    job(jobId) {
+        return new job_1.Job(this, jobId);
+    }
+    /**
+     * Returns a list of the IDs of all currently pending async jobs.
+     *
+     * @example
+     * ```js
+     * const db = new Database();
+     * const pendingJobs = await db.listPendingJobs();
+     * console.log(pendingJobs); // e.g. ["12345", "67890"]
+     * ```
+     */
+    listPendingJobs() {
+        return this.request({
+            path: "/_api/job/pending",
+        }, (res) => res.body);
+    }
+    /**
+     * Returns a list of the IDs of all currently available completed async jobs.
+     *
+     * @example
+     * ```js
+     * const db = new Database();
+     * const completedJobs = await db.listCompletedJobs();
+     * console.log(completedJobs); // e.g. ["12345", "67890"]
+     * ```
+     */
+    listCompletedJobs() {
+        return this.request({
+            path: "/_api/job/done",
+        }, (res) => res.body);
+    }
+    /**
+     * Deletes the results of all completed async jobs created before the given
+     * threshold.
+     *
+     * @param threshold - The expiration timestamp in milliseconds.
+     *
+     * @example
+     * ```js
+     * const db = new Database();
+     * const ONE_WEEK = 7 * 24 * 60 * 60 * 1000;
+     * await db.deleteExpiredJobResults(Date.now() - ONE_WEEK);
+     * // all job results older than a week have been deleted
+     * ```
+     */
+    deleteExpiredJobResults(threshold) {
+        return this.request({
+            method: "DELETE",
+            path: `/_api/job/expired`,
+            qs: { stamp: threshold / 1000 },
+        }, () => undefined);
+    }
+    /**
+     * Deletes the results of all completed async jobs.
+     */
+    deleteAllJobResults() {
+        return this.request({
+            method: "DELETE",
+            path: `/_api/job/all`,
+        }, () => undefined);
+    }
 }
 exports.Database = Database;
 //# sourceMappingURL=database.js.map