@maze014/dom-fetch 1.0.0 → 1.0.2
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/LICENSE +21 -0
- package/README.md +15 -15
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +13 -2
- package/src/validations.ts +1 -1
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Jean Luc Emmanuel VERHANNEMAN
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
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
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@maze014/dom-fetch",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"main": "dist/index.js",
|
|
5
5
|
"description": "Fetch and extract DOM elements from a URL or local HTML file using a CSS query selector.",
|
|
6
6
|
"type": "commonjs",
|
|
@@ -24,5 +24,16 @@
|
|
|
24
24
|
"homepage": "https://github.com/ManuUseGitHub/domFetch#readme",
|
|
25
25
|
"author": "Jean Luc Emmanuel VERHANNEMAN",
|
|
26
26
|
"license": "MIT",
|
|
27
|
-
"types": "./dist/index.d.ts"
|
|
27
|
+
"types": "./dist/index.d.ts",
|
|
28
|
+
"keywords": [
|
|
29
|
+
"file",
|
|
30
|
+
"dom",
|
|
31
|
+
"url",
|
|
32
|
+
"path",
|
|
33
|
+
"html",
|
|
34
|
+
"async",
|
|
35
|
+
"jsdom",
|
|
36
|
+
"helper",
|
|
37
|
+
"utility"
|
|
38
|
+
]
|
|
28
39
|
}
|
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;
|