{"id":16206,"library":"sane-domparser-error","title":"Sane DOMParser Errors","description":"sane-domparser-error is a JavaScript utility library designed to standardize error handling for DOMParser and XMLHttpRequest (when `responseType = 'document'`) in web environments. Typically, when an XML document cannot be parsed, these native APIs do not throw an exception but instead return a document containing a `<parsererror>` element. This library abstracts away the inconsistencies of the `<parsererror>` document across different browsers, providing a consistent mechanism to detect and report parsing failures as standard JavaScript `Error` objects. The package is currently at version 0.2.0, with its last update over a decade ago, indicating a maintenance status with a very infrequent release cadence. Its primary differentiator is simplifying robust XML parsing error detection, which is complex due to browser-specific `parsererror` document structures and namespaces.","status":"maintenance","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/cburgmer/sane-domparser-error","tags":["javascript","XML","parser","DOMParser","XHR","error"],"install":[{"cmd":"npm install sane-domparser-error","lang":"bash","label":"npm"},{"cmd":"yarn add sane-domparser-error","lang":"bash","label":"yarn"},{"cmd":"pnpm add sane-domparser-error","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package's primary usage pattern, given its age, is CommonJS `require()`. While Node.js supports ESM, this module was not designed for it directly, and its methods are accessed via the `saneError` object.","wrong":"import saneError from 'sane-domparser-error';","symbol":"saneError","correct":"const saneError = require('sane-domparser-error');"},{"note":"The `failOnParseError` function is a method of the object exported by the package, not a named export itself. It expects a parsed XML Document as an argument and will throw an Error if a parsing error is detected within the document.","wrong":"import { failOnParseError } from 'sane-domparser-error';","symbol":"failOnParseError","correct":"const saneError = require('sane-domparser-error');\nsaneError.failOnParseError(doc);"}],"quickstart":{"code":"const saneError = require('sane-domparser-error');\n\n// Simulate an invalid XML string\nconst malformedXml = '<root><item>Missing end tag</item>';\n\n// Create a DOMParser instance (globally available in browsers)\nconst parser = new DOMParser();\n\n// Attempt to parse the malformed XML\nconst doc = parser.parseFromString(malformedXml, 'application/xml');\n\ntry {\n  // Use sane-domparser-error to check for and throw an error\n  // if the document contains a parsererror element.\n  saneError.failOnParseError(doc);\n  console.log('XML parsed successfully (this should not happen with malformed XML).');\n} catch (error) {\n  console.error('XML Parsing Error Caught:');\n  console.error(`- Error Message: ${error.message}`);\n  console.error(`- Error Name: ${error.name}`);\n  // In a real application, you might log the full stack or take recovery actions\n}\n\n// Example of valid XML for contrast\nconst validXml = '<root><item>Hello</item></root>';\nconst validDoc = parser.parseFromString(validXml, 'application/xml');\ntry {\n  saneError.failOnParseError(validDoc);\n  console.log('\\nValid XML parsed successfully.');\n} catch (error) {\n  console.error('\\nUnexpected error with valid XML:', error.message);\n}","lang":"javascript","description":"This quickstart demonstrates how to parse a malformed XML string using DOMParser and then utilize sane-domparser-error to catch and standardize the resulting parsing error into a throwable JavaScript Error object, contrasting it with successful parsing."},"warnings":[{"fix":"Always use `saneError.failOnParseError(doc)` after parsing with DOMParser, or manually check for `doc.getElementsByTagName('parsererror').length > 0`.","message":"The native DOMParser and XMLHttpRequest APIs do not throw JavaScript exceptions when XML parsing fails. Instead, they return a Document object containing a `<parsererror>` element. This package exists specifically to normalize this behavior into standard error throwing. Developers must explicitly check for these error documents or use this package.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Rely on `sane-domparser-error` to handle browser inconsistencies in parsing error detection, or implement robust cross-browser checks manually using `namespaceURI` and tag names.","message":"The structure and namespace of the `<parsererror>` element can vary slightly between different browsers (e.g., Firefox vs. Chrome-based browsers), making cross-browser error detection complex. This package aims to abstract these differences.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For Node.js environments, use a DOM implementation like `jsdom` or `@xmldom/xmldom` to polyfill `DOMParser` before attempting to use `sane-domparser-error`. Example: `const { JSDOM } = require('jsdom'); global.DOMParser = new JSDOM().window.DOMParser;`","message":"This package is intended for browser environments. When attempting to use DOMParser in Node.js, you will encounter a `ReferenceError: DOMParser is not defined` because `DOMParser` is a Web API. This package does not provide a DOMParser polyfill for Node.js.","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":"Install and configure a DOM polyfill such as `jsdom` or `@xmldom/xmldom` in your Node.js application to provide a global `DOMParser` implementation. `const { JSDOM } = require('jsdom'); global.DOMParser = new JSDOM().window.DOMParser;`","cause":"Attempting to use `DOMParser` (and by extension `sane-domparser-error`) in a Node.js environment where the Web API is not natively available.","error":"Uncaught ReferenceError: DOMParser is not defined"},{"fix":"After parsing, always pass the resulting document to `saneError.failOnParseError(doc);` within a `try...catch` block to ensure that parsing errors are converted into throwable JavaScript errors.","cause":"The native `DOMParser.parseFromString()` method does not throw an exception on malformed XML. It returns a document containing a `<parsererror>` element, which needs to be explicitly checked.","error":"XML document parsed successfully, but it's malformed and no error was thrown."}],"ecosystem":"npm"}