From 3ab57847037e3c88e948f59bd2cb2b5566dfade5 Mon Sep 17 00:00:00 2001 From: Robin Date: Mon, 19 Oct 2026 19:20:10 +0000 Subject: [PATCH 1/2] perf(parser): lazy import default plugins --- packages/comark/src/parse.ts | 127 ++++++++++++-------- packages/comark/test/parser-sharing.test.ts | 27 +++-- 2 files changed, 90 insertions(+), 64 deletions(-) diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index 142f9ee1d..88c563359 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -12,15 +12,8 @@ import type { Node, } from './types.ts' import MarkdownExit, { type Token } from 'markdown-exit' -import components from './plugins/components.ts' -import attributes from './plugins/attributes.ts' -import taskList from './plugins/task-list.ts' -import alert from './plugins/alert.ts' -import html from './plugins/html.ts' -import frontmatterPlugin from './plugins/frontmatter.ts' import { applyAutoUnwrap, extractReusableNodes } from './internal/parse/utils.ts' import { applyUnwrap, resolveUnwrapTags } from './internal/parse/unwrap.ts' -import { autoCloseMarkdown } from './internal/parse/auto-close/index.ts' import { createSerializedTask, dedupePlugins } from './utils/helpers.ts' import { noopTracer, withSpan } from './utils/trace.ts' import { tokenListToTree } from './internal/parse/tree.ts' @@ -41,6 +34,57 @@ let nextPluginId = 0 const pluginIds = new WeakMap() const sharedParsers = new Map() +/** + * The built-in plugins, imported on first use so bundles that pass + * `registerDefaultPlugins: false` do not ship them (or js-yaml with them). + */ +async function loadDefaultPlugins(options: ParserOptions): Promise[]> { + const [frontmatterPlugin, html, alert, taskList, components, attributes] = await Promise.all([ + import('./plugins/frontmatter.ts'), + // Honor deprecated `html: false` so callers can keep disabling HTML for now. + options.html !== false ? import('./plugins/html.ts') : null, + import('./plugins/alert.ts'), + import('./plugins/task-list.ts'), + import('./plugins/components.ts'), + import('./plugins/attributes.ts'), + ]) + return [ + frontmatterPlugin.default(), + ...(html ? [html.default()] : []), + alert.default(), + taskList.default(), + components.default(), + attributes.default(), + ] +} + +// Imported on the first parse that needs it; afterwards used without awaiting, +// so later parses take no extra async steps. +let autoCloseMarkdown: typeof import('./internal/parse/auto-close/index.ts').autoCloseMarkdown | undefined + +function getSharedParser(mdPlugins: MarkdownExitPlugin[], linkify: boolean): MarkdownExit { + const key = [ + linkify, + ...mdPlugins.map((fn) => pluginIds.get(fn) ?? (pluginIds.set(fn, nextPluginId), nextPluginId++)), + ].join(',') + + let parser = sharedParsers.get(key) + if (parser) { + // Touch for LRU: Map iteration order is insertion order. + sharedParsers.delete(key) + sharedParsers.set(key, parser) + } else { + parser = new MarkdownExit({ linkify }).enable(['table', 'strikethrough']) + for (const fn of mdPlugins) parser.use(fn) + if (sharedParsers.size >= MAX_SHARED_PARSERS) { + const oldestKey = sharedParsers.keys().next().value + if (oldestKey !== undefined) sharedParsers.delete(oldestKey) + } + sharedParsers.set(key, parser) + } + return parser +} + /** * Creates a parser function for Comark content. * @@ -87,54 +131,33 @@ export function createMarkdownParser plugins.some((plugin) => plugin.name === name) - - const mdPlugins: MarkdownExitPlugin[] = [] - for (const plugin of plugins) { - for (const markdownItPlugin of plugin.markdownItPlugins || []) { - mdPlugins.push(markdownItPlugin as unknown as MarkdownExitPlugin) - } - } - - const linkify = options.linkify ?? true - const key = [ - linkify, - ...mdPlugins.map((fn) => pluginIds.get(fn) ?? (pluginIds.set(fn, nextPluginId), nextPluginId++)), - ].join(',') + // Default plugins are imported on the first parse, so plugin setup and the + // parser lookup happen then too, once per parser function. + let plugins: ComarkPlugin[] = [] + let parser: MarkdownExit | undefined + let setup: Promise | null = null + const ensureSetup = () => + (setup ??= (async () => { + const defaultPlugins = options.registerDefaultPlugins !== false ? await loadDefaultPlugins(options) : [] + plugins = dedupePlugins(defaultPlugins, userPlugins) - let parser = sharedParsers.get(key) - if (parser) { - // Touch for LRU: Map iteration order is insertion order. - sharedParsers.delete(key) - sharedParsers.set(key, parser) - } else { - parser = new MarkdownExit({ linkify }).enable(['table', 'strikethrough']) - for (const fn of mdPlugins) parser.use(fn) - if (sharedParsers.size >= MAX_SHARED_PARSERS) { - const oldestKey = sharedParsers.keys().next().value - if (oldestKey !== undefined) sharedParsers.delete(oldestKey) - } - sharedParsers.set(key, parser) - } + const mdPlugins: MarkdownExitPlugin[] = [] + for (const plugin of plugins) { + for (const markdownItPlugin of plugin.markdownItPlugins || []) { + mdPlugins.push(markdownItPlugin as unknown as MarkdownExitPlugin) + } + } + parser = getSharedParser(mdPlugins, options.linkify ?? true) + })()) + const hasPlugin = (name: string) => plugins.some((plugin) => plugin.name === name) let lastOutput: MarkdownDocument | null = null let lastInput: string | null = null const parseFn: ComarkParseFn = async (markdown, opts = {}) => { + // Only the first parse waits; later ones keep the same async steps as before. + if (!parser) await ensureSetup() + // Root active span for the full parse pipeline. Nested startActiveSpan / // startSpan calls become children (OTel active context, or a stack in a // simple recorder) → hierarchical trace: @@ -177,8 +200,10 @@ export function createMarkdownParser autoClose(state.markdown)) } else if (autoClose) { + autoCloseMarkdown ??= (await import('./internal/parse/auto-close/index.ts')).autoCloseMarkdown + const closeMarkdown = autoCloseMarkdown state.markdown = withSpan(tracer, 'comark:autoclose', () => - autoCloseMarkdown(state.markdown, { + closeMarkdown(state.markdown, { frontmatter: hasPlugin('frontmatter') && opts.streaming, syntax: hasPlugin('components'), attributes: hasPlugin('components') || hasPlugin('attributes'), @@ -194,7 +219,7 @@ export function createMarkdownParser parser.parse(state.markdown, {})) + state.tokens = withSpan(tracer, 'comark:tokenize', () => parser!.parse(state.markdown, {})) } catch (e) { // in case of streaming, return the previous output if parsing fails // This is to avoid resetting the tree to an empty state on failure diff --git a/packages/comark/test/parser-sharing.test.ts b/packages/comark/test/parser-sharing.test.ts index fe38a3048..d8ea40138 100644 --- a/packages/comark/test/parser-sharing.test.ts +++ b/packages/comark/test/parser-sharing.test.ts @@ -5,7 +5,8 @@ import binding from '../src/plugins/binding' // The shared instance is internal, so it is observed through the public API: a // markdown-it plugin function runs once per instance, so counting how often it -// is registered counts the instances that were built. +// is registered counts the instances that were built. Instances are built on a +// parser's first parse, once the default plugins have been imported. let stableUses = 0 const stableMdPlugin = (() => { stableUses++ @@ -27,28 +28,28 @@ const closurePlugin = defineComarkPlugin(() => ({ })) describe('parser sharing', () => { - it('builds one instance for parsers with the same plugin functions', () => { + it('builds one instance for parsers with the same plugin functions', async () => { const plugin = stablePlugin() const before = stableUses for (let i = 0; i < 20; i++) { - createMarkdownParser({ plugins: [plugin] }) + await createMarkdownParser({ plugins: [plugin] })('') } expect(stableUses - before).toBe(1) }) - it('builds one instance per closure when a factory returns a fresh function', () => { + it('builds one instance per closure when a factory returns a fresh function', async () => { const before = closureUses for (let i = 0; i < 5; i++) { - createMarkdownParser({ plugins: [closurePlugin()] }) + await createMarkdownParser({ plugins: [closurePlugin()] })('') } expect(closureUses - before).toBe(5) }) - it('refreshes cache hits and evicts the least-recently-used shared instance once the cache is full', () => { + it('refreshes cache hits and evicts the least-recently-used shared instance once the cache is full', async () => { // Dedicated plugins so prior tests in this file cannot keep these keys warm. let markedUses = 0 const markedMdPlugin = (() => { @@ -68,24 +69,24 @@ describe('parser sharing', () => { markdownItPlugins: [oldestMdPlugin], }))() - createMarkdownParser({ plugins: [markedPlugin] }) - createMarkdownParser({ plugins: [oldestPlugin] }) + await createMarkdownParser({ plugins: [markedPlugin] })('') + await createMarkdownParser({ plugins: [oldestPlugin] })('') // Capacity is 32. Keep both named entries in the cache, then refresh // markedPlugin before inserting one more key so only oldestPlugin ages out. for (let i = 0; i < 30; i++) { - createMarkdownParser({ plugins: [closurePlugin()] }) + await createMarkdownParser({ plugins: [closurePlugin()] })('') } expect(markedUses).toBe(1) expect(oldestUses).toBe(1) - createMarkdownParser({ plugins: [markedPlugin] }) - createMarkdownParser({ plugins: [closurePlugin()] }) + await createMarkdownParser({ plugins: [markedPlugin] })('') + await createMarkdownParser({ plugins: [closurePlugin()] })('') - createMarkdownParser({ plugins: [oldestPlugin] }) + await createMarkdownParser({ plugins: [oldestPlugin] })('') expect(oldestUses).toBe(2) - createMarkdownParser({ plugins: [markedPlugin] }) + await createMarkdownParser({ plugins: [markedPlugin] })('') expect(markedUses).toBe(1) }) From f780570ba2fb5eefcaf1f139ca5ec1ab01df3791 Mon Sep 17 00:00:00 2001 From: Robin Date: Mon, 19 Oct 2026 19:56:49 +0000 Subject: [PATCH 2/2] chore: setup on factory call, not first use --- packages/comark/src/parse.ts | 85 +++++++++++++-------- packages/comark/test/parser-sharing.test.ts | 35 +++++---- 2 files changed, 74 insertions(+), 46 deletions(-) diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index 88c563359..c06ed4aa6 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -34,23 +34,40 @@ let nextPluginId = 0 const pluginIds = new WeakMap() const sharedParsers = new Map() -/** - * The built-in plugins, imported on first use so bundles that pass - * `registerDefaultPlugins: false` do not ship them (or js-yaml with them). - */ -async function loadDefaultPlugins(options: ParserOptions): Promise[]> { - const [frontmatterPlugin, html, alert, taskList, components, attributes] = await Promise.all([ +function importDefaultPlugins() { + return Promise.all([ import('./plugins/frontmatter.ts'), - // Honor deprecated `html: false` so callers can keep disabling HTML for now. - options.html !== false ? import('./plugins/html.ts') : null, + import('./plugins/html.ts'), import('./plugins/alert.ts'), import('./plugins/task-list.ts'), import('./plugins/components.ts'), import('./plugins/attributes.ts'), ]) +} +type DefaultPluginModules = Awaited> +type AutoCloseMarkdown = typeof import('./internal/parse/auto-close/index.ts').autoCloseMarkdown + +let defaultPluginModules: DefaultPluginModules | undefined +let defaultPluginModulesLoading: Promise | undefined +let autoCloseMarkdown: AutoCloseMarkdown | undefined +let autoCloseLoading: Promise | undefined + +function loadDefaultPlugins(): Promise { + return (defaultPluginModulesLoading ??= importDefaultPlugins().then((modules) => (defaultPluginModules = modules))) +} + +function loadAutoClose(): Promise { + return (autoCloseLoading ??= import('./internal/parse/auto-close/index.ts').then( + (module) => (autoCloseMarkdown = module.autoCloseMarkdown) + )) +} + +function createDefaultPlugins(modules: DefaultPluginModules, options: ParserOptions): ComarkPlugin[] { + const [frontmatterPlugin, html, alert, taskList, components, attributes] = modules return [ frontmatterPlugin.default(), - ...(html ? [html.default()] : []), + // Honor deprecated `html: false` so callers can keep disabling HTML for now. + ...(options.html !== false ? [html.default()] : []), alert.default(), taskList.default(), components.default(), @@ -58,10 +75,6 @@ async function loadDefaultPlugins(options: ParserOptions): Promise[] = [] let parser: MarkdownExit | undefined - let setup: Promise | null = null - const ensureSetup = () => - (setup ??= (async () => { - const defaultPlugins = options.registerDefaultPlugins !== false ? await loadDefaultPlugins(options) : [] - plugins = dedupePlugins(defaultPlugins, userPlugins) + const setup = (defaultPlugins: ComarkPlugin[]) => { + plugins = dedupePlugins(defaultPlugins, userPlugins) - const mdPlugins: MarkdownExitPlugin[] = [] - for (const plugin of plugins) { - for (const markdownItPlugin of plugin.markdownItPlugins || []) { - mdPlugins.push(markdownItPlugin as unknown as MarkdownExitPlugin) - } + const mdPlugins: MarkdownExitPlugin[] = [] + for (const plugin of plugins) { + for (const markdownItPlugin of plugin.markdownItPlugins || []) { + mdPlugins.push(markdownItPlugin as unknown as MarkdownExitPlugin) } - parser = getSharedParser(mdPlugins, options.linkify ?? true) - })()) + } + parser = getSharedParser(mdPlugins, options.linkify ?? true) + } const hasPlugin = (name: string) => plugins.some((plugin) => plugin.name === name) + // Set up right away when nothing has to be imported. Otherwise start the + // imports now and let the first parse wait for them if they are not done. + let pendingSetup: Promise | undefined + if (options.registerDefaultPlugins === false) { + setup([]) + } else if (defaultPluginModules) { + setup(createDefaultPlugins(defaultPluginModules, options)) + } else { + pendingSetup = loadDefaultPlugins().then((modules) => setup(createDefaultPlugins(modules, options))) + // A failed import is reported by the parse that waits for it. + pendingSetup.catch(() => {}) + } + if (autoClose === true && !autoCloseMarkdown) { + loadAutoClose().catch(() => {}) + } + let lastOutput: MarkdownDocument | null = null let lastInput: string | null = null const parseFn: ComarkParseFn = async (markdown, opts = {}) => { - // Only the first parse waits; later ones keep the same async steps as before. - if (!parser) await ensureSetup() + // Only waits while the default plugins are still being imported. + if (!parser) await pendingSetup // Root active span for the full parse pipeline. Nested startActiveSpan / // startSpan calls become children (OTel active context, or a stack in a @@ -200,8 +224,7 @@ export function createMarkdownParser autoClose(state.markdown)) } else if (autoClose) { - autoCloseMarkdown ??= (await import('./internal/parse/auto-close/index.ts')).autoCloseMarkdown - const closeMarkdown = autoCloseMarkdown + const closeMarkdown = autoCloseMarkdown ?? (await loadAutoClose()) state.markdown = withSpan(tracer, 'comark:autoclose', () => closeMarkdown(state.markdown, { frontmatter: hasPlugin('frontmatter') && opts.streaming, diff --git a/packages/comark/test/parser-sharing.test.ts b/packages/comark/test/parser-sharing.test.ts index d8ea40138..d12cf1c40 100644 --- a/packages/comark/test/parser-sharing.test.ts +++ b/packages/comark/test/parser-sharing.test.ts @@ -1,12 +1,11 @@ -import { describe, expect, it } from 'vitest' +import { beforeAll, describe, expect, it } from 'vitest' import { createMarkdownParser, defineComarkPlugin } from 'comark' import type { MarkdownItPlugin } from 'comark' import binding from '../src/plugins/binding' // The shared instance is internal, so it is observed through the public API: a // markdown-it plugin function runs once per instance, so counting how often it -// is registered counts the instances that were built. Instances are built on a -// parser's first parse, once the default plugins have been imported. +// is registered counts the instances that were built. let stableUses = 0 const stableMdPlugin = (() => { stableUses++ @@ -28,28 +27,34 @@ const closurePlugin = defineComarkPlugin(() => ({ })) describe('parser sharing', () => { - it('builds one instance for parsers with the same plugin functions', async () => { + // The default plugins are imported once per module; after that, parsers set + // up synchronously, which is what the instance counts below rely on. + beforeAll(async () => { + await createMarkdownParser()('') + }) + + it('builds one instance for parsers with the same plugin functions', () => { const plugin = stablePlugin() const before = stableUses for (let i = 0; i < 20; i++) { - await createMarkdownParser({ plugins: [plugin] })('') + createMarkdownParser({ plugins: [plugin] }) } expect(stableUses - before).toBe(1) }) - it('builds one instance per closure when a factory returns a fresh function', async () => { + it('builds one instance per closure when a factory returns a fresh function', () => { const before = closureUses for (let i = 0; i < 5; i++) { - await createMarkdownParser({ plugins: [closurePlugin()] })('') + createMarkdownParser({ plugins: [closurePlugin()] }) } expect(closureUses - before).toBe(5) }) - it('refreshes cache hits and evicts the least-recently-used shared instance once the cache is full', async () => { + it('refreshes cache hits and evicts the least-recently-used shared instance once the cache is full', () => { // Dedicated plugins so prior tests in this file cannot keep these keys warm. let markedUses = 0 const markedMdPlugin = (() => { @@ -69,24 +74,24 @@ describe('parser sharing', () => { markdownItPlugins: [oldestMdPlugin], }))() - await createMarkdownParser({ plugins: [markedPlugin] })('') - await createMarkdownParser({ plugins: [oldestPlugin] })('') + createMarkdownParser({ plugins: [markedPlugin] }) + createMarkdownParser({ plugins: [oldestPlugin] }) // Capacity is 32. Keep both named entries in the cache, then refresh // markedPlugin before inserting one more key so only oldestPlugin ages out. for (let i = 0; i < 30; i++) { - await createMarkdownParser({ plugins: [closurePlugin()] })('') + createMarkdownParser({ plugins: [closurePlugin()] }) } expect(markedUses).toBe(1) expect(oldestUses).toBe(1) - await createMarkdownParser({ plugins: [markedPlugin] })('') - await createMarkdownParser({ plugins: [closurePlugin()] })('') + createMarkdownParser({ plugins: [markedPlugin] }) + createMarkdownParser({ plugins: [closurePlugin()] }) - await createMarkdownParser({ plugins: [oldestPlugin] })('') + createMarkdownParser({ plugins: [oldestPlugin] }) expect(oldestUses).toBe(2) - await createMarkdownParser({ plugins: [markedPlugin] })('') + createMarkdownParser({ plugins: [markedPlugin] }) expect(markedUses).toBe(1) })