udpipe-node

Run the UDPipe 1.x.x dependency parser in Node.js / TypeScript. In-package: English Universal Dependencies 2.5 Model (GUM), Multi-OS WASM Engine, alternative Launcher for OS-Native Binary backends, User-Friendly CLI interface (w/ model-swapping, input modes, tree-graphs, built-in UD glossary, persistent custom model & backend configuration, & more: install it & open via npm start).

Wrapping & taming the original C++ implementation of UDPipe 1.4.0 (version released on 11/20/2025), a convenient tool for grammatical and morphological parsing, this portable package provides a typed, synchronous API, two swappable execution backends for extra compatibility, & a built-in English UD model.

Why this exists: The official UDPipe 1.x.x ships bindings for Python, Java, C#, and Perl — but none for JS/TS/Node. This package fills that gap and, thanks to WASM, can run anywhere. It also provides a new low-fuss versatile interface option designed to aid specialists, while remaining accessible to all those who dwell on words: translators, poets, writers, readers, comparatists, teachers, students, editors, and even virtualized yap'n'crafters (you know, those VYs, or aid stans, or however you call them).

Quick Start (from Terminal / Command Line)

# 1. Install
npm install

# 2. Build TypeScript and run the interactive CLI
npm start

Out-of-the-Box Contents

To facilitate expedient setup and portability, this package bundles:

1. A Pre-compiled WebAssembly Layer (runtime/udpipe-wasm.*) consolidated using Emscripten.
2. Launcher for Official UDPipe Distributions with the 1.4.0 MacOS binary included.
3. A Bundled-in UD Model for English: The GUM (Georgetown University Multilayer Corpus) variant from Universal Dependencies 2.5 (models/english-gum-ud-2.5-191206.udpipe).

[!NOTE] To use other languages or alternative English models, you must download them from the official LINDAT UDPipe Models Repository and pass the custom path to the constructor. 4. Convenient CLI interface (initialized via npm start), with *options to: parse from copy-pasted inputs or from text files, distinct verse/prose input modes, a built-in Universal Dependencies glossary, several intricate outputs (detailed table, directed graph, grammatical dependency tree), an option to temporarily swap out the UD model (whereby relaunching resets the model to a default configuration), options to customize default model and backend configuration (the configuration state saved as .udpipe-node.json in your OS root directory, persists across restarts/reinstalls, & is easily updated).

Architecture & OS Compatibility

The package supports two backends, each with different OS compatibility characteristics:

            ┌────────────────────────────────────────────┐
   text  →  │  UDPipe.parse()  →  engine.process()  →  CoNLL-U  →  parseConllu()  →  UDSentence[]
            └────────────────────────────────────────────┘
                                  ▲
                    ┌───────────────┴───────────────┐
              WasmEngine                  NativeBinaryEngine
           (Pure WebAssembly)              (Subprocess spawn)

• conllu.ts — backend-independent CoNLL-U → typed objects. Reused by every engine.
• engine.ts — the UDPipeEngine interface + NativeBinaryEngine (spawns the binary).
• index.ts — the UDPipe convenience class.

1. WasmEngine (Pure WebAssembly — Recommended)

• Compatibility: Fully Cross-Platform (macOS ARM64/Intel, Windows x64, and Linux x64).
• Requirements: Node.js >= 20. Runs anywhere Node.js runs without OS-specific binaries, compilation, or subprocess spawning.
• Internals: Instantiates the Emscripten-compiled WebAssembly binary synchronously on import using top-level await, allowing synchronous, low-latency parsing (~5ms warm re-parse).

2. NativeBinaryEngine (initiates a subprocess)

• Compatibility: macOS Only out-of-the-box (other OS binaries not packaged in the npm distribution, but easily downloadable from official UDPipe repo).
• Custom Config: To use NativeBinaryEngine on Windows or Linux, you must obtain a compiled udpipe executable for your system and specify its path via the binaryPath option or the CLI.

Usage Guide

1. Using the Portable WASM Engine (Recommended)

Importing from /wasm subpath auto-resolves the bundled English model and runs via WebAssembly.

import { createUDPipe } from 'udpipe-node/wasm';

// Initializes the WASM engine with the bundled English GUM model
const nlp = createUDPipe(); 

// Verse mode — one input line = one sentence (keeps line boundaries):
const sentences = nlp.parseLines('From fairest creatures we desire increase,');

// Prose Mode: UDPipe segments sentences itself
const sentences = nlp.parse("I love poetry. It scans well.");

for (const s of sentences) {
  console.log(`# Sentence: ${s.text}`);
  for (const w of s.words) {
    console.log(`${w.id}\t${w.form}\t${w.xpos}\t${w.deprel}\t→\t${w.head}`);
  }
}

2. Using the Native Binary Engine

If you want to use the native binary runner instead, use the method below. // Defaults to bin-macos/udpipe (macOS only) and English GUM model in the repo root. // Use the CLI to point the toolkit to a downloaded non-MacOS binary file & spawn a config. // Otherwise, the below type of call would fail on Windows/Linux. WASM/CLI should still work.

import { UDPipe, NativeBinaryEngine } from 'udpipe-node';

const nlp = new UDPipe(); 

const sentences = nlp.parseLines("From fairest creatures we desire increase,\nThat thereby beauty's rose might never die,");

3. Custom Binary and Model Paths

Download binaries for your OS from a UDPipe GitHub Distribution. Download models from the LINDAT repo. You can specify custom paths for other languages, models, or native executables:

import { UDPipe, NativeBinaryEngine } from 'udpipe-node';

const nlp = new UDPipe({
  // Path to your custom language model downloaded from LINDAT
  modelPath: '/path/to/czech-pdt-ud-2.5-191206.udpipe', 
  // Path to your local Windows or Linux udpipe binary
  binaryPath: '/path/to/udpipe' 
});

Interactive Parser CLI

The package includes a rich, interactive, colorful terminal CLI for querying the parser. To build the codebase and launch the CLI, run:

npm start

Main Menu Options

1. Verse Mode: Parse pasted text line-by-line (respects line breaks).
2. Prose Mode: Parse pasted text with sentence segmentation.
3. Parse from File (Verse Mode): Read a text file and parse line-by-line.
4. Parse from File (Prose Mode): Read a text file and segment into sentences automatically.
5. Load Model File: Temporarily load a specified .udpipe language model file.
6. Configuration Settings: Set or clear persistent defaults (defaultModelPath, defaultBinaryPath) saved to your configuration file.
7. Information: Full-screen 3-page reference guide for UPOS/XPOS tags and dependencies.
8. Exit: Exit the CLI.

Parsing Navigation Controls

Once a parse is done and your output is ready, move between phrases using keyboard keys:

• → or Enter: Go to the next sentence/line parse.
• ←: Go to the previous sentence/line.
• ↓: Open the full-screen Reference Legend overlay.
• ESC or q: Close parses and return to the main menu.
• Scroll-past boundary: Triggers a Return to the main menu? (y/n) prompt.

Reference Legend Navigation

Available in option 7 (Information) and the parse overlay (↓):

• ← / → (or Enter): Switch between three structured, side-by-side full-screen reference cards:
  • Page 1: Universal POS (UPOS) & English Penn Treebank XPOS.
  • Page 2: Universal Dependency Relations (deprels) grouped by clausal/nominal/modifier subtypes.
  • Page 3: Legacy Stanford relations mapping table & key structural notes.
• ↑ (in overlay), ESC or q: Return to parses or the main menu.

Persistent Configuration Defaults

You can configure default paths for the model and the binary so you do not need to specify them in your code. The engine checks paths in the following priority order:

1. Explicit options passed to the UDPipe or WasmEngine constructor.
2. Local project configuration udpipe-config.json at your project root.
3. Global user configuration ~/.udpipe-node.json in your home directory.
4. Bundled package defaults (macOS binary and English GUM model).

Configuration Schema

{
  "defaultModelPath": "/absolute/path/to/custom-model.udpipe",
  "defaultBinaryPath": "/absolute/path/to/system-udpipe-binary"
}

API Reference

| Method | Returns | Description | |---|---|---| | parse(text, opts?) | UDSentence[] | Tokenizes, tags, and parses dependencies. | | parseLines(text, opts?) | UDSentence[] | Treats each input line as a single sentence (best for verse). | | tag(text, opts?) | UDSentence[] | Tokenizes and tags parts-of-speech (skips dependency parser). | | conllu(text, opts?) | string | Returns the raw CoNLL-U format output. | | parseConllu(str) | UDSentence[] | Utility to parse any CoNLL-U string into typed JS objects. |

Typing Details (UDWord)

Each parsed word carries full UDPipe annotations, including Universal Dependencies tags:

• id: Numerical/ordered position within the phrase.
• form: Word form or punctuation symbol.
• lemma: Lemma or stem of a word (its neutral dictionary form).
• upos: Universal part-of-speech tag (these are shared across all languages covered by UD).
• xpos: Model or/and Language-specific part-of-speech tag (for the English GUM, based on the standard Penn Treebank).
• feats: Raw Universal Morphological Features string.
• featsMap: Parsed key-value pairs of morphological features.
• head: ID of the head word (0 = ROOT).
• deprel: A word's dependency relation to its respective head (e.g., nsubj, obj, root). The 'head' is another word within the phrase or clause which frames or demarcates the given's role in relation to it. Generally, each word has at least one other word it relates to. The word with the most ties/relations extending from it is the sentence's "root". These dependency relations enact the whole plethora of accounted-for grammatical and syntactic constraints/rules.
• spaceAfter: Boolean flag indicating if a whitespace character follows this word.

Development

To rebuild the WebAssembly binary from source, requires Emscripten SDK (emsdk):

npm run build:wasm

The compiled assets will be written to runtime/udpipe-wasm.mjs and runtime/udpipe-wasm.wasm.