Micromark String Decoder Utility

Common errors

• ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/micromark-util-decode-string/index.js

  cause Attempting to import `micromark-util-decode-string` using CommonJS `require()` syntax in a Node.js environment.
  fix Change your import statement from `const { decodeString } = require('micromark-util-decode-string');` to `import { decodeString } from 'micromark-util-decode-string';`. Ensure your `package.json` is configured for ESM, or use a bundler.

• TypeError: Cannot read properties of undefined (reading 'decodeString')

  cause This error often indicates that the module was loaded incorrectly or the named export `decodeString` was not found, possibly due to a CommonJS-style default import `import decodeString from '...'`. The package provides only named exports.
  fix Verify that you are using a named import: `import { decodeString } from 'micromark-util-decode-string';`. Avoid default imports or incorrect destructuring.

Warnings

• breaking Major versions of `micromark-util-decode-string` may drop support for unmaintained Node.js versions. Version `2.x` is compatible with Node.js 16 and higher.
  Fix: Ensure your Node.js environment is updated to a currently maintained LTS version (e.g., Node.js 16+, 18+, 20+). Refer to the Node.js release schedule for support timelines.
• gotcha This package is ESM-only and does not provide a CommonJS export. Attempting to `require()` it will result in a module loading error.
  Fix: Migrate your project to use ECMAScript Modules (`import` / `export`) or use dynamic `import()` if you need to load ESM from a CommonJS context. Ensure your `package.json` specifies `"type": "module"` if running in Node.js.

Install

• npm install micromark-util-decode-string npm
• yarn add micromark-util-decode-string yarn
• pnpm add micromark-util-decode-string pnpm

Imports

• decodeString
  wrong:

  const { decodeString } = require('micromark-util-decode-string');

  correct:

  import { decodeString } from 'micromark-util-decode-string';

  This package is ESM-only. CommonJS `require` is not supported. Use dynamic import for compatibility if needed.
• decodeString
  wrong:

  import { decodeString } from 'micromark-util-decode-string';

  correct:

  import { decodeString } from 'https://esm.sh/micromark-util-decode-string@2'

  For Deno or browser environments, use an ESM CDN like `esm.sh` and specify the version, e.g., `@2` for v2.x.
• decodeString (Type)

  import type { decodeString } from 'micromark-util-decode-string';

  When only importing the type of `decodeString`, use `import type` for better tree-shaking and clarity in TypeScript.

Quickstart

This quickstart demonstrates the `decodeString` function's capability to correctly interpret and resolve various character escapes and references found within Markdown strings, including HTML entities, numeric references, and backslash escapes. It covers common use cases for this low-level utility, which is fundamental to `micromark`'s parsing process.

import { decodeString } from 'micromark-util-decode-string';

// Example 1: Decoding HTML character references like `&`
console.log('Decoding HTML character references:');
const htmlRefString = 'This is a string with & entities ©.';
console.log(`Original: "${htmlRefString}"`);
console.log(`Decoded:  "${decodeString(htmlRefString)}"`);
// Expected output: Original: "This is a string with & entities ©."
//                  Decoded:  "This is a string with & entities ©."

console.log('\n---');

// Example 2: Decoding numeric character references (decimal and hexadecimal)
console.log('Decoding numeric character references:');
const numericRefString = 'Hello € world ☺!';
console.log(`Original: "${numericRefString}"`);
console.log(`Decoded:  "${decodeString(numericRefString)}"`);
// Expected output: Original: "Hello € world ☺!"
//                  Decoded:  "Hello € world ☺!"

console.log('\n---');

// Example 3: Decoding Markdown character escapes (e.g., backslash escapes)
console.log('Decoding Markdown character escapes:');
const escapeString = 'Special characters like \\*asterisks\\* and \\_underscores\\_ are unescaped.';
console.log(`Original: "${escapeString}"`);
console.log(`Decoded:  "${decodeString(escapeString)}"`);
// Expected output: Original: "Special characters like \*asterisks\* and \_underscores\_ are unescaped."
//                  Decoded:  "Special characters like *asterisks* and _underscores_ are unescaped."

console.log('\n---');

// Example 4: Mixed string with common markdown context, simulating internal micromark use
console.log('Mixed context decoding:');
const mixedString = 'A link title with some \\& escaped characters — "Example"';
console.log(`Original: "${mixedString}"`);
console.log(`Decoded:  "${decodeString(mixedString)}"`);
// Expected output: Original: "A link title with some \& escaped characters — "Example""
//                  Decoded:  "A link title with some & escaped characters — "Example""

// This utility is typically used internally by micromark or in custom micromark extensions
// for precise Markdown string processing.