### Clone Repository and Install Dependencies

Source: https://github.com/beshkenadze/eyecite-js/blob/main/CONTRIBUTING.md

Steps to clone the eyecite-js repository and install project dependencies using Bun.

```bash
git clone https://github.com/your-username/eyecite-js.git
cd eyecite-js
bun install
```

--------------------------------

### Install eyecite-js with Bun

Source: https://github.com/beshkenadze/eyecite-js/blob/main/README.md

Installs the eyecite-js package using the Bun package manager. This is the recommended method for installation.

```bash
bun add @beshkenadze/eyecite
```

--------------------------------

### Login to npm

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/PUBLISHING.md

Logs the user into their npm account. This is a prerequisite for publishing packages.

```bash
npm login
```

--------------------------------

### Build and Test Package

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/PUBLISHING.md

Builds the project and runs tests using Bun. Ensures the package is ready for publishing.

```bash
bun run build
bun test
```

--------------------------------

### Publish Package to npm

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/PUBLISHING.md

Publishes the package to the npm registry with public access. Can be executed using npm or Bun.

```bash
npm publish --access public
bunx npm publish --access public
```

--------------------------------

### Conventional Commits for Semantic Release

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/PUBLISHING.md

Defines the commit message conventions used by semantic-release to automate version bumping and publishing.

```bash
# Use conventional commits:
# fix: ... -> patch release
# feat: ... -> minor release
# BREAKING CHANGE: ... -> major release
```

--------------------------------

### Install eyecite-js from GitHub Packages

Source: https://github.com/beshkenadze/eyecite-js/blob/main/README.md

Provides instructions for configuring npm to use GitHub Packages and installing eyecite-js directly from the GitHub registry.

```bash
# Configure registry (one-time setup)

```

```bash
npm config set @beshkenadze:registry https://npm.pkg.github.com

```

```bash
# Install from GitHub Packages

```

```bash
npm install @beshkenadze/eyecite

```

```bash
# Or install directly

```

```bash
npm install @beshkenadze/eyecite --registry=https://npm.pkg.github.com
```

--------------------------------

### Installation Command for eyecite-js

Source: https://github.com/beshkenadze/eyecite-js/blob/main/RELEASE_NOTES_v2.7.6-alpha.21.md

Provides the npm command to install version 2.7.6-alpha.21 of the eyecite-js library.

```bash
npm install @beshkenadze/eyecite@2.7.6-alpha.21
```

--------------------------------

### Set NPM_TOKEN for GitHub Actions

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/PUBLISHING.md

Instructions for setting up the NPM_TOKEN as a repository secret in GitHub Actions to enable automated publishing.

```bash
# Go to https://www.npmjs.com/settings/[your-username]/tokens
# Create an "Automation" token
# Add to GitHub repository: Settings -> Secrets -> Actions -> New repository secret
# Name: NPM_TOKEN
# Value: Your npm token
```

--------------------------------

### Install Specific Versions from npm Registry

Source: https://github.com/beshkenadze/eyecite-js/blob/main/README.md

Demonstrates how to install specific versions of eyecite-js, including stable, alpha, and beta releases, from the npm registry.

```bash
# Latest stable version

```

```bash
npm install @beshkenadze/eyecite

```

```bash
# Alpha version

```

```bash
npm install @beshkenadze/eyecite@alpha

```

```bash
# Beta version  

```

```bash
npm install @beshkenadze/eyecite@beta
```

--------------------------------

### Install eyecite-js with npm

Source: https://github.com/beshkenadze/eyecite-js/blob/main/README.md

Installs the eyecite-js package using the npm package manager. This is a standard method for Node.js projects.

```bash
npm install @beshkenadze/eyecite
```

--------------------------------

### Example Test Case for Citation Extraction

Source: https://github.com/beshkenadze/eyecite-js/blob/main/CONTRIBUTING.md

An example test written in TypeScript using Bun's testing utilities to verify the extraction of a full case citation.

```typescript
import { test, expect } from "bun:test"
import { getCitations } from "../src"

test("should extract full case citation", () => {
  const text = "Bush v. Gore, 531 U.S. 98 (2000)"
  const citations = getCitations(text)
  
  expect(citations).toHaveLength(1)
  expect(citations[0].constructor.name).toBe("FullCaseCitation")
})
```

--------------------------------

### TODO Comment for Porting Incomplete Features

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Example of using a TODO comment in TypeScript to mark features that need to be implemented during the porting process, referencing the original Python function.

```typescript
// TODO: Implement when porting helpers module
// Python: add_law_metadata(self, document.words)
```

--------------------------------

### Update Package Version

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/PUBLISHING.md

Updates the version of the package.json file using Bun. Supports patch, minor, and major version bumps.

```bash
bun version patch  # for bug fixes
bun version minor  # for new features
bun version major  # for breaking changes
```

--------------------------------

### Push Git Tag

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/PUBLISHING.md

Pushes the main branch and a specific version tag to the git repository. The tag can trigger CI/CD workflows.

```bash
git push origin main
git push origin v2.7.6  # replace with your version
```

--------------------------------

### Install eyecite-js with pnpm

Source: https://github.com/beshkenadze/eyecite-js/blob/main/README.md

Installs the eyecite-js package using the pnpm package manager. pnpm is known for its efficient disk space usage and speed.

```bash
pnpm add @beshkenadze/eyecite
```

--------------------------------

### Check npm Login Status

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/PUBLISHING.md

Verifies if the user is currently logged into npm.

```bash
npm whoami
```

--------------------------------

### Pattern Options for addSimpleCitationPattern

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Describes the available options that can be passed when using the `addSimpleCitationPattern` method to customize how citation patterns are interpreted.

```APIDOC
PatternOptions:
  yearPageFormat: boolean
    Use year-page format instead of volume-reporter-page. Defaults to false.

  hyphenFormat: boolean
    Use hyphen-separated format (volume-reporter-page). Defaults to false.

  caseSensitive: boolean
    Whether the pattern should be case-sensitive. Defaults to false.

  editionStr: string
    Custom edition string to use. Defaults to 'ed.'.
```

--------------------------------

### Exception Handling in Python and TypeScript

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Demonstrates the equivalent try-except and try-catch blocks for handling exceptions in Python and TypeScript.

```python
try:
    result = process()
except ValueError:
    return None
```

```typescript
try {
  const result = process()
} catch (error) {
  return null
}
```

--------------------------------

### Tokenizer API Reference

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Provides a reference for the core methods available on the Tokenizer object for managing and manipulating citation extractors.

```APIDOC
Tokenizer Methods:

- `addExtractor(extractor: TokenExtractor): void`
  Adds a single `TokenExtractor` to the tokenizer.

- `addExtractors(extractors: TokenExtractor[]): void`
  Adds an array of `TokenExtractor` objects to the tokenizer.

- `removeExtractor(extractor: TokenExtractor): boolean`
  Removes a specific `TokenExtractor` from the tokenizer. Returns `true` if removed, `false` otherwise.

- `removeExtractors(predicate: (extractor: TokenExtractor) => boolean): number`
  Removes all `TokenExtractor` objects that satisfy the provided predicate function. Returns the number of extractors removed.

- `clearExtractors(): void`
  Removes all `TokenExtractor` objects from the tokenizer.

- `setExtractors(extractors: TokenExtractor[]): void`
  Replaces all existing extractors with the provided array of `TokenExtractor` objects.

- `getExtractorsCopy(): TokenExtractor[]`
  Returns a shallow copy of the current array of `TokenExtractor` objects.

- `modifyExtractorPatterns(modifier: (regex: string, extractor: TokenExtractor) => string, filter?: (extractor: TokenExtractor) => boolean): void`
  Applies a modification function to the regex patterns of extractors. An optional filter can be provided to target specific extractors.

- `findExtractorsByPattern(pattern: string | RegExp): TokenExtractor[]`
  Finds and returns all `TokenExtractor` objects whose patterns match the given string or regular expression.

- `findExtractorsByString(searchString: string): TokenExtractor[]`
  Finds and returns all `TokenExtractor` objects that have the specified string in their `strings` array.
```

--------------------------------

### Tokenizer Cloning and Filtering

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Illustrates how to clone an existing tokenizer and create a filtered version based on specific criteria, demonstrating the management of extractors.

```typescript
const tokenizer = new CustomTokenizer()
tokenizer.addMultipleReporters([
  { pattern: 'Keep' },
  { pattern: 'Remove' }
])

// Clone the tokenizer
const cloned = tokenizer.clone()

// Create a filtered version
const filtered = tokenizer.createFilteredTokenizer(
  extractor => extractor.strings?.includes('Keep') || false
)

console.log(tokenizer.extractors.length) // 2
console.log(filtered.extractors.length)  // 1
```

--------------------------------

### Install eyecite-js with Yarn

Source: https://github.com/beshkenadze/eyecite-js/blob/main/README.md

Installs the eyecite-js package using the Yarn package manager. Yarn is another popular package manager for JavaScript.

```bash
yarn add @beshkenadze/eyecite
```

--------------------------------

### Example Bump Version Session

Source: https://github.com/beshkenadze/eyecite-js/blob/main/scripts/README.md

Illustrates an interactive session with the version bumping tool, showing prompts for version type, confirmation, Git integration steps, build process, and NPM publishing.

```bash
📦 Version Bump Tool
Current version: 2.7.6-alpha.26

Choose version bump type:
  1) Patch  (bug fixes)           → 2.7.7
  2) Minor  (new features)        → 2.8.0
  3) Major  (breaking changes)    → 3.0.0
  4) Prerelease (increment)       → 2.7.6-alpha.27
  7) Custom (specify version)
  0) Cancel

Enter your choice (0-7): 4

New version will be: 2.7.6-alpha.27

Do you want to proceed? (y/n): y
✓ Updated package.json

Do you want to commit and tag? (y/n): y
✓ Staged package.json
✓ Created commit
✓ Created tag: v2.7.6-alpha.27

Do you want to push to remote? (y/n): y
✓ Pushed commits
✓ Pushed tags

Do you want to build the package? (y/n): y
Building package...
✓ Build complete

Do you want to publish to npm? (y/n): n

✨ Version bump complete!
Version changed from 2.7.6-alpha.26 to 2.7.6-alpha.27
```

--------------------------------

### Tokenizer Base Class Methods

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Demonstrates adding, removing, finding, and modifying extractors within the base Tokenizer class.

```typescript
import { Tokenizer, BaseTokenExtractor, CitationToken } from 'eyecite'

const tokenizer = new Tokenizer()

// Add extractors
tokenizer.addExtractor(extractor)
tokenizer.addExtractors([extractor1, extractor2])

// Remove extractors
tokenizer.removeExtractor(extractor)
tokenizer.removeExtractors(ext => ext.strings?.includes('pattern'))

// Modify patterns
tokenizer.modifyExtractorPatterns(
  (regex) => regex.replace('old', 'new'),
  (extractor) => extractor.strings?.includes('target')
)

// Find extractors
const found = tokenizer.findExtractorsByPattern(/pattern/)
const byString = tokenizer.findExtractorsByString('searchTerm')
```

--------------------------------

### RegexPatternBuilder Utilities

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Showcases the use of RegexPatternBuilder for creating flexible and complex regular expression patterns, including handling alternative punctuation and optional components like years.

```typescript
import { RegexPatternBuilder } from 'eyecite'

// Create flexible reporter patterns
const flexibleReporter = RegexPatternBuilder.flexibleReporter(
  ['U', 'S'], 
  '[.,\s]'  // Allows "U.S.", "U,S,", "U S", etc.
)

// Handle alternative punctuation
const altPattern = RegexPatternBuilder.withAlternativePunctuation(
  'U.S. Reports',
  { '.': '[.,]', ' ': '\s+' }
)

// Create optional patterns
const optionalYear = RegexPatternBuilder.optional(
  '\(' + RegexPatternBuilder.yearPattern() + '\)'
)

// Build page patterns with ranges and Roman numerals
const pagePattern = RegexPatternBuilder.pagePattern(true, true)
// Results in: (?:\d+|[ivxlcdm]+)(?:-(?:\d+|[ivxlcdm]+))?
```

--------------------------------

### Extractor Statistics

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Shows how to retrieve statistics about the tokenizers' extractors, including total count, those with string hints, and a breakdown by token type.

```typescript
const stats = tokenizer.getExtractorStats()

console.log('Total extractors:', stats.total)
console.log('With string hints:', stats.withStrings)
console.log('Without string hints:', stats.withoutStrings)
console.log('By token type:', stats.byTokenType)
```

--------------------------------

### Performance Optimization with String-Based Filtering

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Explains and demonstrates the `AhocorasickTokenizer`'s performance optimization, where only extractors with matching string hints are processed.

```typescript
import { AhocorasickTokenizer } from 'eyecite'

const tokenizer = new AhocorasickTokenizer()

// Add extractors with string hints
tokenizer.addSimpleCitationPattern('U.S.', 'federal', 'United States Reports')
tokenizer.addSimpleCitationPattern('F.2d', 'federal', 'Federal Reporter')

// Only relevant extractors will be used
const text1 = 'Text with U.S. citation'  // Only U.S. extractor runs
const text2 = 'Text with F.2d citation' // Only F.2d extractor runs
```

--------------------------------

### CustomTokenizer: Adding Simple Citation Patterns

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Shows how to add various simple citation patterns, including year-page and hyphen formats, and multiple reporters using CustomTokenizer.

```typescript
import { CustomTokenizer } from 'eyecite'

const tokenizer = new CustomTokenizer()

// Add simple citation patterns
tokenizer.addSimpleCitationPattern('CustomRep', 'neutral', 'Custom Reporter')

// Add year-page format (e.g., "T.C. Memo. 2019-233")
tokenizer.addSimpleCitationPattern(
  'T.C. Memo.',
  'tax',
  'Tax Court Memorandum',
  { yearPageFormat: true }
)

// Add hyphen format (e.g., "1-NMCERT-123")
tokenizer.addSimpleCitationPattern(
  'CUSTOM',
  'neutral',
  'Custom Hyphen Reporter',
  { hyphenFormat: true }
)

// Add multiple reporters at once
tokenizer.addMultipleReporters([
  { pattern: 'Rep1', name: 'Reporter One' },
  { pattern: 'Rep2', name: 'Reporter Two', citeType: 'state' }
])
```

--------------------------------

### Basic Usage: Creating Custom Extractors

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Shows how to create a custom extractor with a specific regex pattern, CitationToken, and additional data or string hints for filtering.

```typescript
import { CustomTokenizer, CitationToken } from 'eyecite'

const tokenizer = new CustomTokenizer()

// Create a custom extractor with specific regex
tokenizer.addCustomExtractor(
  '(?<type>STATUTE)\s+(?<section>§\s*\d+(?:\.\d+)*)',
  CitationToken,
  { citationType: 'statute' },    // Extra data
  { strings: ['STATUTE', '§'] }   // String hints for filtering
)

const text = 'See STATUTE § 123.45 for reference.'
const citations = getCitations(text, false, tokenizer)
```

--------------------------------

### Hyphen Format Citations

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Illustrates the configuration for handling citations using a hyphen format, enabling the extraction of volume, reporter, and page information.

```typescript
const tokenizer = new CustomTokenizer()

tokenizer.addSimpleCitationPattern(
  'NMCERT',
  'state',
  'New Mexico Certification',
  { hyphenFormat: true }
)

// Matches "1-NMCERT-123"
const citations = getCitations('1-NMCERT-123', false, tokenizer)
console.log(citations[0].groups.volume)   // "1"
console.log(citations[0].groups.reporter) // "NMCERT"
console.log(citations[0].groups.page)     // "123"
```

--------------------------------

### CustomTokenizer Methods

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Methods for customizing the behavior of the CustomTokenizer, allowing for the addition of citation patterns, custom regex extractors, and modification of punctuation rules.

```APIDOC
CustomTokenizer:
  addSimpleCitationPattern(reporterPattern: string, citeType?: string, reporterName?: string, options?: object): TokenExtractor
    Adds a simple citation pattern to the tokenizer.
    Parameters:
      reporterPattern: The regex pattern for the reporter.
      citeType: The type of citation (optional).
      reporterName: The name of the reporter (optional).
      options: Additional options for the pattern (optional).
    Returns: The updated TokenExtractor.

  addCustomExtractor(regex: string, tokenConstructor: typeof Token, extra?: object, options?: object): TokenExtractor
    Adds a custom extractor defined by a regex and a token constructor.
    Parameters:
      regex: The regular expression for the extractor.
      tokenConstructor: The constructor function for the token.
      extra: Additional data for the extractor (optional).
      options: Additional options for the extractor (optional).
    Returns: The updated TokenExtractor.

  modifyReporterPunctuation(originalChar: string, replacement: string): void
    Modifies the punctuation used for reporter names.
    Parameters:
      originalChar: The original punctuation character.
      replacement: The character to replace it with.

  addMultipleReporters(reporters: Array<{pattern: string, name?: string, citeType?: string, options?: object}>): TokenExtractor[]
    Adds multiple reporters to the tokenizer.
    Parameters:
      reporters: An array of reporter objects, each with a pattern and optional properties.
    Returns: An array of updated TokenExtractors.

  clone(): CustomTokenizer
    Creates a deep clone of the current CustomTokenizer instance.
    Returns: A new CustomTokenizer instance with the same configuration.

  createFilteredTokenizer(predicate: (extractor: TokenExtractor) => boolean): CustomTokenizer
    Creates a new tokenizer containing only extractors that satisfy the given predicate.
    Parameters:
      predicate: A function that returns true if an extractor should be included.
    Returns: A new CustomTokenizer instance with filtered extractors.

  getExtractorStats(): {total: number, withStrings: number, withoutStrings: number, byTokenType: Record<string, number>}
    Retrieves statistics about the extractors currently in the tokenizer.
    Returns: An object containing counts of total extractors, extractors with/without strings, and a breakdown by token type.
```

--------------------------------

### RegexPatternBuilder Methods

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Static methods for constructing complex regular expression patterns used in citation parsing, including handling punctuation, reporters, years, and page numbers.

```APIDOC
RegexPatternBuilder:
  static withAlternativePunctuation(base: string, charMap: Record<string, string>): string
    Builds a pattern by replacing specific characters in a base string with alternatives defined in a map.
    Parameters:
      base: The base pattern string.
      charMap: A record mapping characters to their alternative representations.
    Returns: A new pattern string with alternative punctuation.

  static flexibleReporter(reporterParts: string[], separators?: string): string
    Constructs a flexible reporter pattern from an array of parts, allowing for optional separators.
    Parameters:
      reporterParts: An array of strings representing parts of the reporter name.
      separators: Optional string of characters to use as separators.
    Returns: A regex pattern for a flexible reporter.

  static optional(pattern: string, greedy?: boolean): string
    Wraps a pattern in a non-capturing group and makes it optional.
    Parameters:
      pattern: The pattern to make optional.
      greedy: Whether the quantifier should be greedy (default: false).
    Returns: An optional pattern string.

  static yearPattern(allowPartialYears?: boolean): string
    Generates a regex pattern for matching years, with an option to allow partial years.
    Parameters:
      allowPartialYears: Whether to allow patterns like '99' for years (default: false).
    Returns: A regex pattern for years.

  static volumePattern(): string
    Generates a regex pattern for matching citation volumes.
    Returns: A regex pattern for volumes.

  static pagePattern(allowRanges?: boolean, allowRoman?: boolean): string
    Generates a regex pattern for matching citation page numbers, supporting ranges and Roman numerals.
    Parameters:
      allowRanges: Whether to allow page ranges (e.g., '10-15') (default: false).
      allowRoman: Whether to allow Roman numerals for page numbers (default: false).
    Returns: A regex pattern for page numbers.
```

--------------------------------

### AhocorasickTokenizer Usage

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Illustrates the usage of AhocorasickTokenizer for performance-optimized string-based filtering, noting that extractor management methods are the same as the base Tokenizer.

```typescript
import { AhocorasickTokenizer } from 'eyecite'

const tokenizer = new AhocorasickTokenizer()

// All extractor management methods work the same way
tokenizer.addExtractor(extractor)

// But filtering is optimized based on string hints in the text
const relevantExtractors = tokenizer.getExtractors(text)
```

--------------------------------

### Year-Page Format Citations

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Demonstrates how to configure a tokenizer to handle citations in a year-page format, extracting the year and page number correctly.

```typescript
const tokenizer = new CustomTokenizer()

tokenizer.addSimpleCitationPattern(
  'T.C. Memo.',
  'tax',
  'Tax Court Memorandum',
  { yearPageFormat: true }
)

// Matches "T.C. Memo. 2019-233"
const citations = getCitations('T.C. Memo. 2019-233', false, tokenizer)
console.log(citations[0].groups.volume) // "2019"
console.log(citations[0].groups.page)   // "233"
```

--------------------------------

### Token Merging Logic in TypeScript

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Shows the TypeScript implementation for token merging, using strict equality for constructor comparison.

```typescript
if (this.constructor === other.constructor) {
  // merge logic
}
```

--------------------------------

### Basic Usage: Adding Custom Citation Patterns with getCitations

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Demonstrates adding a custom reporter using CustomTokenizer and then using it with the getCitations function to extract citation details.

```typescript
import { CustomTokenizer, getCitations } from 'eyecite'

const tokenizer = new CustomTokenizer()

// Add a custom reporter
tokenizer.addSimpleCitationPattern('MyRep', 'neutral', 'My Custom Reporter')

// Use with getCitations
const text = 'See 123 MyRep 456 for details.'
const citations = getCitations(text, false, tokenizer)

console.log(citations[0].groups.volume)   // "123"
console.log(citations[0].groups.reporter) // "MyRep"
console.log(citations[0].groups.page)     // "456"
```

--------------------------------

### Multiple Citation Types

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Shows how to add multiple reporters with different citation types and options, including hyphen format, and then extract them from text.

```typescript
const tokenizer = new CustomTokenizer()

tokenizer.addMultipleReporters([
  { pattern: 'CustomFed', citeType: 'federal' },
  { pattern: 'CustomState', citeType: 'state' },
  { pattern: 'CustomNeutral', citeType: 'neutral' },
  { 
    pattern: 'CustomHyphen', 
    citeType: 'neutral',
    options: { hyphenFormat: true }
  }
])

const text = `
  See 1 CustomFed 10, 2 CustomState 20, 3 CustomNeutral 30,
  and 4-CustomHyphen-40 for references.
`

const citations = getCitations(text, false, tokenizer)
console.log(`Found ${citations.length} citations`)
```

--------------------------------

### Hash Function Implementation

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Compares the hash function implementations in Python using `hashlib.sha256` and in TypeScript using Node.js `crypto.createHash('sha256')`.

```python
hashlib.sha256
```

```javascript
crypto.createHash('sha256')
```

--------------------------------

### Custom Tokenizer with Alternative Punctuation

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Demonstrates how to create a custom tokenizer, add a simple citation pattern, and modify it to accept alternative punctuation, such as replacing dots with a character class.

```typescript
const tokenizer = new CustomTokenizer()

// Add a pattern and then modify it to accept alternative punctuation
const extractor = tokenizer.addSimpleCitationPattern('Test.Rep', 'neutral', 'Test Reporter')

// Use the convenience method to replace dots with character class
tokenizer.modifyReporterPunctuation('.', '[.,]')

// Update string hints if needed
if (extractor.strings?.includes('Test.Rep')) {
  extractor.strings.push('Test,Rep')
}
```

--------------------------------

### Python Dictionary/Object Creation to TypeScript

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Converts Python dictionary creation and assignment patterns to their TypeScript equivalents, including handling optional group data from regex matches.

```python
groups = m.groupdict()
metadata = {"year": year, "court": court}
```

```typescript
const groups: Record<string, string | undefined> = {}
if (match.groups) {
  Object.assign(groups, match.groups)
}
const metadata = { year, court }
```

--------------------------------

### Advanced Features: Pattern Modification

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/TOKENIZER_EXTENSIBILITY.md

Illustrates how to modify existing citation patterns to accept alternative formats, such as using commas instead of periods.

```typescript
const tokenizer = new CustomTokenizer()
tokenizer.addSimpleCitationPattern('U.S.', 'federal', 'United States Reports')

// Modify pattern to accept commas instead of periods
tokenizer.modifyExtractorPatterns(
  (regex) => regex.replace('U\.S\.', 'U[.,]S[.,]'),
  (extractor) => extractor.strings?.includes('U.S.') || false
)

// Now matches both "123 U.S. 456" and "123 U,S, 456"
```

--------------------------------

### Python Imports to TypeScript Imports

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Illustrates the conversion of Python import statements to TypeScript's ES module import syntax. It also shows how to handle type-only imports in TypeScript.

```python
from eyecite.models import Token, CitationBase
from typing import Optional, List
```

```typescript
import { Token, CitationBase } from './models'
import type { Token as TokenType } from './models'  // for type-only imports
```

--------------------------------

### Update TypeScript Method Signatures

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/UPDATE_GUIDE.md

Provides examples of updating TypeScript method signatures to match Python method signatures, including optional parameters and return types.

```python
from typing import List

def process(self, text: str, clean_steps: List[str] = None) -> List[Citation]:
    pass
```

```typescript
process(text: string, cleanSteps?: string[]): Citation[]
```

--------------------------------

### Run Tests and Linter

Source: https://github.com/beshkenadze/eyecite-js/blob/main/CONTRIBUTING.md

Commands to execute the test suite and run the linter for the eyecite-js project.

```bash
bun test
bun run lint
```

--------------------------------

### Development Workflow: Branching and Committing

Source: https://github.com/beshkenadze/eyecite-js/blob/main/CONTRIBUTING.md

Demonstrates the workflow for creating a new feature branch, making changes, and committing them following Conventional Commits.

```bash
git checkout -b feature/your-feature-name
git add .
git commit -m "feat: add new citation type support"
```

--------------------------------

### Run Specific Test Case with Bun

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/MARKUP_TEST_STATUS.md

Demonstrates how to execute a specific passing test case using the 'bun test' command, targeting the basic functionality test for HTML markup extraction.

```bash
# Run the passing basic functionality test
bun test --testNamePattern="should extract citations from HTML markup text \(basic functionality\)"
```

--------------------------------

### Fetch and View Python Repository Changes

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/UPDATE_GUIDE.md

Commands to fetch the latest changes from the Python eyecite repository's main branch and view the commit history and detailed differences.

```bash
git fetch origin
git log --oneline HEAD..origin/main
```

```bash
git diff HEAD..origin/main
```

--------------------------------

### Testing Commands

Source: https://github.com/beshkenadze/eyecite-js/blob/main/README.md

Provides commands for running tests, including running all tests, specific files, and in watch mode.

```bash
# Run all tests
bun test

# Run specific test file
bun test find.test.ts

# Run tests in watch mode
bun test --watch
```

--------------------------------

### Run All Markup Tests

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/MARKUP_TEST_STATUS.md

Executes all markup tests, including those that are skipped. This command is useful for a comprehensive test run.

```bash
bun test --testNamePattern="Markup Plaintiff and Antecedent Guesses"
```

--------------------------------

### Python List Comprehension to TypeScript Filter

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Transforms a Python list comprehension used for filtering elements based on a condition into a TypeScript `filter` array method.

```python
editions = [e for e in editions if e.includes_year(year)]
```

```typescript
const editions = editions.filter(e => includesYear(e, year))
```

--------------------------------

### Python f-string to TypeScript Template Literal

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Demonstrates the direct conversion of Python's f-string formatting to TypeScript's template literals for string interpolation.

```python
f"{plaintiff} v. {defendant}, {citation}"
```

```typescript
`${plaintiff} v. ${defendant}, ${citation}`
```

--------------------------------

### Run TypeScript Project Tests and Checks

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/UPDATE_GUIDE.md

Commands to execute tests, perform type checking, and run linters on the TypeScript eyecite-js project.

```bash
bun test
```

```bash
bun run typecheck
```

```bash
bun run check
```

--------------------------------

### Python to TypeScript Collection Operations

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/QUICK_REFERENCE.md

Demonstrates the conversion of Python list comprehensions, dictionary access with defaults, checking key existence, and getting collection length to TypeScript.

```python
[x for x in list if x > 0] → list.filter(x => x > 0)
[x * 2 for x in list] → list.map(x => x * 2)
dict.get('key', default) → dict.key ?? default
'key' in dict → 'key' in dict || dict.hasOwnProperty('key')
len(list) → list.length
```

--------------------------------

### API Usage: Basic Id. Citation

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/ID_RESOLUTION_DESIGN.md

Example demonstrating how to use the `getCitations` and `resolveCitations` functions with a basic 'Id.' citation, showing that it resolves to the same resource as the preceding citation.

```typescript
const text = "See 42 U.S.C. § 1983. Id. provides a cause of action."
const citations = getCitations(text)
const resolved = resolveCitations(citations)
// citations[1] (Id.) resolves to the same resource as citations[0] (42 U.S.C. § 1983)
```

--------------------------------

### API Usage: Id. with Different Section

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/ID_RESOLUTION_DESIGN.md

Example showing an 'Id.' citation with a section number, illustrating that it resolves to the same law but a different section, as handled by the enhanced algorithm.

```typescript
const text = "See 42 U.S.C. § 1983. Id. § 1985 addresses conspiracies."
const citations = getCitations(text)
const resolved = resolveCitations(citations)
// citations[1] (Id. § 1985) resolves to the same U.S.C. title but different section
```

--------------------------------

### Python to TypeScript Class Syntax

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/QUICK_REFERENCE.md

Details the translation of Python class definitions, constructors, instance variables, properties, static methods, and superclass calls to TypeScript.

```python
class A: → class A {
    def __init__(self): → constructor() {
    self.x = 1 → this.x = 1
    @property → get x() {
    @staticmethod → static method() {
    super().__init__() → super()
```

--------------------------------

### Bump Version Script Usage

Source: https://github.com/beshkenadze/eyecite-js/blob/main/scripts/README.md

Provides commands to run the interactive version bumping tool or specific bump types (patch, minor, major) using bun.

```bash
bun run bump
bun run bump:patch
bun run bump:minor
bun run bump:major
```

--------------------------------

### Unique Object Identity Generation

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Illustrates how unique object identities are generated in Python using `id(self)` and in TypeScript using a combination of timestamp and random number.

```python
id(self)
```

```typescript
`unique-${Date.now()}-${Math.random()}`
```

--------------------------------

### Python Property to TypeScript Getter

Source: https://github.com/beshkenadze/eyecite-js/blob/main/docs/porting/PORTING_GUIDE.md

Converts a Python property that lazily compiles a regular expression into a TypeScript getter. The TypeScript version handles flag conversion and memoization.

```python
import re

class RegexMatcher:
    def __init__(self, regex, flags=0):
        self.regex = regex
        self.flags = flags

    @property
    def compiled_regex(self):
        if not hasattr(self, "_compiled_regex"):
            self._compiled_regex = re.compile(self.regex, flags=self.flags)
        return self._compiled_regex
```

```typescript
class RegexMatcher {
  private _compiledRegex?: RegExp
  regex: string
  flags: number

  constructor(regex: string, flags: number = 0) {
    this.regex = regex
    this.flags = flags
  }

  get compiledRegex(): RegExp {
    if (!this._compiledRegex) {
      let jsFlags = 'g'
      if (this.flags & 2) jsFlags += 'i'
      this._compiledRegex = new RegExp(this.regex, jsFlags)
    }
    return this._compiledRegex
  }
}
```