yavascript 0.0.2 → 0.0.5

package/README.md

@@ -0,0 +1,43 @@
+# 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:
+
+- Running programs
+- Accessing environment variables
+- Reading and writing file contents
+- Checking if files/folders exist
+- Removing files/folders
+- Reading and changing the current working directory
+- Using globs to get large lists of files
+- Printing stylized text to the terminal
+
+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:
+
+- Arrays (lists) and Objects (key/value dictionaries)
+- Working with path strings
+- Working with JSON
+- 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)
+
+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.
+
+YavaScript is powered by a fork of the QuickJS JavaScript Engine, originally
+written by Fabrice Bellard. QuickJS is a small, fast JavaScript engine
+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.

package/lib/binary-path.js

@@ -2,9 +2,25 @@ var path = require("path");
 
 var binaryPath;
 if (process.platform === "win32") {
-  binaryPath = path.resolve(__dirname, "..", "bin", "win32", "yavascript.exe");
+  binaryPath = path.resolve(
+    __dirname,
+    "..",
+    "bin",
+    "windows",
+    "yavascript.exe"
+  );
 } else if (process.platform === "darwin") {
-  binaryPath = path.resolve(__dirname, "..", "bin", "darwin", "yavascript");
+  if (process.arch.startsWith("arm")) {
+    binaryPath = path.resolve(
+      __dirname,
+      "..",
+      "bin",
+      "darwin-arm",
+      "yavascript"
+    );
+  } else {
+    binaryPath = path.resolve(__dirname, "..", "bin", "darwin", "yavascript");
+  }
 } else if (process.platform === "linux") {
   binaryPath = path.resolve(__dirname, "..", "bin", "linux", "yavascript");
 } else {

package/package.json

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

package/yavascript.d.ts

@@ -3,16 +3,38 @@
 // 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
+ * variables, and/or delete properties from it to unset environment variables.
+ * Any value you write will be coerced into a string.
+ */
 declare const env: { [key: string]: string | undefined };
 
+// ------------
+// --- exec ---
+// ------------
+
+type BaseExecOptions = {
+  /** Sets the current working directory for the child process. */
+  cwd?: string;
+
+  /** Sets environment variables within the process. */
+  env?: { [key: string | number]: string | number | boolean };
+};
+
 interface Exec {
-  (args: Array<string>): void;
+  (args: Array<string> | string): void;
 
-  (args: Array<string>, options: Record<string, never>): void;
+  (args: Array<string> | string, options: Record<string, never>): void;
 
   (
-    args: Array<string>,
-    options: {
+    args: Array<string> | string,
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -31,8 +53,8 @@ interface Exec {
   ): void;
 
   (
-    args: Array<string>,
-    options: {
+    args: Array<string> | string,
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -51,8 +73,8 @@ interface Exec {
   ): { status: number };
 
   (
-    args: Array<string>,
-    options: {
+    args: Array<string> | string,
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -64,8 +86,8 @@ interface Exec {
   ): { status: number };
 
   (
-    args: Array<string>,
-    options: {
+    args: Array<string> | string,
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -84,8 +106,8 @@ interface Exec {
   ): { stdout: string; stderr: string };
 
   (
-    args: Array<string>,
-    options: {
+    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.
@@ -97,8 +119,8 @@ interface Exec {
   ): { stdout: string; stderr: string };
 
   (
-    args: Array<string>,
-    options: {
+    args: Array<string> | string,
+    options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
        * status code.
@@ -109,60 +131,345 @@ interface Exec {
       captureOutput: true;
     }
   ): { stdout: string; stderr: string; status: number };
+
+  /** Log all executed commands to stderr. `isOn` is optional and defaults to `true`. Pass `false` to disable logging. */
+  enableLogging(isOn?: boolean): void;
 }
 
 /** Run a child process using the provided arguments. The first value in the arguments array is the program to run. */
 declare const exec: Exec;
 
-/** Alias for `exec(args, { captureOutput: true, failOnNonZeroStatus: false })` */
-declare function $(args: Array<string>): {
+/** Alias for `exec(args, { captureOutput: true })` */
+declare function $(args: Array<string> | string): {
   stdout: string;
   stderr: string;
-  status: number;
 };
 
-/** Read the contents of a file from disk, as a string. */
+// -------------
+// --- paths ---
+// -------------
+
+/**
+ * Change the process's current working directory to the specified path.
+ *
+ * Provides the same functionality as the shell builtin of the same name.
+ */
+declare function cd(path: string): void;
+
+/**
+ * Return the process's current working directory.
+ *
+ * Provides the same functionality as the shell builtin of the same name.
+ */
+declare function pwd(): string;
+
+/**
+ * Get the absolute path given a relative path. Symlinks are also resolved.
+ *
+ * The path's target file/directory must exist.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function realpath(path: string): string;
+
+/**
+ * Removes the final component from a path string.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function dirname(path: string): string;
+
+/**
+ * Return the last component of a path string.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function basename(path: string): string;
+
+/**
+ * Returns the file extension of the file at a given path.
+ *
+ * If the file has no extension (eg `Makefile`, etc), then `''` will be returned.
+ *
+ * Pass `{ full: true }` to get compound extensions, eg `.d.ts` or `.test.js` instead of just `.ts`/`.js`.
+ */
+declare function extname(
+  pathOrFilename: string,
+  options?: { full?: boolean }
+): string;
+
+/**
+ * A namespace object providing several path-string-related APIs.
+ */
+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;
+
+  /**
+   * 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;
+
+  /**
+   * 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;
+
+  /**
+   * Returns whether the path starts with either a leading slash or a windows
+   * drive letter.
+   */
+  isAbsolute(path: string): boolean;
+};
+
+/**
+ * The absolute path to the current file (whether script or module).
+ *
+ * Behaves the same as in Node.js, except that it's present within ES modules.
+ */
+declare const __filename: string;
+
+/**
+ * The absolute path to the directory the current file is inside of.
+ *
+ * Behaves the same as in Node.js, except that it's present within ES modules.
+ */
+declare const __dirname: string;
+
+// ------------
+// --- repo ---
+// ------------
+
+/**
+ * Returns the absolute path to the root folder of the git/hg repo.
+ *
+ * This is done by running `git rev-parse --show-toplevel` and `hg root`.
+ *
+ * If `relativeTo` is provided, the git and hg commands will be executed in
+ * that folder instead of in `pwd()`.
+ */
+declare function repoRoot(relativeTo?: string): string;
+
+/**
+ * Returns whether the provided path is ignored by git.
+ */
+declare function isGitignored(path: string): boolean;
+
+// ------------------
+// --- filesystem ---
+// ------------------
+
+/**
+ * Return the contents of a directory, as absolute paths. `.` and `..` are
+ * omitted.
+ *
+ * Use the `relativePaths` option to get relative paths instead (relative to
+ * the parent directory).
+ */
+declare function ls(
+  dir?: string,
+  options?: { relativePaths?: boolean }
+): Array<string>;
+
+/**
+ * Read a symlink.
+ *
+ * Returns the target of the symlink, which may be absolute or relative.
+ *
+ * Provides the same functionality as the unix binary of the same name.
+ */
+declare function readlink(path: string): string;
+
+/**
+ * Read the contents of a file from disk, as a UTF-8 string.
+ */
 declare function readFile(path: string): string;
 
-/** Write the contents of a string or ArrayBuffer to a file. */
+/**
+ * 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;
 
-/** Returns true if the path points to a directory, or if the path points to a symlink which points to a directory. */
-declare function isDir(path: string): 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.
+   */
+  (path: string): boolean;
 
-/** Delete the file or directory at the specified path. If the directory isn't empty, its contents will be deleted, too. */
+  /**
+   * Maximum number of symlinks to follow before erroring. Defaults to 100.
+   */
+  symlinkLimit: 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;
+
+/**
+ * Returns true if the path points to a symlink.
+ */
+declare function isLink(path: string): boolean;
+
+/**
+ * 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;
 
-/** Returns true if a file or directory exists at the specified path. */
+/**
+ * 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;
 
-/** Change the process's current working directory to the specified path. */
-declare function cd(path: string): 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;
 
-/** Return the process's current working directory. */
-declare function pwd(): 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";
+
+  /**
+   * 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;
+};
 
 /**
- * Search the filesystem for files matching the specified glob patterns. Uses [minimatch](https://www.npmjs.com/package/minimatch) with its default options.
+ * Copy a file or folder from one location to another.
+ * Folders are copied recursively.
  *
- * `followSymlinks` defaults to false.
+ * Provides the same functionality as the command `cp -R`.
+ */
+declare function copy(from: string, to: string, options?: CopyOptions): void;
+
+// ------------
+// --- glob ---
+// ------------
+
+/**
+ * Options for {@link glob}.
+ */
+declare type GlobOptions = {
+  /**
+   * Whether to treat symlinks to directories as if they themselves were
+   * directories, traversing into them.
+   *
+   * Defaults to false.
+   */
+  followSymlinks?: boolean;
+
+  /**
+   * If provided, this function will be called multiple times as `glob`
+   * traverses the filesystem, to help you understand what's going on and/or
+   * troubleshoot things. In most cases, it makes sense to use a logging
+   * function here, like so:
+   *
+   * ```js
+   * glob(pwd(), ["./*.js"], { trace: console.log });
+   * ```
+   */
+  trace?: (...args: Array<any>) => void;
+};
+
+/**
+ * Search the filesystem for files matching the specified glob patterns.
+ *
+ * Uses [minimatch](https://www.npmjs.com/package/minimatch) with its default
+ * options.
  */
 declare function glob(
   dir: string,
   patterns: Array<string>,
-  options?: { followSymlinks?: boolean }
+  options?: GlobOptions
 ): Array<string>;
 
-/** Print a value or values to stdout. */
+// ---------------
+// --- console ---
+// ---------------
+
+/**
+ * Print one or more values to stdout.
+ */
 declare const echo: typeof console.log;
 
-/** Convert a value to a string, using the same logic as `echo` and `console.log`. */
-declare function inspect(value: any): string;
+// ---------------
+// --- strings ---
+// ---------------
 
-/** Remove ANSI control characters from a string. */
+/**
+ * Remove ANSI control characters from a string.
+ */
 declare function stripAnsi(input: string): string;
 
-/** Wrap a string in double quotes, and escape any double-quotes inside with `\"`. */
+/**
+ * Wrap a string in double quotes, and escape any double-quotes inside using `\"`.
+ */
 declare function quote(input: string): string;
 
 // Colors
@@ -251,6 +558,15 @@ declare var print: (...args: Array<any>) => void;
 declare var console: {
   /** Same as {@link print}(). */
   log: typeof print;
+
+  /** Same as {@link print}(). */
+  warn: typeof print;
+
+  /** Same as {@link print}(). */
+  error: typeof print;
+
+  /** Same as {@link print}(). */
+  info: typeof print;
 };
 
 declare module "std" {
@@ -301,6 +617,15 @@ declare module "std" {
    */
   export function loadFile(filename: string): string;
 
+  /**
+   * Read the script of module filename from an active stack frame, then return it as a string.
+   *
+   * If there isn't a valid filename for the specified stack frame, an error will be thrown.
+   *
+   * @param stackLevels - How many levels up the stack to search for a filename. Defaults to 0, which uses the current stack frame.
+   */
+  export function getFileNameFromStack(stackLevels: number): string;
+
   /**
    * Open a file (wrapper to the libc `fopen()`).
    * Return the FILE object.
@@ -547,7 +872,7 @@ declare module "std" {
     /** 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 file to the ArrayBuffer `buffer` at byte position `position` (wrapper to the libc `fwrite`). Returns the number of bytes written. */
+    /** 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. */
@@ -938,3 +1263,108 @@ declare module "os" {
   export function access(path: string, accessMode: number): void;
 }
 
+/**
+ * Options for {@link inspect}.
+ */
+declare interface InspectOptions {
+  /** Whether to display non-enumerable properties. Defaults to false. */
+  all?: boolean;
+
+  /** Whether to invoke getter functions. Defaults to false. */
+  followGetters?: boolean;
+
+  /** Whether to display the indexes of iterable entries. Defaults to false. */
+  indexes?: boolean;
+
+  /** Hide object details after 𝑁 recursions. Defaults to Infinity. */
+  maxDepth?: number;
+
+  /** If true, don't identify well-known symbols as `@@…`. Defaults to false. */
+  noAmp?: boolean;
+
+  /** If true, don't format byte-arrays as hexadecimal. Defaults to false. */
+  noHex?: boolean;
+
+  /** If true, don't display function source code. Defaults to false. */
+  noSource?: boolean;
+
+  /** Whether to show `__proto__` properties if possible. Defaults to false. */
+  proto?: boolean;
+
+  /** Whether to sort properties alphabetically. When false, properties are sorted by creation order. Defaults to false. */
+  sort?: boolean;
+
+  /** Options that control whether and how ANSI terminal escape sequences for colours should be added to the output. Defaults to false, meaning no colours. */
+  colours?: boolean | 256 | 8 | InspectColours;
+
+  /** Prefix string to use for indentation. Defaults to '\t'. */
+  indent?: string;
+}
+
+declare interface InspectColours {
+  off?: string | number;
+  red?: string | number;
+  grey?: string | number;
+  green?: string | number;
+  darkGreen?: string | number;
+  punct?: string | number;
+  keys?: string | number;
+  keyEscape?: string | number;
+  typeColour?: string | number;
+  primitive?: string | number;
+  escape?: string | number;
+  date?: string | number;
+  hexBorder?: string | number;
+  hexValue?: string | number;
+  hexOffset?: string | number;
+  reference?: string | number;
+  srcBorder?: string | number;
+  srcRowNum?: string | number;
+  srcRowText?: string | number;
+  nul?: string | number;
+  nulProt?: string | number;
+  undef?: string | number;
+  noExts?: string | number;
+  frozen?: string | number;
+  sealed?: string | number;
+  regex?: string | number;
+  string?: string | number;
+  symbol?: string | number;
+  symbolFade?: string | number;
+  braces?: string | number;
+  quotes?: string | number;
+  empty?: string | number;
+  dot?: string | number;
+}
+
+declare interface InspectFunction {
+  /**
+   * Generate a human-readable representation of a value.
+   *
+   * @param value - Value to inspect
+   * @param options - Additional settings for refining output
+   * @returns A string representation of `value`.
+   */
+  (value: any, options?: InspectOptions): string;
+
+  /**
+   * Generate a human-readable representation of a value.
+   *
+   * @param value - Value to inspect
+   * @param key - The value's corresponding member name
+   * @param options - Additional settings for refining output
+   * @returns A string representation of `value`.
+   */
+  (value: any, key?: string | symbol, options?: InspectOptions): string;
+}
+
+/**
+ * Generate a human-readable representation of a value.
+ *
+ * @param value - Value to inspect
+ * @param key - The value's corresponding member name
+ * @param options - Additional settings for refining output
+ * @returns A string representation of `value`.
+ */
+declare var inspect: InspectFunction;
+