tessl/npm-diff

A JavaScript text diff implementation based on the Myers algorithm for comparing text at different granularities.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Word Diffing

Name: tessl/npm-diff
Author: tessl

Word-level text comparison with intelligent whitespace handling and international text support. Provides two variants: standard word diffing with whitespace normalization, and word diffing that preserves all whitespace and newlines.

Capabilities

diffWords Function

Performs word-level diff with whitespace ignored in comparisons but preserved in output.

/**
 * Compare two strings at the word level with whitespace normalization
 * @param oldStr - Original string
 * @param newStr - New string to compare against  
 * @param options - Configuration options
 * @returns Array of change objects representing the diff
 */
function diffWords(oldStr, newStr, options);

Options:

interface WordDiffOptions extends DiffOptions {
  ignoreCase?: boolean;     // Treat uppercase and lowercase as equal
  intlSegmenter?: Intl.Segmenter;  // Custom word segmentation for international text
}

Usage Examples:

import { diffWords } from "diff";

// Basic word diff
const result = diffWords("hello world", "hello universe");
console.log(result);
// [
//   { value: "hello ", count: 1 },
//   { value: "world", removed: true, count: 1 },
//   { value: "universe", added: true, count: 1 }
// ]

// Case-insensitive comparison
const caseResult = diffWords("Hello World", "hello WORLD", { ignoreCase: true });
// Treats different cases as equal

// International text with Intl.Segmenter
const segmenter = new Intl.Segmenter('zh', { granularity: 'word' });
const chineseResult = diffWords("你好世界", "你好宇宙", { intlSegmenter: segmenter });

diffWordsWithSpace Function

Performs word-level diff preserving all whitespace and newlines as separate tokens.

/**
 * Compare two strings at the word level preserving whitespace and newlines
 * @param oldStr - Original string
 * @param newStr - New string to compare against
 * @param options - Configuration options  
 * @returns Array of change objects representing the diff
 */
function diffWordsWithSpace(oldStr, newStr, options);

Usage Examples:

import { diffWordsWithSpace } from "diff";

// Preserves exact whitespace
const result = diffWordsWithSpace("hello  world\n", "hello   world\n");
// Will show whitespace differences

// Newlines as separate tokens
const newlineResult = diffWordsWithSpace("line1\nline2", "line1\n\nline2");
// Shows the added newline as a separate change

wordDiff Instance

Pre-configured Diff instance for word-level comparisons with custom tokenization.

/**
 * Pre-configured word diff instance with custom tokenization and equality
 * Includes intelligent whitespace handling and token joining
 */
const wordDiff: Diff;

wordWithSpaceDiff Instance

Pre-configured Diff instance for word-level comparisons that preserves whitespace.

/**
 * Pre-configured word diff instance that treats newlines as separate tokens
 * Preserves all whitespace in the comparison
 */
const wordWithSpaceDiff: Diff;

Advanced Usage

International Text Support

import { diffWords } from "diff";

// Swedish text with language-specific rules
const swedishSegmenter = new Intl.Segmenter('sv', { granularity: 'word' });
const result = diffWords("k:a hus", "kyrka hus", { 
  intlSegmenter: swedishSegmenter 
});

// Chinese text segmentation
const chineseSegmenter = new Intl.Segmenter('zh', { granularity: 'word' });
const chineseResult = diffWords("北京大学", "清华大学", { 
  intlSegmenter: chineseSegmenter 
});

Whitespace Handling Comparison

import { diffWords, diffWordsWithSpace } from "diff";

const oldText = "hello  world";
const newText = "hello   world";  // Extra space

// Standard word diff (whitespace normalized)
const normalized = diffWords(oldText, newText);
// May show no differences due to whitespace normalization

// Preserving whitespace
const preserved = diffWordsWithSpace(oldText, newText);  
// Will show the whitespace difference

Custom Word Boundaries

import { wordDiff } from "diff";

// Using the base wordDiff instance directly
const customResult = wordDiff.diff("custom-word_text", "custom word text");

// Async with custom instance
wordDiff.diff(longText1, longText2, (result) => {
  console.log("Custom word diff completed:", result);
});

Performance Optimization

import { diffWords } from "diff";

// For very large texts
const result = diffWords(largeText1, largeText2, {
  maxEditLength: 10000,  // Limit edit distance calculation
  timeout: 10000,        // 10 second timeout
  callback: (result) => {
    if (result) {
      console.log("Word diff completed within limits");
    } else {
      console.log("Word diff exceeded computation limits");
    }
  }
});

Error Handling

import { diffWords } from "diff";

// Handle invalid Intl.Segmenter
try {
  const invalidSegmenter = new Intl.Segmenter('en', { granularity: 'sentence' });
  diffWords("text", "text", { intlSegmenter: invalidSegmenter });
} catch (error) {
  console.error("Segmenter must have granularity of 'word':", error.message);
}

Install with Tessl CLI