oneRepo API: file

File manipulation functions.

Type Aliases

Options

type Options: {
  step: LogStep;
};

Generic options for file functions

Type declaration

step?

optional step: LogStep;

Avoid creating a new step in output for each function. Pass a Logger Step to pipe all logs and output to that instead.

Source: modules/file/src/index.ts

ReadJsonOptions

type ReadJsonOptions: {
  jsonc: boolean;
  } & Options;

Type declaration

jsonc?

optional jsonc: boolean;

Parse the file as JSONC (JSON with comments).

Source: modules/file/src/index.ts

ReadSafeOptions

type ReadSafeOptions: {
  sentinel: string;
  step: LogStep;
};

Type declaration

sentinel?

optional sentinel: string;

Unique string to use as a start and end sentinel for the contents

step?

optional step: LogStep;

Avoid creating a new step in output for each function. Pass a Logger Step to pipe all logs and output to that instead.

Source: modules/file/src/index.ts

SigningStatus

type SigningStatus: "valid" | "invalid" | "unsigned";

Source: modules/file/src/signing.ts

WriteOptions

type WriteOptions: {
  sign: boolean;
  step: LogStep;
};

Type declaration

sign?

optional sign: boolean;

Optionally sign the contents for future verification.

step?

optional step: LogStep;

Avoid creating a new step in output for each function. Pass a Logger Step to pipe all logs and output to that instead.

Source: modules/file/src/index.ts

WriteSafeOptions

type WriteSafeOptions: {
  sentinel: string;
  sign: boolean;
  step: LogStep;
};

Type declaration

sentinel?

optional sentinel: string;

Unique string to use as a start and end sentinel for the contents

sign?

optional sign: boolean;

Optionally sign the contents for future verification.

step?

optional step: LogStep;

Avoid creating a new step in output for each function. Pass a Logger Step to pipe all logs and output to that instead.

Source: modules/file/src/index.ts

Functions

chmod()

chmod(
   filename,
   mode,
options?): Promise<void>

Change file permissions

await file.chmod('/foo', 'a+x');

Parameters:

Parameter	Type
`filename`	`string`
`mode`	`string` \| `number`
`options`?	`Options`

Returns: Promise<void>
Source: modules/file/src/index.ts

copy()

copy(
   input,
   output,
options?): Promise<void>

Copy a file from one location to another.

If --dry-run or process.env.ONEREPO_DRY_RUN is true, no files will be modified.

await file.copy('/path/to/in/', '/path/to/out/');

Parameters:

Parameter	Type
`input`	`string`
`output`	`string`
`options`?	`Options`

Returns: Promise<void>
Source: modules/file/src/index.ts

exists()

exists(filename, options?): Promise<boolean>

Step-wrapped fs.existsSync implementation.

await file.exists('/path/to/file.ts');

Parameters:

Parameter	Type
`filename`	`string`
`options`?	`Options`

Returns: Promise<boolean>
Source: modules/file/src/index.ts

isSigned()

isSigned(contents): boolean

Checks whether a file is signed without verifying the signature.

Parameters:

Parameter	Type
`contents`	`string`

Returns: boolean
Source: modules/file/src/signing.ts

lstat()

lstat(filename, options?): Promise<Stats | null>

Step-wrapped fs.lstat implementation. See the node.js fs.Stats documentation for more on how to use the return data.

Parameters:

Parameter	Type
`filename`	`string`
`options`?	`Options`

Returns: Promise<Stats | null>

If the filename does not exist, null will be returned instead of a Stats object.

const stat = await file.lstat('/path/to/file/');
if (stat.isDirectory()) {
  /* ... */
}

Source: modules/file/src/index.ts

makeTempDir()

makeTempDir(prefix, options?): Promise<string>

Create a tmp directory in the os tmpdir.

const dir = await file.makeTempDir('tacos-');

Parameters:

Parameter	Type
`prefix`	`string`
`options`?	`Options`

Returns: Promise<string>
Source: modules/file/src/index.ts

mkdirp()

mkdirp(pathname, options?): Promise<void>

Recursively create a directory.

await file.mkdirp('/path/to/something');

Parameters:

Parameter	Type
`pathname`	`string`
`options`?	`Options`

Returns: Promise<void>
Source: modules/file/src/index.ts

read()

read(
   filename,
   flag?,
options?): Promise<string>

Read the contents of a file.

const contents = await file.read('/path/to/file/');

Parameters:

Parameter	Type
`filename`	`string`
`flag`?	`OpenMode`
`options`?	`Options`

Returns: Promise<string>
Source: modules/file/src/index.ts

readJson()

readJson<T>(
   filename,
   flag?,
options?): Promise<T>

Read and parse a JSON files.

Compatible with jsonc by stripping comments before running JSON.parse(). Pass jsonc: true to the options to enable jsonc.

const contents = await file.readJson('/path/to/package.json');
const strippedJsonc = await file.readJson('/path/to/tsconfig.json', 'r', { jsonc: true });

Type parameters:

Type parameter
`T` extends `Record`<`string`, `unknown`>

Parameters:

Parameter	Type
`filename`	`string`
`flag`?	`OpenMode`
`options`?	`ReadJsonOptions`

Returns: Promise<T>
Source: modules/file/src/index.ts

readSafe()

readSafe(filename, options?): Promise<[string | null, string]>

Read a sentinel-wrapped portion of a file that was previously written with writeSafe and return both the wrapped portion as well as the full contents of the file.

const [portion, fullContents] = await file.readSafe('/path/to/file/', { sentinel: 'tacos' });

Parameters:

Parameter	Type
`filename`	`string`
`options`?	`ReadSafeOptions`

Returns: Promise<[string | null, string]>
Source: modules/file/src/index.ts

remove()

remove(pathname, options?): Promise<void>

Remove files and folders at a given path. Equivalent to rm -rf {pathname}

await file.remove('/path/to/something');

Parameters:

Parameter	Type
`pathname`	`string`
`options`?	`Options`

Returns: Promise<void>
Source: modules/file/src/index.ts

signContents()

signContents(
   filename,
   contents,
options?): Promise<any>

Sign the contents for a given file without writing out. This function is typically useful for manually comparing signed file contents.

const filename = graph.root.resolve('README.md');
const currentContents = await file.read(filename);
const newContents = generateReadme();
if (currentContents !== (await signContents(filename, contents))) {
  logger.error('Contents mismatch');
}

Parameters:

Parameter	Type
`filename`	`string`
`contents`	`string`
`options`?	`Options`

Returns: Promise<any>
Source: modules/file/src/index.ts

verifySignature()

verifySignature(contents): SigningStatus

Verify the signature in a signed file.

Parameters:

Parameter	Type
`contents`	`string`

Returns: SigningStatus
Source: modules/file/src/signing.ts

write()

write(
   filename,
   contents,
options?): Promise<void>

Write to a file. This will attempt use Prettier to format the contents based on the filename given. If Prettier does not understand the file’s extension, no changes will be made.

If --dry-run or process.env.ONEREPO_DRY_RUN is true, no files will be modified.

await file.write('/path/to/out/', '# hello!');

Parameters:

Parameter	Type
`filename`	`string`
`contents`	`string`
`options`?	`WriteOptions`

Returns: Promise<void>
Source: modules/file/src/index.ts

writeSafe()

writeSafe(
   filename,
   contents,
options?): Promise<void>

Safely write contents to a file, wrapped in a start and end sentinel. This allows writing to a file without overwriting the current content of the file – other than that which falls between the start and end sentinel.

Write to /path/to/out/ between a section denoted by the sentinel 'some-unique-string' while leaving the rest of the file intact.

await file.writeSafe('/path/to/out/', '# hello', { sentinel: 'some-unique-string' });

Write to a section of the file as signed content for verifying later.

await file.writeSafe('/path/to/out/', '# hello', { signed: true });

Parameters:

Parameter	Type
`filename`	`string`
`contents`	`string`
`options`?	`WriteSafeOptions`

Returns: Promise<void>
Source: modules/file/src/index.ts