{"id":15751,"library":"parse-diff","title":"Unified Diff Parser","description":"parse-diff is a lightweight and focused JavaScript library designed to parse unified diff format strings, typically generated by version control systems like Git. It transforms a raw diff string into a structured JavaScript array of file objects, each containing chunks of changes and individual line modifications, including metadata like additions, deletions, and file paths. The current stable version is 0.12.0, published in January 2023, indicating a mature and stable project with an infrequent release cadence. While other parsers exist (e.g., `diffparser`, `parse-git-diff`), `parse-diff` is known for its simplicity and direct approach to the unified diff format, making it suitable for applications requiring programmatic access to diff data. It ships with TypeScript types, enhancing developer experience for TypeScript projects.","status":"active","version":"0.12.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/sergeyt/parse-diff","tags":["javascript","diff","unidiff","parser","typescript"],"install":[{"cmd":"npm install parse-diff","lang":"bash","label":"npm"},{"cmd":"yarn add parse-diff","lang":"bash","label":"yarn"},{"cmd":"pnpm add parse-diff","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary parsing function `parse` is a default export. Attempting a named import will result in a TypeError. This applies to both ESM and TypeScript contexts.","wrong":"import { parse } from 'parse-diff';","symbol":"parse","correct":"import parse from 'parse-diff';"},{"note":"In CommonJS environments, the `parse` function is exported as the module.exports object directly. Destructuring it (e.g., `{ parse }`) will cause a TypeError as `parse` won't be found as a property.","wrong":"const { parse } = require('parse-diff');","symbol":"parse","correct":"const parse = require('parse-diff');"},{"note":"TypeScript users can import type definitions for the parsed output structure (`File`, `Chunk`, `Change`) directly from the package for better type safety and autocompletion.","symbol":"File structure types","correct":"import type { File, Chunk, Change } from 'parse-diff';"}],"quickstart":{"code":"import parse from 'parse-diff';\n\nconst diffString = `diff --git a/README.md b/README.md\nindex c96dc36..0e564d2 100644\n--- a/README.md\n+++ b/README.md\n@@ -1,5 +1,6 @@\n # parse-diff\n \n Simple unified diff parser for JavaScript\n \n-## JavaScript Usage Example\n+## Usage Example\n+\n `;\n\nconst files = parse(diffString);\n\nconsole.log(`Number of patched files: ${files.length}`);\n\nfiles.forEach(file => {\n  console.log(`\\nFile: ${file.from} -> ${file.to}`);\n  console.log(`  Additions: ${file.additions}, Deletions: ${file.deletions}`);\n  file.chunks.forEach(chunk => {\n    console.log(`  Chunk content: ${chunk.content}`);\n    chunk.changes.forEach(change => {\n      console.log(`    Line (${change.type}): ${change.content}`);\n    });\n  });\n});","lang":"typescript","description":"This example demonstrates how to parse a simple unified diff string and iterate through the resulting file, chunk, and change objects, logging their properties."},"warnings":[{"fix":"Always pin `parse-diff` to an exact version (e.g., `\"parse-diff\": \"0.12.0\"`) or use a tilde (`~0.12.0`) in `package.json` to prevent unexpected breaking changes with minor updates. Thoroughly test your application after any upgrade.","message":"As a 0.x.x version, `parse-diff` adheres to a relaxed Semantic Versioning where minor versions (e.g., 0.11.0 to 0.12.0) *can* introduce breaking changes to the API or the structure of the parsed output. Always review release notes when updating.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Ensure the input `diffString` strictly adheres to the unified diff format. Pre-validate input if it comes from untrusted or variable sources. For Git-specific diffs, ensure `git diff --unified` output is used.","message":"The parser expects input in a strict unified diff format. Malformed or non-standard diff strings may lead to unexpected results, such as empty arrays being returned or incomplete parsing, rather than explicit errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Consider breaking down extremely large diffs into smaller, manageable chunks if possible, or explore streaming parsers if available for very large scale diff processing. Profile memory usage when dealing with large inputs.","message":"For very large diff files (e.g., hundreds of thousands of lines), parsing can be memory-intensive due to the entire diff string being loaded into memory and the resulting object structure. This can lead to performance bottlenecks or out-of-memory errors in resource-constrained environments.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ESM/TypeScript, use `import parse from 'parse-diff';`. For CommonJS, use `const parse = require('parse-diff');`.","cause":"Attempting to import `parse` as a named export (`import { parse } from 'parse-diff'`) in an ESM module or TypeScript, or destructuring `require('parse-diff')` in CommonJS. The `parse` function is the module's default export.","error":"TypeError: parse is not a function"},{"fix":"If encountering this error, ensure your project's module resolution is consistent. If your project is primarily CommonJS, verify `parse-diff` is installed in a compatible version. If you are in an ESM context, always use `import parse from 'parse-diff';`.","cause":"Using `require('parse-diff')` in a CommonJS module while `parse-diff` might have been resolved to an ESM-only version or an environment configured for ESM. While `parse-diff` supports CJS, conflicts can arise in mixed environments.","error":"Error: [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import() ..."},{"fix":"Double-check the input diff for strict adherence to the unified diff format. Use a reliable source for diff strings (e.g., `git diff`). Consider adding pre-parsing validation or sanitization steps for user-provided diffs.","cause":"Subtle formatting issues in the input diff string (e.g., incorrect line endings, malformed headers, non-standard Git extensions) can cause the parser to fail silently or misinterpret sections, resulting in incomplete or empty output.","error":"The parsed output array is empty or contains fewer files/chunks than expected, despite valid diff input."}],"ecosystem":"npm"}