{"library":"range-parser","title":"HTTP Range Header Parser","description":"range-parser is a foundational utility within the Node.js ecosystem, specifically designed for parsing the HTTP `Range` header field. This header is crucial for implementing partial content responses (HTTP 206 Partial Content), enabling clients to request specific byte ranges of a resource, which is essential for video streaming, resumable downloads, and efficient data retrieval. Currently at stable version 1.2.1, it provides a straightforward API to transform a `Range` header string into a structured array of byte range objects, each with `start` and `end` properties. A key characteristic is its error handling mechanism, which returns negative integer codes (e.g., -1 for unsatisfiable ranges, -2 for malformed headers) instead of throwing exceptions, requiring developers to explicitly check the return type. It offers a `combine` option to automatically merge overlapping or adjacent ranges for simplified processing. As part of the `jshttp` organization, the package is mature and highly stable, receiving updates primarily for maintenance and minor enhancements rather than frequent new feature releases, making it a reliable choice for server-side range parsing.","language":"javascript","status":"active","last_verified":"Sun Apr 19","install":{"commands":["npm install range-parser"],"cli":null},"imports":["const parseRange = require('range-parser');","import parseRange from 'range-parser';","import type { Range, Ranges, Options } from 'range-parser';"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"const parseRange = require('range-parser');\n\n// Example 1: Basic parsing of a valid range\nconst fileSize1 = 1000;\nconst header1 = 'bytes=0-99,200-299';\nconst ranges1 = parseRange(fileSize1, header1);\n\nif (Array.isArray(ranges1)) {\n  console.log(`Parsed ranges for header '${header1}':`, ranges1);\n  console.log(`Type: ${ranges1.type}`); // Typically 'bytes'\n  ranges1.forEach(r => console.log(`  Start: ${r.start}, End: ${r.end}`));\n} else {\n  console.error(`Error parsing header '${header1}':`, ranges1 === -1 ? 'Unsatisfiable Range' : 'Malformed Header');\n}\n\n// Example 2: Parsing with the 'combine' option to merge overlapping/adjacent ranges\nconst fileSize2 = 100;\nconst header2 = 'bytes=50-55,0-10,5-10,56-60';\nconst ranges2 = parseRange(fileSize2, header2, { combine: true });\n\nif (Array.isArray(ranges2)) {\n  console.log(`\\nParsed (combined) ranges for header '${header2}':`, ranges2);\n  ranges2.forEach(r => console.log(`  Start: ${r.start}, End: ${r.end}`));\n} else {\n  console.error(`Error parsing header '${header2}' with combine:`, ranges2);\n}\n\n// Example 3: Handling an unsatisfiable range (requesting beyond file size)\nconst fileSize3 = 50;\nconst header3 = 'bytes=100-150';\nconst ranges3 = parseRange(fileSize3, header3);\n\nif (!Array.isArray(ranges3)) {\n  console.error(`\\nError for header '${header3}':`, ranges3 === -1 ? 'Unsatisfiable Range' : 'Malformed Header');\n}\n\n// Example 4: Handling a malformed header string\nconst fileSize4 = 100;\nconst header4 = 'invalid-range-string';\nconst ranges4 = parseRange(fileSize4, header4);\n\nif (!Array.isArray(ranges4)) {\n  console.error(`\\nError for header '${header4}':`, ranges4 === -1 ? 'Unsatisfiable Range' : 'Malformed Header');\n}","lang":"javascript","description":"This quickstart demonstrates how to use `range-parser` to parse HTTP `Range` headers, including basic valid range parsing, using the `combine` option, and handling common error conditions like unsatisfiable and malformed headers through its negative integer return values.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}