Code Style and Formatting

Relevant source files

The following files were used as context for generating this wiki page:

• biome.json
• package.json
• tsconfig.json
• src/Parser.ts
• src/Tokenizer.ts

Code style and formatting in the htmlparser2 project are governed by a combination of automated tooling and strict TypeScript compiler configurations. The project primarily utilizes Biome for linting and formatting, supplemented by ESLint for specific TypeScript rules and TypeScript's own strict mode for type safety and code consistency.

The architecture of the style system is designed to ensure that the "fast and forgiving" nature of the parser is supported by highly readable, standardized, and performant code. Automated checks are integrated into the development workflow via npm scripts to maintain these standards across the codebase.

Sources: biome.json:1-10, package.json:63-71, tsconfig.json:14-31

Formatting Configuration

The project uses Biome as its primary formatter. It is configured to enforce a consistent visual structure across all supported file types, including TypeScript, Markdown, JSON, and YAML files.

Biome Formatter Settings

The formatter is configured to use spaces instead of tabs, with a specific width to ensure code blocks remain readable in various editors.

Setting	Value	Description
enabled	true	Enables the Biome formatting engine.
indentStyle	space	Uses spaces for indentation.
indentWidth	4	Sets the number of spaces per indentation level.

Sources: biome.json:12-16

Target Files and VCS Integration

The project integrates with Git to respect ignore files and targets a broad range of file extensions while ignoring hidden files.

The diagram shows the logic Biome uses to filter files and apply formatting rules, including import organization.

Sources: biome.json:7-11, biome.json:51-56

Linting and Technical Standards

Linting is enforced through Biome's recommended ruleset, with additional specific overrides for complexity, performance, and style. This ensures that the code follows modern JavaScript/TypeScript best practices.

Key Linter Rules

Category	Rule	Severity	Description
Complexity	useWhile	Error	Prefers while loops over for loops where appropriate.
Performance	useTopLevelRegex	Error	Prevents re-compiling Regex by mandating top-level definitions.
Style	useConsistentArrayType	Error	Enforces a single way to define arrays (e.g., T[] vs Array<T>).
Suspicious	noConstantBinaryExpressions	Error	Disallows expressions that always evaluate to the same value.

Sources: biome.json:20-50

TypeScript Strictness

The tsconfig.json defines the technical boundaries for code style at the type level. The project uses es2022 as the target and enforces strict type-checking.

{
    "compilerOptions": {
        "target": "es2022",
        "strict": true,
        "noImplicitOverride": true,
        "noUnusedLocals": true,
        "noUnusedParameters": true,
        "forceConsistentCasingInFileNames": true
    }
}

Sources: tsconfig.json:4-29

Development Workflow Scripts

Formatting and linting are integrated into the package.json scripts, allowing developers to easily check and fix style violations.

Script Execution Flow

The sequence diagram illustrates the multi-stage formatting process that combines ESLint and Biome.

Sources: package.json:64-67

Implementation Patterns

The codebase follows specific implementation patterns for consistency, particularly within the core Parser and Tokenizer classes.

• Internal Callbacks: Methods intended only for internal use by the tokenizer are marked with the @internal JSDoc tag and often follow the on[event] naming convention.
  • Sources: src/Parser.ts:251-270, src/Tokenizer.ts:168-183
• Constant Enums: The project utilizes const enum for internal state management (e.g., State in Tokenizer) to improve performance by inlining values, although Biome is configured to allow this specifically.
  • Sources: src/Tokenizer.ts:60-101, biome.json:23
• Set-based Lookups: Tag groups (like voidElements or formTags) are stored in Set objects for O(1) lookup performance during parsing.
  • Sources: src/Parser.ts:5-15, src/Parser.ts:98-118

Summary

htmlparser2 maintains high code quality through a rigorous automated system. By leveraging Biome for formatting and linting, and TypeScript for strict type-checking, the project ensures that the codebase remains consistent and performant. The use of 4-space indentation, organized imports, and strict linting rules regarding performance and complexity reflects the project's focus on maintaining its status as a high-performance HTML/XML parser.