0
# Path Browserify
1

2
Path Browserify provides a browser-compatible implementation of Node.js's core `path` module, enabling POSIX-style path manipulation utilities in browser environments. It implements the complete Node.js 10.3 path API, allowing developers to use familiar path operations like join, resolve, normalize, dirname, and basename in client-side applications.
3

4
## Package Information
5

6
- **Package Name**: path-browserify
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install path-browserify`
10

11
## Core Imports
12

13
```javascript
14
const path = require('path-browserify');
15
```
16

17
For ES modules (if supported by bundler):
18

19
```javascript
20
import path from 'path-browserify';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const path = require('path-browserify');
27

28
// Join path segments
29
const fullPath = path.join('/users', 'john', 'documents', 'file.txt');
30
// Result: '/users/john/documents/file.txt'
31

32
// Resolve absolute path
33
const absolutePath = path.resolve('../docs', 'readme.md');
34
// Result: absolute path based on current working directory
35

36
// Extract components
37
const filename = path.basename('/home/user/document.pdf');
38
// Result: 'document.pdf'
39

40
const directory = path.dirname('/home/user/document.pdf');
41
// Result: '/home/user'
42

43
const extension = path.extname('/home/user/document.pdf');
44
// Result: '.pdf'
45
```
46

47
## Architecture
48

49
Path Browserify is a faithful port of Node.js's POSIX path module, implementing:
50

51
- **POSIX-only operations**: No Windows-specific path handling (uses forward slashes)
52
- **Pure functions**: Stateless path manipulation without side effects  
53
- **Error validation**: Type checking with TypeError for invalid inputs
54
- **Browser compatibility**: No Node.js-specific dependencies, works in all browsers
55
- **Bundler integration**: Automatic substitution by tools like Browserify and Webpack
56

57
## Capabilities
58

59
### Path Resolution
60

61
Resolves path segments into absolute paths, handling relative references and normalization.
62

63
```javascript { .api }
64
/**
65
 * Resolves a sequence of paths or path segments into an absolute path
66
 * @param {...string} paths - Path segments to resolve
67
 * @returns {string} Resolved absolute path
68
 * @throws {TypeError} If any argument is not a string
69
 */
70
function resolve(...paths: string[]): string;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
// Resolve from current directory
77
path.resolve('docs', 'readme.md');
78
// Result: '/current/working/dir/docs/readme.md'
79

80
// Resolve with absolute path
81
path.resolve('/home', 'user', '../shared', 'file.txt');
82
// Result: '/home/shared/file.txt'
83

84
// Multiple relative segments
85
path.resolve('..', 'project', './src/index.js');
86
// Result: '/parent/dir/project/src/index.js'
87
```
88

89
### Path Normalization
90

91
Normalizes paths by resolving `.` and `..` segments and removing redundant separators.
92

93
```javascript { .api }
94
/**
95
 * Normalizes a path, resolving '..' and '.' segments
96
 * @param {string} path - Path to normalize
97
 * @returns {string} Normalized path
98
 * @throws {TypeError} If path is not a string
99
 */
100
function normalize(path: string): string;
101
```
102

103
**Usage Examples:**
104

105
```javascript
106
path.normalize('/foo/bar//baz/asdf/quux/..');
107
// Result: '/foo/bar/baz/asdf'
108

109
path.normalize('./foo/../bar/./baz');
110
// Result: 'bar/baz'
111

112
path.normalize('/foo/bar/../');
113
// Result: '/foo/'
114
```
115

116
### Path Joining
117

118
Joins path segments using the platform separator and normalizes the result.
119

120
```javascript { .api }
121
/**
122
 * Joins multiple path segments together using the platform separator
123
 * @param {...string} paths - Path segments to join
124
 * @returns {string} Joined and normalized path
125
 * @throws {TypeError} If any argument is not a string
126
 */
127
function join(...paths: string[]): string;
128
```
129

130
**Usage Examples:**
131

132
```javascript
133
path.join('/users', 'john', 'documents');
134
// Result: '/users/john/documents'
135

136
path.join('project', 'src', '..', 'tests', 'unit.js');
137
// Result: 'project/tests/unit.js'
138

139
path.join('/root', '', 'subdir');
140
// Result: '/root/subdir'
141
```
142

143
### Relative Path Calculation
144

145
Calculates the relative path from one location to another.
146

147
```javascript { .api }
148
/**
149
 * Returns the relative path from 'from' to 'to'
150
 * @param {string} from - Source path
151
 * @param {string} to - Target path
152
 * @returns {string} Relative path from source to target
153
 * @throws {TypeError} If either argument is not a string
154
 */
155
function relative(from: string, to: string): string;
156
```
157

158
**Usage Examples:**
159

160
```javascript
161
path.relative('/home/user/documents', '/home/user/pictures');
162
// Result: '../pictures'
163

164
path.relative('/var/www', '/var/www/html/index.html');
165
// Result: 'html/index.html'
166

167
path.relative('/home/user', '/home/user');
168
// Result: ''
169
```
170

171
### Absolute Path Detection
172

173
Determines whether a path is absolute.
174

175
```javascript { .api }
176
/**
177
 * Determines if a path is absolute
178
 * @param {string} path - Path to test
179
 * @returns {boolean} True if path is absolute, false otherwise
180
 * @throws {TypeError} If path is not a string
181
 */
182
function isAbsolute(path: string): boolean;
183
```
184

185
**Usage Examples:**
186

187
```javascript
188
path.isAbsolute('/home/user');
189
// Result: true
190

191
path.isAbsolute('relative/path');
192
// Result: false
193

194
path.isAbsolute('./current/dir');
195
// Result: false
196
```
197

198
### Directory Name Extraction
199

200
Returns the directory portion of a path.
201

202
```javascript { .api }
203
/**
204
 * Returns the directory name of a path
205
 * @param {string} path - Path to extract directory from
206
 * @returns {string} Directory portion of the path
207
 * @throws {TypeError} If path is not a string
208
 */
209
function dirname(path: string): string;
210
```
211

212
**Usage Examples:**
213

214
```javascript
215
path.dirname('/home/user/documents/file.txt');
216
// Result: '/home/user/documents'
217

218
path.dirname('relative/path/file.js');
219
// Result: 'relative/path'
220

221
path.dirname('/single');
222
// Result: '/'
223
```
224

225
### Base Name Extraction
226

227
Returns the last portion of a path, optionally removing a specified extension.
228

229
```javascript { .api }
230
/**
231
 * Returns the last portion of a path, optionally removing extension
232
 * @param {string} path - Path to extract basename from
233
 * @param {string} [ext] - Extension to remove from result
234
 * @returns {string} Base name of the path
235
 * @throws {TypeError} If path is not a string or ext is not a string
236
 */
237
function basename(path: string, ext?: string): string;
238
```
239

240
**Usage Examples:**
241

242
```javascript
243
path.basename('/home/user/documents/file.txt');
244
// Result: 'file.txt'
245

246
path.basename('/home/user/documents/file.txt', '.txt');
247
// Result: 'file'
248

249
path.basename('relative/path/script.js', '.js');
250
// Result: 'script'
251
```
252

253
### File Extension Extraction
254

255
Returns the extension portion of a path, including the leading dot.
256

257
```javascript { .api }
258
/**
259
 * Returns the extension of a path, including the leading dot
260
 * @param {string} path - Path to extract extension from
261
 * @returns {string} File extension including dot, or empty string if no extension
262
 * @throws {TypeError} If path is not a string
263
 */
264
function extname(path: string): string;
265
```
266

267
**Usage Examples:**
268

269
```javascript
270
path.extname('/home/user/file.txt');
271
// Result: '.txt'
272

273
path.extname('script.min.js');
274
// Result: '.js'
275

276
path.extname('README');
277
// Result: ''
278
```
279

280
### Path Object Formatting
281

282
Formats a path object into a path string.
283

284
```javascript { .api }
285
/**
286
 * Returns a path string from a path object
287
 * @param {PathObject} pathObject - Object with path components
288
 * @returns {string} Formatted path string
289
 * @throws {TypeError} If pathObject is not an object
290
 */
291
function format(pathObject: PathObject): string;
292

293
interface PathObject {
294
  /** Root portion of path (e.g., '/' or '') */
295
  root?: string;
296
  /** Directory portion of path */
297
  dir?: string;
298
  /** Complete filename including extension */
299
  base?: string;
300
  /** Filename without extension */
301
  name?: string;
302
  /** File extension including dot */
303
  ext?: string;
304
}
305
```
306

307
**Usage Examples:**
308

309
```javascript
310
path.format({
311
  root: '/',
312
  dir: '/home/user',
313
  base: 'file.txt'
314
});
315
// Result: '/home/user/file.txt'
316

317
path.format({
318
  name: 'document',
319
  ext: '.pdf'
320
});
321
// Result: 'document.pdf'
322
```
323

324
### Path Object Parsing
325

326
Parses a path string into a path object with individual components.
327

328
```javascript { .api }
329
/**
330
 * Returns an object with path components from a path string
331
 * @param {string} path - Path string to parse
332
 * @returns {PathObject} Object with path components
333
 * @throws {TypeError} If path is not a string
334
 */
335
function parse(path: string): PathObject;
336
```
337

338
**Usage Examples:**
339

340
```javascript
341
path.parse('/home/user/documents/file.txt');
342
/* Result: {
343
  root: '/',
344
  dir: '/home/user/documents',
345
  base: 'file.txt',
346
  ext: '.txt',
347
  name: 'file'
348
} */
349

350
path.parse('relative/path/script.js');
351
/* Result: {
352
  root: '',
353
  dir: 'relative/path',
354
  base: 'script.js',
355
  ext: '.js',
356
  name: 'script'
357
} */
358
```
359

360
### Path Long Name Helper (Legacy)
361

362
Internal legacy function that returns the path unchanged. Exists for Node.js compatibility.
363

364
```javascript { .api }
365
/**
366
 * Internal legacy function, returns path unchanged
367
 * @param {string} path - Path to process
368
 * @returns {string} Unchanged path
369
 * @deprecated Legacy function for Node.js compatibility
370
 */
371
function _makeLong(path: string): string;
372
```
373

374
## Constants
375

376
### Platform Separator
377

378
```javascript { .api }
379
/** Platform-specific path segment separator (always '/' in POSIX) */
380
const sep: '/';
381
```
382

383
### Path Delimiter
384

385
```javascript { .api }
386
/** Platform-specific path delimiter for PATH environment variable (always ':' in POSIX) */
387
const delimiter: ':';
388
```
389

390
## Legacy Properties
391

392
### POSIX Reference
393

394
```javascript { .api }
395
/** Reference to the POSIX path utilities (same as main object) */
396
const posix: PathModule;
397
```
398

399
### Windows Reference
400

401
```javascript { .api }
402
/** Windows path utilities (null in browser version) */
403
const win32: null;
404
```
405

406
## Error Handling
407

408
All path manipulation functions validate their string inputs and throw `TypeError` with descriptive messages for invalid arguments:
409

410
```javascript
411
// TypeError: Path must be a string. Received number
412
path.join('/path', 123);
413

414
// TypeError: The "pathObject" argument must be of type Object. Received type string  
415
path.format('/invalid/argument');
416
```
417

418
## Browser Compatibility
419

420
Path Browserify works in all modern browsers and is automatically included by bundlers when Node.js `path` module is required in browser-targeted code. It has zero runtime dependencies and provides identical behavior to Node.js path module for POSIX operations.