yavascript 0.0.5 → 0.0.6

package/README.md

@@ -1,11 +1,9 @@
 # yavascript
 
-<!-- NOTE: this file is also used as help text by the CLI. Don't use markdown syntax below this line unless said syntax would also be clearly readable as plain text. -->
-
 YavaScript is a bash-like script runner which is distributed as a single
-statically-linked binary. Scripts are written in JavaScript. There are global
-APIs available for all the things you'd normally want to do in a bash script,
-such as:
+statically-linked binary. Scripts are written in JavaScript or CoffeeScript.
+There are global APIs available for all the things you'd normally want to do in
+a bash script, such as:
 
 - Running programs
 - Accessing environment variables
@@ -40,4 +38,16 @@ supporting the ES2020 specification.
 - Original QuickJS engine: https://bellard.org/quickjs/
 - The fork we use: https://github.com/suchipi/quickjs/
 
-YavaScript is written with <3 by Lily Scott.
+## Compiling
+
+### Binaries (all platforms)
+
+You will need docker installed, then run `./scripts/build.sh`.
+
+### Docker image
+
+You will need docker installed, then run `docker build -t yourusername/yavascript .`.
+
+---
+
+YavaScript is written with <3 by Lily Skye.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "yavascript",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "main": "lib/index.js",
   "bin": "lib/cli.js",
   "types": "yavascript.d.ts",
-  "author": "Lily Scott <me@suchipi.com>",
+  "author": "Lily Skye <me@suchipi.com>",
   "license": "MIT",
   "repository": "suchipi/yavascript"
 }

package/yavascript.d.ts

@@ -1,12 +1,8 @@
-
+// ===============
 // ---------------
 // YavaScript APIs
 // ---------------
-
-// -----------
-// --- env ---
-// -----------
-
+// ===============
 /**
  * An object representing the process's environment variables. You can read
  * from it to read environment variables, write into it to set environment
@@ -15,139 +11,125 @@
  */
 declare const env: { [key: string]: string | undefined };
 
-// ------------
-// --- exec ---
-// ------------
-
-type BaseExecOptions = {
-  /** Sets the current working directory for the child process. */
-  cwd?: string;
+/**
+ * Return the contents of a directory, as absolute paths. `.` and `..` are
+ * omitted.
+ *
+ * Use the `relativePaths` option to get relative paths instead (relative to
+ * the parent directory).
+ */
+declare function ls(
+  dir?: string,
+  options?: { relativePaths?: boolean }
+): Array<string>;
 
-  /** Sets environment variables within the process. */
-  env?: { [key: string | number]: string | number | boolean };
-};
+/**
+ * Read a symlink.
+ *
+ * Returns the target of the symlink, which may be absolute or relative.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function readlink(path: string): string;
 
-interface Exec {
-  (args: Array<string> | string): void;
+/**
+ * Read the contents of a file from disk, as a UTF-8 string.
+ */
+declare function readFile(path: string): string;
 
-  (args: Array<string> | string, options: Record<string, never>): void;
+/**
+ * Write the contents of a string or ArrayBuffer to a file.
+ *
+ * Strings are written using the UTF-8 encoding.
+ */
+declare function writeFile(path: string, data: string | ArrayBuffer): void;
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: true;
-      /**
-       * If true, stdout and stderr will be collected into strings and returned
-       * instead of being printed to the screen.
-       *
-       * Defaults to false.
-       */
-      captureOutput: false;
-    }
-  ): void;
+/**
+ * Function which returns true if the path points to a directory, or if the
+ * path points to a symlink which points to a directory. Otherwise, it returns
+ * false.
+ */
+interface IsDir {
+  /**
+   * Returns true if the path points to a directory, or if the path points to
+   * a symlink which points to a directory. Otherwise, returns false.
+   */
+  (path: string): boolean;
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: false;
-      /**
-       * If true, stdout and stderr will be collected into strings and returned
-       * instead of being printed to the screen.
-       *
-       * Defaults to false.
-       */
-      captureOutput: false;
-    }
-  ): { status: number };
+  /**
+   * Maximum number of symlinks to follow before erroring. Defaults to 100.
+   */
+  symlinkLimit: number;
+}
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: false;
-    }
-  ): { status: number };
+/**
+ * Function which returns true if the path points to a directory, or if the
+ * path points to a symlink which points to a directory. Otherwise, it returns
+ * false.
+ */
+declare const isDir: IsDir;
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: true;
-      /**
-       * If true, stdout and stderr will be collected into strings and returned
-       * instead of being printed to the screen.
-       *
-       * Defaults to false.
-       */
-      captureOutput: true;
-    }
-  ): { stdout: string; stderr: string };
+/**
+ * Returns true if the path points to a symlink.
+ */
+declare function isLink(path: string): boolean;
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * If true, stdout and stderr will be collected into strings and returned
-       * instead of being printed to the screen.
-       *
-       * Defaults to false.
-       */
-      captureOutput: true;
-    }
-  ): { stdout: string; stderr: string };
+/**
+ * Delete the file or directory at the specified path.
+ *
+ * If the directory isn't empty, its contents will be deleted, too.
+ *
+ * Provides the same functionality as the command `rm -rf`.
+ */
+declare function remove(path: string): void;
 
-  (
-    args: Array<string> | string,
-    options: BaseExecOptions & {
-      /**
-       * Whether an Error should be thrown when the process exits with a nonzero
-       * status code.
-       *
-       * Defaults to true.
-       */
-      failOnNonZeroStatus: false;
-      captureOutput: true;
-    }
-  ): { stdout: string; stderr: string; status: number };
+/**
+ * Returns true if a file or directory exists at the specified path.
+ *
+ * Provides the same functionality as the command `test -e`.
+ */
+declare function exists(path: string): boolean;
 
-  /** Log all executed commands to stderr. `isOn` is optional and defaults to `true`. Pass `false` to disable logging. */
-  enableLogging(isOn?: boolean): void;
-}
+/**
+ * Create 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): string;
 
-/** Run a child process using the provided arguments. The first value in the arguments array is the program to run. */
-declare const exec: Exec;
+/**
+ * Options for {@link copy}.
+ */
+declare type CopyOptions = {
+  /**
+   * What to do when attempting to copy something into a location where
+   * something else already exists.
+   *
+   * Defaults to "error".
+   */
+  whenTargetExists?: "overwrite" | "skip" | "error";
 
-/** Alias for `exec(args, { captureOutput: true })` */
-declare function $(args: Array<string> | string): {
-  stdout: string;
-  stderr: string;
+  /**
+   * 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;
 };
 
-// -------------
-// --- paths ---
-// -------------
+/**
+ * Copy a file or folder from one location to another.
+ * Folders are copied recursively.
+ *
+ * Provides the same functionality as the command `cp -R`.
+ */
+declare function copy(from: string, to: string, options?: CopyOptions): void;
 
 /**
  * Change the process's current working directory to the specified path.
@@ -265,152 +247,145 @@ declare const __filename: string;
  */
 declare const __dirname: string;
 
-// ------------
-// --- repo ---
-// ------------
-
-/**
- * Returns the absolute path to the root folder of the git/hg repo.
- *
- * This is done by running `git rev-parse --show-toplevel` and `hg root`.
- *
- * If `relativeTo` is provided, the git and hg commands will be executed in
- * that folder instead of in `pwd()`.
- */
-declare function repoRoot(relativeTo?: string): string;
-
-/**
- * Returns whether the provided path is ignored by git.
- */
-declare function isGitignored(path: string): boolean;
-
-// ------------------
-// --- filesystem ---
-// ------------------
-
-/**
- * Return the contents of a directory, as absolute paths. `.` and `..` are
- * omitted.
- *
- * Use the `relativePaths` option to get relative paths instead (relative to
- * the parent directory).
- */
-declare function ls(
-  dir?: string,
-  options?: { relativePaths?: boolean }
-): Array<string>;
-
-/**
- * Read a symlink.
- *
- * Returns the target of the symlink, which may be absolute or relative.
- *
- * Provides the same functionality as the unix binary of the same name.
- */
-declare function readlink(path: string): string;
-
-/**
- * Read the contents of a file from disk, as a UTF-8 string.
- */
-declare function readFile(path: string): string;
+declare type BaseExecOptions = {
+  /** Sets the current working directory for the child process. */
+  cwd?: string;
 
-/**
- * Write the contents of a string or ArrayBuffer to a file.
- *
- * Strings are written using the UTF-8 encoding.
- */
-declare function writeFile(path: string, data: string | ArrayBuffer): void;
+  /** Sets environment variables within the process. */
+  env?: { [key: string | number]: string | number | boolean };
 
-/**
- * Function which returns true if the path points to a directory, or if the
- * path points to a symlink which points to a directory. Otherwise, it returns
- * false.
- */
-interface IsDir {
   /**
-   * Returns true if the path points to a directory, or if the path points to
-   * a symlink which points to a directory. Otherwise, returns false.
+   * 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 });
+   * ```
    */
-  (path: string): boolean;
+  trace?: (...args: Array<any>) => void;
+};
 
-  /**
-   * Maximum number of symlinks to follow before erroring. Defaults to 100.
-   */
-  symlinkLimit: number;
-}
+declare interface Exec {
+  (args: Array<string> | string): void;
 
-/**
- * Function which returns true if the path points to a directory, or if the
- * path points to a symlink which points to a directory. Otherwise, it returns
- * false.
- */
-declare const isDir: IsDir;
+  (args: Array<string> | string, options: Record<string, never>): void;
 
-/**
- * Returns true if the path points to a symlink.
- */
-declare function isLink(path: string): boolean;
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: true;
+      /**
+       * If true, stdout and stderr will be collected into strings and returned
+       * instead of being printed to the screen.
+       *
+       * Defaults to false.
+       */
+      captureOutput: false;
+    }
+  ): void;
 
-/**
- * Delete the file or directory at the specified path.
- *
- * If the directory isn't empty, its contents will be deleted, too.
- *
- * Provides the same functionality as the command `rm -rf`.
- */
-declare function remove(path: string): void;
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: false;
+      /**
+       * If true, stdout and stderr will be collected into strings and returned
+       * instead of being printed to the screen.
+       *
+       * Defaults to false.
+       */
+      captureOutput: false;
+    }
+  ):
+    | { status: number; signal: undefined }
+    | { status: undefined; signal: number };
 
-/**
- * Returns true if a file or directory exists at the specified path.
- *
- * Provides the same functionality as the command `test -e`.
- */
-declare function exists(path: string): boolean;
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: false;
+    }
+  ):
+    | { status: number; signal: undefined }
+    | { status: undefined; signal: number };
 
-/**
- * Create 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): string;
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: true;
+      /**
+       * If true, stdout and stderr will be collected into strings and returned
+       * instead of being printed to the screen.
+       *
+       * Defaults to false.
+       */
+      captureOutput: true;
+    }
+  ): { stdout: string; stderr: string };
 
-/**
- * Options for {@link copy}.
- */
-declare type CopyOptions = {
-  /**
-   * What to do when attempting to copy something into a location where
-   * something else already exists.
-   *
-   * Defaults to "error".
-   */
-  whenTargetExists?: "overwrite" | "skip" | "error";
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * If true, stdout and stderr will be collected into strings and returned
+       * instead of being printed to the screen.
+       *
+       * Defaults to false.
+       */
+      captureOutput: true;
+    }
+  ): { stdout: string; stderr: string };
 
-  /**
-   * 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;
-};
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      /**
+       * Whether an Error should be thrown when the process exits with a nonzero
+       * status code.
+       *
+       * Defaults to true.
+       */
+      failOnNonZeroStatus: false;
+      captureOutput: true;
+    }
+  ):
+    | { stdout: string; stderr: string; status: number; signal: undefined }
+    | { stdout: string; stderr: string; status: undefined; signal: number };
+}
 
-/**
- * Copy a file or folder from one location to another.
- * Folders are copied recursively.
- *
- * Provides the same functionality as the command `cp -R`.
- */
-declare function copy(from: string, to: string, options?: CopyOptions): void;
+/** Run a child process using the provided arguments. The first value in the arguments array is the program to run. */
+declare const exec: Exec;
 
-// ------------
-// --- glob ---
-// ------------
+/** Alias for `exec(args, { captureOutput: true })` */
+declare function $(args: Array<string> | string): {
+  stdout: string;
+  stderr: string;
+};
 
 /**
  * Options for {@link glob}.
@@ -431,10 +406,15 @@ declare type GlobOptions = {
    * function here, like so:
    *
    * ```js
-   * glob(pwd(), ["./*.js"], { trace: console.log });
+   * glob(["./*.js"], { trace: console.log });
    * ```
    */
   trace?: (...args: Array<any>) => void;
+
+  /**
+   * Directory to interpret glob patterns relative to. Defaults to `pwd()`.
+   */
+  dir?: string;
 };
 
 /**
@@ -444,24 +424,15 @@ declare type GlobOptions = {
  * options.
  */
 declare function glob(
-  dir: string,
-  patterns: Array<string>,
+  patterns: string | Array<string>,
   options?: GlobOptions
 ): Array<string>;
 
-// ---------------
-// --- console ---
-// ---------------
-
 /**
  * Print one or more values to stdout.
  */
 declare const echo: typeof console.log;
 
-// ---------------
-// --- strings ---
-// ---------------
-
 /**
  * Remove ANSI control characters from a string.
  */
@@ -472,6 +443,11 @@ declare function stripAnsi(input: string): string;
  */
 declare function quote(input: string): string;
 
+/**
+ * Clear the contents and scrollback buffer of the tty by printing special characters into stdout.
+ */
+declare function clear(): void;
+
 // Colors
 
 /** Wrap a string with the ANSI control characters that will make it print as black text. */
@@ -533,10 +509,354 @@ declare function hidden(input: string | number): string;
 /** Wrap a string with the ANSI control characters that will make it print with a horizontal line through its center. */
 declare function strikethrough(input: string | number): string;
 
+declare type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array;
+declare type TypedArrayConstructor =
+  | Int8ArrayConstructor
+  | Uint8ArrayConstructor
+  | Uint8ClampedArrayConstructor
+  | Int16ArrayConstructor
+  | Uint16ArrayConstructor
+  | Int32ArrayConstructor
+  | Uint32ArrayConstructor
+  | Float32ArrayConstructor
+  | Float64ArrayConstructor;
+
+declare const is: {
+  string(value: any): value is string;
+  String(value: any): value is string;
+  number(value: any): value is number;
+  Number(value: any): value is number;
+  boolean(value: any): value is boolean;
+  Boolean(value: any): value is boolean;
+  bigint(value: any): value is bigint;
+  BigInt(value: any): value is BigInt;
+  symbol(value: any): value is symbol;
+  Symbol(value: any): value is symbol;
+  null(value: any): value is null;
+  undefined(value: any): value is undefined;
+  void(value: any): value is null | undefined;
+  object(value: any): value is {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Object(value: any): value is {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Array(value: any): value is unknown[];
+  function(value: any): value is Function & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Function(value: any): value is Function & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  tagged(value: any, tag: string): boolean;
+  instanceOf<T>(value: any, klass: new (...args: any) => T): value is T;
+  Error(value: any): value is Error;
+  Infinity(value: any): value is number;
+  NegativeInfinity(value: any): value is number;
+  NaN(value: any): value is number;
+  Date(value: any): value is Date;
+  RegExp(value: any): value is RegExp;
+  Map(value: any): value is Map<unknown, unknown>;
+  Set(value: any): value is Set<unknown>;
+  WeakMap(value: any): value is Map<unknown, unknown>;
+  WeakSet(value: any): value is Set<unknown>;
+  ArrayBuffer(value: any): value is ArrayBuffer;
+  SharedArrayBuffer(value: any): value is SharedArrayBuffer;
+  DataView(value: any): value is DataView;
+  TypedArray(value: any): value is TypedArray;
+  Int8Array(value: any): value is Int8Array;
+  Uint8Array(value: any): value is Uint8Array;
+  Uint8ClampedArray(value: any): value is Uint8ClampedArray;
+  Int16Array(value: any): value is Int16Array;
+  Uint16Array(value: any): value is Uint16Array;
+  Int32Array(value: any): value is Int32Array;
+  Uint32Array(value: any): value is Uint32Array;
+  Float32Array(value: any): value is Float32Array;
+  Float64Array(value: any): value is Float64Array;
+  Promise(value: any): value is Promise<unknown>;
+  Generator(value: any): value is Generator<unknown, any, unknown>;
+  GeneratorFunction(value: any): value is GeneratorFunction;
+  AsyncFunction(value: any): value is ((...args: any) => Promise<unknown>) & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  AsyncGenerator(value: any): value is AsyncGenerator<unknown, any, unknown>;
+  AsyncGeneratorFunction(value: any): value is AsyncGeneratorFunction;
+
+  FILE(value: any): value is FILE;
+
+  JSX: {
+    /** Returns whether `value` is a JSX Element object as created via JSX syntax. */
+    Element(value: any): value is JSX.Element;
+    /** Returns whether `value` is a JSX fragment element as created via JSX syntax. */
+    Fragment(value: any): value is JSX.Fragment;
+  };
+};
+
+/**
+ * The data source of a pipe operation; either an in-memory object, or a
+ * file stream.
+ *
+ * - Use `maxLength` to limit how much data to read.
+ * - Use `until` to stop reading once a certain byte or character has been
+ *   read.
+ * - Use `path` or `fd` to open a file.
+ */
+declare type PipeSource =
+  | { data: string; maxLength?: number; until?: string | byte }
+  | ArrayBuffer
+  | { data: ArrayBuffer; maxLength?: number; until?: string | byte }
+  | SharedArrayBuffer
+  | { data: SharedArrayBuffer; maxLength?: number; until?: string | byte }
+  | TypedArray
+  | { data: TypedArray; maxLength?: number; until?: string | byte }
+  | DataView
+  | { data: DataView; maxLength?: number; until?: string | byte }
+  | FILE
+  | {
+      data: FILE;
+      maxLength?: number;
+      until?: string | byte;
+    }
+  | { path: string; maxLength?: number; until?: string | byte }
+  | { fd: number; maxLength?: number; until?: string | byte };
+
+/**
+ * The target destination of a pipe operation; either an in-memory object, or a
+ * file stream.
+ *
+ * - Use `intoExisting` to put data into an existing object or file handle.
+ * - Use `intoNew` to put data into a new object.
+ * - Use `path` or `fd` to create a new file handle and put data into it.
+ */
+export type PipeDestination =
+  | ArrayBuffer
+  | SharedArrayBuffer
+  | DataView
+  | TypedArray
+  | FILE
+  | ArrayBufferConstructor
+  | SharedArrayBufferConstructor
+  | DataViewConstructor
+  | TypedArrayConstructor
+  | StringConstructor
+  | { path: string }
+  | { fd: number };
+
+/**
+ * Copy data from one source into the given target. Returns the number of bytes
+ * written, and the target that data was written into.
+ */
+declare function pipe<Dest extends PipeDestination>(
+  from: PipeSource,
+  to: Dest
+): {
+  bytesTransferred: number;
+  target: Dest extends
+    | ArrayBuffer
+    | SharedArrayBuffer
+    | DataView
+    | FILE
+    | { path: string }
+    | { fd: number }
+    ? Dest
+    : Dest extends
+        | ArrayBufferConstructor
+        | SharedArrayBufferConstructor
+        | DataViewConstructor
+        | TypedArrayConstructor
+        | DataViewConstructor
+    ? Dest["prototype"]
+    : Dest extends StringConstructor
+    ? string
+    : never;
+};
+
+/**
+ * Returns the absolute path to the root folder of the git/hg repo.
+ *
+ * This is done by running `git rev-parse --show-toplevel` and `hg root`.
+ *
+ * If `relativeTo` is provided, the git and hg commands will be executed in
+ * that folder instead of in `pwd()`.
+ */
+declare function repoRoot(relativeTo?: string): string;
+
+/**
+ * Returns whether the provided path is ignored by git.
+ */
+declare function isGitignored(path: string): boolean;
+
+/**
+ * Configures the default value of `trace` in functions which receive `trace`
+ * as an option.
+ *
+ * - If called with `true`, the default value of `trace` in all functions which
+ *   receive a `trace` option will be changed to `console.error`.
+ * - If called with `false`, the default value of `trace` in all functions which
+ *   receive a `trace` option will be changed to `undefined`.
+ * - If called with any other value, the provided value will be used as the
+ *   default value of `trace` in all functions which receive a `trace` option.
+ *
+ * If you would like to make your own functions use the default value of
+ * `trace` as set by this function (in order to get the same behavior as
+ * yavascript API functions which do so), call `traceAll.getDefaultTrace()` to
+ * get the value which should be used as the default value.
+ */
+declare const traceAll: ((
+  trace: boolean | undefined | ((...args: Array<any>) => void)
+) => void) & {
+  getDefaultTrace(): ((...args: Array<any>) => void) | undefined;
+};
+
+declare namespace JSX {
+  /**
+   * A string containing the expression that should be called to create JSX
+   * elements.
+   *
+   * Defaults to "JSX.createElement".
+   *
+   * If changed, any JSX code loaded afterwards will use a different
+   * expression.
+   *
+   * Note that if you change this, you need to verify that the following
+   * expression always evaluates to `true` (by changing {@link is.JSX.Element}
+   * and {@link is.JSX.Fragment}):
+   * ```jsx
+   * is.JSX.Element(<a />) && is.JSX.Fragment(<></>)
+   * ```
+   *
+   * Failure to uphold this guarantee indicates a bug.
+   */
+  export let pragma: string;
+
+  /**
+   * A string containing the expression that should be used as the first
+   * parameter when creating JSX fragment elements.
+   *
+   * Defaults to "JSX.Fragment".
+   *
+   * If changed, any JSX code loaded afterwards will use a different
+   * expression.
+   *
+   * Note that if you change this, you need to verify that the following
+   * expression always evaluates to `true` (by changing {@link is.JSX.Element}
+   * and {@link is.JSX.Fragment}):
+   * ```jsx
+   * is.JSX.Element(<a />) && is.JSX.Fragment(<></>)
+   * ```
+   *
+   * Failure to uphold this guarantee indicates a bug.
+   */
+  export let pragmaFrag: string;
+
+  export const Element: unique symbol;
+
+  export interface Element<
+    Props = { [key: string | symbol | number]: any },
+    Type = any
+  > {
+    $$typeof: typeof Element;
+    type: Type;
+    props: Props;
+    key: string | number | null;
+  }
+
+  /**
+   * The value which gets passed into the JSX element constructor (as
+   * determined by {@link JSX.pragma}) when JSX fragment syntax is used (unless
+   * {@link JSX.pragmaFrag} is changed).
+   */
+  export const Fragment: unique symbol;
+
+  export type Fragment = Element<{}, typeof Fragment>;
+
+  /**
+   * The JSX element constructor, which gets invoked whenever JSX syntax is
+   * used (unless {@link JSX.pragma} is changed).
+   */
+  export const createElement: {
+    <Type extends string | typeof Fragment | ((...args: any) => any)>(
+      type: Type
+    ): Element<{}, Type>;
+    <
+      Type extends string | typeof Fragment | ((...args: any) => any),
+      Props extends { [key: string | number | symbol]: any }
+    >(
+      type: Type,
+      props: Props
+    ): Element<Props, Type>;
+
+    <
+      Type extends string | typeof Fragment | ((...args: any) => any),
+      Props extends { [key: string | number | symbol]: any },
+      Children extends Array<any>
+    >(
+      type: Type,
+      props: Props,
+      ...children: Children
+    ): Element<Props & { children: Children }, Type>;
+
+    <
+      Type extends string | typeof Fragment | ((...args: any) => any),
+      Children extends Array<any>
+    >(
+      type: Type,
+      ...children: Children
+    ): Element<{ children: Children }, Type>;
+  };
+}
+
+// prettier-ignore
+/** Any integer in the range [0, 255]. */
+declare type byte =
+|   0 |   1 |   2 |   3 |   4 |   5 |   6 |   7 |   8 |   9 |  10 |  11 |  12 |  13 |  14 |  15 
+|  16 |  17 |  18 |  19 |  20 |  21 |  22 |  23 |  24 |  25 |  26 |  27 |  28 |  29 |  30 |  31 
+|  32 |  33 |  34 |  35 |  36 |  37 |  38 |  39 |  40 |  41 |  42 |  43 |  44 |  45 |  46 |  47 
+|  48 |  49 |  50 |  51 |  52 |  53 |  54 |  55 |  56 |  57 |  58 |  59 |  60 |  61 |  62 |  63 
+|  64 |  65 |  66 |  67 |  68 |  69 |  70 |  71 |  72 |  73 |  74 |  75 |  76 |  77 |  78 |  79 
+|  80 |  81 |  82 |  83 |  84 |  85 |  86 |  87 |  88 |  89 |  90 |  91 |  92 |  93 |  94 |  95 
+|  96 |  97 |  98 |  99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 
+| 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 
+| 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 
+| 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 
+| 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 
+| 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 
+| 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 
+| 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 
+| 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 
+| 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255;
+
+// Convenience aliases to provide parity with TypeScript types.
+declare var number: NumberConstructor;
+declare var string: StringConstructor;
+declare var boolean: BooleanConstructor;
+declare var bigint: BigIntConstructor;
+declare var symbol: SymbolConstructor;
+
+// ==========================================
 // ------------------------------------------
 // QuickJS APIs, which YavaScript builds upon
 // ------------------------------------------
-
+// ==========================================
 // Definitions of the globals and modules added by quickjs-libc
 
 /**
@@ -569,6 +889,91 @@ declare var console: {
   info: typeof print;
 };
 
+/** An object representing a file handle. */
+declare interface FILE {
+  /**
+   * Human-readable description of where this FILE points.
+   *
+   * If `target` is a number, the FILE was opened with fdopen, and `target` is
+   * the fd. Otherwise, `target` will be an arbitrary string that describes the
+   * file; it may be the absolute path to the file, the relative path to the
+   * file at time of its opening, or some other string like "stdin" or
+   * "tmpfile".
+   *
+   * You should *not* use this property for anything other than logging and
+   * debugging. It is *only* provided for debugging and/or troubleshooting
+   * purposes. The value of this property could change at any time when
+   * upgrading yavascript, even if upgrading by a minor or patch release.
+   */
+  target: string | number;
+
+  /**
+   * Close the file handle. Note that for files other than stdin/stdout/stderr,
+   * the file will be closed automatically when the `FILE` object is
+   * garbage-collected.
+   */
+  close(): void;
+
+  /** Outputs the string with the UTF-8 encoding. */
+  puts(str: string): void;
+
+  /**
+   * Formatted printf.
+   *
+   * The same formats as the standard C library `printf` are supported. Integer format types (e.g. `%d`) truncate the Numbers or BigInts to 32 bits. Use the `l` modifier (e.g. `%ld`) to truncate to 64 bits.
+   */
+  printf(fmt: string, ...args: Array<any>): void;
+
+  /** Flush the buffered file. Wrapper for C `fflush`. */
+  flush(): void;
+
+  /** Sync the buffered file to disk. Wrapper for C `fsync`. */
+  sync(): void;
+
+  /**
+   * Seek to a given file position (whence is `std.SEEK_*`).
+   *
+   * `offset` can be a number or a bigint.
+   */
+  seek(offset: number, whence: number): void;
+
+  /** Return the current file position. */
+  tell(): number;
+
+  /** Return the current file position as a bigint. */
+  tello(): BigInt;
+
+  /** Return true if end of file. */
+  eof(): boolean;
+
+  /** Return the associated OS handle. */
+  fileno(): number;
+
+  /** Read `length` bytes from the file to the ArrayBuffer `buffer` at byte position `position` (wrapper to the libc `fread`). Returns the number of bytes read, or `0` if the end of the file has been reached.  */
+  read(buffer: ArrayBuffer, position: number, length: number): number;
+
+  /** Write `length` bytes from the ArrayBuffer `buffer` at byte position `position` into the file (wrapper to the libc `fwrite`). Returns the number of bytes written. */
+  write(buffer: ArrayBuffer, position: number, length: number): number;
+
+  /**
+   * Return the next line from the file, assuming UTF-8 encoding, excluding the trailing line feed or EOF.
+   *
+   * If the end of the file has been reached, then `null` will be returned instead of a string.
+   *
+   * Note: Although the trailing line feed has been removed, a carriage return (`\r`) may still be present.
+   */
+  getline(): string | null;
+
+  /** Read `maxSize` bytes from the file and return them as a string assuming UTF-8 encoding. If `maxSize` is not present, the file is read up its end. */
+  readAsString(maxSize?: number): string;
+
+  /** Return the next byte from the file. Return -1 if the end of file is reached. */
+  getByte(): number;
+
+  /** Write one byte to the file. */
+  putByte(value: number): void;
+}
+
 declare module "std" {
   /**
    * Exit the process with the provided status code.
@@ -626,6 +1031,14 @@ declare module "std" {
    */
   export function getFileNameFromStack(stackLevels: number): string;
 
+  /**
+   * Return a boolean indicating whether the provided value is a FILE object.
+   *
+   * @param value - The value to check.
+   * @returns Whether the value was a `FILE` or not.
+   */
+  export function isFILE(value: any): boolean;
+
   /**
    * Open a file (wrapper to the libc `fopen()`).
    * Return the FILE object.
@@ -825,68 +1238,6 @@ declare module "std" {
    * - octal (0o prefix) and hexadecimal (0x prefix) numbers
    */
   export function parseExtJSON(str: string): any;
-
-  /** An object representing a file handle. */
-  export class FILE {
-    /** Close the file.  */
-    close(): void;
-
-    /** Outputs the string with the UTF-8 encoding. */
-    puts(str: string): void;
-
-    /**
-     * Formatted printf.
-     *
-     * The same formats as the standard C library `printf` are supported. Integer format types (e.g. `%d`) truncate the Numbers or BigInts to 32 bits. Use the `l` modifier (e.g. `%ld`) to truncate to 64 bits.
-     */
-    printf(fmt: string, ...args: Array<any>): void;
-
-    /** Flush the buffered file. Wrapper for C `fflush`. */
-    flush(): void;
-
-    /** Sync the buffered file to disk. Wrapper for C `fsync`. */
-    sync(): void;
-
-    /**
-     * Seek to a given file position (whence is `std.SEEK_*`).
-     *
-     * `offset` can be a number or a bigint.
-     */
-    seek(
-      offset: number,
-      whence: typeof SEEK_SET | typeof SEEK_CUR | typeof SEEK_END
-    ): void;
-
-    /** Return the current file position. */
-    tell(): number;
-
-    /** Return the current file position as a bigint. */
-    tello(): BigInt;
-
-    /** Return true if end of file. */
-    eof(): boolean;
-
-    /** Return the associated OS handle. */
-    fileno(): number;
-
-    /** Read `length` bytes from the file to the ArrayBuffer `buffer` at byte position `position` (wrapper to the libc `fread`). Returns the number of bytes read, or `0` if the end of the file has been reached.  */
-    read(buffer: ArrayBuffer, position: number, length: number): number;
-
-    /** Write `length` bytes from the ArrayBuffer `buffer` at byte position `position` into the file (wrapper to the libc `fwrite`). Returns the number of bytes written. */
-    write(buffer: ArrayBuffer, position: number, length: number): number;
-
-    /** Return the next line from the file, assuming UTF-8 encoding, excluding the trailing line feed. */
-    getline(): string;
-
-    /** Read `maxSize` bytes from the file and return them as a string assuming UTF-8 encoding. If `maxSize` is not present, the file is read up its end. */
-    readAsString(maxSize?: number): string;
-
-    /** Return the next byte from the file. Return -1 if the end of file is reached. */
-    getByte(): number;
-
-    /** Write one byte to the file. */
-    putByte(value: number): void;
-  }
 }
 
 declare module "os" {
@@ -1151,6 +1502,24 @@ declare module "os" {
 
   /** Constant for the `options` argument of `waitpid`. */
   export var WNOHANG: number;
+  /** Constant for the `options` argument of `waitpid`. */
+  export var WUNTRACED: number;
+
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WEXITSTATUS(status: number): number;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WTERMSIG(status: number): number;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WSTOPSIG(status: number): number;
+
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WIFEXITED(status: number): boolean;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WIFSIGNALED(status: number): boolean;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WIFSTOPPED(status: number): boolean;
+  /** Function to be used to interpret the 'status' return value of `waitpid`. */
+  export function WIFCONTINUED(status: number): boolean;
 
   /** `dup` Unix system call. */
   export function dup(fd: number): number;
@@ -1368,3 +1737,118 @@ declare interface InspectFunction {
  */
 declare var inspect: InspectFunction;
 
+/**
+ * A class which represents a module namespace object. Note, however, that
+ * instances of this class cannot be constructed manually, and must instead be
+ * obtained from `import * as`, `import()`, `std.importModule`, or `require`.
+ *
+ * The static properties on `Module` let you configure the module loader
+ * (import/export/require). You can use these properties to add support for
+ * importing new filetypes.
+ */
+declare class Module {
+  /** A module namespace object has arbitrary exports. */
+  [key: string | number | symbol]: any;
+
+  /**
+   * Module objects are not constructable.
+   *
+   * You must instead obtain them using import or require.
+   */
+  private constructor();
+
+  /**
+   * Returns true if `target` is a module namespace object.
+   */
+  static [Symbol.hasInstance](target: any): target is Module;
+
+  /**
+   * A list of filetype extensions that may be omitted from an import specifier
+   * string.
+   *
+   * Defaults to `[".js"]`. You can add more strings to this array to
+   * make the engine search for additional files when resolving a
+   * require/import.
+   *
+   * See the doc comment on {@link require} for more information.
+   *
+   * NOTE: If you add a new extension to this array, you will likely also want
+   * to add to {@link Module.compilers}.
+   */
+  static searchExtensions: Array<string>;
+
+  /**
+   * User-defined functions which will handle getting the JavaScript code
+   * associated with a module.
+   *
+   * The key for each property in this object should be a file extension
+   * string with a leading dot, eg `".jsx"`. The value for each property should
+   * be a function which receives the filepath to a module, and should
+   * synchronously load that file, then return a string containing JavaScript
+   * code that corresponds to that module. In many cases, these functions will
+   * compile the contents of the file from one format into JavaScript.
+   *
+   * By adding to this object, you can make it possible to import non-js
+   * filetypes; compile-to-JS languages like JSX, TypeScript, and CoffeeScript
+   * can be compiled at import time, and asset files like .txt files or .png
+   * files can be converted into an appropriate data structure at import time.
+   *
+   * As an example, to make it possible to import .txt files, you might do:
+   * ```js
+   * import * as std from "std";
+   *
+   * Module.compilers[".txt"] = (filename) => {
+   *   const content = std.loadFile(filename);
+   *   return `export default ${JSON.stringify(content)}`;
+   * }
+   * ```
+   * (leveraging `JSON.stringify`'s ability to escape quotes).
+   *
+   * Then, later in your code, you can do:
+   * ```js
+   * import names from "./names.txt";
+   * ```
+   *
+   * And `names` will be a string containing the contents of names.txt.
+   *
+   * NOTE: When adding to this object, you may also wish to add to
+   * {@link Module.searchExtensions}.
+   */
+  static compilers: {
+    [extensionWithDot: string]: (filename: string) => string;
+  };
+}
+
+/**
+ * Synchronously import a module.
+ *
+ * `source` will be resolved relative to the calling file.
+ *
+ * If `source` does not have a file extension, and a file without an extension
+ * cannot be found, the engine will check for files with the extensions in
+ * {@link Module.searchExtensions}, and use one of those if present. This
+ * behavior also happens when using normal `import` statements.
+ *
+ * For example, if you write:
+ *
+ * ```js
+ * import something from "./somewhere";
+ * ```
+ *
+ * but there's no file named `somewhere` in the same directory as the file
+ * where that import appears, and `Module.searchExtensions` is the default
+ * value:
+ *
+ * ```js
+ * [".js"]
+ * ```
+ *
+ * then the engine will look for `somewhere.js`. If that doesn't exist, the
+ * engine will look for `somewhere/index.js`. If *that* doesn't exist, an error
+ * will be thrown.
+ *
+ * If you add more extensions to `Module.searchExtensions`, then the engine
+ * will use those, too. It will search in the same order as the strings appear
+ * in the `Module.searchExtensions` array.
+ */
+declare var require: (source: string) => Module;