html-fetch-parser 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Auto Publish to NPM
+
+on:
+  push:
+    paths:
+      - "package.json"
+      - ".github/workflows/publish.yml"
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18"
+          registry-url: "https://registry.npmjs.org"
+
+
+      - name: Check version update
+        id: version-check
+        run: |
+          CURRENT_VERSION=$(node -pe "require('./package.json').version")
+          echo "CURRENT_VERSION=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+          echo "📦 Current Version: $CURRENT_VERSION"
+
+      - name: Publish to NPM
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+        with:
+          tag_name: v${{ steps.version-check.outputs.CURRENT_VERSION }}
+          release_name: Release v${{ steps.version-check.outputs.CURRENT_VERSION }}
+          body: |
+            # 🚀 New Release v${{ steps.version-check.outputs.CURRENT_VERSION }}
+          draft: false
+          prerelease: false
+
+      - name: Success notification
+        run: echo "✅ Published html-fetch-parser@${{ steps.version-check.outputs.CURRENT_VERSION }} to NPM"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaze
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,280 @@
+# HTML Fetch Parser
+
+Lightweight and powerful HTML fetching, parsing, and manipulation library for Node.js. Combines the best features of fetch, axios, and cheerio in one simple package.
+
+## Features
+
+- **Easy HTML Fetching** - Built-in HTTP client with timeout support
+- **Powerful Parsing** - CSS selector-based HTML parsing
+- **Simple API** - Intuitive chainable methods
+- **Zero Heavy Dependencies** - Uses lightweight `node-html-parser`
+- **TypeScript Support** - Full TypeScript definitions included
+- **Utility Functions** - HTML manipulation helpers built-in
+
+## Installation
+
+```bash
+npm install html-fetch-parser
+```
+
+## Quick Start
+
+### Fetch and Parse Remote HTML
+
+```javascript
+const { fetch } = require('html-fetch-parser');
+
+const parser = await fetch('https://example.com');
+console.log(parser.getTitle());
+console.log(parser.text('h1'));
+console.log(parser.getLinks());
+```
+
+### Load and Parse Local HTML
+
+```javascript
+const HtmlFetchParser = require('html-fetch-parser');
+
+const html = '<h1>Hello World</h1><p>Welcome</p>';
+const parser = new HtmlFetchParser();
+parser.load(html);
+
+console.log(parser.text('h1'));
+```
+
+## API Reference
+
+### Main Class
+
+#### `new HtmlFetchParser(options)`
+
+Create a new instance.
+
+**Options:**
+- `headers` - Default HTTP headers
+- `timeout` - Request timeout in milliseconds (default: 10000)
+
+#### Methods
+
+**Fetching:**
+- `fetch(url, options)` - Fetch HTML from URL
+- `post(url, data, options)` - POST request
+- `load(html)` - Load HTML string
+
+**Querying:**
+- `$(selector)` - Get single element (alias for querySelector)
+- `$$(selector)` - Get all elements (alias for querySelectorAll)
+- `text(selector)` - Get text content
+- `textAll(selector)` - Get all text contents
+- `attr(selector, attr)` - Get attribute value
+- `attrAll(selector, attr)` - Get all attribute values
+- `html(selector)` - Get inner HTML
+
+**Data Extraction:**
+- `extract(schema)` - Extract data using schema
+- `getTitle()` - Get page title
+- `getMeta(name)` - Get meta tag content
+- `getLinks()` - Get all links
+- `getImages()` - Get all images
+- `getRawHtml()` - Get raw HTML string
+
+### Extract Schema
+
+Extract structured data easily:
+
+```javascript
+const data = parser.extract({
+  title: 'h1',
+  description: '.intro',
+  links: {
+    selector: 'a',
+    attr: 'href',
+    multiple: true
+  },
+  prices: {
+    selector: '.price',
+    multiple: true,
+    transform: (value) => parseFloat(value.replace('$', ''))
+  }
+});
+```
+
+**Schema Options:**
+- `selector` (required) - CSS selector
+- `attr` - Attribute name to extract
+- `multiple` - Extract from all matching elements
+- `transform` - Transform function
+
+### Manipulator Class
+
+Static utility methods for HTML manipulation:
+
+```javascript
+const { Manipulator } = require('html-fetch-parser');
+
+Manipulator.stripTags(html);
+Manipulator.decodeEntities(html);
+Manipulator.extractUrls(html, baseUrl);
+Manipulator.extractEmails(html);
+Manipulator.cleanWhitespace(text);
+Manipulator.truncate(text, length, suffix);
+Manipulator.toAbsoluteUrl(url, baseUrl);
+Manipulator.removeScriptsAndStyles(html);
+Manipulator.wordCount(text);
+Manipulator.sanitizeFilename(filename);
+Manipulator.extractStructuredData(html);
+```
+
+## Examples
+
+### Basic Usage
+
+```javascript
+const HtmlFetchParser = require('html-fetch-parser');
+
+const html = `
+  <div>
+    <h1>Products</h1>
+    <div class="product">
+      <h2>Product 1</h2>
+      <span class="price">$19.99</span>
+    </div>
+    <div class="product">
+      <h2>Product 2</h2>
+      <span class="price">$29.99</span>
+    </div>
+  </div>
+`;
+
+const parser = new HtmlFetchParser();
+parser.load(html);
+
+const products = parser.extract({
+  title: 'h1',
+  products: {
+    selector: '.product h2',
+    multiple: true
+  },
+  prices: {
+    selector: '.price',
+    multiple: true
+  }
+});
+
+console.log(products);
+```
+
+### Fetch Remote HTML
+
+```javascript
+const { fetch } = require('html-fetch-parser');
+
+async function scrapeWebsite() {
+  const parser = await fetch('https://example.com', {
+    headers: {
+      'User-Agent': 'My Scraper Bot'
+    }
+  });
+
+  const data = parser.extract({
+    title: 'h1',
+    description: 'meta[name="description"]',
+    links: {
+      selector: 'a',
+      attr: 'href',
+      multiple: true
+    }
+  });
+
+  return data;
+}
+```
+
+### Custom Fetcher
+
+```javascript
+const { Fetcher } = require('html-fetch-parser');
+
+const fetcher = new Fetcher({
+  timeout: 5000,
+  headers: {
+    'User-Agent': 'Custom Bot'
+  }
+});
+
+const html = await fetcher.get('https://example.com');
+```
+
+### HTML Manipulation
+
+```javascript
+const { Manipulator, load } = require('html-fetch-parser');
+
+const html = '<p>Hello &amp; welcome!</p>';
+
+const clean = Manipulator.decodeEntities(html);
+const text = Manipulator.stripTags(clean);
+const truncated = Manipulator.truncate(text, 10);
+
+console.log(truncated);
+```
+
+## Advanced Usage
+
+### Chaining Methods
+
+```javascript
+const data = await fetch('https://example.com')
+  .then(parser => parser.extract({
+    title: 'h1',
+    content: '.content'
+  }));
+```
+
+### Error Handling
+
+```javascript
+try {
+  const parser = await fetch('https://example.com');
+  console.log(parser.getTitle());
+} catch (error) {
+  console.error('Failed to fetch:', error.message);
+}
+```
+
+### Custom Timeout
+
+```javascript
+const parser = new HtmlFetchParser({ timeout: 30000 });
+await parser.fetch('https://slow-website.com');
+```
+
+## TypeScript
+
+Full TypeScript support included:
+
+```typescript
+import HtmlFetchParser, { fetch, Manipulator } from 'html-fetch-parser';
+
+const parser: HtmlFetchParser = await fetch('https://example.com');
+const title: string = parser.getTitle();
+```
+
+## Performance
+
+- Lightweight with minimal dependencies
+- Fast HTML parsing using node-html-parser
+- Native fetch API for HTTP requests
+- Memory efficient
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues and questions, please open an issue on GitHub.

package/example/advanced-scraping.js

@@ -0,0 +1,150 @@
+const HtmlFetchParser = require('../index');
+const { Manipulator } = require('../index');
+
+async function advancedScrapingExample() {
+  console.log('=== Advanced Web Scraping Example ===\n');
+
+  const html = `
+    <!DOCTYPE html>
+    <html lang="en">
+      <head>
+        <title>E-Commerce Store</title>
+        <meta name="description" content="Best products online">
+        <script type="application/ld+json">
+          {
+            "@context": "https://schema.org",
+            "@type": "Product",
+            "name": "Example Product"
+          }
+        </script>
+      </head>
+      <body>
+        <header>
+          <nav>
+            <a href="/home">Home</a>
+            <a href="/products">Products</a>
+            <a href="/about">About</a>
+          </nav>
+        </header>
+
+        <main>
+          <h1>Featured Products</h1>
+
+          <article class="product" data-id="1">
+            <h2 class="product-name">Laptop Pro</h2>
+            <p class="description">High-performance laptop for professionals</p>
+            <span class="price" data-currency="USD">$1,299.99</span>
+            <span class="stock">In Stock</span>
+            <a href="/products/laptop-pro" class="btn">View Details</a>
+          </article>
+
+          <article class="product" data-id="2">
+            <h2 class="product-name">Wireless Mouse</h2>
+            <p class="description">Ergonomic wireless mouse with long battery life</p>
+            <span class="price" data-currency="USD">$49.99</span>
+            <span class="stock">Low Stock</span>
+            <a href="/products/wireless-mouse" class="btn">View Details</a>
+          </article>
+
+          <article class="product" data-id="3">
+            <h2 class="product-name">USB-C Cable</h2>
+            <p class="description">Fast charging USB-C cable, 6ft length</p>
+            <span class="price" data-currency="USD">$12.99</span>
+            <span class="stock">In Stock</span>
+            <a href="/products/usb-c-cable" class="btn">View Details</a>
+          </article>
+        </main>
+
+        <footer>
+          <p>Contact: sales@example.com | support@example.com</p>
+          <p>Visit our blog: https://blog.example.com</p>
+        </footer>
+      </body>
+    </html>
+  `;
+
+  const parser = new HtmlFetchParser();
+  parser.load(html);
+
+  console.log('=== Page Metadata ===');
+  console.log('Title:', parser.getTitle());
+  console.log('Description:', parser.getMeta('description'));
+  console.log();
+
+  console.log('=== Navigation Links ===');
+  const navLinks = parser.extract({
+    links: {
+      selector: 'nav a',
+      attr: 'href',
+      multiple: true
+    }
+  });
+  console.log(navLinks);
+  console.log();
+
+  console.log('=== Extract All Products ===');
+  const products = [];
+  const productElements = parser.$$('.product');
+
+  productElements.forEach(productEl => {
+    const tempParser = new HtmlFetchParser();
+    tempParser.load(productEl.outerHTML);
+
+    products.push({
+      id: productEl.getAttribute('data-id'),
+      name: tempParser.text('.product-name'),
+      description: tempParser.text('.description'),
+      price: tempParser.text('.price'),
+      priceNumeric: parseFloat(tempParser.text('.price').replace(/[^0-9.]/g, '')),
+      stock: tempParser.text('.stock'),
+      url: tempParser.attr('.btn', 'href')
+    });
+  });
+
+  console.log(JSON.stringify(products, null, 2));
+  console.log();
+
+  console.log('=== Statistics ===');
+  const totalProducts = products.length;
+  const inStockProducts = products.filter(p => p.stock === 'In Stock').length;
+  const avgPrice = products.reduce((sum, p) => sum + p.priceNumeric, 0) / totalProducts;
+
+  console.log(`Total Products: ${totalProducts}`);
+  console.log(`In Stock: ${inStockProducts}`);
+  console.log(`Average Price: $${avgPrice.toFixed(2)}`);
+  console.log();
+
+  console.log('=== Extract Contact Information ===');
+  const footerText = parser.text('footer');
+  const emails = Manipulator.extractEmails(footerText);
+  const urls = Manipulator.extractUrls(footerText);
+
+  console.log('Email addresses:', emails);
+  console.log('URLs:', urls);
+  console.log();
+
+  console.log('=== Structured Data ===');
+  const structuredData = Manipulator.extractStructuredData(parser.getRawHtml());
+  console.log(JSON.stringify(structuredData, null, 2));
+  console.log();
+
+  console.log('=== Text Analysis ===');
+  const mainContent = parser.text('main');
+  const cleanText = Manipulator.cleanWhitespace(mainContent);
+  const wordCount = Manipulator.wordCount(cleanText);
+  const preview = Manipulator.truncate(cleanText, 100);
+
+  console.log(`Word Count: ${wordCount}`);
+  console.log(`Preview: ${preview}`);
+  console.log();
+
+  console.log('=== Convert URLs to Absolute ===');
+  const baseUrl = 'https://example.com';
+  const absoluteUrls = products.map(p => ({
+    name: p.name,
+    url: Manipulator.toAbsoluteUrl(p.url, baseUrl)
+  }));
+  console.log(absoluteUrls);
+}
+
+advancedScrapingExample().catch(console.error);

package/example/basic-usage.js

@@ -0,0 +1,57 @@
+const HtmlFetchParser = require('../index');
+
+async function basicExample() {
+  console.log('=== HTML Fetch Parser - Basic Usage ===\n');
+
+  const html = `
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>Sample Page</title>
+        <meta name="description" content="This is a sample page">
+      </head>
+      <body>
+        <h1>Welcome to HTML Fetch Parser</h1>
+        <p class="intro">A lightweight library for HTML manipulation</p>
+        <div class="content">
+          <h2>Features</h2>
+          <ul>
+            <li>Easy HTML fetching</li>
+            <li>Powerful parsing</li>
+            <li>Simple manipulation</li>
+          </ul>
+        </div>
+        <a href="/docs" title="Documentation">Read Docs</a>
+        <img src="/logo.png" alt="Logo">
+      </body>
+    </html>
+  `;
+
+  const parser = new HtmlFetchParser();
+  parser.load(html);
+
+  console.log('Title:', parser.getTitle());
+  console.log('Meta description:', parser.getMeta('description'));
+  console.log('H1 text:', parser.text('h1'));
+  console.log('Intro text:', parser.text('.intro'));
+  console.log('All list items:', parser.textAll('li'));
+  console.log('Links:', parser.getLinks());
+  console.log('Images:', parser.getImages());
+
+  console.log('\n=== Extract with Schema ===');
+  const data = parser.extract({
+    title: 'h1',
+    intro: '.intro',
+    features: {
+      selector: 'li',
+      multiple: true
+    },
+    linkHref: {
+      selector: 'a',
+      attr: 'href'
+    }
+  });
+  console.log(data);
+}
+
+basicExample().catch(console.error);

package/example/fetch-example.js

@@ -0,0 +1,27 @@
+const { fetch } = require('../index');
+
+async function fetchExample() {
+  console.log('=== Fetch Remote HTML Example ===\n');
+
+  try {
+    const parser = await fetch('https://freepublicapisss.vercel.app/');
+
+    console.log('Title:', parser.getTitle());
+    console.log('First paragraph:', parser.text('p'));
+    console.log('All links:', parser.getLinks());
+
+    const data = parser.extract({
+      title: 'h1',
+      paragraphs: {
+        selector: 'p',
+        multiple: true
+      }
+    });
+
+    console.log('\nExtracted data:', data);
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+fetchExample();

package/example/manipulator-example.js

@@ -0,0 +1,39 @@
+const { Manipulator } = require('../index');
+
+console.log('=== Manipulator Example ===\n');
+
+const html = `
+  <div>
+    <h1>Hello &amp; Welcome!</h1>
+    <p>Contact us at: info@example.com or support@test.com</p>
+    <script>alert('test');</script>
+    <p>Visit https://example.com for more info</p>
+  </div>
+`;
+
+console.log('Original HTML:');
+console.log(html);
+
+console.log('\nStrip tags:');
+console.log(Manipulator.stripTags(html));
+
+console.log('\nDecode entities:');
+console.log(Manipulator.decodeEntities('Hello &amp; Welcome!'));
+
+console.log('\nExtract emails:');
+console.log(Manipulator.extractEmails(html));
+
+console.log('\nExtract URLs:');
+console.log(Manipulator.extractUrls(html));
+
+console.log('\nRemove scripts:');
+console.log(Manipulator.removeScriptsAndStyles(html));
+
+console.log('\nTruncate text:');
+console.log(Manipulator.truncate('This is a very long text that needs truncating', 20));
+
+console.log('\nWord count:');
+console.log(Manipulator.wordCount('Hello world this is a test'));
+
+console.log('\nConvert to absolute URL:');
+console.log(Manipulator.toAbsoluteUrl('/path/to/page', 'https://example.com'));

package/index.d.ts

@@ -0,0 +1,97 @@
+declare module 'html-fetch-parser' {
+  export interface FetcherOptions {
+    headers?: Record<string, string>;
+    timeout?: number;
+  }
+
+  export interface FetchOptions extends RequestInit {
+    headers?: Record<string, string>;
+  }
+
+  export interface ExtractConfig {
+    selector: string;
+    attr?: string;
+    multiple?: boolean;
+    transform?: (value: any) => any;
+  }
+
+  export interface ExtractSchema {
+    [key: string]: string | ExtractConfig;
+  }
+
+  export interface LinkObject {
+    text: string;
+    href: string | null;
+    title: string | null;
+  }
+
+  export interface ImageObject {
+    src: string | null;
+    alt: string | null;
+    title: string | null;
+  }
+
+  export class Fetcher {
+    constructor(options?: FetcherOptions);
+    get(url: string, options?: FetchOptions): Promise<string>;
+    post(url: string, data?: any, options?: FetchOptions): Promise<string>;
+    setHeaders(headers: Record<string, string>): void;
+    setTimeout(ms: number): void;
+  }
+
+  export class Parser {
+    constructor(html?: string);
+    load(html: string): Parser;
+    querySelector(selector: string): any;
+    querySelectorAll(selector: string): any[];
+    text(selector: string): string;
+    textAll(selector: string): string[];
+    attr(selector: string, attr: string): string | null;
+    attrAll(selector: string, attr: string): string[];
+    html(selector: string): string;
+    outerHtml(selector: string): string;
+    getTitle(): string;
+    getMeta(name: string): string;
+    getLinks(): LinkObject[];
+    getImages(): ImageObject[];
+    extract(schema: ExtractSchema): Record<string, any>;
+    getRawHtml(): string;
+  }
+
+  export class Manipulator {
+    static stripTags(html: string): string;
+    static decodeEntities(html: string): string;
+    static extractUrls(html: string, baseUrl?: string): string[];
+    static cleanWhitespace(text: string): string;
+    static extractEmails(html: string): string[];
+    static truncate(text: string, length: number, suffix?: string): string;
+    static toAbsoluteUrl(url: string, baseUrl: string): string;
+    static extractStructuredData(html: string): object[];
+    static removeScriptsAndStyles(html: string): string;
+    static wordCount(text: string): number;
+    static sanitizeFilename(filename: string): string;
+  }
+
+  export default class HtmlFetchParser {
+    constructor(options?: FetcherOptions);
+    fetch(url: string, options?: FetchOptions): Promise<HtmlFetchParser>;
+    post(url: string, data?: any, options?: FetchOptions): Promise<HtmlFetchParser>;
+    load(html: string): HtmlFetchParser;
+    $(selector: string): any;
+    $$(selector: string): any[];
+    text(selector: string): string;
+    textAll(selector: string): string[];
+    attr(selector: string, attr: string): string | null;
+    attrAll(selector: string, attr: string): string[];
+    html(selector: string): string;
+    extract(schema: ExtractSchema): Record<string, any>;
+    getTitle(): string;
+    getMeta(name: string): string;
+    getLinks(): LinkObject[];
+    getImages(): ImageObject[];
+    getRawHtml(): string;
+  }
+
+  export function fetch(url: string, options?: FetcherOptions): Promise<HtmlFetchParser>;
+  export function load(html: string): HtmlFetchParser;
+}

package/index.js

@@ -0,0 +1,95 @@
+const Fetcher = require('./lib/fetcher');
+const Parser = require('./lib/parser');
+const Manipulator = require('./lib/manipulator');
+
+class HtmlFetchParser {
+  constructor(options = {}) {
+    this.fetcher = new Fetcher(options);
+    this.parser = new Parser();
+  }
+
+  async fetch(url, options = {}) {
+    const html = await this.fetcher.get(url, options);
+    this.parser.load(html);
+    return this;
+  }
+
+  async post(url, data = {}, options = {}) {
+    const html = await this.fetcher.post(url, data, options);
+    this.parser.load(html);
+    return this;
+  }
+
+  load(html) {
+    this.parser.load(html);
+    return this;
+  }
+
+  $(selector) {
+    return this.parser.querySelector(selector);
+  }
+
+  $$(selector) {
+    return this.parser.querySelectorAll(selector);
+  }
+
+  text(selector) {
+    return this.parser.text(selector);
+  }
+
+  textAll(selector) {
+    return this.parser.textAll(selector);
+  }
+
+  attr(selector, attr) {
+    return this.parser.attr(selector, attr);
+  }
+
+  attrAll(selector, attr) {
+    return this.parser.attrAll(selector, attr);
+  }
+
+  html(selector) {
+    return this.parser.html(selector);
+  }
+
+  extract(schema) {
+    return this.parser.extract(schema);
+  }
+
+  getTitle() {
+    return this.parser.getTitle();
+  }
+
+  getMeta(name) {
+    return this.parser.getMeta(name);
+  }
+
+  getLinks() {
+    return this.parser.getLinks();
+  }
+
+  getImages() {
+    return this.parser.getImages();
+  }
+
+  getRawHtml() {
+    return this.parser.getRawHtml();
+  }
+}
+
+module.exports = HtmlFetchParser;
+module.exports.Fetcher = Fetcher;
+module.exports.Parser = Parser;
+module.exports.Manipulator = Manipulator;
+module.exports.default = HtmlFetchParser;
+
+module.exports.fetch = async (url, options) => {
+  const instance = new HtmlFetchParser(options);
+  return await instance.fetch(url);
+};
+
+module.exports.load = (html) => {
+  const instance = new HtmlFetchParser();
+  return instance.load(html);
+};

package/lib/fetcher.js

@@ -0,0 +1,106 @@
+/**
+ * HTTP Fetcher Module
+ * Lightweight HTTP client for fetching HTML content
+ */
+
+class Fetcher {
+  constructor(options = {}) {
+    this.defaultHeaders = {
+      'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+      ...options.headers
+    };
+    this.timeout = options.timeout || 10000;
+  }
+
+  /**
+   * Fetch HTML content from URL
+   * @param {string} url - URL to fetch
+   * @param {object} options - Fetch options
+   * @returns {Promise<string>} HTML content
+   */
+  async get(url, options = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: { ...this.defaultHeaders, ...options.headers },
+        signal: controller.signal,
+        ...options
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+      }
+
+      return await response.text();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this.timeout}ms`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * POST request with data
+   * @param {string} url - URL to post
+   * @param {object} data - Data to send
+   * @param {object} options - Fetch options
+   * @returns {Promise<string>} Response content
+   */
+  async post(url, data = {}, options = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.defaultHeaders,
+          ...options.headers
+        },
+        body: JSON.stringify(data),
+        signal: controller.signal,
+        ...options
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+      }
+
+      return await response.text();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this.timeout}ms`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Set default headers
+   * @param {object} headers - Headers object
+   */
+  setHeaders(headers) {
+    this.defaultHeaders = { ...this.defaultHeaders, ...headers };
+  }
+
+  /**
+   * Set timeout
+   * @param {number} ms - Timeout in milliseconds
+   */
+  setTimeout(ms) {
+    this.timeout = ms;
+  }
+}
+
+module.exports = Fetcher;

package/lib/manipulator.js

@@ -0,0 +1,151 @@
+/**
+ * HTML Manipulator Module
+ * Utilities for HTML manipulation and transformation
+ */
+
+class Manipulator {
+  /**
+   * Remove HTML tags from text
+   * @param {string} html - HTML string
+   * @returns {string} Plain text
+   */
+  static stripTags(html) {
+    return html.replace(/<[^>]*>/g, '');
+  }
+
+  /**
+   * Decode HTML entities
+   * @param {string} html - HTML string with entities
+   * @returns {string} Decoded string
+   */
+  static decodeEntities(html) {
+    const entities = {
+      '&amp;': '&',
+      '&lt;': '<',
+      '&gt;': '>',
+      '&quot;': '"',
+      '&#039;': "'",
+      '&apos;': "'",
+      '&nbsp;': ' '
+    };
+    return html.replace(/&[#\w]+;/g, entity => entities[entity] || entity);
+  }
+
+  /**
+   * Extract URLs from HTML
+   * @param {string} html - HTML string
+   * @param {string} baseUrl - Base URL for relative links
+   * @returns {Array<string>} Array of URLs
+   */
+  static extractUrls(html, baseUrl = '') {
+    const urlRegex = /https?:\/\/[^\s<>"]+/g;
+    const urls = html.match(urlRegex) || [];
+    return [...new Set(urls)];
+  }
+
+  /**
+   * Clean whitespace
+   * @param {string} text - Text to clean
+   * @returns {string} Cleaned text
+   */
+  static cleanWhitespace(text) {
+    return text
+      .replace(/\s+/g, ' ')
+      .replace(/\n\s*\n/g, '\n')
+      .trim();
+  }
+
+  /**
+   * Extract emails from HTML
+   * @param {string} html - HTML string
+   * @returns {Array<string>} Array of email addresses
+   */
+  static extractEmails(html) {
+    const emailRegex = /[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9_-]+/g;
+    const emails = html.match(emailRegex) || [];
+    return [...new Set(emails)];
+  }
+
+  /**
+   * Truncate text
+   * @param {string} text - Text to truncate
+   * @param {number} length - Max length
+   * @param {string} suffix - Suffix (default: '...')
+   * @returns {string} Truncated text
+   */
+  static truncate(text, length, suffix = '...') {
+    if (text.length <= length) return text;
+    return text.substring(0, length - suffix.length) + suffix;
+  }
+
+  /**
+   * Convert relative URL to absolute
+   * @param {string} url - Relative URL
+   * @param {string} baseUrl - Base URL
+   * @returns {string} Absolute URL
+   */
+  static toAbsoluteUrl(url, baseUrl) {
+    if (!url) return '';
+    if (url.startsWith('http://') || url.startsWith('https://')) return url;
+
+    try {
+      return new URL(url, baseUrl).href;
+    } catch {
+      return url;
+    }
+  }
+
+  /**
+   * Extract structured data (JSON-LD, microdata)
+   * @param {string} html - HTML string
+   * @returns {Array<object>} Array of structured data objects
+   */
+  static extractStructuredData(html) {
+    const jsonLdRegex = /<script[^>]+type=["']application\/ld\+json["'][^>]*>(.*?)<\/script>/gis;
+    const matches = [...html.matchAll(jsonLdRegex)];
+
+    return matches
+      .map(match => {
+        try {
+          return JSON.parse(match[1]);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  }
+
+  /**
+   * Remove scripts and styles
+   * @param {string} html - HTML string
+   * @returns {string} Cleaned HTML
+   */
+  static removeScriptsAndStyles(html) {
+    return html
+      .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
+      .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '');
+  }
+
+  /**
+   * Get word count
+   * @param {string} text - Text to count
+   * @returns {number} Word count
+   */
+  static wordCount(text) {
+    return text.trim().split(/\s+/).filter(Boolean).length;
+  }
+
+  /**
+   * Sanitize filename
+   * @param {string} filename - Filename to sanitize
+   * @returns {string} Safe filename
+   */
+  static sanitizeFilename(filename) {
+    return filename
+      .replace(/[^a-z0-9.-]/gi, '_')
+      .replace(/_+/g, '_')
+      .toLowerCase();
+  }
+}
+
+module.exports = Manipulator;

package/lib/parser.js

@@ -0,0 +1,196 @@
+/**
+ * HTML Parser Module
+ * Parse and query HTML content
+ */
+
+const { parse } = require('node-html-parser');
+
+class Parser {
+  constructor(html = '') {
+    this.root = html ? parse(html) : null;
+    this.rawHtml = html;
+  }
+
+  /**
+   * Load HTML content
+   * @param {string} html - HTML string
+   * @returns {Parser} Parser instance
+   */
+  load(html) {
+    this.rawHtml = html;
+    this.root = parse(html);
+    return this;
+  }
+
+  /**
+   * Find element by CSS selector
+   * @param {string} selector - CSS selector
+   * @returns {object|null} Element
+   */
+  querySelector(selector) {
+    if (!this.root) return null;
+    return this.root.querySelector(selector);
+  }
+
+  /**
+   * Find all elements by CSS selector
+   * @param {string} selector - CSS selector
+   * @returns {Array} Array of elements
+   */
+  querySelectorAll(selector) {
+    if (!this.root) return [];
+    return this.root.querySelectorAll(selector);
+  }
+
+  /**
+   * Get element text content
+   * @param {string} selector - CSS selector
+   * @returns {string} Text content
+   */
+  text(selector) {
+    const element = this.querySelector(selector);
+    return element ? element.text.trim() : '';
+  }
+
+  /**
+   * Get all text from elements
+   * @param {string} selector - CSS selector
+   * @returns {Array<string>} Array of text content
+   */
+  textAll(selector) {
+    const elements = this.querySelectorAll(selector);
+    return elements.map(el => el.text.trim()).filter(text => text);
+  }
+
+  /**
+   * Get element attribute
+   * @param {string} selector - CSS selector
+   * @param {string} attr - Attribute name
+   * @returns {string|null} Attribute value
+   */
+  attr(selector, attr) {
+    const element = this.querySelector(selector);
+    return element ? element.getAttribute(attr) : null;
+  }
+
+  /**
+   * Get attributes from all matching elements
+   * @param {string} selector - CSS selector
+   * @param {string} attr - Attribute name
+   * @returns {Array<string>} Array of attribute values
+   */
+  attrAll(selector, attr) {
+    const elements = this.querySelectorAll(selector);
+    return elements.map(el => el.getAttribute(attr)).filter(val => val);
+  }
+
+  /**
+   * Get element HTML
+   * @param {string} selector - CSS selector
+   * @returns {string} HTML content
+   */
+  html(selector) {
+    const element = this.querySelector(selector);
+    return element ? element.innerHTML : '';
+  }
+
+  /**
+   * Get outer HTML
+   * @param {string} selector - CSS selector
+   * @returns {string} Outer HTML
+   */
+  outerHtml(selector) {
+    const element = this.querySelector(selector);
+    return element ? element.outerHTML : '';
+  }
+
+  /**
+   * Get page title
+   * @returns {string} Page title
+   */
+  getTitle() {
+    return this.text('title');
+  }
+
+  /**
+   * Get meta tags
+   * @param {string} name - Meta name or property
+   * @returns {string} Meta content
+   */
+  getMeta(name) {
+    const meta = this.querySelector(`meta[name="${name}"], meta[property="${name}"]`);
+    return meta ? meta.getAttribute('content') : '';
+  }
+
+  /**
+   * Get all links
+   * @returns {Array<object>} Array of links with text and href
+   */
+  getLinks() {
+    const links = this.querySelectorAll('a');
+    return links.map(link => ({
+      text: link.text.trim(),
+      href: link.getAttribute('href'),
+      title: link.getAttribute('title')
+    }));
+  }
+
+  /**
+   * Get all images
+   * @returns {Array<object>} Array of images with src and alt
+   */
+  getImages() {
+    const images = this.querySelectorAll('img');
+    return images.map(img => ({
+      src: img.getAttribute('src'),
+      alt: img.getAttribute('alt'),
+      title: img.getAttribute('title')
+    }));
+  }
+
+  /**
+   * Extract data using custom mapping
+   * @param {object} schema - Extraction schema
+   * @returns {object} Extracted data
+   */
+  extract(schema) {
+    const result = {};
+
+    for (const [key, config] of Object.entries(schema)) {
+      if (typeof config === 'string') {
+        // Simple selector
+        result[key] = this.text(config);
+      } else if (typeof config === 'object') {
+        // Advanced config
+        const { selector, attr, multiple, transform } = config;
+
+        if (multiple) {
+          result[key] = attr
+            ? this.attrAll(selector, attr)
+            : this.textAll(selector);
+        } else {
+          result[key] = attr
+            ? this.attr(selector, attr)
+            : this.text(selector);
+        }
+
+        // Apply transform function if provided
+        if (transform && typeof transform === 'function') {
+          result[key] = transform(result[key]);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get raw HTML
+   * @returns {string} Raw HTML
+   */
+  getRawHtml() {
+    return this.rawHtml;
+  }
+}
+
+module.exports = Parser;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "html-fetch-parser",
+  "version": "1.0.0",
+  "description": "Lightweight HTML fetching and parsing library - combines fetch, parsing, and manipulation in one simple package",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "html",
+    "parser",
+    "fetch",
+    "scraper",
+    "cheerio",
+    "axios",
+    "dom",
+    "manipulation"
+  ],
+  "author": "KazeDevID",
+  "license": "MIT",
+  "dependencies": {
+    "node-html-parser": "^6.1.12"
+  },
+  "devDependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KazeDevID/html-fetch-parser"
+  },
+  "scripts": {
+    "test": "node examples/basic-usage.js"
+  }
+}