yavascript 0.0.5 → 0.0.7

package/yavascript.d.ts

@@ -1,12 +1,8 @@
-
+// ===============
 // ---------------
 // YavaScript APIs
 // ---------------
-
-// -----------
-// --- env ---
-// -----------
-
+// ===============
 /**
  * An object representing the process's environment variables. You can read
  * from it to read environment variables, write into it to set environment
@@ -15,300 +11,88 @@
  */
 declare const env: { [key: string]: string | undefined };
 
-// ------------
-// --- exec ---
-// ------------
-
-type BaseExecOptions = {
-  /** Sets the current working directory for the child process. */
-  cwd?: string;
-
-  /** Sets environment variables within the process. */
-  env?: { [key: string | number]: string | number | boolean };
-};
-
-interface Exec {
-  (args: Array<string> | string): void;
-
-  (args: Array<string> | string, options: Record<string, never>): void;
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: true;
-      /**
-       * If true, stdout and stderr will be collected into strings and returned
-       * instead of being printed to the screen.
-       *
-       * Defaults to false.
-       */
-      captureOutput: false;
-    }
-  ): void;
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: false;
-      /**
-       * If true, stdout and stderr will be collected into strings and returned
-       * instead of being printed to the screen.
-       *
-       * Defaults to false.
-       */
-      captureOutput: false;
-    }
-  ): { status: number };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: false;
-    }
-  ): { status: number };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: true;
-      /**
-       * If true, stdout and stderr will be collected into strings and returned
-       * instead of being printed to the screen.
-       *
-       * Defaults to false.
-       */
-      captureOutput: true;
-    }
-  ): { stdout: string; stderr: string };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * If true, stdout and stderr will be collected into strings and returned
-       * instead of being printed to the screen.
-       *
-       * Defaults to false.
-       */
-      captureOutput: true;
-    }
-  ): { stdout: string; stderr: string };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: false;
-      captureOutput: true;
-    }
-  ): { stdout: string; stderr: string; status: number };
-
-  /** Log all executed commands to stderr. `isOn` is optional and defaults to `true`. Pass `false` to disable logging. */
-  enableLogging(isOn?: boolean): void;
-}
-
-/** Run a child process using the provided arguments. The first value in the arguments array is the program to run. */
-declare const exec: Exec;
-
-/** Alias for `exec(args, { captureOutput: true })` */
-declare function $(args: Array<string> | string): {
-  stdout: string;
-  stderr: string;
-};
-
-// -------------
-// --- paths ---
-// -------------
-
 /**
- * Change the process's current working directory to the specified path.
+ * Parse command line --flags into an object of flags and an array of
+ * positional arguments. This function is opinionated; if it doesn't meet your
+ * needs, you can parse the `scriptArgs` global manually.
  *
- * Provides the same functionality as the shell builtin of the same name.
- */
-declare function cd(path: string): void;
-
-/**
- * Return the process's current working directory.
+ * Flags `--like-this`, `--like_this`, or `--LIKE_THIS` get converted into
+ * property names `likeThis` on the returned flags object.
  *
- * Provides the same functionality as the shell builtin of the same name.
- */
-declare function pwd(): string;
-
-/**
- * Get the absolute path given a relative path. Symlinks are also resolved.
+ * Flags like this: `-v` get converted into into property names like this: `v`
+ * on the returned flags object.
  *
- * The path's target file/directory must exist.
+ * Anything that appears after `--` is considered a positional argument instead
+ * of a flag. `--` is not present in the returned positional arguments Array.
  *
- * Provides the same functionality as the unix binary of the same name.
- */
-declare function realpath(path: string): string;
-
-/**
- * Removes the final component from a path string.
+ * Single-character flags must have a single leading dash, and multi-character
+ * flags must have two leading dashes.
  *
- * Provides the same functionality as the unix binary of the same name.
- */
-declare function dirname(path: string): string;
-
-/**
- * Return the last component of a path string.
+ * Flags with equals signs in them (eg. `--something=42`) are not supported.
+ * Write `--something 42` instead.
  *
- * Provides the same functionality as the unix binary of the same name.
- */
-declare function basename(path: string): string;
-
-/**
- * Returns the file extension of the file at a given path.
+ * Flags where you specify them multiple times, like `-vvv`, are not supported.
+ * Write something like `-v 3` instead.
  *
- * If the file has no extension (eg `Makefile`, etc), then `''` will be returned.
+ * @param hints - An object whose keys are flag names (in camelCase) and whose values indicate what type to treat that flag as. Valid property values are `String`, `Boolean`, `Number`, and `parseScriptArgs.Path`. `parseScriptArgs.Path` will resolve relative paths into absolute paths for you. If no hints object is specified, `parseScriptArgs` will do its best to guess, based on the command-line args.
+ * @param argv - An array containing the command line flags you want to parse. If unspecified, `scriptArgs.slice(2)` will be used (we slice 2 in order to skip the yavascript binary and script name). If you pass in an array here, it should only contain command-line flags, not the binary being called.
  *
- * Pass `{ full: true }` to get compound extensions, eg `.d.ts` or `.test.js` instead of just `.ts`/`.js`.
- */
-declare function extname(
-  pathOrFilename: string,
-  options?: { full?: boolean }
-): string;
-
-/**
- * A namespace object providing several path-string-related APIs.
+ * @returns An object with two properties: `flags` and `args`. `flags` is an object whose keys are camelCase flag names and whose values are strings, booleans, or numbers corresponding to the input command-line args. `args` is an Array of positional arguments, as found on the command-line.
  */
-declare const paths: {
-  /**
-   * The separator character the host operating system uses between path
-   * components, ie. the slashes in a filepath. On windows, it's a backslash, and
-   * on all other OSes, it's a forward slash.
-   */
-  OS_PATH_SEPARATOR: "/" | "\\";
-
+declare const parseScriptArgs: {
   /**
-   * Split a path string (or array of path strings) on / or \\, returning an
-   * Array of strings.
+   * Parse command line --flags into an object of flags and an array of
+   * positional arguments. This function is opinionated; if it doesn't meet your
+   * needs, you can parse the `scriptArgs` global manually.
    *
-   * Trailing slashes and duplicate path separators will be removed.
+   * Flags `--like-this`, `--like_this`, or `--LIKE_THIS` get converted into
+   * property names `likeThis` on the returned flags object.
    *
-   * If the path starts with `/`, the first string in the Array will be empty.
-   */
-  split(path: string | Array<string>): Array<string>;
-
-  /**
-   * Detect which path separator is present in the given path or array of
-   * paths: `\` or `/`.
+   * Flags like this: `-v` get converted into into property names like this: `v`
+   * on the returned flags object.
    *
-   * If neither is present, `/` will be returned.
-   */
-  detectSeparator(input: string | Array<string>): string;
-
-  /**
-   * Create a path string from one or more path or path component strings.
-   * {@link paths.OS_PATH_SEPARATOR} will be used to combine parts.
+   * Anything that appears after `--` is considered a positional argument instead
+   * of a flag. `--` is not present in the returned positional arguments Array.
    *
-   * This function does not resolve `..` or `.`. Use {@link paths.resolve} for that.
-   */
-  join(...parts: Array<string>): string;
-
-  /**
-   * Resolves all `..` and `.` components in a path, returning an absolute
-   * path.
+   * Single-character flags must have a single leading dash, and multi-character
+   * flags must have two leading dashes.
+   *
+   * Flags with equals signs in them (eg. `--something=42`) are not supported.
+   * Write `--something 42` instead.
    *
-   * Use `from` to specify where leading `.` or `..` characters should be
-   * resolved relative to. If unspecified, it defaults to `pwd()`.
+   * Flags where you specify them multiple times, like `-vvv`, are not supported.
+   * Write something like `-v 3` instead.
+   *
+   * @param hints - An object whose keys are flag names (in camelCase) and whose values indicate what type to treat that flag as. Valid property values are `String`, `Boolean`, `Number`, and `parseScriptArgs.Path`. `parseScriptArgs.Path` will resolve relative paths into absolute paths for you. If no hints object is specified, `parseScriptArgs` will do its best to guess, based on the command-line args.
+   * @param args - An array containing the command line flags you want to parse. If unspecified, `scriptArgs.slice(2)` will be used (we slice 2 in order to skip the yavascript binary and script name). If you pass in an array here, it should only contain command-line flags, not the binary being called.
+   *
+   * @returns An object with two properties: `flags` and `args`. `flags` is an object whose keys are camelCase flag names and whose values are strings, booleans, or numbers corresponding to the input command-line args. `args` is an Array of positional arguments, as found on the command-line.
    */
-  resolve(path: string, from?: string): string;
+  (
+    hints?: {
+      [key: string]:
+        | typeof String
+        | typeof Boolean
+        | typeof Number
+        | typeof parseScriptArgs["Path"];
+    },
+    args?: Array<string>
+  ): {
+    flags: { [key: string]: any };
+    args: Array<string>;
+  };
 
   /**
-   * Returns whether the path starts with either a leading slash or a windows
-   * drive letter.
+   * A hint value for {@link parseScriptArgs}. Behaves similar to the hint value
+   * `String`, except that it also resolves relative paths into absolute paths,
+   * using the following rules:
+   *
+   * - paths `./like/this` or `../like/this` get resolved relative to `pwd()`.
+   * - paths `like/this` or `this` get resolved relative to `pwd()` as if they had a leading `./`.
    */
-  isAbsolute(path: string): boolean;
+  readonly Path: unique symbol;
 };
 
-/**
- * The absolute path to the current file (whether script or module).
- *
- * Behaves the same as in Node.js, except that it's present within ES modules.
- */
-declare const __filename: string;
-
-/**
- * The absolute path to the directory the current file is inside of.
- *
- * Behaves the same as in Node.js, except that it's present within ES modules.
- */
-declare const __dirname: string;
-
-// ------------
-// --- repo ---
-// ------------
-
-/**
- * Returns the absolute path to the root folder of the git/hg repo.
- *
- * This is done by running `git rev-parse --show-toplevel` and `hg root`.
- *
- * If `relativeTo` is provided, the git and hg commands will be executed in
- * that folder instead of in `pwd()`.
- */
-declare function repoRoot(relativeTo?: string): string;
-
-/**
- * Returns whether the provided path is ignored by git.
- */
-declare function isGitignored(path: string): boolean;
-
-// ------------------
-// --- filesystem ---
-// ------------------
-
-/**
- * Return the contents of a directory, as absolute paths. `.` and `..` are
- * omitted.
- *
- * Use the `relativePaths` option to get relative paths instead (relative to
- * the parent directory).
- */
-declare function ls(
-  dir?: string,
-  options?: { relativePaths?: boolean }
-): Array<string>;
-
-/**
- * Read a symlink.
- *
- * Returns the target of the symlink, which may be absolute or relative.
- *
- * Provides the same functionality as the unix binary of the same name.
- */
-declare function readlink(path: string): string;
-
 /**
  * Read the contents of a file from disk, as a UTF-8 string.
  */
@@ -408,135 +192,1234 @@ declare type CopyOptions = {
  */
 declare function copy(from: string, to: string, options?: CopyOptions): void;
 
-// ------------
-// --- glob ---
-// ------------
+/** An object that represents a filesystem path. */
+declare class Path {
+  /** The character used to separate path segments on this OS. */
+  static readonly OS_SEGMENT_SEPARATOR: "/" | "\\";
 
-/**
- * Options for {@link glob}.
- */
-declare type GlobOptions = {
   /**
-   * Whether to treat symlinks to directories as if they themselves were
-   * directories, traversing into them.
-   *
-   * Defaults to false.
+   * The character used to separate entries within the PATH environment
+   * variable on this OS.
    */
-  followSymlinks?: boolean;
+  static readonly OS_ENV_VAR_SEPARATOR: ":" | ";";
+
+  /** Split one or more path strings into an array of path segments. */
+  static splitToSegments(inputParts: Array<string> | string): Array<string>;
 
   /**
-   * If provided, this function will be called multiple times as `glob`
-   * 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:
-   *
-   * ```js
-   * glob(pwd(), ["./*.js"], { trace: console.log });
-   * ```
+   * Search the provided path string or strings for a path separator character,
+   * and return it. If none is found, return `fallback`, which defaults to the
+   * OS's path segment separator.
    */
-  trace?: (...args: Array<any>) => void;
-};
+  static detectSeparator<Fallback extends string | null = string>(
+    input: Array<string> | string,
+    // @ts-ignore might be instantiated with a different subtype
+    fallback: Fallback = Path.OS_SEGMENT_SEPARATOR
+  ): string | Fallback;
 
-/**
- * Search the filesystem for files matching the specified glob patterns.
- *
- * Uses [minimatch](https://www.npmjs.com/package/minimatch) with its default
+  /** Join together one or more paths. */
+  static join(...inputs: Array<string | Path | Array<string | Path>>): string;
+
+  /**
+   * Turns the input path(s) into an absolute path by resolving all `.` and `..`
+   * segments, using `pwd()` as a base dir to use when resolving leading `.` or
+   * `..` segments.
+   */
+  static resolve(
+    ...inputs: Array<string | Path | Array<string | Path>>
+  ): string;
+
+  /**
+   * Concatenates the input path(s) and then resolves all non-leading `.` and
+   * `..` segments.
+   */
+  static normalize(
+    ...inputs: Array<string | Path | Array<string | Path>>
+  ): string;
+
+  /**
+   * Return whether the provided path string is absolute; that is, whether it
+   * starts with either `/` or a drive letter (ie `C:`).
+   */
+  static isAbsolute(path: string): boolean;
+
+  /**
+   * An array of the path segments that make up this path.
+   *
+   * For `/tmp/foo.txt`, it'd be `["", "tmp", "foo.txt"]`.
+   *
+   * For `C:\something\somewhere.txt`, it'd be `["C:", "something", "somewhere.txt"]`.
+   */
+  segments: Array<string>;
+
+  /**
+   * The path separator that should be used to turn this path into a string.
+   *
+   * Will be either `/` or `\`.
+   */
+  separator: string;
+
+  /** Create a new Path object using the provided input(s). */
+  constructor(...inputs: Array<string | Path | Array<string | Path>>);
+
+  /** Create a new Path object using the provided segments and separator. */
+  static from(segments: Array<string>, separator: string): Path;
+
+  /**
+   * Turn this path into an absolute path by resolving all `.` and `..`
+   * segments, using `from` as a base dir to use when resolving leading `.` or
+   * `..` segments.
+   *
+   * If `from` is unspecified, it defaults to `pwd()`.
+   */
+  resolve(from?: string | Path): Path;
+
+  /**
+   * Resolve all non-leading `.` and `..` segments in this path.
+   */
+  normalize(): Path;
+
+  /**
+   * Create a new path by appending another path's segments after this path's
+   * segments.
+   *
+   * The returned path will use this path's separator.
+   */
+  concat(other: string | Path | Array<string | Path>): Path;
+
+  /**
+   * Return whether this path is absolute; that is, whether it starts with
+   * either `/` or a drive letter (ie `C:`).
+   */
+  isAbsolute(): boolean;
+
+  /**
+   * Turn this path into a string by joining its segments using its separator.
+   */
+  toString(): string;
+}
+
+/**
+ * The absolute path to the current file (whether script or module).
+ *
+ * Behaves the same as in Node.js, except that it's present within ES modules.
+ */
+declare const __filename: string;
+
+/**
+ * The absolute path to the directory the current file is inside of.
+ *
+ * Behaves the same as in Node.js, except that it's present within ES modules.
+ */
+declare const __dirname: string;
+
+/**
+ * Return the last component of a path string.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function basename(path: string): string;
+
+/**
+ * Read the contents of one of more files from disk as one UTF-8 string,
+ * print that string to stdout, then return it.
+ */
+declare function cat(...paths: Array<string>): string;
+
+/**
+ * Change the process's current working directory to the specified path. If no
+ * path is specified, moves to the user's home directory.
+ *
+ * Provides the same functionality as the shell builtin of the same name.
+ */
+declare function cd(path?: string): void;
+
+/** A string representing who a permission applies to. */
+declare type ChmodPermissionsWho =
+  | "user"
+  | "group"
+  | "others"
+  | "all"
+  | "u"
+  | "g"
+  | "o"
+  | "a"
+  | "ug"
+  | "go"
+  | "uo";
+
+/** A string representing the access level for the given permission. */
+declare type ChmodPermissionsWhat =
+  | "read"
+  | "write"
+  | "execute"
+  | "readwrite"
+  | "none"
+  | "full"
+  | "r"
+  | "w"
+  | "x"
+  | "rw"
+  | "rx"
+  | "wx"
+  | "rwx";
+
+/**
+ * Set the permission bits for the specified file.
+ *
+ * @param permissions The permission bits to set. This can be a number, a string containing an octal number, or an object.
+ * @param path The path to the file.
+ */
+declare function chmod(
+  permissions:
+    | number
+    | string
+    | Record<ChmodPermissionsWho, ChmodPermissionsWhat>,
+  path: string
+): void;
+
+/**
+ * Removes the final component from a path string.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function dirname(path: string): string;
+
+/**
+ * Print one or more values to stdout.
+ */
+declare const echo: typeof console.log;
+
+/**
+ * Returns the file extension of the file at a given path.
+ *
+ * If the file has no extension (eg `Makefile`, etc), then `''` will be returned.
+ *
+ * Pass `{ full: true }` to get compound extensions, eg `.d.ts` or `.test.js` instead of just `.ts`/`.js`.
+ */
+declare function extname(
+  pathOrFilename: string,
+  options?: { full?: boolean }
+): string;
+
+/**
+ * Return the contents of a directory, as absolute paths. `.` and `..` are
+ * omitted.
+ *
+ * Use the `relativePaths` option to get relative paths instead (relative to
+ * the parent directory).
+ */
+declare function ls(
+  dir?: string,
+  options?: { relativePaths?: boolean }
+): Array<string>;
+
+/**
+ * Print data to stdout using C-style format specifiers.
+ */
+declare function printf(format: string, ...args: Array<any>): void;
+
+/**
+ * Return the process's current working directory.
+ *
+ * Provides the same functionality as the shell builtin of the same name.
+ */
+declare function pwd(): string;
+
+/**
+ * Read a symlink.
+ *
+ * Returns the target of the symlink, which may be absolute or relative.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function readlink(path: string): string;
+
+/**
+ * Get the absolute path given a relative path. Symlinks are also resolved.
+ *
+ * The path's target file/directory must exist.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function realpath(path: string): string;
+
+/**
+ * If the file at `path` exists, update its creation/modification timestamps.
+ *
+ * Otherwise, create an empty file at that path.
+ *
+ * @param path The target path for the file.
+ */
+declare function touch(path: string): void;
+
+declare type BaseExecOptions = {
+  /** Sets the current working directory for the child process. */
+  cwd?: string;
+
+  /** Sets environment variables within the process. */
+  env?: { [key: string | number]: string | number | boolean };
+
+  /**
+   * If provided, this function will be called multiple times as `exec`
+   * runs, 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:
+   *
+   * ```js
+   * exec(["echo", "hi"], { trace: console.log });
+   * ```
+   */
+  trace?: (...args: Array<any>) => void;
+};
+
+declare interface Exec {
+  (args: Array<string> | string): void;
+
+  (args: Array<string> | string, options: Record<string, never>): void;
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: true;
+      /**
+       * If true, stdout and stderr will be collected into strings and returned
+       * instead of being printed to the screen.
+       *
+       * Defaults to false.
+       */
+      captureOutput: false;
+    }
+  ): void;
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: false;
+      /**
+       * If true, stdout and stderr will be collected into strings and returned
+       * instead of being printed to the screen.
+       *
+       * Defaults to false.
+       */
+      captureOutput: false;
+    }
+  ):
+    | { status: number; signal: undefined }
+    | { status: undefined; signal: number };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: false;
+    }
+  ):
+    | { status: number; signal: undefined }
+    | { status: undefined; signal: number };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: true;
+      /**
+       * If true, stdout and stderr will be collected into strings and returned
+       * instead of being printed to the screen.
+       *
+       * Defaults to false.
+       */
+      captureOutput: true;
+    }
+  ): { stdout: string; stderr: string };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * If true, stdout and stderr will be collected into strings and returned
+       * instead of being printed to the screen.
+       *
+       * Defaults to false.
+       */
+      captureOutput: true;
+    }
+  ): { stdout: string; stderr: string };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: false;
+      captureOutput: true;
+    }
+  ):
+    | { stdout: string; stderr: string; status: number; signal: undefined }
+    | { stdout: string; stderr: string; status: undefined; signal: number };
+}
+
+/** Run a child process using the provided arguments. The first value in the arguments array is the program to run. */
+declare const exec: Exec;
+
+/** Alias for `exec(args, { captureOutput: true })` */
+declare function $(args: Array<string> | string): {
+  stdout: string;
+  stderr: string;
+};
+
+/**
+ * Options for {@link glob}.
+ */
+declare type GlobOptions = {
+  /**
+   * Whether to treat symlinks to directories as if they themselves were
+   * directories, traversing into them.
+   *
+   * Defaults to false.
+   */
+  followSymlinks?: boolean;
+
+  /**
+   * If provided, this function will be called multiple times as `glob`
+   * 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:
+   *
+   * ```js
+   * glob(["./*.js"], { trace: console.log });
+   * ```
+   */
+  trace?: (...args: Array<any>) => void;
+
+  /**
+   * Directory to interpret glob patterns relative to. Defaults to `pwd()`.
+   */
+  dir?: string;
+};
+
+/**
+ * Search the filesystem for files matching the specified glob patterns.
+ *
+ * Uses [minimatch](https://www.npmjs.com/package/minimatch) with its default
  * options.
  */
 declare function glob(
-  dir: string,
-  patterns: Array<string>,
+  patterns: string | Array<string>,
   options?: GlobOptions
 ): Array<string>;
 
-// ---------------
-// --- console ---
-// ---------------
+/**
+ * Remove ANSI control characters from a string.
+ */
+declare function stripAnsi(input: string): string;
 
 /**
- * Print one or more values to stdout.
+ * Wrap a string in double quotes, and escape any double-quotes inside using `\"`.
+ */
+declare function quote(input: string): string;
+
+/**
+ * Clear the contents and scrollback buffer of the tty by printing special characters into stdout.
+ */
+declare function clear(): void;
+
+// Colors
+
+/** Wrap a string with the ANSI control characters that will make it print as black text. */
+declare function black(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as red text. */
+declare function red(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as green text. */
+declare function green(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as yellow text. */
+declare function yellow(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as blue text. */
+declare function blue(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as magenta text. */
+declare function magenta(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as cyan text. */
+declare function cyan(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as white text. */
+declare function white(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as gray text. */
+declare function gray(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print as grey text. */
+declare function grey(input: string | number): string;
+
+// Background Colors
+
+/** Wrap a string with the ANSI control characters that will make it have a black background. */
+declare function bgBlack(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it have a red background. */
+declare function bgRed(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it have a green background. */
+declare function bgGreen(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it have a yellow background. */
+declare function bgYellow(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it have a blue background. */
+declare function bgBlue(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it have a magenta background. */
+declare function bgMagenta(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it have a cyan background. */
+declare function bgCyan(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it have a white background. */
+declare function bgWhite(input: string | number): string;
+
+// Modifiers
+
+/** Wrap a string with the ANSI control character that resets all styling. */
+declare function reset(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print with a bold style. */
+declare function bold(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print with a dimmed style. */
+declare function dim(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print italicized. */
+declare function italic(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print underlined. */
+declare function underline(input: string | number): string;
+/** Wrap a string with ANSI control characters such that its foreground (text) and background colors are swapped. */
+declare function inverse(input: string | number): string;
+/** Wrap a string with ANSI control characters such that it is hidden. */
+declare function hidden(input: string | number): string;
+/** Wrap a string with the ANSI control characters that will make it print with a horizontal line through its center. */
+declare function strikethrough(input: string | number): string;
+
+/** Split `str` on newline and then return lines matching `pattern`. */
+declare const grepString: {
+  /** Split `str` on newline and then return lines matching `pattern`. */
+  (str: string, pattern: string | RegExp): Array<string>;
+
+  /** Split `str` on newline and then return lines matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: false }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return lines NOT matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: true }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return lines matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { details: false }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return lines matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: false; details: false }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return lines NOT matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: true; details: false }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return info about lines matching `pattern`. */
+  (str: string, pattern: string | RegExp, options: { details: true }): Array<{
+    lineNumber: number;
+    lineContent: string;
+    matches: RegExpMatchArray;
+  }>;
+
+  /** Split `str` on newline and then return info about lines matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: false; details: true }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return info about lines NOT matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: true; details: true }
+  ): Array<string>;
+};
+
+/** Read the content at `path`, split it on newline, and then return lines matching `pattern`. */
+declare const grepFile: {
+  /** Read the content at `path`, split it on newline,  and then return lines matching `pattern`. */
+  (path: string, pattern: string | RegExp): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: false }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines NOT matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: true }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { details: false }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: false; details: false }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines NOT matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: true; details: false }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return info about lines matching `pattern`. */
+  (path: string, pattern: string | RegExp, options: { details: true }): Array<{
+    lineNumber: number;
+    lineContent: string;
+    matches: RegExpMatchArray;
+  }>;
+
+  /** Read the content at `path`, split it on newline,  and then return info about lines matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: false; details: true }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return info about lines NOT matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: true; details: true }
+  ): Array<string>;
+};
+
+interface String {
+  // Same as grepString but without the first argument.
+  grep: {
+    /** Split the string on newline and then return lines matching `pattern`. */
+    (pattern: string | RegExp): Array<string>;
+
+    /** Split the string on newline and then return lines matching `pattern`. */
+    (pattern: string | RegExp, options: { inverse: false }): Array<string>;
+
+    /** Split the string on newline and then return lines NOT matching `pattern`. */
+    (pattern: string | RegExp, options: { inverse: true }): Array<string>;
+
+    /** Split the string on newline and then return lines matching `pattern`. */
+    (pattern: string | RegExp, options: { details: false }): Array<string>;
+
+    /** Split the string on newline and then return lines matching `pattern`. */
+    (
+      pattern: string | RegExp,
+      options: { inverse: false; details: false }
+    ): Array<string>;
+
+    /** Split the string on newline and then return lines NOT matching `pattern`. */
+    (
+      pattern: string | RegExp,
+      options: { inverse: true; details: false }
+    ): Array<string>;
+
+    /** Split the string on newline and then return info about lines matching `pattern`. */
+    (pattern: string | RegExp, options: { details: true }): Array<{
+      lineNumber: number;
+      lineContent: string;
+      matches: RegExpMatchArray;
+    }>;
+
+    /** Split the string on newline and then return info about lines matching `pattern`. */
+    (
+      pattern: string | RegExp,
+      options: { inverse: false; details: true }
+    ): Array<string>;
+
+    /** Split the string on newline and then return info about lines NOT matching `pattern`. */
+    (
+      pattern: string | RegExp,
+      options: { inverse: true; details: true }
+    ): Array<string>;
+  };
+}
+
+declare type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array;
+declare type TypedArrayConstructor =
+  | Int8ArrayConstructor
+  | Uint8ArrayConstructor
+  | Uint8ClampedArrayConstructor
+  | Int16ArrayConstructor
+  | Uint16ArrayConstructor
+  | Int32ArrayConstructor
+  | Uint32ArrayConstructor
+  | Float32ArrayConstructor
+  | Float64ArrayConstructor;
+
+declare const is: {
+  string(value: any): value is string;
+  String(value: any): value is string;
+  number(value: any): value is number;
+  Number(value: any): value is number;
+  boolean(value: any): value is boolean;
+  Boolean(value: any): value is boolean;
+  bigint(value: any): value is bigint;
+  BigInt(value: any): value is bigint;
+  symbol(value: any): value is symbol;
+  Symbol(value: any): value is symbol;
+  null(value: any): value is null;
+  undefined(value: any): value is undefined;
+  void(value: any): value is null | undefined;
+  object(value: any): value is {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Object(value: any): value is {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Array(value: any): value is unknown[];
+  function(value: any): value is Function & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Function(value: any): value is Function & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  tagged(value: any, tag: string): boolean;
+  instanceOf<T>(value: any, klass: new (...args: any) => T): value is T;
+  Error(value: any): value is Error;
+  Infinity(value: any): value is number;
+  NegativeInfinity(value: any): value is number;
+  NaN(value: any): value is number;
+  Date(value: any): value is Date;
+  RegExp(value: any): value is RegExp;
+  Map(value: any): value is Map<unknown, unknown>;
+  Set(value: any): value is Set<unknown>;
+  WeakMap(value: any): value is Map<unknown, unknown>;
+  WeakSet(value: any): value is Set<unknown>;
+  ArrayBuffer(value: any): value is ArrayBuffer;
+  SharedArrayBuffer(value: any): value is SharedArrayBuffer;
+  DataView(value: any): value is DataView;
+  TypedArray(value: any): value is TypedArray;
+  Int8Array(value: any): value is Int8Array;
+  Uint8Array(value: any): value is Uint8Array;
+  Uint8ClampedArray(value: any): value is Uint8ClampedArray;
+  Int16Array(value: any): value is Int16Array;
+  Uint16Array(value: any): value is Uint16Array;
+  Int32Array(value: any): value is Int32Array;
+  Uint32Array(value: any): value is Uint32Array;
+  Float32Array(value: any): value is Float32Array;
+  Float64Array(value: any): value is Float64Array;
+  Promise(value: any): value is Promise<unknown>;
+  Generator(value: any): value is Generator<unknown, any, unknown>;
+  GeneratorFunction(value: any): value is GeneratorFunction;
+  AsyncFunction(value: any): value is ((...args: any) => Promise<unknown>) & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  AsyncGenerator(value: any): value is AsyncGenerator<unknown, any, unknown>;
+  AsyncGeneratorFunction(value: any): value is AsyncGeneratorFunction;
+
+  FILE(value: any): value is FILE;
+
+  JSX: {
+    /** Returns whether `value` is a JSX Element object as created via JSX syntax. */
+    Element(value: any): value is JSX.Element;
+    /** Returns whether `value` is a JSX fragment element as created via JSX syntax. */
+    Fragment(value: any): value is JSX.Fragment;
+  };
+};
+
+declare const assert: {
+  /**
+   * Throws an error if `value` is not truthy.
+   *
+   * @param value - The value to test for truthiness
+   * @param message - An optional error message to use. If unspecified, "Assertion failed" will be used.
+   */
+  <ValueType>(
+    value: ValueType,
+    message?: string
+  ): asserts value is ValueType extends null | undefined | false | 0 | ""
+    ? never
+    : ValueType;
+
+  string(value: any, message?: string): asserts value is string;
+  String(value: any, message?: string): asserts value is string;
+  number(value: any, message?: string): asserts value is number;
+  Number(value: any, message?: string): asserts value is number;
+  boolean(value: any, message?: string): asserts value is boolean;
+  Boolean(value: any, message?: string): asserts value is boolean;
+  bigint(value: any, message?: string): asserts value is bigint;
+  BigInt(value: any, message?: string): asserts value is bigint;
+  symbol(value: any, message?: string): asserts value is symbol;
+  Symbol(value: any, message?: string): asserts value is symbol;
+  null(value: any, message?: string): asserts value is null;
+  undefined(value: any, message?: string): asserts value is undefined;
+  void(value: any, message?: string): asserts value is null | undefined;
+  object(
+    value: any,
+    message?: string
+  ): asserts value is {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Object(
+    value: any,
+    message?: string
+  ): asserts value is {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Array(value: any, message?: string): asserts value is unknown[];
+  function(
+    value: any,
+    message?: string
+  ): asserts value is Function & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Function(
+    value: any,
+    message?: string
+  ): asserts value is Function & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  tagged(value: any, tag: string, message?: string): void;
+  instanceOf<T>(value: any, klass: new (...args: any) => T): asserts value is T;
+  Error(value: any, message?: string): asserts value is Error;
+  Infinity(value: any, message?: string): asserts value is number;
+  NegativeInfinity(value: any, message?: string): asserts value is number;
+  NaN(value: any, message?: string): asserts value is number;
+  Date(value: any, message?: string): asserts value is Date;
+  RegExp(value: any, message?: string): asserts value is RegExp;
+  Map(value: any, message?: string): asserts value is Map<unknown, unknown>;
+  Set(value: any, message?: string): asserts value is Set<unknown>;
+  WeakMap(value: any, message?: string): asserts value is Map<unknown, unknown>;
+  WeakSet(value: any, message?: string): asserts value is Set<unknown>;
+  ArrayBuffer(value: any, message?: string): asserts value is ArrayBuffer;
+  SharedArrayBuffer(
+    value: any,
+    message?: string
+  ): asserts value is SharedArrayBuffer;
+  DataView(value: any, message?: string): asserts value is DataView;
+  TypedArray(value: any, message?: string): asserts value is TypedArray;
+  Int8Array(value: any, message?: string): asserts value is Int8Array;
+  Uint8Array(value: any, message?: string): asserts value is Uint8Array;
+  Uint8ClampedArray(
+    value: any,
+    message?: string
+  ): asserts value is Uint8ClampedArray;
+  Int16Array(value: any, message?: string): asserts value is Int16Array;
+  Uint16Array(value: any, message?: string): asserts value is Uint16Array;
+  Int32Array(value: any, message?: string): asserts value is Int32Array;
+  Uint32Array(value: any, message?: string): asserts value is Uint32Array;
+  Float32Array(value: any, message?: string): asserts value is Float32Array;
+  Float64Array(value: any, message?: string): asserts value is Float64Array;
+  Promise(value: any, message?: string): asserts value is Promise<unknown>;
+  Generator(
+    value: any,
+    message?: string
+  ): asserts value is Generator<unknown, any, unknown>;
+  GeneratorFunction(
+    value: any,
+    message?: string
+  ): asserts value is GeneratorFunction;
+  AsyncFunction(
+    value: any,
+    message?: string
+  ): asserts value is ((...args: any) => Promise<unknown>) & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  AsyncGenerator(
+    value: any
+  ): asserts value is AsyncGenerator<unknown, any, unknown>;
+  AsyncGeneratorFunction(
+    value: any,
+    message?: string
+  ): asserts value is AsyncGeneratorFunction;
+
+  FILE(value: any, message?: string): asserts value is FILE;
+
+  JSX: {
+    /** Returns whether `value` is a JSX Element object as created via JSX syntax. */
+    Element(value: any, message?: string): asserts value is JSX.Element;
+    /** Returns whether `value` is a JSX fragment element as created via JSX syntax. */
+    Fragment(value: any, message?: string): asserts value is JSX.Fragment;
+  };
+};
+
+/**
+ * The data source of a pipe operation; either an in-memory object, or a
+ * file stream.
+ *
+ * - Use `maxLength` to limit how much data to read.
+ * - Use `until` to stop reading once a certain byte or character has been
+ *   read.
+ * - Use `path` or `fd` to open a file.
+ */
+declare type PipeSource =
+  | { data: string; maxLength?: number; until?: string | byte }
+  | ArrayBuffer
+  | { data: ArrayBuffer; maxLength?: number; until?: string | byte }
+  | SharedArrayBuffer
+  | { data: SharedArrayBuffer; maxLength?: number; until?: string | byte }
+  | TypedArray
+  | { data: TypedArray; maxLength?: number; until?: string | byte }
+  | DataView
+  | { data: DataView; maxLength?: number; until?: string | byte }
+  | FILE
+  | {
+      data: FILE;
+      maxLength?: number;
+      until?: string | byte;
+    }
+  | { path: string; maxLength?: number; until?: string | byte }
+  | { fd: number; maxLength?: number; until?: string | byte };
+
+/**
+ * The target destination of a pipe operation; either an in-memory object, or a
+ * file stream.
+ *
+ * - Use `intoExisting` to put data into an existing object or file handle.
+ * - Use `intoNew` to put data into a new object.
+ * - Use `path` or `fd` to create a new file handle and put data into it.
+ */
+declare type PipeDestination =
+  | ArrayBuffer
+  | SharedArrayBuffer
+  | DataView
+  | TypedArray
+  | FILE
+  | ArrayBufferConstructor
+  | SharedArrayBufferConstructor
+  | DataViewConstructor
+  | TypedArrayConstructor
+  | StringConstructor
+  | { path: string }
+  | { fd: number };
+
+/**
+ * Copy data from one source into the given target. Returns the number of bytes
+ * written, and the target that data was written into.
+ */
+declare function pipe<Dest extends PipeDestination>(
+  from: PipeSource,
+  to: Dest
+): {
+  bytesTransferred: number;
+  target: Dest extends
+    | ArrayBuffer
+    | SharedArrayBuffer
+    | DataView
+    | FILE
+    | { path: string }
+    | { fd: number }
+    ? Dest
+    : Dest extends
+        | ArrayBufferConstructor
+        | SharedArrayBufferConstructor
+        | DataViewConstructor
+        | TypedArrayConstructor
+        | DataViewConstructor
+    ? Dest["prototype"]
+    : Dest extends StringConstructor
+    ? string
+    : never;
+};
+
+/**
+ * Launch the Yavascript REPL (read-eval-print-loop).
+ *
+ * @param context Variables to make available as globals within the repl.
+ * @param lang The langauge to use in the repl. Defaults to "javascript".
+ */
+declare function startRepl(
+  context?: { [key: string]: any },
+  lang?:
+    | "js"
+    | "javascript"
+    | "ts"
+    | "typescript"
+    | "jsx"
+    | "tsx"
+    | "coffee"
+    | "coffeescript"
+): void;
+
+/**
+ * Returns the absolute path to the root folder of the git/hg repo.
+ *
+ * This is done by running `git rev-parse --show-toplevel` and `hg root`.
+ *
+ * If `relativeTo` is provided, the git and hg commands will be executed in
+ * that folder instead of in `pwd()`.
  */
-declare const echo: typeof console.log;
-
-// ---------------
-// --- strings ---
-// ---------------
+declare function repoRoot(relativeTo?: string): string;
 
 /**
- * Remove ANSI control characters from a string.
+ * Returns whether the provided path is ignored by git.
  */
-declare function stripAnsi(input: string): string;
+declare function isGitignored(path: string): boolean;
 
 /**
- * Wrap a string in double quotes, and escape any double-quotes inside using `\"`.
+ * Configures the default value of `trace` in functions which receive `trace`
+ * as an option.
+ *
+ * - If called with `true`, the default value of `trace` in all functions which
+ *   receive a `trace` option will be changed to `console.error`.
+ * - If called with `false`, the default value of `trace` in all functions which
+ *   receive a `trace` option will be changed to `undefined`.
+ * - If called with any other value, the provided value will be used as the
+ *   default value of `trace` in all functions which receive a `trace` option.
+ *
+ * If you would like to make your own functions use the default value of
+ * `trace` as set by this function (in order to get the same behavior as
+ * yavascript API functions which do so), call `traceAll.getDefaultTrace()` to
+ * get the value which should be used as the default value.
  */
-declare function quote(input: string): string;
+declare const traceAll: ((
+  trace: boolean | undefined | ((...args: Array<any>) => void)
+) => void) & {
+  getDefaultTrace(): ((...args: Array<any>) => void) | undefined;
+};
 
-// Colors
+declare namespace JSX {
+  /**
+   * A string containing the expression that should be called to create JSX
+   * elements.
+   *
+   * Defaults to "JSX.createElement".
+   *
+   * If changed, any JSX code loaded afterwards will use a different
+   * expression.
+   *
+   * Note that if you change this, you need to verify that the following
+   * expression always evaluates to `true` (by changing {@link is.JSX.Element}
+   * and {@link is.JSX.Fragment}):
+   * ```jsx
+   * is.JSX.Element(<a />) && is.JSX.Fragment(<></>)
+   * ```
+   *
+   * Failure to uphold this guarantee indicates a bug.
+   */
+  export let pragma: string;
 
-/** Wrap a string with the ANSI control characters that will make it print as black text. */
-declare function black(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as red text. */
-declare function red(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as green text. */
-declare function green(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as yellow text. */
-declare function yellow(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as blue text. */
-declare function blue(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as magenta text. */
-declare function magenta(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as cyan text. */
-declare function cyan(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as white text. */
-declare function white(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as gray text. */
-declare function gray(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print as grey text. */
-declare function grey(input: string | number): string;
+  /**
+   * A string containing the expression that should be used as the first
+   * parameter when creating JSX fragment elements.
+   *
+   * Defaults to "JSX.Fragment".
+   *
+   * If changed, any JSX code loaded afterwards will use a different
+   * expression.
+   *
+   * Note that if you change this, you need to verify that the following
+   * expression always evaluates to `true` (by changing {@link is.JSX.Element}
+   * and {@link is.JSX.Fragment}):
+   * ```jsx
+   * is.JSX.Element(<a />) && is.JSX.Fragment(<></>)
+   * ```
+   *
+   * Failure to uphold this guarantee indicates a bug.
+   */
+  export let pragmaFrag: string;
+
+  export const Element: unique symbol;
+
+  export interface Element<
+    Props = { [key: string | symbol | number]: any },
+    Type = any
+  > {
+    $$typeof: typeof Element;
+    type: Type;
+    props: Props;
+    key: string | number | null;
+  }
 
-// Background Colors
+  /**
+   * The value which gets passed into the JSX element constructor (as
+   * determined by {@link JSX.pragma}) when JSX fragment syntax is used (unless
+   * {@link JSX.pragmaFrag} is changed).
+   */
+  export const Fragment: unique symbol;
 
-/** Wrap a string with the ANSI control characters that will make it have a black background. */
-declare function bgBlack(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it have a red background. */
-declare function bgRed(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it have a green background. */
-declare function bgGreen(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it have a yellow background. */
-declare function bgYellow(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it have a blue background. */
-declare function bgBlue(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it have a magenta background. */
-declare function bgMagenta(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it have a cyan background. */
-declare function bgCyan(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it have a white background. */
-declare function bgWhite(input: string | number): string;
+  export type Fragment = Element<{}, typeof Fragment>;
 
-// Modifiers
+  /**
+   * The JSX element constructor, which gets invoked whenever JSX syntax is
+   * used (unless {@link JSX.pragma} is changed).
+   */
+  export const createElement: {
+    <Type extends string | typeof Fragment | ((...args: any) => any)>(
+      type: Type
+    ): Element<{}, Type>;
+    <
+      Type extends string | typeof Fragment | ((...args: any) => any),
+      Props extends { [key: string | number | symbol]: any }
+    >(
+      type: Type,
+      props: Props
+    ): Element<Props, Type>;
+
+    <
+      Type extends string | typeof Fragment | ((...args: any) => any),
+      Props extends { [key: string | number | symbol]: any },
+      Children extends Array<any>
+    >(
+      type: Type,
+      props: Props,
+      ...children: Children
+    ): Element<Props & { children: Children }, Type>;
+
+    <
+      Type extends string | typeof Fragment | ((...args: any) => any),
+      Children extends Array<any>
+    >(
+      type: Type,
+      ...children: Children
+    ): Element<{ children: Children }, Type>;
+  };
+}
 
-/** Wrap a string with the ANSI control character that resets all styling. */
-declare function reset(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print with a bold style. */
-declare function bold(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print with a dimmed style. */
-declare function dim(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print italicized. */
-declare function italic(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print underlined. */
-declare function underline(input: string | number): string;
-/** Wrap a string with ANSI control characters such that its foreground (text) and background colors are swapped. */
-declare function inverse(input: string | number): string;
-/** Wrap a string with ANSI control characters such that it is hidden. */
-declare function hidden(input: string | number): string;
-/** Wrap a string with the ANSI control characters that will make it print with a horizontal line through its center. */
-declare function strikethrough(input: string | number): string;
+declare const YAML: {
+  /**
+   * Parse a YAML document (`input`) into a JSON-compatible value.
+   */
+  parse(
+    input: string,
+    reviver?: (this: any, key: string, value: any) => any
+  ): any;
 
+  /**
+   * Convert a JSON-compatible value into a YAML document.
+   */
+  stringify(
+    input: any,
+    replacer?:
+      | ((this: any, key: string, value: any) => any)
+      | (number | string)[]
+      | null,
+    indent?: number
+  ): string;
+};
+
+declare const CSV: {
+  /**
+   * Parse a CSV string into an Array of Arrays of strings.
+   *
+   * The outer array holds the rows, and the inner arrays hold the items in
+   * each row.
+   */
+  parse(input: string): Array<Array<string>>;
+
+  /**
+   * Convert an Array of Arrays of strings into a CSV string.
+   *
+   * The outer array holds the rows, and the inner arrays hold the items in
+   * each row.
+   */
+  stringify(input: Array<Array<string>>): string;
+};
+
+interface RegExpConstructor {
+  /** See https://github.com/tc39/proposal-regex-escaping */
+  escape(str: any): string;
+}
+
+// prettier-ignore
+/** Any integer in the range [0, 255]. */
+declare type byte =
+|   0 |   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 |  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 | 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 | 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 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 
+| 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 
+| 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 
+| 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 
+| 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255;
+
+// Convenience aliases to provide parity with TypeScript types.
+declare var number: NumberConstructor;
+declare var string: StringConstructor;
+declare var boolean: BooleanConstructor;
+declare var bigint: BigIntConstructor;
+declare var symbol: SymbolConstructor;
+
+// ==========================================
 // ------------------------------------------
 // QuickJS APIs, which YavaScript builds upon
 // ------------------------------------------
-
+// ==========================================
 // Definitions of the globals and modules added by quickjs-libc
 
 /**
@@ -569,6 +1452,91 @@ declare var console: {
   info: typeof print;
 };
 
+/** An object representing a file handle. */
+declare interface FILE {
+  /**
+   * Human-readable description of where this FILE points.
+   *
+   * If `target` is a number, the FILE was opened with fdopen, and `target` is
+   * the fd. Otherwise, `target` will be an arbitrary string that describes the
+   * file; it may be the absolute path to the file, the relative path to the
+   * file at time of its opening, or some other string like "stdin" or
+   * "tmpfile".
+   *
+   * You should *not* use this property for anything other than logging and
+   * debugging. It is *only* provided for debugging and/or troubleshooting
+   * purposes. The value of this property could change at any time when
+   * upgrading yavascript, even if upgrading by a minor or patch release.
+   */
+  target: string | number;
+
+  /**
+   * Close the file handle. Note that for files other than stdin/stdout/stderr,
+   * the file will be closed automatically when the `FILE` object is
+   * garbage-collected.
+   */
+  close(): void;
+
+  /** Outputs the string with the UTF-8 encoding. */
+  puts(...strings: Array<string>): void;
+
+  /**
+   * Formatted printf.
+   *
+   * The same formats as the standard C library `printf` are supported. Integer format types (e.g. `%d`) truncate the Numbers or BigInts to 32 bits. Use the `l` modifier (e.g. `%ld`) to truncate to 64 bits.
+   */
+  printf(fmt: string, ...args: Array<any>): void;
+
+  /** Flush the buffered file. Wrapper for C `fflush`. */
+  flush(): void;
+
+  /** Sync the buffered file to disk. Wrapper for C `fsync`. */
+  sync(): void;
+
+  /**
+   * Seek to a given file position (whence is `std.SEEK_*`).
+   *
+   * `offset` can be a number or a bigint.
+   */
+  seek(offset: number, whence: number): void;
+
+  /** Return the current file position. */
+  tell(): number;
+
+  /** Return the current file position as a bigint. */
+  tello(): BigInt;
+
+  /** Return true if end of file. */
+  eof(): boolean;
+
+  /** Return the associated OS handle. */
+  fileno(): number;
+
+  /** Read `length` bytes from the file to the ArrayBuffer `buffer` at byte position `position` (wrapper to the libc `fread`). Returns the number of bytes read, or `0` if the end of the file has been reached.  */
+  read(buffer: ArrayBuffer, position: number, length: number): number;
+
+  /** Write `length` bytes from the ArrayBuffer `buffer` at byte position `position` into the file (wrapper to the libc `fwrite`). Returns the number of bytes written. */
+  write(buffer: ArrayBuffer, position: number, length: number): number;
+
+  /**
+   * Return the next line from the file, assuming UTF-8 encoding, excluding the trailing line feed or EOF.
+   *
+   * If the end of the file has been reached, then `null` will be returned instead of a string.
+   *
+   * Note: Although the trailing line feed has been removed, a carriage return (`\r`) may still be present.
+   */
+  getline(): string | null;
+
+  /** Read `maxSize` bytes from the file and return them as a string assuming UTF-8 encoding. If `maxSize` is not present, the file is read up its end. */
+  readAsString(maxSize?: number): string;
+
+  /** Return the next byte from the file. Return -1 if the end of file is reached. */
+  getByte(): number;
+
+  /** Write one byte to the file. */
+  putByte(value: number): void;
+}
+
 declare module "std" {
   /**
    * Exit the process with the provided status code.
@@ -610,6 +1578,15 @@ declare module "std" {
     basename?: string
   ): { [key: string]: any };
 
+  /**
+   * Return the resolved path to a module.
+   *
+   * @param filename - The relative or absolute path to the file to import. Relative paths are resolved relative to the file calling `importModule`, or `basename` if present.
+   * @param basename - If present and `filename` is a relative path, `filename` will be resolved relative to this basename.
+   * @returns The resolved module path.
+   */
+  export function resolveModule(filename: string, basename?: string): string;
+
   /**
    * Load the file `filename` and return it as a string assuming UTF-8 encoding.
    *
@@ -624,7 +1601,15 @@ declare module "std" {
    *
    * @param stackLevels - How many levels up the stack to search for a filename. Defaults to 0, which uses the current stack frame.
    */
-  export function getFileNameFromStack(stackLevels: number): string;
+  export function getFileNameFromStack(stackLevels?: number): string;
+
+  /**
+   * Return a boolean indicating whether the provided value is a FILE object.
+   *
+   * @param value - The value to check.
+   * @returns Whether the value was a `FILE` or not.
+   */
+  export function isFILE(value: any): boolean;
 
   /**
    * Open a file (wrapper to the libc `fopen()`).
@@ -665,7 +1650,7 @@ declare module "std" {
   export function tmpfile(): FILE;
 
   /** Equivalent to `std.out.puts(str)`. */
-  export function puts(str: string): void;
+  export function puts(...strings: Array<string>): void;
 
   /** Equivalent to `std.out.printf(fmt, ...args)` */
   export function printf(fmt: string, ...args: Array<any>): void;
@@ -825,68 +1810,6 @@ declare module "std" {
    * - octal (0o prefix) and hexadecimal (0x prefix) numbers
    */
   export function parseExtJSON(str: string): any;
-
-  /** An object representing a file handle. */
-  export class FILE {
-    /** Close the file.  */
-    close(): void;
-
-    /** Outputs the string with the UTF-8 encoding. */
-    puts(str: string): void;
-
-    /**
-     * Formatted printf.
-     *
-     * The same formats as the standard C library `printf` are supported. Integer format types (e.g. `%d`) truncate the Numbers or BigInts to 32 bits. Use the `l` modifier (e.g. `%ld`) to truncate to 64 bits.
-     */
-    printf(fmt: string, ...args: Array<any>): void;
-
-    /** Flush the buffered file. Wrapper for C `fflush`. */
-    flush(): void;
-
-    /** Sync the buffered file to disk. Wrapper for C `fsync`. */
-    sync(): void;
-
-    /**
-     * Seek to a given file position (whence is `std.SEEK_*`).
-     *
-     * `offset` can be a number or a bigint.
-     */
-    seek(
-      offset: number,
-      whence: typeof SEEK_SET | typeof SEEK_CUR | typeof SEEK_END
-    ): void;
-
-    /** Return the current file position. */
-    tell(): number;
-
-    /** Return the current file position as a bigint. */
-    tello(): BigInt;
-
-    /** Return true if end of file. */
-    eof(): boolean;
-
-    /** Return the associated OS handle. */
-    fileno(): number;
-
-    /** Read `length` bytes from the file to the ArrayBuffer `buffer` at byte position `position` (wrapper to the libc `fread`). Returns the number of bytes read, or `0` if the end of the file has been reached.  */
-    read(buffer: ArrayBuffer, position: number, length: number): number;
-
-    /** Write `length` bytes from the ArrayBuffer `buffer` at byte position `position` into the file (wrapper to the libc `fwrite`). Returns the number of bytes written. */
-    write(buffer: ArrayBuffer, position: number, length: number): number;
-
-    /** Return the next line from the file, assuming UTF-8 encoding, excluding the trailing line feed. */
-    getline(): string;
-
-    /** Read `maxSize` bytes from the file and return them as a string assuming UTF-8 encoding. If `maxSize` is not present, the file is read up its end. */
-    readAsString(maxSize?: number): string;
-
-    /** Return the next byte from the file. Return -1 if the end of file is reached. */
-    getByte(): number;
-
-    /** Write one byte to the file. */
-    putByte(value: number): void;
-  }
 }
 
 declare module "os" {
@@ -1151,6 +2074,24 @@ declare module "os" {
 
   /** Constant for the `options` argument of `waitpid`. */
   export var WNOHANG: number;
+  /** Constant for the `options` argument of `waitpid`. */
+  export var WUNTRACED: number;
+
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WEXITSTATUS(status: number): number;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WTERMSIG(status: number): number;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WSTOPSIG(status: number): number;
+
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WIFEXITED(status: number): boolean;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WIFSIGNALED(status: number): boolean;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WIFSTOPPED(status: number): boolean;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WIFCONTINUED(status: number): boolean;
 
   /** `dup` Unix system call. */
   export function dup(fd: number): number;
@@ -1164,16 +2105,19 @@ declare module "os" {
   /** Sleep for `delay_ms` milliseconds. */
   export function sleep(delay_ms: number): void;
 
-  export type Timer = number & { __is: "Timer" };
+  export type OSTimer = { [Symbol.toStringTag]: "OSTimer" };
 
   /** Call the function func after delay ms. Return a handle to the timer. */
-  export function setTimeout(func: () => void, delay: number): Timer;
+  export function setTimeout(
+    func: (...args: any) => any,
+    delay: number
+  ): OSTimer;
 
   /** Cancel a timer. */
-  export function clearTimeout(handle: Timer): void;
+  export function clearTimeout(handle: OSTimer): void;
 
-  /** Return a string representing the platform: "linux", "darwin", "win32" or "js". */
-  export var platform: "linux" | "darwin" | "win32" | "js";
+  /** Return a string representing the platform: "linux", "darwin", "win32", "freebsd", or "js" (emscripten). */
+  export var platform: "linux" | "darwin" | "win32" | "freebsd" | "js";
 
   /**
    * Things that can be put into Worker.postMessage.
@@ -1261,6 +2205,12 @@ declare module "os" {
 
   /** `access` Unix system call; checks if a file is readable, writable, executable, and/or exists (use {@link R_OK}, {@link W_OK}, {@link X_OK}, and/or {@link F_OK} for `accessMode`). Throws a descriptive error (with errno property) if the requested access is not available; otherwise, returns undefined. */
   export function access(path: string, accessMode: number): void;
+
+  /** gets the path to the executable which is executing this JS code. might be a relative path or symlink. */
+  export function execPath(): string;
+
+  /** changes the access permission bits of the file at `path` using the octal number `mode`. */
+  export function chmod(path: string, mode: number): void;
 }
 
 /**
@@ -1368,3 +2318,193 @@ declare interface InspectFunction {
  */
 declare var inspect: InspectFunction;
 
+/**
+ * A class which represents a module namespace object. Note, however, that
+ * instances of this class cannot be constructed manually, and must instead be
+ * obtained from `import * as`, `import()`, `std.importModule`, or `require`.
+ *
+ * The static properties on `Module` let you configure the module loader
+ * (import/export/require). You can use these properties to add support for
+ * importing new filetypes.
+ */
+declare class Module {
+  /** A module namespace object has arbitrary exports. */
+  [key: string | number | symbol]: any;
+
+  /**
+   * Module objects are not constructable.
+   *
+   * You must instead obtain them using import or require.
+   */
+  private constructor();
+
+  /**
+   * Returns true if `target` is a module namespace object.
+   */
+  static [Symbol.hasInstance](target: any): target is Module;
+
+  /**
+   * A list of filetype extensions that may be omitted from an import specifier
+   * string.
+   *
+   * Defaults to `[".js"]`. You can add more strings to this array to
+   * make the engine search for additional files when resolving a
+   * require/import.
+   *
+   * See the doc comment on {@link require} for more information.
+   *
+   * NOTE: If you add a new extension to this array, you will likely also want
+   * to add to {@link Module.compilers}.
+   */
+  static searchExtensions: Array<string>;
+
+  /**
+   * User-defined functions which will handle getting the JavaScript code
+   * associated with a module.
+   *
+   * The key for each property in this object should be a file extension
+   * string with a leading dot, eg `".jsx"`. The value for each property should
+   * be a function which receives (1) the filepath to a module, and (2) that
+   * file's content as a UTF-8 string, and the function should return a string
+   * containing JavaScript code that corresponds to that module. In most cases,
+   * these functions will compile the contents of the file from one format into JavaScript.
+   *
+   * The function does not have to use the second 'content' argument it
+   * receives (ie. when loading binary files).
+   *
+   * By adding to this object, you can make it possible to import non-js
+   * filetypes; compile-to-JS languages like JSX, TypeScript, and CoffeeScript
+   * can be compiled at import time, and asset files like .txt files or .png
+   * files can be converted into an appropriate data structure at import time.
+   *
+   * As an example, to make it possible to import .txt files, you might do:
+   * ```js
+   * import * as std from "std";
+   *
+   * Module.compilers[".txt"] = (filename, content) => {
+   *   return `export default ${JSON.stringify(content)}`;
+   * }
+   * ```
+   * (leveraging `JSON.stringify`'s ability to escape quotes).
+   *
+   * Then, later in your code, you can do:
+   * ```js
+   * import names from "./names.txt";
+   * ```
+   *
+   * And `names` will be a string containing the contents of names.txt.
+   *
+   * NOTE: When adding to this object, you may also wish to add to
+   * {@link Module.searchExtensions}.
+   */
+  static compilers: {
+    [extensionWithDot: string]: (filename: string, content: string) => string;
+  };
+
+  /**
+   * Create a virtual built-in module whose exports consist of the own
+   * enumerable properties of `obj`.
+   */
+  static define(name: string, obj: { [key: string]: any }): void;
+}
+
+/**
+ * Synchronously import a module.
+ *
+ * `source` will be resolved relative to the calling file.
+ *
+ * If `source` does not have a file extension, and a file without an extension
+ * cannot be found, the engine will check for files with the extensions in
+ * {@link Module.searchExtensions}, and use one of those if present. This
+ * behavior also happens when using normal `import` statements.
+ *
+ * For example, if you write:
+ *
+ * ```js
+ * import something from "./somewhere";
+ * ```
+ *
+ * but there's no file named `somewhere` in the same directory as the file
+ * where that import appears, and `Module.searchExtensions` is the default
+ * value:
+ *
+ * ```js
+ * [".js"]
+ * ```
+ *
+ * then the engine will look for `somewhere.js`. If that doesn't exist, the
+ * engine will look for `somewhere/index.js`. If *that* doesn't exist, an error
+ * will be thrown.
+ *
+ * If you add more extensions to `Module.searchExtensions`, then the engine
+ * will use those, too. It will search in the same order as the strings appear
+ * in the `Module.searchExtensions` array.
+ */
+declare var require: ((source: string) => { [key: string]: any }) & {
+  /**
+   * Resolves the normalized path to a modules, relative to the calling file.
+   */
+  resolve: (source: string) => string;
+};
+
+declare var setTimeout: typeof import("os").setTimeout;
+declare var clearTimeout: typeof import("os").clearTimeout;
+
+declare type Interval = { [Symbol.toStringTag]: "Interval" };
+
+declare function setInterval(func: (...args: any) => any, ms: number): Interval;
+declare function clearInterval(interval: Interval): void;
+
+interface StringConstructor {
+  /**
+   * A no-op template literal tag.
+   *
+   * https://github.com/tc39/proposal-string-cooked
+   */
+  cooked(
+    strings: readonly string[] | ArrayLike<string>,
+    ...substitutions: any[]
+  ): string;
+
+  /**
+   * Remove leading minimum indentation from the string.
+   * The first line of the string must be empty.
+   *
+   * https://github.com/tc39/proposal-string-dedent
+   */
+  dedent: {
+    /**
+     * Remove leading minimum indentation from the string.
+     * The first line of the string must be empty.
+     *
+     * https://github.com/tc39/proposal-string-dedent
+     */
+    (input: string): string;
+
+    /**
+     * Remove leading minimum indentation from the template literal.
+     * The first line of the string must be empty.
+     *
+     * https://github.com/tc39/proposal-string-dedent
+     */
+    (
+      strings: readonly string[] | ArrayLike<string>,
+      ...substitutions: any[]
+    ): string;
+
+    /**
+     * Wrap another template tag function such that tagged literals
+     * become dedented before being passed to the wrapped function.
+     *
+     * https://www.npmjs.com/package/string-dedent#usage
+     */
+    <
+      Func extends (
+        strings: readonly string[] | ArrayLike<string>,
+        ...substitutions: any[]
+      ) => string
+    >(
+      input: Func
+    ): Func;
+  };
+}