Entity Encoding

/**
 * Encodes a string with entities using configurable options
 * @param input - String to encode
 * @param options - Encoding configuration or EntityLevel shorthand
 * @returns Encoded string with characters converted to entities
 */
function encode(
  input: string,
  options?: EncodingOptions | EntityLevel
): string;

interface EncodingOptions {
  /** The level of entities to support (default: EntityLevel.XML) */
  level?: EntityLevel;
  /** Output encoding format (default: EncodingMode.Extensive) */
  mode?: EncodingMode;
}

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

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

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

// Basic XML encoding (default: extensive mode)
encode('<script>alert("XSS")</script>');
// Result: "&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;"

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

// ASCII-only output
encode("Café & 世界", { 
  level: EntityLevel.HTML, 
  mode: EncodingMode.ASCII 
});
// Result: "Caf&#xe9; &amp; &#x4e16;&#x754c;"

// HTML extensive encoding with named entities
encode("© 2023 → ♥", { 
  level: EntityLevel.HTML, 
  mode: EncodingMode.Extensive 
});
// Result: "&copy; 2023 &rarr; &hearts;"

// HTML attribute context encoding
encode('Say "Hello" & goodbye', { 
  level: EntityLevel.HTML,
  mode: EncodingMode.Attribute 
});
// Result: "Say &quot;Hello&quot; &amp; goodbye"

// HTML text context encoding  
encode("2 < 3 & 4 > 1", {
  level: EntityLevel.HTML,
  mode: EncodingMode.Text
});
// Result: "2 &lt; 3 &amp; 4 &gt; 1"

/**
 * Encodes all characters using HTML entities, including valid ASCII characters
 * Most comprehensive encoding - encodes characters like # and ; as entities
 * @param input - String to encode
 * @returns Extensively encoded string
 */
function encodeHTML(input: string): string;

/**
 * Encodes only non-ASCII characters and HTML-invalid characters
 * More compact than encodeHTML - leaves valid ASCII characters unencoded
 * @param input - String to encode  
 * @returns Selectively encoded string
 */
function encodeNonAsciiHTML(input: string): string;

import { encodeHTML, encodeNonAsciiHTML } from "entities";

// Comprehensive HTML encoding
encodeHTML("Hello! #hashtag & café");
// Result: "Hello! #hashtag & café"

// Selective HTML encoding (more compact)
encodeNonAsciiHTML("Hello! #hashtag & café");  
// Result: "Hello! #hashtag & café"

// Deprecated aliases - use encodeHTML instead
function encodeHTML4(input: string): string;
function encodeHTML5(input: string): string;

encode("Café & 日本語", { mode: EncodingMode.UTF8 });
// Result: "Café & 日本語"

encode("Café & 日本語", { 
  level: EntityLevel.HTML,
  mode: EncodingMode.ASCII 
});
// Result: "Café & 日本語"

encode("© 2023 → ♥", { 
  level: EntityLevel.HTML,
  mode: EncodingMode.Extensive 
});
// Result: "© 2023 → ♥"

encode('title="Hello & world"', { mode: EncodingMode.Attribute });
// Result: "title="Hello & world""

encode("2 < 3 & 4 > 1", { mode: EncodingMode.Text });
// Result: "2 &lt; 3 &amp; 4 &gt; 1"

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

function encodeForContext(text: string, context: 'xml' | 'html-attr' | 'html-text') {
  switch (context) {
    case 'xml':
      return encode(text, { level: EntityLevel.XML, mode: EncodingMode.UTF8 });
    case 'html-attr':
      return encode(text, { level: EntityLevel.HTML, mode: EncodingMode.Attribute });
    case 'html-text':
      return encode(text, { level: EntityLevel.HTML, mode: EncodingMode.Text });
    default:
      return encode(text);
  }
}

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

function createHTMLTemplate(data: Record<string, string>) {
  return `
    <div class="user-card">
      <h2>${encode(data.name, { level: EntityLevel.HTML, mode: EncodingMode.Text })}</h2>
      <p title="${encode(data.bio, { level: EntityLevel.HTML, mode: EncodingMode.Attribute })}">
        ${encode(data.description, { level: EntityLevel.HTML, mode: EncodingMode.Text })}
      </p>
    </div>
  `;
}

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

const userInputs = ['<script>', 'Hello & world', '"quotes"'];

const safeOutputs = userInputs.map(input => 
  encode(input, { 
    level: EntityLevel.HTML, 
    mode: EncodingMode.Text 
  })
);

// Security-focused encoding example
function secureHTMLInsertion(userInput: string, context: 'text' | 'attribute') {
  const mode = context === 'text' ? EncodingMode.Text : EncodingMode.Attribute;
  return encode(userInput, { 
    level: EntityLevel.HTML, 
    mode 
  });
}