♻️ rework local and input sources (#376)

Author: ianardee

.github/workflows/_test-code-samples.yml

@@ -11,7 +11,6 @@ jobs:
     strategy:
       matrix:
         node-version:
-          - "18"
           - "20"
           - "22"
           - "24"

.github/workflows/_test-units.yml

@@ -18,6 +18,7 @@ jobs:
           - "18"
           - "20"
           - "22"
+          - "24"
     runs-on: ${{ matrix.os }}
 
     steps:

src/client.ts

@@ -255,10 +255,11 @@ export class Client {
      * @returns A valid prediction
      */
     try {
-      if (Object.prototype.hasOwnProperty.call(localResponse.asDict(), "job")) {
-        return new AsyncPredictResponse(productClass, localResponse.asDict());
+      const asDict = await localResponse.asDict();
+      if (Object.prototype.hasOwnProperty.call(asDict, "job")) {
+        return new AsyncPredictResponse(productClass, asDict);
       }
-      return new PredictResponse(productClass, localResponse.asDict());
+      return new PredictResponse(productClass, asDict);
     } catch {
       throw new MindeeError("No prediction found in local response.");
     }

src/clientV2.ts

@@ -1,15 +1,11 @@
-import {
-  Base64Input, BufferInput, BytesInput, InputSource,
-  PathInput, StreamInput, UrlInput,
-} from "./input";
+import { InputSource } from "./input";
 import { errorHandler } from "./errors/handler";
 import { LOG_LEVELS, logger } from "./logger";
 
 import { setTimeout } from "node:timers/promises";
 import { ErrorResponse, InferenceResponse, JobResponse } from "./parsing/v2";
 import { MindeeApiV2 } from "./http/mindeeApiV2";
 import { MindeeHttpErrorV2 } from "./errors/mindeeError";
-import { Readable } from "stream";
 
 /**
  * Parameters for the internal polling loop in {@link ClientV2.enqueueAndGetInference | enqueueAndGetInference()} .
@@ -160,6 +156,9 @@ export class ClientV2 {
     if (inputSource === undefined) {
       throw new Error("The 'enqueue' function requires an input document.");
     }
+    if (!inputSource.isInitialized()) {
+      await inputSource.init();
+    }
     return await this.mindeeApi.reqPostInferenceEnqueue(inputSource, params);
   }
 
@@ -232,19 +231,19 @@ export class ClientV2 {
    * Send a document to an endpoint and poll the server until the result is sent or
    * until the maximum number of tries is reached.
    *
-   * @param inputDoc document to parse.
+   * @param inputSource file or URL to parse.
    * @param params parameters relating to prediction options.
    *
    * @typeParam T an extension of an `Inference`. Can be omitted as it will be inferred from the `productClass`.
    * @category Synchronous
    * @returns a `Promise` containing parsing results.
    */
   async enqueueAndGetInference(
-    inputDoc: InputSource,
+    inputSource: InputSource,
     params: InferenceParameters
   ): Promise<InferenceResponse> {
     const validatedAsyncParams = this.#setAsyncParams(params.pollingOptions);
-    const enqueueResponse: JobResponse = await this.enqueueInference(inputDoc, params);
+    const enqueueResponse: JobResponse = await this.enqueueInference(inputSource, params);
     if (enqueueResponse.job.id === undefined || enqueueResponse.job.id.length === 0) {
       logger.error(`Failed enqueueing:\n${enqueueResponse.getRawHttp()}`);
       throw Error("Enqueueing of the document failed.");
@@ -283,72 +282,4 @@ Job status: ${pollResults.job.status}.`
       " seconds"
     );
   }
-
-  /**
-   * Load an input source from a local path.
-   * @param inputPath
-   */
-  sourceFromPath(inputPath: string): PathInput {
-    return new PathInput({
-      inputPath: inputPath,
-    });
-  }
-
-  /**
-   * Load an input source from a base64 encoded string.
-   * @param inputString input content, as a string.
-   * @param filename file name.
-   */
-  sourceFromBase64(inputString: string, filename: string): Base64Input {
-    return new Base64Input({
-      inputString: inputString,
-      filename: filename,
-    });
-  }
-
-  /**
-   * Load an input source from a `stream.Readable` object.
-   * @param inputStream input content, as a readable stream.
-   * @param filename file name.
-   */
-  sourceFromStream(inputStream: Readable, filename: string): StreamInput {
-    return new StreamInput({
-      inputStream: inputStream,
-      filename: filename,
-    });
-  }
-
-  /**
-   * Load an input source from bytes.
-   * @param inputBytes input content, as a Uint8Array or Buffer.
-   * @param filename file name.
-   */
-  sourceFromBytes(inputBytes: Uint8Array, filename: string): BytesInput {
-    return new BytesInput({
-      inputBytes: inputBytes,
-      filename: filename,
-    });
-  }
-
-  /**
-   * Load an input source from a Buffer.
-   * @param buffer input content, as a buffer.
-   * @param filename file name.
-   */
-  sourceFromBuffer(buffer: Buffer, filename: string): BufferInput {
-    return new BufferInput({
-      buffer: buffer,
-      filename: filename,
-    });
-  }
-
-  /**
-   * Load an input source from a URL.
-   * @param url input url. Must be HTTPS.
-   */
-  sourceFromUrl(url: string): UrlInput {
-    return new UrlInput({
-      url: url,
-    });
-  }
 }

src/index.ts

@@ -1,5 +1,5 @@
 export * as product from "./product";
-export { Client, PredictOptions } from "./client";
+export { Client, PredictOptions, WorkflowOptions } from "./client";
 export { ClientV2, InferenceParameters, PollingOptions } from "./clientV2";
 export {
   AsyncPredictResponse,
@@ -9,6 +9,10 @@ export {
   Document,
   Page,
 } from "./parsing/common";
+export {
+  InferenceResponse,
+  JobResponse,
+} from "./parsing/v2";
 export {
   InputSource,
   Base64Input,

src/input/localResponse.ts

@@ -12,6 +12,7 @@ import { CommonResponse } from "../parsing/v2";
 export class LocalResponse {
   private file: Buffer;
   private readonly inputHandle: Buffer | string;
+  protected initialized = false;
 
   /**
    * Creates an instance of LocalResponse.
@@ -39,13 +40,17 @@ export class LocalResponse {
     } else {
       throw new MindeeError("Incompatible type for input.");
     }
+    this.initialized = true;
   }
 
   /**
    * Returns the dictionary representation of the file.
    * @returns A JSON-like object.
    */
-  asDict(): StringDict {
+  async asDict(): Promise<StringDict> {
+    if (!this.initialized) {
+      await this.init();
+    }
     try {
       const content = this.file.toString("utf-8");
       return JSON.parse(content);
@@ -60,6 +65,11 @@ export class LocalResponse {
    * @returns The HMAC signature of the local response.
    */
   getHmacSignature(secretKey: string | Buffer | Uint8Array): string {
+    if (!this.initialized) {
+      throw new Error(
+        "The `init()` method must be called before calling `getHmacSignature()`."
+      );
+    }
     const algorithm = "sha256";
     try {
       const hmac = crypto.createHmac(algorithm, secretKey);
@@ -76,7 +86,12 @@ export class LocalResponse {
    * @param signature - The signature to be compared with.
    * @returns True if the HMAC signature is valid.
    */
-  isValidHmacSignature(secretKey: string | Buffer | Uint8Array, signature: string): boolean {
+  public isValidHmacSignature(secretKey: string | Buffer | Uint8Array, signature: string): boolean {
+    if (!this.initialized) {
+      throw new Error(
+        "The `init()` method must be called before calling `isValidHmacSignature()`."
+      );
+    }
     return signature === this.getHmacSignature(secretKey);
   }
 
@@ -90,11 +105,11 @@ export class LocalResponse {
    * @returns An instance of `responseClass` populated with the file content.
    * @throws MindeeError If the provided class cannot be instantiated.
    */
-  public deserializeResponse<ResponseT extends CommonResponse>(
+  public async deserializeResponse<ResponseT extends CommonResponse>(
     responseClass: new (serverResponse: StringDict) => ResponseT
-  ): ResponseT {
+  ): Promise<ResponseT> {
     try {
-      return new responseClass(this.asDict());
+      return new responseClass(await this.asDict());
     } catch {
       throw new MindeeError("Invalid response provided.");
     }

src/input/sources/base64Input.ts

@@ -23,5 +23,6 @@ export class Base64Input extends LocalInputSource {
     this.mimeType = await this.checkMimetype();
     // clear out the string
     this.inputString = "";
+    this.initialized = true;
   }
 }

src/input/sources/bufferInput.ts

@@ -17,5 +17,6 @@ export class BufferInput extends LocalInputSource {
 
   async init(): Promise<void> {
     this.mimeType = await this.checkMimetype();
+    this.initialized = true;
   }
 }

src/input/sources/bytesInput.ts

@@ -22,5 +22,6 @@ export class BytesInput extends LocalInputSource {
     this.fileObject = Buffer.from(this.inputBytes);
     this.mimeType = await this.checkMimetype();
     this.inputBytes = new Uint8Array(0);
+    this.initialized = true;
   }
 }

src/input/sources/inputSource.ts

@@ -14,9 +14,13 @@ export const INPUT_TYPE_BUFFER = "buffer";
 
 export abstract class InputSource {
   fileObject: Buffer | string = "";
+  protected initialized: boolean = false;
 
   async init() {
     throw new Error("not Implemented");
   }
-}
 
+  public isInitialized() {
+    return this.initialized;
+  }
+}