entities 6.0.1: EncodingMode

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify entities.EncodingMode in pkg:npm/entities@6.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/entities@6.0.1
Demonstrate these symbols/APIs:
  - entities.EncodingMode

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:a1859baf62978ee1913dca977108c77a25ae2244cb6a16f8bd21fc45c1629a5e","contract":["EncodingMode enum defines UTF8 (0), ASCII (1), Extensive (2), Attribute (3), and Text (4) modes","encode with EncodingMode.UTF8 escapes XML special characters while preserving non-ASCII UTF-8 characters","encode with EncodingMode.ASCII escapes HTML special characters and encodes non-ASCII characters into named entities","encode with EncodingMode.Extensive encodes all characters that have entity equivalents as well as non-ASCII characters","encode with EncodingMode.Attribute escapes characters required for HTML attributes such as double quotes and ampersands without escaping brackets","encode with EncodingMode.Text escapes characters required for HTML text such as angle brackets and ampersands without escaping quotes","encode with EntityLevel.XML and EncodingMode converts non-ASCII characters to numeric hexadecimal references in ASCII mode"],"goal":"verify entities.EncodingMode in pkg:npm/entities@6.0.1","kind":"HOW","packages":["pkg:npm/entities@6.0.1"],"schemaVersion":1,"symbols":["entities.EncodingMode"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/entities@6.0.1"],"schemaVersion":1,"subject":"pkg:npm/entities@6.0.1","symbols":["entities.EncodingMode"],"verifierAdapter":"node-typescript@1"}

import { encode, decode, EntityLevel, EncodingMode, DecodingMode } from 'entities';

/**
 * Encodes an input string with the given EncodingMode and optional EntityLevel.
 *
 * @param {string} input - The string to encode.
 * @param {EncodingMode} mode - The EncodingMode to use.
 * @param {EntityLevel} [level=EntityLevel.HTML] - The entity level (HTML or XML).
 * @returns {string} The encoded string.
 */
export function encodeWithMode(input, mode, level = EntityLevel.HTML) {
  return encode(input, { mode, level });
}

/**
 * Encodes an input string using UTF8 mode (XML special characters escaped, UTF-8 preserved).
 *
 * @param {string} input - The string to encode.
 * @param {EntityLevel} [level=EntityLevel.HTML] - The entity level.
 * @returns {string} The encoded string.
 */
export function encodeUTF8(input, level = EntityLevel.HTML) {
  return encode(input, { mode: EncodingMode.UTF8, level });
}

/**
 * Encodes an input string using ASCII mode (HTML specials and non-ASCII characters escaped).
 *
 * @param {string} input - The string to encode.
 * @param {EntityLevel} [level=EntityLevel.HTML] - The entity level.
 * @returns {string} The encoded string.
 */
export function encodeASCII(input, level = EntityLevel.HTML) {
  return encode(input, { mode: EncodingMode.ASCII, level });
}

/**
 * Encodes an input string using Extensive mode (all character entities and non-ASCII escaped).
 *
 * @param {string} input - The string to encode.
 * @param {EntityLevel} [level=EntityLevel.HTML] - The entity level.
 * @returns {string} The encoded string.
 */
export function encodeExtensive(input, level = EntityLevel.HTML) {
  return encode(input, { mode: EncodingMode.Extensive, level });
}

/**
 * Encodes an input string using Attribute mode (safe for HTML attribute values).
 *
 * @param {string} input - The string to encode.
 * @returns {string} The encoded string.
 */
export function encodeAttribute(input) {
  return encode(input, { mode: EncodingMode.Attribute, level: EntityLevel.HTML });
}

/**
 * Encodes an input string using Text mode (safe for HTML text nodes).
 *
 * @param {string} input - The string to encode.
 * @returns {string} The encoded string.
 */
export function encodeText(input) {
  return encode(input, { mode: EncodingMode.Text, level: EntityLevel.HTML });
}

export { encode, decode, EntityLevel, EncodingMode, DecodingMode };
export default EncodingMode;

{
  "name": "sample-entities-encoding-mode",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-entities-encoding-mode",
      "version": "1.0.0",
      "dependencies": {
        "entities": "6.0.1"
      }
    },
    "node_modules/entities": {
      "version": "6.0.1",
      "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
      "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=0.12"
      },
      "funding": {
        "url": "https://github.com/fb55/entities?sponsor=1"
      }
    }
  }
}

{
  "name": "sample-entities-encoding-mode",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "entities": "6.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify entities.EncodingMode in pkg:npm/entities@6.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/entities@6.0.1"
  ],
  "symbols": [
    "entities.EncodingMode"
  ]
}

import assert from 'node:assert/strict';
import {
  EncodingMode,
  EntityLevel,
  encode,
  encodeWithMode,
  encodeUTF8,
  encodeASCII,
  encodeExtensive,
  encodeAttribute,
  encodeText,
} from '../index.mjs';

// 1. EncodingMode enum defines UTF8 (0), ASCII (1), Extensive (2), Attribute (3), and Text (4) modes
{
  assert.strictEqual(EncodingMode.UTF8, 0);
  assert.strictEqual(EncodingMode.ASCII, 1);
  assert.strictEqual(EncodingMode.Extensive, 2);
  assert.strictEqual(EncodingMode.Attribute, 3);
  assert.strictEqual(EncodingMode.Text, 4);

  assert.strictEqual(EncodingMode[0], 'UTF8');
  assert.strictEqual(EncodingMode[1], 'ASCII');
  assert.strictEqual(EncodingMode[2], 'Extensive');
  assert.strictEqual(EncodingMode[3], 'Attribute');
  assert.strictEqual(EncodingMode[4], 'Text');
}

// 2. encode with EncodingMode.UTF8 escapes XML special characters while preserving non-ASCII UTF-8 characters
{
  const input = '<div class="main">&copy; "hello" \'world\' \u20AC</div>';
  const out = encodeWithMode(input, EncodingMode.UTF8, EntityLevel.HTML);
  assert.strictEqual(out, '&lt;div class=&quot;main&quot;&gt;&amp;copy; &quot;hello&quot; &apos;world&apos; €&lt;/div&gt;');

  const direct = encodeUTF8(input);
  assert.strictEqual(direct, out);
}

// 3. encode with EncodingMode.ASCII escapes HTML special characters and encodes non-ASCII characters into named entities
{
  const input = '<div class="main">&copy; "hello" \'world\' \u20AC</div>';
  const out = encodeWithMode(input, EncodingMode.ASCII, EntityLevel.HTML);
  assert.strictEqual(out, '&lt;div class=&quot;main&quot;&gt;&amp;copy; &quot;hello&quot; &apos;world&apos; &euro;&lt;/div&gt;');

  const direct = encodeASCII(input);
  assert.strictEqual(direct, out);
}

// 4. encode with EncodingMode.Extensive encodes all characters that have entity equivalents as well as non-ASCII characters
{
  const input = '<div class="main">&copy; 2024</div>';
  const out = encodeWithMode(input, EncodingMode.Extensive, EntityLevel.HTML);
  assert.strictEqual(out, '&lt;div class&equals;&quot;main&quot;&gt;&amp;copy&semi; 2024&lt;&sol;div&gt;');

  const direct = encodeExtensive(input);
  assert.strictEqual(direct, out);
}

// 5. encode with EncodingMode.Attribute escapes characters required for HTML attributes such as double quotes and ampersands without escaping brackets
{
  const input = '<div class="test">&copy; 2024 "Hello" & \'World\' \u20AC</div>';
  const out = encodeAttribute(input);
  assert.strictEqual(out, '<div class=&quot;test&quot;>&amp;copy; 2024 &quot;Hello&quot; &amp; \'World\' €</div>');
}

// 6. encode with EncodingMode.Text escapes characters required for HTML text such as angle brackets and ampersands without escaping quotes
{
  const input = '<div class="test">&copy; 2024 "Hello" & \'World\' \u20AC</div>';
  const out = encodeText(input);
  assert.strictEqual(out, '&lt;div class="test"&gt;&amp;copy; 2024 "Hello" &amp; \'World\' €&lt;/div&gt;');
}

// 7. encode with EntityLevel.XML and EncodingMode converts non-ASCII characters to numeric hexadecimal references in ASCII mode
{
  const input = '<tag id="1">& "val" \'item\' \u00A9 \u20AC</tag>';
  const asciiOut = encode(input, { level: EntityLevel.XML, mode: EncodingMode.ASCII });
  assert.strictEqual(asciiOut, '&lt;tag id=&quot;1&quot;&gt;&amp; &quot;val&quot; &apos;item&apos; &#xa9; &#x20ac;&lt;/tag&gt;');

  const utf8Out = encode(input, { level: EntityLevel.XML, mode: EncodingMode.UTF8 });
  assert.strictEqual(utf8Out, '&lt;tag id=&quot;1&quot;&gt;&amp; &quot;val&quot; &apos;item&apos; \u00A9 \u20AC&lt;/tag&gt;');
}

console.log('Contract assertions for entities.EncodingMode passed successfully.');