{"id":13299,"library":"hpq","title":"HTML Parser and Query Utility","description":"hpq is a utility library designed to parse HTML strings or existing DOM elements and query their content into a structured JavaScript object. The current stable version is 1.4.0, released in March 2023, indicating a mature project with a maintenance-focused release cadence, primarily addressing minor improvements and type definitions. It operates by allowing developers to define an object shape, where values are matcher functions (e.g., `attr`, `text`, `query`) that extract specific data points from the HTML. Its key differentiator is this declarative, object-shape-driven approach to data extraction, inspired by tools like gdom, making it particularly useful for screen scraping or data transformation within a browser environment.","status":"maintenance","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/aduth/hpq","tags":["javascript","typescript"],"install":[{"cmd":"npm install hpq","lang":"bash","label":"npm"},{"cmd":"yarn add hpq","lang":"bash","label":"yarn"},{"cmd":"pnpm add hpq","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports a namespace object, not a default export. Access functions like `hpq.parse`.","wrong":"import hpq from 'hpq';","symbol":"hpq","correct":"import * as hpq from 'hpq';"},{"note":"For selective imports and tree-shaking, individual functions can be imported by name.","symbol":"parse","correct":"import { parse, attr, text, query } from 'hpq';"},{"note":"CommonJS import for Node.js environments. Access functions like `hpq.parse`.","symbol":"hpq","correct":"const hpq = require('hpq');"}],"quickstart":{"code":"import { parse, attr, text, query } from 'hpq';\n\nconst htmlString1 = '<figure><img src=\"img.png\" alt=\"Image\"><figcaption>An Image</figcaption></figure>';\nconst result1 = parse( htmlString1, {\n\tsrc: attr( 'img', 'src' ),\n\talt: attr( 'img', 'alt' ),\t\n\tcaption: text( 'figcaption' )\n} );\n\nconsole.log('Result 1:', result1);\n// Expected: { src: \"img.png\", alt: \"Image\", caption: \"An Image\" }\n\nconst htmlString2 = '<blockquote><p>First paragraph</p><p>Second paragraph</p><cite>Andrew</cite></blockquote>';\nconst result2 = parse( htmlString2, {\n\ttext: query( 'p', text() ), // query all 'p' elements and get their text\n\tcite: text( 'cite' )\n} );\n\nconsole.log('Result 2:', result2);\n// Expected: { text: [ \"First paragraph\", \"Second paragraph\" ], cite: \"Andrew\" }","lang":"typescript","description":"Demonstrates parsing HTML to extract specific attributes and text content into a structured object using various matcher functions."},"warnings":[{"fix":"When running in Node.js, integrate a DOM simulation library like `jsdom`. For example, create a JSDOM instance and pass its `window.document` to a function that uses hpq, or configure global `window` and `document`.","message":"hpq assumes and requires a browser DOM environment to function correctly. It relies on global objects like `document` and `Element`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement explicit checks for `undefined` or empty arrays in your consuming code if non-existence of elements is a possibility and requires specific handling.","message":"Matcher functions like `attr`, `text`, `query`, when applied with selectors that yield no matches, will typically result in `undefined` for single values or empty arrays for multiple values (e.g., `query`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that the HTML input is well-formed. Consider pre-processing HTML with a robust HTML parser if dealing with potentially malformed external sources.","message":"The library does not provide any built-in error handling for invalid HTML markup. Parsing malformed HTML might lead to unexpected results or errors from the underlying DOM APIs.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `jsdom` (`npm install jsdom`) and configure it to provide a global `document` and `window` object before calling hpq functions. Example: `const { JSDOM } = require('jsdom'); const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>'); global.document = dom.window.document;`","cause":"Attempting to run `hpq` in a Node.js environment without a simulated browser DOM.","error":"ReferenceError: document is not defined"},{"fix":"Verify that the `source` passed to `hpq.parse` is a valid HTML string or a DOM `Element` and that subsequent selectors within `query` calls correctly target existing elements.","cause":"The `node` argument passed to a matcher function (or implicitly by `parse`) is `undefined` or not a valid DOM `Element`.","error":"TypeError: Cannot read properties of undefined (reading 'querySelector')"}],"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}