0
# Vue Shared
1
2
Vue Shared is the foundational utility library used internally across all Vue.js packages. It provides a comprehensive collection of utilities for DOM manipulation, type checking, reactive system optimizations, string transformations, and general-purpose functions. These utilities ensure consistent behavior and reduce code duplication across Vue's compiler, reactivity system, runtime, and other core packages.
3
4
## Package Information
5
6
- **Package Name**: @vue/shared
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vue/shared`
10
11
## Core Imports
12
13
```typescript
14
import {
15
isString, isObject, isFunction, extend, hasOwn,
16
PatchFlags, ShapeFlags, SlotFlags,
17
makeMap, camelize, hyphenate, capitalize,
18
escapeHtml, normalizeClass, normalizeStyle
19
} from "@vue/shared";
20
```
21
22
For CommonJS:
23
24
```javascript
25
const {
26
isString, isObject, isFunction, extend, hasOwn,
27
PatchFlags, ShapeFlags, SlotFlags,
28
makeMap, camelize, hyphenate, capitalize,
29
escapeHtml, normalizeClass, normalizeStyle
30
} = require("@vue/shared");
31
```
32
33
## Basic Usage
34
35
```typescript
36
import {
37
isString, isObject, extend, camelize,
38
normalizeClass, escapeHtml, PatchFlags
39
} from "@vue/shared";
40
41
// Type checking
42
if (isString(value)) {
43
console.log("It's a string:", value);
44
}
45
46
if (isObject(data)) {
47
const merged = extend({}, data, { newProp: "value" });
48
}
49
50
// String transformations
51
const camelCase = camelize("kebab-case-string"); // "kebabCaseString"
52
const kebabCase = hyphenate("camelCaseString"); // "camel-case-string"
53
54
// Class normalization
55
const classes = normalizeClass(["btn", { active: true }, "btn-primary"]);
56
// "btn active btn-primary"
57
58
// HTML escaping
59
const safe = escapeHtml('<script>alert("xss")</script>');
60
// "<script>alert("xss")</script>"
61
62
// Using optimization flags
63
const patchFlag = PatchFlags.TEXT | PatchFlags.CLASS;
64
if (patchFlag & PatchFlags.TEXT) {
65
// Handle text content updates
66
}
67
```
68
69
## Architecture
70
71
Vue Shared is organized around several key functional areas:
72
73
- **Type System**: Comprehensive type guards and checking utilities for all JavaScript types
74
- **String Utilities**: Cached transformation functions for common string operations (camelCase, kebab-case, etc.)
75
- **DOM Configuration**: Tag and attribute validation for HTML, SVG, and MathML elements
76
- **Reactive System Support**: Optimization flags (PatchFlags, ShapeFlags, SlotFlags) for efficient rendering
77
- **Normalization**: Standardization of props, styles, and classes across Vue components
78
- **Safety Utilities**: HTML escaping, sanitization, and security helpers
79
- **General Utilities**: Object manipulation, array helpers, and cross-environment compatibility
80
81
## Capabilities
82
83
### Type Checking and Validation
84
85
Comprehensive type guards and validation utilities for runtime type checking and safe property access.
86
87
```typescript { .api }
88
function isString(val: unknown): val is string;
89
function isObject(val: unknown): val is Record<any, any>;
90
function isFunction(val: unknown): val is Function;
91
function isArray(val: unknown): val is any[];
92
function hasOwn(val: object, key: string | symbol): key is keyof typeof val;
93
```
94
95
[Type Checking](./type-checking.md)
96
97
### String Transformations
98
99
Cached string transformation utilities for converting between naming conventions and manipulating text.
100
101
```typescript { .api }
102
function camelize(str: string): string;
103
function hyphenate(str: string): string;
104
function capitalize<T extends string>(str: T): Capitalize<T>;
105
function toHandlerKey<T extends string>(str: T): T extends '' ? '' : `on${Capitalize<T>}`;
106
```
107
108
[String Transformations](./string-transformations.md)
109
110
### Reactive System Flags
111
112
Bitwise optimization flags used by Vue's compiler and runtime for efficient rendering and reactivity tracking.
113
114
```typescript { .api }
115
enum PatchFlags {
116
TEXT = 1,
117
CLASS = 2,
118
STYLE = 4,
119
PROPS = 8,
120
// ... more flags
121
}
122
123
enum ShapeFlags {
124
ELEMENT = 1,
125
FUNCTIONAL_COMPONENT = 2,
126
STATEFUL_COMPONENT = 4,
127
// ... more flags
128
}
129
```
130
131
[Reactive System Flags](./reactive-flags.md)
132
133
### DOM Configuration
134
135
Validation utilities for HTML, SVG, and MathML elements and attributes, used by Vue's compiler for proper DOM handling.
136
137
```typescript { .api }
138
function isHTMLTag(key: string): boolean;
139
function isSVGTag(key: string): boolean;
140
function isBooleanAttr(key: string): boolean;
141
function isVoidTag(key: string): boolean;
142
```
143
144
[DOM Configuration](./dom-configuration.md)
145
146
### Props and Style Normalization
147
148
Utilities for normalizing component props, CSS styles, and class names into standardized formats.
149
150
```typescript { .api }
151
function normalizeClass(value: unknown): string;
152
function normalizeStyle(value: unknown): NormalizedStyle | string | undefined;
153
function normalizeProps(props: Record<string, any> | null): Record<string, any> | null;
154
155
type NormalizedStyle = Record<string, string | number>;
156
```
157
158
[Normalization](./normalization.md)
159
160
### HTML Security
161
162
HTML escaping and sanitization utilities for preventing XSS attacks and ensuring safe rendering.
163
164
```typescript { .api }
165
function escapeHtml(string: unknown): string;
166
function escapeHtmlComment(src: string): string;
167
function getEscapedCssVarName(key: string, doubleEscape: boolean): string;
168
```
169
170
[HTML Security](./html-security.md)
171
172
### Object and Array Utilities
173
174
General-purpose utilities for object manipulation, array operations, and data structure handling.
175
176
```typescript { .api }
177
const extend: typeof Object.assign;
178
function remove<T>(arr: T[], el: T): void;
179
function def(obj: object, key: string | symbol, value: any, writable?: boolean): void;
180
function hasChanged(value: any, oldValue: any): boolean;
181
```
182
183
[Object Utilities](./object-utilities.md)
184
185
### Equality and Comparison
186
187
Deep equality checking and comparison utilities with special handling for complex data types.
188
189
```typescript { .api }
190
function looseEqual(a: any, b: any): boolean;
191
function looseIndexOf(arr: any[], val: any): number;
192
```
193
194
[Equality Utilities](./equality-utilities.md)
195
196
### Display and Formatting
197
198
Utilities for converting values to display strings and formatting data for user presentation.
199
200
```typescript { .api }
201
function toDisplayString(val: unknown): string;
202
function generateCodeFrame(source: string, start?: number, end?: number): string;
203
```
204
205
[Display Utilities](./display-utilities.md)
206
207
### Environment and Global Access
208
209
Cross-environment utilities for accessing global objects and handling platform differences.
210
211
```typescript { .api }
212
function getGlobalThis(): any;
213
function isGloballyAllowed(key: string): boolean;
214
```
215
216
[Environment Utilities](./environment-utilities.md)
217
218
### Compiler Utilities
219
220
Internal utilities used by Vue's compiler for code generation and caching.
221
222
```typescript { .api }
223
function genPropsAccessExp(name: string): string;
224
function genCacheKey(source: string, options: any): string;
225
```
226
227
## Constants and Built-in Values
228
229
### Common Constants
230
231
```typescript { .api }
232
const EMPTY_OBJ: { readonly [key: string]: any };
233
const EMPTY_ARR: readonly never[];
234
const NOOP: () => void;
235
const NO: () => false;
236
```
237
238
### Vue-Specific Lookups
239
240
```typescript { .api }
241
function isReservedProp(key: string): boolean;
242
function isBuiltInDirective(key: string): boolean;
243
function isOn(key: string): boolean;
244
function isModelListener(key: string): key is `onUpdate:${string}`;
245
```
246
247
## TypeScript Utility Types
248
249
Advanced TypeScript utility types for type manipulation and generic programming.
250
251
```typescript { .api }
252
type Prettify<T> = { [K in keyof T]: T[K] } & {};
253
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
254
type LooseRequired<T> = { [P in keyof (T & Required<T>)]: T[P] };
255
type IfAny<T, Y, N> = 0 extends 1 & T ? Y : N;
256
type IsKeyValues<T, K = string> = IfAny<T, false, T extends object ? (keyof T extends K ? true : false) : false>;
257
type OverloadParameters<T extends (...args: any[]) => any> = Parameters<OverloadUnion<T>>;
258
```