@luii/node-tesseract-ocr 2.0.0 → 2.1.0

package/README.md

@@ -16,7 +16,6 @@ Native C++ addon for Node.js that exposes Tesseract OCR (`libtesseract-dev`) to
   - [Enums](#enums)
   - [Types](#types)
   - [Tesseract API](#tesseract-api)
-- [Example](#example)
 - [License](#license)
 - [Special Thanks](#special-thanks)
 
@@ -25,6 +24,7 @@ Native C++ addon for Node.js that exposes Tesseract OCR (`libtesseract-dev`) to
 - Native bindings to Tesseract (prebuilds via `pkg-prebuilds`)
 - Access to Tesseract enums and configuration from TypeScript
 - Progress callback and multiple output formats
+- Lazy download of missing traineddata (configurable)
 
 ## Prerequisites
 
@@ -33,7 +33,7 @@ Native C++ addon for Node.js that exposes Tesseract OCR (`libtesseract-dev`) to
 - c++ build toolchain (e.g. build-essentials)
 - libtesseract-dev
 - libleptonica-dev
-- Tesseract training data (eng, deu, ...)
+- Tesseract training data (eng, deu, ...) or let the library handle that
 
 > See [Install](#install)
 
@@ -59,7 +59,9 @@ Install additional languages as needed, for example:
 sudo apt install -y tesseract-ocr-deu tesseract-ocr-eng tesseract-ocr-jpn
 ```
 
-If you install traineddata files manually, make sure `NODE_TESSERACT_DATAPATH` points to the directory that contains them (for example `/usr/share/tesseract-ocr/5/tessdata`).
+If you install traineddata files manually, make sure `TESSDATA_PREFIX` points to the directory that contains them (for example `/usr/share/tessdata`).
+
+If traineddata is missing, this package will download it lazily during `init` by default. You can control this behavior via `ensureTraineddata`, `cachePath`, and `dataPath`.
 
 ## Build
 
@@ -73,12 +75,14 @@ npm run build:release
 
 ## Start
 
-Set `NODE_TESSERACT_DATAPATH` to your traineddata directory (usually `/usr/share/tesseract-ocr/5/tessdata`).
+Set `TESSDATA_PREFIX` to your traineddata directory (usually `/usr/share/tesseract-ocr/5/tessdata` or `/usr/share/tessdata`).
 
 ```sh
-env NODE_TESSERACT_DATAPATH=/usr/share/tesseract-ocr/5/tessdata node path/to/your/app.js
+env TESSDATA_PREFIX=/usr/share/tessdata node path/to/your/app.js
 ```
 
+If you prefer automatic downloads, you can skip setting `TESSDATA_PREFIX` and let the default cache directory handle traineddata on first use.
+
 ## Scripts
 
 ```bash
@@ -86,9 +90,6 @@ env NODE_TESSERACT_DATAPATH=/usr/share/tesseract-ocr/5/tessdata node path/to/you
 npm run build:debug
 npm run build:release
 
-# Build precompiled binaries for distribution
-npm run prebuild
-
 # Run the JS example (builds debug first)
 npm run example:recognize
 
@@ -100,8 +101,73 @@ npm run test:js:watch
 
 ## Examples
 
+### Run Included Example
+
 ```sh
-env NODE_TESSERACT_DATAPATH=/usr/share/tesseract-ocr/5/tessdata npm run example:recognize
+env TESSDATA_PREFIX=/usr/share/tessdata npm run example:recognize
+```
+
+### Basic OCR (Local Traineddata)
+
+You can find a similar example in the `examples/` folder of the project.
+
+```ts
+import fs from "node:fs";
+import Tesseract, { OcrEngineModes } from "node-tesseract-ocr";
+
+process.env.TESSDATA_PREFIX = "/usr/share/tessdata/";
+
+async function main() {
+  const tesseract = new Tesseract();
+  await tesseract.init({
+    langs: ["eng"],
+  });
+
+  const buffer = fs.readFileSync("example1.png");
+  await tesseract.setImage(buffer);
+  await tesseract.recognize((info) => {
+    console.log(`Progress: ${info.percent}%`);
+  });
+
+  const text = await tesseract.getUTF8Text();
+  console.log(text);
+
+  await tesseract.end();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+### Lazy Traineddata Download (Default)
+
+```ts
+import fs from "node:fs";
+import Tesseract from "node-tesseract-ocr";
+
+async function main() {
+  const tesseract = new Tesseract();
+  await tesseract.init({
+    langs: ["eng"],
+    ensureTraineddata: true
+    dataPath: './tessdata-local'
+  });
+
+  const buffer = fs.readFileSync("example1.png");
+  await tesseract.setImage(buffer);
+  await tesseract.recognize();
+  const text = await tesseract.getUTF8Text();
+  console.log(text);
+
+  await tesseract.end();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
 ```
 
 ## Public API
@@ -151,13 +217,17 @@ Full list of page segmentation modes from Tesseract.
 
 #### `TesseractInitOptions`
 
-| Field                   | Type                                                                                                  | Optional | Default     | Description                             |
-| ----------------------- | ----------------------------------------------------------------------------------------------------- | -------- | ----------- | --------------------------------------- |
-| `lang`                  | [`Language[]`](#availablelanguages)                                                                   | Yes      | `undefined` | Languages to load as an array.          |
-| `oem`                   | [`OcrEngineMode`](#ocrenginemode)                                                                     | Yes      | `undefined` | OCR engine mode.                        |
-| `vars`                  | `Partial<Record<keyof ConfigurationVariables, ConfigurationVariables[keyof ConfigurationVariables]>>` | Yes      | `undefined` | Variables to set.                       |
-| `configs`               | `Array<string>`                                                                                       | Yes      | `undefined` | Tesseract config files to apply.        |
-| `setOnlyNonDebugParams` | `boolean`                                                                                             | Yes      | `undefined` | If true, only non-debug params are set. |
+| Field                   | Type                                                                                                  | Optional | Default                                | Description                             |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- | --------------------------------------- |
+| `langs`                 | [`Language[]`](#availablelanguages)                                                                   | Yes      | `undefined`                            | Languages to load as an array.          |
+| `oem`                   | [`OcrEngineMode`](#ocrenginemode)                                                                     | Yes      | `undefined`                            | OCR engine mode.                        |
+| `vars`                  | `Partial<Record<keyof ConfigurationVariables, ConfigurationVariables[keyof ConfigurationVariables]>>` | Yes      | `undefined`                            | Variables to set.                       |
+| `configs`               | `Array<string>`                                                                                       | Yes      | `undefined`                            | Tesseract config files to apply.        |
+| `setOnlyNonDebugParams` | `boolean`                                                                                             | Yes      | `undefined`                            | If true, only non-debug params are set. |
+| `ensureTraineddata`     | `boolean`                                                                                             | Yes      | `true`                                 | Download missing traineddata lazily.    |
+| `cachePath`             | `string`                                                                                              | Yes      | `~/.cache/node-tesseract-ocr/tessdata` | Cache directory for downloads.          |
+| `dataPath`              | `string`                                                                                              | Yes      | `TESSDATA_PREFIX` or `cachePath`       | Directory used by Tesseract for data.   |
+| `progressCallback`      | `(info: TrainingDataDownloadProgress) => void`                                                        | Yes      | `undefined`                            | Download progress callback.             |
 
 #### `TesseractSetRectangleOptions`
 
@@ -464,39 +534,6 @@ Ends the instance.
 end(): Promise<void>
 ```
 
-## Example
-
-You can find a similar example in the `examples/` folder of the project
-
-```ts
-import fs from "node:fs";
-import Tesseract, { OcrEngineModes } from "node-tesseract-ocr";
-
-async function main() {
-  const tesseract = new Tesseract();
-  await tesseract.init({
-    lang: ["eng"],
-    oem: OcrEngineModes.OEM_LSTM_ONLY,
-  });
-
-  const buffer = fs.readFileSync("example1.png");
-  await tesseract.setImage(buffer);
-  await tesseract.recognize((info) => {
-    console.log(`Progress: ${info.percent}%`);
-  });
-
-  const text = await tesseract.getUTF8Text();
-  console.log(text);
-
-  await tesseract.end();
-}
-
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
-```
-
 ## License
 
 Apache-2.0. See [`LICENSE.md`](/LICENSE.md) for full terms.

package/dist/cjs/index.cjs

@@ -23,6 +23,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NativeTesseract = exports.Tesseract = exports.LogLevels = exports.PageSegmentationModes = exports.OcrEngineModes = exports.Language = void 0;
 /**
@@ -239,14 +242,24 @@ exports.LogLevels = {
     FATAL: "50000",
     OFF: "2147483647",
 };
-const fs = require("node:fs");
-const path = require("node:path");
-const rootFromSource = path.resolve(__dirname, "../../");
-const bindingOptionsFromSource = path.resolve(rootFromSource, "binding-options.js");
-const bindingOptionsPath = fs.existsSync(bindingOptionsFromSource)
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_stream_1 = require("node:stream");
+const promises_2 = require("node:stream/promises");
+const node_zlib_1 = require("node:zlib");
+const proper_lockfile_1 = require("proper-lockfile");
+const utils_1 = require("./utils");
+const TESSDATA4_BEST = (lang) => `https://cdn.jsdelivr.net/npm/@tesseract.js-data/${lang}/4.0.0_best_int/`;
+const TESSDATA4 = (lang) => `https://cdn.jsdelivr.net/npm/@tesseract.js-data/${lang}/4.0.0/`;
+const DEFAULT_CACHE_DIR = node_path_1.default.join(node_os_1.default.homedir(), ".cache", "node-tesseract-ocr", "tessdata");
+const rootFromSource = node_path_1.default.resolve(__dirname, "../../");
+const bindingOptionsFromSource = node_path_1.default.resolve(rootFromSource, "binding-options.js");
+const bindingOptionsPath = (0, node_fs_1.existsSync)(bindingOptionsFromSource)
     ? bindingOptionsFromSource
-    : path.resolve(process.cwd(), "binding-options.js");
-const prebuildRoot = fs.existsSync(bindingOptionsFromSource)
+    : node_path_1.default.resolve(process.cwd(), "binding-options.js");
+const prebuildRoot = (0, node_fs_1.existsSync)(bindingOptionsFromSource)
     ? rootFromSource
     : process.cwd();
 const { Tesseract: NativeTesseract } = require("pkg-prebuilds")(prebuildRoot, require(bindingOptionsPath));
@@ -255,23 +268,124 @@ class Tesseract extends NativeTesseract {
     constructor() {
         super();
     }
-    init(options) {
+    init() {
         const _super = Object.create(null, {
             init: { get: () => super.init }
         });
-        return __awaiter(this, void 0, void 0, function* () {
-            // scan train data for any files
-            // check whether the requested langs are available/cached
-            // if not
-            //   fetch traineddata from cdn
-            //     - add .lock file to downloaded file (while downloading, so other instances
-            //       can wait on it and dont have to download again)
-            //     - place into tesseract standard folder
-            //  if available
-            //    just go on with the init function of the native addon
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            var _a, _b, _c, _d, _e, _f;
+            (_a = options.langs) !== null && _a !== void 0 ? _a : (options.langs = []);
+            (_b = options.ensureTraineddata) !== null && _b !== void 0 ? _b : (options.ensureTraineddata = true);
+            (_c = options.cachePath) !== null && _c !== void 0 ? _c : (options.cachePath = DEFAULT_CACHE_DIR);
+            (_d = options.dataPath) !== null && _d !== void 0 ? _d : (options.dataPath = (_e = process.env.TESSDATA_PREFIX) !== null && _e !== void 0 ? _e : options.cachePath);
+            (_f = options.progressCallback) !== null && _f !== void 0 ? _f : (options.progressCallback = undefined);
+            const cachePath = node_path_1.default.resolve(options.cachePath);
+            const dataPath = node_path_1.default.resolve(options.dataPath);
+            if (options.ensureTraineddata) {
+                for (const lang of [...options.langs, exports.Language.osd]) {
+                    const downloadBaseUrl = options.oem === exports.OcrEngineModes.OEM_LSTM_ONLY
+                        ? TESSDATA4_BEST(lang)
+                        : TESSDATA4(lang);
+                    lang &&
+                        (yield this.ensureTrainingData({ lang, dataPath, cachePath, downloadBaseUrl }, options.progressCallback));
+                }
+            }
             return _super.init.call(this, options);
         });
     }
+    ensureTrainingData(_a, progressCallback_1) {
+        return __awaiter(this, arguments, void 0, function* ({ lang, dataPath, cachePath, downloadBaseUrl }, progressCallback) {
+            const traineddataPath = node_path_1.default.join(dataPath, `${lang}.traineddata`);
+            const cacheTraineddataPath = node_path_1.default.join(cachePath, `${lang}.traineddata`);
+            if (yield (0, utils_1.isValidTraineddata)(cacheTraineddataPath)) {
+                if (traineddataPath !== cacheTraineddataPath) {
+                    yield (0, promises_1.mkdir)(dataPath, { recursive: true });
+                    yield (0, promises_1.copyFile)(cacheTraineddataPath, traineddataPath);
+                }
+                return traineddataPath;
+            }
+            if (yield (0, utils_1.isValidTraineddata)(traineddataPath)) {
+                return traineddataPath;
+            }
+            yield (0, promises_1.mkdir)(dataPath, { recursive: true });
+            const release = yield (0, proper_lockfile_1.lock)(traineddataPath, {
+                lockfilePath: `${traineddataPath}.lock`,
+                stale: 10 * 60 * 1000,
+                update: 30 * 1000,
+                realpath: false,
+                retries: { retries: 50, minTimeout: 200, maxTimeout: 2000 },
+            });
+            try {
+                if (yield (0, utils_1.isValidTraineddata)(traineddataPath)) {
+                    return traineddataPath;
+                }
+                if (traineddataPath !== cacheTraineddataPath &&
+                    (yield (0, utils_1.isValidTraineddata)(cacheTraineddataPath))) {
+                    yield (0, promises_1.copyFile)(cacheTraineddataPath, traineddataPath);
+                    return traineddataPath;
+                }
+                const url = new URL(`${lang}.traineddata.gz`, downloadBaseUrl).toString();
+                const response = yield fetch(url);
+                if (!response.ok || !response.body) {
+                    throw new Error(`Failed to download traineddata for ${lang}: ${response.status} ${response.statusText}`);
+                }
+                const tmpPath = node_path_1.default.join(node_os_1.default.tmpdir(), [
+                    "node-tesseract-ocr",
+                    lang,
+                    "traineddata",
+                    process.pid,
+                    Date.now(),
+                    Math.random().toString(36).slice(2),
+                ].join("-"));
+                const totalBytesHeader = response.headers.get("content-length");
+                const totalBytes = totalBytesHeader
+                    ? Number(totalBytesHeader)
+                    : undefined;
+                let downloadedBytes = 0;
+                const progressStream = new node_stream_1.Transform({
+                    transform(chunk, _, callback) {
+                        if (progressCallback) {
+                            downloadedBytes += chunk.length;
+                            const percent = typeof totalBytes === "number" && Number.isFinite(totalBytes)
+                                ? (downloadedBytes / totalBytes) * 100
+                                : undefined;
+                            progressCallback({
+                                lang,
+                                url,
+                                downloadedBytes,
+                                totalBytes: Number.isFinite(totalBytes) ? totalBytes : undefined,
+                                percent,
+                            });
+                        }
+                        callback(null, chunk);
+                    },
+                });
+                try {
+                    yield (0, promises_2.pipeline)(node_stream_1.Readable.fromWeb(response.body), progressStream, (0, node_zlib_1.createGunzip)(), (0, node_fs_1.createWriteStream)(tmpPath));
+                    try {
+                        yield (0, promises_1.rename)(tmpPath, traineddataPath);
+                    }
+                    catch (error) {
+                        if (error.code === "EXDEV") {
+                            yield (0, promises_1.copyFile)(tmpPath, traineddataPath);
+                            yield (0, promises_1.rm)(tmpPath, { force: true });
+                        }
+                        else {
+                            throw error;
+                        }
+                    }
+                }
+                catch (error) {
+                    yield (0, promises_1.rm)(tmpPath, { force: true });
+                    throw error;
+                }
+                return traineddataPath;
+            }
+            finally {
+                yield release();
+            }
+        });
+    }
 }
 exports.Tesseract = Tesseract;
 exports.default = Tesseract;

package/dist/cjs/index.d.ts

@@ -839,20 +839,81 @@ export interface TesseractInitOptions {
     /**
      * 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
+     * The OSD Language will always be loaded to support orientation and script detection
+     * IMPORTANT: if you specify more than one language here (e.g.: `deu, eng` for example)
+     *            tesseract will try to recognize german and english in the same image.
+     *            Originally tesseract itself accepts it as `deu+eng`, but since this
+     *            makes typing very hard to near impossible its safer to just accept a
+     *            array with the languages it should look for.
+     *            When talking about "hard typing/impossible typing" its because typescript
+     *            itself cannot create recursive types, and chaining template types
+     *            (e.g.: `${Language}+${Language}+...`) stretches out the compilation time
+     *            to a unacceptable amount
+     *
+     * @default [Language.osd]
      */
-    lang?: Language[];
+    langs?: Language[];
+    /**
+     * Specify where the trainingdata is located
+     * Besides the datapath in general it is versioned to the
+     * version of tesseract
+     * @default '~/.cache/node-tesseract-ocr/'
+     */
+    cachePath?: string;
+    /**
+     * Explicit datapath for traineddata. Takes precedence over
+     * the `TESSDATA_PREFIX` environment variable.
+     */
+    dataPath?: string;
+    /**
+     * This will be called for every language that was specified in `lang`,
+     * it allows the user to be flexible about the training data's location
+     * Or if he needs to specify his own location for certain languages/custom languages
+     * IMPORTANT: Ensures that trainingdata will be downloaded from the following cdn
+     *            in case they dont exist
+     *       OEM_LSTM_ONLY => https://cdn.jsdelivr.net/npm/@tesseract.js-data/${lang}/4.0.0_best_int
+     *   NON OEM_LSTM_ONLY => https://cdn.jsdelivr.net/npm/@tesseract.js-data/${lang}/4.0.0
+     * NOTE: Tesseract 5.x.x still uses the 4.x.x trainingdata
+     *
+     * @default true
+     */
+    ensureTraineddata?: boolean;
+    /**
+     * Optional progress callback for traineddata downloads.
+     */
+    progressCallback?: (info: TrainingDataDownloadProgress) => void;
     /**
      * 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.
+     * @default OEM_DEFAULT
      * @throws {Error} Will throw an error when oem mode is below 0 or over 3
      */
     oem?: OcrEngineMode;
+    /**
+     * Controls if only non debug parameters will be set upon initialization
+     * @default false
+     */
     setOnlyNonDebugParams?: boolean;
+    /**
+     * Array of paths that point to their corresponding config files
+     * usually located in the `dataPath` location alongside the training data
+     */
     configs?: Array<string>;
+    /**
+     * Record of parameters that should be set upon initialization
+     * Consult the original documentation of tesseract on which variables
+     * can actually be set
+     */
     vars?: Partial<Record<keyof ConfigurationVariables, ConfigurationVariables[keyof ConfigurationVariables]>>;
 }
+export interface TrainingDataDownloadProgress {
+    lang: Language;
+    url: string;
+    downloadedBytes: number;
+    totalBytes?: number;
+    percent?: number;
+}
 export interface TesseractSetRectangleOptions {
     top: number;
     left: number;
@@ -913,6 +974,13 @@ export interface DetectOrientationScriptResult {
      */
     scriptConfidence: number;
 }
+export type EnsureTrainedDataOptions = {
+    lang: Language;
+    cachePath: string;
+    dataPath: string;
+    downloadBaseUrl: string;
+    progressCallback?: (info: TrainingDataDownloadProgress) => void;
+};
 export interface TesseractInstance {
     /**
      * Initialize the engine with the given options.
@@ -1063,7 +1131,8 @@ export type TesseractConstructor = new () => TesseractInstance;
 declare const NativeTesseract: TesseractConstructor;
 declare class Tesseract extends NativeTesseract {
     constructor();
-    init(options: TesseractInitOptions): Promise<void>;
+    init(options?: TesseractInitOptions): Promise<void>;
+    ensureTrainingData({ lang, dataPath, cachePath, downloadBaseUrl }: EnsureTrainedDataOptions, progressCallback?: (info: TrainingDataDownloadProgress) => void): Promise<string>;
 }
 export { Tesseract, NativeTesseract };
 export default Tesseract;

package/dist/cjs/utils.d.ts

@@ -0,0 +1 @@
+export declare const isValidTraineddata: (filePath: string) => Promise<boolean>;

package/dist/cjs/utils.js

@@ -0,0 +1,23 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidTraineddata = void 0;
+const promises_1 = require("node:fs/promises");
+const isValidTraineddata = (filePath) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const info = yield (0, promises_1.stat)(filePath);
+        return info.isFile() && info.size > 0;
+    }
+    catch (_a) {
+        return false;
+    }
+});
+exports.isValidTraineddata = isValidTraineddata;

package/dist/esm/index.d.ts

@@ -839,20 +839,81 @@ export interface TesseractInitOptions {
     /**
      * 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
+     * The OSD Language will always be loaded to support orientation and script detection
+     * IMPORTANT: if you specify more than one language here (e.g.: `deu, eng` for example)
+     *            tesseract will try to recognize german and english in the same image.
+     *            Originally tesseract itself accepts it as `deu+eng`, but since this
+     *            makes typing very hard to near impossible its safer to just accept a
+     *            array with the languages it should look for.
+     *            When talking about "hard typing/impossible typing" its because typescript
+     *            itself cannot create recursive types, and chaining template types
+     *            (e.g.: `${Language}+${Language}+...`) stretches out the compilation time
+     *            to a unacceptable amount
+     *
+     * @default [Language.osd]
      */
-    lang?: Language[];
+    langs?: Language[];
+    /**
+     * Specify where the trainingdata is located
+     * Besides the datapath in general it is versioned to the
+     * version of tesseract
+     * @default '~/.cache/node-tesseract-ocr/'
+     */
+    cachePath?: string;
+    /**
+     * Explicit datapath for traineddata. Takes precedence over
+     * the `TESSDATA_PREFIX` environment variable.
+     */
+    dataPath?: string;
+    /**
+     * This will be called for every language that was specified in `lang`,
+     * it allows the user to be flexible about the training data's location
+     * Or if he needs to specify his own location for certain languages/custom languages
+     * IMPORTANT: Ensures that trainingdata will be downloaded from the following cdn
+     *            in case they dont exist
+     *       OEM_LSTM_ONLY => https://cdn.jsdelivr.net/npm/@tesseract.js-data/${lang}/4.0.0_best_int
+     *   NON OEM_LSTM_ONLY => https://cdn.jsdelivr.net/npm/@tesseract.js-data/${lang}/4.0.0
+     * NOTE: Tesseract 5.x.x still uses the 4.x.x trainingdata
+     *
+     * @default true
+     */
+    ensureTraineddata?: boolean;
+    /**
+     * Optional progress callback for traineddata downloads.
+     */
+    progressCallback?: (info: TrainingDataDownloadProgress) => void;
     /**
      * 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.
+     * @default OEM_DEFAULT
      * @throws {Error} Will throw an error when oem mode is below 0 or over 3
      */
     oem?: OcrEngineMode;
+    /**
+     * Controls if only non debug parameters will be set upon initialization
+     * @default false
+     */
     setOnlyNonDebugParams?: boolean;
+    /**
+     * Array of paths that point to their corresponding config files
+     * usually located in the `dataPath` location alongside the training data
+     */
     configs?: Array<string>;
+    /**
+     * Record of parameters that should be set upon initialization
+     * Consult the original documentation of tesseract on which variables
+     * can actually be set
+     */
     vars?: Partial<Record<keyof ConfigurationVariables, ConfigurationVariables[keyof ConfigurationVariables]>>;
 }
+export interface TrainingDataDownloadProgress {
+    lang: Language;
+    url: string;
+    downloadedBytes: number;
+    totalBytes?: number;
+    percent?: number;
+}
 export interface TesseractSetRectangleOptions {
     top: number;
     left: number;
@@ -913,6 +974,13 @@ export interface DetectOrientationScriptResult {
      */
     scriptConfidence: number;
 }
+export type EnsureTrainedDataOptions = {
+    lang: Language;
+    cachePath: string;
+    dataPath: string;
+    downloadBaseUrl: string;
+    progressCallback?: (info: TrainingDataDownloadProgress) => void;
+};
 export interface TesseractInstance {
     /**
      * Initialize the engine with the given options.
@@ -1063,7 +1131,8 @@ export type TesseractConstructor = new () => TesseractInstance;
 declare const NativeTesseract: TesseractConstructor;
 declare class Tesseract extends NativeTesseract {
     constructor();
-    init(options: TesseractInitOptions): Promise<void>;
+    init(options?: TesseractInitOptions): Promise<void>;
+    ensureTrainingData({ lang, dataPath, cachePath, downloadBaseUrl }: EnsureTrainedDataOptions, progressCallback?: (info: TrainingDataDownloadProgress) => void): Promise<string>;
 }
 export { Tesseract, NativeTesseract };
 export default Tesseract;

package/dist/esm/index.mjs

@@ -227,14 +227,24 @@ export const LogLevels = {
     FATAL: "50000",
     OFF: "2147483647",
 };
-const fs = require("node:fs");
-const path = require("node:path");
+import { existsSync, createWriteStream } from "node:fs";
+import { mkdir, rename, rm, copyFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { lock } from "proper-lockfile";
+import { isValidTraineddata } from "./utils";
+const TESSDATA4_BEST = (lang) => `https://cdn.jsdelivr.net/npm/@tesseract.js-data/${lang}/4.0.0_best_int/`;
+const TESSDATA4 = (lang) => `https://cdn.jsdelivr.net/npm/@tesseract.js-data/${lang}/4.0.0/`;
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), ".cache", "node-tesseract-ocr", "tessdata");
 const rootFromSource = path.resolve(__dirname, "../../");
 const bindingOptionsFromSource = path.resolve(rootFromSource, "binding-options.js");
-const bindingOptionsPath = fs.existsSync(bindingOptionsFromSource)
+const bindingOptionsPath = existsSync(bindingOptionsFromSource)
     ? bindingOptionsFromSource
     : path.resolve(process.cwd(), "binding-options.js");
-const prebuildRoot = fs.existsSync(bindingOptionsFromSource)
+const prebuildRoot = existsSync(bindingOptionsFromSource)
     ? rootFromSource
     : process.cwd();
 const { Tesseract: NativeTesseract } = require("pkg-prebuilds")(prebuildRoot, require(bindingOptionsPath));
@@ -242,18 +252,116 @@ class Tesseract extends NativeTesseract {
     constructor() {
         super();
     }
-    async init(options) {
-        // scan train data for any files
-        // check whether the requested langs are available/cached
-        // if not
-        //   fetch traineddata from cdn
-        //     - add .lock file to downloaded file (while downloading, so other instances
-        //       can wait on it and dont have to download again)
-        //     - place into tesseract standard folder
-        //  if available
-        //    just go on with the init function of the native addon
+    async init(options = {}) {
+        options.langs ??= [];
+        options.ensureTraineddata ??= true;
+        options.cachePath ??= DEFAULT_CACHE_DIR;
+        options.dataPath ??= process.env.TESSDATA_PREFIX ?? options.cachePath;
+        options.progressCallback ??= undefined;
+        const cachePath = path.resolve(options.cachePath);
+        const dataPath = path.resolve(options.dataPath);
+        if (options.ensureTraineddata) {
+            for (const lang of [...options.langs, Language.osd]) {
+                const downloadBaseUrl = options.oem === OcrEngineModes.OEM_LSTM_ONLY
+                    ? TESSDATA4_BEST(lang)
+                    : TESSDATA4(lang);
+                lang &&
+                    (await this.ensureTrainingData({ lang, dataPath, cachePath, downloadBaseUrl }, options.progressCallback));
+            }
+        }
         return super.init(options);
     }
+    async ensureTrainingData({ lang, dataPath, cachePath, downloadBaseUrl }, progressCallback) {
+        const traineddataPath = path.join(dataPath, `${lang}.traineddata`);
+        const cacheTraineddataPath = path.join(cachePath, `${lang}.traineddata`);
+        if (await isValidTraineddata(cacheTraineddataPath)) {
+            if (traineddataPath !== cacheTraineddataPath) {
+                await mkdir(dataPath, { recursive: true });
+                await copyFile(cacheTraineddataPath, traineddataPath);
+            }
+            return traineddataPath;
+        }
+        if (await isValidTraineddata(traineddataPath)) {
+            return traineddataPath;
+        }
+        await mkdir(dataPath, { recursive: true });
+        const release = await lock(traineddataPath, {
+            lockfilePath: `${traineddataPath}.lock`,
+            stale: 10 * 60 * 1000,
+            update: 30 * 1000,
+            realpath: false,
+            retries: { retries: 50, minTimeout: 200, maxTimeout: 2000 },
+        });
+        try {
+            if (await isValidTraineddata(traineddataPath)) {
+                return traineddataPath;
+            }
+            if (traineddataPath !== cacheTraineddataPath &&
+                (await isValidTraineddata(cacheTraineddataPath))) {
+                await copyFile(cacheTraineddataPath, traineddataPath);
+                return traineddataPath;
+            }
+            const url = new URL(`${lang}.traineddata.gz`, downloadBaseUrl).toString();
+            const response = await fetch(url);
+            if (!response.ok || !response.body) {
+                throw new Error(`Failed to download traineddata for ${lang}: ${response.status} ${response.statusText}`);
+            }
+            const tmpPath = path.join(os.tmpdir(), [
+                "node-tesseract-ocr",
+                lang,
+                "traineddata",
+                process.pid,
+                Date.now(),
+                Math.random().toString(36).slice(2),
+            ].join("-"));
+            const totalBytesHeader = response.headers.get("content-length");
+            const totalBytes = totalBytesHeader
+                ? Number(totalBytesHeader)
+                : undefined;
+            let downloadedBytes = 0;
+            const progressStream = new Transform({
+                transform(chunk, _, callback) {
+                    if (progressCallback) {
+                        downloadedBytes += chunk.length;
+                        const percent = typeof totalBytes === "number" && Number.isFinite(totalBytes)
+                            ? (downloadedBytes / totalBytes) * 100
+                            : undefined;
+                        progressCallback({
+                            lang,
+                            url,
+                            downloadedBytes,
+                            totalBytes: Number.isFinite(totalBytes) ? totalBytes : undefined,
+                            percent,
+                        });
+                    }
+                    callback(null, chunk);
+                },
+            });
+            try {
+                await pipeline(Readable.fromWeb(response.body), progressStream, createGunzip(), createWriteStream(tmpPath));
+                try {
+                    await rename(tmpPath, traineddataPath);
+                }
+                catch (error) {
+                    if (error.code === "EXDEV") {
+                        await copyFile(tmpPath, traineddataPath);
+                        await rm(tmpPath, { force: true });
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+            catch (error) {
+                await rm(tmpPath, { force: true });
+                throw error;
+            }
+            return traineddataPath;
+        }
+        finally {
+            await release();
+        }
+    }
 }
 export { Tesseract, NativeTesseract };
 export default Tesseract;

package/dist/esm/utils.d.ts

@@ -0,0 +1 @@
+export declare const isValidTraineddata: (filePath: string) => Promise<boolean>;

package/dist/esm/utils.js

@@ -0,0 +1,10 @@
+import { stat } from "node:fs/promises";
+export const isValidTraineddata = async (filePath) => {
+    try {
+        const info = await stat(filePath);
+        return info.isFile() && info.size > 0;
+    }
+    catch {
+        return false;
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luii/node-tesseract-ocr",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "binary": {
     "napi_versions": [
@@ -63,15 +63,17 @@
     "LICENSE.md"
   ],
   "devDependencies": {
-    "vitest": "^2.1.9",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  },
-  "dependencies": {
-    "cmake-js": "^7.4.0",
+    "cmake-js": "^8.0.0",
     "node-addon-api": "^8.5.0",
+    "@types/node": "^25.1.0",
+    "@types/proper-lockfile": "^4.1.4",
     "dotenv": "^16.4.5",
-    "pkg-prebuilds": "^1.0.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "pkg-prebuilds": "^1.0.0",
+    "proper-lockfile": "^4.1.2"
   },
   "exports": {
     "require": {

package/src/commands.hpp

@@ -18,7 +18,6 @@
 
 #include "monitor.hpp"
 #include "utils.hpp"
-#include <iostream>
 #include <memory>
 #include <napi.h>
 #include <optional>

package/src/tesseract_wrapper.cpp

@@ -94,16 +94,29 @@ Napi::Value TesseractWrapper::Init(const Napi::CallbackInfo &info) {
   auto options = info[0].As<Napi::Object>();
   CommandInit command{};
 
-  const Napi::Value langOption = options.Get("lang");
-  if (!langOption.IsUndefined()) {
-    if (!langOption.IsArray()) {
+  const Napi::Value dataPathOption = options.Get("dataPath");
+  if (!dataPathOption.IsUndefined()) {
+    if (!dataPathOption.IsString()) {
       deferred.Reject(
-          Napi::TypeError::New(env, "Option 'lang' must be a array of strings")
+          Napi::TypeError::New(env, "Option 'dataPath' must be a string")
               .Value());
       return deferred.Promise();
     }
 
-    Napi::Array languages = langOption.As<Napi::Array>();
+    Napi::String dataPath = dataPathOption.As<Napi::String>();
+    command.data_path = dataPath.Utf8Value();
+  }
+
+  const Napi::Value langsOption = options.Get("langs");
+  if (!langsOption.IsUndefined()) {
+    if (!langsOption.IsArray()) {
+      deferred.Reject(
+          Napi::TypeError::New(env, "Option 'langs' must be a array of strings")
+              .Value());
+      return deferred.Promise();
+    }
+
+    Napi::Array languages = langsOption.As<Napi::Array>();
     std::string language;
 
     for (uint32_t i = 0; i < languages.Length(); ++i) {

package/src/tesseract_wrapper.hpp

@@ -65,6 +65,4 @@ private:
 
   Napi::Env _env;
   WorkerThread _worker_thread;
-
-  const std::string _data_path = std::getenv("TESSDATA_PREFIX");
 };