0
# File Utilities
1

2
Comprehensive file system utilities for path manipulation, globbing, and cross-platform compatibility in TypeChain operations.
3

4
## Capabilities
5

6
### File Pattern Matching
7

8
#### glob Function
9

10
File globbing utility that resolves patterns to file paths.
11

12
```typescript { .api }
13
/**
14
 * File globbing utility that resolves patterns to file paths
15
 * @param cwd - Current working directory for pattern resolution
16
 * @param patternsOrFiles - Array of glob patterns or specific file paths
17
 * @param ignoreNodeModules - Whether to ignore node_modules directory (default: true)
18
 * @returns Array of resolved file paths matching the patterns
19
 */
20
function glob(cwd: string, patternsOrFiles: string[], ignoreNodeModules?: boolean): string[];
21
```
22

23
**Usage Example:**
24

25
```typescript
26
import { glob } from "typechain";
27

28
// Find all JSON files in artifacts directory
29
const files = glob(process.cwd(), ["./artifacts/**/*.json"]);
30
// Result: ["/path/to/artifacts/Contract1.json", "/path/to/artifacts/Contract2.json", ...]
31

32
// Multiple patterns
33
const abiFiles = glob(process.cwd(), [
34
  "./artifacts/**/*.json",
35
  "./contracts/**/*.abi",
36
  "./build/**/*.json"
37
]);
38

39
// Include node_modules (normally ignored)
40
const allFiles = glob(process.cwd(), ["**/*.json"], false);
41
```
42

43
### Path Manipulation
44

45
#### detectInputsRoot Function
46

47
Detects the root directory for input files by finding the common path.
48

49
```typescript { .api }
50
/**
51
 * Detects the root directory for input files by finding the common path
52
 * @param allFiles - Array of all input file paths
53
 * @returns Common root directory path for all input files
54
 */
55
function detectInputsRoot(allFiles: string[]): string;
56
```
57

58
#### ensureAbsPath Function
59

60
Ensures path is absolute, converting relative paths using current working directory.
61

62
```typescript { .api }
63
/**
64
 * Ensures path is absolute, converting relative paths using current working directory
65
 * @param path - File or directory path that may be relative or absolute
66
 * @returns Absolute path
67
 */
68
function ensureAbsPath(path: string): string;
69
```
70

71
#### lowestCommonPath Function
72

73
Finds lowest common path among multiple paths.
74

75
```typescript { .api }
76
/**
77
 * Finds lowest common path among multiple paths
78
 * @param paths - Array of file or directory paths
79
 * @returns Lowest common directory path shared by all inputs
80
 */
81
function lowestCommonPath(paths: string[]): string;
82
```
83

84
**Usage Example:**
85

86
```typescript
87
import { detectInputsRoot, lowestCommonPath, ensureAbsPath } from "typechain";
88

89
const files = [
90
  "./artifacts/contracts/MyToken.sol/MyToken.json",
91
  "./artifacts/contracts/MyNFT.sol/MyNFT.json",
92
  "./artifacts/contracts/governance/Governor.sol/Governor.json"
93
];
94

95
const inputRoot = detectInputsRoot(files);
96
// Result: "./artifacts/contracts"
97

98
const commonPath = lowestCommonPath(files);
99
// Result: "./artifacts/contracts"
100

101
const absolutePath = ensureAbsPath("./artifacts");
102
// Result: "/full/path/to/project/artifacts"
103
```
104

105
### File Name Processing
106

107
#### getFileExtension Function
108

109
Gets file extension from path.
110

111
```typescript { .api }
112
/**
113
 * Gets file extension from path
114
 * @param path - File path
115
 * @returns File extension including the dot (e.g., ".json", ".abi")
116
 */
117
function getFileExtension(path: string): string;
118
```
119

120
#### getFilename Function
121

122
Gets filename without extension from path.
123

124
```typescript { .api }
125
/**
126
 * Gets filename without extension from path
127
 * @param path - File path
128
 * @returns Filename without directory path and extension
129
 */
130
function getFilename(path: string): string;
131
```
132

133
#### normalizeName Function
134

135
Converts valid file names to valid JavaScript symbols.
136

137
```typescript { .api }
138
/**
139
 * Converts valid file names to valid JavaScript symbols
140
 * Handles cases like "ds-token.test" becoming "DsTokenTest"
141
 * @param rawName - Original file name or contract name
142
 * @returns Valid JavaScript identifier in PascalCase
143
 */
144
function normalizeName(rawName: string): string;
145
```
146

147
**Usage Example:**
148

149
```typescript
150
import { getFileExtension, getFilename, normalizeName } from "typechain";
151

152
const path = "./contracts/my-token.test.sol/MyToken.json";
153

154
const extension = getFileExtension(path);
155
// Result: ".json"
156

157
const filename = getFilename(path);
158
// Result: "MyToken"
159

160
const normalized = normalizeName("ds-token.test");
161
// Result: "DsTokenTest"
162

163
const normalizedContract = normalizeName("0x-exchange");
164
// Result: "_0xExchange"
165
```
166

167
### Path Normalization
168

169
#### normalizeSlashes Function
170

171
Normalizes path slashes for cross-platform compatibility.
172

173
```typescript { .api }
174
/**
175
 * Normalizes path slashes for cross-platform compatibility
176
 * Converts backslashes to forward slashes and handles double slashes
177
 * @param path - File or directory path with potentially mixed slashes
178
 * @returns Normalized path with consistent forward slashes
179
 */
180
function normalizeSlashes(path: string): string;
181
```
182

183
#### shortenFullJsonFilePath Function
184

185
Shortens full JSON file paths by removing redundant contract name directories.
186

187
```typescript { .api }
188
/**
189
 * Shortens full JSON file paths by removing redundant contract name directories
190
 * Handles Hardhat's nested directory structure like "Contract.sol/Contract.json"
191
 * @param path - Full file path that may contain redundant directories
192
 * @param allPaths - All file paths for context in shortening decisions
193
 * @returns Shortened path with redundant directories removed
194
 */
195
function shortenFullJsonFilePath(path: string, allPaths: string[]): string;
196
```
197

198
**Usage Example:**
199

200
```typescript
201
import { normalizeSlashes, shortenFullJsonFilePath } from "typechain";
202

203
// Cross-platform path normalization
204
const windowsPath = "contracts\\MyToken.sol\\MyToken.json";
205
const normalized = normalizeSlashes(windowsPath);
206
// Result: "contracts/MyToken.sol/MyToken.json"
207

208
// Shorten Hardhat-style paths
209
const fullPaths = [
210
  "./artifacts/contracts/MyToken.sol/MyToken.json",
211
  "./artifacts/contracts/MyNFT.sol/MyNFT.json"
212
];
213

214
const shortened = shortenFullJsonFilePath(
215
  "./artifacts/contracts/MyToken.sol/MyToken.json",
216
  fullPaths
217
);
218
// Result: "./artifacts/contracts/MyToken.json" (removes redundant .sol directory)
219
```
220

221
### Signature Utilities
222

223
Functions for generating contract function and event signatures:
224

225
```typescript { .api }
226
/**
227
 * Get the signature for a function declaration
228
 * @param fn - Function declaration with name and inputs
229
 * @returns Function signature string like "transfer(address,uint256)"
230
 */
231
function getSignatureForFn(fn: FunctionDeclaration): string;
232

233
/**
234
 * Get the full signature as symbol for event declaration
235
 * @param event - Event declaration with name and inputs
236
 * @returns Event signature symbol for use as identifier
237
 */
238
function getFullSignatureAsSymbolForEvent(event: EventDeclaration): string;
239

240
/**
241
 * Get the full signature for event declaration
242
 * @param event - Event declaration with name and inputs
243
 * @returns Event signature string like "Transfer(address,address,uint256)"
244
 */
245
function getFullSignatureForEvent(event: EventDeclaration): string;
246

247
/**
248
 * Get the indexed signature for event declaration
249
 * @param event - Event declaration with name and inputs
250
 * @returns Indexed event signature with only indexed parameters
251
 */
252
function getIndexedSignatureForEvent(event: EventDeclaration): string;
253

254
/**
255
 * Get argument representation for signature generation
256
 * @param argument - Event argument or ABI parameter
257
 * @returns String representation of the argument type for signatures
258
 */
259
function getArgumentForSignature(argument: EventArgDeclaration | AbiParameter): string;
260
```
261

262
**Usage Example:**
263

264
```typescript
265
import { 
266
  getSignatureForFn, 
267
  getFullSignatureForEvent,
268
  getIndexedSignatureForEvent,
269
  getFullSignatureAsSymbolForEvent 
270
} from "typechain";
271

272
// Function signature generation
273
const transferFn = {
274
  name: "transfer",
275
  inputs: [
276
    { name: "to", type: { originalType: "address" } },
277
    { name: "amount", type: { originalType: "uint256" } }
278
  ]
279
};
280

281
const fnSignature = getSignatureForFn(transferFn);
282
// Result: "transfer(address,uint256)"
283

284
// Event signature generation
285
const transferEvent = {
286
  name: "Transfer",
287
  inputs: [
288
    { name: "from", type: { originalType: "address" }, isIndexed: true },
289
    { name: "to", type: { originalType: "address" }, isIndexed: true },
290
    { name: "value", type: { originalType: "uint256" }, isIndexed: false }
291
  ]
292
};
293

294
const eventSignature = getFullSignatureForEvent(transferEvent);
295
// Result: "Transfer(address,address,uint256)"
296

297
const indexedSignature = getIndexedSignatureForEvent(transferEvent);
298
// Result: "Transfer(address,address)"
299

300
const symbolSignature = getFullSignatureAsSymbolForEvent(transferEvent);
301
// Result: "Transfer_address_address_uint256"
302
```