From c9bf7ded2e74790c902384e13c1d444c7136c1f9 Mon Sep 17 00:00:00 2001 From: Evan You Date: Thu, 30 Apr 2020 17:04:35 -0400 Subject: [PATCH] refactor(types): mark internal API exports and exclude from d.ts BREAKING CHANGE: Internal APIs are now excluded from type decalrations. --- packages/compiler-core/api-extractor.json | 2 +- packages/compiler-dom/api-extractor.json | 4 +- packages/compiler-sfc/api-extractor.json | 4 +- packages/compiler-ssr/api-extractor.json | 4 +- packages/reactivity/api-extractor.json | 2 +- packages/runtime-core/api-extractor.json | 2 +- packages/runtime-core/src/component.ts | 6 +- packages/runtime-core/src/directives.ts | 4 + .../runtime-core/src/helpers/createSlots.ts | 4 + .../runtime-core/src/helpers/renderList.ts | 25 +++- .../runtime-core/src/helpers/renderSlot.ts | 4 + .../runtime-core/src/helpers/resolveAssets.ts | 9 ++ packages/runtime-core/src/helpers/scopeId.ts | 9 ++ .../runtime-core/src/helpers/toHandlers.ts | 5 +- .../src/helpers/withRenderContext.ts | 4 + packages/runtime-core/src/index.ts | 114 ++++++++++-------- packages/runtime-core/src/vnode.ts | 40 ++++-- packages/runtime-dom/api-extractor.json | 2 +- packages/runtime-dom/src/directives/vModel.ts | 18 ++- packages/runtime-dom/src/directives/vOn.ts | 6 + packages/runtime-dom/src/directives/vShow.ts | 3 + packages/runtime-dom/src/index.ts | 16 +-- packages/runtime-test/api-extractor.json | 2 +- packages/server-renderer/api-extractor.json | 2 +- packages/shared/api-extractor.json | 2 +- packages/shared/src/index.ts | 8 +- packages/vue/api-extractor.json | 2 +- scripts/bootstrap.js | 2 +- 28 files changed, 209 insertions(+), 96 deletions(-) diff --git a/packages/compiler-core/api-extractor.json b/packages/compiler-core/api-extractor.json index 933cd92e3d6..b677d51cd8d 100644 --- a/packages/compiler-core/api-extractor.json +++ b/packages/compiler-core/api-extractor.json @@ -2,6 +2,6 @@ "extends": "../../api-extractor.json", "mainEntryPointFilePath": "./dist/packages//src/index.d.ts", "dtsRollup": { - "untrimmedFilePath": "./dist/.d.ts" + "publicTrimmedFilePath": "./dist/.d.ts" } } diff --git a/packages/compiler-dom/api-extractor.json b/packages/compiler-dom/api-extractor.json index 305e85ffe67..5602b3a6fd2 100644 --- a/packages/compiler-dom/api-extractor.json +++ b/packages/compiler-dom/api-extractor.json @@ -2,6 +2,6 @@ "extends": "../../api-extractor.json", "mainEntryPointFilePath": "./dist/packages//src/index.d.ts", "dtsRollup": { - "untrimmedFilePath": "./dist/.d.ts" + "publicTrimmedFilePath": "./dist/.d.ts" } -} \ No newline at end of file +} diff --git a/packages/compiler-sfc/api-extractor.json b/packages/compiler-sfc/api-extractor.json index 305e85ffe67..5602b3a6fd2 100644 --- a/packages/compiler-sfc/api-extractor.json +++ b/packages/compiler-sfc/api-extractor.json @@ -2,6 +2,6 @@ "extends": "../../api-extractor.json", "mainEntryPointFilePath": "./dist/packages//src/index.d.ts", "dtsRollup": { - "untrimmedFilePath": "./dist/.d.ts" + "publicTrimmedFilePath": "./dist/.d.ts" } -} \ No newline at end of file +} diff --git a/packages/compiler-ssr/api-extractor.json b/packages/compiler-ssr/api-extractor.json index 305e85ffe67..5602b3a6fd2 100644 --- a/packages/compiler-ssr/api-extractor.json +++ b/packages/compiler-ssr/api-extractor.json @@ -2,6 +2,6 @@ "extends": "../../api-extractor.json", "mainEntryPointFilePath": "./dist/packages//src/index.d.ts", "dtsRollup": { - "untrimmedFilePath": "./dist/.d.ts" + "publicTrimmedFilePath": "./dist/.d.ts" } -} \ No newline at end of file +} diff --git a/packages/reactivity/api-extractor.json b/packages/reactivity/api-extractor.json index 933cd92e3d6..b677d51cd8d 100644 --- a/packages/reactivity/api-extractor.json +++ b/packages/reactivity/api-extractor.json @@ -2,6 +2,6 @@ "extends": "../../api-extractor.json", "mainEntryPointFilePath": "./dist/packages//src/index.d.ts", "dtsRollup": { - "untrimmedFilePath": "./dist/.d.ts" + "publicTrimmedFilePath": "./dist/.d.ts" } } diff --git a/packages/runtime-core/api-extractor.json b/packages/runtime-core/api-extractor.json index 933cd92e3d6..b677d51cd8d 100644 --- a/packages/runtime-core/api-extractor.json +++ b/packages/runtime-core/api-extractor.json @@ -2,6 +2,6 @@ "extends": "../../api-extractor.json", "mainEntryPointFilePath": "./dist/packages//src/index.d.ts", "dtsRollup": { - "untrimmedFilePath": "./dist/.d.ts" + "publicTrimmedFilePath": "./dist/.d.ts" } } diff --git a/packages/runtime-core/src/component.ts b/packages/runtime-core/src/component.ts index a2387a648a1..2136ae791c6 100644 --- a/packages/runtime-core/src/component.ts +++ b/packages/runtime-core/src/component.ts @@ -417,7 +417,11 @@ type CompileFunction = ( let compile: CompileFunction | undefined -// exported method uses any to avoid d.ts relying on the compiler types. +/** + * For runtime-dom to register the compiler. + * Note the exported method uses any to avoid d.ts relying on the compiler types. + * @internal + */ export function registerRuntimeCompiler(_compile: any) { compile = _compile } diff --git a/packages/runtime-core/src/directives.ts b/packages/runtime-core/src/directives.ts index f5e0eb1ba0b..d4d378345f9 100644 --- a/packages/runtime-core/src/directives.ts +++ b/packages/runtime-core/src/directives.ts @@ -80,6 +80,10 @@ export type DirectiveArguments = Array< | [Directive, any, string, DirectiveModifiers] > +/** + * Adds directives to a VNode. + * @internal + */ export function withDirectives( vnode: T, directives: DirectiveArguments diff --git a/packages/runtime-core/src/helpers/createSlots.ts b/packages/runtime-core/src/helpers/createSlots.ts index c16aeed7740..f6c9c9929f4 100644 --- a/packages/runtime-core/src/helpers/createSlots.ts +++ b/packages/runtime-core/src/helpers/createSlots.ts @@ -6,6 +6,10 @@ interface CompiledSlotDescriptor { fn: Slot } +/** + * Compiler runtime helper for creating dynamic slots object + * @internal + */ export function createSlots( slots: Record, dynamicSlots: ( diff --git a/packages/runtime-core/src/helpers/renderList.ts b/packages/runtime-core/src/helpers/renderList.ts index 5dd68d6b8a8..810ec1edc5c 100644 --- a/packages/runtime-core/src/helpers/renderList.ts +++ b/packages/runtime-core/src/helpers/renderList.ts @@ -1,31 +1,46 @@ import { VNodeChild } from '../vnode' import { isArray, isString, isObject } from '@vue/shared' -// v-for string +/** + * v-for string + * @internal + */ export function renderList( source: string, renderItem: (value: string, index: number) => VNodeChild ): VNodeChild[] -// v-for number +/** + * v-for number + * @internal + */ export function renderList( source: number, renderItem: (value: number, index: number) => VNodeChild ): VNodeChild[] -// v-for array +/** + * v-for array + * @internal + */ export function renderList( source: T[], renderItem: (value: T, index: number) => VNodeChild ): VNodeChild[] -// v-for iterable +/** + * v-for iterable + * @internal + */ export function renderList( source: Iterable, renderItem: (value: T, index: number) => VNodeChild ): VNodeChild[] -// v-for object +/** + * v-for object + * @internal + */ export function renderList( source: T, renderItem: ( diff --git a/packages/runtime-core/src/helpers/renderSlot.ts b/packages/runtime-core/src/helpers/renderSlot.ts index c0bfcaa7bf0..41d942b2949 100644 --- a/packages/runtime-core/src/helpers/renderSlot.ts +++ b/packages/runtime-core/src/helpers/renderSlot.ts @@ -10,6 +10,10 @@ import { import { PatchFlags } from '@vue/shared' import { warn } from '../warning' +/** + * Compiler runtime helper for rendering + * @internal + */ export function renderSlot( slots: Slots, name: string, diff --git a/packages/runtime-core/src/helpers/resolveAssets.ts b/packages/runtime-core/src/helpers/resolveAssets.ts index f7118a88fc7..b2db0adbe45 100644 --- a/packages/runtime-core/src/helpers/resolveAssets.ts +++ b/packages/runtime-core/src/helpers/resolveAssets.ts @@ -12,12 +12,18 @@ import { warn } from '../warning' const COMPONENTS = 'components' const DIRECTIVES = 'directives' +/** + * @internal + */ export function resolveComponent(name: string): Component | string | undefined { return resolveAsset(COMPONENTS, name) || name } export const NULL_DYNAMIC_COMPONENT = Symbol() +/** + * @internal + */ export function resolveDynamicComponent( component: unknown ): Component | string | typeof NULL_DYNAMIC_COMPONENT { @@ -29,6 +35,9 @@ export function resolveDynamicComponent( } } +/** + * @internal + */ export function resolveDirective(name: string): Directive | undefined { return resolveAsset(DIRECTIVES, name) } diff --git a/packages/runtime-core/src/helpers/scopeId.ts b/packages/runtime-core/src/helpers/scopeId.ts index 36aaf68ee82..6c30ca10074 100644 --- a/packages/runtime-core/src/helpers/scopeId.ts +++ b/packages/runtime-core/src/helpers/scopeId.ts @@ -7,15 +7,24 @@ import { withCtx } from './withRenderContext' export let currentScopeId: string | null = null const scopeIdStack: string[] = [] +/** + * @internal + */ export function pushScopeId(id: string) { scopeIdStack.push((currentScopeId = id)) } +/** + * @internal + */ export function popScopeId() { scopeIdStack.pop() currentScopeId = scopeIdStack[scopeIdStack.length - 1] || null } +/** + * @internal + */ export function withScopeId(id: string): (fn: T) => T { return ((fn: Function) => withCtx(function(this: any) { diff --git a/packages/runtime-core/src/helpers/toHandlers.ts b/packages/runtime-core/src/helpers/toHandlers.ts index 777a4f0f84d..a87b9e6858f 100644 --- a/packages/runtime-core/src/helpers/toHandlers.ts +++ b/packages/runtime-core/src/helpers/toHandlers.ts @@ -1,7 +1,10 @@ import { isObject } from '@vue/shared' import { warn } from '../warning' -// For prefixing keys in v-on="obj" with "on" +/** + * For prefixing keys in v-on="obj" with "on" + * @internal + */ export function toHandlers(obj: Record): Record { const ret: Record = {} if (__DEV__ && !isObject(obj)) { diff --git a/packages/runtime-core/src/helpers/withRenderContext.ts b/packages/runtime-core/src/helpers/withRenderContext.ts index 558d40d278f..f8aeb397162 100644 --- a/packages/runtime-core/src/helpers/withRenderContext.ts +++ b/packages/runtime-core/src/helpers/withRenderContext.ts @@ -5,6 +5,10 @@ import { } from '../componentRenderUtils' import { ComponentInternalInstance } from '../component' +/** + * Wrap a slot function to memoize current rendering instance + * @internal + */ export function withCtx( fn: Slot, ctx: ComponentInternalInstance | null = currentRenderingInstance diff --git a/packages/runtime-core/src/index.ts b/packages/runtime-core/src/index.ts index 324349b8937..85efb5b0f98 100644 --- a/packages/runtime-core/src/index.ts +++ b/packages/runtime-core/src/index.ts @@ -74,9 +74,8 @@ export { useCSSModule } from './helpers/useCssModule' // SSR context export { useSSRContext, ssrContextKey } from './helpers/useSsrContext' -// Internal API ---------------------------------------------------------------- +// Custom Renderer API --------------------------------------------------------- -// For custom renderers export { createRenderer, createHydrationRenderer } from './renderer' export { queuePostFlushCb } from './scheduler' export { warn } from './warning' @@ -92,57 +91,6 @@ export { setTransitionHooks } from './components/BaseTransition' -// For compiler generated code -// should sync with '@vue/compiler-core/src/runtimeConstants.ts' -export { withCtx } from './helpers/withRenderContext' -export { withDirectives } from './directives' -export { - resolveComponent, - resolveDirective, - resolveDynamicComponent -} from './helpers/resolveAssets' -export { renderList } from './helpers/renderList' -export { toHandlers } from './helpers/toHandlers' -export { renderSlot } from './helpers/renderSlot' -export { createSlots } from './helpers/createSlots' -export { pushScopeId, popScopeId, withScopeId } from './helpers/scopeId' -export { - setBlockTracking, - createTextVNode, - createCommentVNode, - createStaticVNode -} from './vnode' -export { toDisplayString, camelize } from '@vue/shared' - -// For integration with runtime compiler -export { registerRuntimeCompiler } from './component' - -// For test-utils -export { transformVNodeArgs } from './vnode' - -// SSR ------------------------------------------------------------------------- - -import { createComponentInstance, setupComponent } from './component' -import { - renderComponentRoot, - setCurrentRenderingInstance -} from './componentRenderUtils' -import { isVNode, normalizeVNode } from './vnode' -import { normalizeSuspenseChildren } from './components/Suspense' - -// SSR utils are only exposed in cjs builds. -const _ssrUtils = { - createComponentInstance, - setupComponent, - renderComponentRoot, - setCurrentRenderingInstance, - isVNode, - normalizeVNode, - normalizeSuspenseChildren -} - -export const ssrUtils = (__NODE_JS__ ? _ssrUtils : null) as typeof _ssrUtils - // Types ----------------------------------------------------------------------- export { @@ -233,3 +181,63 @@ export { AsyncComponentLoader } from './apiAsyncComponent' export { HMRRuntime } from './hmr' + +// Internal API ---------------------------------------------------------------- + +// **IMPORTANT** Internal APIs may change without notice between versions and +// user code should avoid relying on them. + +// For compiler generated code +// should sync with '@vue/compiler-core/src/runtimeConstants.ts' +export { withCtx } from './helpers/withRenderContext' +export { withDirectives } from './directives' +export { + resolveComponent, + resolveDirective, + resolveDynamicComponent +} from './helpers/resolveAssets' +export { renderList } from './helpers/renderList' +export { toHandlers } from './helpers/toHandlers' +export { renderSlot } from './helpers/renderSlot' +export { createSlots } from './helpers/createSlots' +export { pushScopeId, popScopeId, withScopeId } from './helpers/scopeId' +export { + setBlockTracking, + createTextVNode, + createCommentVNode, + createStaticVNode +} from './vnode' +export { toDisplayString, camelize } from '@vue/shared' +// For integration with runtime compiler +export { registerRuntimeCompiler } from './component' +// For test-utils +export { transformVNodeArgs } from './vnode' + +// SSR ------------------------------------------------------------------------- + +// **IMPORTANT** These APIs are exposed solely for @vue/server-renderer and may +// change without notice between versions. User code should never rely on them. + +import { createComponentInstance, setupComponent } from './component' +import { + renderComponentRoot, + setCurrentRenderingInstance +} from './componentRenderUtils' +import { isVNode, normalizeVNode } from './vnode' +import { normalizeSuspenseChildren } from './components/Suspense' + +const _ssrUtils = { + createComponentInstance, + setupComponent, + renderComponentRoot, + setCurrentRenderingInstance, + isVNode, + normalizeVNode, + normalizeSuspenseChildren +} + +/** + * SSR utils for \@vue/server-renderer. Only exposed in cjs builds. + * @internal + */ +export const ssrUtils = (__NODE_JS__ ? _ssrUtils : null) as typeof _ssrUtils diff --git a/packages/runtime-core/src/vnode.ts b/packages/runtime-core/src/vnode.ts index 3b21c6abcb4..eee9a1b8ce1 100644 --- a/packages/runtime-core/src/vnode.ts +++ b/packages/runtime-core/src/vnode.ts @@ -155,15 +155,21 @@ export function openBlock(disableTracking = false) { // incremented/decremented by nested usage of v-once (see below) let shouldTrack = 1 -// Block tracking sometimes needs to be disabled, for example during the -// creation of a tree that needs to be cached by v-once. The compiler generates -// code like this: -// _cache[1] || ( -// setBlockTracking(-1), -// _cache[1] = createVNode(...), -// setBlockTracking(1), -// _cache[1] -// ) +/** + * Block tracking sometimes needs to be disabled, for example during the + * creation of a tree that needs to be cached by v-once. The compiler generates + * code like this: + * + * ``` js + * _cache[1] || ( + * setBlockTracking(-1), + * _cache[1] = createVNode(...), + * setBlockTracking(1), + * _cache[1] + * ) + * ``` + * @internal + */ export function setBlockTracking(value: number) { shouldTrack += value } @@ -222,8 +228,11 @@ let vnodeArgsTransformer: ) => Parameters) | undefined -// Internal API for registering an arguments transform for createVNode -// used for creating stubs in the test-utils +/** + * Internal API for registering an arguments transform for createVNode + * used for creating stubs in the test-utils + * @internal + */ export function transformVNodeArgs(transformer?: typeof vnodeArgsTransformer) { vnodeArgsTransformer = transformer } @@ -406,14 +415,23 @@ export function cloneVNode( } } +/** + * @internal + */ export function createTextVNode(text: string = ' ', flag: number = 0): VNode { return createVNode(Text, null, text, flag) } +/** + * @internal + */ export function createStaticVNode(content: string): VNode { return createVNode(Static, null, content) } +/** + * @internal + */ export function createCommentVNode( text: string = '', // when used as the v-else branch, the comment node must be created as a diff --git a/packages/runtime-dom/api-extractor.json b/packages/runtime-dom/api-extractor.json index 933cd92e3d6..b677d51cd8d 100644 --- a/packages/runtime-dom/api-extractor.json +++ b/packages/runtime-dom/api-extractor.json @@ -2,6 +2,6 @@ "extends": "../../api-extractor.json", "mainEntryPointFilePath": "./dist/packages//src/index.d.ts", "dtsRollup": { - "untrimmedFilePath": "./dist/.d.ts" + "publicTrimmedFilePath": "./dist/.d.ts" } } diff --git a/packages/runtime-dom/src/directives/vModel.ts b/packages/runtime-dom/src/directives/vModel.ts index e7c70f82965..090f27ce1a3 100644 --- a/packages/runtime-dom/src/directives/vModel.ts +++ b/packages/runtime-dom/src/directives/vModel.ts @@ -41,7 +41,11 @@ function toNumber(val: string): number | string { type ModelDirective = ObjectDirective // We are exporting the v-model runtime directly as vnode hooks so that it can -// be tree-shaken in case v-model is never used. +// be tree-shaken in case v-model is never used. These are used by compilers +// only and userland code should avoid relying on them. +/** + * @internal + */ export const vModelText: ModelDirective< HTMLInputElement | HTMLTextAreaElement > = { @@ -90,6 +94,9 @@ export const vModelText: ModelDirective< } } +/** + * @internal + */ export const vModelCheckbox: ModelDirective = { beforeMount(el, binding, vnode) { setChecked(el, binding, vnode) @@ -135,6 +142,9 @@ function setChecked( } } +/** + * @internal + */ export const vModelRadio: ModelDirective = { beforeMount(el, { value }, vnode) { el.checked = looseEqual(value, vnode.props!.value) @@ -151,6 +161,9 @@ export const vModelRadio: ModelDirective = { } } +/** + * @internal + */ export const vModelSelect: ModelDirective = { // use mounted & updated because