Add createTracker helper on state

wooorm · wooorm · commit 35ceafcec038 · 2023-01-04T11:35:26.000+01:00
diff --git a/index.d.ts b/index.d.ts
@@ -316,7 +316,9 @@ export type {
   Join,
   Map,
   Options,
+  SafeConfig,
   State,
+  Tracker,
   Unsafe
 } from './lib/types.js'
 // Deprecated.
diff --git a/lib/handle/blockquote.js b/lib/handle/blockquote.js
@@ -6,8 +6,6 @@
  * @typedef {import('../types.js').Map} Map
  */
 
-import {track} from '../util/track.js'
-
 /**
  * @param {Blockquote} node
  * @param {Parent | undefined} _
@@ -17,7 +15,7 @@ import {track} from '../util/track.js'
  */
 export function blockquote(node, _, state, info) {
   const exit = state.enter('blockquote')
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   tracker.move('> ')
   tracker.shift(2)
   const value = state.indentLines(
diff --git a/lib/handle/code.js b/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 {track} from '../util/track.js'
 
 /**
  * @param {Code} node
@@ -30,7 +29,7 @@ export function code(node, _, state, info) {
     return value
   }
 
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   const sequence = marker.repeat(Math.max(longestStreak(raw, marker) + 1, 3))
   const exit = state.enter('codeFenced')
   let value = tracker.move(sequence)
diff --git a/lib/handle/definition.js b/lib/handle/definition.js
@@ -7,7 +7,6 @@
 
 import {association} from '../util/association.js'
 import {checkQuote} from '../util/check-quote.js'
-import {track} from '../util/track.js'
 
 /**
  * @param {Definition} node
@@ -21,7 +20,7 @@ export function definition(node, _, state, info) {
   const suffix = quote === '"' ? 'Quote' : 'Apostrophe'
   const exit = state.enter('definition')
   let subexit = state.enter('label')
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   let value = tracker.move('[')
   value += tracker.move(
     state.safe(association(node), {
diff --git a/lib/handle/emphasis.js b/lib/handle/emphasis.js
@@ -6,7 +6,6 @@
  */
 
 import {checkEmphasis} from '../util/check-emphasis.js'
-import {track} from '../util/track.js'
 
 emphasis.peek = emphasisPeek
 
@@ -24,7 +23,7 @@ emphasis.peek = emphasisPeek
 export function emphasis(node, _, state, info) {
   const marker = checkEmphasis(state)
   const exit = state.enter('emphasis')
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   let value = tracker.move(marker)
   value += tracker.move(
     state.containerPhrasing(node, {
diff --git a/lib/handle/heading.js b/lib/handle/heading.js
@@ -6,7 +6,6 @@
  */
 
 import {formatHeadingAsSetext} from '../util/format-heading-as-setext.js'
-import {track} from '../util/track.js'
 
 /**
  * @param {Heading} node
@@ -17,7 +16,7 @@ import {track} from '../util/track.js'
  */
 export function heading(node, _, state, info) {
   const rank = Math.max(Math.min(6, node.depth || 1), 1)
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
 
   if (formatHeadingAsSetext(node, state)) {
     const exit = state.enter('headingSetext')
diff --git a/lib/handle/image-reference.js b/lib/handle/image-reference.js
@@ -6,7 +6,6 @@
  */
 
 import {association} from '../util/association.js'
-import {track} from '../util/track.js'
 
 imageReference.peek = imageReferencePeek
 
@@ -21,7 +20,7 @@ export function imageReference(node, _, state, info) {
   const type = node.referenceType
   const exit = state.enter('imageReference')
   let subexit = state.enter('label')
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   let value = tracker.move('![')
   const alt = state.safe(node.alt, {
     before: value,
diff --git a/lib/handle/image.js b/lib/handle/image.js
@@ -6,7 +6,6 @@
  */
 
 import {checkQuote} from '../util/check-quote.js'
-import {track} from '../util/track.js'
 
 image.peek = imagePeek
 
@@ -22,7 +21,7 @@ export function image(node, _, state, info) {
   const suffix = quote === '"' ? 'Quote' : 'Apostrophe'
   const exit = state.enter('image')
   let subexit = state.enter('label')
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   let value = tracker.move('![')
   value += tracker.move(
     state.safe(node.alt, {before: value, after: ']', ...tracker.current()})
diff --git a/lib/handle/link-reference.js b/lib/handle/link-reference.js
@@ -6,7 +6,6 @@
  */
 
 import {association} from '../util/association.js'
-import {track} from '../util/track.js'
 
 linkReference.peek = linkReferencePeek
 
@@ -21,7 +20,7 @@ export function linkReference(node, _, state, info) {
   const type = node.referenceType
   const exit = state.enter('linkReference')
   let subexit = state.enter('label')
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   let value = tracker.move('[')
   const text = state.containerPhrasing(node, {
     before: value,
diff --git a/lib/handle/link.js b/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 {track} from '../util/track.js'
 
 link.peek = linkPeek
 
@@ -22,7 +21,7 @@ link.peek = linkPeek
 export function link(node, _, state, info) {
   const quote = checkQuote(state)
   const suffix = quote === '"' ? 'Quote' : 'Apostrophe'
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   /** @type {Exit} */
   let exit
   /** @type {Exit} */
diff --git a/lib/handle/list-item.js b/lib/handle/list-item.js
@@ -8,7 +8,6 @@
 
 import {checkBullet} from '../util/check-bullet.js'
 import {checkListItemIndent} from '../util/check-list-item-indent.js'
-import {track} from '../util/track.js'
 
 /**
  * @param {ListItem} node
@@ -43,7 +42,7 @@ export function listItem(node, parent, state, info) {
     size = Math.ceil(size / 4) * 4
   }
 
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   tracker.move(bullet + ' '.repeat(size - bullet.length))
   tracker.shift(size)
   const exit = state.enter('listItem')
diff --git a/lib/handle/strong.js b/lib/handle/strong.js
@@ -6,7 +6,6 @@
  */
 
 import {checkStrong} from '../util/check-strong.js'
-import {track} from '../util/track.js'
 
 strong.peek = strongPeek
 
@@ -24,7 +23,7 @@ strong.peek = strongPeek
 export function strong(node, _, state, info) {
   const marker = checkStrong(state)
   const exit = state.enter('strong')
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   let value = tracker.move(marker + marker)
   value += tracker.move(
     state.containerPhrasing(node, {
diff --git a/lib/index.js b/lib/index.js
@@ -21,6 +21,7 @@ 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'
+import {track} from './util/track.js'
 
 /**
  * Turn an mdast syntax tree into markdown.
@@ -39,6 +40,7 @@ export function toMarkdown(tree, options = {}) {
     indentLines,
     containerPhrasing: containerPhrasingBound,
     containerFlow: containerFlowBound,
+    createTracker: track,
     safe: safeBound,
     stack: [],
     unsafe: [],
diff --git a/lib/types.js b/lib/types.js
@@ -32,6 +32,47 @@
  * @typedef {TrackFields & SafeFields} Info
  *   Info on the surrounding of the node that is serialized.
  *
+ * @callback TrackCurrent
+ *   Get current tracked info.
+ * @returns {TrackFields}
+ *   Current tracked info.
+ *
+ * @callback TrackShift
+ *   Define a relative increased line shift (the typical indent for lines).
+ * @param {number} value
+ *   Relative increment in how much each line will be padded.
+ * @returns {void}
+ *   Nothing.
+ *
+ * @callback TrackMove
+ *   Move past some generated markdown.
+ * @param {string | null | undefined} value
+ *   Generated markdown.
+ * @returns {string}
+ *   Given markdown.
+ *
+ * @typedef Tracker
+ *   Track positional info in the output.
+ *
+ *   This info isn’t used yet but such functionality will allow line wrapping,
+ *   source maps, etc.
+ * @property {TrackCurrent} current
+ *   Get the current tracked info.
+ * @property {TrackShift} shift
+ *   Define an increased line shift (the typical indent for lines).
+ * @property {TrackMove} move
+ *   Move past some generated markdown.
+ *
+ * @callback CreateTracker
+ *   Track positional info in the output.
+ *
+ *   This info isn’t used yet but such functionality will allow line wrapping,
+ *   source maps, etc.
+ * @param {TrackFields} info
+ *   Info on where we are in the document we are generating.
+ * @returns {Tracker}
+ *   Tracker.
+ *
  * @callback Map
  *   Map function to pad a single line.
  * @param {string} value
@@ -132,6 +173,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 {CreateTracker} createTracker
+ *   Track positional info in the output.
  * @property {Safe} safe
  *   Serialize the children of a parent that contains flow children.
  * @property {Enter} enter
diff --git a/lib/util/container-flow.js b/lib/util/container-flow.js
@@ -6,8 +6,6 @@
  * @typedef {import('../types.js').TrackFields} TrackFields
  */
 
-import {track} from './track.js'
-
 /**
  * @param {Parent & {children: Array<FlowContent>}} parent
  *   Parent of flow nodes.
@@ -21,7 +19,7 @@ import {track} from './track.js'
 export function containerFlow(parent, state, info) {
   const indexStack = state.indexStack
   const children = parent.children || []
-  const tracker = track(info)
+  const tracker = state.createTracker(info)
   /** @type {Array<string>} */
   const results = []
   let index = -1
diff --git a/lib/util/container-phrasing.js b/lib/util/container-phrasing.js
@@ -6,8 +6,6 @@
  * @typedef {import('../types.js').State} State
  */
 
-import {track} from './track.js'
-
 /**
  * Serialize the children of a parent that contains phrasing children.
  *
@@ -31,7 +29,7 @@ export function containerPhrasing(parent, state, info) {
   let before = info.before
 
   indexStack.push(-1)
-  let tracker = track(info)
+  let tracker = state.createTracker(info)
 
   while (++index < children.length) {
     const child = children[index]
@@ -76,7 +74,7 @@ export function containerPhrasing(parent, state, info) {
       before = ' '
 
       // To do: does this work to reset tracker?
-      tracker = track(info)
+      tracker = state.createTracker(info)
       tracker.move(results.join(''))
     }
 
diff --git a/lib/util/track.js b/lib/util/track.js
@@ -1,21 +1,20 @@
 /**
- * @typedef {import('unist').Point} Point
- * @typedef {import('../types.js').TrackFields} TrackFields
+ * @typedef {import('../types.js').CreateTracker} CreateTracker
+ * @typedef {import('../types.js').TrackCurrent} TrackCurrent
+ * @typedef {import('../types.js').TrackMove} TrackMove
+ * @typedef {import('../types.js').TrackShift} TrackShift
  */
 
 /**
- * Functions to track output positions.
+ * Track positional info in the output.
  *
- * This info isn’t used yet but suchs functionality allows line wrapping,
- * and theoretically source maps (though, is there practical use in that?).
- *
- * @param {TrackFields} options_
+ * @type {CreateTracker}
  */
-export function track(options_) {
+export function track(config) {
   // Defaults are used to prevent crashes when older utilities somehow activate
   // this code.
   /* c8 ignore next 5 */
-  const options = options_ || {}
+  const options = config || {}
   const now = options.now || {}
   let lineShift = options.lineShift || 0
   let line = now.line || 1
@@ -26,7 +25,7 @@ export function track(options_) {
   /**
    * Get the current tracked info.
    *
-   * @returns {TrackFields}
+   * @type {TrackCurrent}
    */
   function current() {
     return {now: {line, column}, lineShift}
@@ -35,19 +34,20 @@ export function track(options_) {
   /**
    * Define an increased line shift (the typical indent for lines).
    *
-   * @param {number} value
+   * @type {TrackShift}
    */
   function shift(value) {
     lineShift += value
   }
 
   /**
-   * Move past a string.
+   * Move past some generated markdown.
    *
-   * @param {string} value
-   * @returns {string}
+   * @type {TrackMove}
    */
-  function move(value = '') {
+  function move(input) {
+    // eslint-disable-next-line unicorn/prefer-default-parameters
+    const value = input || ''
     const chunks = value.split(/\r?\n|\r/g)
     const tail = chunks[chunks.length - 1]
     line += chunks.length - 1
diff --git a/readme.md b/readme.md
