yavascript 0.0.9 → 0.0.10

package/package.json

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

package/yavascript.d.ts

@@ -128,19 +128,10 @@ declare const env: { [key: string]: string | undefined };
  * 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 `Path`. `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.
+ * @returns An object with three properties: `flags`, `args`, and `metadata`. `flags` is an object whose keys are camelCase flag names and whose values are strings, booleans, numbers, or `Path`s corresponding to the input command-line args. `args` is an Array of positional arguments, as found on the command-line. `metadata` contains information about what name and type the flags got mapped to.
  */
 declare function parseScriptArgs(
   hints?: {
@@ -150,6 +141,17 @@ declare function parseScriptArgs(
 ): {
   flags: { [key: string]: any };
   args: Array<string>;
+  metadata: {
+    keys: {
+      [key: string]: string | undefined;
+    };
+    hints: {
+      [key: string]: string | undefined;
+    };
+    guesses: {
+      [key: string]: string | undefined;
+    };
+  };
 };
 
 /**
@@ -187,6 +189,11 @@ declare function writeFile(
   data: string | ArrayBuffer
 ): void;
 
+/**
+ * Function which returns true if the path points to a regular file.
+ */
+declare function isFile(path: string | Path): 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
@@ -199,6 +206,28 @@ declare function isDir(path: string | Path): boolean;
  */
 declare function isLink(path: string | Path): boolean;
 
+/**
+ * Returns true if the resource at the provided path can be executed by the
+ * current user.
+ *
+ * If nothing exists at that path, an error will be thrown.
+ */
+declare function isExecutable(path: string | Path): boolean;
+
+/**
+ * Returns true if the resource at the provided path can be read by the current
+ * user.
+ *
+ * If nothing exists at that path, an error will be thrown.
+ */
+declare function isReadable(path: string | Path): boolean;
+
+/**
+ * Returns true if a resource at the provided path could be written to by the
+ * current user.
+ */
+declare function isWritable(path: string | Path): boolean;
+
 /**
  * Delete the file or directory at the specified path.
  *
@@ -562,6 +591,40 @@ declare function readlink(path: string | Path): string;
  */
 declare function realpath(path: string | Path): string;
 
+/**
+ * Blocks the current thread for at least the specified number of milliseconds,
+ * or maybe a tiny bit longer.
+ *
+ * alias for `sleep.sync`.
+ */
+declare var sleep: {
+  /**
+   * Blocks the current thread for at least the specified number of milliseconds,
+   * or maybe a tiny bit longer.
+   *
+   * alias for `sleep.sync`.
+   *
+   * @param milliseconds - The number of milliseconds to block for.
+   */
+  (milliseconds: number): void;
+
+  /**
+   * Blocks the current thread for at least the specified number of milliseconds,
+   * or maybe a tiny bit longer.
+   *
+   * @param milliseconds - The number of milliseconds to block for.
+   */
+  sync(milliseconds: number): void;
+
+  /**
+   * Returns a Promise which resolves in at least the specified number of
+   * milliseconds, maybe a little longer.
+   *
+   * @param milliseconds - The number of milliseconds to wait before the returned Promise should be resolved.
+   */
+  async(milliseconds: number): Promise<void>;
+};
+
 /**
  * If the file at `path` exists, update its creation/modification timestamps.
  *
@@ -598,33 +661,19 @@ declare type BaseExecOptions = {
   failOnNonZeroStatus?: boolean;
 
   /**
-   * If true, stdout and stderr will be collected into strings and returned
-   * instead of being printed to the screen.
+   * If true, stdout and stderr will be collected into strings or array buffers
+   * and returned instead of being printed to the screen.
    *
-   * Defaults to false.
+   * Defaults to false. true is an alias for "utf8".
    */
-  captureOutput?: boolean;
+  captureOutput?: boolean | "utf8" | "arraybuffer";
 };
 
 declare interface Exec {
-  (args: Array<string> | string, options?: BaseExecOptions): 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;
@@ -632,19 +681,7 @@ declare interface Exec {
   (
     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;
     }
   ):
@@ -654,12 +691,70 @@ declare interface Exec {
   (
     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;
+      captureOutput: true;
+    }
+  ): { stdout: string; stderr: string };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      failOnNonZeroStatus: true;
+      captureOutput: "utf8";
+    }
+  ): { stdout: string; stderr: string };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      failOnNonZeroStatus: true;
+      captureOutput: "arraybuffer";
+    }
+  ): { stdout: ArrayBuffer; stderr: ArrayBuffer };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      failOnNonZeroStatus: false;
+      captureOutput: true;
+    }
+  ):
+    | { stdout: string; stderr: string; status: number; signal: undefined }
+    | { stdout: string; stderr: string; status: undefined; signal: number };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      failOnNonZeroStatus: false;
+      captureOutput: "utf-8";
+    }
+  ):
+    | { stdout: string; stderr: string; status: number; signal: undefined }
+    | { stdout: string; stderr: string; status: undefined; signal: number };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
+      failOnNonZeroStatus: false;
+      captureOutput: "arraybuffer";
+    }
+  ):
+    | {
+        stdout: ArrayBuffer;
+        stderr: ArrayBuffer;
+        status: number;
+        signal: undefined;
+      }
+    | {
+        stdout: ArrayBuffer;
+        stderr: ArrayBuffer;
+        status: undefined;
+        signal: number;
+      };
+
+  (
+    args: Array<string> | string,
+    options: BaseExecOptions & {
       failOnNonZeroStatus: true;
     }
   ): void;
@@ -667,12 +762,6 @@ declare interface Exec {
   (
     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;
     }
   ):
@@ -682,19 +771,6 @@ declare interface Exec {
   (
     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 };
@@ -702,44 +778,25 @@ declare interface Exec {
   (
     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;
+      captureOutput: "utf8";
     }
   ): { stdout: string; stderr: string };
 
   (
     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: false;
+      captureOutput: "arraybuffer";
     }
-  ): void;
+  ): { stdout: ArrayBuffer; stderr: ArrayBuffer };
 
   (
     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;
+      captureOutput: false;
     }
-  ):
-    | { stdout: string; stderr: string; status: number; signal: undefined }
-    | { stdout: string; stderr: string; status: undefined; signal: number };
+  ): void;
+
+  (args: Array<string> | string, options?: BaseExecOptions): void;
 }
 
 /** Runs a child process using the provided arguments. The first value in the arguments array is the program to run. */
@@ -1026,7 +1083,11 @@ declare const grepString: {
     str: string,
     pattern: string | RegExp,
     options: { inverse: true; details: true }
-  ): Array<string>;
+  ): Array<{
+    lineNumber: number;
+    lineContent: string;
+    matches: RegExpMatchArray;
+  }>;
 };
 
 /** Read the content at `path`, split it on newline, and then return lines matching `pattern`. */
@@ -1092,7 +1153,11 @@ declare const grepFile: {
     path: string | Path,
     pattern: string | RegExp,
     options: { inverse: true; details: true }
-  ): Array<string>;
+  ): Array<{
+    lineNumber: number;
+    lineContent: string;
+    matches: RegExpMatchArray;
+  }>;
 };
 
 interface String {
@@ -1139,7 +1204,11 @@ interface String {
     (
       pattern: string | RegExp,
       options: { inverse: true; details: true }
-    ): Array<string>;
+    ): Array<{
+      lineNumber: number;
+      lineContent: string;
+      matches: RegExpMatchArray;
+    }>;
   };
 }
 
@@ -2675,21 +2744,20 @@ declare const startRepl: {
  */
 declare class GitRepo {
   /**
-   * Given a path to a file or folder on disk, finds the parent git repo
-   * containing that path, and returns the absolute path to the repo root (the
-   * folder that contains the '.git' folder).
-   *
-   * This is done by running `git rev-parse --show-toplevel`.
+   * Given a path to a file or folder on disk, searches upwards through the
+   * directory ancestry to find a `.git` folder, then returns the Path that
+   * contains that `.git` folder. If no `.git` folder is found, an error will be
+   * thrown.
    */
   static findRoot(fromPath: string | Path): Path;
 
   /**
-   * Creates a new `Git` object for the given repo on disk.
+   * Creates a new `GitRepo` object for the given repo on disk.
    */
   constructor(repoDir: string | Path);
 
   /**
-   * The root folder of the git repo that this `Git` object represents (the
+   * The root folder of the git repo that this `GitRepo` object represents (the
    * folder that contains the '.git' folder).
    */
   repoDir: Path;
@@ -2721,7 +2789,7 @@ declare class GitRepo {
   /**
    * Returns whether the provided path is ignored by git.
    *
-   * If `path` is an absolute path, it must be a child directory of this Git
+   * If `path` is an absolute path, it must be a child directory of this GitRepo
    * object's `repoDir`, or else an error will be thrown.
    */
   isIgnored(path: string | Path): boolean;
@@ -4100,6 +4168,38 @@ declare module "quickjs:std" {
   /** Return an object containing the environment variables as key-value pairs. */
   export function getenviron(): { [key: string]: string | undefined };
 
+  /**
+   * Return the real user ID of the calling process.
+   *
+   * This function throws an error on windows, because windows doesn't support
+   * the same uid/gid paradigm as Unix-like operating systems.
+   */
+  export function getuid(): number;
+
+  /**
+   * Return the effective user ID of the calling process.
+   *
+   * This function throws an error on windows, because windows doesn't support
+   * the same uid/gid paradigm as Unix-like operating systems.
+   */
+  export function geteuid(): number;
+
+  /**
+   * Return the real group ID of the calling process.
+   *
+   * This function throws an error on windows, because windows doesn't support
+   * the same uid/gid paradigm as Unix-like operating systems.
+   */
+  export function getgid(): number;
+
+  /**
+   * Return the effective group ID of the calling process.
+   *
+   * This function throws an error on windows, because windows doesn't support
+   * the same uid/gid paradigm as Unix-like operating systems.
+   */
+  export function getegid(): number;
+
   interface UrlGet {
     /**
      * Download `url` using the `curl` command line utility. Returns string
@@ -4217,6 +4317,20 @@ declare module "quickjs:std" {
    * - octal (0o prefix) and hexadecimal (0x prefix) numbers
    */
   export function parseExtJSON(str: string): any;
+
+  /**
+   * A wrapper around the standard C [strftime](https://en.cppreference.com/w/c/chrono/strftime).
+   * Formats a time/date into a format as specified by the user.
+   *
+   * @param maxBytes - The number of bytes to allocate for the string that will be returned
+   * @param format - Format string, using `%`-prefixed sequences as found in [this table](https://en.cppreference.com/w/c/chrono/strftime#Format_string).
+   * @param time - The Date object (or unix timestamp, in ms) to render.
+   */
+  export function strftime(
+    maxBytes: number,
+    format: string,
+    time: Date | number
+  ): string;
 }
 
 declare module "quickjs:os" {
@@ -5053,6 +5167,10 @@ interface RequireFunction {
 
 declare var require: RequireFunction;
 
+interface ImportMeta {
+  require: RequireFunction;
+}
+
 declare var setTimeout: typeof import("quickjs:os").setTimeout;
 declare var clearTimeout: typeof import("quickjs:os").clearTimeout;
 
@@ -5319,3 +5437,6 @@ declare module "quickjs:context" {
     eval(code: string): any;
   }
 }
+
+declare const std: typeof import("quickjs:std");
+declare const os: typeof import("quickjs:os");