udpipe-node 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# udpipe-node
+
+Run the [UDPipe 1.x](https://ufal.mff.cuni.cz/udpipe/1) dependency parser in Node.js / TypeScript. In-package:English UD 2.5 model (GUM), Multi-OS WASM engine, MacOS CLI engine.
+
+Wrapping the original C++ implementation of [UDPipe 1.4.0 (version released on 11/20/2025)](https://github.com/ufal/udpipe/releases/tag/v1.4.0), this portable package provides a typed, synchronous API, two swappable execution backends for extra compatibility, & a built-in model. 
+**Why this exists**: The official UDPipe 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. 
+
+---
+
+## Out-of-the-Box Contents
+
+To facilitate expedient setup and portability, this package bundles:
+1. **A Pre-compiled WebAssembly Layer** (`runtime/udpipe-wasm.*`) generated using Emscripten.
+2. **A Single Default English Model**: The GUM 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](https://lindat.mff.cuni.cz/repository/items/41f05304-629f-4313-b9cf-9eeb0a2ca7c6)** and pass the custom path to the constructor.
+
+---
+
+## Architecture & OS Compatibility
+
+The package supports two backends, each with different OS compatibility characteristics:
+
+```
+            ┌────────────────────────────────────────────┐
+   text  →  │  UDPipe.parse()  →  engine.process()  →  CoNLL-U  →  parseConllu()  →  UDSentence[]
+            └────────────────────────────────────────────┘
+                                  ▲
+                   ┌───────────────┴───────────────┐
+             WasmEngine                        CliEngine
+          (Pure WebAssembly)              (Subprocess spawn)
+```
+- **`conllu.ts`** — backend-independent CoNLL-U → typed objects. Reused by every engine.
+- **`engine.ts`** — the `UDPipeEngine` interface + `CliEngine` (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 native binaries, native 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. CliEngine (Subprocess Native Binary)
+* **Compatibility**: **macOS Only** out-of-the-box (other OS binaries *not* packaged in the npm distribution). 
+* **Custom Config**: To use `CliEngine` on Windows or Linux, you must obtain a compiled `udpipe` executable for your system and specify its path manually using the `binaryPath` option.
+
+---
+
+## Quick Start / Setup
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Build TypeScript and run the WASM smoke test
+npm start
+```
+
+---
+
+## Usage Guide
+
+### 1. Using the Portable WASM Engine (Recommended)
+Importing from the `/wasm` subpath resolves the bundled English model automatically and runs via pure WebAssembly.
+
+```typescript
+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 CLI Engine (macOS Only Out-of-the-Box)
+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.
+// Will fail on Windows/Linux or in published npm environments unless paths are provided.
+
+```typescript
+import { UDPipe, CliEngine } 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 the [UDPipe GitHub Distribution](https://github.com/ufal/udpipe/releases/tag/v1.4.0). <br>
+**Download models** from the [LINDAT repo](https://lindat.mff.cuni.cz/repository/items/41f05304-629f-4313-b9cf-9eeb0a2ca7c6). <br>
+You can **specify custom paths** for other languages, models, or native executables:
+
+```typescript
+import { UDPipe, CliEngine } 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, chalk-colored terminal CLI for querying and testing the parser. To build the codebase and launch the CLI, run:
+
+```bash
+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**: Dynamically load a different `.udpipe` language model file.
+6. **Information**: Full-screen 3-page reference guide for POS tags and dependencies.
+7. **Exit**: Terminate the CLI.
+
+### Parsing Navigation Controls
+Once parsing is complete, traverse sentences using the keyboard:
+* **`→` 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 6 (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.
+
+---
+
+## 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 format 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 word form.
+* `upos`: Universal part-of-speech tag.
+* `xpos`: Language-specific part-of-speech tag (Penn Treebank for English).
+* `feats` / `featsMap`: Morphological features.
+* `head`: ID of the head word (0 = ROOT).
+* `deprel`: Universal dependency relation (e.g., `nsubj`, `obj`, `root`).
+* `spaceAfter`: Boolean flag indicating if a whitespace character follows this word.
+
+---
+
+## Development & Building
+
+To rebuild the WebAssembly binary from source, ensure you have the Emscripten SDK (`emsdk`) installed and activated, then run:
+
+```bash
+npm run build:wasm
+```
+
+The compiled assets will be written to `runtime/udpipe-wasm.mjs` and `runtime/udpipe-wasm.wasm`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}