hpq

library1.4.0jsnpmunverified

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.

web-framework data

npm install hpq

github ↗package ↗

INSTALL

IMPORT

SIG · HPQ

hpq

web-frameworkjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

hpq

✓ import * as hpq from 'hpq';

✗ import hpq from 'hpq';

The library exports a namespace object, not a default export. Access functions like `hpq.parse`.

parse

✓ import { parse, attr, text, query } from 'hpq';

For selective imports and tree-shaking, individual functions can be imported by name.

hpq

✓ const hpq = require('hpq');

CommonJS import for Node.js environments. Access functions like `hpq.parse`.

Demonstrates parsing HTML to extract specific attributes and text content into a structured object using various matcher functions.

import { parse, attr, text, query } from 'hpq'; const htmlString1 = '<figure><img src="img.png" alt="Image"><figcaption>An Image</figcaption></figure>'; const result1 = parse( htmlString1, { src: attr( 'img', 'src' ), alt: attr( 'img', 'alt' ), caption: text( 'figcaption' ) } ); console.log('Result 1:', result1); // Expected: { src: "img.png", alt: "Image", caption: "An Image" } const htmlString2 = '<blockquote><p>First paragraph</p><p>Second paragraph</p><cite>Andrew</cite></blockquote>'; const result2 = parse( htmlString2, { text: query( 'p', text() ), // query all 'p' elements and get their text cite: text( 'cite' ) } ); console.log('Result 2:', result2); // Expected: { text: [ "First paragraph", "Second paragraph" ], cite: "Andrew" }

Debug

Known issues

gotchahpq assumes and requires a browser DOM environment to function correctly. It relies on global objects like `document` and `Element`.

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`.

affects: >=1.0.0

gotchaMatcher 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`).

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.

affects: >=1.0.0

gotchaThe 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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: document is not defined

Attempting to run `hpq` in a Node.js environment without a simulated browser DOM.

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;`

TypeError: Cannot read properties of undefined (reading 'querySelector')

The `node` argument passed to a matcher function (or implicitly by `parse`) is `undefined` or not a valid DOM `Element`.

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.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/aduth/hpq ↗

packagehttps://www.npmjs.com/package/hpq ↗