@maze014/dom-fetch 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -15
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/validations.ts +1 -1
package/README.md
CHANGED
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
Fetch and extract DOM elements from a **URL or local HTML file** using a CSS query selector.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`@maze014/dom-fetch` lets you retrieve HTML elements and choose how they are represented (raw element, HTML string, children HTML, or a structured breakdown).
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## Installation
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
|
-
$ npm install dom-fetch
|
|
12
|
+
$ npm install @maze014/dom-fetch
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
---
|
|
@@ -19,7 +19,7 @@ $ npm install dom-fetch
|
|
|
19
19
|
### Basic example (fetch from a URL)
|
|
20
20
|
|
|
21
21
|
```ts
|
|
22
|
-
import { selectElements } from "dom-fetch";
|
|
22
|
+
import { selectElements } from "@maze014/dom-fetch";
|
|
23
23
|
|
|
24
24
|
const elements = await selectElements(
|
|
25
25
|
"https://example.com",
|
|
@@ -65,12 +65,12 @@ const elements = await selectElements(
|
|
|
65
65
|
|
|
66
66
|
The `output` option controls how each matched element is returned.
|
|
67
67
|
|
|
68
|
-
| Output value
|
|
69
|
-
|
|
70
|
-
| `"html"`
|
|
71
|
-
| `"children"`
|
|
72
|
-
| `"object"`
|
|
73
|
-
| `"breakdown"` | A structured object describing the element
|
|
68
|
+
| Output value | Description |
|
|
69
|
+
| ------------- | -------------------------------------------------- |
|
|
70
|
+
| `"html"` | The full HTML of the matched element (`outerHTML`) |
|
|
71
|
+
| `"children"` | The inner HTML of the matched element |
|
|
72
|
+
| `"object"` | The raw DOM `Element` |
|
|
73
|
+
| `"breakdown"` | A structured object describing the element |
|
|
74
74
|
|
|
75
75
|
### Breakdown output example
|
|
76
76
|
|
|
@@ -137,12 +137,12 @@ Fetches elements matching a CSS selector from a given source.
|
|
|
137
137
|
|
|
138
138
|
#### Parameters
|
|
139
139
|
|
|
140
|
-
| Parameter
|
|
141
|
-
|
|
142
|
-
| `source`
|
|
143
|
-
| `selector`
|
|
144
|
-
| `options.output` | `"object" \| "html" \| "children" \| "breakdown"` | `"html"` | Format of returned elements
|
|
145
|
-
| `options.source` | `"url" \| "file"`
|
|
140
|
+
| Parameter | Type | Default | Description |
|
|
141
|
+
| ---------------- | ------------------------------------------------- | -------- | ----------------------------------------- |
|
|
142
|
+
| `source` | `string` | — | URL or relative file path containing HTML |
|
|
143
|
+
| `selector` | `string` | — | CSS selector (uses `querySelectorAll`) |
|
|
144
|
+
| `options.output` | `"object" \| "html" \| "children" \| "breakdown"` | `"html"` | Format of returned elements |
|
|
145
|
+
| `options.source` | `"url" \| "file"` | `"url"` | Defines how the source is fetched |
|
|
146
146
|
|
|
147
147
|
#### Returns
|
|
148
148
|
|
package/dist/index.js
CHANGED
|
@@ -33,7 +33,7 @@ var VERSION = "1.0.0";
|
|
|
33
33
|
// src/validations.ts
|
|
34
34
|
var import_node_fs = require("fs");
|
|
35
35
|
var import_promises = require("fs/promises");
|
|
36
|
-
var UA =
|
|
36
|
+
var UA = `@maze014/dom-fetch/${VERSION}`;
|
|
37
37
|
function validateOutputOption(options) {
|
|
38
38
|
const output = options.output;
|
|
39
39
|
if (!/^(?:object|html|children|breakdown)$/.test(output)) {
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts","../src/fetch.ts","../src/constants.ts","../src/validations.ts"],"sourcesContent":["import { FetchOptions } from \"./types\";\nimport { _fromFile, _fromHttp } from \"./fetch\";\nimport { validateOutputOption, validateSourceOption } from \"./validations\";\n\n/**\n *\n * @param source References the source from where to fetch the DOM. It can be an a relative file path or an URL\n * @param selector The query selector used to fetch elements from the DOM. (will run querySelectorAll)\n * @param options The FetchOptions needed for the requested elements\n * @returns\n */\nexport async function selectElements(\n\tsource: string,\n\tselector: string,\n\toptions?: FetchOptions\n) {\n\ttry {\n\t\tlet nodes: Array<Element> = [];\n\t\tconst fixedOptions = _initOptions(options);\n\t\tconst sourceOption = validateSourceOption(fixedOptions);\n\n\t\tif (sourceOption == \"url\") {\n\t\t\tnodes = await _fromHttp(source, selector);\n\t\t} else if (sourceOption == \"file\") {\n\t\t\tnodes = await _fromFile(source, selector);\n\t\t}\n\n\t\treturn nodes.map((el) => {\n\t\t\treturn _computed(el, fixedOptions);\n\t\t});\n\t} catch (error: any) {\n\t\treturn Promise.reject(error);\n\t}\n}\n\n// ============================= PRIVATE functions =============================\n\nconst _initOptions = (options: any = {}) => {\n\tconst { output = \"html\", source = \"url\" } = options;\n\treturn { output, source } as FetchOptions;\n};\n\nconst _computed = (el: Element, options: FetchOptions) => {\n\tlet result: any;\n\tconst output = validateOutputOption(options);\n\n\tswitch (output) {\n\t\tcase \"html\":\n\t\tcase \"children\":\n\t\t\tif (output == \"html\") {\n\t\t\t\tresult = el.outerHTML;\n\t\t\t} else {\n\t\t\t\tresult = el.innerHTML;\n\t\t\t}\n\t\t\tbreak;\n\t\tcase \"breakdown\":\n\t\t\tresult = {\n\t\t\t\ttag: el.tagName.toLowerCase(),\n\t\t\t\ttext: el.textContent?.trim() ?? \"\",\n\t\t\t\thtml: el.innerHTML,\n\t\t\t\tattributes: Object.fromEntries(\n\t\t\t\t\tArray.from(el.attributes).map((a) => [a.name, a.value])\n\t\t\t\t),\n\t\t\t};\n\t\t\tbreak;\n\t\tdefault:\n\t\t\tresult = el;\n\t}\n\treturn result;\n};\n","import { JSDOM } from \"jsdom\";\nimport { HTML_CONTENT_TYPE } from \"./constants\";\nimport {\n\tvalidateFileExistance,\n\tvalidateResource,\n} from \"./validations\";\n\nexport async function _fromHttp(\n\tsource: string,\n\tselector: string\n): Promise<Element[]> {\n\tconst res = await validateResource(source);\n\n\tconst html = await res.text();\n\n\tconst dom = new JSDOM(html, {\n\t\turl: source,\n\t\tcontentType: HTML_CONTENT_TYPE,\n\t});\n\n\tconst document = dom.window.document;\n\n\treturn Array.from(document.querySelectorAll(selector));\n}\n\nexport const _fromFile = async (source: string, selector: string) => {\n\tlet html = await validateFileExistance(source);\n\n\tconst dom = new JSDOM(html, {\n\t\tcontentType: HTML_CONTENT_TYPE,\n\t});\n\n\tconst document = dom.window.document;\n\treturn Array.from(document.querySelectorAll(selector));\n};\n","export const PACKAGE_ERROR_INTRO = \"Fetch-Dom error : \"\nexport const HTML_CONTENT_TYPE = \"text/html\";\nexport const VERSION = __VERSION__;","import { existsSync } from \"node:fs\";\nimport { VERSION } from \"./constants\";\nimport { FetchOptions } from \"./types\";\nimport { readFile } from \"node:fs/promises\";\n\nconst UA =
|
|
1
|
+
{"version":3,"sources":["../src/index.ts","../src/fetch.ts","../src/constants.ts","../src/validations.ts"],"sourcesContent":["import { FetchOptions } from \"./types\";\nimport { _fromFile, _fromHttp } from \"./fetch\";\nimport { validateOutputOption, validateSourceOption } from \"./validations\";\n\n/**\n *\n * @param source References the source from where to fetch the DOM. It can be an a relative file path or an URL\n * @param selector The query selector used to fetch elements from the DOM. (will run querySelectorAll)\n * @param options The FetchOptions needed for the requested elements\n * @returns\n */\nexport async function selectElements(\n\tsource: string,\n\tselector: string,\n\toptions?: FetchOptions\n) {\n\ttry {\n\t\tlet nodes: Array<Element> = [];\n\t\tconst fixedOptions = _initOptions(options);\n\t\tconst sourceOption = validateSourceOption(fixedOptions);\n\n\t\tif (sourceOption == \"url\") {\n\t\t\tnodes = await _fromHttp(source, selector);\n\t\t} else if (sourceOption == \"file\") {\n\t\t\tnodes = await _fromFile(source, selector);\n\t\t}\n\n\t\treturn nodes.map((el) => {\n\t\t\treturn _computed(el, fixedOptions);\n\t\t});\n\t} catch (error: any) {\n\t\treturn Promise.reject(error);\n\t}\n}\n\n// ============================= PRIVATE functions =============================\n\nconst _initOptions = (options: any = {}) => {\n\tconst { output = \"html\", source = \"url\" } = options;\n\treturn { output, source } as FetchOptions;\n};\n\nconst _computed = (el: Element, options: FetchOptions) => {\n\tlet result: any;\n\tconst output = validateOutputOption(options);\n\n\tswitch (output) {\n\t\tcase \"html\":\n\t\tcase \"children\":\n\t\t\tif (output == \"html\") {\n\t\t\t\tresult = el.outerHTML;\n\t\t\t} else {\n\t\t\t\tresult = el.innerHTML;\n\t\t\t}\n\t\t\tbreak;\n\t\tcase \"breakdown\":\n\t\t\tresult = {\n\t\t\t\ttag: el.tagName.toLowerCase(),\n\t\t\t\ttext: el.textContent?.trim() ?? \"\",\n\t\t\t\thtml: el.innerHTML,\n\t\t\t\tattributes: Object.fromEntries(\n\t\t\t\t\tArray.from(el.attributes).map((a) => [a.name, a.value])\n\t\t\t\t),\n\t\t\t};\n\t\t\tbreak;\n\t\tdefault:\n\t\t\tresult = el;\n\t}\n\treturn result;\n};\n","import { JSDOM } from \"jsdom\";\nimport { HTML_CONTENT_TYPE } from \"./constants\";\nimport {\n\tvalidateFileExistance,\n\tvalidateResource,\n} from \"./validations\";\n\nexport async function _fromHttp(\n\tsource: string,\n\tselector: string\n): Promise<Element[]> {\n\tconst res = await validateResource(source);\n\n\tconst html = await res.text();\n\n\tconst dom = new JSDOM(html, {\n\t\turl: source,\n\t\tcontentType: HTML_CONTENT_TYPE,\n\t});\n\n\tconst document = dom.window.document;\n\n\treturn Array.from(document.querySelectorAll(selector));\n}\n\nexport const _fromFile = async (source: string, selector: string) => {\n\tlet html = await validateFileExistance(source);\n\n\tconst dom = new JSDOM(html, {\n\t\tcontentType: HTML_CONTENT_TYPE,\n\t});\n\n\tconst document = dom.window.document;\n\treturn Array.from(document.querySelectorAll(selector));\n};\n","export const PACKAGE_ERROR_INTRO = \"Fetch-Dom error : \"\nexport const HTML_CONTENT_TYPE = \"text/html\";\nexport const VERSION = __VERSION__;","import { existsSync } from \"node:fs\";\nimport { VERSION } from \"./constants\";\nimport { FetchOptions } from \"./types\";\nimport { readFile } from \"node:fs/promises\";\n\nconst UA = `@maze014/dom-fetch/${VERSION}`;\n\nexport function validateOutputOption(options: FetchOptions) {\n\tconst output = options.output;\n\tif (!/^(?:object|html|children|breakdown)$/.test(output)) {\n\t\tthrow `output option not supported [\"${output}\"]`;\n\t}\n\treturn output;\n}\n\nexport function validateSourceOption(options: FetchOptions) {\n\tconst source = options.source;\n\tif (!/^(?:url|file)$/.test(source)) {\n\t\tthrow `source option not supported [\"${source}\"]`;\n\t}\n\treturn source;\n}\n\nexport function validateHTTPSource(source: string) {\n\tif (!source.startsWith(\"http\")) {\n\t\tthrow \"source given is not an URL\";\n\t}\n}\n\nexport async function validateResource(source: string) {\n\tconst res = await fetch(source, {\n\t\theaders: {\n\t\t\t\"User-Agent\": UA,\n\t\t\tAccept: \"text/html\",\n\t\t},\n\t});\n\n\tif (!res.ok) {\n\t\tthrow new Error(`Failed to fetch ${source}`);\n\t}\n\treturn res;\n}\n\nexport async function validateFileExistance(source: string) {\n\tif (!existsSync(source)) {\n\t\tthrow new Error(`no such file [\"${source}\"]`);\n\t}\n\treturn await readFile(source, \"utf-8\");\n}\n"],"mappings":"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","names":[]}
|
package/package.json
CHANGED
package/src/validations.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { VERSION } from "./constants";
|
|
|
3
3
|
import { FetchOptions } from "./types";
|
|
4
4
|
import { readFile } from "node:fs/promises";
|
|
5
5
|
|
|
6
|
-
const UA =
|
|
6
|
+
const UA = `@maze014/dom-fetch/${VERSION}`;
|
|
7
7
|
|
|
8
8
|
export function validateOutputOption(options: FetchOptions) {
|
|
9
9
|
const output = options.output;
|