LaTeX and BibTeX Parser Utilities

7.0.0 verified Thu Apr 23 auth: no javascript

latex-utensils is a TypeScript library providing robust parsing capabilities for LaTeX and BibTeX documents, along with various utility functions. Its current stable version is 7.0.0. The project demonstrates an active release cadence, with frequent beta releases preceding major versions, signaling continuous development and refinement. It uniquely offers both LaTeX and BibTeX parsers within a unified package, building upon established parser foundations like LaTeX.js and latex-parser to deliver comprehensive functionality. This library is particularly well-suited for applications that require programmatic interaction with LaTeX source code, such as creating linters, IDE extensions, or advanced document analysis tools. It achieves this by transforming raw LaTeX strings into a structured Abstract Syntax Tree (AST) that is easily traversable and manipulable. A key differentiator is its inclusion of full TypeScript type definitions, significantly improving developer experience and ensuring type safety when integrating parsing logic into modern JavaScript and TypeScript environments.

Common errors

error ERR_REQUIRE_ESM ↓

cause Attempting to `require()` an ES Module-only package in a CommonJS context.

fix

Switch to ES Module imports (import { ... } from 'latex-utensils';) or configure your project for ESM. For Node.js, add "type": "module" to your package.json.

error TypeError: latexParser.parse is not a function ↓

cause Incorrectly importing `latexParser` or trying to call `parse` on an undefined or incorrect object.

fix

Ensure you are using import { latexParser } from 'latex-utensils'; and that latexParser is properly destructured from the named export.

error SyntaxError: Expected "}" but got "\end" ↓

cause A common parsing error indicating malformed LaTeX syntax in the input string, such as missing braces or mismatched environments.

fix

Review the LaTeX input string for syntax errors. The error message usually provides line and column numbers to help pinpoint the issue. Ensure all environments are properly closed and commands have correct arguments.

Warnings

breaking Major version 7.0.0 might introduce breaking changes to the internal AST structure or parser options, even with minimal release notes. Always review the detailed changelog or test thoroughly when upgrading from v6.x. ↓

fix Consult the official API documentation for any changes to AST node types or parser configuration. Update existing parsing logic to match the new structure if necessary.

gotcha The library primarily uses ES Module (ESM) syntax for imports. Attempting to use CommonJS `require()` directly might lead to 'ERR_REQUIRE_ESM' errors or incorrect import behavior in Node.js environments. ↓

fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` for Node.js) and use `import ... from 'latex-utensils';`. For older CommonJS projects, consider using dynamic `import()` or a transpilation step.

gotcha Parsing very large or complex LaTeX documents can be resource-intensive and slow. The parser is designed for accuracy, which can come at the cost of speed for extreme inputs. ↓

fix For performance-critical applications, consider optimizing input size, pre-processing documents, or implementing caching mechanisms for ASTs. Profile parsing operations to identify bottlenecks.

gotcha Incorrect input encoding for LaTeX files can lead to parsing errors or malformed ASTs, especially with non-ASCII characters. LaTeX documents often specify encoding with `\usepackage[utf8]{inputenc}`. ↓

fix Ensure that the input string provided to `latexParser.parse` is correctly encoded, preferably UTF-8. If reading from a file, explicitly specify UTF-8 encoding during file read operations.

Install

npm install latex-utensils

yarn add latex-utensils

pnpm add latex-utensils

Imports

latexParser
wrong
```
const latexParser = require('latex-utensils').latexParser;
```
correct
```
import { latexParser } from 'latex-utensils';
```
The primary entry point for parsing LaTeX and BibTeX. Use named import for ESM. CommonJS `require` might lead to issues since v7.0.0 seems to be ESM-first.
BibTeXLexer
```
import { BibTeXLexer } from 'latex-utensils';
```
Used for lexing BibTeX documents. Often needed for more granular control over the parsing process beyond the simple `parse` function.
AstRoot
wrong
```
import { AstRoot } from 'latex-utensils';
```
correct
```
import type { AstRoot } from 'latex-utensils';
```
Type definition for the root of the LaTeX AST. Always use `import type` for type-only imports to prevent bundling issues and ensure correct tooling behavior.
Node
```
import type { Node } from 'latex-utensils';
```
Base type for all nodes within the parsed LaTeX AST. Essential for type-checking when traversing the AST.

Quickstart

Demonstrates parsing a LaTeX string into an Abstract Syntax Tree (AST) and basic AST traversal to find commands.

import { latexParser } from 'latex-utensils';
import type { AstRoot } from 'latex-utensils';

const texString = `
\documentclass{article}
\usepackage{amsmath}
\begin{document}
ab c
d $x + y$ e
\begin{align}
    i + j
\end{align}
\end{document}
`;

try {
  const ast: AstRoot = latexParser.parse(texString, { startRule: 'Root' });
  console.log('Parsed LaTeX AST:\n', JSON.stringify(ast, undefined, 2));
  // Example: Find all commands
  const commands = ast.content.filter(node => node.kind === 'command');
  console.log('\nFound commands:', commands.map(cmd => (cmd as any).name));
} catch (error) {
  console.error('Error parsing LaTeX:', error);
}