Skip to content

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.md
new file mode 100644
index 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.
+
+@jiunshinn
diff --git a/packages/core/src/Markdown/incremental.test.ts b/packages/core/src/Markdown/incremental.test.ts
index 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.ts
index 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.ts
index 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);
}
// ---------------------------------------------------------------------------