@maze014/dom-fetch 1.0.0

package/README.md

@@ -0,0 +1,174 @@
+# domFetch
+
+Fetch and extract DOM elements from a **URL or local HTML file** using a CSS query selector.
+
+`dom-fetch` lets you retrieve HTML elements and choose how they are represented (raw element, HTML string, children HTML, or a structured breakdown).
+
+---
+
+## Installation
+
+```bash
+$ npm install dom-fetch
+```
+
+---
+
+## Usage
+
+### Basic example (fetch from a URL)
+
+```ts
+import { selectElements } from "dom-fetch";
+
+const elements = await selectElements(
+  "https://example.com",
+  "h1"
+);
+
+console.log(elements);
+```
+
+By default:
+- `source` is `"url"`
+- `output` is `"html"`
+
+So this returns an array of `outerHTML` strings.
+
+---
+
+### Fetch from a local HTML file
+
+```ts
+const elements = await selectElements(
+  "./index.html",
+  ".article",
+  { source: "file" }
+);
+```
+
+---
+
+### Change output format
+
+```ts
+const elements = await selectElements(
+  "https://example.com",
+  "a",
+  { output: "breakdown" }
+);
+```
+
+---
+
+## Output formats
+
+The `output` option controls how each matched element is returned.
+
+| Output value | Description |
+|-------------|------------|
+| `"html"` | The full HTML of the matched element (`outerHTML`) |
+| `"children"` | The inner HTML of the matched element |
+| `"object"` | The raw DOM `Element` |
+| `"breakdown"` | A structured object describing the element |
+
+### Breakdown output example
+
+```ts
+{
+  tag: "a",
+  text: "Click here",
+  html: "Click here",
+  attributes: {
+    href: "/about",
+    class: "link"
+  }
+}
+```
+
+### Within a node script from a resource
+
+First, create a simple js file that displays the paragraphs of the NodeJS page
+
+```js
+// nodeParagraphs.mjs
+
+const source = "https://nodejs.org/en/learn/getting-started/introduction-to-nodejs";
+const selector = "main p";
+
+const paragraphs = await selectElements(source, selector)
+
+console.log(paragraphs.join(""))
+```
+
+Then write out in an html file
+```bash
+$ node nodeParagraphs.mjs > paragraphs.html
+```
+
+### Within a node script from a local file
+
+First, create a simple js file that displays the paragraphs of the NodeJS page
+
+```js
+// nodeParagraphs.mjs
+
+const source = "./example/nodePage.html";
+const selector = "main p";
+const options = { source : 'file' };
+
+const paragraphs = await selectElements(source, selector, options)
+
+console.log(paragraphs.join(""))
+```
+
+Then write out in an html file
+```bash
+$ node nodeParagraphs.mjs > paragraphs.html
+``` 
+
+---
+
+## API
+
+### `selectElements(source: string, selector: string, options?: FetchOptions): Promise<any[]>`
+
+Fetches elements matching a CSS selector from a given source.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+|---------|------|---------|-------------|
+| `source` | `string` | — | URL or relative file path containing HTML |
+| `selector` | `string` | — | CSS selector (uses `querySelectorAll`) |
+| `options.output` | `"object" \| "html" \| "children" \| "breakdown"` | `"html"` | Format of returned elements |
+| `options.source` | `"url" \| "file"` | `"url"` | Defines how the source is fetched |
+
+#### Returns
+
+**`Promise<any[]>`**  
+An array of elements formatted according to the selected `output` option.
+
+---
+
+## FetchOptions
+
+```ts
+type FetchOptions = {
+  output?: "object" | "html" | "children" | "breakdown";
+  source?: "url" | "file";
+};
+```
+
+---
+
+## Tests
+
+A test project is available via [this repository](https://github.com/ManuUseGitHub/domFetchTest).
+
+
+---
+
+## License
+
+[MIT](https://github.com/ManuUseGitHub/domFetch?tab=MIT-1-ov-file#readme)

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Defines the kind of representation you can get from the request
+ * object : the element itself
+ * html : the targeted elements HTML. The root element being the element matched by the queryy selector
+ * children : the HTML of the children from the targeted elements matched
+ * breakdown : the brokendown element
+ */
+type FetchOutput = "object" | "html" | "children" | "breakdown";
+/**
+ * Defines the kind of sourse to fetch from or read from
+ * file : the source should be a file defined by a relative path
+ * url : the source should be the response of a fetched resource through the HTTP GET method
+ */
+type FetchSource = "file" | "url";
+/**
+ * Defines how the request should work to fetch the element of a given source kind
+ */
+type FetchOptions = {
+    output: FetchOutput;
+    source: FetchSource;
+};
+
+/**
+ *
+ * @param source References the source from where to fetch the DOM. It can be an a relative file path or an URL
+ * @param selector The query selector used to fetch elements from the DOM. (will run querySelectorAll)
+ * @param options The FetchOptions needed for the requested elements
+ * @returns
+ */
+declare function selectElements(source: string, selector: string, options?: FetchOptions): Promise<any[]>;
+
+export { selectElements };

package/dist/index.js

@@ -0,0 +1,143 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  selectElements: () => selectElements
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/fetch.ts
+var import_jsdom = require("jsdom");
+
+// src/constants.ts
+var HTML_CONTENT_TYPE = "text/html";
+var VERSION = "1.0.0";
+
+// src/validations.ts
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var UA = `dom-fetch/${VERSION}`;
+function validateOutputOption(options) {
+  const output = options.output;
+  if (!/^(?:object|html|children|breakdown)$/.test(output)) {
+    throw `output option not supported ["${output}"]`;
+  }
+  return output;
+}
+function validateSourceOption(options) {
+  const source = options.source;
+  if (!/^(?:url|file)$/.test(source)) {
+    throw `source option not supported ["${source}"]`;
+  }
+  return source;
+}
+async function validateResource(source) {
+  const res = await fetch(source, {
+    headers: {
+      "User-Agent": UA,
+      Accept: "text/html"
+    }
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${source}`);
+  }
+  return res;
+}
+async function validateFileExistance(source) {
+  if (!(0, import_node_fs.existsSync)(source)) {
+    throw new Error(`no such file ["${source}"]`);
+  }
+  return await (0, import_promises.readFile)(source, "utf-8");
+}
+
+// src/fetch.ts
+async function _fromHttp(source, selector) {
+  const res = await validateResource(source);
+  const html = await res.text();
+  const dom = new import_jsdom.JSDOM(html, {
+    url: source,
+    contentType: HTML_CONTENT_TYPE
+  });
+  const document = dom.window.document;
+  return Array.from(document.querySelectorAll(selector));
+}
+var _fromFile = async (source, selector) => {
+  let html = await validateFileExistance(source);
+  const dom = new import_jsdom.JSDOM(html, {
+    contentType: HTML_CONTENT_TYPE
+  });
+  const document = dom.window.document;
+  return Array.from(document.querySelectorAll(selector));
+};
+
+// src/index.ts
+async function selectElements(source, selector, options) {
+  try {
+    let nodes = [];
+    const fixedOptions = _initOptions(options);
+    const sourceOption = validateSourceOption(fixedOptions);
+    if (sourceOption == "url") {
+      nodes = await _fromHttp(source, selector);
+    } else if (sourceOption == "file") {
+      nodes = await _fromFile(source, selector);
+    }
+    return nodes.map((el) => {
+      return _computed(el, fixedOptions);
+    });
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+var _initOptions = (options = {}) => {
+  const { output = "html", source = "url" } = options;
+  return { output, source };
+};
+var _computed = (el, options) => {
+  let result;
+  const output = validateOutputOption(options);
+  switch (output) {
+    case "html":
+    case "children":
+      if (output == "html") {
+        result = el.outerHTML;
+      } else {
+        result = el.innerHTML;
+      }
+      break;
+    case "breakdown":
+      result = {
+        tag: el.tagName.toLowerCase(),
+        text: el.textContent?.trim() ?? "",
+        html: el.innerHTML,
+        attributes: Object.fromEntries(
+          Array.from(el.attributes).map((a) => [a.name, a.value])
+        )
+      };
+      break;
+    default:
+      result = el;
+  }
+  return result;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  selectElements
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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 = `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

@@ -0,0 +1,28 @@
+{
+  "name": "@maze014/dom-fetch",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "description": "Fetch and extract DOM elements from a URL or local HTML file using a CSS query selector.",
+  "type": "commonjs",
+  "devDependencies": {
+    "@types/jsdom": "^27.0.0",
+    "jsmin": "^1.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ManuUseGitHub/domFetch.git"
+  },
+  "dependencies": {
+    "jsdom": "^27.4.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist; tsup",
+    "dev": "tsup --watch"
+  },
+  "homepage": "https://github.com/ManuUseGitHub/domFetch#readme",
+  "author": "Jean Luc Emmanuel VERHANNEMAN",
+  "license": "MIT",
+  "types": "./dist/index.d.ts"
+}

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const PACKAGE_ERROR_INTRO = "Fetch-Dom error : "
+export const HTML_CONTENT_TYPE = "text/html";
+export const VERSION = __VERSION__;

package/src/env.d.ts

@@ -0,0 +1 @@
+declare const __VERSION__: string;

package/src/fetch.ts

@@ -0,0 +1,35 @@
+import { JSDOM } from "jsdom";
+import { HTML_CONTENT_TYPE } from "./constants";
+import {
+	validateFileExistance,
+	validateResource,
+} from "./validations";
+
+export async function _fromHttp(
+	source: string,
+	selector: string
+): Promise<Element[]> {
+	const res = await validateResource(source);
+
+	const html = await res.text();
+
+	const dom = new JSDOM(html, {
+		url: source,
+		contentType: HTML_CONTENT_TYPE,
+	});
+
+	const document = dom.window.document;
+
+	return Array.from(document.querySelectorAll(selector));
+}
+
+export const _fromFile = async (source: string, selector: string) => {
+	let html = await validateFileExistance(source);
+
+	const dom = new JSDOM(html, {
+		contentType: HTML_CONTENT_TYPE,
+	});
+
+	const document = dom.window.document;
+	return Array.from(document.querySelectorAll(selector));
+};

package/src/index.ts

@@ -0,0 +1,70 @@
+import { FetchOptions } from "./types";
+import { _fromFile, _fromHttp } from "./fetch";
+import { validateOutputOption, validateSourceOption } from "./validations";
+
+/**
+ *
+ * @param source References the source from where to fetch the DOM. It can be an a relative file path or an URL
+ * @param selector The query selector used to fetch elements from the DOM. (will run querySelectorAll)
+ * @param options The FetchOptions needed for the requested elements
+ * @returns
+ */
+export async function selectElements(
+	source: string,
+	selector: string,
+	options?: FetchOptions
+) {
+	try {
+		let nodes: Array<Element> = [];
+		const fixedOptions = _initOptions(options);
+		const sourceOption = validateSourceOption(fixedOptions);
+
+		if (sourceOption == "url") {
+			nodes = await _fromHttp(source, selector);
+		} else if (sourceOption == "file") {
+			nodes = await _fromFile(source, selector);
+		}
+
+		return nodes.map((el) => {
+			return _computed(el, fixedOptions);
+		});
+	} catch (error: any) {
+		return Promise.reject(error);
+	}
+}
+
+// ============================= PRIVATE functions =============================
+
+const _initOptions = (options: any = {}) => {
+	const { output = "html", source = "url" } = options;
+	return { output, source } as FetchOptions;
+};
+
+const _computed = (el: Element, options: FetchOptions) => {
+	let result: any;
+	const output = validateOutputOption(options);
+
+	switch (output) {
+		case "html":
+		case "children":
+			if (output == "html") {
+				result = el.outerHTML;
+			} else {
+				result = el.innerHTML;
+			}
+			break;
+		case "breakdown":
+			result = {
+				tag: el.tagName.toLowerCase(),
+				text: el.textContent?.trim() ?? "",
+				html: el.innerHTML,
+				attributes: Object.fromEntries(
+					Array.from(el.attributes).map((a) => [a.name, a.value])
+				),
+			};
+			break;
+		default:
+			result = el;
+	}
+	return result;
+};

package/src/types.ts

@@ -0,0 +1,24 @@
+
+/**
+ * Defines the kind of representation you can get from the request
+ * object : the element itself
+ * html : the targeted elements HTML. The root element being the element matched by the queryy selector
+ * children : the HTML of the children from the targeted elements matched
+ * breakdown : the brokendown element
+ */
+export type FetchOutput = "object" | "html" | "children" | "breakdown";
+
+/**
+ * Defines the kind of sourse to fetch from or read from
+ * file : the source should be a file defined by a relative path
+ * url : the source should be the response of a fetched resource through the HTTP GET method
+ */
+export type FetchSource = "file" | "url";
+
+/**
+ * Defines how the request should work to fetch the element of a given source kind
+ */
+export type FetchOptions = {
+    output: FetchOutput;
+    source: FetchSource;
+};

package/src/validations.ts

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs";
+import { VERSION } from "./constants";
+import { FetchOptions } from "./types";
+import { readFile } from "node:fs/promises";
+
+const UA = `dom-fetch/${VERSION}`;
+
+export function validateOutputOption(options: FetchOptions) {
+	const output = options.output;
+	if (!/^(?:object|html|children|breakdown)$/.test(output)) {
+		throw `output option not supported ["${output}"]`;
+	}
+	return output;
+}
+
+export function validateSourceOption(options: FetchOptions) {
+	const source = options.source;
+	if (!/^(?:url|file)$/.test(source)) {
+		throw `source option not supported ["${source}"]`;
+	}
+	return source;
+}
+
+export function validateHTTPSource(source: string) {
+	if (!source.startsWith("http")) {
+		throw "source given is not an URL";
+	}
+}
+
+export async function validateResource(source: string) {
+	const res = await fetch(source, {
+		headers: {
+			"User-Agent": UA,
+			Accept: "text/html",
+		},
+	});
+
+	if (!res.ok) {
+		throw new Error(`Failed to fetch ${source}`);
+	}
+	return res;
+}
+
+export async function validateFileExistance(source: string) {
+	if (!existsSync(source)) {
+		throw new Error(`no such file ["${source}"]`);
+	}
+	return await readFile(source, "utf-8");
+}

package/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "tsup";
+import pkg from "./package.json";
+console.log(pkg.version)
+export default defineConfig({
+	entry: ["src/index.ts"],
+	outDir: 'dist',
+	format: ["cjs"], // Node-friendly
+	target: "node18",
+	bundle: true, // 👈 single file
+	splitting: false, // 👈 force ONE file
+	sourcemap: true,
+	clean: true,
+	dts: true, // generates index.d.ts
+	define: {
+		__VERSION__: JSON.stringify(pkg.version),
+	},
+});