Continued refinement of the “fs” module

Author: ldaniels528

src/main/scala/io/scalajs/nodejs/buffer/Buffer.scala

@@ -23,32 +23,25 @@ import scala.scalajs.js.|
   * @author lawrence.daniels@gmail.com
   */
 @js.native
-@JSImport("buffer", JSImport.Namespace)
-class Buffer extends js.Object {
+@JSImport("buffer", "Buffer")
+class Buffer() extends js.Object {
 
   /////////////////////////////////////////////////////////////////////////////////
   //      Constructors
   /////////////////////////////////////////////////////////////////////////////////
 
   /**
-    * new Buffer(size)
+    * @example new Buffer(size)
     */
   @inline
   def this(size: Int) = this()
 
   /**
-    * new Buffer(str, [encoding])
+    * @example new Buffer(str, [encoding])
     */
   @inline
   @deprecated("Use Buffer.from(str[, encoding]) instead.", since = "6.0.0")
-  def this(str: String, encoding: String) = this()
-
-  /**
-    * new Buffer(str, [encoding])
-    */
-  @inline
-  @deprecated("Use Buffer.from(str[, encoding]) instead.", since = "6.0.0")
-  def this(str: String) = this()
+  def this(str: String, encoding: String = js.native) = this()
 
   /**
     * @example new Buffer(array)
@@ -204,6 +197,15 @@ class Buffer extends js.Object {
     */
   def keys(): Iterator[Int] = js.native
 
+  /**
+    * The largest size allowed for a single Buffer instance.
+    * On 32-bit architectures, this value is (2^30)-1 (~1GB). On 64-bit architectures, this value is (2^31)-1 (~2GB).
+    * Note that this is a property on the buffer module returned by require('buffer'), not on the Buffer global or
+    * a Buffer instance.
+    * @return the largest size allowed
+    */
+  def kMaxLength: Int = js.native
+
   /**
     * Identical to buf.indexOf(), except buf is searched from back to front instead of front to back.
     * @param value      What to search for
@@ -523,6 +525,17 @@ class Buffer extends js.Object {
     */
   def toString(encoding: String = js.native, start: Int = js.native, end: Int = js.native): String = js.native
 
+  /**
+    * Re-encodes the given Buffer instance from one character encoding to another. Returns a new Buffer instance.
+    * Throws if the fromEnc or toEnc specify invalid character encodings or if conversion from fromEnc to toEnc
+    * is not permitted.
+    * @param source  A Buffer instance
+    * @param fromEnc The current encoding
+    * @param toEnc   To target encoding
+    * @return a new [[Buffer]]
+    */
+  def transcode(source: Buffer, fromEnc: String, toEnc: String): Buffer = js.native
+
   /**
     * Creates and returns an iterator for buf values (bytes). This function is called automatically when a [[Buffer]]
     * is used in a for..of statement.

src/main/scala/io/scalajs/nodejs/fs/Fs.scala

@@ -49,7 +49,7 @@ trait Fs extends IEventEmitter {
   val W_OK: FileMode = js.native
 
   /**
-    * File can be executed by the calling process. This has no effect on Windows (will behave like fs.[[F_OK]]).
+    * File can be executed by the calling process. This has no effect on Windows (will behave like [[F_OK]]).
     */
   val X_OK: FileMode = js.native
 
@@ -195,9 +195,9 @@ trait Fs extends IEventEmitter {
     * <ul>
     * <li>fs.F_OK - File is visible to the calling process. This is useful for determining if a file exists,
     * but says nothing about rwx permissions. Default if no mode is specified.</li>
-    * <li>fs.[[R_OK]] - File can be read by the calling process.</li>
-    * <li>fs.[[W_OK]] - File can be written by the calling process.</li>
-    * <li>fs.[[X_OK]] - File can be executed by the calling process. This has no effect on Windows (will behave like fs.[[F_OK]]).</li>
+    * <li>[[R_OK]] - File can be read by the calling process.</li>
+    * <li>[[W_OK]] - File can be written by the calling process.</li>
+    * <li>[[X_OK]] - File can be executed by the calling process. This has no effect on Windows (will behave like [[F_OK]]).</li>
     * </ul>
     * @param path     the path (Buffer | String)
     * @param mode     the optional mode
@@ -214,9 +214,9 @@ trait Fs extends IEventEmitter {
     * <ul>
     * <li>fs.F_OK - File is visible to the calling process. This is useful for determining if a file exists,
     * but says nothing about rwx permissions. Default if no mode is specified.</li>
-    * <li>fs.[[R_OK]] - File can be read by the calling process.</li>
-    * <li>fs.[[W_OK]] - File can be written by the calling process.</li>
-    * <li>fs.[[X_OK]] - File can be executed by the calling process. This has no effect on Windows (will behave like fs.[[F_OK]]).</li>
+    * <li>[[R_OK]] - File can be read by the calling process.</li>
+    * <li>[[W_OK]] - File can be written by the calling process.</li>
+    * <li>[[X_OK]] - File can be executed by the calling process. This has no effect on Windows (will behave like [[F_OK]]).</li>
     * </ul>
     * @param path     the path (Buffer | String)
     * @param callback is a callback function that is invoked with a possible error argument. If any of the accessibility
@@ -400,13 +400,14 @@ trait Fs extends IEventEmitter {
     * @param fd       the file descriptor
     * @param callback the completion callback.
     */
-  def fstat(fd: FileDescriptor, callback: FsCallback0): Unit = js.native
+  def fstat(fd: FileDescriptor, callback: FsCallback1[Stats]): Unit = js.native
 
   /**
-    * Synchronous fstat(2). Returns an instance of fs.Stats.
+    * Synchronous fstat(2).
     * @param fd the file descriptor
+    * @return an instance of [[fs.Stats]].
     */
-  def fstatSync(fd: FileDescriptor): Unit = js.native
+  def fstatSync(fd: FileDescriptor): Stats = js.native
 
   /**
     * Asynchronous fsync(2). No arguments other than a possible exception are given to the completion callback.
@@ -424,21 +425,21 @@ trait Fs extends IEventEmitter {
 
   /**
     * Asynchronous ftruncate(2). No arguments other than a possible exception are given to the completion callback.
-    * If the file referred to by the file descriptor was larger than len bytes, only the first len bytes will be
+    * If the file referred to by the file descriptor was larger than length bytes, only the first length bytes will be
     * retained in the file.
     * @param fd       the file descriptor
-    * @param len      the desired length
+    * @param length   the desired length
     * @param callback the completion callback.
     */
-  def ftruncate(fd: FileDescriptor, len: Double, callback: FsCallback0): Unit = js.native
+  def ftruncate(fd: FileDescriptor, length: Double, callback: FsCallback0): Unit = js.native
 
   /**
     * Synchronous ftruncate(2).
-    * @param fd  the file descriptor
-    * @param len the desired length
+    * @param fd     the file descriptor
+    * @param length the desired length
     * @return undefined.
     */
-  def ftruncateSync(fd: FileDescriptor, len: Double): Unit = js.native
+  def ftruncateSync(fd: FileDescriptor, length: Double): Unit = js.native
 
   /**
     * Change the file timestamps of a file referenced by the supplied file descriptor.
@@ -516,7 +517,7 @@ trait Fs extends IEventEmitter {
   /**
     * Synchronous lstat(2).
     * @param path the path (Buffer | String)
-    * @return an instance of fs.Stats.
+    * @return an instance of [[fs.Stats]].
     */
   def lstatSync(path: Buffer | String): Stats = js.native
 
@@ -525,7 +526,7 @@ trait Fs extends IEventEmitter {
     * mode defaults to 0o777.
     * @example fs.mkdir(path[, mode], callback)
     */
-  def mkdir(path: Buffer | String, mode: FileMode | js.Any, callback: FsCallback0): Unit = js.native
+  def mkdir(path: Buffer | String, mode: FileMode, callback: FsCallback0): Unit = js.native
 
   /**
     * Asynchronous mkdir(2). No arguments other than a possible exception are given to the completion callback.
@@ -785,7 +786,7 @@ trait Fs extends IEventEmitter {
     */
   def readlink(path: Buffer | String,
                options: String | FileEncodingOptions | RawOptions,
-               callback: js.Function2[FileIOError, String, Any]): Unit = js.native
+               callback: FsCallback1[String]): Unit = js.native
 
   /**
     * Synchronous readlink(2).
@@ -864,14 +865,14 @@ trait Fs extends IEventEmitter {
   def rmdirSync(path: Buffer | String): Unit = js.native
 
   /**
-    * Asynchronous stat(2). The callback gets two arguments (err, stats) where stats is a fs.[[Stats]] object.
+    * Asynchronous stat(2). The callback gets two arguments (err, stats) where stats is a [[fs.Stats]] object.
     * See the fs.Stats section for more information.
     * @example fs.stat(path, callback)
     */
   def stat(path: Buffer | String, callback: FsCallback1[Stats]): Stats = js.native
 
   /**
-    * Synchronous stat(2). Returns an instance of fs.[[Stats]].
+    * Synchronous stat(2). Returns an instance of [[fs.Stats]].
     * @example fs.statSync(path)
     */
   def statSync(path: Buffer | String): Stats = js.native
@@ -912,7 +913,7 @@ trait Fs extends IEventEmitter {
     * @param path     the path  <String> | <Buffer>
     * @param length   the length
     * @param callback the completion callback.
-    * @example fs.truncate(path, len, callback)
+    * @example fs.truncate(path, length, callback)
     */
   def truncate(path: Buffer | FileDescriptor | String, length: Int, callback: FsCallback0): Unit = js.native
 
@@ -922,7 +923,7 @@ trait Fs extends IEventEmitter {
     * @param path   the path or file descriptor - <String> | <Buffer> | <Integer>
     * @param length the length
     * @return undefined.
-    * @example fs.truncateSync(path, len)
+    * @example fs.truncateSync(path, length)
     */
   def truncateSync(path: Buffer | FileDescriptor | String, length: Int): Unit = js.native
 
@@ -971,7 +972,7 @@ trait Fs extends IEventEmitter {
 
   /**
     * Watch for changes on filename, where filename is either a file or a directory.
-    * The returned object is a fs.[[FSWatcher]].
+    * The returned object is a [[fs.FSWatcher]].
     *
     * The second argument is optional. If options is provided as a string, it specifies the encoding.
     * Otherwise options should be passed as an object.
@@ -990,7 +991,7 @@ trait Fs extends IEventEmitter {
 
   /**
     * Watch for changes on filename, where filename is either a file or a directory.
-    * The returned object is a fs.[[FSWatcher]].
+    * The returned object is a [[fs.FSWatcher]].
     *
     * The second argument is optional. If options is provided as a string, it specifies the encoding.
     * Otherwise options should be passed as an object.
@@ -1008,7 +1009,7 @@ trait Fs extends IEventEmitter {
 
   /**
     * Watch for changes on filename, where filename is either a file or a directory.
-    * The returned object is a fs.[[FSWatcher]].
+    * The returned object is a [[fs.FSWatcher]].
     *
     * The second argument is optional. If options is provided as a string, it specifies the encoding.
     * Otherwise options should be passed as an object.

src/main/scala/io/scalajs/nodejs/fs/Stats.scala

@@ -16,13 +16,13 @@ trait Stats extends js.Object {
 
   def dev: Int = js.native
 
-  def mode: Int = js.native
+  def mode: FileMode = js.native
 
   def nlink: Int = js.native
 
-  def uid: Int = js.native
+  def uid: UID = js.native
 
-  def gid: Int = js.native
+  def gid: GID = js.native
 
   def rdev: Int = js.native