he

const he = require('he');

import * as he from 'he';
// or
import he from 'he';

require(['he'], function(he) {
  // use he
});

<script src="he.js"></script>
<script>
  // window.he is available
</script>

const he = require('he');

// Encode text for safe HTML insertion
const encoded = he.encode('foo © bar ≠ baz 𝌆 qux');
// → 'foo © bar ≠ baz 𝌆 qux'

// Decode HTML entities back to text
const decoded = he.decode('foo © bar ≠ baz 𝌆 qux');
// → 'foo © bar ≠ baz 𝌆 qux'

// Escape unsafe characters for HTML contexts
const escaped = he.escape('<img src="x" onerror="alert(1)">');
// → '&lt;img src=&quot;x&quot; onerror=&quot;alert(1)&quot;&gt;'

// Using named references for better readability
const withNames = he.encode('foo © bar', { useNamedReferences: true });
// → 'foo &copy; bar'

/**
 * Encodes a string by converting symbols to character references
 * @param {string} string - The input string to encode
 * @param {object} [options] - Optional configuration object  
 * @param {boolean} [options.useNamedReferences=false] - Use named references like © instead of ©
 * @param {boolean} [options.decimal=false] - Use decimal escapes © instead of hex ©
 * @param {boolean} [options.encodeEverything=false] - Encode all symbols including printable ASCII
 * @param {boolean} [options.strict=false] - Throw errors on invalid code points
 * @param {boolean} [options.allowUnsafeSymbols=false] - Don't encode unsafe HTML chars &<>"'`
 * @returns {string} Encoded string safe for HTML insertion
 */
he.encode(string, options)

// Basic encoding (hex escapes, safe characters only)
he.encode('foo © bar ≠ baz');
// → 'foo © bar ≠ baz'

// Using named references
he.encode('foo © bar ≠ baz', { useNamedReferences: true });
// → 'foo © bar ≠ baz'

// Using decimal escapes
he.encode('foo © bar', { decimal: true });
// → 'foo © bar'

// Encoding everything including ASCII
he.encode('hello', { encodeEverything: true });
// → 'hello'

// Strict mode throws on invalid code points
he.encode('foo\x00bar', { strict: true });
// → Throws Parse error

// Allow unsafe symbols (don't escape HTML characters)
he.encode('foo & bar', { allowUnsafeSymbols: true });
// → 'foo & bar'

/**
 * Decodes HTML entities in a string
 * @param {string} html - HTML string containing entities to decode
 * @param {object} [options] - Optional configuration object
 * @param {boolean} [options.isAttributeValue=false] - Treat input as HTML attribute value context
 * @param {boolean} [options.strict=false] - Throw errors on malformed character references
 * @returns {string} Decoded Unicode string
 */
he.decode(html, options)

// Basic decoding
he.decode('foo © bar ≠ baz 𝌆 qux');
// → 'foo © bar ≠ baz 𝌆 qux'

// Handles ambiguous ampersands (text context)
he.decode('foo&ampbar');
// → 'foo&bar'

// Attribute value context (different parsing rules)
he.decode('foo&ampbar', { isAttributeValue: true });
// → 'foo&ampbar'

// Strict mode throws on malformed entities
he.decode('foo&ampbar', { strict: true });
// → Throws Parse error

// Mixed entity types
he.decode('© © ©');
// → '© © ©'

/**
 * Escapes unsafe HTML characters for text contexts
 * @param {string} string - The input string to escape
 * @returns {string} String with unsafe characters escaped
 */
he.escape(string)

// Escape HTML-unsafe characters
he.escape('<script>alert("xss")</script>');
// → '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'

// Escape attribute content
he.escape('value="malicious"');
// → 'value=&quot;malicious&quot;'

// Handles all unsafe characters: & < > " ' `
he.escape('&<>"\'`');
// → '&amp;&lt;&gt;&quot;&#x27;&#x60;'

/**
 * Unescapes HTML entities (alias for decode)
 * @param {string} html - HTML string containing entities to decode
 * @param {object} [options] - Optional configuration object (same as decode)
 * @returns {string} Decoded Unicode string
 */
he.unescape(html, options)

// Identical to he.decode()
he.unescape('<script>');
// → '<script>'

// Same options as decode
he.unescape('foo&ampbar', { isAttributeValue: true });
// → 'foo&ampbar'

/** Global default options for encode function */
he.encode.options = {
  allowUnsafeSymbols: false,      // Don't encode unsafe HTML chars &<>"'`
  encodeEverything: false,        // Only encode necessary characters  
  strict: false,                  // Don't throw on invalid code points
  useNamedReferences: false,      // Use hex escapes instead of names
  decimal: false                  // Use hex instead of decimal escapes
};

/** Global default options for decode function */
he.decode.options = {
  isAttributeValue: false,        // Treat input as HTML text context
  strict: false                   // Don't throw on malformed entities
};

// Override global encode defaults
he.encode.options.useNamedReferences = true;
he.encode('foo © bar');  // Now uses named refs by default
// → 'foo © bar'

// Override global decode defaults  
he.decode.options.strict = true;
he.decode('foo&ampbar');  // Now throws on malformed entities
// → Parse error

// Read current defaults
console.log(he.encode.options.decimal);  // → false
console.log(he.decode.options.isAttributeValue);  // → false

/** Semantic version string of the library */
he.version  // '1.2.0'

console.log(he.version);  // → '1.2.0'

// Version-based feature detection
if (he.version >= '1.2.0') {
  // Use newer features
}

npm install -g he

# Encode text
he --encode 'föo ♥ bår 𝌆 baz'
# → föo ♥ bår 𝌆 baz

# Encode with named references  
he --encode --use-named-refs 'föo ♥ bår'
# → föo ♥ bår

# Decode entities
he --decode 'föo ♥ bår'
# → föo ♥ bår

# Escape HTML
he --escape '<img src="x" onerror="alert(1)">'
# → &lt;img src=&quot;x&quot; onerror=&quot;alert(1)&quot;&gt;

# Use named character references
he --encode --use-named-refs 'text © symbol'

# Encode everything including ASCII  
he --encode --everything 'hello'

# Use decimal instead of hex escapes
he --encode --decimal 'text © symbol'

# Allow unsafe HTML characters
he --encode --allow-unsafe 'text & symbol'

# Treat as HTML attribute value
he --decode --attribute 'foo&ampbar'

# Enable strict parsing mode
he --decode --strict 'foo&ampbar'

# Process files with redirection
he --encode < input.txt > output.html
he --decode < input.html > output.txt

# Process remote content
curl -s "https://example.com/data.txt" | he --encode > encoded.html

# Show version
he --version
he -v

# Show help
he --help  
he -h

// In non-strict mode, invalid code points are preserved
he.encode('foo\x00bar');  
// → 'foo\x00bar'

// In strict mode, throws Parse error
he.encode('foo\x00bar', { strict: true });
// → Parse error: forbidden code point

// In non-strict mode, malformed entities are left as-is
he.decode('foo&ampbar');
// → 'foo&bar'

// In strict mode, throws Parse error  
he.decode('foo&ampbar', { strict: true });
// → Parse error: named character reference was not terminated by a semicolon

// Handles astral symbols (4-byte Unicode) correctly
he.encode('𝌆');  // Mathematical symbol
// → '𝌆'

he.decode('𝌆');
// → '𝌆'

// Handles surrogate pairs correctly
he.encode('\uD834\uDF06');  // Same symbol as above
// → '𝌆'

/** Main library object */
const he = {
  version: '1.2.0',
  encode: function(string, options) { /* ... */ },
  decode: function(html, options) { /* ... */ },  
  escape: function(string) { /* ... */ },
  unescape: function(html, options) { /* ... */ }  // alias for decode
};

/** Encode options object properties */
const encodeOptions = {
  useNamedReferences: false,    // Use named refs like © instead of ©
  decimal: false,               // Use decimal © instead of hex ©
  encodeEverything: false,      // Encode all symbols including ASCII
  strict: false,                // Throw on invalid code points
  allowUnsafeSymbols: false     // Don't encode &<>"'` characters
};

/** Decode options object properties */
const decodeOptions = {
  isAttributeValue: false,      // Treat as HTML attribute value context
  strict: false                 // Throw on malformed character references
};

/** Error thrown in strict mode for invalid input */
throw new Error('Parse error: ' + message);