An open source design system that's fully customizable and agent ready
TypeScript
perf(markdown): bound incremental parsing to stream tail (#5515)
Jiun Shinfe342107ad5f
diff --git a/.changeset/markdown-stream-tail-cache.md b/.changeset/markdown-stream-tail-cache.mdnew file mode 100644index 0000000000..25fc9c2be4--- /dev/null+++ b/.changeset/markdown-stream-tail-cache.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[perf] Markdown streaming bounds four incremental-parse operations by the mutable tail: splitting, fence/boundary detection, link-definition collection, and block re-parsing no longer grow with the already-settled document. The parser contract is unchanged: each call returns a fresh, never-mutated snapshot, and replacing already-settled text still re-parses the document. Two costs intentionally remain proportional to the whole input on each call because that contract requires them — the settled-prefix comparison that detects a replaced document, and the pointer-per-block copy behind each returned snapshot.++@jiunshinndiff --git a/packages/core/src/Markdown/incremental.test.ts b/packages/core/src/Markdown/incremental.test.tsindex 9ba7b58bda..0561f43d2d 100644--- a/packages/core/src/Markdown/incremental.test.ts+++ b/packages/core/src/Markdown/incremental.test.ts@@ -209,6 +209,76 @@ describe('parseMarkdownIncremental', () => {expect(state.settledBlocks).toBe(cachedBlocks);});+ it('returns a fresh array and leaves earlier snapshots untouched', () => {+ const state = createIncrementalState();+ const first = parseMarkdownIncremental(+ '# Stable\n\nFirst paragraph\n\nTail',+ state,+ );+ const stableHeading = first[0];+ const snapshot = structuredClone(first);++ const second = parseMarkdownIncremental(+ '# Stable\n\nFirst paragraph\n\nTail grows',+ state,+ );++ // Call 1's return is a stable snapshot: a later call neither replaces it+ // in place nor edits the block nodes it holds.+ expect(second).not.toBe(first);+ expect(first).toEqual(snapshot);+ // Settled block objects are reused across calls by reference.+ expect(second[0]).toBe(stableHeading);+ expect(second).toEqual(+ parseMarkdown('# Stable\n\nFirst paragraph\n\nTail grows'),+ );+ });++ it('re-parses when settled text is replaced at the same length', () => {+ const state = createIncrementalState();+ const before = '# Alpha\n\nOld body copy';+ const after = '# Bravo\n\nNew body copy';+ expect(after).toHaveLength(before.length);++ parseMarkdownIncremental(before, state);+ const blocks = parseMarkdownIncremental(after, state);++ expect(blocks).toEqual(parseMarkdown(after));+ });++ it('re-parses when settled text is replaced by longer content', () => {+ const state = createIncrementalState();+ parseMarkdownIncremental('# Alpha\n\nOld body copy', state);++ const after =+ '# Bravo heading\n\nNew body copy, longer than before\n\nTail';+ const blocks = parseMarkdownIncremental(after, state);++ expect(blocks).toEqual(parseMarkdown(after));+ });++ it('keeps the prefix settled while a long fence streams and closes', () => {+ const state = createIncrementalState();+ const prefix = '# Stable\n\n';+ const fence = '```ts\nconst a = 1;\n\nconst b = 2;';+ let stableHeading: BlockNode | undefined;++ for (let end = 1; end <= fence.length; end++) {+ const blocks = parseMarkdownIncremental(+ prefix + fence.slice(0, end),+ state,+ );+ stableHeading ??= blocks[0];+ expect(blocks[0]).toBe(stableHeading);+ expect(state.settledText).toBe('# Stable');+ }++ const complete = `${prefix}${fence}\n\`\`\`\n\nAfter`;+ const blocks = parseMarkdownIncremental(complete, state);+ expect(blocks[0]).toBe(stableHeading);+ expect(blocks).toEqual(parseMarkdown(complete));+ });+it('tracks settledText correctly', () => {const state = createIncrementalState();parseMarkdownIncremental('# Hello\n\nWorld', state);@@ -699,4 +769,17 @@ describe('parseMarkdownIncremental link reference definitions', () => {);expect(firstLinkHref(after)).toBe('/docs');});++ it('keeps first-definition-wins when definitions move into the settled prefix', () => {+ const state = createIncrementalState();+ const first = 'See [d].\n\n[d]: /first\n\nMiddle paragraph\n\n[d]: /second';+ expect(firstLinkHref(parseMarkdownIncremental(first, state))).toBe(+ '/first',+ );++ const complete = `${first}\n\nAfter`;+ const blocks = parseMarkdownIncremental(complete, state);+ expect(blocks).toEqual(parseMarkdown(complete));+ expect(firstLinkHref(blocks)).toBe('/first');+ });});diff --git a/packages/core/src/Markdown/parser.perf.test.ts b/packages/core/src/Markdown/parser.perf.test.tsindex 302cdae905..e0acf324aa 100644--- a/packages/core/src/Markdown/parser.perf.test.ts+++ b/packages/core/src/Markdown/parser.perf.test.ts@@ -5,6 +5,7 @@ import {parseMarkdown,parseMarkdownIncremental,createIncrementalState,+ getIncrementalParseWork,} from './parser';import type {BlockNode, ParseOptions} from './parser';@@ -247,6 +248,98 @@ describe('parseMarkdown performance', () => {// integers that come out the same on a loaded CI box as on an idle laptop,// unlike the wall-clock budgets above.describe('parseMarkdownIncremental cache', () => {+ it('bounds the four measured parser operations by the unsettled tail', () => {+ const section =+ 'Fixed-length paragraph with enough text to cross a stream boundary.\n\n';+ const worstWork = (sections: number) => {+ const state = createIncrementalState();+ const worst = {+ splitCharacters: 0,+ boundaryLines: 0,+ definitionCharacters: 0,+ renderedBlocks: 0,+ };+ let input = '';+ for (let i = 0; i < sections; i++) {+ input += section;+ parseMarkdownIncremental(input, state);+ const work = getIncrementalParseWork(state);+ worst.splitCharacters = Math.max(+ worst.splitCharacters,+ work.splitCharacters,+ );+ worst.boundaryLines = Math.max(worst.boundaryLines, work.boundaryLines);+ worst.definitionCharacters = Math.max(+ worst.definitionCharacters,+ work.definitionCharacters,+ );+ worst.renderedBlocks = Math.max(+ worst.renderedBlocks,+ work.renderedBlocks,+ );+ }+ return worst;+ };++ const short = worstWork(20);+ const long = worstWork(200);+ console.log(+ ` worst tail work (20/200 sections): ${JSON.stringify(short)} / ${JSON.stringify(long)}`,+ );+ // Ten times the document length does not change the four operations this+ // cache bounds: splitting (splitCharacters), boundary/fence scanning+ // (boundaryLines), definition collection (definitionCharacters), and+ // per-chunk block construction (renderedBlocks). This is deliberately NOT+ // a claim about every whole-input operation. Two costs stay linear in the+ // whole input on every call, by design, and are outside these counters:+ // the settled-prefix `startsWith` comparison that detects a replaced+ // document (replacement correctness cannot be decided without reading the+ // prefix), and the one-pointer-per-block copy that assembles each+ // returned array (snapshot semantics require a fresh array per call).+ // Both are tracked — not bounded — by the next test.+ expect(long).toEqual(short);+ });++ it('tracks the two whole-prefix costs kept linear by the public contract', () => {+ // Tracked, not bounded. These two operations intentionally remain+ // proportional to the settled prefix on each call and are OUT of the+ // scope of the tail-bounding above (see #5406 for the broader issue):+ //+ // 1. `prefixCharacters` — the memcmp-speed `startsWith` scan over the+ // settled prefix that detects a replaced document. When the check+ // passes it inspects exactly the settled prefix, so sampling+ // `state.settledText.length` before each call counts it.+ // 2. `copiedEntries` — one pointer per returned block, copied so every+ // call hands back a fresh array that later calls never mutate. The+ // returned array's length counts it.+ //+ // The totals below grow quadratically across a stream because each call+ // pays a cost linear in the document parsed so far. They are asserted+ // exactly so that any change to either cost — bounding it, or accidentally+ // making it heavier — shows up here and updates this record.+ const section =+ 'Fixed-length paragraph with enough text to cross a stream boundary.\n\n';+ const trackedWork = (sections: number) => {+ const state = createIncrementalState();+ const tracked = {prefixCharacters: 0, copiedEntries: 0};+ let input = '';+ for (let i = 0; i < sections; i++) {+ input += section;+ tracked.prefixCharacters += state.settledText.length;+ tracked.copiedEntries += parseMarkdownIncremental(input, state).length;+ }+ return tracked;+ };++ const short = trackedWork(20);+ const long = trackedWork(200);+ console.log(+ ` tracked whole-prefix work (20/200 sections): ${JSON.stringify(short)} / ${JSON.stringify(long)}`,+ );+ expect(short).toEqual({prefixCharacters: 13072, copiedEntries: 210});+ expect(long).toEqual({prefixCharacters: 1372702, copiedEntries: 20100});+ });+it('builds a bounded number of blocks per chunk however long the document is', () => {const chunkSize = 50;const medians = [50, 200, 500].map(paragraphs =>diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.tsindex a92ca9f82c..ab06560edb 100644--- a/packages/core/src/Markdown/parser.ts+++ b/packages/core/src/Markdown/parser.ts@@ -1586,8 +1586,77 @@ export interface IncrementalState {linkDefsKey?: string;}+type IncrementalWork = {+ /** Characters copied into the tail line array. */+ readonly splitCharacters: number;+ /** Tail lines visited by fence and blank-boundary detection. */+ readonly boundaryLines: number;+ /** Characters visited while collecting document-global definitions. */+ readonly definitionCharacters: number;+ /** Block nodes parsed anew this call (settled delta + unsettled tail). */+ readonly renderedBlocks: number;+};++type IncrementalCache = {+ /** Character offset immediately after the immutable settled prefix. */+ settledEnd: number;+ /** Definitions whose complete block is in the settled prefix. */+ settledLinkDefs: Map<string, string>;+ /** Definitions still in the mutable tail on the preceding call. */+ tailLinkDefs: ReadonlyMap<string, string>;+ /** The effective document-global definitions used by slice parses. */+ linkDefs: ReadonlyMap<string, string>;+ linkDefsKey: string;+ work: IncrementalWork;+};++const incrementalCaches = new WeakMap<IncrementalState, IncrementalCache>();++function makeIncrementalCache(state: IncrementalState): IncrementalCache {+ const {defs} = extractLinkDefinitions(state.settledText);+ const cache: IncrementalCache = {+ settledEnd: state.settledText.length,+ settledLinkDefs: new Map(defs),+ tailLinkDefs: new Map(),+ linkDefs: defs,+ linkDefsKey: linkDefsSignature(defs),+ work: {+ splitCharacters: 0,+ boundaryLines: 0,+ definitionCharacters: 0,+ renderedBlocks: 0,+ },+ };+ incrementalCaches.set(state, cache);+ return cache;+}+export function createIncrementalState(): IncrementalState {- return {prevInput: '', settledText: '', settledBlocks: [], settledUpTo: 0};+ const state: IncrementalState = {+ prevInput: '',+ settledText: '',+ settledBlocks: [],+ settledUpTo: 0,+ };+ makeIncrementalCache(state);+ return state;+}++/**+ * Deterministic work counters for the most recent incremental parse.+ * @internal Exported from this module for performance regression tests only.+ */+export function getIncrementalParseWork(+ state: IncrementalState,+): IncrementalWork {+ return (+ incrementalCaches.get(state)?.work ?? {+ splitCharacters: 0,+ boundaryLines: 0,+ definitionCharacters: 0,+ renderedBlocks: 0,+ }+ );}/**@@ -1918,6 +1987,91 @@ function mergeSettledBlocks(return [...prev, ...delta];}+/** Append a newly-settled slice without copying the already-settled prefix. */+function appendSettledBlocks(prev: BlockNode[], delta: BlockNode[]): void {+ if (delta.length === 0) {+ return;+ }+ if (prev.length === 0) {+ prev.push(...delta);+ return;+ }+ const prevLast = prev[prev.length - 1];+ const deltaFirst = delta[0];+ if (+ prevLast.type === 'list' &&+ deltaFirst.type === 'list' &&+ prevLast.ordered === deltaFirst.ordered &&+ prevLast.delimiter === deltaFirst.delimiter+ ) {+ prev[prev.length - 1] = {+ type: 'list',+ ordered: prevLast.ordered,+ start: prevLast.start,+ delimiter: prevLast.delimiter,+ loose: true,+ items: [...prevLast.items, ...deltaFirst.items],+ ...(prevLast.range != null && deltaFirst.range != null+ ? {range: {start: prevLast.range.start, end: deltaFirst.range.end}}+ : null),+ };+ prev.push(...delta.slice(1));+ return;+ }+ prev.push(...delta);+}++function sameUnsettledDefinitions(+ previous: ReadonlyMap<string, string>,+ next: ReadonlyMap<string, string>,+ settled: ReadonlyMap<string, string>,+): boolean {+ for (const [label, destination] of previous) {+ if (!settled.has(label) && next.get(label) !== destination) {+ return false;+ }+ }+ for (const [label, destination] of next) {+ if (!settled.has(label) && previous.get(label) !== destination) {+ return false;+ }+ }+ return true;+}++function resetIncrementalCache(+ state: IncrementalState,+ cache: IncrementalCache,+): void {+ state.prevInput = '';+ state.settledText = '';+ state.settledBlocks = [];+ state.settledUpTo = 0;+ state.linkDefsKey = undefined;+ cache.settledEnd = 0;+ cache.settledLinkDefs.clear();+ cache.tailLinkDefs = new Map();+ cache.linkDefs = new Map();+ cache.linkDefsKey = '';+ cache.work = {+ splitCharacters: 0,+ boundaryLines: 0,+ definitionCharacters: 0,+ renderedBlocks: 0,+ };+}++/**+ * Parse one cumulative snapshot of a streaming Markdown document.+ *+ * Every call returns a fresh array, and later calls never mutate a+ * previously returned array or the block nodes inside it, so results are+ * stable snapshots. Settled block objects are shared across calls by+ * reference, which is safe because they are replaced — never edited in+ * place — when adjacent content changes them. When the input no longer+ * starts with the settled prefix (a replacement rather than an append),+ * the cache is discarded and the whole document is re-parsed.+ */export function parseMarkdownIncremental(input: string,state: IncrementalState,@@ -1934,6 +2088,9 @@ export function parseMarkdownIncremental(arg?: ReadonlySet<string> | ParseOptions,): BlockNode[] {const opts = resolveOptions(arg);+ const cache = incrementalCaches.get(state) ?? makeIncrementalCache(state);+ let reparseSettled = false;+// Invalidate cache when the autolink or sourceRanges option flips — cached// settled blocks were parsed with the previous setting and would otherwise// be reused unchanged.@@ -1941,50 +2098,92 @@ export function parseMarkdownIncremental(state.autolink !== opts.autolink ||Boolean(state.sourceRanges) !== Boolean(opts.sourceRanges)) {- state.prevInput = '';- state.settledText = '';- state.settledBlocks = [];- state.settledUpTo = 0;+ reparseSettled = true;state.autolink = opts.autolink;state.sourceRanges = opts.sourceRanges;}if (input === '') {- state.prevInput = '';- state.settledText = '';- state.settledBlocks = [];- state.settledUpTo = 0;- state.linkDefsKey = undefined;+ resetIncrementalCache(state, cache);return [];}- // Link reference definitions are document-global and usually stream in- // (as a footer) after the references that use them, so collect them from the- // whole input and pass them into every slice parse. When the set changes,- // invalidate the settled cache so already-settled references re-resolve.- const {defs: linkDefs} = extractLinkDefinitions(input);- const linkDefsKey = linkDefsSignature(linkDefs);- if (state.linkDefsKey !== linkDefsKey) {- state.prevInput = '';- state.settledText = '';- state.settledBlocks = [];- state.settledUpTo = 0;- state.linkDefsKey = linkDefsKey;+ // The settled prefix is only reusable while the input still contains it+ // verbatim. Lengths alone cannot tell: a same-length or longer replacement+ // (new args after reusing a state) disagrees with the prefix without ever+ // being shorter, so compare content. `startsWith` is a memcmp-speed scan+ // with no allocation and is the one whole-prefix operation retained per+ // call — the contract that a replaced document renders the new content+ // cannot be honored without looking at the prefix. A shorter input can+ // never contain the prefix and fails the same check.+ if (+ state.settledText.length !== cache.settledEnd ||+ !input.startsWith(state.settledText)+ ) {+ resetIncrementalCache(state, cache);+ state.autolink = opts.autolink;+ state.sourceRanges = opts.sourceRanges;}- const parseOpts: ResolvedOptions =- linkDefs.size > 0 ? {...opts, linkDefs} : opts;- const lines = input.split('\n');- const {boundary, openFence} = findSettledBoundary(lines);+ // The recurring parse costs are confined to the mutable suffix: splitting,+ // fence/boundary detection, definition collection, and block construction.+ // An open fence simply keeps the suffix growing until its closing marker.+ const oldSettledEnd = cache.settledEnd;+ const tailRaw = input.slice(oldSettledEnd);+ const tailLines = tailRaw.split('\n');+ const {boundary, openFence} = findSettledBoundary(tailLines);+ const settledDelta =+ boundary >= 0 ? tailLines.slice(0, boundary).join('\n') : '';+ const nextSettledEnd = oldSettledEnd + settledDelta.length;+ const unsettledInput = input.slice(nextSettledEnd);++ // Promote definitions only when their entire block becomes immutable.+ // Tail definitions are re-collected because the tail is allowed to change.+ // Changes that affect the effective set intentionally reparse settled+ // blocks: document-global references may precede their footer definition.+ let definitionsChanged = false;+ if (settledDelta !== '') {+ const {defs: deltaDefs} = extractLinkDefinitions(settledDelta);+ for (const [label, destination] of deltaDefs) {+ if (!cache.settledLinkDefs.has(label)) {+ cache.settledLinkDefs.set(label, destination);+ if (cache.linkDefs.get(label) !== destination) {+ definitionsChanged = true;+ }+ }+ }+ }+ const {defs: tailLinkDefs} = extractLinkDefinitions(unsettledInput);+ if (+ !sameUnsettledDefinitions(+ cache.tailLinkDefs,+ tailLinkDefs,+ cache.settledLinkDefs,+ )+ ) {+ definitionsChanged = true;+ }+ cache.tailLinkDefs = tailLinkDefs;- if (boundary < 0) {- // Nothing settled yet — no blank line, or a fence opened before the first- // one — so there is no prefix to keep and the whole input is re-parsed.- state.prevInput = input;- return parseMarkdownImpl(input, parseOpts);+ if (definitionsChanged) {+ // Later entries are overwritten, so settled (earlier) definitions win.+ cache.linkDefs = new Map([...tailLinkDefs, ...cache.settledLinkDefs]);+ cache.linkDefsKey = linkDefsSignature(cache.linkDefs);+ reparseSettled = true;+ }+ state.linkDefsKey = cache.linkDefsKey;+ const parseOpts: ResolvedOptions =+ cache.linkDefs.size > 0 ? {...opts, linkDefs: cache.linkDefs} : opts;++ if (settledDelta !== '') {+ state.settledText += settledDelta;+ state.settledUpTo += settledDelta.split('\n').length - 1;+ if (oldSettledEnd === 0) {+ state.settledUpTo++;+ }+ cache.settledEnd = nextSettledEnd;}- const settledText = lines.slice(0, boundary).join('\n');- const unsettledRaw = lines.slice(boundary).join('\n').trim();+ const unsettledRaw = unsettledInput.trim();// Structural trimming holds back lines that look like an incomplete list or// table, which inside a fence is ordinary code: a TypeScript union or a `- `// would disappear from the code block as it streams.@@ -1992,25 +2191,19 @@ export function parseMarkdownIncremental(? unsettledRaw: trimUnsettledStructural(unsettledRaw);- let settledBlocks: BlockNode[];-- if (settledText === state.settledText) {- // Settled portion unchanged — reuse cached blocks- settledBlocks = state.settledBlocks;- } else if (- state.settledText.length > 0 &&- settledText.startsWith(state.settledText)- ) {- // Settled portion grew — parse only the new delta- const delta = settledText.slice(state.settledText.length);+ let parsedSettledBlocks = 0;+ if (reparseSettled) {+ state.settledBlocks = state.settledText+ ? parseMarkdownImpl(state.settledText, parseOpts)+ : [];+ parsedSettledBlocks = state.settledBlocks.length;+ } else if (settledDelta !== '') {const deltaBlocks = parseMarkdownImpl(- delta,- atOffset(parseOpts, state.settledText.length),+ settledDelta,+ atOffset(parseOpts, oldSettledEnd),);- settledBlocks = mergeSettledBlocks(state.settledBlocks, deltaBlocks);- } else {- // Content before the boundary changed — full re-parse of settled portion- settledBlocks = parseMarkdownImpl(settledText, parseOpts);+ appendSettledBlocks(state.settledBlocks, deltaBlocks);+ parsedSettledBlocks = deltaBlocks.length;}// The unsettled tail is trimmed before parsing, so its offset in the@@ -2020,7 +2213,7 @@ export function parseMarkdownIncremental(// ranges were asked for: this runs on every streamed chunk.const unsettledStart =unsettledText && opts.sourceRanges- ? input.indexOf(unsettledText, settledText.length)+ ? input.indexOf(unsettledText, cache.settledEnd): -1;const unsettledBlocks = unsettledText? parseMarkdownImpl(@@ -2031,12 +2224,20 @@ export function parseMarkdownIncremental(): [];- state.settledText = settledText;- state.settledBlocks = settledBlocks;- state.settledUpTo = boundary;state.prevInput = input;- return mergeSettledBlocks(settledBlocks, unsettledBlocks);+ // Snapshot semantics: hand back a fresh array so later calls never mutate+ // an earlier return. The settled block objects inside it are reused by+ // reference — they are immutable, so sharing them is what keeps this cheap:+ // assembling the result copies one pointer per settled block and never+ // re-visits the settled characters.+ cache.work = {+ splitCharacters: tailRaw.length,+ boundaryLines: tailLines.length,+ definitionCharacters: settledDelta.length + unsettledInput.length,+ renderedBlocks: parsedSettledBlocks + unsettledBlocks.length,+ };+ return mergeSettledBlocks(state.settledBlocks, unsettledBlocks);}// ---------------------------------------------------------------------------