very-happy-dom 0.0.7

package/README.md

@@ -0,0 +1,251 @@
+# VeryHappyDOM
+
+A blazing-fast DOM implementation for Bun, built for speed and browser API compatibility.
+
+## ⚡ Performance
+
+VeryHappyDOM is **16× to 79,000× faster** than established DOM implementations:
+
+- **HTML Parsing**: 413ns average (34,400× faster than HappyDOM)
+- **querySelector**: Sub-microsecond to low-microsecond performance
+- **DOM Manipulation**: Microsecond-level performance
+- **Zero Dependencies**: Pure Bun implementation
+
+See [benchmarks](../benchmarks/README.md) for detailed performance comparisons.
+
+## 🎯 Features
+
+### Core DOM APIs
+
+- ✅ HTML parsing and serialization
+- ✅ DOM manipulation (createElement, appendChild, innerHTML, etc.)
+- ✅ CSS selectors (querySelector, querySelectorAll)
+- ✅ Event handling (addEventListener, dispatchEvent, CustomEvent)
+- ✅ Document API (getElementById, getElementsByClassName, etc.)
+
+### Browser APIs
+
+- ✅ **Storage** - localStorage, sessionStorage with Proxy support
+- ✅ **Timers** - setTimeout, setInterval, requestAnimationFrame
+- ✅ **Network** - fetch, XMLHttpRequest, WebSocket, request interception
+- ✅ **Observers** - MutationObserver, IntersectionObserver, ResizeObserver
+- ✅ **XPath** - Full XPath 1.0 support with document.evaluate()
+- ✅ **Events** - CustomEvent, event emitters, page events
+- ✅ **Interaction** - click, type, focus, hover, keyboard, mouse
+- ✅ **Web Components** - Shadow DOM, Custom Elements
+- ✅ **File API** - File, FileReader, FileList
+- ✅ **Clipboard** - navigator.clipboard.writeText/readText
+- ✅ **Performance** - performance.now/mark/measure
+- ✅ **Geolocation** - navigator.geolocation
+
+## 📦 Installation
+
+```bash
+bun add very-happy-dom
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { Window } from 'very-happy-dom'
+
+const window = new Window()
+
+// Parse HTML
+window.document.body.innerHTML = '<div id="app"><h1>Hello World</h1></div>'
+
+// Query DOM
+const app = window.document.getElementById('app')
+const title = window.document.querySelector('h1')
+
+console.log(title?.textContent) // "Hello World"
+
+// Cleanup
+await window.happyDOM.close()
+```
+
+## 🧪 Test Coverage
+
+VeryHappyDOM has **972+ comprehensive tests** organized by functionality:
+
+### Organized Test Suites (586 tests)
+
+| Test Suite | Tests | Coverage |
+|-----------|-------|----------|
+| **storage.test.ts** | 50 | localStorage, sessionStorage, isolation, edge cases |
+| **timers.test.ts** | 29 | setTimeout, setInterval, requestAnimationFrame, cleanup |
+| **network.test.ts** | 43 | fetch, XMLHttpRequest, WebSocket, request interception |
+| **observers.test.ts** | 45 | MutationObserver, IntersectionObserver, ResizeObserver |
+| **xpath.test.ts** | 23 | XPath expressions, predicates, axes, result types |
+| **events.test.ts** | 19 | CustomEvent, addEventListener, page events |
+| **interaction.test.ts** | 11 | click, type, focus, hover, keyboard, mouse |
+| **webcomponents.test.ts** | 21 | Shadow DOM, Custom Elements, lifecycle |
+| **browser-apis.test.ts** | 31 | Performance, Clipboard, Geolocation, File API |
+| **integration.test.ts** | 24 | End-to-end scenarios combining features |
+| **security-sanitization.test.ts** | 52 | XSS prevention, script injection, content sanitization |
+| **attribute-property.test.ts** | 127 | Comprehensive attribute and property handling |
+| **selector-engine.test.ts** | 70 | CSS selectors, combinators, pseudo-classes |
+| **advanced-edge-cases.test.ts** | 41 | Complex scenarios and edge cases |
+
+### Legacy Test Suites (287+ tests)
+
+All legacy tests have been organized in `tests/legacy/` folder:
+
+- ✅ Basic feature tests (43)
+- ✅ Advanced feature tests (35)
+- ✅ Final feature tests (32)
+- ✅ Additional feature tests
+- ✅ Core DOM tests
+- ✅ DOM edge cases
+- ✅ Pseudo-class selector tests
+
+Plus active stress tests:
+
+- ✅ 87 browser API stress tests
+
+### Test Organization
+
+Tests are logically organized by domain rather than by implementation phase:
+
+```
+tests/
+├── Core Domain Tests (296 tests)
+│   ├── storage.test.ts       # Storage API tests
+│   ├── timers.test.ts        # Timer API tests
+│   ├── network.test.ts       # Network API tests
+│   ├── observers.test.ts     # Observer pattern tests
+│   ├── xpath.test.ts         # XPath evaluation tests
+│   ├── events.test.ts        # Event system tests
+│   ├── interaction.test.ts   # User interaction tests
+│   ├── webcomponents.test.ts # Web Components tests
+│   ├── browser-apis.test.ts  # Browser API tests
+│   └── integration.test.ts   # Integration tests
+│
+├── Quality Assurance (27 tests)
+│   ├── error-handling.test.ts # Error scenarios
+│   └── performance.test.ts    # Performance regression
+│
+├── Stress Tests (87 tests)
+│   └── browser-api.stress.test.ts
+│
+├── Test Utilities
+│   └── test-utils.ts         # Shared test helpers
+│
+└── Legacy Tests (287+ tests)
+    └── legacy/               # Old tests preserved
+```
+
+### Running Tests
+
+```bash
+# Run specific test suite
+bun test tests/storage.test.ts
+
+# Run all tests
+bun test tests/*.test.ts
+```
+
+## 🏗️ Architecture
+
+### Window API
+
+```typescript
+import { Window } from 'very-happy-dom'
+
+const window = new Window({
+  url: 'https://example.com',
+  width: 1920,
+  height: 1080,
+  settings: {
+    navigator: {
+      userAgent: 'Custom User Agent'
+    }
+  }
+})
+```
+
+### Browser API
+
+```typescript
+import { Browser } from 'very-happy-dom'
+
+const browser = new Browser()
+const page = browser.newPage()
+
+await page.goto('https://example.com')
+await page.click('#button')
+await page.type('#input', 'Hello')
+
+await browser.close()
+```
+
+## 🔧 Advanced Features
+
+### Request Interception
+
+```typescript
+await page.setRequestInterception(true, async (request) => {
+  // Mock API responses
+  request.respond({
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ success: true })
+  })
+})
+```
+
+### XPath Support
+
+```typescript
+const result = window.document.evaluate(
+  '//div[@class="item"]',
+  window.document,
+  null,
+  XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
+  null
+)
+
+for (let i = 0; i < result.snapshotLength; i++) {
+  console.log(result.snapshotItem(i))
+}
+```
+
+### Shadow DOM
+
+```typescript
+const host = window.document.createElement('div')
+const shadow = host.attachShadow({ mode: 'open' })
+
+shadow.innerHTML = '<p>Shadow content</p>'
+const p = shadow.querySelector('p')
+```
+
+### Custom Elements
+
+```typescript
+class MyComponent extends window.HTMLElement {
+  connectedCallback() {
+    this.innerHTML = '<h1>Custom Component</h1>'
+  }
+}
+
+window.customElements.define('my-component', MyComponent)
+```
+
+## 📊 Benchmarks
+
+See the [benchmarks package](../benchmarks) for detailed performance comparisons with HappyDOM and JSDOM.
+
+Key results on Apple M3 Pro:
+
+- HTML Parsing: **413 ns** (vs HappyDOM 14.20 ms, JSDOM 32.69 ms)
+- querySelector: **741 ns** (vs HappyDOM 14.27 ms, JSDOM 30.74 ms)
+- DOM Manipulation: **35.49 µs** (vs HappyDOM 1.06 ms, JSDOM 3.00 ms)
+
+## 🤝 Contributing
+
+Contributions welcome! Please check the [FEATURE_ROADMAP.md](./FEATURE_ROADMAP.md) for planned features and current status.
+
+## 📄 License
+
+MIT

package/dist/apis/BrowserAPIs.d.ts

@@ -0,0 +1,93 @@
+declare interface GeolocationPosition {
+  coords: GeolocationCoordinates
+  timestamp: number
+}
+declare interface GeolocationPositionError {
+  code: number
+  message: string
+}
+declare interface GeolocationOptions {
+  enableHighAccuracy?: boolean
+  timeout?: number
+  maximumAge?: number
+}
+declare interface NotificationOptions {
+  body?: string
+  icon?: string
+  tag?: string
+  data?: any
+}
+declare type DataTransferItemList = any[]
+/**
+ * Browser APIs implementation
+ * Performance, Geolocation, Notifications, Console, etc.
+ */
+/* eslint-disable no-console */
+// Performance API
+export declare class Performance {
+  private _marks: any;
+  private _measures: any;
+  private _startTime: any;
+  now(): number;
+  mark(name: string): void;
+  measure(name: string, startMark?: string, endMark?: string): void;
+  clearMarks(name?: string): void;
+  clearMeasures(name?: string): void;
+  getEntriesByName(name: string): any[];
+}
+// Geolocation API
+export declare class Geolocation {
+  getCurrentPosition(success: (position: GeolocationPosition) => void, _error?: (error: GeolocationPositionError) => void, _options?: GeolocationOptions): void;
+  watchPosition(success: (position: GeolocationPosition) => void, _error?: (error: GeolocationPositionError) => void, _options?: GeolocationOptions): number;
+  clearWatch(id: number): void;
+}
+// Notification API
+export declare class Notification {
+  static permission: 'default' | 'granted' | 'denied';
+  title: string;
+  body?: string;
+  icon?: string;
+  tag?: string;
+  onclick: ((event: Event) => void) | null;
+  onclose: ((event: Event) => void) | null;
+  onerror: ((event: Event) => void) | null;
+  onshow: ((event: Event) => void) | null;
+  constructor(title: string, options?: NotificationOptions);
+  static requestPermission(): Promise<'default' | 'granted' | 'denied'>;
+  close(): void;
+}
+// Enhanced Console API
+export declare class EnhancedConsole {
+  private _groups: string[];
+  private _timers: any;
+  log(args: any[]): void;
+  warn(args: any[]): void;
+  error(args: any[]): void;
+  info(args: any[]): void;
+  debug(args: any[]): void;
+  table(data: any): void;
+  group(label?: string): void;
+  groupCollapsed(label?: string): void;
+  groupEnd(): void;
+  time(label: string): void;
+  timeEnd(label: string): void;
+  timeLog(label: string, args: any[]): void;
+  clear(): void;
+  count(label?: any): void;
+  assert(condition: boolean, args: any[]): void;
+  trace(args: any[]): void;
+  private _prefix(): string[];
+}
+// DataTransfer for Drag & Drop
+export declare class DataTransfer {
+  private _data: any;
+  dropEffect: 'none' | 'copy' | 'link' | 'move';
+  effectAllowed: 'none' | 'copy' | 'copyLink' | 'copyMove' | 'link' | 'linkMove' | 'move' | 'all' | 'uninitialized';
+  files: File[];
+  items: DataTransferItemList;
+  types: string[];
+  setData(format: string, data: string): void;
+  getData(format: string): string;
+  clearData(format?: string): void;
+  setDragImage(_image: Element, _x: number, _y: number): void;
+}

package/dist/apis/Clipboard.d.ts

@@ -0,0 +1,24 @@
+import { Geolocation } from './BrowserAPIs';
+declare type ClipboardItems = ClipboardItem[]
+export declare class Clipboard {
+  private _text: any;
+  writeText(text: string): Promise<void>;
+  readText(): Promise<string>;
+  write(data: ClipboardItems): Promise<void>;
+  read(): Promise<ClipboardItems>;
+}
+export declare class Navigator {
+  clipboard: Clipboard;
+  geolocation: Geolocation;
+  userAgent: string;
+  language: string;
+  languages: readonly string[];
+  platform: string;
+  cookieEnabled: boolean;
+  onLine: boolean;
+}
+declare class ClipboardItem {
+  constructor(data: Record<string, Blob | string | Promise<Blob | string>>);
+  readonly types: string[];
+  getType(type: string): Promise<Blob>;
+}

package/dist/apis/FileAPI.d.ts

@@ -0,0 +1,56 @@
+declare interface FilePropertyBag extends BlobPropertyBag {
+  lastModified?: number
+}
+declare interface ProgressEvent extends Event {
+  lengthComputable: boolean
+  loaded: number
+  total: number
+}
+declare type EventListener = (event: Event) => void
+/**
+ * File API implementation
+ * Provides File, FileReader, and FileList for testing file uploads
+ */
+/**
+ * File implementation
+ */
+export declare class VeryHappyFile extends Blob {
+  name: string;
+  lastModified: number;
+  constructor(bits: BlobPart[], name: string, options?: FilePropertyBag);
+}
+/**
+ * FileReader implementation
+ */
+export declare class VeryHappyFileReader {
+  static readonly EMPTY: any;
+  static readonly LOADING: any;
+  static readonly DONE: any;
+  readyState: number;
+  result: string | ArrayBuffer | null;
+  error: Error | null;
+  onload: ((event: ProgressEvent) => void) | null;
+  onerror: ((event: ProgressEvent) => void) | null;
+  onloadstart: ((event: ProgressEvent) => void) | null;
+  onloadend: ((event: ProgressEvent) => void) | null;
+  onprogress: ((event: ProgressEvent) => void) | null;
+  onabort: ((event: ProgressEvent) => void) | null;
+  private _eventListeners: any;
+  readAsText(blob: Blob, _encoding?: any): void;
+  readAsDataURL(blob: Blob): void;
+  readAsArrayBuffer(blob: Blob): void;
+  readAsBinaryString(blob: Blob): void;
+  abort(): void;
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
+  private _trigger(type: string): void;
+}
+/**
+ * FileList implementation
+ */
+export declare class VeryHappyFileList {
+  private _files: File[];
+  constructor(files?: File[]);
+  item(index: number): File | null;
+  [Symbol.iterator](): Iterator<File>;
+}

package/dist/browser/Browser.d.ts

@@ -0,0 +1,23 @@
+import { BrowserContext } from './BrowserContext';
+import type { BrowserPage } from './BrowserPage';
+import type { IBrowserSettings, IOptionalBrowserSettings } from '../window/Window';
+export declare interface BrowserOptions {
+  settings?: IOptionalBrowserSettings
+  console?: Console
+}
+/**
+ * Browser represents an instance of a VeryHappyDOM browser
+ * Compatible with Happy DOM's Browser API
+ */
+export declare class Browser {
+  console: Console;
+  defaultContext: BrowserContext;
+  private _contexts: BrowserContext[];
+  private _settings: IBrowserSettings;
+  constructor(options?: BrowserOptions);
+  close(): Promise<void>;
+  waitUntilComplete(): Promise<void>;
+  abort(): Promise<void>;
+  newIncognitoContext(): BrowserContext;
+  newPage(): BrowserPage;
+}

package/dist/browser/BrowserContext.d.ts

@@ -0,0 +1,21 @@
+import { BrowserPage } from './BrowserPage';
+import { CookieContainer } from './CookieContainer';
+import type { Browser } from './Browser';
+/**
+ * BrowserContext represents a context where data such as cache and cookies
+ * can be shared between its pages
+ * Compatible with Happy DOM's BrowserContext API
+ */
+export declare class BrowserContext {
+  cookieContainer: CookieContainer;
+  responseCache: Map<string, Response>;
+  preflightResponseCache: Map<string, Response>;
+  private _browser: Browser;
+  private _pages: BrowserPage[];
+  constructor(browser: Browser);
+  close(): Promise<void>;
+  waitUntilComplete(): Promise<void>;
+  abort(): Promise<void>;
+  newPage(): BrowserPage;
+  _removePage(page: BrowserPage): void;
+}

package/dist/browser/BrowserFrame.d.ts

@@ -0,0 +1,25 @@
+import { VirtualDocument } from '../nodes/VirtualDocument';
+import type { BrowserPage } from './BrowserPage';
+/**
+ * BrowserFrame represents a browser frame
+ * Compatible with Happy DOM's BrowserFrame API
+ */
+export declare class BrowserFrame {
+  window: Window & { document: VirtualDocument };
+  document: VirtualDocument;
+  private _page: BrowserPage;
+  private _parentFrame: BrowserFrame | null;
+  private _childFrames: BrowserFrame[];
+  private _url: string;
+  private _content: string;
+  constructor(page: BrowserPage, parentFrame?: BrowserFrame | null);
+  waitUntilComplete(): Promise<void>;
+  waitForNavigation(): Promise<void>;
+  abort(): Promise<void>;
+  evaluate(code: string | ((...args: any[]) => any)): any;
+  goto(url: string): Promise<Response | null>;
+  goBack(): Promise<Response | null>;
+  goForward(): Promise<Response | null>;
+  goSteps(_steps: number): Promise<Response | null>;
+  reload(): Promise<Response | null>;
+}

package/dist/browser/BrowserPage.d.ts

@@ -0,0 +1,82 @@
+import { BrowserFrame } from './BrowserFrame';
+import { Buffer } from 'node:buffer';
+import type { BrowserContext } from './BrowserContext';
+export declare interface IBrowserPageViewport {
+  width: number
+  height: number
+}
+export type PageEventType = 'console' | 'request' | 'response' | 'error' | 'load' | 'domcontentloaded'
+export type PageEventHandler = (event: any) => void
+/**
+ * BrowserPage represents a browser page (tab or popup window)
+ * Compatible with Happy DOM's BrowserPage API
+ */
+export declare class BrowserPage {
+  mainFrame: BrowserFrame;
+  console: Console;
+  virtualConsolePrinter: ((type: string, ...args: any[]) => void) | null;
+  private _context: BrowserContext;
+  private _viewport: IBrowserPageViewport;
+  private _frames: BrowserFrame[];
+  private _eventListeners: any;
+  private _requestInterceptor: any;
+  constructor(context: BrowserContext);
+  close(): Promise<void>;
+  waitUntilComplete(): Promise<void>;
+  waitForNavigation(): Promise<void>;
+  abort(): Promise<void>;
+  evaluate(code: string | ((...args: any[]) => any)): any;
+  setViewport(viewport: IBrowserPageViewport): void;
+  goto(url: string): Promise<Response | null>;
+  goBack(): Promise<Response | null>;
+  goForward(): Promise<Response | null>;
+  goSteps(steps: number): Promise<Response | null>;
+  reload(): Promise<Response | null>;
+  waitForSelector(selector: string, options?: { timeout?: number, visible?: boolean }): Promise<any | null>;
+  waitForFunction(fn: ((...args: any[]) => any) | string, options?: { timeout?: number, polling?: number | 'raf' }): Promise<any>;
+  waitForTimeout(ms: number): Promise<void>;
+  click(selector: string, options?: { delay?: number, button?: 'left' | 'right' | 'middle' }): Promise<void>;
+  type(selector: string, text: string, options?: { delay?: number }): Promise<void>;
+  focus(selector: string): Promise<void>;
+  hover(selector: string): Promise<void>;
+  on(event: PageEventType, handler: PageEventHandler): void;
+  off(event: PageEventType, handler: PageEventHandler): void;
+  emit(event: PageEventType, data: any): void;
+  _emitConsole(type: string, args: any[]): void;
+  _emitRequest(request: any): void;
+  _emitResponse(response: any): void;
+  _emitError(error: Error): void;
+  dragAndDrop(source: string, target: string, options?: { delay?: number }): Promise<void>;
+  setRequestInterception(enabled: boolean): Promise<void>;
+  screenshot(options?: {
+    type?: 'png' | 'jpeg' | 'webp'
+    quality?: number
+    fullPage?: boolean
+    clip?: { x: number, y: number, width: number, height: number }
+    omitBackground?: boolean
+    encoding?: 'base64' | 'binary'
+  }): Promise<string | Buffer>;
+  pdf(options?: {
+    path?: string
+    scale?: number
+    displayHeaderFooter?: boolean
+    headerTemplate?: string
+    footerTemplate?: string
+    printBackground?: boolean
+    landscape?: boolean
+    pageRanges?: string
+    format?: 'Letter' | 'Legal' | 'Tabloid' | 'Ledger' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6'
+    width?: string | number
+    height?: string | number
+    margin?: {
+      top?: string | number
+      right?: string | number
+      bottom?: string | number
+      left?: string | number
+    }
+    preferCSSPageSize?: boolean
+  }): Promise<Buffer>;
+  private _generateSVG(html: string): string;
+  private _generatePDF(html: string): string;
+  private _escapeXML(text: string): string;
+}

package/dist/browser/CookieContainer.d.ts

@@ -0,0 +1,25 @@
+export declare interface ICookie {
+  key: string
+  value?: string
+  originURL: string
+  domain?: string
+  path?: string
+  expires?: Date
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: CookieSameSiteEnum
+}
+/**
+ * CookieContainer manages cookies stored in memory for a BrowserContext
+ */
+export declare class CookieContainer {
+  private _cookies: ICookie[];
+  addCookies(cookies: ICookie[]): void;
+  getCookies(url: string, includeHttpOnly?: any): ICookie[];
+  clearCookies(): void;
+}
+export declare enum CookieSameSiteEnum {
+  none = 'None',
+  lax = 'Lax',
+  strict = 'Strict',
+}

package/dist/events/CustomEvent.d.ts

@@ -0,0 +1,14 @@
+import { VirtualEvent } from './VirtualEvent';
+export declare interface CustomEventInit {
+  bubbles?: boolean
+  cancelable?: boolean
+  detail?: any
+}
+/**
+ * CustomEvent implementation
+ * Compatible with DOM CustomEvent API
+ */
+export declare class CustomEvent extends VirtualEvent {
+  detail: any;
+  constructor(type: string, eventInitDict?: CustomEventInit);
+}

package/dist/events/VirtualEvent.d.ts

@@ -0,0 +1,16 @@
+import type { VirtualElement } from '../nodes/VirtualElement';
+export declare class VirtualEvent {
+  type: string;
+  target: VirtualElement | null;
+  currentTarget: VirtualElement | null;
+  bubbles: boolean;
+  cancelable: boolean;
+  defaultPrevented: any;
+  propagationStopped: any;
+  immediatePropagationStopped: any;
+  timeStamp: number;
+  constructor(type: string, options?: { bubbles?: boolean, cancelable?: boolean });
+  preventDefault(): void;
+  stopPropagation(): void;
+  stopImmediatePropagation(): void;
+}