{"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 = '
\"Image\"
An Image
';\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 = '

First paragraph

Second paragraph

Andrew
';\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,"search_vec":"'1.4.0':34 '2023':38 'address':51 'allow':60 'approach':94 'attr':73 'browser':115 'cadenc':49 'content':23 'current':30 'data':79,96,111 'declar':89 'defin':63 'definit':56 'design':11 'develop':61 'differenti':86 'dom':18 'driven':93 'e.g':72 'element':19 'environ':116 'exist':17 'extract':77,97 'focus':47 'function':71 'gdom':102 'hpq':6 'html':1,14,83 'improv':53 'indic':39 'inspir':98 'javascript':27,117 'key':85 'librari':10 'like':101 'mainten':46 'maintenance-focus':45 'make':103 'march':37 'matcher':70 'matur':41 'minor':52 'object':28,65,91 'object-shape-driven':90 'oper':58 'pars':13 'parser':2 'particular':105 'point':80 'primarili':50 'project':42 'queri':4,21,75 'releas':35,48 'scrape':109 'screen':108 'shape':66,92 'specif':78 'stabl':31 'string':15 'structur':26 'text':74 'tool':100 'transform':112 'type':55 'typescript':118 'use':106 'util':5,9 'valu':68 'version':32 'within':113","created_at":"2026-04-20T01:53:46.274335+00:00","updated_at":"2026-04-20T01:53:46.274335+00:00","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(''); 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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/aduth/hpq","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/hpq","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}