or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-decoding.mddecoding.mdencoding.mdescaping.mdindex.md
tile.json

tessl/npm-entities

High-performance library for encoding and decoding HTML and XML entities with configurable options

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/entities@6.0.x

To install, run

npx @tessl/cli install tessl/npm-entities@6.0.0

index.mddocs/

Entities

Entities is a high-performance TypeScript library for encoding and decoding HTML and XML entities. It provides configurable encoding options, fast decoding capabilities with strict and lenient parsing modes, and serves as a foundational utility for HTML/XML processing pipelines.

Package Information

  • Package Name: entities
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install entities

Core Imports

import { decode, encode, EntityLevel, EncodingMode } from "entities";

For CommonJS:

const { decode, encode, EntityLevel, EncodingMode } = require("entities");

Selective Imports

Import specific functionality from submodules:

// Decoding only
import { decodeHTML, decodeXML } from "entities/decode";

// Encoding/escaping only  
import { escapeUTF8, encodeXML } from "entities/escape";

Basic Usage

import { decode, encode, EntityLevel, EncodingMode } from "entities";

// Decode HTML entities (default: legacy mode, allows incomplete entities)
const decodedHTML = decode("<script>alert('XSS')</script>", EntityLevel.HTML);
// Result: "<script>alert('XSS')</script>"

// Decode XML entities (strict mode, requires semicolons)
const decodedXML = decode("& <tag>", EntityLevel.XML);
// Result: "& <tag>"

// Encode for safe HTML output
const encodedHTML = encode("<script>alert('XSS')</script>", {
  level: EntityLevel.HTML,
  mode: EncodingMode.Extensive
});
// Result: "&lt;script&gt;alert&apos;XSS&apos;&lt;&sol;script&gt;"

// UTF-8 optimized encoding (minimal escaping)
const encodedUTF8 = encode("Hello & 世界", EncodingMode.UTF8);
// Result: "Hello &amp; 世界"

Architecture

Entities is built around several key components:

  • Dual API Design: Main unified API (decode/encode) plus specialized functions for specific use cases
  • Performance Optimization: Trie-based entity lookup tables and optimized regex matching for maximum speed
  • Configurable Output: Multiple encoding modes from minimal UTF-8 escaping to extensive entity encoding
  • Standards Compliance: WHATWG HTML specification compatibility for attribute and text escaping
  • Tree Shakeable: Modular exports support selective importing to minimize bundle size
  • Dual Module System: Full CommonJS and ESM support with TypeScript type definitions

Capabilities

Entity Decoding

Comprehensive HTML and XML entity decoding with configurable strictness modes and legacy compatibility.

function decode(
  input: string,
  options?: DecodingOptions | EntityLevel
): string;

function decodeStrict(
  input: string,
  options?: DecodingOptions | EntityLevel  
): string;

enum EntityLevel {
  XML = 0,
  HTML = 1
}

enum DecodingMode {
  Legacy = 0,
  Strict = 1,
  Attribute = 2
}

interface DecodingOptions {
  level?: EntityLevel;
  mode?: DecodingMode;
}

Entity Decoding

Entity Encoding

Flexible HTML and XML entity encoding with multiple output modes for different use cases and environments.

function encode(
  input: string,
  options?: EncodingOptions | EntityLevel
): string;

enum EncodingMode {
  UTF8,
  ASCII,
  Extensive,
  Attribute,
  Text
}

interface EncodingOptions {
  level?: EntityLevel;
  mode?: EncodingMode;
}

Entity Encoding

Entity Escaping

Fast, targeted character escaping functions for specific HTML/XML contexts and UTF-8 optimized output.

function escapeUTF8(data: string): string;
function escapeAttribute(data: string): string;
function escapeText(data: string): string;
function encodeXML(input: string): string;

Entity Escaping

Advanced Decoding

Streaming entity decoder and low-level decoding utilities for performance-critical applications.

class EntityDecoder {
  constructor(
    decodeTree: Uint16Array,
    emitCodePoint: (cp: number, consumed: number) => void,
    errors?: EntityErrorProducer
  );
  startEntity(decodeMode: DecodingMode): void;
  write(input: string, offset: number): number;
}

interface EntityErrorProducer {
  missingSemicolonAfterCharacterReference(): void;
  absenceOfDigitsInNumericCharacterReference(consumedCharacters: number): void;
  validateNumericCharacterReference(code: number): void;
}

Advanced Decoding

Core Types

enum EntityLevel {
  /** Support only XML entities */
  XML = 0,
  /** Support HTML entities, which are a superset of XML entities */
  HTML = 1
}

enum EncodingMode {
  /** UTF-8 encoded output, only XML characters escaped */
  UTF8,
  /** ASCII-only output with HTML escaping */
  ASCII, 
  /** Encode all characters with entities + non-ASCII */
  Extensive,
  /** HTML attribute escaping per WHATWG spec */
  Attribute,
  /** HTML text escaping per WHATWG spec */
  Text
}

enum DecodingMode {
  /** Entities can end with any character (legacy compatibility) */
  Legacy = 0,
  /** Only semicolon-terminated entities allowed */
  Strict = 1,
  /** Entities in attributes with ending character limitations */
  Attribute = 2
}

interface DecodingOptions {
  /** Entity level support (default: XML) */
  level?: EntityLevel;
  /** Decoding strictness mode (default: Legacy) */
  mode?: DecodingMode;
}

interface EncodingOptions {
  /** Entity level support (default: XML) */
  level?: EntityLevel;
  /** Output encoding format (default: Extensive) */
  mode?: EncodingMode;
}