HTML Entities

import { encode, decode, decodeEntity } from "html-entities";
import type { EncodeOptions, DecodeOptions, Level, EncodeMode, DecodeScope } from "html-entities";

const { encode, decode, decodeEntity } = require("html-entities");

import { encode, decode, decodeEntity } from "html-entities";

// Basic encoding - HTML special characters only
const encoded = encode('< > " \' & © ∆');
// Result: '&lt; &gt; &quot; &apos; &amp; © ∆'

// Basic decoding - all entities
const decoded = decode('&lt; &gt; &quot; &apos; &amp; &#169; &#8710;');
// Result: '< > " \' & © ∆'

// Single entity decoding
const singleDecoded = decodeEntity('&lt;');
// Result: '<'

// Advanced encoding with options
const advancedEncoded = encode('< ©', { mode: 'nonAsciiPrintable' });
// Result: '&lt; &copy;'

// XML-specific encoding
const xmlEncoded = encode('< ©', { mode: 'nonAsciiPrintable', level: 'xml' });
// Result: '&lt; &#169;'

/**
 * Encodes all the necessary (specified by level) characters in the text
 * @param text - Text to encode (supports null/undefined, returns empty string)
 * @param options - Encoding configuration options
 * @returns Encoded text with HTML entities
 */
function encode(
  text: string | undefined | null,
  options?: EncodeOptions
): string;

interface EncodeOptions {
  /** Encoding mode - determines which characters to encode */
  mode?: EncodeMode;
  /** Numeric format for character codes */
  numeric?: 'decimal' | 'hexadecimal';  
  /** Entity level/standard to use */
  level?: Level;
}

type EncodeMode = 
  | 'specialChars'        // Only HTML special characters (<>&"')
  | 'nonAscii'           // Special chars + all non-ASCII characters  
  | 'nonAsciiPrintable'  // Special chars + non-ASCII + non-printable ASCII
  | 'nonAsciiPrintableOnly' // Only non-ASCII printable (keeps HTML special chars intact)
  | 'extensive';         // All non-printable, non-ASCII, and characters with named references

type Level = 'xml' | 'html4' | 'html5' | 'all';

import { encode } from "html-entities";

// Basic HTML escaping
const basic = encode('<script>alert("XSS")</script>');
// Result: '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'

// Non-ASCII character encoding
const nonAscii = encode('Hello 世界 © 2023', { mode: 'nonAscii' });
// Result: 'Hello &#19990;&#30028; &copy; 2023'

// XML-only entities
const xmlOnly = encode('< > " \' &', { level: 'xml' });
// Result: '&lt; &gt; &quot; &apos; &amp;'

// Hexadecimal numeric entities
const hexEntities = encode('© ∆', { mode: 'nonAscii', numeric: 'hexadecimal' });
// Result: '&#xa9; &#x2206;'

/**
 * Decodes all entities in the text
 * @param text - Text containing HTML entities to decode
 * @param options - Decoding configuration options
 * @returns Decoded text with entities converted to characters
 */
function decode(
  text: string | undefined | null,
  options?: DecodeOptions
): string;

interface DecodeOptions {
  /** Entity level/standard to recognize */
  level?: Level;
  /** Decoding scope - affects handling of entities without semicolons */
  scope?: DecodeScope;
}

type DecodeScope = 
  | 'body'      // Browser behavior in tag bodies (entities without semicolon replaced)
  | 'attribute' // Browser behavior in attributes (entities without semicolon when not followed by =)
  | 'strict';   // Only entities with semicolons

import { decode } from "html-entities";

// Basic decoding
const basic = decode('<script>alert("XSS")</script>');
// Result: '<script>alert("XSS")</script>'

// Mixed named and numeric entities
const mixed = decode('&copy; &#169; &#xa9; &#8710;');
// Result: '© © © ∆'

// Strict decoding - only entities with semicolons
const strict = decode('&lt &gt;', { scope: 'strict' });  
// Result: '&lt &gt;' (unchanged - no semicolons)

// Body scope - entities without semicolons decoded
const body = decode('&lt &gt');
// Result: '< >' (decoded despite missing semicolons)

// XML level - only XML entities recognized
const xmlLevel = decode('&copy; &lt; &amp;', { level: 'xml' });
// Result: '&copy; < &' (copyright not decoded in XML)

/**
 * Decodes a single entity
 * @param entity - Single HTML entity to decode (e.g., '<', '©')
 * @param options - Decoding configuration options
 * @returns Decoded character or original entity if unknown
 */
function decodeEntity(
  entity: string | undefined | null,
  options?: CommonOptions
): string;

interface CommonOptions {
  /** Entity level/standard to use for recognition */
  level?: Level;
}

import { decodeEntity } from "html-entities";

// Named entity decoding
const named = decodeEntity('<');
// Result: '<'

// Numeric entity decoding
const numeric = decodeEntity('&#169;');
// Result: '©'

// Hexadecimal entity decoding  
const hex = decodeEntity('&#xa9;');
// Result: '©'

// Unknown entity (left unchanged)
const unknown = decodeEntity('&unknownentity;');
// Result: '&unknownentity;'

// Level-specific decoding
const xmlOnly = decodeEntity('&copy;', { level: 'xml' });
// Result: '&copy;' (unchanged - not an XML entity)

const htmlDecoded = decodeEntity('&copy;', { level: 'html5' });
// Result: '©'

// Main configuration types
type Level = 'xml' | 'html4' | 'html5' | 'all';

type EncodeMode = 
  | 'specialChars'        // HTML special characters only: <>&"'
  | 'nonAscii'           // Special chars + non-ASCII characters
  | 'nonAsciiPrintable'  // Special chars + non-ASCII + non-printable ASCII  
  | 'nonAsciiPrintableOnly' // Non-ASCII printable only (preserves HTML special chars)
  | 'extensive';         // Comprehensive encoding of special characters

type DecodeScope = 
  | 'strict'    // Only entities ending with semicolon
  | 'body'      // Browser body parsing (loose semicolon handling)
  | 'attribute'; // Browser attribute parsing (semicolon handling with = check)

// Options interfaces
interface EncodeOptions {
  mode?: EncodeMode;                    // Default: 'specialChars'
  numeric?: 'decimal' | 'hexadecimal'; // Default: 'decimal'  
  level?: Level;                       // Default: 'all'
}

interface DecodeOptions {
  level?: Level;        // Default: 'all'
  scope?: DecodeScope;  // Default: 'body' (or 'strict' for XML level)
}

interface CommonOptions {
  level?: Level;        // Default: 'all'
}