Improve TaskClient, BatchClient and associated types (#1825)

* Remove unnecessary classes

* Save progress

* Progress

* Progress

* Fix formatting

* Fix test

* Fix test

* Fix rest of the tests, adjust readme

* Add documentation, adjust types, functions, misc

* Fix formatting

* Revert some changes, misc

* Adjust types

* Fix test

* Misc

* Adjust docs

* Adjust doc

* Revert settings types change

* Fix formatting

* Add task wait applier to tasks as well

* Revert bad test

* Remove focus from test, experiment with old interval

* Fix not clearing timers when task is successfully awaited

* Try and fix waitTask being slow

* Fix unhandled rejections

* Refactor waitTask

* Try fix slow waitTask

* Try fix slow waitTask

* Add ability to specify default wait options for tasks through exported classes, use lower interval in tests

* Shorten code

* Rename variables

* Remove hint about bad Meilisearch version

* Add test for failing waitTask

* Fix formatting, don't add timeout if interval is invalid

* Rename functions, adjust description

* Do not export TaskClient in index

* Revert deprecations

* Fix formatting

* Added missing batchUids prop, misc

* Make waitTask abort last getTask on timeout

* Improve timeout errors, fix tests

* Misc

* Fix error

* Fix formatting

* Remove unnecessary tests

* Fix waitTask, try Symbol for timeout ID

* Fix http requests not catching abort error on response.text()

* Fix Node.js 18 compat

* Add documentation to changed errors

* Update type definitions header

---------

Co-authored-by: Laurent Cazanove <[email protected]>

Author: flevi29

README.md

@@ -564,34 +564,16 @@ client.index('myIndex').getTasks(parameters: TasksQuery): Promise<TasksResults>
 client.index('myIndex').getTask(uid: number): Promise<Task>
 ```
 
-
 #### Wait for one task
 
-
-##### Using the client
-
-```ts
-client.waitForTask(uid: number, { timeOutMs?: number, intervalMs?: number }): Promise<Task>
-```
-
-##### Using the index
-
 ```ts
-client.index('myIndex').waitForTask(uid: number, { timeOutMs?: number, intervalMs?: number }): Promise<Task>
+client.tasks.waitForTask(uid: number, { timeout?: number, interval?: number }): Promise<Task>
 ```
 
 #### Wait for multiple tasks
 
-##### Using the client
-
-```ts
-client.waitForTasks(uids: number[], { timeOutMs?: number, intervalMs?: number }): Promise<Task[]>
-```
-
-##### Using the index
-
 ```ts
-client.index('myIndex').waitForTasks(uids: number[], { timeOutMs?: number, intervalMs?: number }): Promise<Task[]>
+client.tasks.waitForTasks(uids: number[], { timeout?: number, interval?: number }): Promise<Task[]>
 ```
 
 ### Batches <!-- omit in toc -->

playgrounds/javascript/src/meilisearch.ts

@@ -12,23 +12,22 @@ const index = client.index<{ id: number; title: string; genres: string[] }>(
 export async function addDocuments(): Promise<void> {
   await client.deleteIndexIfExists(indexUid);
 
-  const task1 = await client.createIndex(indexUid);
-  await client.waitForTask(task1.taskUid);
-
-  const task2 = await index.addDocuments([
-    { id: 1, title: "Carol", genres: ["Romance", "Drama"] },
-    { id: 2, title: "Wonder Woman", genres: ["Action", "Adventure"] },
-    { id: 3, title: "Life of Pi", genres: ["Adventure", "Drama"] },
-    {
-      id: 4,
-      title: "Mad Max: Fury Road",
-      genres: ["Adventure", "Science Fiction"],
-    },
-    { id: 5, title: "Moana", genres: ["Fantasy", "Action"] },
-    { id: 6, title: "Philadelphia", genres: ["Drama"] },
-  ]);
-
-  await client.index(indexUid).waitForTask(task2.taskUid);
+  await client.createIndex(indexUid).waitTask();
+
+  await index
+    .addDocuments([
+      { id: 1, title: "Carol", genres: ["Romance", "Drama"] },
+      { id: 2, title: "Wonder Woman", genres: ["Action", "Adventure"] },
+      { id: 3, title: "Life of Pi", genres: ["Adventure", "Drama"] },
+      {
+        id: 4,
+        title: "Mad Max: Fury Road",
+        genres: ["Adventure", "Science Fiction"],
+      },
+      { id: 5, title: "Moana", genres: ["Fantasy", "Action"] },
+      { id: 6, title: "Philadelphia", genres: ["Drama"] },
+    ])
+    .waitTask();
 }
 
 export async function getAllHits(element: HTMLDivElement): Promise<void> {

src/batch.ts

@@ -1,69 +1,38 @@
 import type {
-  Config,
-  BatchObject,
-  BatchesQuery,
+  Batch,
   BatchesResults,
-  BatchesResultsObject,
-} from "./types.js";
-import { HttpRequests } from "./http-requests.js";
-
-class Batch {
-  uid: BatchObject["uid"];
-  details: BatchObject["details"];
-  stats: BatchObject["stats"];
-  startedAt: BatchObject["startedAt"];
-  finishedAt: BatchObject["finishedAt"];
-  duration: BatchObject["duration"];
-  progress: BatchObject["progress"];
-
-  constructor(batch: BatchObject) {
-    this.uid = batch.uid;
-    this.details = batch.details;
-    this.stats = batch.stats;
-    this.startedAt = batch.startedAt;
-    this.finishedAt = batch.finishedAt;
-    this.duration = batch.duration;
-    this.progress = batch.progress;
-  }
-}
-
-class BatchClient {
-  httpRequest: HttpRequests;
-
-  constructor(config: Config) {
-    this.httpRequest = new HttpRequests(config);
+  TasksOrBatchesQuery,
+} from "./types/index.js";
+import type { HttpRequests } from "./http-requests.js";
+
+/**
+ * Class for handling batches.
+ *
+ * @see {@link https://www.meilisearch.com/docs/reference/api/batches}
+ */
+export class BatchClient {
+  readonly #httpRequest: HttpRequests;
+
+  constructor(httpRequests: HttpRequests) {
+    this.#httpRequest = httpRequests;
   }
 
-  /**
-   * Get one batch
-   *
-   * @param uid - Unique identifier of the batch
-   * @returns
-   */
+  /** {@link https://www.meilisearch.com/docs/reference/api/batches#get-one-batch} */
   async getBatch(uid: number): Promise<Batch> {
-    const batch = await this.httpRequest.get<BatchObject>({
+    const batch = await this.#httpRequest.get<Batch>({
       path: `batches/${uid}`,
     });
-    return new Batch(batch);
+    return batch;
   }
 
-  /**
-   * Get batches
-   *
-   * @param parameters - Parameters to browse the batches
-   * @returns Promise containing all batches
-   */
-  async getBatches(batchesQuery?: BatchesQuery): Promise<BatchesResults> {
-    const batches = await this.httpRequest.get<BatchesResultsObject>({
+  /** {@link https://www.meilisearch.com/docs/reference/api/batches#get-batches} */
+  async getBatches(
+    batchesQuery?: TasksOrBatchesQuery,
+  ): Promise<BatchesResults> {
+    const batches = await this.#httpRequest.get<BatchesResults>({
       path: "batches",
       params: batchesQuery,
     });
-
-    return {
-      ...batches,
-      results: batches.results.map((batch) => new Batch(batch)),
-    };
+    return batches;
   }
 }
-
-export { BatchClient, Batch };

src/enqueued-task.ts

@@ -1,4 +1,5 @@
 export * from "./meilisearch-api-error.js";
 export * from "./meilisearch-request-error.js";
 export * from "./meilisearch-error.js";
-export * from "./meilisearch-timeout-error.js";
+export * from "./meilisearch-request-timeout-error.js";
+export * from "./meilisearch-task-timeout-error.js";

src/errors/index.ts

@@ -1,4 +1,4 @@
-import type { MeiliSearchErrorResponse } from "../types.js";
+import type { MeiliSearchErrorResponse } from "../types/index.js";
 import { MeiliSearchError } from "./meilisearch-error.js";
 
 export class MeiliSearchApiError extends MeiliSearchError {

src/errors/meilisearch-api-error.ts

@@ -1,7 +1,3 @@
 export class MeiliSearchError extends Error {
   override name = "MeiliSearchError";
-
-  constructor(...params: ConstructorParameters<typeof Error>) {
-    super(...params);
-  }
 }

src/errors/meilisearch-error.ts

@@ -0,0 +1,13 @@
+import { MeiliSearchError } from "./meilisearch-error.js";
+
+/** Error thrown when a HTTP request times out. */
+export class MeiliSearchRequestTimeOutError extends MeiliSearchError {
+  override name = "MeiliSearchRequestTimeOutError";
+  override cause: { timeout: number; requestInit: RequestInit };
+
+  constructor(timeout: number, requestInit: RequestInit) {
+    super(`request timed out after ${timeout}ms`);
+
+    this.cause = { timeout, requestInit };
+  }
+}

src/errors/meilisearch-request-timeout-error.ts

@@ -0,0 +1,15 @@
+import { MeiliSearchError } from "./meilisearch-error.js";
+
+/** Error thrown when a waiting for a task times out. */
+export class MeiliSearchTaskTimeOutError extends MeiliSearchError {
+  override name = "MeiliSearchTaskTimeOutError";
+  override cause: { taskUid: number; timeout: number };
+
+  constructor(taskUid: number, timeout: number) {
+    super(
+      `timeout of ${timeout}ms has exceeded on task ${taskUid} when waiting for it to be resolved.`,
+    );
+
+    this.cause = { taskUid, timeout };
+  }
+}

src/errors/meilisearch-task-timeout-error.ts

@@ -5,12 +5,13 @@ import type {
   MainRequestOptions,
   URLSearchParamsRecord,
   MeiliSearchErrorResponse,
-} from "./types.js";
+} from "./types/index.js";
 import { PACKAGE_VERSION } from "./package-version.js";
 import {
   MeiliSearchError,
   MeiliSearchApiError,
   MeiliSearchRequestError,
+  MeiliSearchRequestTimeOutError,
 } from "./errors/index.js";
 import { addProtocolIfNotPresent, addTrailingSlash } from "./utils.js";
 
@@ -79,7 +80,7 @@ const TIMEOUT_ID = {};
  * @remarks
  * This could be a short few straight forward lines using {@link AbortSignal.any}
  * and {@link AbortSignal.timeout}, but these aren't yet widely supported enough,
- * nor polyfillable, at the time of writing.
+ * nor polyfill -able, at the time of writing.
  * @returns A new function which starts the timeout, which then returns another
  *   function that clears the timeout
  */
@@ -240,9 +241,7 @@ export class HttpRequests {
       throw new MeiliSearchRequestError(
         url.toString(),
         Object.is(error, TIMEOUT_ID)
-          ? new Error(`request timed out after ${this.#requestTimeout}ms`, {
-              cause: init,
-            })
+          ? new MeiliSearchRequestTimeOutError(this.#requestTimeout!, init)
           : error,
       );
     } finally {

src/errors/meilisearch-timeout-error.ts

@@ -1,8 +1,6 @@
-export * from "./types.js";
+export * from "./types/index.js";
 export * from "./errors/index.js";
 export * from "./indexes.js";
-export * from "./enqueued-task.js";
-export * from "./task.js";
 import { MeiliSearch } from "./meilisearch.js";
 
 /**