Class: FileUtils

Defined in: core/src/FileUtils.ts:16

Utility functions for working with files.

Constructors

Constructor

new FileUtils(): FileUtils

Returns

FileUtils

Methods

assertContained()

static assertContained(rootDir, target): Promise<string>

Defined in: core/src/FileUtils.ts:46

Throws an error if target is not contained within rootDir. Used to prevent path traversal (e.g. ../) from escaping an intended root when a caller opts in by providing rootDir.

Both rootDir and the longest already-existing ancestor of target are resolved via fs.promises.realpath before the containment check, not just path.resolve. Without this, a symlink placed anywhere on disk within target's existing ancestry (including target itself) that points outside rootDir would pass a purely lexical check, yet fs.existsSync/fs.writeFileSync/fs.readFileSync etc. would transparently follow it - defeating the containment guarantee entirely. Any remaining (not-yet-existing) trailing path segments can't be symlinks yet, so they're safely appended as literal strings.

Parameters

rootDir

string

The directory that target must be contained within. Must exist.

target

string

The path to verify.

Returns

Promise<string>

The fully resolved (existing-portion realpath'd) path. Callers should use this value - not the original target - for the actual filesystem operation, so a symlink swapped in after this check can't reintroduce the gap it closes.

---

copyBinaryFile()

static copyBinaryFile(srcPath, outPath, variables?, rootDir?, overwrite?): Promise<void>

Defined in: core/src/FileUtils.ts:173

Generates a copy of the source file at the desired output destination using binary copy mode.

Parameters

srcPath

string

The source file to copy.

outPath

string

The destination file to generate.

variables?

any = {}

The map of variable names to values to swap. Applies to outPath only.

rootDir?

string

Optional. When provided, all resolved source and destination paths must be contained within this directory, otherwise an error is thrown.

overwrite?

boolean = false

Set to true to overwrite an existing file at the destination. Default is false, matching the behavior of writeFile/copyFile. Appended after rootDir to preserve the existing positional call signature - note this is the opposite order from copyFile's (overwrite, rootDir).

Returns

Promise<void>

---

copyDirectory()

static copyDirectory(srcPath, outPath, vars?, excludeFilters?, binaryFilters?, force?, rootDir?): Promise<void>

Defined in: core/src/FileUtils.ts:247

Performs a deep copy of a directory tree at the given srcPath to the specified output directory. Performs template replacement for all variables given and skips any files in the specified filter.

Parameters

srcPath

string

The path to the source directory to copy files from.

outPath

string

The path to the destination directory to copy files to.

vars?

any = {}

The map of template variables to perform replacement on.

excludeFilters?

string[] = []

The list of file extension filters to exclude during the copy process.

binaryFilters?

string[] = []

The list of file extension filters to copy as binary only.

force?

boolean = false

Set to true to force writing over any existing files.

rootDir?

string

Optional. When provided, all resolved source and destination paths must be contained within this directory, otherwise an error is thrown.

Returns

Promise<void>

---

copyFile()

static copyFile(srcPath, outPath, variables?, overwrite?, rootDir?): Promise<void>

Defined in: core/src/FileUtils.ts:130

Generates a copy of the source file at the desired output destination and performs a swap of all values of the variables specified.

Parameters

srcPath

string

The source file to copy.

outPath

string

The destination file to generate.

variables?

any = {}

The map of variable names to values to swap.

overwrite?

boolean = false

Set to true to overwrite an existing file at outPath.

rootDir?

string

Optional. When provided, all resolved source and destination paths must be contained within this directory, otherwise an error is thrown.

Returns

Promise<void>

---

exists()

static exists(target): Promise<boolean>

Defined in: core/src/FileUtils.ts:20

Determines if the provided path exists on the filesystem.

Parameters

target

string

Returns

Promise<boolean>

---

writeFile()

static writeFile(srcPath, outPath, contents, overwrite?, rootDir?): Promise<void>

Defined in: core/src/FileUtils.ts:83

Attempts to write the provided contents to the file path given. If a file already exists at the destination an error is thrown unless overwrite is set to true.

Parameters

srcPath

string

The baseline template file the contents were generated from.

outPath

string

The destination file path to be written.

contents

any

The contents of the file to write.

overwrite?

boolean = false

Set to true to overwrite an existing file at outPath.

rootDir?

string

Optional. When provided, srcPath and outPath must both resolve to a location contained within this directory, otherwise an error is thrown. Callers that pass externally-influenced paths should always supply this to prevent path traversal.

Returns

Promise<void>