Entity Escaping

/**
 * Encodes only XML-critical characters for UTF-8 output
 * Fastest escaping option - only escapes: " & ' < >
 * @param data - String to escape
 * @returns String with only essential XML characters escaped
 */
function escapeUTF8(data: string): string;

import { escapeUTF8 } from "entities/escape";

// Minimal escaping for UTF-8 content
escapeUTF8('Hello & "world" <tag>');
// Result: 'Hello &amp; &quot;world&quot; &lt;tag&gt;'

// Unicode characters preserved
escapeUTF8("Café & 世界 <hello>");
// Result: "Café &amp; 世界 &lt;hello&gt;"

/**
 * Escapes characters for HTML attribute values
 * Follows WHATWG HTML spec for attribute context
 * Escapes: " & \u00A0 (quote, ampersand, non-breaking space)
 * @param data - String to escape
 * @returns String safe for HTML attribute values
 */
function escapeAttribute(data: string): string;

/**
 * Escapes characters for HTML text content  
 * Follows WHATWG HTML spec for text context
 * Escapes: & < > \u00A0 (ampersand, less-than, greater-than, nbsp)
 * @param data - String to escape
 * @returns String safe for HTML text content
 */
function escapeText(data: string): string;

import { escapeAttribute, escapeText } from "entities/escape";

// HTML attribute escaping
escapeAttribute('Say "Hello" & goodbye');
// Result: 'Say "Hello" & goodbye'

// HTML text escaping
escapeText("2 < 3 & 4 > 1");  
// Result: "2 &lt; 3 &amp; 4 &gt; 1"

// Non-breaking space handling
escapeText("Word\u00A0word");
// Result: "Word&nbsp;word"

/**
 * Encodes all non-ASCII characters and XML-invalid characters using XML entities
 * If a character has no equivalent entity, uses numeric hexadecimal reference
 * @param input - String to encode
 * @returns Fully encoded XML-safe string
 */
function encodeXML(input: string): string;

/**
 * Alias for encodeXML function for backward compatibility
 * @param input - String to encode  
 * @returns Fully encoded XML-safe string
 */
function escape(input: string): string;

import { encodeXML, escape } from "entities/escape";

// Full XML encoding
encodeXML("Café & <script>alert('XSS')</script>");
// Result: "Caf&#xe9; &amp; &lt;script&gt;alert(&apos;XSS&apos;)&lt;/script&gt;"

// Using the alias
escape('<hello>world & "quotes"</hello>');
// Result: "&lt;hello&gt;world &amp; &quot;quotes&quot;&lt;/hello&gt;"

// Non-ASCII characters become numeric entities
encodeXML("世界");
// Result: "&#x4e16;&#x754c;"

/**
 * Regular expression for matching XML characters needing replacement
 * Matches: " $ & ' < > and all characters from U+0080 to U+FFFF
 */
const xmlReplacer: RegExp;

/**
 * Gets Unicode code point at specified index (polyfill for older environments)
 * @param c - Input string
 * @param index - Character index
 * @returns Unicode code point
 */
function getCodePoint(c: string, index: number): number;

import { escapeAttribute, escapeText } from "entities/escape";

function buildHTMLElement(tag: string, attributes: Record<string, string>, content: string) {
  const attrs = Object.entries(attributes)
    .map(([key, value]) => `${key}="${escapeAttribute(value)}"`)
    .join(' ');
    
  return `<${tag} ${attrs}>${escapeText(content)}</${tag}>`;
}

// Usage
const html = buildHTMLElement('div', 
  { 
    class: 'user-input',
    title: 'Contains "quotes" & symbols' 
  },
  'User said: <script>alert("XSS")</script>'
);
// Result: <div class="user-input" title="Contains &quot;quotes&quot; &amp; symbols">User said: &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;</div>

import { escapeUTF8 } from "entities/escape";

function processTextStream(chunks: string[]): string[] {
  return chunks.map(chunk => escapeUTF8(chunk));
}

// Safe for concatenation
const safeChunks = processTextStream(['Hello & ', 'world <tag>']);
const result = safeChunks.join('');
// Result: "Hello &amp; world &lt;tag&gt;"

import { escapeAttribute, escapeText, escapeUTF8 } from "entities/escape";

type HTMLContext = 'text' | 'attribute' | 'xml';

function contextualEscape(input: string, context: HTMLContext): string {
  switch (context) {
    case 'text':
      return escapeText(input);
    case 'attribute':
      return escapeAttribute(input);  
    case 'xml':
      return escapeUTF8(input);
    default:
      throw new Error(`Unknown context: ${context}`);
  }
}

import { escapeText } from "entities/escape";

function escapeUserInputs(inputs: string[]): string[] {
  return inputs.map(input => escapeText(input));
}

// Safe processing of multiple user inputs
const userComments = [
  "Great post! <3",
  "Check out this link: http://example.com?a=1&b=2", 
  "Quote: \"Be yourself\" - Someone"
];

const safeComments = escapeUserInputs(userComments);
// All comments are now HTML-safe

import { escapeText, escapeAttribute } from "entities/escape";

// GOOD: Escape user input before HTML insertion
function safeHTMLInsertion(userInput: string) {
  return `<div>${escapeText(userInput)}</div>`;
}

// GOOD: Escape attribute values
function safeAttributeInsertion(userValue: string) {
  return `<input value="${escapeAttribute(userValue)}">`;
}

// BAD: Never insert unescaped user input
function unsafeInsertion(userInput: string) {
  return `<div>${userInput}</div>`; // VULNERABLE TO XSS
}

// Correct context usage
`<div title="${escapeAttribute(userTitle)}">${escapeText(userContent)}</div>`

// Incorrect - using wrong context
`<div title="${escapeText(userTitle)}">${escapeAttribute(userContent)}</div>`

import { encode, EncodingMode } from "entities";
import { escapeUTF8, escapeAttribute, escapeText } from "entities/escape";

// These are equivalent:
escapeUTF8(input) === encode(input, { mode: EncodingMode.UTF8 })
escapeAttribute(input) === encode(input, { mode: EncodingMode.Attribute })  
escapeText(input) === encode(input, { mode: EncodingMode.Text })