{"id":13293,"library":"header-range-parser","title":"Header Range Parser","description":"This package provides a robust utility for parsing HTTP `Range` header fields, designed specifically for Node.js environments. It's a maintained fork of the original `range-parser` library, aiming for 100% compatibility while providing ongoing updates and fixes. The current stable version is 1.1.5. Releases are made on an as-needed basis, primarily for bug fixes, minor improvements, and dependency updates, without a strict cadence. Key differentiators include its active maintenance, explicit TypeScript support, and improved error reporting and handling of invalid range formats compared to its unmaintained predecessor. It accurately extracts byte ranges from the header string, which can then be used for partial content delivery in HTTP servers.","status":"active","version":"1.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/r37r0m0d3l/header-range-parser","tags":["javascript","header","http","parser","range","typescript"],"install":[{"cmd":"npm install header-range-parser","lang":"bash","label":"npm"},{"cmd":"yarn add header-range-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add header-range-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `parseRange` function is the primary API for parsing range headers and is a named export, not a default export.","wrong":"import parseRange from 'header-range-parser';","symbol":"parseRange","correct":"import { parseRange } from 'header-range-parser';"},{"note":"All error constants (e.g., `ERROR_UNSATISFIABLE_RESULT`, `ERROR_STRING_IS_NOT_HEADER`) are named exports. CommonJS `require` syntax is also supported in CJS projects.","wrong":"import ERROR_UNSATISFIABLE_RESULT from 'header-range-parser';","symbol":"ERROR_UNSATISFIABLE_RESULT","correct":"import { ERROR_UNSATISFIABLE_RESULT } from 'header-range-parser';"},{"note":"Dedicated TypeScript types like `Ranges` and `Result` are provided for type-safe usage. For optimal bundling and clarity in TypeScript, prefer `import type` when only importing type declarations.","wrong":"import { Ranges, Result } from 'header-range-parser';","symbol":"Ranges","correct":"import type { Ranges, Result } from 'header-range-parser';"}],"quickstart":{"code":"import { parseRange, ERROR_UNSATISFIABLE_RESULT, ERROR_STRING_IS_NOT_HEADER, ERROR_INVALID_ARGUMENT } from 'header-range-parser';\nimport type { Ranges } from 'header-range-parser';\n\n// Simulate a total resource size and various range headers\nconst totalSize = 1000;\nconst rangeHeaderValid = 'bytes=0-499, 500-999';\nconst rangeHeaderPartial = 'bytes=500-'; // Request from 500 to end\nconst rangeHeaderUnsatisfiable = 'bytes=1500-2000'; // Ranges beyond totalSize\nconst rangeHeaderInvalid = 'bytes=abc-def'; // Malformed header\nconst rangeHeaderCombined = 'bytes=50-55,0-10,5-10,56-60'; // Overlapping/adjacent ranges\n\nconsole.log('--- Parsing Valid Range Header ---');\nconst subRangesValid: Ranges | number = parseRange(totalSize, rangeHeaderValid);\nif (Array.isArray(subRangesValid)) {\n  console.log(`Parsed type: ${subRangesValid.type}`);\n  subRangesValid.forEach((range, index) => {\n    console.log(`  Range ${index}: start=${range.start}, end=${range.end}`);\n  });\n} else {\n  console.error('Error parsing valid range:', subRangesValid);\n}\n\nconsole.log('\\n--- Parsing Partial Range Header (500- end of file) ---');\nconst subRangesPartial: Ranges | number = parseRange(totalSize, rangeHeaderPartial);\nif (Array.isArray(subRangesPartial)) {\n  console.log(`Parsed type: ${subRangesPartial.type}`);\n  subRangesPartial.forEach((range, index) => {\n    console.log(`  Range ${index}: start=${range.start}, end=${range.end}`);\n  });\n} else {\n  console.error('Error parsing partial range:', subRangesPartial);\n}\n\nconsole.log('\\n--- Parsing Unsatisfiable Range Header ---');\nlet subRangesUnsatisfiable: Ranges | number = parseRange(totalSize, rangeHeaderUnsatisfiable);\nif (subRangesUnsatisfiable === ERROR_UNSATISFIABLE_RESULT) {\n  console.log(`Result: Range is unsatisfiable (error code: ${subRangesUnsatisfiable})`);\n} else if (Array.isArray(subRangesUnsatisfiable)) {\n  console.log(`Unexpected success for unsatisfiable range. Parsed type: ${subRangesUnsatisfiable.type}`);\n}\n\nconsole.log('\\n--- Parsing Invalid Range Header (with throwError: false) ---');\n// Using throwError: false to get error codes instead of throwing exceptions\nconst subRangesInvalid: Ranges | number = parseRange(totalSize, rangeHeaderInvalid, { throwError: false });\nif (subRangesInvalid === ERROR_STRING_IS_NOT_HEADER || subRangesInvalid === ERROR_INVALID_ARGUMENT) {\n  console.log(`Result: Invalid header string (error code: ${subRangesInvalid})`);\n} else if (Array.isArray(subRangesInvalid)) {\n  console.log(`Unexpected success for invalid range. Parsed type: ${subRangesInvalid.type}`);\n}\n\nconsole.log('\\n--- Combining Overlapping and Adjacent Ranges ---');\nconst subRangesCombined: Ranges | number = parseRange(totalSize, rangeHeaderCombined, { combine: true });\nif (Array.isArray(subRangesCombined)) {\n  console.log(`Parsed type: ${subRangesCombined.type}`);\n  subRangesCombined.forEach((range, index) => {\n    console.log(`  Combined Range ${index}: start=${range.start}, end=${range.end}`);\n  });\n} else {\n  console.error('Error combining ranges:', subRangesCombined);\n}","lang":"typescript","description":"This example demonstrates parsing various `Range` header formats, including valid, partial, unsatisfiable, and invalid inputs. It also shows how to use the `combine` option and handle different error outcomes returned by `parseRange`."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 12.22.0 or higher to ensure compatibility and stability.","message":"Starting with version 1.1.1, `header-range-parser` requires Node.js version 12.22.0 or newer. Environments running older Node.js versions will encounter runtime errors or fail to install.","severity":"breaking","affected_versions":">=1.1.1"},{"fix":"Always check the return value of `parseRange`. Handle negative number results (e.g., `if (subRanges === ERROR_UNSATISFIABLE_RESULT) { ... }`) or utilize the exported error constants or their corresponding type results for explicit error handling.","message":"The `parseRange` function returns negative numbers (`-1`, `-2`, `-3`) or specific error objects (`ResultUnsatisfiable`, etc.) to indicate parsing failures or invalid inputs, unless the `throwError` option is explicitly set to `true`. Neglecting to check for these return values can lead to unexpected runtime behavior or incorrect processing of ranges.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review applications that process potentially malformed `Range` headers to ensure they correctly handle stricter parsing and improved error reporting introduced in version 1.1.5. Test with a variety of edge cases including excessive whitespace or unusual range syntax.","message":"Version 1.1.5 introduced improved parsing logic for handling whitespace and various invalid range formats. While generally an improvement for robustness, code that previously relied on specific (potentially lenient) parsing behaviors for malformed headers might now see different results, including ranges previously accepted now being flagged as invalid or unsatisfiable.","severity":"gotcha","affected_versions":">=1.1.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"To prevent exceptions, set `throwError: false` in the options object passed to `parseRange`. This will make the function return numeric error codes or error objects instead of throwing. Alternatively, ensure the input `header` string is a valid HTTP `Range` header before parsing.","cause":"The `throwError` option is implicitly or explicitly set to `true` (which is the default behavior), and an invalid or malformed `Range` header string was provided to `parseRange`.","error":"RangeError: Invalid range header: bytes=-100"},{"fix":"Before accessing properties of the result, explicitly check if the return value of `parseRange` is an array of ranges (e.g., `if (Array.isArray(subRanges)) { ... }`) or one of the documented negative error codes.","cause":"`parseRange` returned a negative number (e.g., `-1`, `-2`, `-3`) or an error object, indicating a parsing failure, but the subsequent code attempted to access properties (like `type`) as if a successful `Ranges` array was returned.","error":"TypeError: Cannot read properties of undefined (reading 'type')"},{"fix":"If your project is configured as an ESM module (e.g., `\"type\": \"module\"` in `package.json`), you must use ESM `import` statements: `import { parseRange } from 'header-range-parser';`.","cause":"Attempting to use `require()` CommonJS syntax to import `header-range-parser` in an ECMAScript Module (ESM) project context.","error":"ERR_REQUIRE_ESM: require() of ES Module ... header-range-parser.js from ... not supported."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}