Compromise API Reference

July 14, 2026 · View on GitHub

Every method returns a new View (a sub-selection of the document) unless noted, so calls chain: nlp(text).match('#Verb').toPastTense().text(). Methods are grouped by what they do.

Method availability depends on the build tier: compromise/one (tokenize), compromise/two (+tags & contractions), and the default compromise / compromise/three (+ all selections below).

Core methods

(available on every View)

  • .case [getter] — preserve the case of the original, ignoring the case of the replacement
  • .possessives [getter] — preserve whether the original was a possessive
  • .tags [getter] — preserve all of the tags of the original, regardless of the tags of the replacement

Utils

  • .found [getter] — is this document empty?
  • .docs [getter] — get a list of term objects for this view
  • .document [getter] — get the full parsed text
  • .pointer [getter] — the indexes for the current view
  • .fullPointer [getter] — explicit indexes for the current view
  • .methods [getter] — access internal library methods
  • .model [getter] — access internal library data
  • .hooks [getter] — which compute methods run by default
  • .isView [getter] — helper for detecting a compromise object
  • .length [getter] — count the # of characters of each match
  • .update(pointer) — create a new view, from this document
  • .toView(pointer) — turn a Verb or Noun view into a normal one
  • .fromText(text) — create a new document
  • .termList() — .docs [alias]
  • .compute(method) — run a named operation on the document
  • .clone(shallow?) — deep-copy the document, so that no references remain

Loops

  • .forEach(fn) — run a function on each phrase, as an individual document
  • .map(fn, emptyResult?) — run each phrase through a function, and create a new document
  • .filter(fn) — return only the phrases that return true
  • .find(fn) — return a document with only the first phrase that matches
  • .some(fn) — return true or false if there is one matching phrase
  • .random(n?) — sample a subset of the results

Accessors

  • .terms(n?) — split-up results by each individual term
  • .groups(name?) — grab a specific named capture group
  • .eq(n) — use only the nth result
  • .first(n?) — use only the first result(s)
  • .last(n?) — use only the last result(s)
  • .firstTerms() — get the first word in each match
  • .lastTerms() — get the end word in each match
  • .slice(start, end?) — grab a subset of the results
  • .all() — return the whole original document ('zoom out')
  • .fullSentences() — return the full original sentence for each match
  • .none() — return an empty view
  • .isDoc(view?) — are these two views of the same document?
  • .wordCount() — count the # of terms in each match

Match

  • .match(match, group?, options?) — return matching patterns in this doc
  • .matchOne(match, group?, options?) — return only the first match
  • .has(match, group?, options?) — Return a boolean if this match exists
  • .if(match, group?, options?) — return each current phrase, only if it contains this match
  • .ifNo(match, group?, options?) — Filter-out any current phrases that have this match
  • .before(match, group?, options?) — return the terms before each match
  • .after(match, group?, options?) — return the terms after each match
  • .lookBehind(match, group?, options?) — alias of .before()
  • .lookBefore(match, group?, options?) — alias of .before()
  • .lookAhead(match, group?, options?) — alias of .after()
  • .lookAfter(match, group?, options?) — alias of .after()
  • .growLeft(match, group?, options?) — add any immediately-preceding matches to the view
  • .growRight(match, group?, options?) — add any immediately-following matches to the view
  • .grow(match, group?, options?) — expand the view with any left-or-right matches
  • .sweep(match, opts?) — apply a sequence of match objects to the document
  • .splitOn(match?, group?) — .split() [alias]
  • .splitBefore(match?, group?) — separate everything after the match as a new phrase
  • .splitAfter(match?, group?) — separate everything before the word, as a new phrase
  • .split(match?, group?) — splitAfter() alias

Case

  • .toLowerCase() — turn every letter of every term to lower-cse
  • .toUpperCase() — turn every letter of every term to upper case
  • .toTitleCase() — upper-case the first letter of each term
  • .toCamelCase() — remove whitespace and title-case each term

Insert

  • .concat(input) — add these new things to the end
  • .insertBefore(input) — add these words before each match
  • .prepend(input) — insertBefore() alias
  • .insertAfter(text) — add these words after each match
  • .append(text) — insertAfter() alias
  • .insert(text) — insertAfter() alias
  • .remove(match) — fully remove these terms from the document
  • .delete(match) — alias for .remove()
  • .replace(from, to?, keep?) — search and replace match with new content
  • .replaceWith(to, keep?) — substitute-in new content
  • .unique() — remove any duplicate matches
  • .reverse() — reverse the order of the matches, but not the words
  • .sort(method?) — re-arrange the order of the matches (in place)
  • .normalize(options?) — cleanup various aspects of the words

Whitespace

  • .pre(str?, concat?) — add this punctuation or whitespace before each match
  • .post(str?, concat?) — add this punctuation or whitespace after each match
  • .trim() — remove start and end whitespace
  • .hyphenate() — connect words with hyphen, and remove whitespace
  • .dehyphenate() — remove hyphens between words, and set whitespace
  • .deHyphenate() — alias for .dehyphenate()
  • .toQuotations(start?, end?) — add quotation marks around selections
  • .toQuotation(start?, end?) — alias for toQuotations()
  • .toParentheses(start?, end?) — add parentheses around selections

Output

  • .text(options?) — return the document as text
  • .json(options?) — pull out desired metadata from the document
  • .debug() — pretty-print the current document and its tags
  • .out(format?) — some named output formats
  • .html(toHighlight) — produce an html string
  • .wrap(matches) — produce an html string

Pointers

  • .union(match) — return all matches without duplicates
  • .and(match) — .union() alias
  • .intersection(match) — return only duplicate matches
  • .not(match, options?) — return all results except for this
  • .difference(match, options?) — .not() alias
  • .complement(match) — get everything that is not a match
  • .settle(match) — remove overlaps in matches

Tag

  • .tag(tag, reason?) — Give all terms the given tag
  • .tagSafe(tag, reason?) — Only apply tag to terms if it is consistent with current tags
  • .unTag(tag, reason?) — Remove this term from the given terms
  • .canBe(tag) — return only the terms that can be this tag

Cache

  • .cache(options?) — freeze the current state of the document, for speed-purposes
  • .uncache(options?) — un-freezes the current state of the document, so it may be transformed
  • .freeze() — prevent current tags from being removed
  • .unfreeze() — allow current tags to be changed [default]
  • .lookup(trie, opts?) — quick find for an array of string matches
  • .autoFill() — assume any type-ahead prefixes
  • .contractions(n?) — return any multi-word terms, like "didn't"
  • .contract() — contract words that can combine, like "did not"
  • .confidence() — Average measure of tag confidence
  • .swap(fromLemma, toLemma, guardTag?) — smart-replace root forms
  • .expand() — turn "i've" into "i have"

Selections (compromise/three)

These return specialised sub-views with extra methods. e.g. doc.verbs().toPastTense().

Selection methods on any View

  • .clauses(n?) — split-up results into multi-term phrases
  • .chunks() — split-up noun-phrase and verb-phrases
  • .normalize(options?) — clean-up the document, in various ways
  • .redact(opts?, blockStr?, keepTags?) — remove any people, places, and organizations
  • .hyphenated(n?) — return all terms connected with a hyphen or dash like 'wash-out'
  • .hashTags(n?) — return terms like '#nlp'
  • .emails(n?) — return terms like 'hi@compromise.cool'
  • .emoji(n?) — return terms like 💋
  • .emoticons(n?) — return terms like :)
  • .atMentions(n?) — return terms like '@nlp_compromise'
  • .urls(n?) — return terms like 'compromise.cool'
  • .pronouns(n?) — return terms like 'he'
  • .conjunctions(n?) — return terms like 'but'
  • .prepositions(n?) — return terms like 'of'
  • .honorifics(n?) — return terms like 'Dr.'
  • .abbreviations(n?) — return terms like 'st.'
  • .phoneNumbers(n?) — return terms like '(939) 555-0113'
  • .addresses(n?) — return terms like '23 Park Avenue'
  • .acronyms(n?) — return terms like 'FBI'
  • .parentheses(n?) — return anything inside (parentheses)
  • .possessives(n?) — return terms like "Spencer's"
  • .quotations(n?) — return any terms inside 'quotation marks'
  • .slashes(n?) — return any slashed terms like 'love/hate'
  • .adjectives(n?) — return words like "clean"
  • .adverbs(n?) — return words like "quickly"
  • .nouns(n?, opts?) — return noun phrases in the view
  • .numbers(n?, opts?) — return any numbers in the view
  • .percentages(n?, opts?) — return any percentages in the view
  • .money(n?, opts?) — return any money in the view
  • .fractions(n?, opts?) — return any fractions in the view
  • .sentences(n?, opts?) — return full sentences in the view
  • .questions(n?, opts?) — find full sentences of any questions in the view
  • .verbs(n?) — return any subsequent terms tagged as a Verb
  • .people(n?) — return person names like 'John A. Smith'
  • .places(n?) — return location names like 'Paris, France'
  • .organizations(n?) — return companies and org names like 'Google Inc.'
  • .topics(n?) — return people, places, and organizations

.nouns() →

  • .parse(n?) — grab the parsed noun-phrase
  • .isPlural() — return only plural nouns
  • .adjectives() — get any adjectives describing this noun
  • .toPlural(setArticle?) — 'football captain' → 'football captains'
  • .toSingular(setArticle?) — 'turnovers' → 'turnover'

.numbers() →

  • .parse(n?) — grab the parsed number
  • .get(n?) — grab the parsed number
  • .isOrdinal() — return only ordinal numbers
  • .isCardinal() — return only cardinal numbers
  • .isUnit(units) — return only numbers with the given unit(s), like 'km'
  • .toNumber() — convert number to 5 or 5th
  • .toLocaleString() — add commas, or nicer formatting for numbers
  • .toText() — convert number to five or fifth
  • .toCardinal() — convert number to five or 5
  • .toOrdinal() — convert number to fifth or 5th
  • .isEqual() — return numbers with this value
  • .greaterThan(min) — return numbers bigger than n
  • .lessThan(max) — return numbers smaller than n
  • .between(min, max) — return numbers between min and max
  • .set(n) — set number to n
  • .add(n) — increase number by n
  • .subtract(n) — decrease number by n
  • .increment() — increase number by 1
  • .decrement() — decrease number by 1

.fractions() →

  • .parse(n?) — grab the parsed number
  • .get(n?) — grab the parsed number
  • .toDecimal() — convert '1/4' to 0.25
  • .toFraction() — convert 'one fourth' to 1/4
  • .toOrdinal() — convert '1/4' to '1/4th'
  • .toCardinal() — convert '1/4th' to '1/4'
  • .toPercentage() — convert '1/4' to 25%

.sentences() →

  • .parse(n?) — grab the parsed sentence
  • .toPastTense() — 'will go' → 'went'
  • .toPresentTense() — 'walked' → 'walks'
  • .toFutureTense() — 'walked' → 'will walk'
  • .toInfinitive() — 'walks' → 'walk'
  • .toNegative() — 'he is cool' → 'he is not cool'
  • .toPositive() — 'he isn't cool' -> 'he is cool'
  • .isQuestion() — keep only questions
  • .isExclamation() — keep only sentences with an exclamation-mark
  • .isStatement() — remove questions, and exclamations

.people() →

  • .parse() — get first/last/middle names

.verbs() →

  • .parse(n?) — grab the parsed verb-phrase
  • .subjects() — grab what [doing] the verb
  • .adverbs() — return the adverbs describing this verb
  • .isSingular() — return only singular nouns
  • .isPlural() — return only plural nouns
  • .isImperative() — only verbs that are instructions
  • .toInfinitive() — 'walks' → 'walk'
  • .toPresentTense() — 'walked' → 'walks'
  • .toPastTense() — 'will go' → 'went'
  • .toFutureTense() — 'walked' → 'will walk'
  • .toGerund() — 'walks' → 'walking'
  • .toPastParticiple() — 'walks' → 'has walked'
  • .conjugate() — return all forms of these verbs
  • .isNegative() — return verbs with 'not'
  • .isPositive() — only verbs without 'not'
  • .toPositive() — "didn't study" → 'studied'
  • .toNegative() — 'went' → 'did not go'

.acronyms() →

  • .strip() — 'F.B.I.' -> 'FBI'
  • .addPeriods() — 'FBI' -> 'F.B.I.'

.parentheses() →

  • .strip() — remove ( and ) punctuation

.possessives() →

  • .strip() — "spencer's" -> "spencer"

.quotations() →

  • .strip() — remove leading and trailing quotation marks

.slashes() →

  • .split() — turn 'love/hate' into 'love hate'

.adjectives() →

  • .adverbs() — get the words describing this adjective
  • .conjugate() — return all forms of these
  • .toComparative(n?) — 'quick' -> 'quicker'
  • .toSuperlative(n?) — 'quick' -> 'quickest'
  • .toAdverb(n?) — 'quick' -> 'quickly'
  • .toNoun(n?) — 'quick' -> 'quickness'

Constructor methods (nlp.*)

(called on the imported nlp object, not a View)

  • nlp.tokenize(text, lexicon?) — interpret text without tagging
  • nlp.lazy(text, match?) — scan through text with minimal analysis
  • nlp.plugin(plugin) — mix in a compromise-plugin
  • nlp.extend(plugin) — mix-in a compromise plugin
  • nlp.parseMatch(match, opts?) — turn a match-string into json
  • nlp.world() — grab library internals
  • nlp.model() — grab library metadata
  • nlp.methods() — grab exposed library methods
  • nlp.hooks() — which compute functions run automatically
  • nlp.verbose(toLog?) — log our decision-making for debugging
  • nlp.version — current semver version of the library
  • nlp.addTags(tags) — connect new tags to tagset graph
  • nlp.addWords(words, isFrozen?) — add new words to internal lexicon
  • nlp.buildTrie(words) — turn a list of words into a searchable graph
  • nlp.buildNet(matches) — compile a set of match objects to a more optimized form
  • nlp.typeahead(words) — add words to the autoFill dictionary