eyecite-ts

TypeScript legal citation extraction — a port of Python eyecite with extended capabilities.

Extract structured data from legal citations in court opinions, briefs, and legal documents. A citation like 500 F.2d 123 (9th Cir. 2020) encodes a volume (500), reporter (Federal Reporter, 2nd Series), page (123), court (Ninth Circuit), and year. This library parses all of that into typed objects, resolves short-form references like "Id." back to their antecedents, and can annotate the original text with HTML markup. Zero runtime dependencies, browser-compatible, ~37 KB brotli.

Installation

npm install eyecite-ts

Quick Start

A complete extract → resolve → annotate workflow:

import { extractCitations } from "eyecite-ts"
import { annotate } from "eyecite-ts/annotate"

const text = `In Smith v. Jones, 500 F.2d 123 (9th Cir. 2020), the court
applied 42 U.S.C. § 1983. Id. at 130. See also 123 Harv. L. Rev. 456 (2019).`

// Step 1: Extract and resolve in one call
const citations = extractCitations(text, { resolve: true })

// Step 2: Inspect results
for (const cite of citations) {
  switch (cite.type) {
    case "case":
      console.log(cite.caseName, cite.reporter, cite.year)
      // "Smith v. Jones" "F.2d" 2020
      break
    case "statute":
      console.log(cite.title, cite.code, cite.section)
      // 42 "U.S.C." "1983"
      break
    case "id":
      console.log("Id. resolves to:", cite.resolution?.resolvedTo)
      // Id. resolves to: 0
      break
    case "journal":
      console.log(cite.journal, cite.volume, cite.page)
      // "Harv. L. Rev." 123 456
      break
  }
}

// Step 3: Annotate the original text
const result = annotate(text, citations, {
  template: { before: '<cite>', after: '</cite>' },
})
console.log(result.text)

What It Extracts

12 citation types, each with its own TypeScript interface:

| Type | Example | Key Fields | |------|---------|------------| | case | 500 F.2d 123 (9th Cir. 2020) | volume, reporter, page, court, year, caseName | | docket | No. 12-3456 (S.D.N.Y. 2024) | docketNumber, court, year, caseName | | statute | 42 U.S.C. § 1983(a)(1) | title, code, section, subsection, jurisdiction | | constitutional | U.S. Const. amend. XIV, § 1 | jurisdiction, amendment, section, clause | | journal | 123 Harv. L. Rev. 456 | volume, journal, page, year | | neutral | 2020 WL 123456 | year, database, documentNumber | | publicLaw | Pub. L. No. 117-263 | congress, lawNumber | | federalRegister | 87 Fed. Reg. 1234 | volume, page, year | | statutesAtLarge | 136 Stat. 4459 | volume, page, year | | id | Id. at 125 | pincite, caseName (inherited) | | supra | Smith, supra, at 130 | partyName, pincite | | shortFormCase | 500 F.2d at 140 | volume, reporter, pincite, partyName |

Statute & Administrative Code Coverage

Statutes are extracted across 52 jurisdictions (50 states + DC + federal) using four pattern families:

| Family | Jurisdictions | Example | |--------|--------------|---------| | Federal | USC, CFR, USCA, prose ("section X of title Y") | 42 U.S.C. § 1983(a)(1) et seq. | | Named-code | NY (21 laws), CA (29 codes), TX (29 codes), MD (36 articles), VA, AL, MA | N.Y. Penal Law § 125.25(1)(a) | | Abbreviated-code | FL, OH, MI, UT, CO, WA, NC, GA, PA, IN, NJ, DE + 20 more states | Fla. Stat. § 775.082 | | Chapter-act | IL (ILCS), IL (Ill. Rev. Stat.) | 735 ILCS 5/2-1001 |

State-specific forms include: Alabama Code of 1940, California bare-code (Penal Code § 187), Georgia pre-1983 Code Ann., Hawaii Revised Laws (pre-1955), Idaho postfix (I.C. § N), Kansas year-edition (K.S.A. 2019 Supp.), Nebraska R.R.S. 1943, Oregon chapter-only (ORS chapter 174), Rhode Island General Laws 1956, Washington RCW chapter-postfix, West Virginia Code 1931, Wisconsin Stats. postfix, and more.

Administrative codes: NMAC (New Mexico), OAR (Oregon), COMAR (Maryland), IDAPA (Idaho), ARM (Montana).

Key Features

Case Names & Full Spans

The library backward-searches for party names and tracks full citation boundaries:

const text = "In Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc), the court held..."
const [cite] = extractCitations(text)

if (cite.type === "case") {
  cite.caseName    // "Smith v. Jones"
  cite.plaintiff   // "Smith"
  cite.defendant   // "Jones"
  cite.disposition // "en banc"
  cite.span        // covers "500 F.2d 123" (citation core)
  cite.fullSpan    // covers "Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc)"
}

Procedural prefixes recognized: In re, Ex parte, Matter of, Estate of, In the Matter of, and bankruptcy adversary captions (Spence v. Hintze (In re Hintze)). Case name search also runs on neutral/vendor citations (2020 WL 123456).

Docket Citations

Slip opinions and unreported decisions identified by docket number:

const text = "IKB Int'l, S.A. v. Wells Fargo Bank, N.A., No. 51 (N.Y. 2023)"
const [cite] = extractCitations(text)

if (cite.type === "docket") {
  cite.docketNumber // "51"
  cite.court        // "N.Y."
  cite.caseName     // "IKB Int'l, S.A. v. Wells Fargo Bank, N.A."
}

Accepts PACER colon prefixes (2:17-cv-00413), space-separated parts (18 C 7039), and prefix variants (C.A., Civ., Civil Action, Adv.).

Parallel Citations

When multiple reporters cite the same case, the library groups them automatically:

const text = "See 410 U.S. 113, 93 S. Ct. 705, 35 L. Ed. 2d 147 (1973)."
const citations = extractCitations(text)

citations[0].groupId // "410-U.S.-113"
citations[1].groupId // "410-U.S.-113" (same group)
citations[2].groupId // "410-U.S.-113" (same group)

if (citations[0].type === "case") {
  citations[0].parallelCitations
  // [{ volume: 93, reporter: 'S. Ct.', page: 705 },
  //  { volume: 35, reporter: 'L. Ed. 2d', page: 147 }]
}

Short-Form Resolution

Pass { resolve: true } to link Id., supra, and short-form case citations to their full antecedents:

const text = `Smith v. Jones, 500 F.2d 123 (2020). Id. at 125. Smith, supra, at 130.`
const citations = extractCitations(text, { resolve: true })

// Id. resolves to most recent antecedent
citations[1].resolution  // { resolvedTo: 0 }

// Id. inherits case name from antecedent
if (citations[1].type === "id") {
  citations[1].caseName   // "Smith v. Jones" (inherited)
  citations[1].plaintiff  // "Smith" (inherited)
}

The resolver supports paragraph/section/footnote scope boundaries, fuzzy party name matching via Levenshtein distance, bare-party shortform (Smith, at 12), and bracketed [supra] (Connecticut style). See the Resolution Guide for the power-user API.

Subsequent History & Dispositions

Case citations automatically extract subsequent history chains and disposition parentheticals:

const text = "Smith v. Jones, 500 F.2d 123 (9th Cir. 2020), aff'd, 600 U.S. 456 (2021)"
const [cite] = extractCitations(text)

if (cite.type === "case") {
  cite.subsequentHistoryEntries
  // [{ signal: 'affirmed', rawSignal: "aff'd", signalSpan: { ... }, order: 0 }]
}

Recognized history signals include federal (aff'd, rev'd, vacated, remanded, cert. denied, rehearing denied), Texas writ/petition history (writ refused, pet. denied), and California review history (review denied, review granted, not published, superseded by grant of review).

Dispositions extracted: en banc, per curiam, dissent, concurrence, plurality opinion, mem., with justice attribution ((Brennan, J., dissenting) → justices: ["Brennan"]).

Explanatory Parentheticals

Explanatory parentheticals following case citations are parsed and classified:

const text = '500 F.2d 123 (9th Cir. 2020) (holding that X requires Y)'
const [cite] = extractCitations(text)

if (cite.type === "case") {
  cite.parentheticals
  // [{ text: "holding that X requires Y", type: "holding" }]
}

Classification types: holding, finding, stating, noting, explaining, quoting, citing, discussing, describing, recognizing, applying, rejecting, adopting, requiring, other.

Citation Annotation

Mark up citations with HTML using template or callback modes:

import { annotate } from "eyecite-ts/annotate"

// Template mode
const result = annotate(text, citations, {
  template: { before: '<cite>', after: '</cite>' },
})

// Callback mode for custom markup
const linked = annotate(text, citations, {
  callback: (citation, surrounding) => {
    if (citation.type === "case") {
      return `<a href="/cases/${citation.volume}-${citation.page}">${citation.matchedText}</a>`
    }
    return `<span>${citation.matchedText}</span>`
  },
})

XSS auto-escape is enabled by default. Use useFullSpan: true to annotate from case name through closing parenthetical.

Confidence Scoring

Each citation carries a confidence score (0–1) based on pattern match quality, reporter validation, and metadata completeness:

const [cite] = extractCitations(text)
cite.confidence // 0.85

Scores are adjusted by reporter validation (+0.2 for known reporters, -0.3 for unknown), year plausibility, case name presence, and court identification. False positives from international reporters or implausible years get reduced to 0.1.

Citation Signals

Citations preceded by Bluebook signals are tagged:

const text = "See also Smith v. Jones, 500 F.2d 123 (2020)."
const [cite] = extractCitations(text)
cite.signal // "see also"

Recognized signals: see, see also, see generally, cf, but see, but cf, compare, accord, contra, e.g., and combined forms (see, e.g., see also, e.g., but see, e.g., cf., e.g., but cf., e.g.).

Court Inference

Case citations carry a inferredCourt field derived from the reporter series:

const [cite] = extractCitations(text)
if (cite.type === "case") {
  cite.inferredCourt
  // { level: "appellate", jurisdiction: "federal", confidence: 1.0 }
}

Component Spans

Every citation carries per-field position data for precise source mapping:

const [cite] = extractCitations(text)
if (cite.type === "case") {
  cite.spans?.volume    // { cleanStart, cleanEnd, originalStart, originalEnd }
  cite.spans?.reporter  // ...
  cite.spans?.page      // ...
  cite.spans?.court     // ...
  cite.spans?.year      // ...
  cite.spans?.caseName  // ...
}

Footnote Detection

Opt-in feature that tags citations with their footnote context and enables zone-scoped resolution:

const citations = extractCitations(text, { detectFootnotes: true })

for (const cite of citations) {
  if (cite.inFootnote) {
    console.log(`Footnote ${cite.footnoteNumber}: ${cite.matchedText}`)
  }
}

Two strategies: HTML tag scanner (<footnote>, <fn>, footnote class/id attributes) and plaintext separator detection (5+ dashes/underscores followed by numbered markers). The "footnote" scope strategy enforces zone-based isolation: Id. is strict (same zone only), supra and short-form case can cross from footnotes to body.

Structured Dates

Parentheticals with full dates return structured date objects:

const text = "500 F.3d 100 (2d Cir. Jan. 15, 2020)"
const [cite] = extractCitations(text)
if (cite.type === "case") {
  cite.date // { iso: '2020-01-15', parsed: { year: 2020, month: 1, day: 15 } }
}

Post-Extraction Utilities

The eyecite-ts/utils entry point provides composable post-processing:

import { extractCitations, isCaseCitation } from "eyecite-ts"
import { groupByCase, toBluebook, toReporterKey, getSurroundingContext } from "eyecite-ts/utils"

const citations = extractCitations(text, { resolve: true })

// Group citations by case (parallel + short-form → full)
// Requires resolved citations — pass `{ resolve: true }` to extractCitations.
const groups = groupByCase(citations)

// Format as Bluebook citation string (any Citation)
const formatted = toBluebook(citations[0])

// Get canonical reporter key for deduplication (full case citations only)
const first = citations[0]
if (isCaseCitation(first)) {
  const key = toReporterKey(first) // "500 F.2d 123"
}

// Extract surrounding sentence context (pass a {start, end} span, not the citation)
const cite = citations[0]
const ctx = getSurroundingContext(
  text,
  { start: cite.span.originalStart, end: cite.span.originalEnd },
  { maxLength: 100 },
)

Type System

All citation types use a discriminated union on the type field:

import type { Citation, FullCaseCitation, StatuteCitation } from "eyecite-ts"
import { isFullCitation, isCaseCitation, assertUnreachable } from "eyecite-ts"

// Type guards
if (isCaseCitation(citation)) {
  citation.reporter // typed as string
}

// Exhaustive switch
switch (citation.type) {
  case "case": /* ... */ break
  case "docket": /* ... */ break
  case "statute": /* ... */ break
  case "constitutional": /* ... */ break
  case "journal": /* ... */ break
  case "neutral": /* ... */ break
  case "publicLaw": /* ... */ break
  case "federalRegister": /* ... */ break
  case "statutesAtLarge": /* ... */ break
  case "id": /* ... */ break
  case "supra": /* ... */ break
  case "shortFormCase": /* ... */ break
  default: assertUnreachable(citation.type)
}

CitationOfType<'case'> extracts the subtype: CitationOfType<'case'> = FullCaseCitation. See the Type Reference for the full catalog.

Bundle Size

Four entry points for tree-shaking:

| Entry Point | Import | Size (brotli) | |-------------|--------|---------------| | Core extraction | eyecite-ts | ~37 KB | | Annotation | eyecite-ts/annotate | ~1 KB | | Post-extraction utils | eyecite-ts/utils | ~1.8 KB | | Reporter data | eyecite-ts/data | lazy-loaded |

Import only what you need — the reporter database is loaded on first use, not at import time.

Comparison with Python eyecite

Every claim verified against Python eyecite source code (May 2026).

| Capability | Python eyecite | eyecite-ts | Notes | |---|---|---|---| | Case citations | Yes | Yes | Both extract volume/reporter/page/court/year | | Docket citations | No | Yes | Slip opinions, PACER docket numbers | | Statute citations | Yes (50 states + DC + territories) | Yes (50 states + DC + federal) | Python uses reporters-db; TS uses built-in patterns | | Constitutional citations | No | Yes (U.S. + 50 states) | Dedicated type with article/amendment/section/clause | | State admin codes | No | Yes (NM, OR, MD, ID, MT) | NMAC, OAR, COMAR, IDAPA, ARM | | Journal / law review | Yes | Yes | | | Neutral (WL/LEXIS) | Yes (as case) | Yes (dedicated type) | Separate NeutralCitation with database/court split | | Short-form resolution | Yes | Yes | | | Case name extraction | Yes | Yes | Both use backward scanning; TS runs on neutral cites too | | Parallel citation linking | Partial | Yes | groupId + parallelCitations array | | Subsequent history | No | Yes | Federal, Texas writ/petition, California review signals | | Explanatory parentheticals | No | Yes | Classified by gerund (holding, finding, stating, ...) | | Justice attribution | No | Yes | (Brennan, J., dissenting) → justices + scope | | Court inference | No | Yes | Level/jurisdiction from reporter series | | Full span tracking | Yes | Yes | TS carries dual clean/original positions | | Component spans | Minimal | Yes (all fields) | Per-component position data | | Footnote detection | No | Yes | HTML + plaintext strategies | | Citation signals | No (stop words) | Yes (metadata) | Bluebook signals including combined forms | | Confidence scoring | No | Yes | Pattern quality + reporter validation | | Annotation | Yes (HTML modes) | Yes (template/callback) | XSS auto-escape on by default | | Position mapping | Yes (diff-based) | Yes (incremental) | TransformationMap during cleaning | | Type system | Class inheritance | Discriminated union | Exhaustive switch, conditional types | | Post-extraction utils | No | Yes | groupByCase, toBluebook, toReporterKey |

eyecite-ts started as a port and has diverged. Both are capable citation extractors — eyecite-ts adds docket citations, constitutional citations, subsequent history, explanatory parentheticals, footnote detection, citation signals, structured confidence scoring, court inference, rich component spans, and a TypeScript-native type system, while Python eyecite has broader statute coverage via reporters-db and a mature ecosystem.

Coming from Python eyecite? See the Migration Guide.

Architecture

Citations flow through a 4-stage pipeline: clean → tokenize → extract → resolve. Text cleaning builds a TransformationMap that tracks position shifts, so every citation carries dual coordinates (cleaned and original text). Resolution is optional and runs as a final pass.

See ARCHITECTURE.md for details.

Development

pnpm install           # Install dependencies (corepack, pnpm 10)
pnpm test              # Run tests (vitest, watch mode)
pnpm exec vitest run   # Run tests once (2,966 tests, 96 files)
pnpm typecheck         # Type-check with tsc
pnpm build             # Build (ESM + CJS + DTS)
pnpm lint              # Lint with Biome
pnpm format            # Format with Biome
pnpm size              # Check bundle size limits

Requires Node.js >= 18.0.0. See ARCHITECTURE.md for contributor orientation.

Internal Bughunt CLI

pnpm bughunt is a repo-local development tool for reproducible citation-parser bug hunting. It is intentionally private to this repository: it is not exported as a package entry point and is not installed as a public binary.

pnpm bughunt run --lane all --seed 1234 --sample 5
pnpm bughunt inspect .bughunt/latest.json --id <finding-id>
pnpm bughunt promote .bughunt/latest.json --id <finding-id>

The run command writes local artifacts under .bughunt/runs/<run-id>/ plus a .bughunt/latest.json pointer. Runs include manifest.json, findings.jsonl, cases.jsonl, events.jsonl, report.json, and summary.md; .bughunt/ is gitignored and should not be committed.

Available v1 lanes:

• corpus: runs extraction and resolution over inline smoke cases and reports crashes or performance outliers.
• invariants: checks citation/span invariants and records violations.
• mutate: uses fast-check with deterministic seeds and replay paths for generated-input failures.

promote is preview-only in v1. It prints a Vitest repro skeleton with the finding ID, original command, source context, and minimized/input text when available; it does not write files.

License

MIT

Credits

Inspired by and ported from eyecite (Python) by Free Law Project. This TypeScript implementation extends the original with docket citations, constitutional citations, subsequent history, explanatory parentheticals, footnote detection, citation signals, structured confidence scoring, court inference, parallel citation grouping, component spans, post-extraction utilities, and a discriminated-union type system.