0
# Utility Functions
1

2
Core utility functions for package management, validation, data processing, and system operations.
3

4
## Capabilities
5

6
### Validation Utilities
7

8
Object and data validation functions for type checking and data integrity.
9

10
```typescript { .api }
11
/**
12
 * Check whether an element is an Object
13
 * @param obj - The element to check
14
 * @returns Boolean indicating if element is an object
15
 */
16
function isObject(obj: any): boolean;
17

18
/**
19
 * Check whether an element is an Object or Array (deprecated)
20
 * @param obj - The element to check
21
 * @returns Boolean indicating if element is object or array
22
 */
23
function isObjectOrArray(obj: any): boolean;
24

25
/**
26
 * Check whether the path already exists as a directory
27
 * @param path - Directory path to check
28
 * @returns Boolean indicating if directory exists
29
 */
30
function folderExists(path: string): boolean;
31

32
/**
33
 * Check whether the path already exists as a file
34
 * @param path - File path to check
35
 * @returns Boolean indicating if file exists
36
 */
37
function fileExists(path: string): boolean;
38
```
39

40
### Package Version Management
41

42
Utilities for handling semantic versioning and package metadata.
43

44
```typescript { .api }
45
/**
46
 * Tag a package version with a distribution tag
47
 * @param data - Package manifest data
48
 * @param version - Version string to tag
49
 * @param tag - Distribution tag name (e.g., 'latest', 'beta')
50
 * @returns Boolean indicating if tagging was successful
51
 */
52
function tagVersion(data: Manifest, version: string, tag: string): boolean;
53

54
/**
55
 * Get version object from package metadata with semver handling
56
 * @param pkg - Package manifest
57
 * @param version - Version string or semver range
58
 * @returns Version object or undefined if not found
59
 */
60
function getVersion(pkg: Manifest, version: any): Version | void;
61

62
/**
63
 * Sort version strings using semantic versioning rules
64
 * @param listVersions - Array of version strings
65
 * @returns Sorted array of valid version strings
66
 */
67
function semverSort(listVersions: string[]): string[];
68

69
/**
70
 * Normalize distribution tags in package manifest
71
 * @param pkg - Package manifest to normalize
72
 */
73
function normalizeDistTags(pkg: Manifest): void;
74

75
/**
76
 * Check if package version is valid and exists in metadata
77
 * @param packageMeta - Package metadata object
78
 * @param packageVersion - Version string to validate
79
 * @returns Boolean indicating if version is valid and exists
80
 */
81
function isVersionValid(packageMeta: any, packageVersion: any): boolean;
82

83
/**
84
 * Check if package has any deprecated versions
85
 * @param pkgInfo - Package manifest
86
 * @returns Boolean indicating if any version is deprecated
87
 */
88
function isRelatedToDeprecation(pkgInfo: Manifest): boolean;
89
```
90

91
### Network and Address Parsing
92

93
URL and network address parsing utilities with support for various protocols.
94

95
```typescript { .api }
96
/**
97
 * Parse internet address with protocol, host, and port detection
98
 * Supports: https:localhost:1234, localhost:1234, 1234, http::1234,
99
 * https://localhost:443/, http://[::1]:443/, unix:/tmp/http.sock
100
 * @param urlAddress - Address string to parse
101
 * @returns Parsed address object or null if invalid
102
 */
103
function parseAddress(urlAddress: any): {
104
  proto: string;
105
  host?: string;
106
  port?: number;
107
  path?: string;
108
} | null;
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
// Parse various address formats
115
parseAddress("https://localhost:4873");
116
// { proto: "https", host: "localhost", port: 4873 }
117

118
parseAddress("localhost:4873");
119
// { proto: "http", host: "localhost", port: 4873 }
120

121
parseAddress("4873");
122
// { proto: "http", host: "localhost", port: 4873 }
123

124
parseAddress("unix:/tmp/verdaccio.sock");
125
// { proto: "http", path: "/tmp/verdaccio.sock" }
126
```
127

128
### Time and Interval Parsing
129

130
Parse time interval strings with unit support.
131

132
```typescript { .api }
133
/**
134
 * Parse time interval string to milliseconds
135
 * Supports units: ms, s, m, h, d, w, M, y
136
 * @param interval - Interval string (e.g., "5m", "2h 30m", "1d")
137
 * @returns Interval in milliseconds
138
 * @throws Error for invalid interval format
139
 */
140
function parseInterval(interval: any): number;
141
```
142

143
**Usage Examples:**
144

145
```typescript
146
parseInterval("5m");        // 300000 (5 minutes)
147
parseInterval("2h 30m");    // 9000000 (2.5 hours)
148
parseInterval("1d");        // 86400000 (1 day)
149
parseInterval(3600);        // 3600000 (1 hour from number)
150
```
151

152
### Data Processing Utilities
153

154
General data manipulation and formatting utilities.
155

156
```typescript { .api }
157
/**
158
 * Sort packages by name with optional direction
159
 * @param packages - Array of package objects with name property
160
 * @param orderAscending - Sort direction (true for ascending)
161
 * @returns Sorted array of packages
162
 */
163
function sortByName(packages: any[], orderAscending?: boolean): string[];
164

165
/**
166
 * Add npm scope prefix to package name
167
 * @param scope - Scope name (without @)
168
 * @param packageName - Package name
169
 * @returns Scoped package name (@scope/packageName)
170
 */
171
function addScope(scope: string, packageName: string): string;
172

173
/**
174
 * Remove specified properties from object
175
 * @param propertiesToDelete - Array of property names to remove
176
 * @param objectItem - Object to modify
177
 * @returns Modified object with properties removed
178
 */
179
function deleteProperties(propertiesToDelete: string[], objectItem: any): any;
180

181
/**
182
 * Create masked string for sensitive data display
183
 * @param str - String to mask
184
 * @param charNum - Number of characters to show at start/end
185
 * @returns Masked string (e.g., "abc...xyz")
186
 */
187
function mask(str: string, charNum?: number): string;
188

189
/**
190
 * URL-encode scoped package names for URI usage
191
 * @param packageName - Package name (may include scope)
192
 * @returns URL-encoded package name
193
 */
194
function encodeScopedUri(packageName: string): string;
195

196
/**
197
 * Check if versions object has more than one key
198
 * @param versions - Versions object to check
199
 * @returns Boolean indicating if multiple versions exist
200
 */
201
function hasDiffOneKey(versions: any): boolean;
202
```
203

204
### README Processing
205

206
Package README file processing and validation utilities.
207

208
```typescript { .api }
209
/**
210
 * Process package README content with fallback handling
211
 * @param packageName - Package name for logging
212
 * @param readme - README content string
213
 * @returns Processed README content or error message
214
 */
215
function parseReadme(packageName: string, readme: string): string | void;
216
```
217

218
### Error Handling Utilities
219

220
Standardized error creation and handling functions.
221

222
```typescript { .api }
223
/**
224
 * Collection of error factory functions for HTTP responses
225
 */
226
const ErrorCode: {
227
  getConflict(message?: string): Error;
228
  getBadData(message?: string): Error;
229
  getBadRequest(message?: string): Error;
230
  getInternalError(message?: string): Error;
231
  getUnauthorized(message?: string): Error;
232
  getForbidden(message?: string): Error;
233
  getServiceUnavailable(message?: string): Error;
234
  getNotFound(message?: string): Error;
235
  getCode(code: number, message?: string): Error;
236
};
237
```
238

239
**Usage Examples:**
240

241
```typescript
242
// Create standardized errors
243
throw ErrorCode.getNotFound("Package not found");
244
throw ErrorCode.getUnauthorized("Authentication required");
245
throw ErrorCode.getBadRequest("Invalid package data");
246
```
247

248
### Additional Utility Functions
249

250
Additional helper functions for package validation and data processing.
251

252
```typescript { .api }
253
/**
254
 * Check if package version is valid and exists in metadata
255
 * @param packageMeta - Package metadata object
256
 * @param packageVersion - Version string to validate
257
 * @returns Boolean indicating if version is valid and exists
258
 */
259
function isVersionValid(packageMeta: any, packageVersion: any): boolean;
260

261
/**
262
 * Check if package has any deprecated versions
263
 * @param pkgInfo - Package manifest
264
 * @returns Boolean indicating if any version is deprecated
265
 */
266
function isRelatedToDeprecation(pkgInfo: Manifest): boolean;
267

268
/**
269
 * Check if login functionality is enabled in configuration
270
 * @param config - Verdaccio configuration object
271
 * @returns Boolean indicating if login is enabled
272
 */
273
function hasLogin(config: Config): boolean;
274

275
/**
276
 * Build authentication token utility (re-exported from @verdaccio/utils)
277
 * @param token - Token data
278
 * @returns Built token string
279
 */
280
function buildToken(token: any): string;
281
```
282

283
## Type Definitions
284

285
```typescript { .api }
286
interface Manifest {
287
  name: string;
288
  versions: { [version: string]: Version };
289
  "dist-tags": { [tag: string]: string };
290
  [key: string]: any;
291
}
292

293
interface Version {
294
  name: string;
295
  version: string;
296
  description?: string;
297
  main?: string;
298
  dependencies?: { [name: string]: string };
299
  devDependencies?: { [name: string]: string };
300
  [key: string]: any;
301
}
302

303
interface Config {
304
  storage: string;
305
  auth?: any;
306
  uplinks?: { [name: string]: any };
307
  packages?: { [pattern: string]: any };
308
  web?: {
309
    login?: boolean;
310
    [key: string]: any;
311
  };
312
  [key: string]: any;
313
}
314
```
315

316
## Constants
317

318
Key constants used throughout the utility functions:
319

320
- `DEFAULT_DOMAIN`: "localhost"
321
- `DEFAULT_PORT`: 4873  
322
- `DEFAULT_PROTOCOL`: "http"
323
- `DIST_TAGS`: "dist-tags"
324

325
These utilities form the foundation for Verdaccio's package management, configuration handling, and data processing capabilities.