yavascript 0.0.10 → 0.0.11

package/yavascript.d.ts

@@ -99,6 +99,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 }
@@ -307,6 +312,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>;
 
@@ -322,16 +335,14 @@ declare class Path {
   ): string | Fallback;
 
   /** Join together one or more paths. */
-  static join(...inputs: Array<string | Path | Array<string | Path>>): string;
+  static join(...inputs: Array<string | Path | Array<string | Path>>): Path;
 
   /**
    * 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;
+  static resolve(...inputs: Array<string | Path | Array<string | Path>>): Path;
 
   /**
    * Concatenates the input path(s) and then resolves all non-leading `.` and
@@ -339,7 +350,7 @@ declare class Path {
    */
   static normalize(
     ...inputs: Array<string | Path | Array<string | Path>>
-  ): string;
+  ): Path;
 
   /**
    * Return whether the provided path is absolute; that is, whether it
@@ -347,18 +358,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.
    *
@@ -382,13 +381,11 @@ declare class Path {
   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()`.
+   * Create an absolute path by `concat`ting `subpaths` onto this Path (which is
+   * presumed to be an absolute path) and then using `normalize()` on the
+   * result. If the result is not an absolute path, an error will be thrown.
    */
-  resolve(from?: string | Path): Path;
+  resolve(...subpaths: Array<string | Path>): Path;
 
   /**
    * Resolve all non-leading `.` and `..` segments in this path.
@@ -396,21 +393,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 +435,116 @@ 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 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,8 +569,7 @@ 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 of more files from disk as one UTF-8 string.
  */
 declare function cat(...paths: Array<string | Path>): string;
 
@@ -526,7 +630,7 @@ 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.
@@ -548,14 +652,8 @@ declare function extname(
 /**
  * Returns 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 | Path,
-  options?: { relativePaths?: boolean }
-): Array<string>;
+declare function ls(dir?: string | Path): Array<Path>;
 
 /**
  * Print data to stdout using C-style format specifiers.
@@ -571,7 +669,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 +691,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 +700,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 +745,26 @@ 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 `traceAll.getDefaultTrace()`.
+ */
+declare function which(
+  binaryName: string,
+  options?: {
+    searchPaths?: Array<Path | string>;
+    suffixes?: Array<string>;
+    trace?: (...args: Array<any>) => void;
+  }
+): Path | null;
+
 declare type BaseExecOptions = {
   /** Sets the current working directory for the child process. */
   cwd?: string | Path;
@@ -671,7 +802,7 @@ declare type BaseExecOptions = {
 
 declare interface Exec {
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: true;
       captureOutput: false;
@@ -679,7 +810,7 @@ declare interface Exec {
   ): void;
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: false;
       captureOutput: false;
@@ -689,7 +820,7 @@ declare interface Exec {
     | { status: undefined; signal: number };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: true;
       captureOutput: true;
@@ -697,7 +828,7 @@ declare interface Exec {
   ): { stdout: string; stderr: string };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: true;
       captureOutput: "utf8";
@@ -705,7 +836,7 @@ declare interface Exec {
   ): { stdout: string; stderr: string };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: true;
       captureOutput: "arraybuffer";
@@ -713,7 +844,7 @@ declare interface Exec {
   ): { stdout: ArrayBuffer; stderr: ArrayBuffer };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: false;
       captureOutput: true;
@@ -723,7 +854,7 @@ declare interface Exec {
     | { stdout: string; stderr: string; status: undefined; signal: number };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: false;
       captureOutput: "utf-8";
@@ -733,7 +864,7 @@ declare interface Exec {
     | { stdout: string; stderr: string; status: undefined; signal: number };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: false;
       captureOutput: "arraybuffer";
@@ -753,14 +884,14 @@ declare interface Exec {
       };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: true;
     }
   ): void;
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       failOnNonZeroStatus: false;
     }
@@ -769,41 +900,54 @@ declare interface Exec {
     | { status: undefined; signal: number };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       captureOutput: true;
     }
   ): { stdout: string; stderr: string };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       captureOutput: "utf8";
     }
   ): { stdout: string; stderr: string };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       captureOutput: "arraybuffer";
     }
   ): { stdout: ArrayBuffer; stderr: ArrayBuffer };
 
   (
-    args: Array<string> | string,
+    args: Array<string | Path | number> | string | Path,
     options: BaseExecOptions & {
       captureOutput: false;
     }
   ): void;
 
-  (args: Array<string> | string, options?: BaseExecOptions): void;
+  (
+    args: Array<string | Path | number> | string | Path,
+    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 +961,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 };
@@ -859,7 +1003,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 };
@@ -893,7 +1037,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;
 
@@ -961,7 +1105,7 @@ declare function stripAnsi(input: string): 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 | Path): string;
 
 // Colors
 
@@ -2560,11 +2704,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.
@@ -2796,8 +2950,9 @@ declare class GitRepo {
 }
 
 /**
- * Configures the default value of `trace` in functions which receive `trace`
- * as an option.
+ * Configures the default value of `trace` in yavascript API functions which
+ * receive `trace` as an option, like {@link which}, {@link exec}, {@link copy}
+ * and {@link glob}.
  *
  * - If called with `true`, the default value of `trace` in all functions which
  *   receive a `trace` option will be changed to `console.error`.
@@ -2806,10 +2961,12 @@ declare class GitRepo {
  * - 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.
+ * 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 current
+ * value which should be used as the default value.
+ *
+ * `traceAll` provides similar functionality to shell builtin `set -x`.
  */
 declare const traceAll: ((
   trace: boolean | undefined | ((...args: Array<any>) => void)
@@ -2820,7 +2977,7 @@ declare const traceAll: ((
 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 +2997,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 +3038,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>;
@@ -3034,6 +3201,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,6 +4052,151 @@ interface BigDecimal {
 // TypeScript will not understand or handle unary/binary operators for BigFloat
 // and BigDecimal properly.
 
+/** 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 };
+}
+
 // Definitions of the globals and modules added by quickjs-libc
 
 /**
@@ -4004,71 +4328,50 @@ 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.
+   * Can only be called from the main thread.
+   *
+   * 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 statusCode The future exit code; 0 for success, nonzero for failure.
    */
-  export function exit(statusCode: number): void;
+  export function setExitCode(statusCode: number): void;
 
   /**
-   * Evaluate the string `code` as a script (global eval).
+   * Return the exit code that was previously set by {@link setExitCode}, or 0 if
+   * it hasn't yet been set.
    *
-   * @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.
+   * Can only be called from the main thread.
    */
-  export function evalScript(
-    code: string,
-    options?: { backtraceBarrier?: boolean; filename?: string }
-  ): any;
+  export function getExitCode(): number;
 
   /**
-   * Evaluate the file `filename` as a script (global eval).
+   * Exit the process with the provided status code.
    *
-   * @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.
+   * 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 loadScript(filename: string): any;
+  export function exit(statusCode?: number): never;
 
   /**
-   * Evaluate the file `filename` as a module. Effectively a synchronous dynamic `import()`.
-   *
-   * @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).
-   */
-  export function importModule(
-    filename: string,
-    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.
+   * Load the file `filename` and return it as a string assuming UTF-8 encoding.
    *
    * @param filename - The relative or absolute path to the file to load. Relative paths are resolved relative to the process's current working directory.
    */
   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.
    *
@@ -4919,110 +5222,57 @@ 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;
+declare var setTimeout: typeof import("quickjs:os").setTimeout;
+declare var clearTimeout: typeof import("quickjs:os").clearTimeout;
 
-  /** Prefix string to use for indentation. Defaults to '\t'. */
-  indent?: string;
-}
+declare type Interval = { [Symbol.toStringTag]: "Interval" };
 
-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 function setInterval(func: (...args: any) => any, ms: number): Interval;
+declare function clearInterval(interval: Interval): void;
 
-declare interface InspectFunction {
+interface StringConstructor {
   /**
-   * Generate a human-readable representation of a value.
+   * Remove leading minimum indentation from the string.
+   * The first line of the string must be empty.
    *
-   * @param value - Value to inspect
-   * @param options - Additional settings for refining output
-   * @returns A string representation of `value`.
+   * https://github.com/tc39/proposal-string-dedent
    */
-  (value: any, options?: InspectOptions): string;
+  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;
 
-  /**
-   * 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;
-}
+    /**
+     * 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;
 
-/**
- * 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;
+    /**
+     * 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;
+  };
+}
 
 /**
  * A global which lets you configure the module loader (import/export/require).
@@ -5122,6 +5372,7 @@ interface ModuleGlobal {
   read(modulePath: string): string;
 }
 
+// global added by QJMS_AddModuleGlobal
 declare var Module: ModuleGlobal;
 
 interface RequireFunction {
@@ -5165,72 +5416,116 @@ interface RequireFunction {
   resolve: (source: string) => string;
 }
 
+// global added by QJMS_AddRequireGlobal
 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 Module.resolve} to resolve the name. If you
+   * want this to return URL strings, change `Module.resolve` and `Module.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:module" {
+  /**
+   * 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;
 }
 
 declare module "quickjs:bytecode" {
@@ -5304,6 +5599,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` */
@@ -5315,6 +5614,9 @@ declare module "quickjs:context" {
       /** Enables `String.prototype.normalize`. Defaults to `true`. */
       stringNormalize?: boolean;
 
+      /** Enables `String.dedent`. Defaults to `true`. */
+      stringDedent?: boolean;
+
       /** Enables `RegExp`. Defaults to `true`. */
       regExp?: boolean;
 
@@ -5381,33 +5683,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` and `Module`. 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 +5710,8 @@ declare module "quickjs:context" {
         "quickjs:bytecode"?: boolean;
         /** Enables the "quickjs:context" module. Defaults to `true`. */
         "quickjs:context"?: boolean;
+        /** Enables the "quickjs:module" module. Defaults to `true`. */
+        "quickjs:module"?: boolean;
       };
     });