Skip to content

filesystem.md

Latest commit

 

History

History
287 lines (208 loc) · 6.82 KB

filesystem.md

File metadata and controls

287 lines (208 loc) · 6.82 KB

readFile (function)

Read the contents of a file from disk.

With no options specified, it reads the file as UTF-8 and returns a string:

const contents = readFile("README.md");
console.log(contents);
// "# yavascript\n\nYavaScript is a cross-platform bash-like script runner and repl which is distributed as a single\nstatically-linked binary..."

But, if you pass { binary: true } as the second argument, it returns an ArrayBuffer containing the raw bytes from the file:

const contents = readFile("README.md", { binary: true });
console.log(contents);
// ArrayBuffer {
//   │0x00000000│ 23 20 79 61 76 61 73 63 72 69 70 74 0A 0A 59 61
//   │0x00000010│ 76 61 53 63 72 69 70 74 20 69 73 20 61 20 63 72
//   │0x00000020│ 6F 73 73 2D 70 6C 61 74 66 6F 72 6D 20 62 61 73
//   │0x00000030│ 68 2D 6C 69 6B 65 20 73 63 72 69 70 74 20 72 75
// ...
const readFile: {
  (path: string | Path): string;
  (path: string | Path, options: {}): string;
  (
    path: string | Path,
    options: {
      binary: false;
    },
  ): string;
  (
    path: string | Path,
    options: {
      binary: true;
    },
  ): ArrayBuffer;
};

readFile(...) (call signature)

Read the contents of a file from disk, as a UTF-8 string.

(path: string | Path): string;

readFile(...) (call signature)

Read the contents of a file from disk, as a UTF-8 string.

(path: string | Path, options: {}): string;

readFile(...) (call signature)

Read the contents of a file from disk, as a UTF-8 string.

(path: string | Path, options: {
  binary: false;
}): string;

readFile(...) (call signature)

Read the contents of a file from disk, as an ArrayBuffer.

(path: string | Path, options: {
  binary: true;
}): ArrayBuffer;

writeFile (function)

Write the contents of a string or ArrayBuffer to a file.

Strings are written using the UTF-8 encoding.

declare function writeFile(
  path: string | Path,
  data: string | ArrayBuffer,
): void;

isFile (function)

Function which returns true if the path points to a regular file.

declare function isFile(path: string | Path): boolean;

isDir (function)

Function which returns true if the path points to a directory, or if the path points to a symlink which points to a directory. Otherwise, it returns false.

declare function isDir(path: string | Path): boolean;

isLink (function)

Returns true if the path points to a symlink.

declare function isLink(path: string | Path): boolean;

isExecutable (function)

Returns true if the resource at the provided path can be executed by the current user.

If nothing exists at that path, an error will be thrown.

declare function isExecutable(path: string | Path): boolean;

isReadable (function)

Returns true if the resource at the provided path can be read by the current user.

If nothing exists at that path, an error will be thrown.

declare function isReadable(path: string | Path): boolean;

isWritable (function)

Returns true if a resource at the provided path could be written to by the current user.

declare function isWritable(path: string | Path): boolean;

remove (function)

Delete the file or directory at the specified path.

If the directory isn't empty, its contents will be deleted, too.

Provides the same functionality as the command rm -rf.

declare function remove(path: string | Path): void;

exists (function)

Returns true if a file or directory exists at the specified path.

Provides the same functionality as the command test -e.

declare function exists(path: string | Path): boolean;

copy (function)

Copies a file or folder from one location to another. Folders are copied recursively.

Provides the same functionality as the command cp -R.

declare function copy(
  from: string | Path,
  to: string | Path,
  options?: CopyOptions,
): void;

CopyOptions (type)

Options for copy.

declare type CopyOptions = {
  whenTargetExists?: "overwrite" | "skip" | "error";
  logging?: {
    trace?: (...args: Array<any>) => void;
    info?: (...args: Array<any>) => void;
  };
};

CopyOptions.whenTargetExists (property)

What to do when attempting to copy something into a location where something else already exists.

Defaults to "error".

whenTargetExists?: "overwrite" | "skip" | "error";

CopyOptions.logging (object property)

Options which control logging.

logging?: {
  trace?: (...args: Array<any>) => void;
  info?: (...args: Array<any>) => void;
};

CopyOptions.logging.trace (function property)

If provided, this function will be called multiple times as copy traverses the filesystem, to help you understand what's going on and/or troubleshoot things. In most cases, it makes sense to use a logging function here, like so:

copy("./source", "./destination", {
  logging: { trace: console.log },
});

Defaults to the current value of logger.trace. logger.trace defaults to a no-op function.

trace?: (...args: Array<any>) => void;

CopyOptions.logging.info (function property)

An optional, user-provided logging function to be used for informational messages.

Defaults to the current value of logger.info. logger.info defaults to a function which writes to stderr.

info?: (...args: Array<any>) => void;

rename (function)

Rename the file or directory at the specified path.

Provides the same functionality as the command mv.

declare function rename(from: string | Path, to: string | Path): void;