0
# Utility Functions
1

2
Source map manipulation and path handling utilities for advanced declaration file processing and development tooling integration.
3

4
## Capabilities
5

6
### Source Map Directory Editing
7

8
Utility function for modifying source map directory references when declaration files are output to different directories.
9

10
```typescript { .api }
11
/**
12
 * Edit source map directory references to maintain correct paths
13
 * @param content - Source map content as JSON string
14
 * @param fromDir - Original source directory path
15
 * @param toDir - Target destination directory path
16
 * @returns Modified source map content, true if no change needed, or false if parsing fails
17
 */
18
function editSourceMapDir(content: string, fromDir: string, toDir: string): string | boolean;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { editSourceMapDir } from "vite-plugin-dts";
25

26
// Edit source map when moving files between directories
27
const sourceMapContent = JSON.stringify({
28
  version: 3,
29
  sources: ["../src/index.ts", "../src/utils.ts"],
30
  mappings: "AAAA,..."
31
});
32

33
const updatedSourceMap = editSourceMapDir(
34
  sourceMapContent,
35
  "/project/src",
36
  "/project/dist/types"
37
);
38

39
if (updatedSourceMap && typeof updatedSourceMap === 'string') {
40
  // Source map successfully updated
41
  const parsedMap = JSON.parse(updatedSourceMap);
42
  console.log(parsedMap.sources); // Updated relative paths
43
} else {
44
  console.error("Failed to update source map");
45
}
46

47
// Using in beforeWriteFile hook
48
dts({
49
  beforeWriteFile: async (filePath, content) => {
50
    if (filePath.endsWith('.d.ts.map')) {
51
      const result = editSourceMapDir(content, 'src', 'dist/types');
52
      if (typeof result === 'string') {
53
        return { content: result };
54
      }
55
    }
56
  }
57
});
58
```
59

60
**Note:** The `editSourceMapDir` function is the only public utility function exported by the plugin. All other utilities are internal implementation details and are not part of the public API.
61

62
### Source Map Structure
63

64
When working with source maps, the plugin handles the following structure:
65

66
```typescript { .api }
67
interface SourceMapData {
68
  version: number;
69
  sources: string[];
70
  mappings: string;
71
  names?: string[];
72
  sourceRoot?: string;
73
  sourcesContent?: (string | null)[];
74
}
75
```
76

77
**Usage in Plugin Context:**
78

79
```typescript
80
// Example of source map processing within the plugin
81
dts({
82
  afterBuild: async (emittedFiles) => {
83
    for (const [filePath, content] of emittedFiles) {
84
      if (filePath.endsWith('.d.ts.map')) {
85
        try {
86
          const sourceMap: SourceMapData = JSON.parse(content);
87
          console.log(`Source map for ${filePath}:`);
88
          console.log(`- Sources: ${sourceMap.sources.length}`);
89
          console.log(`- Mappings length: ${sourceMap.mappings.length}`);
90
        } catch (error) {
91
          console.warn(`Invalid source map in ${filePath}`);
92
        }
93
      }
94
    }
95
  }
96
});
97
```
98

99
### Path Resolution Examples
100

101
Common patterns for working with paths in plugin configuration and utilities:
102

103
```typescript
104
// Normalize paths across platforms
105
const normalizedPath = normalizePath("/path\\to\\file"); // "/path/to/file"
106

107
// Ensure absolute paths
108
const absolutePath = ensureAbsolute("./src", "/project"); // "/project/src"
109

110
// Work with arrays consistently
111
const fileList = ensureArray("single-file.ts"); // ["single-file.ts"]
112
const multipleFiles = ensureArray(["file1.ts", "file2.ts"]); // ["file1.ts", "file2.ts"]
113

114
// Convert TypeScript paths to Vite aliases
115
const aliases = parseTsAliases("/project/src", {
116
  "@/*": ["./src/*"],
117
  "@utils/*": ["./src/utils/*"]
118
});
119
```