@luii/node-tesseract-ocr 1.0.15 → 1.0.18

package/binding.gyp

@@ -0,0 +1,60 @@
+{
+  "targets": [
+    {
+      "target_name": "node-tesseract-ocr",
+      "sources": [
+        "src/addon.cpp",
+        "src/ocr_result.cpp",
+        "src/ocr_worker.cpp",
+        "src/handle.cpp"
+      ],
+      "include_dirs": [
+        "<!(node -p \"require('node-addon-api').include\")"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').targets\"):node_addon_api",
+      ],
+      "cflags_cc": [
+        "-std=c++23",
+        "-Wall",
+        "-Wextra",
+        "-Wpedantic",
+        "-Wconversion",
+        "-Werror",
+        "-fexceptions"
+      ],
+      "defines": [
+        "NODE_ADDON_API_DISABLE_DEPRECATED",
+      ],
+      "conditions": [
+        [
+          "OS=='linux'",
+          {
+            "include_dirs": [
+              "<!(node -p \"require('node-addon-api').include\")",
+              "<!@(pkg-config --cflags-only-I tesseract lept | sed -e 's/-I//g')"
+            ],
+            "libraries": [
+              "<!@(pkg-config --libs tesseract lept)"
+            ]
+          }
+        ],
+        [
+          "OS=='mac'",
+          {
+            "include_dirs": [
+              "<!(node -p \"require('node-addon-api').include\")",
+              "/opt/homebrew/include",
+              "/usr/local/include"
+            ],
+            "libraries": [
+              "-L/opt/homebrew/lib",
+              "-L/usr/local/lib",
+              "-ltesseract"
+            ]
+          }
+        ],
+      ]
+    }
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,351 @@
+/*
+* node-tesseract-ocr
+* Copyright (C) 2025  Philipp Czarnetzki
+* 
+* This program is free software: you can redistribute it and/or modify
+* it under the terms of the GNU Affero General Public License as published by
+* the Free Software Foundation, either version 3 of the License, or
+* (at your option) any later version.
+* 
+* This program is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU Affero General Public License for more details.
+* 
+* You should have received a copy of the GNU Affero General Public License
+* along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+declare module 'node-tesseract-ocr' {
+
+  /**
+   * All available languages for tesseract
+   * @readonly
+   * @enum {string}
+   */
+  export enum AvailableLanguages {
+    afr = 'afr',
+    amh = 'amh',
+    ara = 'ara',
+    asm = 'asm',
+    aze = 'aze',
+    aze_cyrl = 'aze_cyrl',
+    bel = 'bel',
+    ben = 'ben',
+    bod = 'bod',
+    bos = 'bos',
+    bre = 'bre',
+    bul = 'bul',
+    cat = 'cat',
+    ceb = 'ceb',
+    ces = 'ces',
+    chi_sim = 'chi_sim',
+    chi_tra = 'chi_tra',
+    chr = 'chr',
+    cos = 'cos',
+    cym = 'cym',
+    dan = 'dan',
+    deu = 'deu',
+    deu_latf = 'deu_latf',
+    div = 'div',
+    dzo = 'dzo',
+    ell = 'ell',
+    eng = 'eng',
+    enm = 'enm',
+    epo = 'epo',
+    equ = 'equ',
+    est = 'est',
+    eus = 'eus',
+    fao = 'fao',
+    fas = 'fas',
+    fil = 'fil',
+    fin = 'fin',
+    fra = 'fra',
+    frm = 'frm',
+    fry = 'fry',
+    gla = 'gla',
+    gle = 'gle',
+    glg = 'glg',
+    grc = 'grc',
+    guj = 'guj',
+    hat = 'hat',
+    heb = 'heb',
+    hin = 'hin',
+    hrv = 'hrv',
+    hun = 'hun',
+    hye = 'hye',
+    iku = 'iku',
+    ind = 'ind',
+    isl = 'isl',
+    ita = 'ita',
+    ita_old = 'ita_old',
+    jav = 'jav',
+    jpn = 'jpn',
+    kan = 'kan',
+    kat = 'kat',
+    kat_old = 'kat_old',
+    kaz = 'kaz',
+    khm = 'khm',
+    kir = 'kir',
+    kmr = 'kmr',
+    kor = 'kor',
+    kor_vert = 'kor_vert',
+    kur = 'kur',
+    lao = 'lao',
+    lat = 'lat',
+    lav = 'lav',
+    lit = 'lit',
+    ltz = 'ltz',
+    mal = 'mal',
+    mar = 'mar',
+    mkd = 'mkd',
+    mlt = 'mlt',
+    mon = 'mon',
+    mri = 'mri',
+    msa = 'msa',
+    mya = 'mya',
+    nep = 'nep',
+    nld = 'nld',
+    nor = 'nor',
+    oci = 'oci',
+    ori = 'ori',
+    osd = 'osd',
+    pan = 'pan',
+    pol = 'pol',
+    por = 'por',
+    pus = 'pus',
+    que = 'que',
+    ron = 'ron',
+    rus = 'rus',
+    san = 'san',
+    sin = 'sin',
+    slk = 'slk',
+    slv = 'slv',
+    snd = 'snd',
+    spa = 'spa',
+    spa_old = 'spa_old',
+    sqi = 'sqi',
+    srp = 'srp',
+    srp_latn = 'srp_latn',
+    sun = 'sun',
+    swa = 'swa',
+    swe = 'swe',
+    syr = 'syr',
+    tam = 'tam',
+    tat = 'tat',
+    tel = 'tel',
+    tgk = 'tgk',
+    tha = 'tha',
+    tir = 'tir',
+    ton = 'ton',
+    tur = 'tur',
+    uig = 'uig',
+    ukr = 'ukr',
+    urd = 'urd',
+    uzb = 'uzb',
+    uzb_cyrl = 'uzb_cyrl',
+    vie = 'vie',
+    yid = 'yid',
+    yor = 'yor'
+  }
+
+  /**
+   * When Tesseract/Cube is initialized we can choose to instantiate/load/run
+   * only the Tesseract part, only the Cube part or both along with the combiner.
+   * The preference of which engine to use is stored in tessedit_ocr_engine_mode.
+   * @readonly
+   * @enum {number}
+   */
+  export enum OcrEngineMode {
+    // Run Tesseract only - fastest; deprecated
+    OEM_TESSERACT_ONLY = 0,
+    // Run just the LSTM line recognizer.
+    OEM_LSTM_ONLY = 1,
+    // Run the LSTM recognizer, but allow fallback
+    // to Tesseract when things get difficult.
+    // deprecated
+    OEM_TESSERACT_LSTM_COMBINED = 2,
+    // Specify this mode when calling init_*(),
+    // to indicate that any of the above modes
+    // should be automatically inferred from the
+    // variables in the language-specific config,
+    // command-line configs, or if not specified
+    // in any of the above should be set to the
+    // default OEM_TESSERACT_ONLY.
+    OEM_DEFAULT = 3,
+  }
+
+
+  /**
+   * Possible modes for page layout analysis.
+   * @readonly 
+   * @enum {number}
+   */
+  export enum PageSegmentationMode {
+    // Orientation and script detection only.
+    PSM_OSD_ONLY = 0,
+    // Automatic page segmentation with orientation and script detection. (OSD)
+    PSM_AUTO_OSD = 1,
+    // Automatic page segmentation, but no OSD, or OCR.
+    PSM_AUTO_ONLY = 2,
+    // Fully automatic page segmentation, but no OSD.
+    PSM_AUTO = 3,
+    // Assume a single column of text of variable sizes.
+    PSM_SINGLE_COLUMN = 4,
+    // Assume a single uniform block of vertically aligned text.
+    PSM_SINGLE_BLOCK_VERT_TEXT = 5,
+    // Assume a single uniform block of text. (Default.)
+    PSM_SINGLE_BLOCK = 6,
+    // Treat the image as a single text line.
+    PSM_SINGLE_LINE = 7,
+    // Treat the image as a single word.
+    PSM_SINGLE_WORD = 8,
+    // Treat the image as a single word in a circle.
+    PSM_CIRCLE_WORD = 9,
+    // Treat the image as a single character.
+    PSM_SINGLE_CHAR = 10,
+    // Find as much text as possible in no particular order.
+    PSM_SPARSE_TEXT = 11,
+    // Sparse text with orientation and script det.
+    PSM_SPARSE_TEXT_OSD = 12,
+    // Treat the image as a single text line, bypassing hacks that are Tesseract-specific.
+    PSM_RAW_LINE = 13,
+  }
+
+  /**
+   * Tesseract constructor options
+   */
+  export interface TesseractOptions {
+    /**
+     * Its generally safer to use as few languages as possible.
+     * The more languages Tesseract needs to load the longer it takes to recognize a image.
+     * @public
+     */
+    lang: Array<keyof typeof AvailableLanguages>;
+
+    /**
+     * Skip Ocr for when you only want to (for example) analyze the layout
+     * @property {boolean} [skipOcr]
+     */
+    skipOcr?: boolean;
+
+    /**
+     * OCR Engine Modes
+     * The engine mode cannot be changed after creating the instance
+     * If another mode is needed, its advised to create a new instance.
+     * @throws {Error} Will throw an error when oem mode is below 0 or over 3
+     */
+    oemMode?: OcrEngineMode;
+
+    /**
+     * Page Segmentation Modes
+     * The page segmentation mode cannot be changed after creating the instance
+     * If another mode is needed, its advised to create a new instance.
+     * @throws {Error} Will throw a error when psm mode is below 0 or over 13
+     */
+    psm?: PageSegmentationMode;
+  }
+
+  export interface ProgressChangedInfo {
+
+    /**
+     * Chars in this buffer
+     */
+    progress: number;
+
+    /**
+     * Percent complete increasing (0-100) 
+     */
+    percent: number;
+
+    /**
+     * States if the worker is still alive
+     */
+    ocrAlive: number;
+
+    /**
+     * top coordinate of the bbox of the current element that tesseract is processing
+     */
+    top: number;
+
+    /**
+     * right coordinate of the bbox of the current element that tesseract is processing
+     */
+    right: number;
+
+    /**
+     * bottom coordinate of the bbox of the current element that tesseract is processing
+     */
+    bottom: number;
+
+    /**
+     * left coordinate of the bbox of the current element that tesseract is processing
+     */
+    left: number;
+  }
+
+  /**
+   * Progress callback thats called during `recognize`
+   */
+  export type RecognizeProgressChangedCallback = (info: ProgressChangedInfo) => void;
+
+  export interface RecognizeOptions {
+
+    /**
+     * @property {RecognizeProgressChangedCallback} [progressChanged]
+     */
+    progressChanged?: RecognizeProgressChangedCallback;
+  }
+
+  export interface RecognizeResult {
+
+    /**
+     * Returns the recognized text as utf8
+     * @returns {string}
+     */
+    getText: () => string;
+
+    /**
+     * Returns the recognized text as tsv format (Tab seperated values)
+     * @returns {string}
+     */
+    getTSV: () => string;
+
+    /**
+     * Returns the recognized results in an hOCR format.
+     * hOCR is a derivative of the XML format and can be parsed as such.
+     * The hOCR format contains layout information, so that
+     * it could be overlayed over the source material for example.
+     * @see https://en.wikipedia.org/wiki/HOCR
+     * @returns {string}
+     */
+    getHOCR: () => string;
+
+    /**
+     * Returns the recognized results in an ALTO format.
+     * ALTO is a derivative of the XML format and can be parsed as such.
+     * The ALTO format contains layout information, so that 
+     * it could be overlayed over the source material for example.
+     * @see https://en.wikipedia.org/wiki/Analyzed_Layout_and_Text_Object
+     * @returns {string}
+     */
+    getALTO: () => string;
+  }
+
+  export class Tesseract {
+    constructor(options: TesseractOptions);
+
+    /**
+     * @throws  {Error} Will throw an error if no available underlying api is available
+     * @throws  {Error} Will throw an error if skipOcr is on and this function is called
+     * @throws  {Error} Will throw an error if the parameter at index 0 is not a buffer
+     * @param   {Buffer<ArrayBuffer>} imageBuffer The image that should be recognized
+     * @param   {RecognizeOptions}    [options]   Optional options, 
+     * @returns {Promise<RecognizeResult>} Returns a result object containing 
+     *                                     various functions to retrieve the results
+     */
+    recognize: (imageBuffer: Buffer<ArrayBuffer>, options?: RecognizeOptions) => Promise<RecognizeResult>;
+  }
+
+  export default Tesseract;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luii/node-tesseract-ocr",
-  "version": "1.0.15",
+  "version": "1.0.18",
   "private": false,
   "gypfile": true,
   "main": "dist/cjs/index.cjs",
@@ -41,7 +41,8 @@
     "build": "npm run build:release",
     "build:addon:debug": "node-gyp rebuild --debug",
     "build:addon:release": "node-gyp rebuild --release",
-    "build:ts": "npm run build:cjs && npm run build:esm",
+    "build:types": "mkdir -p dist && cp lib/index.d.ts dist/index.d.ts",
+    "build:ts": "npm run build:cjs && npm run build:esm && npm run build:types",
     "build:cjs": "tsc -p tsconfig.cjs.json && mv dist/cjs/index.js dist/cjs/index.cjs",
     "build:esm": "tsc -p tsconfig.esm.json && mv dist/esm/index.js dist/esm/index.mjs",
     "build:debug": "rm -rf dist && mkdir dist && npm run build:addon:debug && npm run build:cjs && npm run build:esm",
@@ -52,9 +53,12 @@
   "files": [
     "dist/**",
     "prebuilds/**",
+    "src/**",
     "build/Release/*.node",
     "package.json",
-    "README.md"
+    "binding.gyp",
+    "README.md",
+    "LICENSE.md"
   ],
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -70,7 +74,7 @@
     ".": {
       "import": "./dist/esm/index.mjs",
       "require": "./dist/cjs/index.cjs",
-      "types": "./lib/index.d.ts"
+      "types": "./dist/index.d.ts"
     }
   }
 }

package/src/addon.cpp

@@ -0,0 +1,26 @@
+/*
+ * node-tesseract-ocr
+ * Copyright (C) 2025  Philipp Czarnetzki
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "handle.h"
+#include <napi.h>
+
+Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
+  return Handle::GetClass(env, exports);
+}
+
+NODE_API_MODULE(hello, InitAll)

package/src/handle.cpp

@@ -0,0 +1,172 @@
+/*
+ * node-tesseract-ocr
+ * Copyright (C) 2025  Philipp Czarnetzki
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "handle.h"
+#include "napi.h"
+#include "ocr_worker.h"
+#include <tesseract/pageiterator.h>
+#include <tesseract/publictypes.h>
+
+Napi::Object Handle::GetClass(Napi::Env env, Napi::Object exports) {
+  Napi::Function funcs = DefineClass(
+      env, "Tesseract", {InstanceMethod("recognize", &Handle::Recognize)});
+
+  Napi::FunctionReference *constructor = new Napi::FunctionReference();
+
+  *constructor = Napi::Persistent(funcs);
+  exports.Set("Tesseract", funcs);
+  env.SetInstanceData<Napi::FunctionReference>(constructor);
+
+  return exports;
+};
+
+Handle::Handle(const Napi::CallbackInfo &info)
+    : Napi::ObjectWrap<Handle>(info) {
+
+  Napi::Env env = info.Env();
+
+  if (info.Length() == 1 && info[0].IsObject()) {
+    auto ctorOptions = info[0].As<Napi::Object>();
+
+    const Napi::Value skipOcrOption = ctorOptions.Get("skipOcr");
+    if (!skipOcrOption.IsUndefined() && skipOcrOption.IsBoolean()) {
+      skipOcr_ = skipOcrOption.As<Napi::Boolean>().Value();
+    }
+
+    const Napi::Value dataPathOption = ctorOptions.Get("dataPath");
+    if (!dataPathOption.IsUndefined() && dataPathOption.IsString()) {
+      dataPath_ = dataPathOption.As<Napi::String>().Utf8Value();
+    }
+
+    const Napi::Value langOption = ctorOptions.Get("lang");
+    if (!langOption.IsUndefined() && langOption.IsString()) {
+      lang_ = langOption.As<Napi::String>().Utf8Value();
+    }
+
+    const Napi::Value engineModeOption = ctorOptions.Get("engineMode");
+    if (!engineModeOption.IsUndefined() && engineModeOption.IsNumber()) {
+      oemMode_ = static_cast<tesseract::OcrEngineMode>(
+          engineModeOption.As<Napi::Number>().Int32Value());
+    }
+
+    const Napi::Value psmOption = ctorOptions.Get("psm");
+    if (!psmOption.IsUndefined() && psmOption.IsNumber()) {
+      psm_ = static_cast<tesseract::PageSegMode>(
+          psmOption.As<Napi::Number>().Int32Value());
+    }
+
+    if (oemMode_ < 0 || oemMode_ >= tesseract::OEM_COUNT) {
+      Napi::TypeError::New(env, "Unsupported OCR Engine Mode")
+          .ThrowAsJavaScriptException();
+      return;
+    }
+
+    if (psm_ < 0 || psm_ >= tesseract::PSM_COUNT) {
+      Napi::TypeError::New(env, "Unsupported Page Segmentation Mode")
+          .ThrowAsJavaScriptException();
+      return;
+    }
+  }
+}
+
+Handle::~Handle() {}
+
+std::unique_ptr<tesseract::TessBaseAPI> Handle::CreateApi() {
+  auto api = std::make_unique<tesseract::TessBaseAPI>();
+  if (skipOcr_) {
+    api->InitForAnalysePage();
+  } else {
+    if (api->Init(dataPath_.c_str(), lang_.c_str(), oemMode_) == -1) {
+      api->End();
+      return nullptr;
+    }
+  }
+
+  api->SetPageSegMode(static_cast<tesseract::PageSegMode>(psm_));
+  return api;
+}
+
+Napi::Value Handle::Recognize(const Napi::CallbackInfo &info) {
+  const Napi::Env env = info.Env();
+  const Napi::Promise::Deferred deffered = Napi::Promise::Deferred::New(env);
+
+  if (skipOcr_) {
+    deffered.Reject(Napi::Error::New(env, "OCR not available when handle was "
+                                          "created with `skipOcr` turned on")
+                        .Value());
+    return deffered.Promise();
+  }
+
+  if (info.Length() <= 0 || !info[0].IsBuffer()) {
+    deffered.Reject(
+        Napi::TypeError::New(env, "Expected argument at index 0 to be a Buffer")
+            .Value());
+    return deffered.Promise();
+  }
+
+  Napi::Function progressCallback = Napi::Function();
+  if (info.Length() == 2 && info[1].IsObject()) {
+    const Napi::Object recognizeOptions = info[1].As<Napi::Object>();
+    const Napi::Value progressChangedOption =
+        recognizeOptions.Get("progressChanged");
+    if (!progressChangedOption.IsUndefined() &&
+        progressChangedOption.IsFunction()) {
+      progressCallback = progressChangedOption.As<Napi::Function>();
+    }
+  }
+
+  auto imageBuffer = info[0].As<Napi::Buffer<uint8_t>>();
+  auto *pWorker = new OCRWorker(this, info.This().As<Napi::Object>(),
+                                imageBuffer, deffered, progressCallback);
+
+  pWorker->Queue();
+
+  return deffered.Promise();
+}
+
+// Napi::Value Handle::AnalyzeLayout(const Napi::CallbackInfo &info) {
+//   const Napi::Env env = info.Env();
+//   ArgParser args(info);
+//
+//   const Napi::Promise::Deferred deffered = Napi::Promise::Deferred::New(env);
+//
+//   if (!skipOcr_) {
+//     deffered.Reject(
+//         Napi::Error::New(
+//             env, "Page analysis not available unless `skipOcr` is turned on")
+//             .Value());
+//
+//     return deffered.Promise();
+//   }
+//
+//   if (info.Length() < 1 || !info[0].IsBoolean()) {
+//     deffered.Reject(Napi::TypeError::New(
+//                         info.Env(), "Expected first argument to be a
+//                         boolean") .Value());
+//     return deffered.Promise();
+//   }
+//
+//   bool merge_similar_words = info[0].As<Napi::Boolean>().Value();
+//
+//   api_->SetImage();
+//
+//   tesseract::PageIterator *iterator =
+//   api_->AnalyseLayout(merge_similar_words); return;
+// }
+
+std::mutex &Handle::Mutex() { return mutex_; }

package/src/handle.h

@@ -0,0 +1,59 @@
+/*
+ * node-tesseract-ocr
+ * Copyright (C) 2025  Philipp Czarnetzki
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef HANDLE_H
+#define HANDLE_H
+
+#include "napi.h"
+#include <cstdint>
+#include <cstdlib>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <tesseract/baseapi.h>
+#include <tesseract/ocrclass.h>
+#include <tesseract/publictypes.h>
+
+using Napi::CallbackInfo;
+
+class Handle : public Napi::ObjectWrap<Handle> {
+public:
+  static Napi::Object GetClass(Napi::Env env, Napi::Object exports);
+  Handle(const Napi::CallbackInfo &info);
+  ~Handle();
+
+  std::unique_ptr<tesseract::TessBaseAPI> CreateApi();
+  std::mutex &Mutex();
+  tesseract::ETEXT_DESC *Monitor();
+
+private:
+  bool skipOcr_ = false;
+
+  std::string dataPath_ = std::getenv("NODE_TESSERACT_DATAPATH");
+  std::string lang_ = "eng";
+  tesseract::OcrEngineMode oemMode_ = tesseract::OEM_DEFAULT;
+  tesseract::PageSegMode psm_ = tesseract::PSM_SINGLE_BLOCK;
+
+  std::unique_ptr<tesseract::TessBaseAPI> api_;
+  std::mutex mutex_;
+
+  Napi::Value Recognize(const CallbackInfo &info);
+  Napi::Value AnalyzeLayout(const CallbackInfo &info);
+};
+
+#endif // HANDLE_H

package/src/ocr_result.cpp

@@ -0,0 +1,101 @@
+/*
+ * node-tesseract-ocr
+ * Copyright (C) 2025  Philipp Czarnetzki
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "ocr_result.h"
+#include "napi.h"
+#include <mutex>
+#include <tesseract/baseapi.h>
+#include <tesseract/ocrclass.h>
+
+Napi::Function OCRResult::GetClass(Napi::Env env) {
+  return DefineClass(env, "OCRResult",
+                     {
+                         InstanceMethod("getText", &OCRResult::GetText),
+                         InstanceMethod("getHOCR", &OCRResult::GetHOCR),
+                         InstanceMethod("getTSV", &OCRResult::GetTSV),
+                         InstanceMethod("getALTO", &OCRResult::GetALTO),
+                     });
+}
+
+OCRResult::OCRResult(const Napi::CallbackInfo &info)
+    : Napi::ObjectWrap<OCRResult>(info), handle_(nullptr) {
+  // Expect constructor args: text, hocr, tsv (all strings)
+  if (info.Length() >= 1 && info[0].IsString()) {
+    text_ = info[0].As<Napi::String>().Utf8Value();
+  }
+  if (info.Length() >= 2 && info[1].IsString()) {
+    hocr_ = info[1].As<Napi::String>().Utf8Value();
+  }
+  if (info.Length() >= 3 && info[2].IsString()) {
+    tsv_ = info[2].As<Napi::String>().Utf8Value();
+  }
+  if (info.Length() >= 4 && info[3].IsString()) {
+    alto_ = info[3].As<Napi::String>().Utf8Value();
+  }
+}
+
+Napi::Object OCRResult::NewInstance(Napi::Env env, const std::string &text,
+                                    const std::string &hocr,
+                                    const std::string &tsv,
+                                    const std::string &alto) {
+  Napi::EscapableHandleScope scope(env);
+
+  Napi::Function ctor = OCRResult::GetClass(env);
+  Napi::Object obj =
+      ctor.New({Napi::String::New(env, text), Napi::String::New(env, hocr),
+                Napi::String::New(env, tsv), Napi::String::New(env, alto)});
+
+  return scope.Escape(obj).As<Napi::Object>();
+}
+
+void OCRResult::Cancel(const Napi::CallbackInfo &info) {
+  // Napi::Env env = info.Env();
+
+  {
+    std::lock_guard<std::mutex> lock(handle_->Mutex());
+    tesseract::ETEXT_DESC *monitor = handle_->Monitor();
+
+    monitor->cancel = [](void *should_cancel, int wordcount) -> bool {
+      return true;
+    };
+    monitor->cancel_this = (void *)true;
+    monitor->cancel(monitor->cancel_this, monitor->count);
+  }
+
+  return;
+}
+
+Napi::Value OCRResult::GetText(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  return Napi::String::New(env, text_);
+}
+
+Napi::Value OCRResult::GetHOCR(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  return Napi::String::New(env, hocr_);
+}
+
+Napi::Value OCRResult::GetTSV(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  return Napi::String::New(env, tsv_);
+}
+
+Napi::Value OCRResult::GetALTO(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+  return Napi::String::New(env, alto_);
+}

package/src/ocr_result.h

@@ -0,0 +1,49 @@
+/*
+ * node-tesseract-ocr
+ * Copyright (C) 2025  Philipp Czarnetzki
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef OCRRESULT_H
+#define OCRRESULT_H
+
+#include "handle.h"
+#include <napi.h>
+
+class OCRResult : public Napi::ObjectWrap<OCRResult> {
+
+public:
+  OCRResult(const Napi::CallbackInfo &info);
+  static Napi::Function GetClass(Napi::Env env);
+  static Napi::Object NewInstance(Napi::Env env, const std::string &text,
+                                  const std::string &hocr,
+                                  const std::string &tsv,
+                                  const std::string &alto);
+
+private:
+  void Cancel(const CallbackInfo &info);
+  Napi::Value GetText(const CallbackInfo &info);
+  Napi::Value GetHOCR(const CallbackInfo &info);
+  Napi::Value GetTSV(const CallbackInfo &info);
+  Napi::Value GetALTO(const CallbackInfo &info);
+
+  Handle *handle_;
+  std::string text_;
+  std::string hocr_;
+  std::string tsv_;
+  std::string alto_;
+};
+
+#endif // OCRRESULT_H

package/src/ocr_worker.cpp

@@ -0,0 +1,193 @@
+/*
+ * node-tesseract-ocr
+ * Copyright (C) 2025  Philipp Czarnetzki
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "ocr_worker.h"
+#include "napi.h"
+#include "ocr_result.h"
+#include <cstddef>
+#include <cstdio>
+#include <tesseract/baseapi.h>
+#include <tesseract/ocrclass.h>
+
+OCRWorker::OCRWorker(Handle *handle, Napi::Object handleObject,
+                     Napi::Buffer<uint8_t> buffer,
+                     Napi::Promise::Deferred deffered,
+                     Napi::Function &progressCallback)
+    : Napi::AsyncProgressWorker<ProgressPayload>{handle->Env(), "OCRWorker"},
+      handle_(handle), data_(buffer.Data()), length_(buffer.Length()),
+      deffered_{deffered} {
+
+  this->progressCallback_.Reset(progressCallback, 1);
+
+  // Hold a persistent reference to the JS Buffer.
+  // So its memory isn't freed while the async worker is running.
+  this->bufferRef_.Reset(buffer, 1);
+  // Hold a persistent reference to the JS Handle object.
+  // So it isn't GC'd while this worker is active.
+  this->handleRef_.Reset(handleObject, 1);
+
+  // allocate and zero-init the monitor to avoid uninitialized fields
+  monitor_ = new tesseract::ETEXT_DESC();
+
+  monitor_->progress_callback2 = [](tesseract::ETEXT_DESC *monitor, int left,
+                                    int right, int top, int bottom) -> bool {
+    ProgressPayload payload{monitor->more_to_come,
+                            monitor->progress,
+                            monitor->ocr_alive,
+                            top,
+                            right,
+                            bottom,
+                            left};
+    auto *executionProgress =
+        static_cast<OCRWorker::ExecutionProgress *>(monitor->cancel_this);
+    if (executionProgress == nullptr) {
+      return false;
+    }
+    executionProgress->Send(&payload, 1);
+    return false;
+  };
+  monitor_->ocr_alive = 1;
+};
+
+OCRWorker::~OCRWorker() {
+  // release the persistent buffer reference
+  if (!this->bufferRef_.IsEmpty()) {
+    this->bufferRef_.Reset();
+  }
+
+  // free monitor
+  if (monitor_) {
+    delete monitor_;
+    monitor_ = nullptr;
+  }
+  if (!this->handleRef_.IsEmpty()) {
+    this->handleRef_.Reset();
+  }
+}
+
+void OCRWorker::Execute(const ExecutionProgress &executionProgress) {
+
+  Pix *pPix = pixReadMem(data_, length_);
+
+  if (!pPix) {
+    SetError("Could not read image from buffer");
+    return;
+  }
+
+  // determine image depth and normalize to 8-bit grayscale (if needed)
+  int depth = pixGetDepth(pPix);
+  if (depth != 8) {
+    Pix *pGray = pixConvertTo8(pPix, 0); /* 0 = no colormap */
+    if (pGray) {
+      pixDestroy(&pPix);
+      pPix = pGray;
+    }
+  }
+
+  std::unique_ptr<tesseract::TessBaseAPI> localApi;
+  {
+    std::lock_guard<std::mutex> lock(handle_->Mutex());
+
+    // Create a thread-local TessBaseAPI to avoid sharing across threads;
+    localApi = handle_->CreateApi();
+
+    if (!localApi) {
+      pixDestroy(&pPix);
+      SetError("Could not initialize thread-local Tesseract API");
+      return;
+    }
+
+    localApi->SetImage(pPix);
+    monitor_->cancel_this = (void *)&executionProgress;
+
+    if (localApi->Recognize(monitor_) != 0) {
+      pixDestroy(&pPix);
+      monitor_->cancel_this = nullptr;
+      SetError("Recognize failed");
+      return;
+    }
+  }
+
+  // retrieve results from the local API
+  {
+    char *t = nullptr;
+    t = localApi->GetUTF8Text();
+    if (t) {
+      resultText_.assign(t);
+      delete[] t;
+    }
+
+    t = localApi->GetHOCRText(0);
+    if (t) {
+      resultHOCR_.assign(t);
+      delete[] t;
+    }
+
+    t = localApi->GetTSVText(0);
+    if (t) {
+      resultTSV_.assign(t);
+      delete[] t;
+    }
+
+    t = localApi->GetAltoText(0);
+    if (t) {
+      resultALTO_.assign(t);
+      delete[] t;
+    }
+  }
+
+  monitor_->cancel_this = nullptr;
+  pixDestroy(&pPix);
+}
+
+void OCRWorker::OnOK() {
+  Napi::Env env = Env();
+  Napi::HandleScope scope(env);
+
+  Napi::Object resultObj = OCRResult::NewInstance(env, resultText_, resultHOCR_,
+                                                  resultTSV_, resultALTO_);
+  // Attach a reference to the Handle JS object on the result.
+  // So the Handle stays alive as long as the OCRResult is reachable from JS.
+  if (!handleRef_.IsEmpty()) {
+    resultObj.Set("_handle", handleRef_.Value());
+  }
+
+  this->deffered_.Resolve(resultObj);
+}
+
+void OCRWorker::OnError(const Napi::Error &error) {
+  Napi::HandleScope scope(Env());
+  this->deffered_.Reject(error.Value());
+}
+
+void OCRWorker::OnProgress(const ProgressPayload *payload, size_t count) {
+  Napi::HandleScope scope(Env());
+  Napi::Object progress = Napi::Object::New(Env());
+
+  progress.Set("percent", payload->percent);
+  progress.Set("progress", payload->progress);
+  progress.Set("ocr_alive", payload->ocr_alive);
+  progress.Set("top", payload->top);
+  progress.Set("right", payload->right);
+  progress.Set("bottom", payload->bottom);
+  progress.Set("left", payload->left);
+
+  if (!this->progressCallback_.IsEmpty()) {
+    progressCallback_.Call(Env().Undefined(), {progress});
+  }
+}

package/src/ocr_worker.h

@@ -0,0 +1,69 @@
+/*
+ * node-tesseract-ocr
+ * Copyright (C) 2025  Philipp Czarnetzki
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef OCRWORKER_H
+#define OCRWORKER_H
+
+#include "handle.h"
+#include "leptonica/allheaders.h"
+#include "napi.h"
+#include <cstddef>
+#include <memory>
+#include <tesseract/baseapi.h>
+#include <tesseract/ocrclass.h>
+
+struct ProgressPayload {
+  int percent;
+  int progress;
+  int ocr_alive;
+  int top;
+  int right;
+  int bottom;
+  int left;
+};
+
+class OCRWorker : public Napi::AsyncProgressWorker<ProgressPayload> {
+public:
+  OCRWorker(Handle *handle, Napi::Object handleObject,
+            Napi::Buffer<uint8_t> buffer, Napi::Promise::Deferred deffered,
+            Napi::Function &progressCallback);
+  ~OCRWorker();
+
+protected:
+  void Execute(const ExecutionProgress &executionProgress) override;
+
+  void OnOK() override;
+  void OnError(const Napi::Error &error) override;
+  void OnProgress(const ProgressPayload *payload, size_t count) override;
+
+private:
+  Handle *handle_;
+  Napi::Reference<Napi::Object> handleRef_;
+  uint8_t *data_;
+  size_t length_;
+  Napi::Reference<Napi::Buffer<uint8_t>> bufferRef_;
+  Napi::Promise::Deferred deffered_;
+  tesseract::ETEXT_DESC *monitor_ = nullptr;
+  Napi::FunctionReference progressCallback_;
+  std::string resultText_;
+  std::string resultHOCR_;
+  std::string resultTSV_;
+  std::string resultALTO_;
+};
+
+#endif // OCRWORKER_H