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

Line Diffing

Name: tessl/npm-diff
Author: tessl

Line-by-line text comparison with configurable whitespace and newline handling. Essential for code diffs, file comparisons, and text processing where line boundaries are significant.

Capabilities

diffLines Function

Performs line-level diff between two strings, treating each line as a token.

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

Options:

interface LineDiffOptions extends DiffOptions {
  ignoreWhitespace?: boolean;    // Ignore leading/trailing whitespace on lines
  ignoreNewlineAtEof?: boolean;  // Ignore missing newline at end of file
  stripTrailingCr?: boolean;     // Remove \r before \n for cross-platform compatibility
  newlineIsToken?: boolean;      // Treat newlines as separate tokens
}

Usage Examples:

import { diffLines } from "diff";

// Basic line diff
const result = diffLines(
  "line1\nline2\nline3", 
  "line1\nmodified line2\nline3"
);
console.log(result);
// [
//   { value: "line1\n", count: 1 },
//   { value: "line2\n", removed: true, count: 1 },
//   { value: "modified line2\n", added: true, count: 1 },
//   { value: "line3", count: 1 }
// ]

// Ignore whitespace differences
const whitespaceResult = diffLines(
  "  indented line  \n",
  "indented line\n",
  { ignoreWhitespace: true }
);
// No differences detected due to whitespace normalization

// Cross-platform line endings
const crossPlatform = diffLines(
  "line1\r\nline2\r\n",  // Windows endings
  "line1\nline2\n",      // Unix endings  
  { stripTrailingCr: true }
);
// Treats both formats as equivalent

diffTrimmedLines Function

Convenience function that performs line diff with whitespace ignored (deprecated wrapper).

/**
 * Line diff with whitespace ignored (deprecated - use diffLines with ignoreWhitespace)
 * @param oldStr - Original string
 * @param newStr - New string to compare against
 * @param callback - Optional callback for async operation
 * @returns Array of change objects representing the diff
 * @deprecated Use diffLines with { ignoreWhitespace: true } instead
 */
function diffTrimmedLines(oldStr, newStr, callback);

lineDiff Instance

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

/**
 * Pre-configured line diff instance with line-aware tokenization
 * Handles line breaks and line-based equality checking
 */
const lineDiff: Diff;

Advanced Usage

Newline Handling Options

import { diffLines } from "diff";

// Treat newlines as separate tokens
const newlineTokens = diffLines(
  "line1\nline2",
  "line1\n\nline2",  // Added blank line
  { newlineIsToken: true }
);
// Newlines appear as separate change objects

// Ignore missing newline at end of file
const eofNewline = diffLines(
  "last line\n",     // Has trailing newline
  "last line",       // Missing trailing newline
  { ignoreNewlineAtEof: true }
);
// Treats both as equivalent

Cross-Platform Compatibility

import { diffLines } from "diff";

// Handle Windows vs Unix line endings
const windowsText = "line1\r\nline2\r\n";
const unixText = "line1\nline2\n";

const compatible = diffLines(windowsText, unixText, {
  stripTrailingCr: true
});
// No differences detected despite different line endings

Code Diff Applications

import { diffLines } from "diff";

function createCodeDiff(oldCode, newCode) {
  return diffLines(oldCode, newCode, {
    ignoreWhitespace: false,  // Preserve code formatting
    newlineIsToken: false,    // Keep lines together
    stripTrailingCr: true     // Cross-platform compatibility
  });
}

// Usage for code comparison
const oldCode = `function hello() {
  console.log("old");
}`;

const newCode = `function hello() {
  console.log("new");
  return true;
}`;

const codeDiff = createCodeDiff(oldCode, newCode);

Large File Handling

import { diffLines } from "diff";

// Async processing for large files
function diffLargeFiles(oldContent, newContent, callback) {
  diffLines(oldContent, newContent, {
    callback: callback,
    maxEditLength: 50000,  // Limit computation
    timeout: 30000         // 30 second timeout
  });
}

diffLargeFiles(largeFile1, largeFile2, (result) => {
  if (result) {
    console.log(`Found ${result.length} change blocks`);
  } else {
    console.log("Files too different to compute diff efficiently");
  }
});

Whitespace Comparison Modes

import { diffLines } from "diff";

const oldText = "  line with spaces  \n";
const newText = "line with spaces\n";

// Strict comparison (shows whitespace changes)
const strict = diffLines(oldText, newText);

// Ignore whitespace comparison
const relaxed = diffLines(oldText, newText, { 
  ignoreWhitespace: true 
});

console.log("Strict changes:", strict.length);
console.log("Relaxed changes:", relaxed.length);

Direct Instance Usage

import { lineDiff } from "diff";

// Using the pre-configured instance
const customDiff = lineDiff.diff("old\nlines", "new\nlines");

// Custom tokenization access
const tokens = lineDiff.tokenize("line1\nline2\nline3");
console.log("Line tokens:", tokens);

// Custom equality checking
const equal = lineDiff.equals("  trimmed  ", "trimmed", { 
  ignoreWhitespace: true 
});

Install with Tessl CLI