feat: add warnOnSyncRender option

Author: antfu

README.md

@@ -26,6 +26,18 @@ const md = MarkdownItAsync({
 const html = await md.renderAsync(markdown)
 ```
 
+## Opt-in Warning
+
+If you integrate this package into your project, and want to make sure you have every usage of `md.render` migrated to `md.renderAsync`, you can enable the `warnOnSyncRender` option.
+
+```ts
+const md = MarkdownItAsync({
+  warnOnSyncRender: true
+})
+
+md.render('Hello') // This will throw a conole warning
+```
+
 ## How it works?
 
 This package is a thin wrapper around `markdown-it` to support async highlight function. It uses [the approach suggested in `markdown-it`'s docs](https://github.com/markdown-it/markdown-it/blob/master/docs/development.md#i-need-async-rule-how-to-do-it), by putting placeholders in sync mode and then replace them with async results.

src/index.ts

@@ -20,6 +20,13 @@ export interface MarkdownItAsyncOptions extends Omit<Options, 'highlight'> {
    * @default null
    */
   highlight?: ((str: string, lang: string, attrs: string) => string | Promise<string>) | null | undefined
+
+  /**
+   * Emit warning when calling `md.render` instead of `md.renderAsync`.
+   *
+   * @default false
+   */
+  warnOnSyncRender?: boolean
 }
 
 export type { MarkdownItAsyncOptions as Options }
@@ -58,9 +65,16 @@ export class MarkdownItAsync extends MarkdownIt {
     return super.use(plugin, ...params)
   }
 
+  render(src: string, env?: any): string {
+    if ((this.options as MarkdownItAsyncOptions).warnOnSyncRender) {
+      console.warn('[markdown-it-async] Please use `md.renderAsync` instead of `md.render`')
+    }
+    return super.render(src, env)
+  }
+
   async renderAsync(src: string, env?: any): Promise<string> {
     this.options.highlight = wrapHightlight(this.options.highlight, this.placeholderMap)
-    const result = this.render(src, env)
+    const result = super.render(src, env)
     return replaceAsync(result, placeholderRe, async (match, id) => {
       if (!this.placeholderMap.has(id))
         throw new Error(`Unknown highlight placeholder id: ${id}`)

test/index.test.ts

@@ -1,6 +1,6 @@
 import createMarkdownIt from 'markdown-it'
 import { codeToHtml, createHighlighter } from 'shiki'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import createMarkdownItAsync from '../src/'
 
 const fixture = `
@@ -55,4 +55,21 @@ describe('markdown-it-async', async () => {
 
     expect(expectedResult).toEqual(await mda.renderAsync(fixture))
   })
+
+  it('warn', () => {
+    const mda = createMarkdownItAsync({
+      warnOnSyncRender: true,
+    })
+
+    const spy = vi
+      .spyOn(console, 'warn')
+      .mockImplementation(() => {})
+
+    mda.render(fixture)
+
+    expect.soft(spy)
+      .toHaveBeenCalledWith('[markdown-it-async] Please use `md.renderAsync` instead of `md.render`')
+
+    spy.mockRestore()
+  })
 })