', { 21 | text: hpq.query( 'p', hpq.text() ), 22 | cite: hpq.text( 'cite' ) 23 | } ); 24 | 25 | // { text: [ "...", "..." ], cite: "Andrew" } 26 | ``` 27 | 28 | ## Getting Started 29 | 30 | [Download the generated script file](https://unpkg.com/hpq/dist/hpq.min.js) or install via NPM if you have a front-end build process: 31 | 32 | ``` 33 | npm install hpq 34 | ``` 35 | 36 | `hpq` assumes that it's being run in a browser environment. If you need to simulate this in Node, consider [jsdom](https://www.npmjs.com/package/jsdom). 37 | 38 | ## Usage 39 | 40 | Pass a markup string or DOM element to the top-level `parse` function, along with the object shape you'd like to match. Keys of the matcher object will align with the returned object shape, where values are matcher functions; one of the many included matchers or your own accepting the node under test. 41 | 42 | ## API 43 | 44 | `parse( source: string | Element, matchers: Object | Function ): Object | mixed` 45 | 46 | Given a markup string or DOM element, creates an object aligning with the shape of the `matchers` object, or the value returned by the matcher function. If `matchers` is an object, its keys are the desired parameter names and its values are matcher functions that will each extract the value of their desired parameter. 47 | 48 | Matcher functions accept a single parameter `node` (a DOM element) and return the requested value. 49 | 50 | `attr( selector: ?string, name: string ): Function` 51 | 52 | Generates a function which matches node of type selector, returning an attribute by name if the attribute exists. If no selector is passed, returns attribute of the query element. 53 | 54 | `prop( selector: ?string, name: string ): Function` 55 | 56 | Generates a function which matches node of type selector, returning an attribute by property if the attribute exists. If no selector is passed, returns property of the query element. 57 | 58 | `html( selector: ?string ): Function` 59 | 60 | Convenience for `prop( selector, 'innerHTML' )` . 61 | 62 | `text( selector: ?string ): Function` 63 | 64 | Convenience for `prop( selector, 'textContent' )` . 65 | 66 | `query( selector: string, matchers: Object | Function )` 67 | 68 | Creates a new matching context by first finding elements matching selector using [`querySelectorAll`](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll) before then running another `parse` on `matchers` scoped to the matched elements. 69 | 70 | ## License 71 | 72 | Copyright (c) 2018 Andrew Duthie 73 | 74 | [The MIT License (MIT)](https://opensource.org/licenses/MIT) 75 | 76 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 77 | 78 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 79 | 80 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 81 | -------------------------------------------------------------------------------- /mocha-setup.js: -------------------------------------------------------------------------------- 1 | import register from '@babel/register'; 2 | 3 | register({ extensions: ['.ts'] }); 4 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "hpq", 3 | "version": "1.4.0", 4 | "description": "Utility to parse and query HTML into an object shape", 5 | "homepage": "https://github.com/aduth/hpq", 6 | "bugs": { 7 | "url": "https://github.com/aduth/hpq/issues" 8 | }, 9 | "repository": { 10 | "type": "git", 11 | "url": "https://github.com/aduth/hpq.git" 12 | }, 13 | "main": "dist/hpq.js", 14 | "module": "es/index.js", 15 | "types": "es/index.d.ts", 16 | "files": [ 17 | "dist", 18 | "es", 19 | "src" 20 | ], 21 | "scripts": { 22 | "build:es": "babel src/ --extensions '.ts' --out-dir es", 23 | "build:umd": "rollup -c", 24 | "build:types": "tsc -b tsconfig.decl.json", 25 | "build": "npm run build:es && npm run build:umd && npm run build:types", 26 | "dev": "rollup -c -w", 27 | "lint": "eslint . --ignore-pattern dist --ignore-pattern es", 28 | "unit-test": "NODE_ENV=test mocha -r jsdom-global/register -r @babel/register -r ./mocha-setup.js --extension ts", 29 | "typecheck": "tsc", 30 | "test": "npm run unit-test && npm run lint && npm run typecheck", 31 | "prepublishOnly": "npm run build" 32 | }, 33 | "author": { 34 | "name": "Andrew Duthie", 35 | "email": "andrew@andrewduthie.com", 36 | "url": "http://andrewduthie.com" 37 | }, 38 | "license": "MIT", 39 | "devDependencies": { 40 | "@aduth/eslint-config": "^4.4.1", 41 | "@babel/cli": "^7.21.0", 42 | "@babel/core": "^7.21.3", 43 | "@babel/preset-env": "^7.20.2", 44 | "@babel/preset-typescript": "^7.21.0", 45 | "@babel/register": "^7.21.0", 46 | "@rollup/plugin-babel": "^6.0.3", 47 | "@rollup/plugin-node-resolve": "^15.0.1", 48 | "@rollup/plugin-terser": "^0.4.0", 49 | "@types/chai": "^4.3.4", 50 | "@types/mocha": "^10.0.1", 51 | "@typescript-eslint/eslint-plugin": "^5.56.0", 52 | "@typescript-eslint/parser": "^5.56.0", 53 | "chai": "^4.3.7", 54 | "eslint": "^8.36.0", 55 | "eslint-config-prettier": "^8.8.0", 56 | "eslint-plugin-prettier": "^4.2.1", 57 | "jsdom": "^21.1.1", 58 | "jsdom-global": "^3.0.2", 59 | "mocha": "^10.2.0", 60 | "prettier": "^2.8.7", 61 | "rollup": "^3.20.2", 62 | "typescript": "^5.0.2" 63 | } 64 | } 65 | -------------------------------------------------------------------------------- /rollup.config.mjs: -------------------------------------------------------------------------------- 1 | import babel from '@rollup/plugin-babel'; 2 | import terser from '@rollup/plugin-terser'; 3 | import { nodeResolve } from '@rollup/plugin-node-resolve'; 4 | 5 | export default [ 6 | { 7 | input: 'src/index.ts', 8 | output: { 9 | format: 'umd', 10 | name: 'hpq', 11 | file: 'dist/hpq.js', 12 | }, 13 | plugins: [ 14 | nodeResolve({ 15 | extensions: ['.ts'], 16 | }), 17 | babel({ 18 | extensions: ['.ts'], 19 | babelHelpers: 'bundled', 20 | exclude: 'node_modules/**', 21 | presets: ['@babel/preset-typescript'], 22 | }), 23 | ], 24 | }, 25 | { 26 | input: 'src/index.ts', 27 | output: { 28 | format: 'umd', 29 | name: 'hpq', 30 | file: 'dist/hpq.min.js', 31 | }, 32 | plugins: [ 33 | nodeResolve({ 34 | extensions: ['.ts'], 35 | }), 36 | babel({ 37 | extensions: ['.ts'], 38 | babelHelpers: 'bundled', 39 | exclude: 'node_modules/**', 40 | presets: ['@babel/preset-typescript'], 41 | }), 42 | terser(), 43 | ], 44 | }, 45 | ]; 46 | -------------------------------------------------------------------------------- /src/get-path.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * Given object and string of dot-delimited path segments, returns value at 3 | * path or undefined if path cannot be resolved. 4 | * 5 | * @param object Lookup object 6 | * @param path Path to resolve 7 | * @return Resolved value 8 | */ 9 | export default function getPath(object: Record...
...
Andrew
'; 15 | 16 | // Element 17 | let element: HTMLElement; 18 | 19 | before(() => { 20 | element = document.createElement('div'); 21 | element.innerHTML = markup; 22 | element = element.firstChild as HTMLElement; 23 | }); 24 | 25 | describe('parse()', () => { 26 | it('should return undefined if passed no matchers', () => { 27 | const result = parse(markup); 28 | 29 | expect(result).to.be.undefined; 30 | }); 31 | 32 | it('should accept a string of markup as source', () => { 33 | const result = parse(markup, text('cite')); 34 | 35 | expect(result).to.equal('— Andrew'); 36 | }); 37 | 38 | it('should return matcher value if passed function matcher', () => { 39 | const result = parse(element, text('cite')); 40 | 41 | expect(result).to.equal('— Andrew'); 42 | }); 43 | 44 | it('should return undefined if passed matchers other than object, function', () => { 45 | // @ts-ignore 46 | const result = parse(element, 2); 47 | 48 | expect(result).to.be.undefined; 49 | }); 50 | 51 | it('should return parsed matches in shape of matcher object', () => { 52 | const result = parse(element, { 53 | author: text('cite'), 54 | deep: { value: text('cite') }, 55 | }); 56 | 57 | expect(result).to.eql({ 58 | author: '— Andrew', 59 | deep: { value: '— Andrew' }, 60 | }); 61 | }); 62 | }); 63 | 64 | describe('prop()', () => { 65 | it('should return a matcher function', () => { 66 | // @ts-ignore 67 | const matcher = prop(); 68 | 69 | expect(matcher).to.be.a('function'); 70 | }); 71 | 72 | it('should return property of current top node if undefined selector', () => { 73 | const result = parse(element, prop(undefined, 'nodeName')); 74 | 75 | expect(result).to.equal('BLOCKQUOTE'); 76 | }); 77 | 78 | it('should return property of current top node if omitted selector', () => { 79 | const result = parse(element, prop('nodeName')); 80 | 81 | expect(result).to.equal('BLOCKQUOTE'); 82 | }); 83 | 84 | it('should return undefined if selector does not match', () => { 85 | const result = parse(element, prop('strong', 'nodeName')); 86 | 87 | expect(result).to.be.undefined; 88 | }); 89 | 90 | it('should return property of selector match by property', () => { 91 | const result = parse(element, prop('cite', 'nodeName')); 92 | 93 | expect(result).to.equal('CITE'); 94 | }); 95 | }); 96 | 97 | describe('attr()', () => { 98 | it('should return a matcher function', () => { 99 | // @ts-ignore 100 | const matcher = attr(); 101 | 102 | expect(matcher).to.be.a('function'); 103 | }); 104 | 105 | it('should return attribute of current top node if undefined selector', () => { 106 | const result = parse(element, query('cite', attr(undefined, 'class'))); 107 | 108 | expect(result).to.eql(['large']); 109 | }); 110 | 111 | it('should return attribute of current top node if omitted selector', () => { 112 | const result = parse(element, query('cite', attr('class'))); 113 | 114 | expect(result).to.eql(['large']); 115 | }); 116 | 117 | it('should return undefined if selector does not match', () => { 118 | const result = parse(element, attr('strong', 'class')); 119 | 120 | expect(result).to.be.undefined; 121 | }); 122 | 123 | it('should return undefined if match does not have attribute', () => { 124 | const result = parse(element, attr('cite', 'data-unknown')); 125 | 126 | expect(result).to.be.undefined; 127 | }); 128 | 129 | it('should return attribute value of match', () => { 130 | const result = parse(element, attr('cite', 'class')); 131 | 132 | expect(result).to.equal('large'); 133 | }); 134 | }); 135 | 136 | describe('html()', () => { 137 | it('should return a matcher function', () => { 138 | const matcher = html(); 139 | 140 | expect(matcher).to.be.a('function'); 141 | }); 142 | 143 | it('should return inner HTML of top node if no selector', () => { 144 | const result = parse(element, html()); 145 | 146 | expect(result).to.match(/^…
…
— Andrew
/); 147 | }); 148 | 149 | it('should return inner HTML of selector match', () => { 150 | const result = parse(element, html('cite')); 151 | 152 | expect(result).to.equal('— Andrew'); 153 | }); 154 | }); 155 | 156 | describe('text()', () => { 157 | it('should return a matcher function', () => { 158 | const matcher = text(); 159 | 160 | expect(matcher).to.be.a('function'); 161 | }); 162 | 163 | it('should return text content of top node if no selector', () => { 164 | const result = parse(element, text()); 165 | 166 | expect(result).to.match(/^…/); 167 | }); 168 | 169 | it('should return text content of selector match', () => { 170 | const result = parse(element, text('cite')); 171 | 172 | expect(result).to.equal('— Andrew'); 173 | }); 174 | }); 175 | 176 | describe('query()', () => { 177 | it('should return array of parse on matched nodes', () => { 178 | const result = parse(element, { text: query('p', text()) }); 179 | 180 | expect(result).to.eql({ 181 | text: ['…', '…'], 182 | }); 183 | }); 184 | }); 185 | }); 186 | -------------------------------------------------------------------------------- /tsconfig.decl.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "./tsconfig.json", 3 | "compilerOptions": { 4 | "declaration": true, 5 | "emitDeclarationOnly": true, 6 | "outDir": "./es", 7 | "rootDir": "src", 8 | "noEmit": false 9 | }, 10 | "include": ["src"] 11 | } 12 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "ES2017", 4 | "lib": ["ES2017", "DOM", "DOM.Iterable"], 5 | "moduleResolution": "node", 6 | "strict": true, 7 | "noEmit": true 8 | }, 9 | "include": ["src", "test"] 10 | } 11 | --------------------------------------------------------------------------------