[DE-339] Implement async jobs management

Author: pluma

CHANGELOG.md

@@ -22,6 +22,8 @@ This driver uses semantic versioning:
 
 - Implemented logging API (DE-144, DE-145, DE-146, DE-147)
 
+- Implemented async jobs management (DE-339)
+
 ## [8.4.1] - 2023-09-15
 
 ### Fixed

src/database.ts

@@ -44,6 +44,7 @@ import {
   Graph,
   GraphInfo,
 } from "./graph";
+import { Job } from "./job";
 import { Blob } from "./lib/blob";
 import { DATABASE_NOT_FOUND } from "./lib/codes";
 import { toForm } from "./lib/multipart";
@@ -5906,4 +5907,96 @@ export class Database {
     });
   }
   //#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: string): Job {
+    return new 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(): Promise<string[]> {
+    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(): Promise<string[]> {
+    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: number): Promise<void> {
+    return this.request(
+      {
+        method: "DELETE",
+        path: `/_api/job/expired`,
+        qs: { stamp: threshold / 1000 },
+      },
+      () => undefined
+    );
+  }
+
+  /**
+   * Deletes the results of all completed async jobs.
+   */
+  deleteAllJobResults(): Promise<void> {
+    return this.request(
+      {
+        method: "DELETE",
+        path: `/_api/job/all`,
+      },
+      () => undefined
+    );
+  }
+  //#endregion
 }

src/job.ts

@@ -0,0 +1,118 @@
+import { Database } from "./database";
+
+/**
+ * Represents an async job in a {@link database.Database}.
+ */
+export class Job<T = any> {
+  protected _id: string;
+  protected _db: Database;
+  protected _loaded: boolean = false;
+  protected _result: T | undefined;
+
+  /**
+   * @internal
+   */
+  constructor(db: Database, id: string) {
+    this._db = db;
+    this._id = id;
+  }
+
+  /**
+   * Whether the job's results have been loaded. If set to `true`, the job's
+   * result can be accessed from {@link Job.result}.
+   */
+  get isLoaded(): boolean {
+    return this._loaded;
+  }
+
+  /**
+   * The job's result if it has been loaded or `undefined` otherwise.
+   */
+  get result(): T | undefined {
+    return this._result;
+  }
+
+  /**
+   * Loads the job's result from the database if it is not already loaded.
+   *
+   * @example
+   * ```js
+   * // poll for the job to complete
+   * while (!job.isLoaded) {
+   *   await timeout(1000);
+   *   const result = await job.load();
+   *   console.log(result);
+   * }
+   * // job result is now loaded and can also be accessed from job.result
+   * console.log(job.result);
+   * ```
+   */
+  async load(): Promise<T | undefined> {
+    if (!this.isLoaded) {
+      const res = await this._db.request(
+        {
+          method: "PUT",
+          path: `/_api/job/${this._id}`,
+        },
+        false
+      );
+      if (res.statusCode !== 204) {
+        this._loaded = true;
+        this._result = res.body;
+      }
+    }
+    return this._result;
+  }
+
+  /**
+   * Cancels the job if it is still running. Note that it may take some time to
+   * actually cancel the job.
+   */
+  cancel(): Promise<void> {
+    return this._db.request(
+      {
+        method: "PUT",
+        path: `/_api/job/${this._id}/cancel`,
+      },
+      () => undefined
+    );
+  }
+
+  /**
+   * Deletes the result if it has not already been retrieved or deleted.
+   */
+  deleteResult(): Promise<void> {
+    return this._db.request(
+      {
+        method: "DELETE",
+        path: `/_api/job/${this._id}`,
+      },
+      () => undefined
+    );
+  }
+
+  /**
+   * Fetches the job's completion state.
+   *
+   * Returns `true` if the job has completed, `false` otherwise.
+   *
+   * @example
+   * ```js
+   * // poll for the job to complete
+   * while (!(await job.getCompleted())) {
+   *   await timeout(1000);
+   * }
+   * // job result is now available and can be loaded
+   * await job.load();
+   * console.log(job.result);
+   * ```
+   */
+  getCompleted(): Promise<boolean> {
+    return this._db.request(
+      {
+        path: `/_api/job/${this._id}`,
+      },
+      (res) => res.statusCode !== 204
+    );
+  }
+}