compromise-nlp

Using compromise

compromise is a rule-based English NLP library for JavaScript (no network, no model, no deps). You tokenize text into a document, it tags each word's part-of-speech, and you find and transform parts of the text with a jQuery-like chained API.

import nlp from 'compromise'

let doc = nlp('she sells seashells by the seashore.')
doc.verbs().toPastTense()        // transform
doc.text()                       // 'she sold seashells by the seashore.'

The five rules that prevent almost every mistake

These are the things that are easy to get wrong from memory. Internalize them before writing code.

1. Transforms mutate the document in place — read the result from the original variable

Every transform method (.toPastTense(), .replace(), .tag(), .normalize(), case/whitespace methods…) changes the underlying document. The View it returns is the selection it acted on, not the whole document. So calling .text() on the chain gives you only the selected fragment:

let doc = nlp('I walk to work')
doc.verbs().toPastTense()
doc.text()                                            // ✅ 'I walked to work'  (read from doc)

nlp('I walk to work').verbs().toPastTense().text()    // ❌ 'walked work'  (just the selection)

To transform a copy and leave the original untouched, call .clone() first:

let past = doc.clone().verbs().toPastTense().text()

Read-only methods (.match, .has, .if, .found, .text, .json, accessors) never mutate.

2. Only real tags work — an invalid #Tag matches nothing, silently

There are ~88 valid part-of-speech tags, and they're a hierarchy (#FirstName ⊂ #Person ⊂ #Noun). A #Tag that isn't real does not error — it just matches nothing, which looks like a logic bug. Common inventions that are NOT tags: #Name, #Location, #Subject, #Object, #Adj, #Entity. (Valid ones include #Person, #Place, #Organization, #Noun, #Verb, #Value, #Date.) When unsure, check node_modules/compromise/docs/tags.md.