0
# @intlify/shared
1
2
A comprehensive shared utility library for the Intlify internationalization ecosystem, providing performance measurement tools, string formatting functions, event emitter implementations, error handling utilities, and type checking functions. The library serves as a foundational utility package that supports other Intlify projects like Vue I18n.
3
4
## Package Information
5
6
- **Package Name**: @intlify/shared
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @intlify/shared`
10
11
## Core Imports
12
13
```typescript
14
import {
15
// Utility functions
16
isArray, isString, isObject, format, escapeHtml,
17
// Event system
18
createEmitter, type Emittable,
19
// Warning system
20
warn, warnOnce,
21
// Environment detection
22
inBrowser, getGlobalThis
23
} from "@intlify/shared";
24
```
25
26
For CommonJS:
27
28
```javascript
29
const {
30
isArray, isString, isObject, format, escapeHtml,
31
createEmitter, warn, warnOnce, inBrowser, getGlobalThis
32
} = require("@intlify/shared");
33
```
34
35
## Basic Usage
36
37
```typescript
38
import {
39
format, isObject, createEmitter, warn, escapeHtml,
40
type Emittable, type EventHandler
41
} from "@intlify/shared";
42
43
// String formatting with placeholders
44
const message = format("Hello {name}, you have {count} messages", {
45
name: "Alice",
46
count: 5
47
});
48
49
// Type checking
50
if (isObject(someValue)) {
51
// Safe to access properties
52
}
53
54
// Event emitter
55
const emitter = createEmitter<{ userLogin: { userId: string } }>();
56
emitter.on("userLogin", (payload) => {
57
console.log(`User logged in: ${payload?.userId}`);
58
});
59
emitter.emit("userLogin", { userId: "123" });
60
61
// Warning system
62
warn("This is a warning message");
63
64
// HTML escaping for security
65
const safeHtml = escapeHtml("<script>alert('xss')</script>");
66
```
67
68
## Architecture
69
70
@intlify/shared is organized into several key functional areas:
71
72
- **Type System**: Comprehensive type checking utilities covering all JavaScript types
73
- **String Processing**: Formatting, escaping, and sanitization functions for secure text handling
74
- **Event System**: Type-safe event emitter implementation with wildcard support
75
- **Environment Detection**: Runtime environment detection and global object access
76
- **Performance Tools**: Development-time performance measurement utilities
77
- **Warning System**: Consistent warning and debugging message display
78
- **Object Utilities**: Object manipulation and deep copying functions
79
80
## Capabilities
81
82
### Type Checking Utilities
83
84
Comprehensive type checking functions for runtime type validation and type guards.
85
86
```typescript { .api }
87
function isArray(val: unknown): val is any[];
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 isBoolean(val: unknown): val is boolean;
92
function isNumber(val: unknown): val is number;
93
function isPromise<T = any>(val: unknown): val is Promise<T>;
94
function isPlainObject(val: unknown): val is object;
95
```
96
97
[Type Checking](./type-checking.md)
98
99
### String Processing
100
101
String formatting, HTML escaping, and sanitization functions for secure text processing.
102
103
```typescript { .api }
104
function format(message: string, ...args: any): string;
105
function escapeHtml(rawText: string): string;
106
function sanitizeTranslatedHtml(html: string): string;
107
function toDisplayString(val: unknown): string;
108
function join(items: string[], separator?: string): string;
109
```
110
111
[String Processing](./string-processing.md)
112
113
### Event System
114
115
Type-safe event emitter implementation with support for wildcard listeners and strongly-typed event payloads.
116
117
```typescript { .api }
118
function createEmitter<Events extends Record<EventType, unknown>>(): Emittable<Events>;
119
120
interface Emittable<Events extends Record<EventType, unknown> = {}> {
121
events: EventHandlerMap<Events>;
122
on<Key extends keyof Events>(
123
event: Key | '*',
124
handler: EventHandler<Events[keyof Events]> | WildcardEventHandler<Events>
125
): void;
126
off<Key extends keyof Events>(
127
event: Key | '*',
128
handler: EventHandler<Events[keyof Events]> | WildcardEventHandler<Events>
129
): void;
130
emit<Key extends keyof Events>(
131
event: Key,
132
payload?: Events[keyof Events]
133
): void;
134
}
135
```
136
137
[Event System](./event-system.md)
138
139
### Environment & Performance
140
141
Environment detection and performance measurement utilities for cross-platform development.
142
143
```typescript { .api }
144
const inBrowser: boolean;
145
function getGlobalThis(): any;
146
let mark: (tag: string) => void | undefined;
147
let measure: (name: string, startTag: string, endTag: string) => void | undefined;
148
```
149
150
[Environment & Performance](./environment-performance.md)
151
152
### Object Utilities
153
154
Object creation, property checking, and deep copying utilities.
155
156
```typescript { .api }
157
const assign: typeof Object.assign;
158
function create(obj?: object | null): object;
159
function hasOwn(obj: object | Array<any>, key: string): boolean;
160
function deepCopy(src: any, des: any): void;
161
```
162
163
[Object Utilities](./object-utilities.md)
164
165
### Warning System
166
167
Consistent warning and debugging message display system.
168
169
```typescript { .api }
170
function warn(msg: string, err?: Error): void;
171
function warnOnce(msg: string): void;
172
```
173
174
[Warning System](./warning-system.md)
175
176
## Core Types
177
178
```typescript { .api }
179
type EventType = string | symbol;
180
type EventHandler<T = unknown> = (payload?: T) => void;
181
type WildcardEventHandler<T = Record<string, unknown>> = (
182
event: keyof T,
183
payload?: T[keyof T]
184
) => void;
185
186
interface BaseError {
187
code: number;
188
}
189
```