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,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/compiler-dom/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/compiler-sfc/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/compiler-ssr/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/reactivity/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/runtime-core/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

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
 }

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<T extends VNode>(
   vnode: T,
   directives: DirectiveArguments

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<string, Slot>,
   dynamicSlots: (

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<T>(
   source: T[],
   renderItem: (value: T, index: number) => VNodeChild
 ): VNodeChild[]
 
-// v-for iterable
+/**
+ * v-for iterable
+ * @internal
+ */
 export function renderList<T>(
   source: Iterable<T>,
   renderItem: (value: T, index: number) => VNodeChild
 ): VNodeChild[]
 
-// v-for object
+/**
+ * v-for object
+ * @internal
+ */
 export function renderList<T>(
   source: T,
   renderItem: <K extends keyof T>(

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 <slot/>
+ * @internal
+ */
 export function renderSlot(
   slots: Slots,
   name: string,

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)
 }

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): <T extends Function>(fn: T) => T {
   return ((fn: Function) =>
     withCtx(function(this: any) {

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<string, any>): Record<string, any> {
   const ret: Record<string, any> = {}
   if (__DEV__ && !isObject(obj)) {

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

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

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
+ * Block tracking sometimes needs to be disabled, for example during the
-// code like this:
+ * creation of a tree that needs to be cached by v-once. The compiler generates
-//   _cache[1] || (
+ * code like this:
-//     setBlockTracking(-1),
+ *
-//     _cache[1] = createVNode(...),
+ * ``` js
-//     setBlockTracking(1),
+ * _cache[1] || (
-//     _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<typeof _createVNode>)
   | 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<T, U>(
   }
 }
 
+/**
+ * @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

packages/runtime-dom/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/runtime-dom/src/directives/vModel.ts

@@ -41,7 +41,11 @@ function toNumber(val: string): number | string {
 type ModelDirective<T> = ObjectDirective<T & { _assign: AssignerFn }>
 
 // 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<HTMLInputElement> = {
   beforeMount(el, binding, vnode) {
     setChecked(el, binding, vnode)
@@ -135,6 +142,9 @@ function setChecked(
   }
 }
 
+/**
+ * @internal
+ */
 export const vModelRadio: ModelDirective<HTMLInputElement> = {
   beforeMount(el, { value }, vnode) {
     el.checked = looseEqual(value, vnode.props!.value)
@@ -151,6 +161,9 @@ export const vModelRadio: ModelDirective<HTMLInputElement> = {
   }
 }
 
+/**
+ * @internal
+ */
 export const vModelSelect: ModelDirective<HTMLSelectElement> = {
   // use mounted & updated because <select> relies on its children <option>s.
   mounted(el, { value }, vnode) {
@@ -212,6 +225,9 @@ function getCheckboxValue(
   return key in el ? el[key] : checked
 }
 
+/**
+ * @internal
+ */
 export const vModelDynamic: ObjectDirective<
   HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement
 > = {

packages/runtime-dom/src/directives/vOn.ts

@@ -22,6 +22,9 @@ const modifierGuards: Record<
     systemModifiers.some(m => (e as any)[`${m}Key`] && !modifiers.includes(m))
 }
 
+/**
+ * @internal
+ */
 export const withModifiers = (fn: Function, modifiers: string[]) => {
   return (event: Event) => {
     for (let i = 0; i < modifiers.length; i++) {
@@ -44,6 +47,9 @@ const keyNames: Record<string, string | string[]> = {
   delete: 'backspace'
 }
 
+/**
+ * @internal
+ */
 export const withKeys = (fn: Function, modifiers: string[]) => {
   return (event: KeyboardEvent) => {
     if (!('key' in event)) return

packages/runtime-dom/src/directives/vShow.ts

@@ -5,6 +5,9 @@ interface VShowElement extends HTMLElement {
   _vod: string
 }
 
+/**
+ * @internal
+ */
 export const vShow: ObjectDirective<VShowElement> = {
   beforeMount(el, { value }, { transition }) {
     el._vod = el.style.display === 'none' ? '' : el.style.display

packages/runtime-dom/src/index.ts

@@ -109,7 +109,14 @@ function normalizeContainer(container: Element | string): Element | null {
   return container
 }
 
-// DOM-only runtime directive helpers
+// DOM-only components
+export { Transition, TransitionProps } from './components/Transition'
+export {
+  TransitionGroup,
+  TransitionGroupProps
+} from './components/TransitionGroup'
+
+// **Internal** DOM-only runtime directive helpers
 export {
   vModelText,
   vModelCheckbox,
@@ -120,13 +127,6 @@ export {
 export { withModifiers, withKeys } from './directives/vOn'
 export { vShow } from './directives/vShow'
 
-// DOM-only components
-export { Transition, TransitionProps } from './components/Transition'
-export {
-  TransitionGroup,
-  TransitionGroupProps
-} from './components/TransitionGroup'
-
 // re-export everything from core
 // h, Component, reactivity API, nextTick, flags & types
 export * from '@vue/runtime-core'

packages/runtime-test/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/server-renderer/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/shared/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

packages/shared/src/index.ts

@@ -89,6 +89,9 @@ const cacheStringFunction = <T extends (str: string) => string>(fn: T): T => {
 }
 
 const camelizeRE = /-(\w)/g
+/**
+ * @internal
+ */
 export const camelize = cacheStringFunction(
   (str: string): string => {
     return str.replace(camelizeRE, (_, c) => (c ? c.toUpperCase() : ''))
@@ -112,7 +115,10 @@ export const capitalize = cacheStringFunction(
 export const hasChanged = (value: any, oldValue: any): boolean =>
   value !== oldValue && (value === value || oldValue === oldValue)
 
-// for converting {{ interpolation }} values to displayed strings.
+/**
+ * For converting {{ interpolation }} values to displayed strings.
+ * @internal
+ */
 export const toDisplayString = (val: unknown): string => {
   return val == null
     ? ''

packages/vue/api-extractor.json

@@ -2,6 +2,6 @@
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }

scripts/bootstrap.js

@@ -65,7 +65,7 @@ files.forEach(shortName => {
   "extends": "../../api-extractor.json",
   "mainEntryPointFilePath": "./dist/packages/<unscopedPackageName>/src/index.d.ts",
   "dtsRollup": {
-    "untrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
   }
 }
 `.trim()