yavascript 0.0.3 → 0.0.4

package/package.json

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

package/yavascript.d.ts

@@ -3,11 +3,9 @@
 // YavaScript APIs
 // ---------------
 
-/** The name of the current file (whether script or module). Alias for `os.realpath(std.getFileNameFromStack())`. */
-declare const __filename: string;
-
-/** The name of the directory the current file is inside of. */
-declare const __dirname: string;
+// -----------
+// --- env ---
+// -----------
 
 /**
  * An object representing the process's environment variables. You can read
@@ -17,6 +15,10 @@ declare const __dirname: string;
  */
 declare const env: { [key: string]: string | undefined };
 
+// ------------
+// --- exec ---
+// ------------
+
 type BaseExecOptions = {
   /** Sets the current working directory for the child process. */
   cwd?: string;
@@ -26,12 +28,12 @@ type BaseExecOptions = {
 };
 
 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>,
+    args: Array<string> | string,
     options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
@@ -51,7 +53,7 @@ interface Exec {
   ): void;
 
   (
-    args: Array<string>,
+    args: Array<string> | string,
     options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
@@ -71,7 +73,7 @@ interface Exec {
   ): { status: number };
 
   (
-    args: Array<string>,
+    args: Array<string> | string,
     options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
@@ -84,7 +86,7 @@ interface Exec {
   ): { status: number };
 
   (
-    args: Array<string>,
+    args: Array<string> | string,
     options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
@@ -104,7 +106,7 @@ interface Exec {
   ): { stdout: string; stderr: string };
 
   (
-    args: Array<string>,
+    args: Array<string> | string,
     options: BaseExecOptions & {
       /**
        * If true, stdout and stderr will be collected into strings and returned
@@ -117,7 +119,7 @@ interface Exec {
   ): { stdout: string; stderr: string };
 
   (
-    args: Array<string>,
+    args: Array<string> | string,
     options: BaseExecOptions & {
       /**
        * Whether an Error should be thrown when the process exits with a nonzero
@@ -129,82 +131,162 @@ 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 })` */
-declare function $(args: Array<string>): {
+declare function $(args: Array<string> | string): {
   stdout: string;
   stderr: string;
 };
 
-/** Read the contents of a file from disk, as a string. */
-declare function readFile(path: string): string;
-
-/** Write the contents of a string or ArrayBuffer to a file. */
-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;
-
-/** Delete the file or directory at the specified path. If the directory isn't empty, its contents will be deleted, too. */
-declare function remove(path: string): void;
-
-/** Returns true if a file or directory exists at the specified path. */
-declare function exists(path: string): boolean;
+// -------------
+// --- paths ---
+// -------------
 
-/** Change the process's current working directory to the specified path. */
+/**
+ * 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. */
+/**
+ * Return the process's current working directory.
+ *
+ * Provides the same functionality as the shell builtin of the same name.
+ */
 declare function pwd(): string;
 
-/** Removes the final component from a path 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;
 
 /**
- * The separator character the host operative 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.
+ * Return the last component of a path string.
+ *
+ * Provides the same functionality as the unix binary of the same name.
  */
-declare const OS_PATH_SEPARATOR: "/" | "\\";
+declare function basename(path: string): string;
 
 /**
- * Create a path string from one or more path or path component strings.
- * 
- * Trailing slashes and duplicate path separators will be removed. Any slashes
- * or backslashes that do not match the requested path separator character
- * (which defaults to {@link OS_PATH_SEPARATOR}) will be converted to the
- * requested path separator. If multiple strings are passed, they will be
- * joined together using the requested path separator.
- * 
- * This function does not resolve `..` or `.`. Use {@link realpath} for that.
- * 
- * To request a path separator other than {@link OS_PATH_SEPARATOR}, pass an
- * object like `{ separator: "/" }` as the final argument to `makePath`.
+ * Returns the file extension of the file at a given path.
+ *
+ * If the file has no extension (eg `Makefile`, etc), then `''` will be returned.
  *
- * @param parts strings containing path components that should be present in
- * the returned path string.
+ * Pass `{ full: true }` to get compound extensions, eg `.d.ts` or `.test.js` instead of just `.ts`/`.js`.
  */
-declare function makePath(
-  ...parts: Array<string | { separator: string }>
+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 
+ *
+ * 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
+declare function isGitignored(path: string): boolean;
+
+// ------------------
+// --- filesystem ---
+// ------------------
 
 /**
  * Return the contents of a directory, as absolute paths. `.` and `..` are
@@ -218,33 +300,176 @@ declare function ls(
   options?: { relativePaths?: boolean }
 ): Array<string>;
 
-/** Get the absolute path given a relative path. Symlinks are also resolved. */
-declare function realpath(path: string): string;
-
-/** Read a symlink. */
+/**
+ * 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;
 
 /**
- * Search the filesystem for files matching the specified glob patterns. Uses [minimatch](https://www.npmjs.com/package/minimatch) with its default options.
+ * 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.
+ *
+ * Strings are written using the UTF-8 encoding.
+ */
+declare function writeFile(path: string, data: string | ArrayBuffer): 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;
+
+  /**
+   * 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.
+ *
+ * Provides the same functionality as the command `test -e`.
+ */
+declare function exists(path: string): boolean;
+
+/**
+ * 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;
+
+/**
+ * Options for {@link copy}.
+ */
+export 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;
+};
+
+/**
+ * Copy a file or folder from one location to another.
+ * Folders are copied recursively.
+ *
+ * Provides the same functionality as the command `cp -R`.
+ */
+export function copy(from: string, to: string, options?: CopyOptions): void;
+
+// ------------
+// --- glob ---
+// ------------
+
+/**
+ * Options for {@link glob}.
+ */
+export 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.
  *
- * `followSymlinks` defaults to false.
+ * 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
@@ -333,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" {
@@ -385,9 +619,9 @@ declare module "std" {
 
   /**
    * 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;
@@ -638,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. */
@@ -1029,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;
+