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
// "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
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
```