feat(core): new options object signature for createdBundledHighlighter for custom engine bundle, deprecate old signature

Author: antfu

packages/core/src/constructors/bundle-factory.ts

@@ -1,25 +1,72 @@
 import type { Root } from 'hast'
-import type { BundledHighlighterOptions, CodeToHastOptions, CodeToTokensBaseOptions, CodeToTokensOptions, CodeToTokensWithThemesOptions, GrammarState, HighlighterCoreOptions, HighlighterGeneric, LanguageInput, RequireKeys, SpecialLanguage, SpecialTheme, ThemeInput, ThemedToken, ThemedTokenWithVariants, TokensResult } from '../types'
+import type { Awaitable, BundledHighlighterOptions, CodeToHastOptions, CodeToTokensBaseOptions, CodeToTokensOptions, CodeToTokensWithThemesOptions, CreatedBundledHighlighterOptions, GrammarState, HighlighterCoreOptions, HighlighterGeneric, LanguageInput, RegexEngine, RequireKeys, SpecialLanguage, SpecialTheme, ThemeInput, ThemedToken, ThemedTokenWithVariants, TokensResult } from '../types'
 import { isSpecialLang, isSpecialTheme } from '../utils'
 import { ShikiError } from '../error'
+import { createWasmOnigEngine } from '../engines/wasm'
 import { createHighlighterCore } from './highlighter'
 
 export type CreateHighlighterFactory<L extends string, T extends string> = (
   options: BundledHighlighterOptions<L, T>
 ) => Promise<HighlighterGeneric<L, T>>
 
+/**
+ * Create a `createHighlighter` function with bundled themes, languages, and engine.
+ *
+ * @example
+ * ```ts
+ * const createHighlighter = createdBundledHighlighter({
+ *   langs: {
+ *     typescript: () => import('shiki/langs/typescript.mjs'),
+ *     // ...
+ *   },
+ *   themes: {
+ *     nord: () => import('shiki/themes/nord.mjs'),
+ *     // ...
+ *   },
+ *   engine: () => createWasmOnigEngine(), // or createJavaScriptRegexEngine()
+ * })
+ * ```
+ *
+ * @param options
+ */
+export function createdBundledHighlighter<BundledLangs extends string, BundledThemes extends string>(
+  options: CreatedBundledHighlighterOptions<BundledLangs, BundledThemes>
+): CreateHighlighterFactory<BundledLangs, BundledThemes>
+
 /**
  * Create a `createHighlighter` function with bundled themes and languages.
  *
- * @param bundledLanguages
- * @param bundledThemes
- * @param loadWasm
+ * @deprecated Use `createdBundledHighlighter({ langs, themes, engine })` signature instead.
  */
 export function createdBundledHighlighter<BundledLangs extends string, BundledThemes extends string>(
   bundledLanguages: Record<BundledLangs, LanguageInput>,
   bundledThemes: Record<BundledThemes, ThemeInput>,
   loadWasm: HighlighterCoreOptions['loadWasm'],
+): CreateHighlighterFactory<BundledLangs, BundledThemes>
+
+// Implementation
+export function createdBundledHighlighter<BundledLangs extends string, BundledThemes extends string>(
+  arg1: Record<BundledLangs, LanguageInput> | CreatedBundledHighlighterOptions<BundledLangs, BundledThemes>,
+  arg2?: Record<BundledThemes, ThemeInput>,
+  arg3?: HighlighterCoreOptions['loadWasm'],
 ): CreateHighlighterFactory<BundledLangs, BundledThemes> {
+  let bundledLanguages: Record<BundledLangs, LanguageInput>
+  let bundledThemes: Record<BundledThemes, ThemeInput>
+  let engine: () => Awaitable<RegexEngine>
+
+  if (arg2) {
+    // TODO: next: console.warn('`createdBundledHighlighter` signature with `bundledLanguages` and `bundledThemes` is deprecated. Use the options object signature instead.')
+    bundledLanguages = arg1 as Record<BundledLangs, LanguageInput>
+    bundledThemes = arg2
+    engine = () => createWasmOnigEngine(arg3)
+  }
+  else {
+    const options = arg1 as CreatedBundledHighlighterOptions<BundledLangs, BundledThemes>
+    bundledLanguages = options.langs
+    bundledThemes = options.themes
+    engine = options.engine
+  }
+
   async function createHighlighter(
     options: BundledHighlighterOptions<BundledLangs, BundledThemes>,
   ): Promise<HighlighterGeneric<BundledLangs, BundledThemes>> {
@@ -56,7 +103,7 @@ export function createdBundledHighlighter<BundledLangs extends string, BundledTh
       ...options,
       themes: _themes,
       langs,
-      loadWasm,
+      engine: engine(),
     })
 
     return {

packages/core/src/types/highlighter.ts

@@ -4,7 +4,8 @@ import type { LanguageInput, LanguageRegistration, ResolveBundleKey, SpecialLang
 import type { SpecialTheme, ThemeInput, ThemeRegistrationAny, ThemeRegistrationResolved } from './themes'
 import type { CodeToTokensBaseOptions, CodeToTokensOptions, CodeToTokensWithThemesOptions, GrammarState, ThemedToken, ThemedTokenWithVariants, TokensResult } from './tokens'
 import type { CodeToHastOptions } from './options'
-import type { MaybeArray } from './utils'
+import type { Awaitable, MaybeArray } from './utils'
+import type { RegexEngine } from './engines'
 
 /**
  * Internal context of Shiki, core textmate logic
@@ -135,3 +136,12 @@ export interface HighlighterGeneric<BundledLangKeys extends string, BundledTheme
  * The fine-grained core Shiki highlighter instance.
  */
 export type HighlighterCore = HighlighterGeneric<never, never>
+
+/**
+ * Options for creating a bundled highlighter.
+ */
+export interface CreatedBundledHighlighterOptions<BundledLangs extends string, BundledThemes extends string> {
+  langs: Record<BundledLangs, LanguageInput>
+  themes: Record<BundledThemes, ThemeInput>
+  engine: () => Awaitable<RegexEngine>
+}

packages/shiki/src/bundle-full.ts

@@ -1,5 +1,5 @@
 import type { CreateHighlighterFactory, HighlighterGeneric } from '@shikijs/core'
-import { createSingletonShorthands, createdBundledHighlighter } from './core'
+import { createSingletonShorthands, createWasmOnigEngine, createdBundledHighlighter } from './core'
 import type { BundledLanguage } from './assets/langs-bundle-full'
 import type { BundledTheme } from './themes'
 import { bundledLanguages } from './assets/langs-bundle-full'
@@ -28,11 +28,11 @@ export type Highlighter = HighlighterGeneric<BundledLanguage, BundledTheme>
 export const createHighlighter = /* @__PURE__ */ createdBundledHighlighter<
   BundledLanguage,
   BundledTheme
->(
-  bundledLanguages,
-  bundledThemes,
-  getWasmInlined,
-)
+>({
+  langs: bundledLanguages,
+  themes: bundledThemes,
+  engine: () => createWasmOnigEngine(getWasmInlined),
+})
 
 export const {
   codeToHtml,

packages/shiki/src/bundle-web.ts

@@ -1,5 +1,5 @@
 import type { CreateHighlighterFactory, HighlighterGeneric } from '@shikijs/core'
-import { createSingletonShorthands, createdBundledHighlighter } from './core'
+import { createSingletonShorthands, createWasmOnigEngine, createdBundledHighlighter } from './core'
 import type { BundledLanguage } from './assets/langs-bundle-web'
 import type { BundledTheme } from './themes'
 import { bundledLanguages } from './assets/langs-bundle-web'
@@ -28,11 +28,11 @@ export type Highlighter = HighlighterGeneric<BundledLanguage, BundledTheme>
 export const createHighlighter = /* @__PURE__ */ createdBundledHighlighter<
   BundledLanguage,
   BundledTheme
->(
-  bundledLanguages,
-  bundledThemes,
-  getWasmInlined,
-)
+>({
+  langs: bundledLanguages,
+  themes: bundledThemes,
+  engine: () => createWasmOnigEngine(getWasmInlined),
+})
 
 export const {
   codeToHtml,