janus-parse 1.0.4 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# janus-parse
+# janus-parse [![npm version](https://img.shields.io/npm/v/janus-parse?style=flat-round)](https://www.npmjs.com/package/janus-parse) ![language](https://img.shields.io/badge/Language-Typescript-blue?style=flat-round) [![release](https://github.com/Casneil/janus-parse/actions/workflows/publish.yml/badge.svg)](https://github.com/Casneil/janus-parse/actions/workflows/publish.yml) [![build](https://github.com/Casneil/janus-parse/actions/workflows/build.yml/badge.svg)](https://github.com/Casneil/janus-parse/actions/workflows/build.yml)
 
 A lightweight, high-performance, isomorphic HTML text extractor and sanitizer built entirely in TypeScript. It safely strips out targeted layout elements or malicious scripts and returns clean, whitespace-normalized text.
 
@@ -49,9 +49,7 @@ const rawHtml = `
   </main>
 `;
 
-const cleanText = await janusServer(rawHtml);
-console.log(cleanText);
-// Output: "Hello Universe This is a highly spaced sentence."
+const cleanText = await janusServer(rawHtml); // Output: "Hello Universe This is a highly spaced sentence."
 ```
 
 ### 2. Client-Side Execution (Browser)
@@ -64,9 +62,7 @@ import { janusClient } from "janus-parse";
 const webMarkup =
   "<div> Dynamic Web App <style>body { display: none; }</style></div>";
 
-const textOnly = janusClient(webMarkup);
-console.log(textOnly);
-// Output: " Dynamic Web App"
+const textOnly = janusClient(webMarkup); // Output: " Dynamic Web App"
 ```
 
 ### 3. Custom Configurations
@@ -75,8 +71,8 @@ You can modify which HTML tags are targeted for destruction by passing an option
 
 ```typescript
 const structuralConfig = {
-  addBlacklistTags: ["span", "section"], // Purge extra elements
-  removeBlacklistTags: ["script"], // Keep scripts if you are building an isolated sandbox
+  tagsToRemove: ["span", "section"] // Adds additonal blacklist candidates,
+  tagsToPreserve: ["script"] // Preserves script tag in output,
 };
 ```
 
@@ -87,9 +83,9 @@ const processedTextServer = await janusServer(htmlSource, structuralConfig);
 ```
 
 ```typescript
-import { janusClient } from 'janus-parse';
+import { janusClient } from "janus-parse";
 
-const processedTextClient = janusClienthtmlSource, structuralConfig);
+const processedTextClient = janusClient(htmlSource, structuralConfig);
 ```
 
 ---
@@ -101,19 +97,19 @@ const processedTextClient = janusClienthtmlSource, structuralConfig);
 TypeScript interface passed to fine-tune tag removal behaviors.
 
 ```typescript
-interface Config {
-  addBlacklistTags?: string[];
-  removeBlacklistTags?: string[];
+type Config {
+  tagsToRemove?: string[];
+  tagsToPreserve?: string[];
 }
 ```
 
-### `janusServer(text: string, config?: Config): Promise<string>`
+#### `janusServer(text: string, config?: Config): Promise<string>`
 
 - **`text`**: The input raw HTML string.
 - **`config`**: Optional rule blocks to override standard cleaning lists.
 - **Returns**: A promise that resolves to a stripped, whitespace-normalized single-line string.
 
-### `janusClient(text: string, config?: Config): string`
+#### `janusClient(text: string, config?: Config): string`
 
 - **`text`**: The input raw HTML string.
 - **`config`**: Optional rule blocks to override standard cleaning lists.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./janus-parse.js";
+export * from "./janus-parse";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -1 +1 @@
-export * from "./janus-parse.js";
+export * from "./janus-parse";

package/dist/janus-parse.d.ts

@@ -1,4 +1,4 @@
-import { Config } from "./utils/index.js";
+import type { Config } from "./utils";
 export declare function janusServer(text: string, config?: Config): Promise<string>;
-export declare function janusClient(text: string, config?: Config): string | null;
+export declare function janusClient(text: string, config?: Config): string;
 //# sourceMappingURL=janus-parse.d.ts.map

package/dist/janus-parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"janus-parse.d.ts","sourceRoot":"","sources":["../lib/janus-parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,MAAM,EAAW,MAAM,kBAAkB,CAAC;AAO9E,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAoB,mBAU3E;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAoB,iBAYrE"}
+{"version":3,"file":"janus-parse.d.ts","sourceRoot":"","sources":["../lib/janus-parse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAOtC,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAoB,mBAS3E;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAoB,UASrE"}

package/dist/janus-parse.js

@@ -1,25 +1,19 @@
-import { validateText, removeNodes, getTags } from "./utils/index.js";
+import { validateText, getTags, normalizeWhitespace, serialize } from "./utils";
 const janusConfig = {
-    addBlacklistTags: [],
-    removeBlacklistTags: [],
+    tagsToRemove: [],
+    tagsToPreserve: [],
 };
 export async function janusServer(text, config = janusConfig) {
     validateText(text);
-    const tags = getTags(config);
     const parser = await import("node-html-parser");
     const root = parser.parse(text);
-    const nodesToRemove = root.querySelectorAll(tags);
-    // @ts-expect-error
-    removeNodes(nodesToRemove);
-    return root.textContent.replace(new RegExp("\\s+", "g"), " ").trim();
+    const { removedTags, preservedTags } = getTags(config);
+    return normalizeWhitespace(serialize({ node: root, removedTags, preservedTags }));
 }
 export function janusClient(text, config = janusConfig) {
     validateText(text);
-    const tags = getTags(config);
     const parser = new DOMParser();
-    const virtualDoc = parser.parseFromString(text, "text/html");
-    const nodesToRemove = virtualDoc.querySelectorAll(tags);
-    removeNodes(nodesToRemove);
-    const cleanText = virtualDoc.body.textContent;
-    return cleanText;
+    const { removedTags, preservedTags } = getTags(config);
+    const root = parser.parseFromString(text, "text/html").body;
+    return normalizeWhitespace(serialize({ node: root, removedTags, preservedTags }));
 }

package/dist/utils/index.d.ts

@@ -1,8 +1,19 @@
+import type { HTMLElement as NodeHTMLElement } from "node-html-parser";
 export type Config = {
-    addBlacklistTags?: string[];
-    removeBlacklistTags?: string[];
+    tagsToRemove?: string[];
+    tagsToPreserve?: string[];
 };
 export declare function validateText(text: string): void;
-export declare function getTags(config: Config): string;
-export declare function removeNodes(nodesToRemove: HTMLElement[] | NodeListOf<Element>): NodeListOf<Element> | HTMLElement[];
+export declare function normalizeWhitespace(text?: string): string;
+export declare function getTags(config: Config): {
+    removedTags: Set<string>;
+    preservedTags: Set<string>;
+};
+export declare function serialize({ node, removedTags, preservedTags, }: {
+    node: Node;
+    removedTags: Set<string>;
+    preservedTags: Set<string>;
+}): string;
+type Node = NodeHTMLElement | ChildNode;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/utils/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG;IACnB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC,CAAC;AAIF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,QAUxC;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,UAWrC;AAED,wBAAgB,WAAW,CACzB,aAAa,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,uCAOnD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEvE,MAAM,MAAM,MAAM,GAAG;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAIF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,QAUxC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,SAAK,UAE5C;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM;;;EAiBrC;AAED,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,WAAW,EACX,aAAa,GACd,EAAE;IACD,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC5B,GAAG,MAAM,CAgCT;AAwBD,KAAK,IAAI,GAAG,eAAe,GAAG,SAAS,CAAC"}

package/dist/utils/index.js

@@ -5,33 +5,64 @@ export function validateText(text) {
         throw new Error("The text is not a valid string. Please provide a valid string to parse.", { cause: text });
     }
 }
+export function normalizeWhitespace(text = "") {
+    return text.replace(new RegExp(String.raw `\s+`, "g"), " ").trim();
+}
 export function getTags(config) {
-    let tags = new Set();
-    if (config.addBlacklistTags) {
-        tags = addBlackListTags(config.addBlacklistTags);
+    const removedTags = new Set(defaultBlacklistTags);
+    const preservedTags = new Set();
+    if (config.tagsToRemove) {
+        addBlackListTags(removedTags, config.tagsToRemove);
     }
-    if (config.removeBlacklistTags) {
-        tags = removeBlackListTags(config.removeBlacklistTags);
+    if (config.tagsToPreserve) {
+        removeBlackListTags({
+            removedTags,
+            preservedTags,
+            tagsToPreserve: config.tagsToPreserve,
+        });
     }
-    return [...tags].join(",");
+    return { removedTags, preservedTags };
 }
-export function removeNodes(nodesToRemove) {
-    for (const node of nodesToRemove) {
-        node.remove();
+export function serialize({ node, removedTags, preservedTags, }) {
+    if (!node)
+        return "";
+    if (node.nodeType === 3) {
+        // DOM Text node => 3
+        const rawText = validateNode(node, "rawText");
+        const text = validateNode(node, "text");
+        return rawText ?? text ?? node.textContent ?? "";
+    }
+    const tagName = validateNode(node, "tagName") ?? "";
+    const tag = tagName.toLowerCase();
+    //  Completely ignore blacklisted tags
+    if (removedTags.has(tag))
+        return "";
+    //  Keep preserved tags intact along with their outer HTML structure
+    if (preservedTags.has(tag)) {
+        const outerHTML = validateNode(node, "outerHTML");
+        return (outerHTML ??
+            (typeof node.toString === "function" ? node.toString() : undefined) ??
+            "");
     }
-    return nodesToRemove;
+    const children = [...node.childNodes];
+    return children
+        .map((child) => serialize({ node: child, removedTags, preservedTags }))
+        .join("");
 }
-function removeBlackListTags(removeBlacklistTags) {
-    const blacklistTags = new Set(defaultBlacklistTags);
-    for (const tag of removeBlacklistTags) {
-        blacklistTags.delete(tag);
+function removeBlackListTags({ removedTags, preservedTags, tagsToPreserve, }) {
+    for (const tag of tagsToPreserve) {
+        const normalized = tag.toLowerCase();
+        removedTags.delete(normalized);
+        preservedTags.add(normalized);
     }
-    return blacklistTags;
 }
-function addBlackListTags(addBlacklistTags) {
-    const blacklistTags = new Set(defaultBlacklistTags);
-    for (const tag of addBlacklistTags) {
-        blacklistTags.add(tag);
+function addBlackListTags(preserveTags, tagsToRemove) {
+    for (const tag of tagsToRemove) {
+        preserveTags.add(tag.toLowerCase());
     }
-    return blacklistTags;
+}
+function validateNode(node, lookup = "outerHTML") {
+    const targetNode = node;
+    const value = targetNode[lookup];
+    return value ?? undefined;
 }

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "janus-parse",
   "license": "MIT",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "packageManager": "pnpm@11.15.1",
   "keywords": [
     "html-parser",
     "text-extractor",
@@ -44,9 +45,11 @@
   "type": "module",
   "prepack": "pnpm build",
   "scripts": {
-    "janus": "tsx ./lib/index.ts",
+    "janus": "tsx ./lib",
     "test": "vitest",
+    "code:lint": "pnpm eslint --flag unstable_native_nodejs_ts_config --cache .",
     "fmt": "prettier --write .",
+    "type:check": "tsc --noEmit",
     "build": "tsc",
     "prepublishOnly": "pnpm build"
   },
@@ -54,18 +57,24 @@
     "node-html-parser": "9.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/github": "^12.0.9",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/node": "^26.1.1",
     "eslint": "^10.7.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-unicorn": "^72.0.0",
     "happy-dom": "^20.11.0",
-    "prettier": "^3.9.5",
+    "prettier": "^3.9.6",
     "semantic-release": "^25.0.8",
     "tsx": "4.23.1",
-    "typescript": "5.7.2",
+    "typescript": "6.0.3",
+    "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   },
-  "prettier": {}
+  "prettier": {},
+  "--Typescript V 7--": "cannot use TS v7 until typescript-eslint adds support"
 }