@nojaja/dirwalker 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +181 -547
- package/package.json +69 -69
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 nojaja
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 nojaja
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,547 +1,181 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
- Node.js 18
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
| `targetPath
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
type
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
-
|
|
172
|
-
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
- `
|
|
182
|
-
- `patterns` - Array of RegExp patterns to match against
|
|
183
|
-
|
|
184
|
-
**Returns:** The matching RegExp object or `null` if no match found
|
|
185
|
-
|
|
186
|
-
## Usage Examples
|
|
187
|
-
|
|
188
|
-
### Basic Usage - Simple File Listing
|
|
189
|
-
|
|
190
|
-
```typescript
|
|
191
|
-
import { DirWalker } from '@nojaja/dirwalker';
|
|
192
|
-
|
|
193
|
-
const walker = new DirWalker();
|
|
194
|
-
const fileCount = await walker.walk(
|
|
195
|
-
'./src',
|
|
196
|
-
{},
|
|
197
|
-
(relativePath) => {
|
|
198
|
-
console.log(relativePath);
|
|
199
|
-
},
|
|
200
|
-
(error) => {
|
|
201
|
-
console.error('Error:', error);
|
|
202
|
-
}
|
|
203
|
-
);
|
|
204
|
-
|
|
205
|
-
console.log(`Total files processed: ${fileCount}`);
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
### Excluding Directories
|
|
209
|
-
|
|
210
|
-
Common patterns to exclude:
|
|
211
|
-
|
|
212
|
-
```typescript
|
|
213
|
-
const walker = new DirWalker();
|
|
214
|
-
|
|
215
|
-
await walker.walk(
|
|
216
|
-
'./project',
|
|
217
|
-
{
|
|
218
|
-
excludeDirs: [
|
|
219
|
-
/node_modules/, // npm dependencies
|
|
220
|
-
/\.git/, // git repository
|
|
221
|
-
/dist/, // build output
|
|
222
|
-
/coverage/, // test coverage
|
|
223
|
-
/__pycache__/, // Python cache
|
|
224
|
-
/\.next/, // Next.js build
|
|
225
|
-
/\.venv/ // Python virtual env
|
|
226
|
-
]
|
|
227
|
-
},
|
|
228
|
-
(relativePath) => {
|
|
229
|
-
console.log('Source file:', relativePath);
|
|
230
|
-
}
|
|
231
|
-
);
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
**Note:** Directory patterns match the full file path, so `node_modules` will match any "node_modules" directory at any level.
|
|
235
|
-
|
|
236
|
-
### Filtering by File Extension
|
|
237
|
-
|
|
238
|
-
```typescript
|
|
239
|
-
const walker = new DirWalker();
|
|
240
|
-
|
|
241
|
-
await walker.walk(
|
|
242
|
-
'./src',
|
|
243
|
-
{
|
|
244
|
-
excludeExt: [
|
|
245
|
-
/\.test\.ts$/, // Jest test files
|
|
246
|
-
/\.spec\.ts$/, // Jasmine spec files
|
|
247
|
-
/\.d\.ts$/, // TypeScript declarations
|
|
248
|
-
/\.map$/, // Source maps
|
|
249
|
-
/\.log$/ // Log files
|
|
250
|
-
]
|
|
251
|
-
},
|
|
252
|
-
(relativePath) => {
|
|
253
|
-
console.log('Production file:', relativePath);
|
|
254
|
-
}
|
|
255
|
-
);
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
### Combining Directory and Extension Filters
|
|
259
|
-
|
|
260
|
-
```typescript
|
|
261
|
-
const walker = new DirWalker();
|
|
262
|
-
|
|
263
|
-
await walker.walk(
|
|
264
|
-
'./project',
|
|
265
|
-
{
|
|
266
|
-
excludeDirs: [/node_modules/, /\.git/, /dist/],
|
|
267
|
-
excludeExt: [/\.test\.ts$/, /\.d\.ts$/, /\.log$/]
|
|
268
|
-
},
|
|
269
|
-
(relativePath) => {
|
|
270
|
-
console.log('Production source:', relativePath);
|
|
271
|
-
}
|
|
272
|
-
);
|
|
273
|
-
```
|
|
274
|
-
|
|
275
|
-
### Processing Files with Async Operations
|
|
276
|
-
|
|
277
|
-
```typescript
|
|
278
|
-
import { DirWalker } from '@nojaja/dirwalker';
|
|
279
|
-
import { readFile } from 'fs/promises';
|
|
280
|
-
import * as path from 'path';
|
|
281
|
-
|
|
282
|
-
const walker = new DirWalker();
|
|
283
|
-
const results = [];
|
|
284
|
-
|
|
285
|
-
await walker.walk(
|
|
286
|
-
'./docs',
|
|
287
|
-
{
|
|
288
|
-
excludeExt: [/^(?!.*\.md$)/] // Only markdown files
|
|
289
|
-
},
|
|
290
|
-
async (filePath) => {
|
|
291
|
-
try {
|
|
292
|
-
const content = await readFile(filePath, 'utf-8');
|
|
293
|
-
results.push({
|
|
294
|
-
file: filePath,
|
|
295
|
-
lines: content.split('\n').length,
|
|
296
|
-
size: content.length
|
|
297
|
-
});
|
|
298
|
-
} catch (error) {
|
|
299
|
-
console.error(`Failed to read ${filePath}:`, error);
|
|
300
|
-
}
|
|
301
|
-
},
|
|
302
|
-
(error) => {
|
|
303
|
-
console.error('Walk error:', error);
|
|
304
|
-
}
|
|
305
|
-
);
|
|
306
|
-
|
|
307
|
-
console.log('Results:', results);
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
### Counting Files by Extension
|
|
311
|
-
|
|
312
|
-
```typescript
|
|
313
|
-
import * as path from 'path';
|
|
314
|
-
|
|
315
|
-
const walker = new DirWalker();
|
|
316
|
-
const stats = new Map<string, number>();
|
|
317
|
-
|
|
318
|
-
await walker.walk(
|
|
319
|
-
'./src',
|
|
320
|
-
{ excludeDirs: [/node_modules/] },
|
|
321
|
-
(filePath) => {
|
|
322
|
-
const ext = path.extname(filePath) || '(no extension)';
|
|
323
|
-
stats.set(ext, (stats.get(ext) || 0) + 1);
|
|
324
|
-
}
|
|
325
|
-
);
|
|
326
|
-
|
|
327
|
-
console.log('Files by extension:');
|
|
328
|
-
for (const [ext, count] of stats) {
|
|
329
|
-
console.log(` ${ext}: ${count}`);
|
|
330
|
-
}
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
### Debug Mode
|
|
334
|
-
|
|
335
|
-
Enable debug logging to track directory traversal:
|
|
336
|
-
|
|
337
|
-
```typescript
|
|
338
|
-
import { DirWalker } from '@nojaja/dirwalker';
|
|
339
|
-
|
|
340
|
-
const walker = new DirWalker(true); // Enable debug logging
|
|
341
|
-
|
|
342
|
-
await walker.walk(
|
|
343
|
-
'./src',
|
|
344
|
-
{ excludeDirs: [/node_modules/] },
|
|
345
|
-
(file) => {
|
|
346
|
-
console.log('Processing:', file);
|
|
347
|
-
}
|
|
348
|
-
);
|
|
349
|
-
|
|
350
|
-
// Debug output example:
|
|
351
|
-
// シンボリックリンクをスキップ: /path/to/symlink
|
|
352
|
-
// ファイル発見: /path/to/file.ts
|
|
353
|
-
// ディレクトリ読み取りエラー: ... (if any)
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
## Error Handling
|
|
357
|
-
|
|
358
|
-
The library provides flexible error handling through callbacks:
|
|
359
|
-
|
|
360
|
-
### Method 1: Error Callback
|
|
361
|
-
|
|
362
|
-
```typescript
|
|
363
|
-
await walker.walk(
|
|
364
|
-
'./src',
|
|
365
|
-
{},
|
|
366
|
-
(relativePath) => {
|
|
367
|
-
console.log('Processing:', relativePath);
|
|
368
|
-
},
|
|
369
|
-
(error) => {
|
|
370
|
-
// Custom error handling
|
|
371
|
-
console.error('Walk error:', error.message);
|
|
372
|
-
// Log to file, send alert, etc.
|
|
373
|
-
}
|
|
374
|
-
);
|
|
375
|
-
```
|
|
376
|
-
|
|
377
|
-
### Method 2: Default Logging
|
|
378
|
-
|
|
379
|
-
If no error callback is provided, errors are logged automatically:
|
|
380
|
-
|
|
381
|
-
```typescript
|
|
382
|
-
await walker.walk(
|
|
383
|
-
'./src',
|
|
384
|
-
{},
|
|
385
|
-
(relativePath) => {
|
|
386
|
-
console.log('Processing:', relativePath);
|
|
387
|
-
}
|
|
388
|
-
// Errors will be logged to console automatically
|
|
389
|
-
);
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
### Error Scenarios Handled
|
|
393
|
-
|
|
394
|
-
- **Directory not found** - Directory read error (ENOENT)
|
|
395
|
-
- **Permission denied** - File access errors (EACCES)
|
|
396
|
-
- **Invalid path** - Stat operation failures
|
|
397
|
-
- **Symbolic links** - Automatically skipped (not an error)
|
|
398
|
-
- **RegExp errors** - Caught and logged in debug mode
|
|
399
|
-
|
|
400
|
-
## Development Setup
|
|
401
|
-
|
|
402
|
-
### Prerequisites
|
|
403
|
-
|
|
404
|
-
- Node.js 18.0.0 or higher
|
|
405
|
-
- npm 10.8.2 or yarn equivalent
|
|
406
|
-
|
|
407
|
-
### Installation
|
|
408
|
-
|
|
409
|
-
```bash
|
|
410
|
-
# Clone repository
|
|
411
|
-
git clone https://github.com/nojaja/dir-walker.git
|
|
412
|
-
cd dir-walker
|
|
413
|
-
|
|
414
|
-
# Install dependencies
|
|
415
|
-
npm install
|
|
416
|
-
```
|
|
417
|
-
|
|
418
|
-
### Development Commands
|
|
419
|
-
|
|
420
|
-
```bash
|
|
421
|
-
# Run unit tests
|
|
422
|
-
npm run test
|
|
423
|
-
|
|
424
|
-
# Run tests with coverage report
|
|
425
|
-
npm run test:ci
|
|
426
|
-
|
|
427
|
-
# TypeScript type checking
|
|
428
|
-
npm run type-check
|
|
429
|
-
|
|
430
|
-
# Linting with ESLint
|
|
431
|
-
npm run lint
|
|
432
|
-
|
|
433
|
-
# Build production bundle
|
|
434
|
-
npm run build
|
|
435
|
-
|
|
436
|
-
# Build development bundle (with source maps)
|
|
437
|
-
npm run build:dev
|
|
438
|
-
|
|
439
|
-
# Generate API documentation
|
|
440
|
-
npm run docs
|
|
441
|
-
|
|
442
|
-
# Analyze dependency health
|
|
443
|
-
npm run depcruise
|
|
444
|
-
|
|
445
|
-
# Clean build artifacts
|
|
446
|
-
npm run clean
|
|
447
|
-
```
|
|
448
|
-
|
|
449
|
-
### Build Output
|
|
450
|
-
|
|
451
|
-
The build process generates:
|
|
452
|
-
- **dist/dirwalker.bundle.js** - UMD bundle for universal compatibility
|
|
453
|
-
- **dist/index.d.ts** - TypeScript type definitions
|
|
454
|
-
- **dist/** - Other compiled modules
|
|
455
|
-
|
|
456
|
-
### Project Scripts Reference
|
|
457
|
-
|
|
458
|
-
| Script | Purpose |
|
|
459
|
-
|--------|---------|
|
|
460
|
-
| `build` | Production-optimized Webpack bundle |
|
|
461
|
-
| `build:dev` | Development bundle with source maps |
|
|
462
|
-
| `test` | Run Jest unit tests |
|
|
463
|
-
| `test:ci` | Run tests with coverage reporting |
|
|
464
|
-
| `type-check` | TypeScript type checking |
|
|
465
|
-
| `lint` | ESLint code quality check |
|
|
466
|
-
| `clean` | Remove dist/ directory |
|
|
467
|
-
| `depcruise` | Dependency graph analysis |
|
|
468
|
-
| `docs` | Generate TypeDoc HTML documentation |
|
|
469
|
-
|
|
470
|
-
## TypeScript Support
|
|
471
|
-
|
|
472
|
-
Full TypeScript definitions are included:
|
|
473
|
-
|
|
474
|
-
```typescript
|
|
475
|
-
import {
|
|
476
|
-
DirWalker,
|
|
477
|
-
WalkSettings,
|
|
478
|
-
FileCallback,
|
|
479
|
-
ErrorCallback
|
|
480
|
-
} from '@nojaja/dirwalker';
|
|
481
|
-
|
|
482
|
-
const settings: WalkSettings = {
|
|
483
|
-
excludeDirs: [/node_modules/, /\.git/],
|
|
484
|
-
excludeExt: [/\.log$/, /\.tmp$/]
|
|
485
|
-
};
|
|
486
|
-
|
|
487
|
-
const fileCallback: FileCallback = async (relativePath, settings) => {
|
|
488
|
-
console.log(`Processing: ${relativePath}`);
|
|
489
|
-
};
|
|
490
|
-
|
|
491
|
-
const errorCallback: ErrorCallback = (error) => {
|
|
492
|
-
console.error(`Error: ${error.message}`);
|
|
493
|
-
};
|
|
494
|
-
|
|
495
|
-
const walker = new DirWalker();
|
|
496
|
-
await walker.walk('./src', settings, fileCallback, errorCallback);
|
|
497
|
-
```
|
|
498
|
-
|
|
499
|
-
## Current Status
|
|
500
|
-
|
|
501
|
-
**Version**: 1.0.0 (Initial Release)
|
|
502
|
-
|
|
503
|
-
### ✅ Completed Features
|
|
504
|
-
- Recursive directory traversal with async/await support
|
|
505
|
-
- RegExp-based pattern matching for directories and file extensions
|
|
506
|
-
- Symbolic link detection and automatic skipping
|
|
507
|
-
- TypeScript with strict mode enabled
|
|
508
|
-
- Comprehensive type definitions and JSDoc annotations
|
|
509
|
-
- Debug mode for detailed logging
|
|
510
|
-
- Unit tests with >80% code coverage
|
|
511
|
-
- Zero external runtime dependencies
|
|
512
|
-
- UMD bundle for universal compatibility
|
|
513
|
-
- Webpack bundling configuration
|
|
514
|
-
|
|
515
|
-
### Performance Characteristics
|
|
516
|
-
- **Memory**: O(depth) - scales with directory tree depth
|
|
517
|
-
- **Speed**: I/O bound - depends on file system performance
|
|
518
|
-
- **Scalability**: Suitable for projects with thousands of files
|
|
519
|
-
- **Async**: Non-blocking using fs/promises
|
|
520
|
-
|
|
521
|
-
## License
|
|
522
|
-
|
|
523
|
-
MIT
|
|
524
|
-
|
|
525
|
-
## Author
|
|
526
|
-
|
|
527
|
-
**nojaja** <free.riccia@gmail.com> ([GitHub](https://github.com/nojaja))
|
|
528
|
-
|
|
529
|
-
## Contributing
|
|
530
|
-
|
|
531
|
-
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
532
|
-
|
|
533
|
-
### Development Workflow
|
|
534
|
-
|
|
535
|
-
1. Fork the repository
|
|
536
|
-
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
537
|
-
3. Make your changes
|
|
538
|
-
4. Run tests and linting (`npm run test && npm run lint`)
|
|
539
|
-
5. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
540
|
-
6. Push to the branch (`git push origin feature/amazing-feature`)
|
|
541
|
-
7. Open a Pull Request
|
|
542
|
-
|
|
543
|
-
## Repository
|
|
544
|
-
|
|
545
|
-
- **Repository**: [GitHub - nojaja/dir-walker](https://github.com/nojaja/dir-walker)
|
|
546
|
-
- **Issues**: [GitHub Issues](https://github.com/nojaja/dir-walker/issues)
|
|
547
|
-
- **NPM Package**: [@nojaja/dirwalker](https://www.npmjs.com/package/@nojaja/dirwalker)
|
|
1
|
+
yarn add @nojaja/dirwalker
|
|
2
|
+
# @nojaja/dirwalker
|
|
3
|
+
|
|
4
|
+
Lightweight, callback-first directory walker for Node.js. Provides recursive traversal with RegExp-based exclusion for directories and extensions, returns relative file paths, and ships with TypeScript types out of the box.
|
|
5
|
+
|
|
6
|
+
## Project Overview
|
|
7
|
+
|
|
8
|
+
- Purpose: walk a directory tree asynchronously and execute your callback for each file while skipping symlinks and unwanted paths.
|
|
9
|
+
- Package: `@nojaja/dirwalker` (`type: commonjs`, main: `dist/dirwalker.bundle.js`).
|
|
10
|
+
- Current version: 1.0.1.
|
|
11
|
+
|
|
12
|
+
## Project Structure
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
.
|
|
16
|
+
├── src/
|
|
17
|
+
│ ├── DirWalker.ts # Core implementation and exported types
|
|
18
|
+
│ └── index.ts # Public export surface
|
|
19
|
+
├── test/
|
|
20
|
+
│ ├── unit/DirWalker.test.ts# Jest unit tests (mocked fs/promises)
|
|
21
|
+
│ └── fixtures/ # Fixture roots for tests
|
|
22
|
+
├── dist/ # Build artifacts (generated)
|
|
23
|
+
├── docs/ # Generated API docs (typedoc)
|
|
24
|
+
├── dependency-extractor/ # Separate dependency extraction tool (see its README)
|
|
25
|
+
├── webpack.config.js # Webpack bundle settings
|
|
26
|
+
├── jest.unit.config.js # Jest config for unit tests
|
|
27
|
+
├── tsconfig.json # TypeScript config (strict)
|
|
28
|
+
├── package.json # Scripts and metadata
|
|
29
|
+
└── README.md
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Technology Stack
|
|
33
|
+
|
|
34
|
+
- TypeScript 5.3.3 (strict) on Node.js >=18
|
|
35
|
+
- Webpack 5.99.8 for production and development bundles
|
|
36
|
+
- Jest 29.6.1 with ts-jest for unit tests
|
|
37
|
+
- ESLint 8.45.0 + TypeScript ESLint, Prettier 3.0.0
|
|
38
|
+
- Runtime deps: `@nojaja/greputil` (RegExpArray helper), `@nojaja/pathutil`
|
|
39
|
+
|
|
40
|
+
## Features
|
|
41
|
+
|
|
42
|
+
### Completed
|
|
43
|
+
- Async recursive traversal using `fs/promises`
|
|
44
|
+
- Exclude directories and extensions with RegExp arrays
|
|
45
|
+
- Skips symbolic links to avoid cycles
|
|
46
|
+
- Passes relative paths to your callback
|
|
47
|
+
- Optional debug logging (console.debug)
|
|
48
|
+
- Error handling via callback or default console.error
|
|
49
|
+
- Bundled output (`dist/dirwalker.bundle.js`) plus `.d.ts` types
|
|
50
|
+
|
|
51
|
+
### Limitations / Not Included
|
|
52
|
+
- Only exclusion filters are supported (no include/allowlist API)
|
|
53
|
+
- No synchronous API; traversal is async-only
|
|
54
|
+
- No built-in CLI; use the library programmatically
|
|
55
|
+
|
|
56
|
+
## Installation
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
npm install @nojaja/dirwalker
|
|
60
|
+
# or
|
|
61
|
+
yarn add @nojaja/dirwalker
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Requirements: Node.js 18+ and npm 10.8.2+.
|
|
65
|
+
|
|
66
|
+
## Usage (Library)
|
|
67
|
+
|
|
68
|
+
### Basic example
|
|
69
|
+
|
|
70
|
+
```typescript
|
|
71
|
+
import { DirWalker } from '@nojaja/dirwalker';
|
|
72
|
+
|
|
73
|
+
const walker = new DirWalker();
|
|
74
|
+
|
|
75
|
+
const count = await walker.walk(
|
|
76
|
+
'./my-directory',
|
|
77
|
+
{},
|
|
78
|
+
(relativePath) => {
|
|
79
|
+
console.log(relativePath);
|
|
80
|
+
}
|
|
81
|
+
);
|
|
82
|
+
|
|
83
|
+
console.log(`Processed ${count} files`);
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Excluding directories and extensions
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
const walker = new DirWalker();
|
|
90
|
+
|
|
91
|
+
await walker.walk(
|
|
92
|
+
'./project',
|
|
93
|
+
{
|
|
94
|
+
excludeDirs: [/node_modules/, /\.git/, /dist/],
|
|
95
|
+
excludeExt: [/\.log$/, /\.map$/]
|
|
96
|
+
},
|
|
97
|
+
(relativePath) => {
|
|
98
|
+
console.log('source file:', relativePath);
|
|
99
|
+
}
|
|
100
|
+
);
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Handling errors explicitly
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
const walker = new DirWalker(true); // enable debug logs
|
|
107
|
+
|
|
108
|
+
await walker.walk(
|
|
109
|
+
'./src',
|
|
110
|
+
{},
|
|
111
|
+
async (file) => {
|
|
112
|
+
// async work per file is allowed
|
|
113
|
+
},
|
|
114
|
+
(error) => {
|
|
115
|
+
// custom error handling
|
|
116
|
+
console.error('walk error:', error.message);
|
|
117
|
+
}
|
|
118
|
+
);
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### API reference
|
|
122
|
+
|
|
123
|
+
| Export | Description |
|
|
124
|
+
|--------|-------------|
|
|
125
|
+
| `class DirWalker` | `constructor(debug?: boolean)` creates a walker instance. |
|
|
126
|
+
| `walk(targetPath: string, settings: WalkSettings, fileCallback: FileCallback, errCallback?: ErrorCallback): Promise<number>` | Recursively traverses `targetPath`, executes `fileCallback` for each file, and returns the processed file count. |
|
|
127
|
+
| `WalkSettings` | `{ excludeDirs?: RegExp[]; excludeExt?: RegExp[]; }` exclusion patterns. |
|
|
128
|
+
| `FileCallback` | `(relativePath: string, settings: WalkSettings) => void | Promise<void>` receives the path relative to `targetPath`. |
|
|
129
|
+
| `ErrorCallback` | `(error: Error) => void` invoked on errors; defaults to console.error when omitted. |
|
|
130
|
+
|
|
131
|
+
## Development Setup
|
|
132
|
+
|
|
133
|
+
### Local setup
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
git clone https://github.com/nojaja/NodeDirWalker.git
|
|
137
|
+
cd NodeDirWalker
|
|
138
|
+
npm install
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Scripts
|
|
142
|
+
|
|
143
|
+
| Command | Description |
|
|
144
|
+
|---------|-------------|
|
|
145
|
+
| `npm run build` | Build production bundle (webpack, outputs to dist/). |
|
|
146
|
+
| `npm run build:dev` | Build development bundle with source maps. |
|
|
147
|
+
| `npm run test` | Run Jest unit tests (uses jest.unit.config.js). |
|
|
148
|
+
| `npm run test:ci` | Run tests with coverage. |
|
|
149
|
+
| `npm run test:coverage` | Run Jest with coverage via `--experimental-vm-modules`. |
|
|
150
|
+
| `npm run lint` | ESLint TypeScript linting. |
|
|
151
|
+
| `npm run type-check` | TypeScript type checking with `tsc --noEmit`. |
|
|
152
|
+
| `npm run depcruise` | Dependency cruiser analysis. |
|
|
153
|
+
| `npm run docs` | Generate typedoc output into docs/. |
|
|
154
|
+
| `npm run clean` | Remove dist/. |
|
|
155
|
+
|
|
156
|
+
## Technical Details
|
|
157
|
+
|
|
158
|
+
- Uses `fs.promises.readdir` + `fs.promises.stat` for traversal; symlinks are skipped intentionally.
|
|
159
|
+
- Pattern matching relies on `RegExpArray` from `@nojaja/greputil` for both directory and extension filters.
|
|
160
|
+
- Callbacks receive file paths relative to the root you pass to `walk`.
|
|
161
|
+
- Errors are surfaced via `ErrorCallback`; when omitted they are logged with Japanese messages for clarity.
|
|
162
|
+
|
|
163
|
+
## Current Status
|
|
164
|
+
|
|
165
|
+
- Package version: 1.0.1.
|
|
166
|
+
- Scope: library-only; no CLI or web UI components.
|
|
167
|
+
- Tests: unit coverage for traversal, exclusions, symlink skipping, debug logging, and error handling (see test/unit/DirWalker.test.ts).
|
|
168
|
+
|
|
169
|
+
## Performance / Goals
|
|
170
|
+
|
|
171
|
+
- Traversal is I/O bound; memory scales with directory depth (O(depth)).
|
|
172
|
+
- Designed for thousands of files while keeping callbacks async to avoid blocking the event loop.
|
|
173
|
+
|
|
174
|
+
## License & Author
|
|
175
|
+
|
|
176
|
+
- License: MIT
|
|
177
|
+
- Author: nojaja <free.riccia@gmail.com> (https://github.com/nojaja)
|
|
178
|
+
|
|
179
|
+
## Related Projects
|
|
180
|
+
|
|
181
|
+
- `dependency-extractor/`: companion tool (same repo) to detect project manifests and export dependency lists. See its README for usage.
|
package/package.json
CHANGED
|
@@ -1,69 +1,69 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@nojaja/dirwalker",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "A lightweight, flexible directory walker utility for Node.js with pattern matching support",
|
|
5
|
-
"type": "commonjs",
|
|
6
|
-
"main": "dist/dirwalker.bundle.js",
|
|
7
|
-
"types": "dist/index.d.ts",
|
|
8
|
-
"scripts": {
|
|
9
|
-
"build": "webpack --mode production",
|
|
10
|
-
"build:dev": "webpack --mode development",
|
|
11
|
-
"test": "jest --config jest.unit.config.js",
|
|
12
|
-
"test:ci": "jest --config jest.unit.config.js --coverage",
|
|
13
|
-
"test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
|
|
14
|
-
"lint": "eslint src/**/*.ts --config eslint.config.js",
|
|
15
|
-
"type-check": "tsc --noEmit",
|
|
16
|
-
"clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\"",
|
|
17
|
-
"depcruise": "depcruise src --config .dependency-cruiser.js",
|
|
18
|
-
"docs": "typedoc --config typedoc.js"
|
|
19
|
-
},
|
|
20
|
-
"keywords": [
|
|
21
|
-
"directory",
|
|
22
|
-
"walker",
|
|
23
|
-
"file",
|
|
24
|
-
"traversal",
|
|
25
|
-
"recursive",
|
|
26
|
-
"filesystem",
|
|
27
|
-
"pattern-matching",
|
|
28
|
-
"utility"
|
|
29
|
-
],
|
|
30
|
-
"author": "nojaja <free.riccia@gmail.com> (https://github.com/nojaja)",
|
|
31
|
-
"license": "MIT",
|
|
32
|
-
"repository": {
|
|
33
|
-
"type": "git",
|
|
34
|
-
"url": "git+https://github.com/nojaja/NodeDirWalker.git"
|
|
35
|
-
},
|
|
36
|
-
"bugs": {
|
|
37
|
-
"url": "https://github.com/nojaja/NodeDirWalker/issues"
|
|
38
|
-
},
|
|
39
|
-
"homepage": "https://github.com/nojaja/NodeDirWalker#readme",
|
|
40
|
-
"engines": {
|
|
41
|
-
"node": ">=18.0.0"
|
|
42
|
-
},
|
|
43
|
-
"files": [
|
|
44
|
-
"dist"
|
|
45
|
-
],
|
|
46
|
-
"devDependencies": {
|
|
47
|
-
"@types/jest": "^29.5.8",
|
|
48
|
-
"@types/node": "^20.0.0",
|
|
49
|
-
"@typescript-eslint/eslint-plugin": "^8.18.2",
|
|
50
|
-
"@typescript-eslint/parser": "^8.18.2",
|
|
51
|
-
"dependency-cruiser": "^17.3.6",
|
|
52
|
-
"eslint": "^8.45.0",
|
|
53
|
-
"eslint-plugin-jsdoc": "^61.5.0",
|
|
54
|
-
"eslint-plugin-sonarjs": "^3.0.5",
|
|
55
|
-
"jest": "^29.6.1",
|
|
56
|
-
"prettier": "^3.0.0",
|
|
57
|
-
"ts-jest": "^29.1.0",
|
|
58
|
-
"ts-loader": "^9.5.0",
|
|
59
|
-
"typedoc": "^0.28.15",
|
|
60
|
-
"typedoc-plugin-markdown": "^4.9.0",
|
|
61
|
-
"typescript": "^5.3.3",
|
|
62
|
-
"webpack": "^5.99.8",
|
|
63
|
-
"webpack-cli": "^5.0.0"
|
|
64
|
-
},
|
|
65
|
-
"dependencies": {
|
|
66
|
-
"@nojaja/greputil": "^1.0.4",
|
|
67
|
-
"@nojaja/pathutil": "^1.0.6"
|
|
68
|
-
}
|
|
69
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@nojaja/dirwalker",
|
|
3
|
+
"version": "1.0.1",
|
|
4
|
+
"description": "A lightweight, flexible directory walker utility for Node.js with pattern matching support",
|
|
5
|
+
"type": "commonjs",
|
|
6
|
+
"main": "dist/dirwalker.bundle.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
|
+
"scripts": {
|
|
9
|
+
"build": "webpack --mode production",
|
|
10
|
+
"build:dev": "webpack --mode development",
|
|
11
|
+
"test": "jest --config jest.unit.config.js",
|
|
12
|
+
"test:ci": "jest --config jest.unit.config.js --coverage",
|
|
13
|
+
"test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
|
|
14
|
+
"lint": "eslint src/**/*.ts --config eslint.config.js",
|
|
15
|
+
"type-check": "tsc --noEmit",
|
|
16
|
+
"clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\"",
|
|
17
|
+
"depcruise": "depcruise src --config .dependency-cruiser.js",
|
|
18
|
+
"docs": "typedoc --config typedoc.js"
|
|
19
|
+
},
|
|
20
|
+
"keywords": [
|
|
21
|
+
"directory",
|
|
22
|
+
"walker",
|
|
23
|
+
"file",
|
|
24
|
+
"traversal",
|
|
25
|
+
"recursive",
|
|
26
|
+
"filesystem",
|
|
27
|
+
"pattern-matching",
|
|
28
|
+
"utility"
|
|
29
|
+
],
|
|
30
|
+
"author": "nojaja <free.riccia@gmail.com> (https://github.com/nojaja)",
|
|
31
|
+
"license": "MIT",
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "git+https://github.com/nojaja/NodeDirWalker.git"
|
|
35
|
+
},
|
|
36
|
+
"bugs": {
|
|
37
|
+
"url": "https://github.com/nojaja/NodeDirWalker/issues"
|
|
38
|
+
},
|
|
39
|
+
"homepage": "https://github.com/nojaja/NodeDirWalker#readme",
|
|
40
|
+
"engines": {
|
|
41
|
+
"node": ">=18.0.0"
|
|
42
|
+
},
|
|
43
|
+
"files": [
|
|
44
|
+
"dist"
|
|
45
|
+
],
|
|
46
|
+
"devDependencies": {
|
|
47
|
+
"@types/jest": "^29.5.8",
|
|
48
|
+
"@types/node": "^20.0.0",
|
|
49
|
+
"@typescript-eslint/eslint-plugin": "^8.18.2",
|
|
50
|
+
"@typescript-eslint/parser": "^8.18.2",
|
|
51
|
+
"dependency-cruiser": "^17.3.6",
|
|
52
|
+
"eslint": "^8.45.0",
|
|
53
|
+
"eslint-plugin-jsdoc": "^61.5.0",
|
|
54
|
+
"eslint-plugin-sonarjs": "^3.0.5",
|
|
55
|
+
"jest": "^29.6.1",
|
|
56
|
+
"prettier": "^3.0.0",
|
|
57
|
+
"ts-jest": "^29.1.0",
|
|
58
|
+
"ts-loader": "^9.5.0",
|
|
59
|
+
"typedoc": "^0.28.15",
|
|
60
|
+
"typedoc-plugin-markdown": "^4.9.0",
|
|
61
|
+
"typescript": "^5.3.3",
|
|
62
|
+
"webpack": "^5.99.8",
|
|
63
|
+
"webpack-cli": "^5.0.0"
|
|
64
|
+
},
|
|
65
|
+
"dependencies": {
|
|
66
|
+
"@nojaja/greputil": "^1.0.4",
|
|
67
|
+
"@nojaja/pathutil": "^1.0.6"
|
|
68
|
+
}
|
|
69
|
+
}
|