yavascript 0.0.6 → 0.0.7

package/README.md

@@ -1,35 +1,79 @@
 # yavascript
 
-YavaScript is a bash-like script runner which is distributed as a single
-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
+YavaScript is a cross-platform bash-like script runner and repl which is distributed as a single
+statically-linked binary. Scripts can be written in JavaScript, TypeScript, JSX/TSX, or CoffeeScript.
+
+There are APIs available for all the things you'd normally want to do in
 a bash script, such as:
 
-- Running programs
-- Accessing environment variables
-- Reading and writing file contents
+- Running programs and getting their stdout/stderr/status
+- Reading/writing environment variables
 - Checking if files/folders exist
-- Removing files/folders
+- Removing/creating/copying files/folders
 - Reading and changing the current working directory
+- Reading and resolving symbolic links
 - Using globs to get large lists of files
-- Printing stylized text to the terminal
+- Printing stylized text
+- Clearing the terminal
+- Fetching files from the internet
 
-Additionally, since it's JavaScript, you get some other features that are
-either not present in bash or are cumbersome to use in bash, namely:
+Additionally, you can do other things that are either not present in bash or are cumbersome to use in bash, namely:
 
-- Arrays (lists) and Objects (key/value dictionaries)
-- Working with path strings
-- Working with JSON
+- Serialize and deserialize JSON, CSV, and YAML
+- Removing ANSI control characters from a string
+- Split path strings into a list of segments and rejoin them into a string
+- Check if a path is absolute and resolve relative paths
+- Parse command-line flags
+- Work with Arrays (lists)
+- Work with Objects (key/value dictionaries)
+- Work with Typed Arrays (byte buffers)
+- Reliably get the path to the currently-running file
+- Strongly-typed interfaces and functions (via TypeScript)
 - Cross-file import/export using ECMAScript Modules
-- Splitting strings on delimeters
-- Pretty-printing of objects
-- Getting the path to the currently-running script (via import.meta.url or `__filename`)
-- Getting the absolute path to the root folder of the current git/mercurial repo (repoRoot function)
+- Split strings on delimeters
+- Pretty-print complex structures
+- Call low-level POSIX C APIs like fputs, sprintf, isatty
+- Perform work in threads
+
+You'll also find analogues to familiar CLI tools, like:
+
+- dirname
+- basename
+- cat
+- ls
+- realpath
+- readlink
+
+...and more.
 
 To view the APIs, consult the file yavascript.d.ts which was distributed with
 this program, or online at https://github.com/suchipi/yavascript/blob/main/yavascript.d.ts.
 This file contains TypeScript type definitions which can be given to your IDE
-to assist you when writing scripts.
+to assist you when writing scripts, even if you aren't writing your scripts in TypeScript.
+
+Here's an example of a script using YavaScript:
+
+```js
+#!/usr/bin/env yavascript
+
+// This comment is optional; it tells VS Code to load the specified TypeScript definitions.
+/// <reference path="./yavascript.d.ts" />
+
+let isWorkingTreeDirty;
+try {
+  exec(`git diff --quiet`);
+  isWorkingTreeDirty = false;
+} catch (error) {
+  isWorkingTreeDirty = true;
+}
+
+const branchName = $(`git rev-parse --abbrev-ref HEAD`).stdout.trim();
+
+const gitInfo = { branchName, isWorkingTreeDirty };
+echo(gitInfo);
+
+writeFile("git-info.yml", YAML.stringify(gitInfo));
+```
 
 YavaScript is powered by a fork of the QuickJS JavaScript Engine, originally
 written by Fabrice Bellard. QuickJS is a small, fast JavaScript engine
@@ -42,7 +86,11 @@ supporting the ES2020 specification.
 
 ### Binaries (all platforms)
 
-You will need docker installed, then run `./scripts/build.sh`.
+You will need docker installed, then run `meta/docker/build-all.sh`.
+
+### Binaries (just for your machine)
+
+You will need node.js and ninja installed, then run `meta/build.sh`.
 
 ### Docker image
 

package/lib/binary-path.js

@@ -1,30 +1,33 @@
 var path = require("path");
 
-var binaryPath;
-if (process.platform === "win32") {
-  binaryPath = path.resolve(
-    __dirname,
-    "..",
-    "bin",
-    "windows",
-    "yavascript.exe"
-  );
-} else if (process.platform === "darwin") {
-  if (process.arch.startsWith("arm")) {
-    binaryPath = path.resolve(
-      __dirname,
-      "..",
-      "bin",
-      "darwin-arm",
-      "yavascript"
-    );
-  } else {
-    binaryPath = path.resolve(__dirname, "..", "bin", "darwin", "yavascript");
+var binDir = path.resolve(__dirname, "..", "bin");
+
+function getBinaryPath(platformAndArch) {
+  switch (platformAndArch) {
+    case "darwin-arm64": {
+      return path.join(binDir, "darwin-arm64", "yavascript");
+    }
+    case "darwin-x64": {
+      return path.join(binDir, "darwin-x86_64", "yavascript");
+    }
+    case "linux-arm64": {
+      return path.join(binDir, "linux-aarch64", "yavascript");
+    }
+    case "linux-x64": {
+      return path.join(binDir, "linux-amd64", "yavascript");
+    }
+    case "win32-x64": {
+      return path.join(binDir, "windows-x86_64", "yavascript.exe");
+    }
+    default: {
+      throw new Error("Unsupported platform: " + platformAndArch);
+    }
   }
-} else if (process.platform === "linux") {
-  binaryPath = path.resolve(__dirname, "..", "bin", "linux", "yavascript");
-} else {
-  throw new Error("Unsupported platform: " + process.platform);
 }
 
-module.exports = binaryPath;
+var binaryPath = getBinaryPath(process.platform + "-" + process.arch);
+
+module.exports = {
+  getBinaryPath: getBinaryPath,
+  binaryPath: binaryPath,
+};

package/lib/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 var child_process = require("child_process");
-var binaryPath = require("./binary-path");
+var binaryPath = require("./binary-path").binaryPath;
 
 try {
   child_process.execFileSync(binaryPath, process.argv.slice(2), {

package/lib/index.js

@@ -1,7 +1,9 @@
-const binaryPath = require("./binary-path");
-const version = require("./package.json").version;
+var getBinaryPath = require("./binary-path").getBinaryPath;
+var binaryPath = require("./binary-path").binaryPath;
+var version = require("../package.json").version;
 
 module.exports = {
+  getBinaryPath,
   binaryPath,
   version,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yavascript",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "main": "lib/index.js",
   "bin": "lib/cli.js",
   "types": "yavascript.d.ts",

package/yavascript.d.ts

@@ -12,25 +12,86 @@
 declare const env: { [key: string]: string | undefined };
 
 /**
- * Return the contents of a directory, as absolute paths. `.` and `..` are
- * omitted.
+ * Parse command line --flags into an object of flags and an array of
+ * positional arguments. This function is opinionated; if it doesn't meet your
+ * needs, you can parse the `scriptArgs` global manually.
  *
- * 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.
+ * Flags `--like-this`, `--like_this`, or `--LIKE_THIS` get converted into
+ * property names `likeThis` on the returned flags object.
  *
- * Returns the target of the symlink, which may be absolute or relative.
+ * Flags like this: `-v` get converted into into property names like this: `v`
+ * on the returned flags object.
  *
- * Provides the same functionality as the unix binary of the same name.
+ * Anything that appears after `--` is considered a positional argument instead
+ * of a flag. `--` is not present in the returned positional arguments Array.
+ *
+ * Single-character flags must have a single leading dash, and multi-character
+ * flags must have two leading dashes.
+ *
+ * Flags with equals signs in them (eg. `--something=42`) are not supported.
+ * Write `--something 42` instead.
+ *
+ * Flags where you specify them multiple times, like `-vvv`, are not supported.
+ * Write something like `-v 3` instead.
+ *
+ * @param hints - An object whose keys are flag names (in camelCase) and whose values indicate what type to treat that flag as. Valid property values are `String`, `Boolean`, `Number`, and `parseScriptArgs.Path`. `parseScriptArgs.Path` will resolve relative paths into absolute paths for you. If no hints object is specified, `parseScriptArgs` will do its best to guess, based on the command-line args.
+ * @param argv - An array containing the command line flags you want to parse. If unspecified, `scriptArgs.slice(2)` will be used (we slice 2 in order to skip the yavascript binary and script name). If you pass in an array here, it should only contain command-line flags, not the binary being called.
+ *
+ * @returns An object with two properties: `flags` and `args`. `flags` is an object whose keys are camelCase flag names and whose values are strings, booleans, or numbers corresponding to the input command-line args. `args` is an Array of positional arguments, as found on the command-line.
  */
-declare function readlink(path: string): string;
+declare const parseScriptArgs: {
+  /**
+   * Parse command line --flags into an object of flags and an array of
+   * positional arguments. This function is opinionated; if it doesn't meet your
+   * needs, you can parse the `scriptArgs` global manually.
+   *
+   * Flags `--like-this`, `--like_this`, or `--LIKE_THIS` get converted into
+   * property names `likeThis` on the returned flags object.
+   *
+   * Flags like this: `-v` get converted into into property names like this: `v`
+   * on the returned flags object.
+   *
+   * Anything that appears after `--` is considered a positional argument instead
+   * of a flag. `--` is not present in the returned positional arguments Array.
+   *
+   * Single-character flags must have a single leading dash, and multi-character
+   * flags must have two leading dashes.
+   *
+   * Flags with equals signs in them (eg. `--something=42`) are not supported.
+   * Write `--something 42` instead.
+   *
+   * Flags where you specify them multiple times, like `-vvv`, are not supported.
+   * Write something like `-v 3` instead.
+   *
+   * @param hints - An object whose keys are flag names (in camelCase) and whose values indicate what type to treat that flag as. Valid property values are `String`, `Boolean`, `Number`, and `parseScriptArgs.Path`. `parseScriptArgs.Path` will resolve relative paths into absolute paths for you. If no hints object is specified, `parseScriptArgs` will do its best to guess, based on the command-line args.
+   * @param args - An array containing the command line flags you want to parse. If unspecified, `scriptArgs.slice(2)` will be used (we slice 2 in order to skip the yavascript binary and script name). If you pass in an array here, it should only contain command-line flags, not the binary being called.
+   *
+   * @returns An object with two properties: `flags` and `args`. `flags` is an object whose keys are camelCase flag names and whose values are strings, booleans, or numbers corresponding to the input command-line args. `args` is an Array of positional arguments, as found on the command-line.
+   */
+  (
+    hints?: {
+      [key: string]:
+        | typeof String
+        | typeof Boolean
+        | typeof Number
+        | typeof parseScriptArgs["Path"];
+    },
+    args?: Array<string>
+  ): {
+    flags: { [key: string]: any };
+    args: Array<string>;
+  };
+
+  /**
+   * A hint value for {@link parseScriptArgs}. Behaves similar to the hint value
+   * `String`, except that it also resolves relative paths into absolute paths,
+   * using the following rules:
+   *
+   * - paths `./like/this` or `../like/this` get resolved relative to `pwd()`.
+   * - paths `like/this` or `this` get resolved relative to `pwd()` as if they had a leading `./`.
+   */
+  readonly Path: unique symbol;
+};
 
 /**
  * Read the contents of a file from disk, as a UTF-8 string.
@@ -131,28 +192,191 @@ declare type CopyOptions = {
  */
 declare function copy(from: string, to: string, options?: CopyOptions): void;
 
+/** An object that represents a filesystem path. */
+declare class Path {
+  /** The character used to separate path segments on this OS. */
+  static readonly OS_SEGMENT_SEPARATOR: "/" | "\\";
+
+  /**
+   * The character used to separate entries within the PATH environment
+   * variable on this OS.
+   */
+  static readonly OS_ENV_VAR_SEPARATOR: ":" | ";";
+
+  /** Split one or more path strings into an array of path segments. */
+  static splitToSegments(inputParts: Array<string> | string): Array<string>;
+
+  /**
+   * Search the provided path string or strings for a path separator character,
+   * and return it. If none is found, return `fallback`, which defaults to the
+   * OS's path segment separator.
+   */
+  static detectSeparator<Fallback extends string | null = string>(
+    input: Array<string> | string,
+    // @ts-ignore might be instantiated with a different subtype
+    fallback: Fallback = Path.OS_SEGMENT_SEPARATOR
+  ): string | Fallback;
+
+  /** Join together one or more paths. */
+  static join(...inputs: Array<string | Path | Array<string | Path>>): string;
+
+  /**
+   * Turns the input path(s) into an absolute path by resolving all `.` and `..`
+   * segments, using `pwd()` as a base dir to use when resolving leading `.` or
+   * `..` segments.
+   */
+  static resolve(
+    ...inputs: Array<string | Path | Array<string | Path>>
+  ): string;
+
+  /**
+   * Concatenates the input path(s) and then resolves all non-leading `.` and
+   * `..` segments.
+   */
+  static normalize(
+    ...inputs: Array<string | Path | Array<string | Path>>
+  ): string;
+
+  /**
+   * Return whether the provided path string is absolute; that is, whether it
+   * starts with either `/` or a drive letter (ie `C:`).
+   */
+  static isAbsolute(path: string): boolean;
+
+  /**
+   * An array of the path segments that make up this path.
+   *
+   * For `/tmp/foo.txt`, it'd be `["", "tmp", "foo.txt"]`.
+   *
+   * For `C:\something\somewhere.txt`, it'd be `["C:", "something", "somewhere.txt"]`.
+   */
+  segments: Array<string>;
+
+  /**
+   * The path separator that should be used to turn this path into a string.
+   *
+   * Will be either `/` or `\`.
+   */
+  separator: string;
+
+  /** Create a new Path object using the provided input(s). */
+  constructor(...inputs: Array<string | Path | Array<string | Path>>);
+
+  /** Create a new Path object using the provided segments and separator. */
+  static from(segments: Array<string>, separator: string): Path;
+
+  /**
+   * Turn this path into an absolute path by resolving all `.` and `..`
+   * segments, using `from` as a base dir to use when resolving leading `.` or
+   * `..` segments.
+   *
+   * If `from` is unspecified, it defaults to `pwd()`.
+   */
+  resolve(from?: string | Path): Path;
+
+  /**
+   * Resolve all non-leading `.` and `..` segments in this path.
+   */
+  normalize(): Path;
+
+  /**
+   * Create a new path by appending another path's segments after this path's
+   * segments.
+   *
+   * The returned path will use this path's separator.
+   */
+  concat(other: string | Path | Array<string | Path>): Path;
+
+  /**
+   * Return whether this path is absolute; that is, whether it starts with
+   * either `/` or a drive letter (ie `C:`).
+   */
+  isAbsolute(): boolean;
+
+  /**
+   * Turn this path into a string by joining its segments using its separator.
+   */
+  toString(): string;
+}
+
 /**
- * Change the process's current working directory to the specified path.
+ * The absolute path to the current file (whether script or module).
  *
- * Provides the same functionality as the shell builtin of the same name.
+ * Behaves the same as in Node.js, except that it's present within ES modules.
  */
-declare function cd(path: string): void;
+declare const __filename: string;
 
 /**
- * Return the process's current working directory.
+ * The absolute path to the directory the current file is inside of.
  *
- * Provides the same functionality as the shell builtin of the same name.
+ * Behaves the same as in Node.js, except that it's present within ES modules.
  */
-declare function pwd(): string;
+declare const __dirname: string;
 
 /**
- * Get the absolute path given a relative path. Symlinks are also resolved.
- *
- * The path's target file/directory must exist.
+ * Return the last component of a path string.
  *
  * Provides the same functionality as the unix binary of the same name.
  */
-declare function realpath(path: string): string;
+declare function basename(path: string): string;
+
+/**
+ * Read the contents of one of more files from disk as one UTF-8 string,
+ * print that string to stdout, then return it.
+ */
+declare function cat(...paths: Array<string>): string;
+
+/**
+ * Change the process's current working directory to the specified path. If no
+ * path is specified, moves to the user's home directory.
+ *
+ * Provides the same functionality as the shell builtin of the same name.
+ */
+declare function cd(path?: string): void;
+
+/** A string representing who a permission applies to. */
+declare type ChmodPermissionsWho =
+  | "user"
+  | "group"
+  | "others"
+  | "all"
+  | "u"
+  | "g"
+  | "o"
+  | "a"
+  | "ug"
+  | "go"
+  | "uo";
+
+/** A string representing the access level for the given permission. */
+declare type ChmodPermissionsWhat =
+  | "read"
+  | "write"
+  | "execute"
+  | "readwrite"
+  | "none"
+  | "full"
+  | "r"
+  | "w"
+  | "x"
+  | "rw"
+  | "rx"
+  | "wx"
+  | "rwx";
+
+/**
+ * Set the permission bits for the specified file.
+ *
+ * @param permissions The permission bits to set. This can be a number, a string containing an octal number, or an object.
+ * @param path The path to the file.
+ */
+declare function chmod(
+  permissions:
+    | number
+    | string
+    | Record<ChmodPermissionsWho, ChmodPermissionsWhat>,
+  path: string
+): void;
 
 /**
  * Removes the final component from a path string.
@@ -162,11 +386,9 @@ declare function realpath(path: string): string;
 declare function dirname(path: string): string;
 
 /**
- * Return the last component of a path string.
- *
- * Provides the same functionality as the unix binary of the same name.
+ * Print one or more values to stdout.
  */
-declare function basename(path: string): string;
+declare const echo: typeof console.log;
 
 /**
  * Returns the file extension of the file at a given path.
@@ -181,71 +403,55 @@ declare function extname(
 ): string;
 
 /**
- * A namespace object providing several path-string-related APIs.
+ * 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 const paths: {
-  /**
-   * The separator character the host operating system uses between path
-   * components, ie. the slashes in a filepath. On windows, it's a backslash, and
-   * on all other OSes, it's a forward slash.
-   */
-  OS_PATH_SEPARATOR: "/" | "\\";
-
-  /**
-   * Split a path string (or array of path strings) on / or \\, returning an
-   * Array of strings.
-   *
-   * Trailing slashes and duplicate path separators will be removed.
-   *
-   * If the path starts with `/`, the first string in the Array will be empty.
-   */
-  split(path: string | Array<string>): Array<string>;
-
-  /**
-   * Detect which path separator is present in the given path or array of
-   * paths: `\` or `/`.
-   *
-   * If neither is present, `/` will be returned.
-   */
-  detectSeparator(input: string | Array<string>): string;
+declare function ls(
+  dir?: string,
+  options?: { relativePaths?: boolean }
+): Array<string>;
 
-  /**
-   * Create a path string from one or more path or path component strings.
-   * {@link paths.OS_PATH_SEPARATOR} will be used to combine parts.
-   *
-   * This function does not resolve `..` or `.`. Use {@link paths.resolve} for that.
-   */
-  join(...parts: Array<string>): string;
+/**
+ * Print data to stdout using C-style format specifiers.
+ */
+declare function printf(format: string, ...args: Array<any>): void;
 
-  /**
-   * Resolves all `..` and `.` components in a path, returning an absolute
-   * path.
-   *
-   * Use `from` to specify where leading `.` or `..` characters should be
-   * resolved relative to. If unspecified, it defaults to `pwd()`.
-   */
-  resolve(path: string, from?: string): string;
+/**
+ * Return the process's current working directory.
+ *
+ * Provides the same functionality as the shell builtin of the same name.
+ */
+declare function pwd(): string;
 
-  /**
-   * Returns whether the path starts with either a leading slash or a windows
-   * drive letter.
-   */
-  isAbsolute(path: string): 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;
 
 /**
- * The absolute path to the current file (whether script or module).
+ * Get the absolute path given a relative path. Symlinks are also resolved.
  *
- * Behaves the same as in Node.js, except that it's present within ES modules.
+ * The path's target file/directory must exist.
+ *
+ * Provides the same functionality as the unix binary of the same name.
  */
-declare const __filename: string;
+declare function realpath(path: string): string;
 
 /**
- * The absolute path to the directory the current file is inside of.
+ * If the file at `path` exists, update its creation/modification timestamps.
  *
- * Behaves the same as in Node.js, except that it's present within ES modules.
+ * Otherwise, create an empty file at that path.
+ *
+ * @param path The target path for the file.
  */
-declare const __dirname: string;
+declare function touch(path: string): void;
 
 declare type BaseExecOptions = {
   /** Sets the current working directory for the child process. */
@@ -428,11 +634,6 @@ declare function glob(
   options?: GlobOptions
 ): Array<string>;
 
-/**
- * Print one or more values to stdout.
- */
-declare const echo: typeof console.log;
-
 /**
  * Remove ANSI control characters from a string.
  */
@@ -509,6 +710,178 @@ declare function hidden(input: string | number): string;
 /** Wrap a string with the ANSI control characters that will make it print with a horizontal line through its center. */
 declare function strikethrough(input: string | number): string;
 
+/** Split `str` on newline and then return lines matching `pattern`. */
+declare const grepString: {
+  /** Split `str` on newline and then return lines matching `pattern`. */
+  (str: string, pattern: string | RegExp): Array<string>;
+
+  /** Split `str` on newline and then return lines matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: false }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return lines NOT matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: true }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return lines matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { details: false }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return lines matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: false; details: false }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return lines NOT matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: true; details: false }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return info about lines matching `pattern`. */
+  (str: string, pattern: string | RegExp, options: { details: true }): Array<{
+    lineNumber: number;
+    lineContent: string;
+    matches: RegExpMatchArray;
+  }>;
+
+  /** Split `str` on newline and then return info about lines matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: false; details: true }
+  ): Array<string>;
+
+  /** Split `str` on newline and then return info about lines NOT matching `pattern`. */
+  (
+    str: string,
+    pattern: string | RegExp,
+    options: { inverse: true; details: true }
+  ): Array<string>;
+};
+
+/** Read the content at `path`, split it on newline, and then return lines matching `pattern`. */
+declare const grepFile: {
+  /** Read the content at `path`, split it on newline,  and then return lines matching `pattern`. */
+  (path: string, pattern: string | RegExp): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: false }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines NOT matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: true }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { details: false }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: false; details: false }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return lines NOT matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: true; details: false }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return info about lines matching `pattern`. */
+  (path: string, pattern: string | RegExp, options: { details: true }): Array<{
+    lineNumber: number;
+    lineContent: string;
+    matches: RegExpMatchArray;
+  }>;
+
+  /** Read the content at `path`, split it on newline,  and then return info about lines matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: false; details: true }
+  ): Array<string>;
+
+  /** Read the content at `path`, split it on newline,  and then return info about lines NOT matching `pattern`. */
+  (
+    path: string,
+    pattern: string | RegExp,
+    options: { inverse: true; details: true }
+  ): Array<string>;
+};
+
+interface String {
+  // Same as grepString but without the first argument.
+  grep: {
+    /** Split the string on newline and then return lines matching `pattern`. */
+    (pattern: string | RegExp): Array<string>;
+
+    /** Split the string on newline and then return lines matching `pattern`. */
+    (pattern: string | RegExp, options: { inverse: false }): Array<string>;
+
+    /** Split the string on newline and then return lines NOT matching `pattern`. */
+    (pattern: string | RegExp, options: { inverse: true }): Array<string>;
+
+    /** Split the string on newline and then return lines matching `pattern`. */
+    (pattern: string | RegExp, options: { details: false }): Array<string>;
+
+    /** Split the string on newline and then return lines matching `pattern`. */
+    (
+      pattern: string | RegExp,
+      options: { inverse: false; details: false }
+    ): Array<string>;
+
+    /** Split the string on newline and then return lines NOT matching `pattern`. */
+    (
+      pattern: string | RegExp,
+      options: { inverse: true; details: false }
+    ): Array<string>;
+
+    /** Split the string on newline and then return info about lines matching `pattern`. */
+    (pattern: string | RegExp, options: { details: true }): Array<{
+      lineNumber: number;
+      lineContent: string;
+      matches: RegExpMatchArray;
+    }>;
+
+    /** Split the string on newline and then return info about lines matching `pattern`. */
+    (
+      pattern: string | RegExp,
+      options: { inverse: false; details: true }
+    ): Array<string>;
+
+    /** Split the string on newline and then return info about lines NOT matching `pattern`. */
+    (
+      pattern: string | RegExp,
+      options: { inverse: true; details: true }
+    ): Array<string>;
+  };
+}
+
 declare type TypedArray =
   | Int8Array
   | Uint8Array
@@ -538,7 +911,7 @@ declare const is: {
   boolean(value: any): value is boolean;
   Boolean(value: any): value is boolean;
   bigint(value: any): value is bigint;
-  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;
@@ -611,6 +984,132 @@ declare const is: {
   };
 };
 
+declare const assert: {
+  /**
+   * Throws an error if `value` is not truthy.
+   *
+   * @param value - The value to test for truthiness
+   * @param message - An optional error message to use. If unspecified, "Assertion failed" will be used.
+   */
+  <ValueType>(
+    value: ValueType,
+    message?: string
+  ): asserts value is ValueType extends null | undefined | false | 0 | ""
+    ? never
+    : ValueType;
+
+  string(value: any, message?: string): asserts value is string;
+  String(value: any, message?: string): asserts value is string;
+  number(value: any, message?: string): asserts value is number;
+  Number(value: any, message?: string): asserts value is number;
+  boolean(value: any, message?: string): asserts value is boolean;
+  Boolean(value: any, message?: string): asserts value is boolean;
+  bigint(value: any, message?: string): asserts value is bigint;
+  BigInt(value: any, message?: string): asserts value is bigint;
+  symbol(value: any, message?: string): asserts value is symbol;
+  Symbol(value: any, message?: string): asserts value is symbol;
+  null(value: any, message?: string): asserts value is null;
+  undefined(value: any, message?: string): asserts value is undefined;
+  void(value: any, message?: string): asserts value is null | undefined;
+  object(
+    value: any,
+    message?: string
+  ): asserts value is {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Object(
+    value: any,
+    message?: string
+  ): asserts value is {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Array(value: any, message?: string): asserts value is unknown[];
+  function(
+    value: any,
+    message?: string
+  ): asserts value is Function & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  Function(
+    value: any,
+    message?: string
+  ): asserts value is Function & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  tagged(value: any, tag: string, message?: string): void;
+  instanceOf<T>(value: any, klass: new (...args: any) => T): asserts value is T;
+  Error(value: any, message?: string): asserts value is Error;
+  Infinity(value: any, message?: string): asserts value is number;
+  NegativeInfinity(value: any, message?: string): asserts value is number;
+  NaN(value: any, message?: string): asserts value is number;
+  Date(value: any, message?: string): asserts value is Date;
+  RegExp(value: any, message?: string): asserts value is RegExp;
+  Map(value: any, message?: string): asserts value is Map<unknown, unknown>;
+  Set(value: any, message?: string): asserts value is Set<unknown>;
+  WeakMap(value: any, message?: string): asserts value is Map<unknown, unknown>;
+  WeakSet(value: any, message?: string): asserts value is Set<unknown>;
+  ArrayBuffer(value: any, message?: string): asserts value is ArrayBuffer;
+  SharedArrayBuffer(
+    value: any,
+    message?: string
+  ): asserts value is SharedArrayBuffer;
+  DataView(value: any, message?: string): asserts value is DataView;
+  TypedArray(value: any, message?: string): asserts value is TypedArray;
+  Int8Array(value: any, message?: string): asserts value is Int8Array;
+  Uint8Array(value: any, message?: string): asserts value is Uint8Array;
+  Uint8ClampedArray(
+    value: any,
+    message?: string
+  ): asserts value is Uint8ClampedArray;
+  Int16Array(value: any, message?: string): asserts value is Int16Array;
+  Uint16Array(value: any, message?: string): asserts value is Uint16Array;
+  Int32Array(value: any, message?: string): asserts value is Int32Array;
+  Uint32Array(value: any, message?: string): asserts value is Uint32Array;
+  Float32Array(value: any, message?: string): asserts value is Float32Array;
+  Float64Array(value: any, message?: string): asserts value is Float64Array;
+  Promise(value: any, message?: string): asserts value is Promise<unknown>;
+  Generator(
+    value: any,
+    message?: string
+  ): asserts value is Generator<unknown, any, unknown>;
+  GeneratorFunction(
+    value: any,
+    message?: string
+  ): asserts value is GeneratorFunction;
+  AsyncFunction(
+    value: any,
+    message?: string
+  ): asserts value is ((...args: any) => Promise<unknown>) & {
+    [key: string]: unknown;
+    [key: number]: unknown;
+    [key: symbol]: unknown;
+  };
+  AsyncGenerator(
+    value: any
+  ): asserts value is AsyncGenerator<unknown, any, unknown>;
+  AsyncGeneratorFunction(
+    value: any,
+    message?: string
+  ): asserts value is AsyncGeneratorFunction;
+
+  FILE(value: any, message?: string): asserts value is FILE;
+
+  JSX: {
+    /** Returns whether `value` is a JSX Element object as created via JSX syntax. */
+    Element(value: any, message?: string): asserts value is JSX.Element;
+    /** Returns whether `value` is a JSX fragment element as created via JSX syntax. */
+    Fragment(value: any, message?: string): asserts value is JSX.Fragment;
+  };
+};
+
 /**
  * The data source of a pipe operation; either an in-memory object, or a
  * file stream.
@@ -647,7 +1146,7 @@ declare type PipeSource =
  * - 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 =
+declare type PipeDestination =
   | ArrayBuffer
   | SharedArrayBuffer
   | DataView
@@ -690,6 +1189,25 @@ declare function pipe<Dest extends PipeDestination>(
     : never;
 };
 
+/**
+ * Launch the Yavascript REPL (read-eval-print-loop).
+ *
+ * @param context Variables to make available as globals within the repl.
+ * @param lang The langauge to use in the repl. Defaults to "javascript".
+ */
+declare function startRepl(
+  context?: { [key: string]: any },
+  lang?:
+    | "js"
+    | "javascript"
+    | "ts"
+    | "typescript"
+    | "jsx"
+    | "tsx"
+    | "coffee"
+    | "coffeescript"
+): void;
+
 /**
  * Returns the absolute path to the root folder of the git/hg repo.
  *
@@ -825,6 +1343,51 @@ declare namespace JSX {
   };
 }
 
+declare const YAML: {
+  /**
+   * Parse a YAML document (`input`) into a JSON-compatible value.
+   */
+  parse(
+    input: string,
+    reviver?: (this: any, key: string, value: any) => any
+  ): any;
+
+  /**
+   * Convert a JSON-compatible value into a YAML document.
+   */
+  stringify(
+    input: any,
+    replacer?:
+      | ((this: any, key: string, value: any) => any)
+      | (number | string)[]
+      | null,
+    indent?: number
+  ): string;
+};
+
+declare const CSV: {
+  /**
+   * Parse a CSV string into an Array of Arrays of strings.
+   *
+   * The outer array holds the rows, and the inner arrays hold the items in
+   * each row.
+   */
+  parse(input: string): Array<Array<string>>;
+
+  /**
+   * Convert an Array of Arrays of strings into a CSV string.
+   *
+   * The outer array holds the rows, and the inner arrays hold the items in
+   * each row.
+   */
+  stringify(input: Array<Array<string>>): string;
+};
+
+interface RegExpConstructor {
+  /** See https://github.com/tc39/proposal-regex-escaping */
+  escape(str: any): string;
+}
+
 // prettier-ignore
 /** Any integer in the range [0, 255]. */
 declare type byte =
@@ -915,7 +1478,7 @@ declare interface FILE {
   close(): void;
 
   /** Outputs the string with the UTF-8 encoding. */
-  puts(str: string): void;
+  puts(...strings: Array<string>): void;
 
   /**
    * Formatted printf.
@@ -1015,6 +1578,15 @@ declare module "std" {
     basename?: string
   ): { [key: string]: any };
 
+  /**
+   * Return the resolved path to a module.
+   *
+   * @param filename - The relative or absolute path to the file to import. Relative paths are resolved relative to the file calling `importModule`, or `basename` if present.
+   * @param basename - If present and `filename` is a relative path, `filename` will be resolved relative to this basename.
+   * @returns The resolved module path.
+   */
+  export function resolveModule(filename: string, basename?: string): string;
+
   /**
    * Load the file `filename` and return it as a string assuming UTF-8 encoding.
    *
@@ -1029,7 +1601,7 @@ declare module "std" {
    *
    * @param stackLevels - How many levels up the stack to search for a filename. Defaults to 0, which uses the current stack frame.
    */
-  export function getFileNameFromStack(stackLevels: number): string;
+  export function getFileNameFromStack(stackLevels?: number): string;
 
   /**
    * Return a boolean indicating whether the provided value is a FILE object.
@@ -1078,7 +1650,7 @@ declare module "std" {
   export function tmpfile(): FILE;
 
   /** Equivalent to `std.out.puts(str)`. */
-  export function puts(str: string): void;
+  export function puts(...strings: Array<string>): void;
 
   /** Equivalent to `std.out.printf(fmt, ...args)` */
   export function printf(fmt: string, ...args: Array<any>): void;
@@ -1533,16 +2105,19 @@ declare module "os" {
   /** Sleep for `delay_ms` milliseconds. */
   export function sleep(delay_ms: number): void;
 
-  export type Timer = number & { __is: "Timer" };
+  export type OSTimer = { [Symbol.toStringTag]: "OSTimer" };
 
   /** Call the function func after delay ms. Return a handle to the timer. */
-  export function setTimeout(func: () => void, delay: number): Timer;
+  export function setTimeout(
+    func: (...args: any) => any,
+    delay: number
+  ): OSTimer;
 
   /** Cancel a timer. */
-  export function clearTimeout(handle: Timer): void;
+  export function clearTimeout(handle: OSTimer): void;
 
-  /** Return a string representing the platform: "linux", "darwin", "win32" or "js". */
-  export var platform: "linux" | "darwin" | "win32" | "js";
+  /** Return a string representing the platform: "linux", "darwin", "win32", "freebsd", or "js" (emscripten). */
+  export var platform: "linux" | "darwin" | "win32" | "freebsd" | "js";
 
   /**
    * Things that can be put into Worker.postMessage.
@@ -1630,6 +2205,12 @@ declare module "os" {
 
   /** `access` Unix system call; checks if a file is readable, writable, executable, and/or exists (use {@link R_OK}, {@link W_OK}, {@link X_OK}, and/or {@link F_OK} for `accessMode`). Throws a descriptive error (with errno property) if the requested access is not available; otherwise, returns undefined. */
   export function access(path: string, accessMode: number): void;
+
+  /** gets the path to the executable which is executing this JS code. might be a relative path or symlink. */
+  export function execPath(): string;
+
+  /** changes the access permission bits of the file at `path` using the octal number `mode`. */
+  export function chmod(path: string, mode: number): void;
 }
 
 /**
@@ -1783,10 +2364,13 @@ declare class 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.
+   * be a function which receives (1) the filepath to a module, and (2) that
+   * file's content as a UTF-8 string, and the function should return a string
+   * containing JavaScript code that corresponds to that module. In most cases,
+   * these functions will compile the contents of the file from one format into JavaScript.
+   *
+   * The function does not have to use the second 'content' argument it
+   * receives (ie. when loading binary files).
    *
    * By adding to this object, you can make it possible to import non-js
    * filetypes; compile-to-JS languages like JSX, TypeScript, and CoffeeScript
@@ -1797,8 +2381,7 @@ declare class Module {
    * ```js
    * import * as std from "std";
    *
-   * Module.compilers[".txt"] = (filename) => {
-   *   const content = std.loadFile(filename);
+   * Module.compilers[".txt"] = (filename, content) => {
    *   return `export default ${JSON.stringify(content)}`;
    * }
    * ```
@@ -1815,8 +2398,14 @@ declare class Module {
    * {@link Module.searchExtensions}.
    */
   static compilers: {
-    [extensionWithDot: string]: (filename: string) => string;
+    [extensionWithDot: string]: (filename: string, content: string) => string;
   };
+
+  /**
+   * Create a virtual built-in module whose exports consist of the own
+   * enumerable properties of `obj`.
+   */
+  static define(name: string, obj: { [key: string]: any }): void;
 }
 
 /**
@@ -1851,4 +2440,71 @@ declare class Module {
  * 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;
+declare var require: ((source: string) => { [key: string]: any }) & {
+  /**
+   * Resolves the normalized path to a modules, relative to the calling file.
+   */
+  resolve: (source: string) => string;
+};
+
+declare var setTimeout: typeof import("os").setTimeout;
+declare var clearTimeout: typeof import("os").clearTimeout;
+
+declare type Interval = { [Symbol.toStringTag]: "Interval" };
+
+declare function setInterval(func: (...args: any) => any, ms: number): Interval;
+declare function clearInterval(interval: Interval): void;
+
+interface StringConstructor {
+  /**
+   * A no-op template literal tag.
+   *
+   * https://github.com/tc39/proposal-string-cooked
+   */
+  cooked(
+    strings: readonly string[] | ArrayLike<string>,
+    ...substitutions: any[]
+  ): string;
+
+  /**
+   * Remove leading minimum indentation from the string.
+   * The first line of the string must be empty.
+   *
+   * https://github.com/tc39/proposal-string-dedent
+   */
+  dedent: {
+    /**
+     * Remove leading minimum indentation from the string.
+     * The first line of the string must be empty.
+     *
+     * https://github.com/tc39/proposal-string-dedent
+     */
+    (input: string): string;
+
+    /**
+     * Remove leading minimum indentation from the template literal.
+     * The first line of the string must be empty.
+     *
+     * https://github.com/tc39/proposal-string-dedent
+     */
+    (
+      strings: readonly string[] | ArrayLike<string>,
+      ...substitutions: any[]
+    ): string;
+
+    /**
+     * Wrap another template tag function such that tagged literals
+     * become dedented before being passed to the wrapped function.
+     *
+     * https://www.npmjs.com/package/string-dedent#usage
+     */
+    <
+      Func extends (
+        strings: readonly string[] | ArrayLike<string>,
+        ...substitutions: any[]
+      ) => string
+    >(
+      input: Func
+    ): Func;
+  };
+}