-
-
Notifications
You must be signed in to change notification settings - Fork 363
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: introduce warning system for deprecated API (#788)
- Loading branch information
Showing
20 changed files
with
171 additions
and
35 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
# Future | ||
|
||
We planned to remove some deprecated APIs and optimize the tree-shaking in the future major versions. | ||
|
||
The plan is: | ||
|
||
- 👉 `v1.x`: Deprecated APIs are still supported, marked on type level only. With optional runtime warnings to opt-in. | ||
- `v2.0`: No breaking changes, but enable runtime deprecated warnings by default. | ||
- `v3.0`: Remove deprecated APIs, breaking changes. | ||
|
||
At the current version, since v1.19.0, you can opt-in to the runtime warnings by calling `enableDeprecationWarnings()` at the beginning of your application. | ||
|
||
```ts | ||
import { enableDeprecationWarnings, getHighlighter } from 'shiki' | ||
|
||
enableDeprecationWarnings() // [!code hl] | ||
|
||
// Then calling deprecated usages like below would warn: | ||
// [SHIKI DEPRECATED]: Use `createHighlighter` instead | ||
const shiki = await getHighlighter(/* ... */) | ||
``` | ||
|
||
This would help you better prepare for the future changes and upgrade smoothly. | ||
|
||
## Notable Deprecations | ||
|
||
### `getHighlighter` -> `createHighlighter` | ||
|
||
There is no functional changes, but more like correcting the naming to avoid confusion. It should be a straightforward find-and-replace. | ||
|
||
### WASM Related APIs | ||
|
||
Since the introduce of the [engine system](/guide/regex-engines) in v0.16, the WebAssembly related dependencies are no longer a hard requirement. To make tree-shaking easier and decoupled the engines with the core, two packages are extracted `@shikijs/engine-oniguruma` and `@shikijs/engine-javascript`. They are also re-exported from the main package's `shiki/engine/oniguruma` and `shiki/engine/javascript` respectively. | ||
|
||
You might need to change your import path: | ||
|
||
```ts | ||
import { loadWasm } from 'shiki' // [!code --] | ||
import { loadWasm } from 'shiki/engine/oniguruma' // [!code ++] | ||
``` | ||
`loadWasm` field in `getHighlighter` is replaced with `engine` field: | ||
```ts | ||
import { createHighlighter } from 'shiki' | ||
import { createWasmOnigEngine } from 'shiki/engine/oniguruma' // [!code ++] | ||
const shiki = await createHighlighter({ | ||
// ... | ||
loadWasm: () => import('shiki/wasm'), // [!code --] | ||
engine: createWasmOnigEngine(() => import('shiki/wasm')), // [!code ++] | ||
}) | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,11 @@ | ||
export * from '@shikijs/engine-javascript' | ||
import type { JavaScriptRegexEngineOptions } from '@shikijs/engine-javascript' | ||
import type { RegexEngine } from '@shikijs/types' | ||
import { createJavaScriptRegexEngine as _createJavaScriptRegexEngine, defaultJavaScriptRegexConstructor } from '@shikijs/engine-javascript' | ||
import { warnDeprecated } from '../warn' | ||
|
||
export function createJavaScriptRegexEngine(options?: JavaScriptRegexEngineOptions): RegexEngine { | ||
warnDeprecated('import `createJavaScriptRegexEngine` from `@shikijs/engine-javascript` or `shiki/engine/javascript` instead') | ||
return _createJavaScriptRegexEngine(options) | ||
} | ||
|
||
export { defaultJavaScriptRegexConstructor } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,20 +1,16 @@ | ||
import type { LoadWasmOptions } from '@shikijs/types' | ||
import type { LoadWasmOptions, RegexEngine } from '@shikijs/types' | ||
import { | ||
createWasmOnigEngine as _createWasmOnigEngine, | ||
loadWasm as _loadWasm, | ||
} from '@shikijs/engine-oniguruma' | ||
import { warnDeprecated } from '../warn' | ||
|
||
export * from '@shikijs/engine-oniguruma' | ||
|
||
let _defaultWasmLoader: LoadWasmOptions | undefined | ||
|
||
/** | ||
* Set the default wasm loader for `loadWasm`. | ||
* @internal | ||
*/ | ||
export function setDefaultWasmLoader(_loader: LoadWasmOptions): void { | ||
_defaultWasmLoader = _loader | ||
export function createWasmOnigEngine(options?: LoadWasmOptions | null): Promise<RegexEngine> { | ||
warnDeprecated('import `createWasmOnigEngine` from `@shikijs/engine-oniguruma` or `shiki/engine/oniguruma` instead') | ||
return _createWasmOnigEngine(options) | ||
} | ||
|
||
/** | ||
* @internal | ||
*/ | ||
export function getDefaultWasmLoader(): LoadWasmOptions | undefined { | ||
return _defaultWasmLoader | ||
export function loadWasm(options: LoadWasmOptions): Promise<void> { | ||
warnDeprecated('import `loadWasm` from `@shikijs/engine-oniguruma` or `shiki/engine/oniguruma` instead') | ||
return _loadWasm(options) | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
let emitDeprecation = false | ||
|
||
/** | ||
* Enable runtime warning for deprecated APIs, for the future versions of Shiki. | ||
* | ||
* Disabled by default, will be enabled in Shiki v2. | ||
* | ||
* @experimental The accuracy of the warning messages is not yet guaranteed. | ||
*/ | ||
export function enableDeprecationWarnings(value = true): void { | ||
emitDeprecation = value | ||
} | ||
|
||
/** | ||
* @internal | ||
*/ | ||
export function warnDeprecated(message: string): void { | ||
if (emitDeprecation) | ||
// eslint-disable-next-line no-console | ||
console.trace(`[SHIKI DEPRECATE]: ${message}`) | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,6 @@ | ||
import { warnDeprecated } from './warn' | ||
|
||
export { default } from '@shikijs/engine-oniguruma/wasm-inlined' | ||
export * from '@shikijs/engine-oniguruma/wasm-inlined' | ||
|
||
warnDeprecated('Import from `@shikijs/engine-oniguruma/wasm-inlined` instead') |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,2 @@ | ||
export { default } from '@shikijs/core/wasm-inlined' | ||
export * from '@shikijs/core/wasm-inlined' | ||
export { default } from '@shikijs/engine-oniguruma/wasm-inlined' | ||
export * from '@shikijs/engine-oniguruma/wasm-inlined' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters