0
# Replace Ext
1

2
Replace Ext is a lightweight utility function that replaces file extensions in path strings while preserving directory structure and handling cross-platform path separators. It's designed for build tools, file processing utilities, and applications that need to transform file paths by changing their extensions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const replaceExt = require('replace-ext');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const replaceExt = require('replace-ext');
21

22
// Replace extension in a simple filename
23
const newPath = replaceExt('file.js', '.ts');
24
console.log(newPath); // file.ts
25

26
// Replace extension in a full path
27
const fullPath = replaceExt('/some/dir/file.coffee', '.js');
28
console.log(fullPath); // /some/dir/file.js
29

30
// Remove extension entirely
31
const noExt = replaceExt('document.pdf', '');
32
console.log(noExt); // document
33

34
// Preserves relative path structure
35
const relativePath = replaceExt('./src/index.js', '.ts');
36
console.log(relativePath); // ./src/index.ts
37
```
38

39
## Capabilities
40

41
### File Extension Replacement
42

43
Replaces the file extension in a path string with a new extension while preserving directory structure and handling edge cases.
44

45
```javascript { .api }
46
/**
47
 * Replaces the extension from npath with ext and returns the updated path string.
48
 * Does not replace the extension if npath is not a string or is empty.
49
 * 
50
 * @param {string} npath - The file path whose extension should be replaced
51
 * @param {string} ext - The new extension (including the dot, e.g., '.js')
52
 * @returns {string|*} The path with the new extension, or original input if not a string
53
 */
54
function replaceExt(npath, ext);
55
```
56

57
**Key Features:**
58

59
- **Cross-platform compatibility**: Uses Node.js path module for proper path separator handling
60
- **Relative path preservation**: Maintains leading `./` and `../` in relative paths 
61
- **Safe input handling**: Returns input unchanged if not a string or empty string
62
- **Extension removal**: Pass empty string as extension to remove file extension entirely
63
- **Directory preservation**: Maintains full directory structure in the output path
64

65
**Usage Examples:**
66

67
```javascript
68
const replaceExt = require('replace-ext');
69

70
// Basic extension replacement
71
replaceExt('test.coffee', '.js');           // 'test.js'
72
replaceExt('/path/to/file.ts', '.js');      // '/path/to/file.js'
73

74
// Extension removal
75
replaceExt('document.pdf', '');             // 'document'
76
replaceExt('/docs/readme.md', '');          // '/docs/readme'
77

78
// Adding extension to extensionless file
79
replaceExt('/path/to/file', '.txt');        // '/path/to/file.txt'
80

81
// Relative path handling
82
replaceExt('./src/index.js', '.ts');        // './src/index.ts'
83
replaceExt('../lib/util.coffee', '.js');    // '../lib/util.js'
84

85
// Safe input handling
86
replaceExt(null, '.js');                    // null (unchanged)
87
replaceExt('', '.js');                      // '' (unchanged)
88
replaceExt({}, '.js');                      // {} (unchanged)
89
```
90

91
**Cross-platform Behavior:**
92

93
The function handles path separators correctly across different operating systems:
94

95
```javascript
96
// On Windows
97
replaceExt('a\\b\\c.js', '.ts');           // 'a\\b\\c.ts'
98
replaceExt('.\\a\\b\\c.js', '.ts');        // '.\\a\\b\\c.ts'
99

100
// On Unix/Linux/macOS  
101
replaceExt('a/b/c.js', '.ts');             // 'a/b/c.ts'
102
replaceExt('./a/b/c.js', '.ts');           // './a/b/c.ts'
103
```