Function decodeEntities

xml/_entities.ts:99–158

(text: string, xml11: boolean)

 * @throws {Error} If the text contains invalid or unknown entity references.
 */
export function decodeEntities(text: string, xml11: boolean): string {
  // Fast path: no ampersand means no entities to decode
  if (!text.includes("&")) return text;

  const isValid = xml11 ? isValidXml11CharRef : isValidXml10CharRef;

  // Single-pass: decode predefined entities and char refs, error on invalid
  return text.replace(
    ENTITY_OR_AMPERSAND_REGEXP,
    (
      match: string,
      namedEntity: string | undefined,
      decimalRef: string | undefined,
      hexRef: string | undefined,
      offset: number,
    ) => {
      // Hex character reference (&#xNN;)
      if (hexRef !== undefined) {
        const codePoint = parseInt(hexRef.slice(2), 16);
        if (!isValid(codePoint)) {
          throw new Error(
            `Invalid character reference '${match}' at position ${offset}: ` +
              `code point ${codePoint} is not a valid XML character`,
          );
        }
        return String.fromCodePoint(codePoint);
      }

      // Decimal character reference (&#NN;)
      if (decimalRef !== undefined) {
        const codePoint = parseInt(decimalRef.slice(1), 10);
        if (!isValid(codePoint)) {
          throw new Error(
            `Invalid character reference '${match}' at position ${offset}: ` +
              `code point ${codePoint} is not a valid XML character`,
          );
        }
        return String.fromCodePoint(codePoint);
      }

      // Named entity (&name;)
      if (namedEntity !== undefined) {
        const predefined = NAMED_ENTITIES[namedEntity];
        if (predefined !== undefined) {
          return predefined;
        }
        throw new Error(
          `Unknown entity '${match}' at position ${offset}: ` +
            `only predefined entities (lt, gt, amp, apos, quot) are recognized`,
        );
      }

      // Bare ampersand (no valid entity pattern matched)
      throw new Error(
        `Invalid bare '&' at position ${offset}: ` +
          `use & or a valid entity reference (&name;, &#num;, &#xHex;)`,
      );
    },