textract-lite

A small, dependency-light text extraction module for node. ESM only.

This is a trimmed-down fork of textract. Everything that required an external binary (antiword, tesseract, pdftotext, unzip, …) has been removed, so there is nothing to install beyond the package itself.

Currently Extracts...

• .docx — application/vnd.openxmlformats-officedocument.wordprocessingml.document
• Anything with a text/* mime type — .txt, .csv, .html, .md, …
• application/csv
• application/javascript

What textract-lite cares about is the mime type, not the extension. Any extension that maps to one of the types above will extract. The mime type is resolved from the file name via mime, and can be overridden — see typeOverride below.

Need a type that isn't listed? Open an issue or a pull request.

Requirements

• Node.js >= 24.11

Install

npm i @nosferatu500/textract-lite

Usage

The package is ESM only, so use import. There is no CLI.

import { fromFileWithPath, fromFileWithMimeAndPath } from "@nosferatu500/textract-lite";

APIs

Both functions are async and resolve to either the extracted text or an Error. options is optional.

File

const text = await fromFileWithPath(filePath);

The mime type is derived from filePath.

File + mime type

const text = await fromFileWithMimeAndPath(type, filePath);

Use this when the file name doesn't reflect its contents, or when you already know the type.

Error handling

Extraction failures are reported two different ways, so handle both: most failures resolve with an Error (unsupported mime type, undeterminable mime type, missing file, undetectable text encoding, a file that isn't really a zip), while a .docx with no extractable content rejects.

try {
    const result = await fromFileWithPath(filePath);
    if (result instanceof Error) {
        // unsupported/unknown type, missing file, unknown encoding, not a zip
        console.error(result.message);
    } else {
        console.log(result);
    }
} catch (error) {
    // .docx containing no extractable content
    console.error(error);
}

TypeScript

The package ships its own types. ExtractOptions is exported for annotating a shared config object:

import { fromFileWithPath, type ExtractOptions } from "@nosferatu500/textract-lite";

const options: ExtractOptions = { preserveLineBreaks: true };
const text = await fromFileWithPath(filePath, options);

Configuration

The second argument to both functions accepts:

• preserveLineBreaks: Defaults to false, which strips all line breaks from the output. Pass true to keep them.
• preserveOnlyMultipleLineBreaks: Defaults to false. When true, single line breaks are collapsed into spaces but consecutive line breaks are preserved. Note that this does not reliably preserve paragraphs unless the source actually uses multiple breaks between them. Setting this implies preserveLineBreaks.
• typeOverride: Only used by fromFileWithPath. When set, this mime type is used instead of the one derived from the file name.

const text = await fromFileWithPath(filePath, { preserveLineBreaks: true });
const csv = await fromFileWithPath("data.dat", { typeOverride: "application/csv" });

Notes on extraction

• Text files have their encoding detected with jschardet and are decoded with iconv-lite. If the encoding cannot be detected, an Error is returned rather than a best-effort guess.
• All extracted text is passed through a cleansing step that normalizes typographic quotes, ellipses and long hyphens, collapses runs of whitespace, and decodes XML entities.

Development

The build targets ES2025 and the package is ESM only. Tests run straight from the TypeScript source using Node's built-in type stripping, so there is no transpiling test loader to configure.

npm install
npm run build     # clean + tsc + prune internal .d.ts files
npm test          # mocha, tests live in tests/
npm run lint      # eslint (flat config)
npm run docs      # typedoc into docs/

License

MIT. See LICENSE.