Entity Decoding

/**
 * Decodes a string with entities using configurable options
 * @param input - String containing entities to decode
 * @param options - Decoding configuration or EntityLevel shorthand
 * @returns Decoded string with entities converted to characters
 */
function decode(
  input: string,
  options?: DecodingOptions | EntityLevel
): string;

interface DecodingOptions {
  /** The level of entities to support (default: EntityLevel.XML) */
  level?: EntityLevel;
  /** 
   * Decoding mode for strictness (default: DecodingMode.Legacy)
   * - Legacy: Allows entities without semicolons for HTML compatibility
   * - Strict: Requires semicolon termination
   * - Attribute: Special rules for attribute context
   */
  mode?: DecodingMode;
}

enum EntityLevel {
  /** Support only XML entities (&, <, >, ", ') */
  XML = 0,
  /** Support HTML entities (superset of XML, includes named entities like  ) */
  HTML = 1
}

enum DecodingMode {
  /** Entities in text nodes that can end with any character */
  Legacy = 0,
  /** Only allow entities terminated with a semicolon */
  Strict = 1, 
  /** Entities in attributes have limitations on ending characters */
  Attribute = 2
}

import { decode, EntityLevel, DecodingMode } from "entities";

// Basic XML decoding (default)
decode("& <hello>");
// Result: "& <hello>"

// HTML decoding with named entities
decode("&nbsp;&copy;&hearts;", EntityLevel.HTML);
// Result: " ©♥"

// Strict decoding (requires semicolons)
decode("&amp &lt;tag&gt;", { level: EntityLevel.XML, mode: DecodingMode.Strict });
// Result: "&amp <tag>" (amp without semicolon not decoded)

// Attribute context decoding
decode('value="&quot;test&quot;"', { 
  level: EntityLevel.HTML, 
  mode: DecodingMode.Attribute 
});
// Result: 'value=""test""'

/**
 * @deprecated Use decode() with mode set to DecodingMode.Strict
 * Decodes entities requiring semicolon termination
 * @param input - String to decode
 * @param options - Decoding options or EntityLevel shorthand
 * @returns Decoded string
 */
function decodeStrict(
  input: string,
  options?: DecodingOptions | EntityLevel
): string;

/**
 * Decodes HTML entities with configurable strictness
 * @param htmlString - HTML string to decode
 * @param mode - Decoding mode (default: DecodingMode.Legacy)
 * @returns Decoded string
 */
function decodeHTML(
  htmlString: string,
  mode?: DecodingMode
): string;

/**
 * Decodes HTML entities in attribute context with proper termination rules
 * @param htmlAttribute - Attribute value to decode
 * @returns Decoded attribute value
 */
function decodeHTMLAttribute(htmlAttribute: string): string;

/**
 * Decodes HTML entities requiring semicolon termination
 * @param htmlString - HTML string to decode  
 * @returns Decoded string
 */
function decodeHTMLStrict(htmlString: string): string;

import { decodeHTML, decodeHTMLAttribute, decodeHTMLStrict } from "entities/decode";

// HTML decoding with legacy mode (default)
decodeHTML("<div> Hello & world</div>");
// Result: "<div> Hello & world</div>"

// Attribute-specific decoding
decodeHTMLAttribute("title=\"&quot;Hello &amp; goodbye&quot;\"");
// Result: "title="\"Hello & goodbye\""" 

// Strict HTML decoding
decodeHTMLStrict("&amp &lt;tag&gt;"); 
// Result: "&amp <tag>" (incomplete entity not decoded)

/**
 * Decodes XML entities with strict semicolon requirement
 * All XML decoding is inherently strict
 * @param xmlString - XML string to decode
 * @returns Decoded string
 */
function decodeXML(xmlString: string): string;

import { decodeXML } from "entities/decode";

// XML decoding (always strict)
decodeXML("<root>"Hello"</root>");
// Result: "<root>&quot;Hello&quot;</root>"

// Incomplete entities are not decoded in XML
decodeXML("&amp &lt;tag&gt;");
// Result: "&amp <tag>"

// Deprecated aliases - use decodeHTML instead
function decodeHTML4(htmlString: string, mode?: DecodingMode): string;
function decodeHTML5(htmlString: string, mode?: DecodingMode): string;
function decodeHTML4Strict(htmlString: string): string;
function decodeHTML5Strict(htmlString: string): string;

// Deprecated alias - use decodeXML instead  
function decodeXMLStrict(xmlString: string): string;

import { decode, EntityLevel } from "entities";

const htmlFragments = [
  "<p>Hello & world</p>",
  " © 2023 ♥",
  ""Special 'quotes'""
];

const decodedFragments = htmlFragments.map(html => 
  decode(html, EntityLevel.HTML)
);

import { decode, decodeHTMLAttribute, DecodingMode, EntityLevel } from "entities";

// Text content decoding (permissive)
const textContent = decode(htmlText, {
  level: EntityLevel.HTML,
  mode: DecodingMode.Legacy
});

// Attribute value decoding (strict for security)
const attributeValue = decodeHTMLAttribute(attrText);

// XML content decoding (always strict)
const xmlContent = decode(xmlText, EntityLevel.XML);

import { decode, EntityLevel } from "entities";

// Malformed entities are handled gracefully
const result = decode("� &invalidEntity; &#;", EntityLevel.HTML);
// Invalid parts remain unchanged or are replaced with safe characters