0
# Utilities and Version Information
1

2
Utility functions, deprecation handling, and version information for the WebSocket library.
3

4
## Capabilities
5

6
### Version Information
7

8
Library version information and identification.
9

10
```javascript { .api }
11
/**
12
 * Current library version string
13
 */
14
const version: string; // "1.0.35"
15
```
16

17
**Usage Example:**
18

19
```javascript
20
const WebSocket = require('websocket');
21

22
console.log('WebSocket library version:', WebSocket.version);
23
// Output: WebSocket library version: 1.0.35
24

25
// Check version programmatically
26
const majorVersion = parseInt(WebSocket.version.split('.')[0]);
27
if (majorVersion >= 1) {
28
    console.log('Using modern WebSocket library');
29
}
30
```
31

32
### Deprecation Handling
33

34
Deprecation warning system for managing deprecated functionality.
35

36
```javascript { .api }
37
/**
38
 * Deprecation management
39
 */
40
class Deprecation {
41
    /** Disable all deprecation warnings */
42
    static disableWarnings: boolean;
43
    
44
    /** Map of deprecation warning messages */
45
    static deprecationWarningMap: object;
46
    
47
    /**
48
     * Show deprecation warning
49
     * @param deprecationName - Name of deprecated feature
50
     */
51
    static warn(deprecationName: string): void;
52
}
53
```
54

55
**Usage Example:**
56

57
```javascript
58
const WebSocket = require('websocket');
59

60
// Disable deprecation warnings globally
61
WebSocket.deprecation.disableWarnings = true;
62

63
// Or handle specific deprecation warnings
64
WebSocket.deprecation.warn('oldFeature');
65

66
// Check if warnings are enabled
67
if (!WebSocket.deprecation.disableWarnings) {
68
    console.log('Deprecation warnings are enabled');
69
}
70
```
71

72
### Utility Functions
73

74
Cross-platform utility functions for internal library operations.
75

76
```javascript { .api }
77
/**
78
 * Utility functions (mostly internal use)
79
 */
80
interface Utils {
81
    /** No-operation function */
82
    noop(): void;
83
    
84
    /** 
85
     * Extend object with properties from another object
86
     * @param dest - Destination object
87
     * @param source - Source object
88
     * @returns Extended object
89
     */
90
    extend(dest: object, source: object): object;
91
    
92
    /**
93
     * Cross-version event listener count
94
     * @param emitter - EventEmitter instance
95
     * @param type - Event type
96
     * @returns Number of listeners
97
     */
98
    eventEmitterListenerCount(emitter: EventEmitter, type: string): number;
99
    
100
    /**
101
     * Cross-version buffer allocation
102
     * @param size - Buffer size in bytes
103
     * @returns Allocated buffer
104
     */
105
    bufferAllocUnsafe(size: number): Buffer;
106
    
107
    /**
108
     * Cross-version buffer from string
109
     * @param string - String to convert
110
     * @param encoding - String encoding
111
     * @returns Buffer from string
112
     */
113
    bufferFromString(string: string, encoding?: string): Buffer;
114
    
115
    /**
116
     * Create buffering logger
117
     * @param identifier - Logger identifier
118
     * @param uniqueID - Unique logger ID  
119
     * @returns Logger function
120
     */
121
    BufferingLogger(identifier: string, uniqueID: string): Function;
122
}
123
```
124

125
**Usage Example:**
126

127
```javascript
128
// These utilities are primarily for internal use
129
// but can be accessed if needed for advanced usage
130

131
const WebSocket = require('websocket');
132

133
// Access internal utilities (not recommended for normal use)
134
const utils = require('websocket/lib/utils');
135

136
// Extend objects
137
const config = { timeout: 5000 };
138
const extendedConfig = utils.extend(config, { keepalive: true });
139
console.log(extendedConfig); // { timeout: 5000, keepalive: true }
140

141
// Cross-platform buffer operations
142
const buffer = utils.bufferAllocUnsafe(100);
143
const stringBuffer = utils.bufferFromString('Hello World', 'utf8');
144

145
// No-op function for default callbacks
146
const callback = utils.noop;
147
```
148

149
### Browser Compatibility
150

151
Browser-specific exports and compatibility handling.
152

153
```javascript { .api }
154
/**
155
 * Browser-specific exports
156
 * Available when using websocket/lib/browser
157
 */
158
interface BrowserExports {
159
    /** W3C WebSocket for browsers (may be null if native WebSocket available) */
160
    w3cwebsocket: typeof W3CWebSocket | null;
161
    
162
    /** Library version */
163
    version: string;
164
}
165
```
166

167
**Usage Example:**
168

169
```javascript
170
// In browser environments
171
const browserWebSocket = require('websocket/lib/browser');
172

173
// Use native WebSocket if available, fallback to library implementation
174
const WebSocketClass = browserWebSocket.w3cwebsocket || WebSocket;
175

176
if (WebSocketClass) {
177
    const client = new WebSocketClass('ws://localhost:8080/');
178
    console.log('Using WebSocket implementation');
179
} else {
180
    console.log('No WebSocket implementation available');
181
}
182

183
// Check library version in browser
184
console.log('Library version:', browserWebSocket.version);
185
```
186

187
### Advanced Utility Usage
188

189
**Custom Configuration Extension:**
190

191
```javascript
192
const WebSocket = require('websocket');
193
const utils = require('websocket/lib/utils');
194

195
// Create default configuration
196
const defaultConfig = {
197
    maxReceivedFrameSize: 64 * 1024,
198
    maxReceivedMessageSize: 1024 * 1024,
199
    keepalive: true
200
};
201

202
// Extend with user configuration
203
function createServerConfig(userConfig) {
204
    return utils.extend({}, utils.extend(defaultConfig, userConfig || {}));
205
}
206

207
const config = createServerConfig({
208
    keepalive: false,
209
    customOption: 'value'
210
});
211

212
const wsServer = new WebSocket.server(config);
213
```
214

215
**Cross-Version Compatibility:**
216

217
```javascript
218
const WebSocket = require('websocket');
219
const utils = require('websocket/lib/utils');
220

221
// Handle different Node.js versions
222
function createBuffer(size) {
223
    // Uses appropriate buffer allocation method for the Node.js version
224
    return utils.bufferAllocUnsafe(size);
225
}
226

227
function stringToBuffer(str) {
228
    // Uses appropriate string to buffer conversion
229
    return utils.bufferFromString(str, 'utf8');
230
}
231

232
// Event listener management across Node.js versions
233
function getListenerCount(emitter, eventType) {
234
    return utils.eventEmitterListenerCount(emitter, eventType);
235
}
236
```
237

238
## Types
239

240
### Deprecation Configuration
241

242
```javascript { .api }
243
interface DeprecationConfig {
244
    disableWarnings: boolean;
245
    deprecationWarningMap: {
246
        [key: string]: string;
247
    };
248
}
249
```
250

251
### Utility Types
252

253
```javascript { .api }
254
interface BufferingLoggerFunction {
255
    (message: string): void;
256
    dump(): string[];
257
    clear(): void;
258
}
259
```