@hyperfrontend/project-scope/project/traversaltraversal
Directory-walking and file-search helpers built around an explicit visitor pattern.
walkDirectory and walkTree traverse a folder hierarchy, invoking a WalkVisitor for every entry; the visitor's WalkVisitorResult controls whether to descend, skip, or stop. findFiles, findFilesInTree, and findDirectories are the higher-level shortcuts for "give me everything matching this pattern" use cases, with FindOptions covering depth limits, include/exclude globs, and symlink behavior. Designed for static analysis tools that need predictable, side-effect-free directory iteration with backpressure-style control.
API Reference§
ƒ Functions
§functionfindDirectories(
findDirectories(
Searches a directory tree for directories matching one or more glob patterns, returning relative or absolute paths based on options.
Parameters
| Name | Type | Description |
|---|---|---|
§startPath | string | Root directory to begin the search |
§patterns | string | string[ | Glob patterns to filter directories (supports wildcards) |
§options? | FindOptions | Configuration for search behavior |
Returns
string[List of relative directory paths that match the patterns
Example
Finding directories by pattern
import { findDirectories } from '@hyperfrontend/project-scope'
const componentDirs = findDirectories('./src', 'components')
// => ['features/auth/components', 'features/dashboard/components']Searches a directory tree for files matching one or more glob patterns, returning relative or absolute paths based on options.
Parameters
| Name | Type | Description |
|---|---|---|
§startPath | string | Root directory to begin the search |
§patterns | string | string[ | Glob patterns (e.g., '.ts', '/.json') to filter files |
§options? | FindOptions | Configuration for search behavior |
Returns
string[List of relative file paths that match the patterns
Example
Finding files by pattern
import { findFiles } from '@hyperfrontend/project-scope'
// Find all TypeScript files
const tsFiles = findFiles('./src', '\*\*/*.ts')
// Find multiple file types
const configFiles = findFiles('./', ['\*.json', '\*.yaml', '\*.yml'])
// Limit results and get absolute paths
const first10 = findFiles('./src', '\*\*/*.ts', {
maxResults: 10,
absolutePaths: true
})Searches a virtual file system tree for files matching glob patterns, useful for analyzing project structure without disk I/O.
Parameters
| Name | Type | Description |
|---|---|---|
§tree | Tree | In-memory virtual file system representation |
§patterns | string | string[ | Glob patterns (e.g., '.ts', '/.json') to filter files |
§options? | FindOptions | Configuration for search behavior |
Returns
string[List of virtual file paths that match the patterns
Example
Finding files in a virtual tree
import { createTree, findFilesInTree } from '@hyperfrontend/project-scope'
const tree = createTree('/workspace')
const tsFiles = findFilesInTree(tree, '**/*.ts', { maxDepth: 3 })
// => ['src/index.ts', 'src/utils/helpers.ts']Traverses a directory tree synchronously, calling a visitor function for each file and directory encountered. Supports depth limiting, hidden file filtering, and gitignore pattern matching.
Parameters
| Name | Type | Description |
|---|---|---|
§startPath | string | Root directory to begin traversal |
§visitor | WalkVisitor | Callback function invoked for each file system entry |
§options? | WalkOptions | Configuration for traversal behavior |
Example
Walking a directory tree
import { walkDirectory } from '@hyperfrontend/project-scope'
const tsFiles: string[] = []
walkDirectory('./src', (entry) => {
if (entry.isFile && entry.name.endsWith('.ts')) {
tsFiles.push(entry.relativePath)
}
}, { maxDepth: 5, respectGitignore: true })Traverses a virtual file system tree, calling a visitor function for each file and directory. Operates on in-memory tree structure without disk I/O.
Parameters
| Name | Type | Description |
|---|---|---|
§tree | Tree | In-memory virtual file system representation |
§startPath | string | Root path within the tree to begin traversal |
§visitor | WalkVisitor | Callback function invoked for each tree entry |
§options? | WalkOptions | Configuration for traversal behavior |
Example
Walking a virtual tree
import { createTree, walkTree } from '@hyperfrontend/project-scope'
const tree = createTree('/workspace')
walkTree(tree, 'src', (entry) => {
if (entry.isDirectory) {
console.log('Dir:', entry.relativePath)
return 'skip' // Don't recurse into this directory
}
})◈ Interfaces
Options for file and directory search operations.
Properties
Walk entry representing a file or directory.
Properties
◆ Types
Walk visitor function.
type WalkVisitor = (Visitor function signature.
type WalkVisitorResult = void | "skip" | "stop"