perf: improve heap space usage

Author: harlan-zw

src/const.ts

@@ -235,6 +235,9 @@ export const TRACK_DEPTH_MAP_KEYS = [
   TAG_TH,
 ]
 
+// Maximum tag ID for creating the typed array (97 for TAG_RP + 1 for buffer)
+export const MAX_TAG_ID = 98
+
 // Pre-defined strings to avoid repeated allocations
 export const FRONTMATTER_START = '---'
 export const FRONTMATTER_END = '\n---'

src/parser.ts

@@ -1,6 +1,7 @@
-import type { MdreamProcessingState, MdreamRuntimeState, Node, NodeEvent, ParentNode } from './types.ts'
+import type { DepthMapArray, MdreamProcessingState, MdreamRuntimeState, Node, NodeEvent, ParentNode } from './types.ts'
 import {
   ELEMENT_NODE,
+  MAX_TAG_ID,
   NodeEventEnter,
   NodeEventExit,
   TAG_A,
@@ -39,19 +40,12 @@ const TAB_CHAR = 9 // '\t'
 const NEWLINE_CHAR = 10 // '\n'
 const CARRIAGE_RETURN_CHAR = 13 // '\r'
 
-// Pre-allocate arrays to reduce allocations
+// Pre-allocate arrays and objects to reduce allocations
 const EMPTY_ATTRIBUTES: Record<string, string> = Object.freeze({})
 
-// Fast object copy for small objects like depthMap
+// Fast typed array copy for depthMap
 function copyDepthMap(depthMap: Node['depthMap']): Node['depthMap'] {
-  const copy: Node['depthMap'] = {}
-  for (let i = 0; i < TRACK_DEPTH_MAP_KEYS.length; i++) {
-    const key = TRACK_DEPTH_MAP_KEYS[i]
-    if (depthMap[key]) {
-      copy[key] = depthMap[key]
-    }
-  }
-  return copy
+  return new Uint8Array(depthMap)
 }
 
 /**
@@ -74,7 +68,7 @@ export function parseHTML(htmlChunk: string, state: MdreamProcessingState, handl
   let textBuffer = '' // Buffer to accumulate text content
 
   // Initialize state
-  state.depthMap ??= {}
+  state.depthMap ??= new Uint8Array(MAX_TAG_ID) // Initialize using typed array
   state.depth ??= 0
   state.lastCharWasWhitespace ??= true // don't allow subsequent whitespace at start
   state.justClosedTag ??= false
@@ -448,7 +442,7 @@ function closeNode(node: ParentNode | Node | null, state: MdreamProcessingState,
   }
 
   if (node.tagId) {
-    state.depthMap[node.tagId] = Math.max(0, (state.depthMap[node.tagId] || 0) - 1)
+    state.depthMap[node.tagId] = Math.max(0, state.depthMap[node.tagId] - 1)
   }
 
   if (state.inUnsupportedNodeDepth === state.depth) {
@@ -553,22 +547,13 @@ function processOpeningTag(
     closeNode(state.currentElementNode, state, handleEvent)
   }
 
-  // Fast increment depth tracking
-  const currentTagCount = state.depthMap[tagId] || 0
-  state.depthMap[tagId] = currentTagCount + 1
-  state.depth++
-
   // Get tag handler for this tag
   const tagHandler = tagHandlers[tagId]
 
   // Process attributes and tag properties
   const result = processTagAttributes(htmlChunk, i, tagHandler)
 
   if (!result.complete) {
-    // Roll back depth changes
-    state.depthMap[tagId] = currentTagCount
-    state.depth--
-
     return {
       complete: false,
       newPosition: i,
@@ -577,6 +562,11 @@ function processOpeningTag(
     }
   }
 
+  // Fast increment depth tracking with Uint8Array
+  const currentTagCount = state.depthMap[tagId]
+  state.depthMap[tagId] = currentTagCount + 1
+  state.depth++
+
   i = result.newPosition
 
   // Pre-compute flags
@@ -823,6 +813,7 @@ export function processPartialHTMLToMarkdown(
   state: Partial<MdreamRuntimeState> = {},
 ): { chunk: string, remainingHTML: string } {
   state.fragmentCount = 0
+  state.depthMap ??= new Uint8Array(MAX_TAG_ID)
 
   const strategy = state.options?.strategy
   const isMinimalFromFirstHeader = strategy === 'minimal-from-first-header'

src/types.ts

@@ -17,6 +17,13 @@ export interface HTMLToMarkdownOptions {
 export const ELEMENT_NODE = 1
 export const TEXT_NODE = 3
 
+/**
+ * Type for the optimized depth map using Uint8Array
+ * This replaces the Record<number, number> with a fixed-size typed array
+ * for faster property access
+ */
+export type DepthMapArray = Uint8Array
+
 /**
  * Base DOM node interface
  */
@@ -39,8 +46,8 @@ export interface Node {
   /** Current nesting depth in the DOM tree */
   depth: number
 
-  /** Map of tag names to their nesting count */
-  depthMap: Required<MdreamRuntimeState>['depthMap']
+  /** Map of tag names to their nesting count (using Uint8Array for performance) */
+  depthMap: DepthMapArray
 
   /** Whether this node should be excluded from output */
   minimal: boolean
@@ -80,8 +87,8 @@ export interface ParentNode extends Node {
  * State interface for HTML parsing and processing
  */
 export interface MdreamProcessingState {
-  /** Map of tag names to their current nesting depth */
-  depthMap: Record<number, number>
+  /** Map of tag names to their current nesting depth (using Uint8Array for performance) */
+  depthMap: DepthMapArray
 
   /** Current overall nesting depth */
   depth: number

test/unit/walk.test.ts

@@ -1,6 +1,6 @@
 import type { MdreamProcessingState, NodeEvent } from '../../src/types.js'
 import { describe, expect, it } from 'vitest'
-import { NodeEventEnter } from '../../src/const.js'
+import { MAX_TAG_ID, NodeEventEnter } from '../../src/const.js'
 import { syncHtmlToMarkdown } from '../../src/index.js'
 import { parseHTML } from '../../src/parser.js'
 
@@ -10,7 +10,7 @@ describe('hTML walking', () => {
     const depthLog: { tagName: string, depth: number, event: string }[] = []
 
     const state: Partial<MdreamProcessingState> = {
-      depthMap: {},
+      depthMap: new Uint8Array(MAX_TAG_ID),
       depth: 0,
       currentElementNode: null,
     }
@@ -45,7 +45,7 @@ describe('hTML walking', () => {
     const depthLog: { tagName: string, depth: number, event: string }[] = []
 
     const state: Partial<MdreamProcessingState> = {
-      depthMap: {},
+      depthMap: new Uint8Array(MAX_TAG_ID),
       depth: 0,
       currentElementNode: null,
     }
@@ -79,10 +79,10 @@ describe('hTML walking', () => {
 
   it('tracks depthMap correctly for multiple levels of nested elements', () => {
     const html = '<div><ul><li><a href="#">Link <strong>with bold</strong> text</a></li></ul></div>'
-    const depthMapLog: { tagName: string, depthMap: Record<number, number> }[] = []
+    const depthMapLog: { tagName: string, depthMap: Uint8Array }[] = []
 
     const state: Partial<MdreamProcessingState> = {
-      depthMap: {},
+      depthMap: new Uint8Array(MAX_TAG_ID),
       depth: 0,
       currentElementNode: null,
     }
@@ -93,7 +93,7 @@ describe('hTML walking', () => {
       if (event.type === NodeEventEnter && node.type === 1) { // ELEMENT_NODE enter
         depthMapLog.push({
           tagName: node.name || '',
-          depthMap: { ...node.depthMap }, // Copy to avoid reference issues in test
+          depthMap: new Uint8Array(node.depthMap), // Copy to avoid reference issues in test
         })
       }
     }
@@ -109,11 +109,21 @@ describe('hTML walking', () => {
     expect(depthMapLog[4].tagName).toBe('strong')
 
     // Each node should have a depthMap that includes itself and its ancestors
-    expect(depthMapLog[4].depthMap).toMatchObject({
-      // The exact tag IDs will depend on the TAG_MAP constants
-      // but the strong element should have entries for div, ul, li, a, and strong
-      // with counts >= 1
-    })
+    // Check that the values in the Uint8Array for the corresponding tag IDs
+    // are all greater than 0 for the expected elements
+    const depthMap = depthMapLog[4].depthMap
+    // Import these constants in a real implementation
+    const divId = 36 // TAG_DIV
+    const ulId = 24 // TAG_UL
+    const liId = 25 // TAG_LI
+    const aId = 26 // TAG_A
+    const strongId = 14 // TAG_STRONG
+
+    expect(depthMap[divId]).toBeGreaterThan(0)
+    expect(depthMap[ulId]).toBeGreaterThan(0)
+    expect(depthMap[liId]).toBeGreaterThan(0)
+    expect(depthMap[aId]).toBeGreaterThan(0)
+    expect(depthMap[strongId]).toBeGreaterThan(0)
   })
 
   it('handles complex nested elements with text nodes', () => {