Add safe helper on state

lib/handle/code.js

@@ -9,7 +9,6 @@
 import {longestStreak} from 'longest-streak'
 import {formatCodeAsIndented} from '../util/format-code-as-indented.js'
 import {checkFence} from '../util/check-fence.js'
-import {safe} from '../util/safe.js'
 import {track} from '../util/track.js'
 
 /**
@@ -39,7 +38,7 @@ export function code(node, _, state, info) {
   if (node.lang) {
     const subexit = state.enter(`codeFencedLang${suffix}`)
     value += tracker.move(
-      safe(state, node.lang, {
+      state.safe(node.lang, {
         before: value,
         after: ' ',
         encode: ['`'],
@@ -53,7 +52,7 @@ export function code(node, _, state, info) {
     const subexit = state.enter(`codeFencedMeta${suffix}`)
     value += tracker.move(' ')
     value += tracker.move(
-      safe(state, node.meta, {
+      state.safe(node.meta, {
         before: value,
         after: '\n',
         encode: ['`'],

lib/handle/definition.js

@@ -7,7 +7,6 @@
 
 import {association} from '../util/association.js'
 import {checkQuote} from '../util/check-quote.js'
-import {safe} from '../util/safe.js'
 import {track} from '../util/track.js'
 
 /**
@@ -25,7 +24,7 @@ export function definition(node, _, state, info) {
   const tracker = track(info)
   let value = tracker.move('[')
   value += tracker.move(
-    safe(state, association(node), {
+    state.safe(association(node), {
       before: value,
       after: ']',
       ...tracker.current()
@@ -44,14 +43,14 @@ export function definition(node, _, state, info) {
     subexit = state.enter('destinationLiteral')
     value += tracker.move('<')
     value += tracker.move(
-      safe(state, node.url, {before: value, after: '>', ...tracker.current()})
+      state.safe(node.url, {before: value, after: '>', ...tracker.current()})
     )
     value += tracker.move('>')
   } else {
     // No whitespace, raw is prettier.
     subexit = state.enter('destinationRaw')
     value += tracker.move(
-      safe(state, node.url, {
+      state.safe(node.url, {
         before: value,
         after: node.title ? ' ' : '\n',
         ...tracker.current()
@@ -65,7 +64,7 @@ export function definition(node, _, state, info) {
     subexit = state.enter(`title${suffix}`)
     value += tracker.move(' ' + quote)
     value += tracker.move(
-      safe(state, node.title, {
+      state.safe(node.title, {
         before: value,
         after: quote,
         ...tracker.current()

lib/handle/image-reference.js

@@ -6,7 +6,6 @@
  */
 
 import {association} from '../util/association.js'
-import {safe} from '../util/safe.js'
 import {track} from '../util/track.js'
 
 imageReference.peek = imageReferencePeek
@@ -24,7 +23,7 @@ export function imageReference(node, _, state, info) {
   let subexit = state.enter('label')
   const tracker = track(info)
   let value = tracker.move('![')
-  const alt = safe(state, node.alt, {
+  const alt = state.safe(node.alt, {
     before: value,
     after: ']',
     ...tracker.current()
@@ -40,7 +39,7 @@ export function imageReference(node, _, state, info) {
   // up making a `shortcut` reference, because then there is no brace output.
   // Practically, in that case, there is no content, so it doesn’t matter that
   // we’ve tracked one too many characters.
-  const reference = safe(state, association(node), {
+  const reference = state.safe(association(node), {
     before: value,
     after: ']',
     ...tracker.current()

lib/handle/image.js

@@ -6,7 +6,6 @@
  */
 
 import {checkQuote} from '../util/check-quote.js'
-import {safe} from '../util/safe.js'
 import {track} from '../util/track.js'
 
 image.peek = imagePeek
@@ -26,7 +25,7 @@ export function image(node, _, state, info) {
   const tracker = track(info)
   let value = tracker.move('![')
   value += tracker.move(
-    safe(state, node.alt, {before: value, after: ']', ...tracker.current()})
+    state.safe(node.alt, {before: value, after: ']', ...tracker.current()})
   )
   value += tracker.move('](')
 
@@ -41,14 +40,14 @@ export function image(node, _, state, info) {
     subexit = state.enter('destinationLiteral')
     value += tracker.move('<')
     value += tracker.move(
-      safe(state, node.url, {before: value, after: '>', ...tracker.current()})
+      state.safe(node.url, {before: value, after: '>', ...tracker.current()})
     )
     value += tracker.move('>')
   } else {
     // No whitespace, raw is prettier.
     subexit = state.enter('destinationRaw')
     value += tracker.move(
-      safe(state, node.url, {
+      state.safe(node.url, {
         before: value,
         after: node.title ? ' ' : ')',
         ...tracker.current()
@@ -62,7 +61,7 @@ export function image(node, _, state, info) {
     subexit = state.enter(`title${suffix}`)
     value += tracker.move(' ' + quote)
     value += tracker.move(
-      safe(state, node.title, {
+      state.safe(node.title, {
         before: value,
         after: quote,
         ...tracker.current()

lib/handle/link-reference.js

@@ -6,7 +6,6 @@
  */
 
 import {association} from '../util/association.js'
-import {safe} from '../util/safe.js'
 import {track} from '../util/track.js'
 
 linkReference.peek = linkReferencePeek
@@ -40,7 +39,7 @@ export function linkReference(node, _, state, info) {
   // up making a `shortcut` reference, because then there is no brace output.
   // Practically, in that case, there is no content, so it doesn’t matter that
   // we’ve tracked one too many characters.
-  const reference = safe(state, association(node), {
+  const reference = state.safe(association(node), {
     before: value,
     after: ']',
     ...tracker.current()

lib/handle/link.js

@@ -8,7 +8,6 @@
 
 import {checkQuote} from '../util/check-quote.js'
 import {formatLinkAsAutolink} from '../util/format-link-as-autolink.js'
-import {safe} from '../util/safe.js'
 import {track} from '../util/track.js'
 
 link.peek = linkPeek
@@ -70,14 +69,14 @@ export function link(node, _, state, info) {
     subexit = state.enter('destinationLiteral')
     value += tracker.move('<')
     value += tracker.move(
-      safe(state, node.url, {before: value, after: '>', ...tracker.current()})
+      state.safe(node.url, {before: value, after: '>', ...tracker.current()})
     )
     value += tracker.move('>')
   } else {
     // No whitespace, raw is prettier.
     subexit = state.enter('destinationRaw')
     value += tracker.move(
-      safe(state, node.url, {
+      state.safe(node.url, {
         before: value,
         after: node.title ? ' ' : ')',
         ...tracker.current()
@@ -91,7 +90,7 @@ export function link(node, _, state, info) {
     subexit = state.enter(`title${suffix}`)
     value += tracker.move(' ' + quote)
     value += tracker.move(
-      safe(state, node.title, {
+      state.safe(node.title, {
         before: value,
         after: quote,
         ...tracker.current()

lib/handle/text.js

@@ -5,8 +5,6 @@
  * @typedef {import('../types.js').Info} Info
  */
 
-import {safe} from '../util/safe.js'
-
 /**
  * @param {Text} node
  * @param {Parent | undefined} _
@@ -15,5 +13,5 @@ import {safe} from '../util/safe.js'
  * @returns {string}
  */
 export function text(node, _, state, info) {
-  return safe(state, node.value, info)
+  return state.safe(node.value, info)
 }

lib/index.js

@@ -7,6 +7,7 @@
  * @typedef {import('./types.js').Options} Options
  * @typedef {import('./types.js').Parent} Parent
  * @typedef {import('./types.js').PhrasingContent} PhrasingContent
+ * @typedef {import('./types.js').SafeConfig} SafeConfig
  * @typedef {import('./types.js').State} State
  * @typedef {import('./types.js').TrackFields} TrackFields
  */
@@ -19,6 +20,7 @@ import {unsafe} from './unsafe.js'
 import {containerPhrasing} from './util/container-phrasing.js'
 import {containerFlow} from './util/container-flow.js'
 import {indentLines} from './util/indent-lines.js'
+import {safe} from './util/safe.js'
 
 /**
  * Turn an mdast syntax tree into markdown.
@@ -37,6 +39,7 @@ export function toMarkdown(tree, options = {}) {
     indentLines,
     containerPhrasing: containerPhrasingBound,
     containerFlow: containerFlowBound,
+    safe: safeBound,
     stack: [],
     unsafe: [],
     join: [],
@@ -150,3 +153,32 @@ function containerPhrasingBound(parent, info) {
 function containerFlowBound(parent, info) {
   return containerFlow(parent, this, info)
 }
+
+/**
+ * Make a string safe for embedding in markdown constructs.
+ *
+ * In markdown, almost all punctuation characters can, in certain cases,
+ * result in something.
+ * Whether they do is highly subjective to where they happen and in what
+ * they happen.
+ *
+ * To solve this, `mdast-util-to-markdown` tracks:
+ *
+ * * Characters before and after something;
+ * * What “constructs” we are in.
+ *
+ * This information is then used by this function to escape or encode
+ * special characters.
+ *
+ * @this {State}
+ *   Info passed around about the current state.
+ * @param {string | null | undefined} value
+ *   Raw value to make safe.
+ * @param {SafeConfig} config
+ *   Configuration.
+ * @returns {string}
+ *   Serialized markdown safe for embedding.
+ */
+function safeBound(value, config) {
+  return safe(this, value, config)
+}

lib/types.js

@@ -75,6 +75,39 @@
  * @returns {string}
  *   Serialized children, joined by (blank) lines.
  *
+ * @typedef SafeEncodeFields
+ *   Extra configuration for `safe`
+ * @property {Array<string> | null | undefined} [encode]
+ *   Extra characters that *must* be encoded (as character references) instead
+ *   of escaped (character escapes).
+ *
+ *   Only ASCII punctuation will use character escapes, so you never need to
+ *   pass non-ASCII-punctuation here.
+ *
+ * @typedef {SafeFields & SafeEncodeFields} SafeConfig
+ *
+ * @callback Safe
+ *   Make a string safe for embedding in markdown constructs.
+ *
+ *   In markdown, almost all punctuation characters can, in certain cases,
+ *   result in something.
+ *   Whether they do is highly subjective to where they happen and in what
+ *   they happen.
+ *
+ *   To solve this, `mdast-util-to-markdown` tracks:
+ *
+ *   * Characters before and after something;
+ *   * What “constructs” we are in.
+ *
+ *   This information is then used by this function to escape or encode
+ *   special characters.
+ * @param {string | null | undefined} input
+ *   Raw value to make safe.
+ * @param {SafeConfig} config
+ *   Configuration.
+ * @returns {string}
+ *   Serialized markdown safe for embedding.
+ *
  * @callback Enter
  *   Enter something.
  * @param {ConstructName} name
@@ -99,6 +132,8 @@
  *   Serialize the children of a parent that contains phrasing children.
  * @property {ContainerFlow} containerFlow
  *   Serialize the children of a parent that contains flow children.
+ * @property {Safe} safe
+ *   Serialize the children of a parent that contains flow children.
  * @property {Enter} enter
  *   Enter a construct (returns a corresponding exit function).
  * @property {Options} options

lib/util/safe.js

@@ -1,16 +1,35 @@
 /**
  * @typedef {import('../types.js').State} State
- * @typedef {import('../types.js').SafeFields} SafeFields
+ * @typedef {import('../types.js').SafeConfig} SafeConfig
  */
 
 import {patternCompile} from './pattern-compile.js'
 import {patternInScope} from './pattern-in-scope.js'
 
 /**
+ * Make a string safe for embedding in markdown constructs.
+ *
+ * In markdown, almost all punctuation characters can, in certain cases,
+ * result in something.
+ * Whether they do is highly subjective to where they happen and in what
+ * they happen.
+ *
+ * To solve this, `mdast-util-to-markdown` tracks:
+ *
+ * * Characters before and after something;
+ * * What “constructs” we are in.
+ *
+ * This information is then used by this function to escape or encode
+ * special characters.
+ *
  * @param {State} state
+ *   Info passed around about the current state.
  * @param {string | null | undefined} input
- * @param {SafeFields & {encode?: Array<string>}} config
+ *   Raw value to make safe.
+ * @param {SafeConfig} config
+ *   Configuration.
  * @returns {string}
+ *   Serialized markdown safe for embedding.
  */
 export function safe(state, input, config) {
   const value = (config.before || '') + (input || '') + (config.after || '')