yavascript 0.0.10 → 0.0.12

package/yavascript.d.ts

@@ -24,8 +24,11 @@ declare var help: {
      *
      * If the value is later passed into the `help` function, the provided text
      * will be printed.
+     *
+     * To set help text for the values `null` or `undefined`, `allowNullish`
+     * must be `true`.
      */
-    (value: object, text: string): void;
+    (value: object, text: string, allowNullish?: boolean): void;
 
     /**
      * Lazily sets the help text for the provided value using the provided
@@ -99,6 +102,11 @@ declare const yavascript: {
       options?: { filename?: string; expression?: boolean }
     ): string;
 
+    civet(
+      code: string,
+      options?: { filename?: string; expression?: boolean }
+    ): string;
+
     autodetect(
       code: string,
       options?: { filename?: string; expression?: boolean }
@@ -244,14 +252,6 @@ declare function remove(path: string | Path): void;
  */
 declare function exists(path: string | Path): boolean;
 
-/**
- * Creates directories for each of the provided path components,
- * if they don't already exist.
- *
- * Provides the same functionality as the command `mkdir -p`.
- */
-declare function ensureDir(path: string | Path): string;
-
 /**
  * Options for {@link copy}.
  */
@@ -264,17 +264,34 @@ declare type CopyOptions = {
    */
   whenTargetExists?: "overwrite" | "skip" | "error";
 
-  /**
-   * 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:
-   *
-   * ```js
-   * copy("./source", "./destination", { trace: console.log });
-   * ```
-   */
-  trace?: (...args: Array<any>) => void;
+  /** Options which control logging. */
+  logging?: {
+    /**
+     * 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:
+     *
+     * ```js
+     * copy("./source", "./destination", {
+     *   logging: { trace: console.log },
+     * });
+     * ```
+     *
+     * Defaults to the current value of {@link logger.trace}. `logger.trace`
+     * defaults to a no-op function.
+     */
+    trace?: (...args: Array<any>) => void;
+
+    /**
+     * An optional, user-provided logging function to be used for informational
+     * messages.
+     *
+     * Defaults to the current value of {@link logger.info}. `logger.info`
+     * defaults to a function which writes to stderr.
+     */
+    info?: (...args: Array<any>) => void;
+  };
 };
 
 /**
@@ -307,6 +324,14 @@ declare class Path {
    */
   static readonly OS_ENV_VAR_SEPARATOR: ":" | ";";
 
+  /**
+   * A list of suffixes that could appear in the filename for a program on the
+   * current OS. For instance, on Windows, programs often end with ".exe".
+   *
+   * On Unix-like OSes, this is empty. On Windows, it's based on `env.PATHEXT`.
+   */
+  static readonly OS_PROGRAM_EXTENSIONS: ReadonlySet<string>;
+
   /** Split one or more path strings into an array of path segments. */
   static splitToSegments(inputParts: Array<string> | string): Array<string>;
 
@@ -321,25 +346,13 @@ declare class Path {
     fallback: Fallback = Path.OS_SEGMENT_SEPARATOR
   ): string | Fallback;
 
-  /** 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;
+  ): Path;
 
   /**
    * Return whether the provided path is absolute; that is, whether it
@@ -347,18 +360,6 @@ declare class Path {
    */
   static isAbsolute(path: string | Path): boolean;
 
-  /** A tagged template literal function that creates a `Path` object. */
-  static tag(
-    strings: TemplateStringsArray,
-    ...values: ReadonlyArray<string | Path | Array<string | Path>>
-  ): Path;
-
-  /**
-   * Returns a tagged template literal that creates a `Path` object. `dir` is
-   * used as a prefix for every `Path` object created.
-   */
-  static tagUsingBase(dir: string | Path): typeof Path.tag;
-
   /**
    * An array of the path segments that make up this path.
    *
@@ -378,17 +379,12 @@ declare class Path {
   /** 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.
+   * Create a new Path object using the provided segments and separator.
    *
-   * If `from` is unspecified, it defaults to `pwd()`.
+   * If unspecified, `separator` defaults to `Path.OS_SEGMENT_SEPARATOR`.
    */
-  resolve(from?: string | Path): Path;
+  static fromRaw(segments: Array<string>, separator?: string): Path;
 
   /**
    * Resolve all non-leading `.` and `..` segments in this path.
@@ -396,21 +392,22 @@ declare class Path {
   normalize(): Path;
 
   /**
-   * Create a new path by appending another path's segments after this path's
-   * segments.
+   * Create a new Path by appending additional path segments onto the end of
+   * this Path's segments.
    *
    * The returned path will use this path's separator.
    */
-  concat(other: string | Path | Array<string | Path>): Path;
+  concat(...other: Array<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:`).
+   * either `/`, `\`, or a drive letter (ie `C:`).
    */
   isAbsolute(): boolean;
 
   /**
-   * Make a second Path object containing the same information as this one.
+   * Make a second Path object containing the same segments and separator as
+   * this one.
    */
   clone(): this;
 
@@ -437,9 +434,122 @@ declare class Path {
   toString(): string;
 
   /**
-   * Alias for `toString`; causes Path objects to be serialized as strings.
+   * Alias for `toString`; causes Path objects to be serialized as strings when
+   * they (or an object referencing them) are passed into JSON.stringify.
    */
   toJSON(): string;
+
+  /**
+   * Return the final path segment of this path. If this path has no path
+   * segments, the empty string is returned.
+   */
+  basename(): string;
+
+  /**
+   * Return the trailing extension of this path. The `options` parameter works
+   * the same as the global `extname`'s `options` parameter.
+   */
+  extname(options?: { full?: boolean }): string;
+
+  /**
+   * Return a new Path containing all of the path segments in this one except
+   * for the last one; ie. the path to the directory that contains this path.
+   */
+  dirname(): Path;
+
+  /**
+   * Return whether this path starts with the provided value, by comparing one
+   * path segment at a time.
+   *
+   * The starting segments of this path must *exactly* match the segments in the
+   * provided value.
+   *
+   * This means that, given two Paths A and B:
+   *
+   * ```
+   *   A: Path { /home/user/.config }
+   *   B: Path { /home/user/.config2 }
+   * ```
+   *
+   * Path B does *not* start with Path A, because `".config" !== ".config2"`.
+   */
+  startsWith(value: string | Path | Array<string | Path>): boolean;
+
+  /**
+   * Return whether this path ends with the provided value, by comparing one
+   * path segment at a time.
+   *
+   * The ending segments of this path must *exactly* match the segments in the
+   * provided value.
+   *
+   * This means that, given two Paths A and B:
+   *
+   * ```
+   *   A: Path { /home/1user/.config }
+   *   B: Path { user/.config }
+   * ```
+   *
+   * Path A does *not* end with Path B, because `"1user" !== "user"`.
+   */
+  endsWith(value: string | Path | Array<string | Path>): boolean;
+
+  /**
+   * Return the path segment index at which `value` appears in this path, or
+   * `-1` if it doesn't appear in this path.
+   *
+   * @param value - The value to search for. If the value contains more than one path segment, the returned index will refer to the location of the value's first path segment.
+   * @param fromIndex - The index into this path's segments to begin searching at. Defaults to `0`.
+   */
+  indexOf(
+    value: string | Path | Array<string | Path>,
+    fromIndex?: number | undefined
+  ): number;
+
+  /**
+   * Return whether `value` appears in this path.
+   *
+   * @param value - The value to search for.
+   * @param fromIndex - The index into this path's segments to begin searching at. Defaults to `0`.
+   */
+  includes(
+    value: string | Path | Array<string | Path>,
+    fromIndex?: number | undefined
+  ): boolean;
+
+  /**
+   * Return a new Path wherein the segments in `value` have been replaced with
+   * the segments in `replacement`. If the segments in `value` are not present
+   * in this path, a clone of this path is returned.
+   *
+   * Note that only the first match is replaced.
+   *
+   * @param value - What should be replaced
+   * @param replacement - What it should be replaced with
+   */
+  replace(
+    value: string | Path | Array<string | Path>,
+    replacement: string | Path | Array<string | Path>
+  ): Path;
+
+  /**
+   * Return a new Path wherein all occurrences of the segments in `value` have
+   * been replaced with the segments in `replacement`. If the segments in
+   * `value` are not present in this path, a clone of this path is returned.
+   *
+   * @param value - What should be replaced
+   * @param replacement - What it should be replaced with
+   */
+  replaceAll(
+    value: string | Path | Array<string | Path>,
+    replacement: string | Path | Array<string | Path>
+  ): Path;
+
+  /**
+   * Return a copy of this path but with the final segment replaced with `replacement`
+   *
+   * @param replacement - The new final segment(s) for the returned Path
+   */
+  replaceLast(replacement: string | Path | Array<string | Path>): Path;
 }
 
 /**
@@ -464,10 +574,36 @@ declare var __dirname: string;
 declare function basename(path: string | Path): string;
 
 /**
- * Read the contents of one of more files from disk as one UTF-8 string,
- * print that string to stdout, then return it.
+ * Reads the contents of one or more files from disk as either one UTF-8 string
+ * or one ArrayBuffer.
  */
-declare function cat(...paths: Array<string | Path>): string;
+declare const cat: {
+  /**
+   * Read the contents of one or more files from disk, as one UTF-8 string.
+   */
+  (paths: string | Path | Array<string | Path>): string;
+
+  /**
+   * Read the contents of one or more files from disk, as one UTF-8 string.
+   */
+  (paths: string | Path | Array<string | Path>, options: {}): string;
+
+  /**
+   * Read the contents of one or more files from disk, as one UTF-8 string.
+   */
+  (
+    paths: string | Path | Array<string | Path>,
+    options: { binary: false }
+  ): string;
+
+  /**
+   * Read the contents of one or more files from disk, as one ArrayBuffer.
+   */
+  (
+    paths: string | Path | Array<string | Path>,
+    options: { binary: true }
+  ): ArrayBuffer;
+};
 
 /**
  * Change the process's current working directory to the specified path. If no
@@ -526,13 +662,29 @@ declare function chmod(
  *
  * Provides the same functionality as the unix binary of the same name.
  */
-declare function dirname(path: string | Path): string;
+declare function dirname(path: string | Path): Path;
 
 /**
  * Print one or more values to stdout.
  */
 declare const echo: typeof console.log;
 
+/**
+ * Exit the yavascript process.
+ *
+ * Provides the same functionality as the shell builtin of the same name.
+ *
+ * If exit is called with an argument, that argument is used as the exit code.
+ * Otherwise, `exit.code` is used, which defaults to 0.
+ *
+ * `exit.code` will also be used as the exit status code for the yavascript
+ * process if the process exits normally.
+ */
+declare const exit: {
+  (code?: number): never;
+  code: number;
+};
+
 /**
  * Returns the file extension of the file at a given path.
  *
@@ -548,14 +700,43 @@ declare function extname(
 /**
  * Returns the contents of a directory, as absolute paths. `.` and `..` are
  * omitted.
+ */
+declare function ls(dir?: string | Path): Array<Path>;
+
+/**
+ * Create a directory (folder).
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function mkdir(
+  path: string | Path,
+  options?: {
+    recursive?: boolean;
+    mode?: number;
+    logging?: {
+      trace?: (...args: Array<any>) => void;
+      info?: (...args: Array<any>) => void;
+    };
+  }
+): void;
+
+/**
+ * Create a directory (folder) and all parents, recursively
  *
- * Use the `relativePaths` option to get relative paths instead (relative to
- * the parent directory).
+ * Alias for `mkdir(path, { recursive: true })`.
+ *
+ * Provides the same functionality as `mkdir -p`.
  */
-declare function ls(
-  dir?: string | Path,
-  options?: { relativePaths?: boolean }
-): Array<string>;
+declare function mkdirp(
+  path: string | Path,
+  options?: {
+    mode?: number;
+    logging?: {
+      trace?: (...args: Array<any>) => void;
+      info?: (...args: Array<any>) => void;
+    };
+  }
+): void;
 
 /**
  * Print data to stdout using C-style format specifiers.
@@ -571,7 +752,20 @@ declare function printf(format: string, ...args: Array<any>): void;
  *
  * Provides the same functionality as the shell builtin of the same name.
  */
-declare function pwd(): string;
+declare const pwd: {
+  /**
+   * Returns the process's current working directory.
+   *
+   * Provides the same functionality as the shell builtin of the same name.
+   */
+  (): Path;
+
+  /**
+   * A frozen, read-only `Path` object containing what `pwd()` was when
+   * yavascript first started up.
+   */
+  readonly initial: Path;
+};
 
 /**
  * Reads a symlink.
@@ -580,7 +774,7 @@ declare function pwd(): string;
  *
  * Provides the same functionality as the unix binary of the same name.
  */
-declare function readlink(path: string | Path): string;
+declare function readlink(path: string | Path): Path;
 
 /**
  * Get the absolute path given a relative path. Symlinks are also resolved.
@@ -589,7 +783,7 @@ declare function readlink(path: string | Path): string;
  *
  * Provides the same functionality as the unix binary of the same name.
  */
-declare function realpath(path: string | Path): string;
+declare function realpath(path: string | Path): Path;
 
 /**
  * Blocks the current thread for at least the specified number of milliseconds,
@@ -634,6 +828,54 @@ declare var sleep: {
  */
 declare function touch(path: string | Path): void;
 
+/**
+ * Searches the system for the path to a program named `binaryName`.
+ *
+ * If the program can't be found, `null` is returned.
+ *
+ * @param binaryName The program to search for
+ * @param options Options which affect how the search is performed
+ * @param options.searchPaths A list of folders where programs may be found. Defaults to `env.PATH?.split(Path.OS_ENV_VAR_SEPARATOR) || []`.
+ * @param options.suffixes A list of filename extension suffixes to include in the search, ie [".exe"]. Defaults to `Path.OS_PROGRAM_EXTENSIONS`.
+ * @param options.trace A logging function that will be called at various times during the execution of `which`. Defaults to {@link logger.trace}.
+ */
+declare function which(
+  binaryName: string,
+  options?: {
+    /**
+     * A list of folders where programs may be found. Defaults to
+     * `env.PATH?.split(Path.OS_ENV_VAR_SEPARATOR) || []`.
+     */
+    searchPaths?: Array<Path | string>;
+
+    /**
+     * A list of filename extension suffixes to include in the search, ie
+     * `[".exe"]`. Defaults to {@link Path.OS_PROGRAM_EXTENSIONS}.
+     */
+    suffixes?: Array<string>;
+
+    /** Options which control logging. */
+    logging?: {
+      /**
+       * If provided, this logging function will be called multiple times as
+       * `which` runs, to help you understand what's going on and/or troubleshoot
+       * things. In most cases, it makes sense to use a function from `console`
+       * here, like so:
+       *
+       * ```js
+       * which("bash", {
+       *   logging: { trace: console.log }
+       * });
+       * ```
+       *
+       * Defaults to the current value of {@link logger.trace}. `logger.trace`
+       * defaults to a no-op function.
+       */
+      trace?: (...args: Array<any>) => void;
+    };
+  }
+): Path | null;
+
 declare type BaseExecOptions = {
   /** Sets the current working directory for the child process. */
   cwd?: string | Path;
@@ -641,16 +883,34 @@ declare type BaseExecOptions = {
   /** 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;
+  /** Options which control logging. */
+  logging?: {
+    /**
+     * If provided, this logging 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 function from `console`
+     * here, like so:
+     *
+     * ```js
+     * exec(["echo", "hi"], {
+     *   logging: { trace: console.log },
+     * });
+     * ```
+     *
+     * Defaults to the current value of {@link logger.trace}. `logger.trace`
+     * defaults to a no-op function.
+     */
+    trace?: (...args: Array<any>) => void;
+
+    /**
+     * An optional, user-provided logging function to be used for informational
+     * messages. Less verbose than `logging.trace`.
+     *
+     * Defaults to the current value of {@link logger.info}. `logger.info`
+     * defaults to a function which logs to stderr.
+     */
+    info?: (...args: Array<any>) => void;
+  };
 
   /**
    * Whether an Error should be thrown when the process exits with a nonzero
@@ -667,143 +927,63 @@ declare type BaseExecOptions = {
    * Defaults to false. true is an alias for "utf8".
    */
   captureOutput?: boolean | "utf8" | "arraybuffer";
-};
-
-declare interface Exec {
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: true;
-      captureOutput: false;
-    }
-  ): void;
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: false;
-      captureOutput: false;
-    }
-  ):
-    | { status: number; signal: undefined }
-    | { status: undefined; signal: number };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: true;
-      captureOutput: true;
-    }
-  ): { stdout: string; stderr: string };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: true;
-      captureOutput: "utf8";
-    }
-  ): { stdout: string; stderr: string };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: true;
-      captureOutput: "arraybuffer";
-    }
-  ): { stdout: ArrayBuffer; stderr: ArrayBuffer };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: false;
-      captureOutput: true;
-    }
-  ):
-    | { stdout: string; stderr: string; status: number; signal: undefined }
-    | { stdout: string; stderr: string; status: undefined; signal: number };
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: false;
-      captureOutput: "utf-8";
-    }
-  ):
-    | { stdout: string; stderr: string; status: number; signal: undefined }
-    | { stdout: string; stderr: string; status: undefined; signal: number };
+  /**
+   * If true, exec doesn't return until the process is done running. If false,
+   * exec returns an object with a "wait" method which can be used to wait for
+   * the process to be done running.
+   *
+   * Defaults to true.
+   */
+  block?: boolean;
+};
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: false;
-      captureOutput: "arraybuffer";
-    }
-  ):
-    | {
-        stdout: ArrayBuffer;
-        stderr: ArrayBuffer;
-        status: number;
-        signal: undefined;
-      }
-    | {
-        stdout: ArrayBuffer;
-        stderr: ArrayBuffer;
-        status: undefined;
-        signal: number;
-      };
+type ExecWaitResult<ExecOptions extends BaseExecOptions> = ExecOptions extends
+  | { captureOutput: true | "utf8" | "arraybuffer" }
+  | { failOnNonZeroStatus: false }
+  ? (ExecOptions["captureOutput"] extends true | "utf8"
+      ? { stdout: string; stderr: string }
+      : {}) &
+      (ExecOptions["captureOutput"] extends "arraybuffer"
+        ? { stdout: ArrayBuffer; stderr: ArrayBuffer }
+        : {}) &
+      (ExecOptions["failOnNonZeroStatus"] extends false
+        ?
+            | { status: number; signal: undefined }
+            | { status: undefined; signal: number }
+        : {})
+  : void;
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
+declare interface Exec {
+  <
+    ExecOptions extends BaseExecOptions = {
       failOnNonZeroStatus: true;
-    }
-  ): void;
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      failOnNonZeroStatus: false;
-    }
-  ):
-    | { status: number; signal: undefined }
-    | { status: undefined; signal: number };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      captureOutput: true;
-    }
-  ): { stdout: string; stderr: string };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      captureOutput: "utf8";
-    }
-  ): { stdout: string; stderr: string };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      captureOutput: "arraybuffer";
-    }
-  ): { stdout: ArrayBuffer; stderr: ArrayBuffer };
-
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
       captureOutput: false;
+      block: true;
     }
-  ): void;
+  >(
+    args: Array<string | Path | number> | string | Path,
+    options?: ExecOptions
+  ): ExecOptions["block"] extends false
+    ? { wait(): ExecWaitResult<ExecOptions> }
+    : ExecWaitResult<ExecOptions>;
 
-  (args: Array<string> | string, options?: BaseExecOptions): void;
+  /**
+   * Parse the provided value into an array of command-line argument strings,
+   * using the same logic that {@link exec} and {@link ChildProcess} use.
+   */
+  toArgv(args: Array<string | Path | number> | string | Path): Array<string>;
 }
 
-/** Runs a child process using the provided arguments. The first value in the arguments array is the program to run. */
+/**
+ * Runs 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): {
+declare function $(args: Array<string | Path | number> | string | Path): {
   stdout: string;
   stderr: string;
 };
@@ -817,7 +997,7 @@ declare interface ChildProcess {
   args: Array<string>;
 
   /** The current working directory for the process. */
-  cwd: string;
+  cwd: Path;
 
   /** The environment variables for the process. */
   env: { [key: string]: string };
@@ -836,12 +1016,6 @@ declare interface ChildProcess {
     err: FILE;
   };
 
-  /**
-   * Optional trace function which, if present, will be called at various times
-   * to provide information about the lifecycle of the process.
-   */
-  trace?: (...args: Array<any>) => void;
-
   pid: number | null;
 
   /** Spawns the process and returns its pid (process id). */
@@ -859,7 +1033,7 @@ declare interface ChildProcess {
  */
 declare type ChildProcessOptions = {
   /** The current working directory for the process. */
-  cwd?: string;
+  cwd?: string | Path;
 
   /** The environment variables for the process. */
   env?: { [key: string]: string };
@@ -878,11 +1052,17 @@ declare type ChildProcessOptions = {
     err?: FILE;
   };
 
-  /**
-   * Optional trace function which, if present, will be called at various times
-   * to provide information about the lifecycle of the process.
-   */
-  trace?: (...args: Array<any>) => void;
+  /** Options which control logging */
+  logging?: {
+    /**
+     * Optional trace function which, if present, will be called at various
+     * times to provide information about the lifecycle of the process.
+     *
+     * Defaults to the current value of {@link logger.trace}. `logger.trace`
+     * defaults to a function which writes to stderr.
+     */
+    trace?: (...args: Array<any>) => void;
+  };
 };
 
 declare interface ChildProcessConstructor {
@@ -893,7 +1073,7 @@ declare interface ChildProcessConstructor {
    * @param options - Options for the process (cwd, env, stdio, etc)
    */
   new (
-    args: string | Array<string>,
+    args: string | Path | Array<string | number | Path>,
     options?: ChildProcessOptions
   ): ChildProcess;
 
@@ -914,18 +1094,35 @@ declare type GlobOptions = {
    */
   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;
-
+  /** Options which control logging. */
+  logging?: {
+    /**
+     * 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"], {
+     *  logging: { trace: console.log }
+     * });
+     * ```
+     *
+     * Defaults to the current value of {@link logger.trace}. `logger.trace`
+     * defaults to a no-op function.
+     */
+    trace?: (...args: Array<any>) => void;
+
+    /**
+     * An optional, user-provided logging function to be used for informational
+     * messages. Less verbose than `logging.trace`.
+     *
+     * Defaults to the current value of {@link logger.info}. `logger.info`
+     * defaults to a function which writes to stderr.
+     */
+    info?: (...args: Array<any>) => void;
+  };
+
   /**
    * Directory to interpret glob patterns relative to. Defaults to `pwd()`.
    */
@@ -956,73 +1153,73 @@ interface Console {
 /**
  * Remove ANSI control characters from a string.
  */
-declare function stripAnsi(input: string): string;
+declare function stripAnsi(input: string | number | Path): string;
 
 /**
  * Wrap a string in double quotes, and escape any double-quotes inside using `\"`.
  */
-declare function quote(input: string): string;
+declare function quote(input: string | number | Path): string;
 
 // Colors
 
 /** Wrap a string with the ANSI control characters that will make it print as black text. */
-declare function black(input: string | number): string;
+declare function black(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as red text. */
-declare function red(input: string | number): string;
+declare function red(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as green text. */
-declare function green(input: string | number): string;
+declare function green(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as yellow text. */
-declare function yellow(input: string | number): string;
+declare function yellow(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as blue text. */
-declare function blue(input: string | number): string;
+declare function blue(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as magenta text. */
-declare function magenta(input: string | number): string;
+declare function magenta(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as cyan text. */
-declare function cyan(input: string | number): string;
+declare function cyan(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as white text. */
-declare function white(input: string | number): string;
+declare function white(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as gray text. */
-declare function gray(input: string | number): string;
+declare function gray(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print as grey text. */
-declare function grey(input: string | number): string;
+declare function grey(input: string | number | Path): 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;
+declare function bgBlack(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it have a red background. */
-declare function bgRed(input: string | number): string;
+declare function bgRed(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it have a green background. */
-declare function bgGreen(input: string | number): string;
+declare function bgGreen(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it have a yellow background. */
-declare function bgYellow(input: string | number): string;
+declare function bgYellow(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it have a blue background. */
-declare function bgBlue(input: string | number): string;
+declare function bgBlue(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it have a magenta background. */
-declare function bgMagenta(input: string | number): string;
+declare function bgMagenta(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it have a cyan background. */
-declare function bgCyan(input: string | number): string;
+declare function bgCyan(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it have a white background. */
-declare function bgWhite(input: string | number): string;
+declare function bgWhite(input: string | number | Path): string;
 
 // Modifiers
 
 /** Wrap a string with the ANSI control character that resets all styling. */
-declare function reset(input: string | number): string;
+declare function reset(input: string | number | Path): 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;
+declare function bold(input: string | number | Path): 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;
+declare function dim(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print italicized. */
-declare function italic(input: string | number): string;
+declare function italic(input: string | number | Path): string;
 /** Wrap a string with the ANSI control characters that will make it print underlined. */
-declare function underline(input: string | number): string;
+declare function underline(input: string | number | Path): 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;
+declare function inverse(input: string | number | Path): string;
 /** Wrap a string with ANSI control characters such that it is hidden. */
-declare function hidden(input: string | number): string;
+declare function hidden(input: string | number | Path): 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 function strikethrough(input: string | number | Path): string;
 
 /** Split `str` on newline and then return lines matching `pattern`. */
 declare const grepString: {
@@ -1418,17 +1615,9 @@ declare const types: {
   exactSymbol<T extends symbol>(sym: T): TypeValidator<T>;
   hasClassName<Name extends string>(
     name: Name
-  ): TypeValidator<{
-    constructor: Function & {
-      name: Name;
-    };
-  }>;
+  ): TypeValidator<{ constructor: Function & { name: Name } }>;
   hasToStringTag(name: string): TypeValidator<any>;
-  instanceOf<
-    Klass extends Function & {
-      prototype: any;
-    }
-  >(
+  instanceOf<Klass extends Function & { prototype: any }>(
     klass: Klass
   ): TypeValidator<Klass["prototype"]>;
   stringMatching(regexp: RegExp): TypeValidator<string>;
@@ -2546,7 +2735,6 @@ declare const types: {
   ) => TypeValidator<UnwrapTypeFromCoerceableOrValidator<V>>;
 
   FILE: TypeValidator<FILE>;
-  Module: TypeValidator<{ [key: string]: unknown }>;
   Path: TypeValidator<Path>;
   JSX: {
     unknownElement: TypeValidator<
@@ -2560,11 +2748,21 @@ declare const types: {
   };
 };
 
+/**
+ * Returns whether `value` is of type `type`. Useful for validating that values have the correct type at runtime, in library functions or etc.
+ *
+ * Run `help(is)` for more info.
+ */
 declare const is: <T extends TypeValidator<any> | CoerceableToTypeValidator>(
   value: any,
   type: T
 ) => value is UnwrapTypeFromCoerceableOrValidator<T>;
 
+/**
+ * Alias to {@link is}, for Civet, because `is` is a reserved keyword in Civet.
+ */
+declare const _is: typeof is;
+
 declare const assert: {
   /**
    * Throws an error if `value` is not truthy.
@@ -2591,83 +2789,6 @@ declare const assert: {
   ) => asserts value is UnwrapTypeFromCoerceableOrValidator<T>;
 };
 
-/**
- * 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 (or pass a FILE or Path object).
- */
-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
-  | { path: 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
-  | Path
-  | 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;
-};
-
 interface InteractivePrompt {
   prompt?: () => string;
   printInput?: (input: string) => void;
@@ -2729,6 +2850,7 @@ declare const startRepl: {
       | "tsx"
       | "coffee"
       | "coffeescript"
+      | "civet"
   ): void;
 
   /**
@@ -2796,31 +2918,38 @@ declare class GitRepo {
 }
 
 /**
- * Configures the default value of `trace` in functions which receive `trace`
- * as an option.
+ * The logger used internally by yavascript API functions such as {@link which},
+ * {@link exec}, {@link copy}, {@link glob}, and more.
  *
- * - 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.
+ * You can modify the properties on this object in order to configure the
+ * amount and style of log output from yavascript API functions.
  *
- * 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.
+ * This object behaves similarly to the shell builtin `set -x`.
  */
-declare const traceAll: ((
-  trace: boolean | undefined | ((...args: Array<any>) => void)
-) => void) & {
-  getDefaultTrace(): ((...args: Array<any>) => void) | undefined;
+declare const logger: {
+  /**
+   * This property is used as the default value for `trace` in yavascript API
+   * functions which receive `logging.trace` as an option, like {@link which},
+   * {@link exec}, {@link copy} and {@link glob}.
+   *
+   * The default value of `logger.trace` is a no-op function.
+   */
+  trace: (...args: Array<any>) => void;
+
+  /**
+   * This property is used as the default value for `info` in yavascript API
+   * functions which receive `logging.info` as an option, like {@link exec},
+   * {@link copy}, and {@link glob}.
+   *
+   * The default value of `logger.info` writes dimmed text to stdout.
+   */
+  info: (...args: Array<any>) => void;
 };
 
 declare namespace JSX {
   /**
    * A string containing the expression that should be called to create JSX
-   * elements.
+   * elements. yavascript's internals use this string to transpile JSX syntax.
    *
    * Defaults to "JSX.createElement".
    *
@@ -2840,7 +2969,8 @@ declare namespace JSX {
 
   /**
    * A string containing the expression that should be used as the first
-   * parameter when creating JSX fragment elements.
+   * parameter when creating JSX fragment elements. yavascript's internals use
+   * this string to transpile JSX syntax.
    *
    * Defaults to "JSX.Fragment".
    *
@@ -2880,10 +3010,19 @@ declare namespace JSX {
   export type Fragment = Element<{}, typeof Fragment>;
 
   /**
-   * The JSX element constructor, which gets invoked whenever JSX syntax is
+   * The JSX element builder function, which gets invoked whenever JSX syntax is
    * used (unless {@link JSX.pragma} is changed).
+   *
+   * Note that if you change this, you need to verify that the following
+   * expression always evaluates to `true` (by changing {@link types.JSX.Element}
+   * and {@link types.JSX.Fragment}):
+   * ```jsx
+   * types.JSX.Element(<a />) && types.JSX.Fragment(<></>)
+   * ```
+   *
+   * Failure to uphold this guarantee indicates a bug.
    */
-  export const createElement: {
+  export let createElement: {
     <Type extends string | typeof Fragment | ((...args: any) => any)>(
       type: Type
     ): Element<{}, Type>;
@@ -2955,11 +3094,66 @@ declare const CSV: {
   stringify(input: Array<Array<string>>): string;
 };
 
+declare var TOML: {
+  /**
+   * Parse a TOML document (`data`) into an object.
+   */
+  parse(data: string): { [key: string]: any };
+  /**
+   * Convert an object into a TOML document.
+   */
+  stringify(data: { [key: string]: any }): string;
+};
+
 interface RegExpConstructor {
   /** See https://github.com/tc39/proposal-regex-escaping */
   escape(str: any): string;
 }
 
+interface StringConstructor {
+  /**
+   * 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: unknown[]
+    ): 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;
+  };
+}
+
 // prettier-ignore
 /** Any integer in the range [0, 255]. */
 declare type byte =
@@ -3008,6 +3202,10 @@ declare type TypedArrayConstructor =
   | Float32ArrayConstructor
   | Float64ArrayConstructor;
 
+interface ErrorOptions {
+  [key: string]: any;
+}
+
 // ==========================================
 // ------------------------------------------
 // QuickJS APIs, which YavaScript builds upon
@@ -3034,6 +3232,18 @@ interface ObjectConstructor {
   isPrimitive(input: any): boolean;
 }
 
+interface StringConstructor {
+  /**
+   * A no-op template literal tag.
+   *
+   * https://github.com/tc39/proposal-string-cooked
+   */
+  cooked(
+    strings: readonly string[] | ArrayLike<string>,
+    ...substitutions: any[]
+  ): string;
+}
+
 interface SymbolConstructor {
   /**
    * A method that changes the result of using the `typeof` operator on the
@@ -3873,13 +4083,6 @@ interface BigDecimal {
 // TypeScript will not understand or handle unary/binary operators for BigFloat
 // and BigDecimal properly.
 
-// Definitions of the globals and modules added by quickjs-libc
-
-/**
- * Provides the command line arguments. The first argument is the script name.
- */
-declare var scriptArgs: Array<string>;
-
 /**
  * Print the arguments separated by spaces and a trailing newline.
  *
@@ -3907,6 +4110,163 @@ interface Console {
 
 declare var console: Console;
 
+/** npm: @suchipi/print@2.5.0. License: ISC */
+/* (with some QuickJS-specific modifications) */
+
+/*
+Copyright (c) 2016-2022, John Gardner
+Copyright (c) 2022 Lily Skye
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+/**
+ * Options for {@link inspect}.
+ */
+declare interface InspectOptions {
+  /** Whether to display non-enumerable properties. Defaults to false. */
+  all?: boolean;
+
+  /** Whether to invoke getter functions. Defaults to false. */
+  followGetters?: boolean;
+
+  /** Whether to display the indexes of iterable entries. Defaults to false. */
+  indexes?: boolean;
+
+  /** Hide object details after 𝑁 recursions. Defaults to Infinity. */
+  maxDepth?: number;
+
+  /** If true, don't identify well-known symbols as `@@…`. Defaults to false. */
+  noAmp?: boolean;
+
+  /** If true, don't format byte-arrays as hexadecimal. Defaults to false. */
+  noHex?: boolean;
+
+  /** If true, don't display function source code. Defaults to false. */
+  noSource?: boolean;
+
+  /** Whether to show `__proto__` properties if possible. Defaults to false. */
+  proto?: boolean;
+
+  /** Whether to sort properties alphabetically. When false, properties are sorted by creation order. Defaults to false. */
+  sort?: boolean;
+
+  /** Options that control whether and how ANSI terminal escape sequences for colours should be added to the output. Defaults to false, meaning no colours. */
+  colours?: boolean | 256 | 8 | InspectColours;
+
+  /** Prefix string to use for indentation. Defaults to '\t'. */
+  indent?: string;
+}
+
+declare interface InspectColours {
+  off?: string | number;
+  red?: string | number;
+  grey?: string | number;
+  green?: string | number;
+  darkGreen?: string | number;
+  punct?: string | number;
+  keys?: string | number;
+  keyEscape?: string | number;
+  typeColour?: string | number;
+  primitive?: string | number;
+  escape?: string | number;
+  date?: string | number;
+  hexBorder?: string | number;
+  hexValue?: string | number;
+  hexOffset?: string | number;
+  reference?: string | number;
+  srcBorder?: string | number;
+  srcRowNum?: string | number;
+  srcRowText?: string | number;
+  nul?: string | number;
+  nulProt?: string | number;
+  undef?: string | number;
+  noExts?: string | number;
+  frozen?: string | number;
+  sealed?: string | number;
+  regex?: string | number;
+  string?: string | number;
+  symbol?: string | number;
+  symbolFade?: string | number;
+  braces?: string | number;
+  quotes?: string | number;
+  empty?: string | number;
+  dot?: string | number;
+}
+
+declare interface InspectFunction {
+  /**
+   * Generate a human-readable representation of a value.
+   *
+   * @param value - Value to inspect
+   * @param options - Additional settings for refining output
+   * @returns A string representation of `value`.
+   */
+  (value: any, options?: InspectOptions): string;
+
+  /**
+   * Generate a human-readable representation of a value.
+   *
+   * @param value - Value to inspect
+   * @param key - The value's corresponding member name
+   * @param options - Additional settings for refining output
+   * @returns A string representation of `value`.
+   */
+  (value: any, key?: string | symbol, options?: InspectOptions): string;
+
+  /**
+   * A symbol which can be used to customize how an object gets printed.
+   */
+  custom: symbol;
+}
+
+/**
+ * Generate a human-readable representation of a value.
+ *
+ * @param value - Value to inspect
+ * @param key - The value's corresponding member name
+ * @param options - Additional settings for refining output
+ * @returns A string representation of `value`.
+ */
+declare var inspect: InspectFunction;
+
+declare interface InspectCustomInputs {
+  key: string | symbol;
+  type: string;
+  brackets: [string, string];
+  oneLine: boolean;
+  linesBefore: Array<string>;
+  linesAfter: Array<string>;
+  propLines: Array<string>;
+  readonly tooDeep: boolean;
+  indent: string;
+  typeSuffix: string;
+  opts: InspectOptions;
+  colours: { [Key in keyof Required<InspectColours>]: string };
+}
+
+declare type Interval = { [Symbol.toStringTag]: "Interval" };
+
+declare function setInterval(func: (...args: any) => any, ms: number): Interval;
+declare function clearInterval(interval: Interval): void;
+
+// Definitions of the globals and modules added by quickjs-libc
+
+/**
+ * Provides the command line arguments. The first argument is the script name.
+ */
+declare var scriptArgs: Array<string>;
+
 /** An object representing a file handle. */
 declare interface FILE {
   /**
@@ -3974,9 +4334,23 @@ declare interface FILE {
   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.
+   * Write this file into `target`, using a memory buffer of size `bufferSize`.
    *
-   * If the end of the file has been reached, then `null` will be returned instead of a string.
+   * If `limit` is specified, only that amount of bytes will be read and
+   * written. Otherwise, data is read and written until this file reaches EOF.
+   *
+   * A `limit` of 0 is treated the same as not specifying a limit.
+   *
+   * Internally, this function uses libc `fread` and `fwrite` in a loop.
+   *
+   * Returns the number of bytes read and written.
+   */
+  writeTo(target: FILE, bufferSize: number, limit?: 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.
    */
@@ -4004,54 +4378,42 @@ declare interface FILE {
 
 declare module "quickjs:std" {
   /**
-   * Exit the process with the provided status code.
+   * Set the exit code that the process should exit with in the future, if it
+   * exits normally.
    *
-   * @param statusCode The exit code; 0 for success, nonzero for failure.
-   */
-  export function exit(statusCode: number): void;
-
-  /**
-   * Evaluate the string `code` as a script (global eval).
+   * Can only be called from the main thread.
    *
-   * @param code - The code to evaluate.
-   * @param options - An optional object containing the following optional properties:
-   * @property backtraceBarrier - Boolean (default = false). If true, error backtraces do not list the stack frames below the evalScript.
-   * @property filename - String (default = "<evalScript>"). The filename to associate with the code being executed.
-   * @returns The result of the evaluation.
-   */
-  export function evalScript(
-    code: string,
-    options?: { backtraceBarrier?: boolean; filename?: string }
-  ): any;
-
-  /**
-   * Evaluate the file `filename` as a script (global eval).
+   * This exit code will only be used if the process exits "normally", ie, when
+   * there are no more pending JS tasks/listeners. If an unhandled exception is
+   * thrown, the process will always exit with status `1`, regardless of the
+   * status code passed to `setExitCode`. If someone calls {@link exit} and
+   * passes in a status code, that status code will take precedence over the
+   * status code passed to `setExitCode`.
    *
-   * @param filename - The relative or absolute path to the file to load. Relative paths are resolved relative to the process's current working directory.
-   * @returns The result of the evaluation.
+   * @param statusCode The future exit code; 0 for success, nonzero for failure.
    */
-  export function loadScript(filename: string): any;
+  export function setExitCode(statusCode: number): void;
 
   /**
-   * Evaluate the file `filename` as a module. Effectively a synchronous dynamic `import()`.
+   * Return the exit code that was previously set by {@link setExitCode}, or 0 if
+   * it hasn't yet been set.
    *
-   * @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 result of the evaluation (module namespace object).
+   * Can only be called from the main thread.
    */
-  export function importModule(
-    filename: string,
-    basename?: string
-  ): { [key: string]: any };
+  export function getExitCode(): number;
 
   /**
-   * Return the resolved path to a module.
+   * Exit the process with the provided status code.
    *
-   * @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.
+   * Can only be called from the main thread.
+   *
+   * If `statusCode` is not provided, a value previously passed into
+   * {@link setExitCode} will be used. If no value was previously passed into
+   * setExitCode, `0` will be used.
+   *
+   * @param statusCode The exit code; 0 for success, nonzero for failure.
    */
-  export function resolveModule(filename: string, basename?: string): string;
+  export function exit(statusCode?: number): never;
 
   /**
    * Load the file `filename` and return it as a string assuming UTF-8 encoding.
@@ -4060,15 +4422,6 @@ declare module "quickjs:std" {
    */
   export function loadFile(filename: string): string;
 
-  /**
-   * Read the script of module filename from an active stack frame, then return it as a string.
-   *
-   * If there isn't a valid filename for the specified stack frame, an error will be thrown.
-   *
-   * @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;
-
   /**
    * Return a boolean indicating whether the provided value is a FILE object.
    *
@@ -4153,9 +4506,6 @@ declare module "quickjs:std" {
   /** Constant for {@link FILE.setvbuf}. Declares that the buffer mode should be 'no buffering'. */
   export var _IONBF: number;
 
-  /** Manually invoke the cycle removal algorithm (garbage collector). The cycle removal algorithm is automatically started when needed, so this function is useful in case of specific memory constraints or for testing. */
-  export function gc(): void;
-
   /** Return the value of the environment variable `name` or `undefined` if it is not defined. */
   export function getenv(name: string): string | undefined;
 
@@ -4806,7 +5156,7 @@ declare module "quickjs:os" {
   export function dup2(oldfd: number, newfd: number): number;
 
   /** `pipe` Unix system call. Return two handles as `[read_fd, write_fd]`. */
-  export function pipe(): null | [number, number];
+  export function pipe(): [number, number];
 
   /** Sleep for `delay_ms` milliseconds. */
   export function sleep(delay_ms: number): void;
@@ -4919,126 +5269,14 @@ declare module "quickjs:os" {
   export function chmod(path: string, mode: number): void;
 }
 
-/**
- * Options for {@link inspect}.
- */
-declare interface InspectOptions {
-  /** Whether to display non-enumerable properties. Defaults to false. */
-  all?: boolean;
-
-  /** Whether to invoke getter functions. Defaults to false. */
-  followGetters?: boolean;
-
-  /** Whether to display the indexes of iterable entries. Defaults to false. */
-  indexes?: boolean;
-
-  /** Hide object details after 𝑁 recursions. Defaults to Infinity. */
-  maxDepth?: number;
-
-  /** If true, don't identify well-known symbols as `@@…`. Defaults to false. */
-  noAmp?: boolean;
-
-  /** If true, don't format byte-arrays as hexadecimal. Defaults to false. */
-  noHex?: boolean;
-
-  /** If true, don't display function source code. Defaults to false. */
-  noSource?: boolean;
-
-  /** Whether to show `__proto__` properties if possible. Defaults to false. */
-  proto?: boolean;
-
-  /** Whether to sort properties alphabetically. When false, properties are sorted by creation order. Defaults to false. */
-  sort?: boolean;
-
-  /** Options that control whether and how ANSI terminal escape sequences for colours should be added to the output. Defaults to false, meaning no colours. */
-  colours?: boolean | 256 | 8 | InspectColours;
-
-  /** Prefix string to use for indentation. Defaults to '\t'. */
-  indent?: string;
-}
-
-declare interface InspectColours {
-  off?: string | number;
-  red?: string | number;
-  grey?: string | number;
-  green?: string | number;
-  darkGreen?: string | number;
-  punct?: string | number;
-  keys?: string | number;
-  keyEscape?: string | number;
-  typeColour?: string | number;
-  primitive?: string | number;
-  escape?: string | number;
-  date?: string | number;
-  hexBorder?: string | number;
-  hexValue?: string | number;
-  hexOffset?: string | number;
-  reference?: string | number;
-  srcBorder?: string | number;
-  srcRowNum?: string | number;
-  srcRowText?: string | number;
-  nul?: string | number;
-  nulProt?: string | number;
-  undef?: string | number;
-  noExts?: string | number;
-  frozen?: string | number;
-  sealed?: string | number;
-  regex?: string | number;
-  string?: string | number;
-  symbol?: string | number;
-  symbolFade?: string | number;
-  braces?: string | number;
-  quotes?: string | number;
-  empty?: string | number;
-  dot?: string | number;
-}
-
-declare interface InspectFunction {
-  /**
-   * Generate a human-readable representation of a value.
-   *
-   * @param value - Value to inspect
-   * @param options - Additional settings for refining output
-   * @returns A string representation of `value`.
-   */
-  (value: any, options?: InspectOptions): string;
-
-  /**
-   * Generate a human-readable representation of a value.
-   *
-   * @param value - Value to inspect
-   * @param key - The value's corresponding member name
-   * @param options - Additional settings for refining output
-   * @returns A string representation of `value`.
-   */
-  (value: any, key?: string | symbol, options?: InspectOptions): string;
-}
-
-/**
- * Generate a human-readable representation of a value.
- *
- * @param value - Value to inspect
- * @param key - The value's corresponding member name
- * @param options - Additional settings for refining output
- * @returns A string representation of `value`.
- */
-declare var inspect: InspectFunction;
+declare var setTimeout: typeof import("quickjs:os").setTimeout;
+declare var clearTimeout: typeof import("quickjs:os").clearTimeout;
 
 /**
- * A global which lets you configure the module loader (import/export/require).
- * You can use these properties to add support for importing new filetypes.
- *
- * This global can also be used to identify whether an object is a module
- * namespace record.
+ * An object which lets you configure the module loader (import/export/require).
+ * You can change these properties to add support for importing new filetypes.
  */
-interface ModuleGlobal {
-  /**
-   * Returns true if `target` is a module namespace object.
-   */
-  [Symbol.hasInstance](target: any): target is {
-    [key: string | number | symbol]: any;
-  };
-
+interface ModuleDelegate {
   /**
    * A list of filetype extensions that may be omitted from an import specifier
    * string.
@@ -5050,7 +5288,7 @@ interface ModuleGlobal {
    * 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}.
+   * to add to {@link compilers}.
    */
   searchExtensions: Array<string>;
 
@@ -5077,7 +5315,7 @@ interface ModuleGlobal {
    * ```js
    * import * as std from "std";
    *
-   * Module.compilers[".txt"] = (filename, content) => {
+   * ModuleDelegate.compilers[".txt"] = (filename, content) => {
    *   return `export default ${JSON.stringify(content)}`;
    * }
    * ```
@@ -5091,24 +5329,20 @@ interface ModuleGlobal {
    * 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}.
+   * {@link searchExtensions}.
    */
   compilers: {
     [extensionWithDot: string]: (filename: string, content: string) => string;
   };
 
   /**
-   * Create a virtual built-in module whose exports consist of the own
-   * enumerable properties of `obj`.
-   */
-  define(name: string, obj: { [key: string]: any }): void;
-
-  /**
-   * Resolves a require/import request from `fromFile` into a canonicalized path.
+   * Resolves a require/import request from `fromFile` into a canonicalized
+   * path.
    *
    * To change native module resolution behavior, replace this function with
    * your own implementation. Note that you must handle
-   * `Module.searchExtensions` yourself in your replacement implementation.
+   * `ModuleDelegate.searchExtensions` yourself in your replacement
+   * implementation.
    */
   resolve(name: string, fromFile: string): string;
 
@@ -5116,14 +5350,12 @@ interface ModuleGlobal {
    * Reads the contents of the given resolved module name into a string.
    *
    * To change native module loading behavior, replace this function with your
-   * own implementation. Note that you must handle `Module.compilers` yourself
-   * in your replacement implementation.
+   * own implementation. Note that you must handle `ModuleDelegate.compilers`
+   * yourself in your replacement implementation.
    */
   read(modulePath: string): string;
 }
 
-declare var Module: ModuleGlobal;
-
 interface RequireFunction {
   /**
    * Synchronously import a module.
@@ -5132,8 +5364,8 @@ interface RequireFunction {
    *
    * 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.
+   * {@link ModuleDelegate.searchExtensions}, and use one of those if present.
+   * This behavior also happens when using normal `import` statements.
    *
    * For example, if you write:
    *
@@ -5142,20 +5374,20 @@ interface RequireFunction {
    * ```
    *
    * 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:
+   * where that import appears, and `ModuleDelegate.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.
+   * 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.
+   * If you add more extensions to `ModuleDelegate.searchExtensions`, then the
+   * engine will use those, too. It will search in the same order as the strings
+   * appear in the `ModuleDelegate.searchExtensions` array.
    */
   (source: string): any;
 
@@ -5165,72 +5397,145 @@ interface RequireFunction {
   resolve: (source: string) => string;
 }
 
+// global added by QJMS_InitContext
 declare var require: RequireFunction;
 
+// gets set per-module by QJMS_SetModuleImportMeta
 interface ImportMeta {
+  /**
+   * A URL representing the current module.
+   *
+   * Usually starts with `file://`.
+   */
+  url: string;
+
+  /**
+   * Whether the current module is the "main" module, meaning that it is the
+   * entrypoint file that's been loaded, or, in other terms, the first
+   * user-authored module that's been loaded.
+   */
+  main: boolean;
+
+  /**
+   * Equivalent to `globalThis.require`. Provided for compatibility with tools
+   * that can leverage a CommonJS require function via `import.meta.require`.
+   */
   require: RequireFunction;
+
+  /**
+   * Resolves a module specifier based on the current module's path.
+   *
+   * Equivalent to `globalThis.require.resolve`.
+   *
+   * Behaves similarly to [the browser
+   * import.meta.resolve](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve),
+   * but it does not ensure that the returned string is a valid URL, because it
+   * delegates directly to {@link ModuleDelegate.resolve} to resolve the name.
+   * If you want this to return URL strings, change `ModuleDelegate.resolve` and
+   * `ModuleDelegate.read` to work with URL strings.
+   */
+  resolve: RequireFunction["resolve"];
 }
 
-declare var setTimeout: typeof import("quickjs:os").setTimeout;
-declare var clearTimeout: typeof import("quickjs:os").clearTimeout;
+declare module "quickjs:engine" {
+  /**
+   * Return whether the provided resolved module path is set as the main module.
+   *
+   * In other words, return what the value of `import.meta.main` would be within
+   * the module.
+   *
+   * The main module can be set via {@link setMainModule}.
+   */
+  export function isMainModule(resolvedFilepath: string): boolean;
 
-declare type Interval = { [Symbol.toStringTag]: "Interval" };
+  /**
+   * Set the main module to the module with the provided resolved path.
+   *
+   * This will affect the value of `import.meta.main` for modules loaded in the
+   * future, but it will NOT retroactively change the value of
+   * `import.meta.main` in existing already-loaded modules.
+   */
+  export function setMainModule(resolvedFilepath: string): void;
 
-declare function setInterval(func: (...args: any) => any, ms: number): Interval;
-declare function clearInterval(interval: Interval): void;
+  /**
+   * Evaluate the string `code` as a script (global eval).
+   *
+   * @param code - The code to evaluate.
+   * @param options - An optional object containing the following optional properties:
+   * @property backtraceBarrier - Boolean (default = false). If true, error backtraces do not list the stack frames below the evalScript.
+   * @property filename - String (default = "<evalScript>"). The filename to associate with the code being executed.
+   * @returns The result of the evaluation.
+   */
+  export function evalScript(
+    code: string,
+    options?: { backtraceBarrier?: boolean; filename?: string }
+  ): any;
 
-interface StringConstructor {
   /**
-   * A no-op template literal tag.
+   * Evaluate the file `filename` as a script (global eval).
    *
-   * https://github.com/tc39/proposal-string-cooked
+   * @param filename - The relative or absolute path to the file to load. Relative paths are resolved relative to the process's current working directory.
+   * @returns The result of the evaluation.
    */
-  cooked(
-    strings: readonly string[] | ArrayLike<string>,
-    ...substitutions: any[]
-  ): string;
+  export function runScript(filename: string): any;
 
   /**
-   * Remove leading minimum indentation from the string.
-   * The first line of the string must be empty.
+   * Evaluate the file `filename` as a module. Effectively a synchronous dynamic `import()`.
    *
-   * https://github.com/tc39/proposal-string-dedent
+   * @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 result of the evaluation (module namespace object).
    */
-  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;
+  export function importModule(
+    filename: string,
+    basename?: string
+  ): { [key: string]: any };
 
-    /**
-     * 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;
+  /**
+   * 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;
 
-    /**
-     * 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;
-  };
+  /**
+   * Read the script of module filename from an active stack frame, then return it as a string.
+   *
+   * If there isn't a valid filename for the specified stack frame, an error will be thrown.
+   *
+   * @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;
+
+  /**
+   * Returns true if `target` is a module namespace object.
+   */
+  export function isModuleNamespace(target: any): boolean;
+
+  /**
+   * Create a virtual built-in module whose exports consist of the own
+   * enumerable properties of `obj`.
+   */
+  export function defineBuiltinModule(
+    name: string,
+    obj: { [key: string]: any }
+  ): void;
+
+  /**
+   * An object which lets you configure the module loader (import/export/require).
+   * You can change these properties to add support for importing new filetypes.
+   */
+  export const ModuleDelegate: ModuleDelegate;
+
+  /**
+   * Manually invoke the cycle removal algorithm (garbage collector).
+   *
+   * The cycle removal algorithm is automatically started when needed, so this
+   * function is useful in case of specific memory constraints or for testing.
+   */
+  export function gc(): void;
 }
 
 declare module "quickjs:bytecode" {
@@ -5241,7 +5546,11 @@ declare module "quickjs:bytecode" {
    */
   export function fromFile(
     path: string,
-    options?: { byteSwap?: boolean; sourceType?: "module" | "script" }
+    options?: {
+      byteSwap?: boolean;
+      sourceType?: "module" | "script";
+      encodedFileName?: string;
+    }
   ): ArrayBuffer;
 
   /**
@@ -5304,6 +5613,10 @@ declare module "quickjs:context" {
      * - Symbol
      * - eval (but it doesn't work unless the `eval` option is enabled)
      * - globalThis
+     *
+     * Note that new contexts don't have a `scriptArgs` global. If you need one
+     * to be present in the new context, you can add one onto the Context's
+     * `globalThis` property.
      */
     constructor(options?: {
       /** Enables `Date`. Defaults to `true` */
@@ -5381,33 +5694,22 @@ declare module "quickjs:context" {
        */
       operators?: boolean;
 
-      /** Enables "use math". Defaults to `true`. */
+      /** Enables `"use math"`. Defaults to `true`. */
       useMath?: boolean;
 
+      /** Enables `inspect`. Defaults to `true`. */
+      inspect?: boolean;
+      /** Enables `console`. Defaults to `true`. */
+      console?: boolean;
+      /** Enables `print`. Defaults to `true`. */
+      print?: boolean;
+      /** Enables `require`. Defaults to `true`. */
+      moduleGlobals?: boolean;
       /**
-       * Enables:
-       *
-       * - inspect
-       * - console
-       * - print
-       * - require (and require.resolve)
-       * - setTimeout
-       * - clearTimeout
-       * - setInterval
-       * - clearInterval
-       * - String.cooked
-       * - String.dedent
-       *
-       * Defaults to `true`.
-       *
-       * NOTE: The following globals, normally part of `js_std_add_helpers`, are NEVER added:
-       *
-       * - Module
-       * - scriptArgs
-       *
-       * If you need them in the new context, copy them over from your context's globalThis onto the child context's globalThis.
+       * Enables `setTimeout`, `clearTimeout`, `setInterval`, and
+       * `clearInterval`. Defaults to `true`.
        */
-      stdHelpers?: boolean;
+      timers?: boolean;
 
       /** Enable builtin modules. */
       modules?: {
@@ -5419,6 +5721,10 @@ declare module "quickjs:context" {
         "quickjs:bytecode"?: boolean;
         /** Enables the "quickjs:context" module. Defaults to `true`. */
         "quickjs:context"?: boolean;
+        /** Enables the "quickjs:engine" module. Defaults to `true`. */
+        "quickjs:engine"?: boolean;
+        /** Enables the "quickjs:encoding" module. Defaults to `true`. */
+        "quickjs:encoding"?: boolean;
       };
     });
 
@@ -5438,5 +5744,16 @@ declare module "quickjs:context" {
   }
 }
 
+// WHATWG encoding spec at https://encoding.spec.whatwg.org/ would be better,
+// but this is better than nothing
+declare module "quickjs:encoding" {
+  export function toUtf8(input: ArrayBuffer): string;
+  export function fromUtf8(input: string): ArrayBuffer;
+}
+
 declare const std: typeof import("quickjs:std");
 declare const os: typeof import("quickjs:os");
+
+// undocumented from quickjs, but it's there
+/** Get the current unix timestamp with microsecond precision. */
+declare function __date_clock(): number;