View source

class Fs

package js.node

@:directlyUsed@:jsRequire("fs")

File I/O is provided by simple wrappers around standard POSIX functions. All the methods have asynchronous and synchronous forms.

The asynchronous form always take a completion callback as its last argument. The arguments passed to the completion callback depend on the method, but the first argument is always reserved for an exception.

If the operation was completed successfully, then the first argument will be null.

When using the synchronous form any exceptions are immediately thrown. You can use try/catch to handle exceptions or allow them to bubble up.

Static variables

staticread onlyF_OK:Int

A mode flag for access and accessSync methods:

File is visible to the calling process. This is useful for determining if a file exists, but says nothing about rwx permissions.

staticread onlyR_OK:Int

A mode flag for access and accessSync methods:

File can be read by the calling process.

staticread onlyW_OK:Int

A mode flag for access and accessSync methods:

File can be written by the calling process.

staticread onlyX_OK:Int

A mode flag for access and accessSync methods:

File can be executed by the calling process. This has no effect on Windows.

staticread onlyconstants:FsConstants

An object containing commonly used constants for file system operations.

Static methods

staticaccess(path:FsPath, mode:Int, callback:Error ‑> Void):Void

staticaccess(path:FsPath, callback:Error ‑> Void):Void

Tests a user's permissions for the file or directory specified by path.

The mode argument is an optional integer that specifies the accessibility checks to be performed. The following constants define the possible values of mode. It is possible to create a mask consisting of the bitwise OR of two or more values.

  • Fs.constants.F_OK - path 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.
  • Fs.constants.R_OK - path can be read by the calling process.
  • Fs.constants.W_OK - path can be written by the calling process.
  • Fs.constants.X_OK - path can be executed by the calling process. This has no effect on Windows (will behave like Fs.constants.F_OK).

The final argument, callback, is a callback function that is invoked with a possible error argument. If any of the accessibility checks fail, the error argument will be populated.

staticaccessSync(path:FsPath, ?mode:Int):Void

Synchronous version of access. This throws if any accessibility checks fail, and does nothing otherwise.

staticappendFile(filename:FsPath, data:String, options:EitherType<String, FsWriteFileOptions>, callback:Error ‑> Void):Void

staticappendFile(filename:FsPath, data:Buffer, callback:Error ‑> Void):Void

staticappendFile(filename:FsPath, data:String, callback:Error ‑> Void):Void

staticappendFile(filename:FsPath, data:Buffer, options:EitherType<String, FsWriteFileOptions>, callback:Error ‑> Void):Void

Asynchronously append data to a file, creating the file if it not yet exists. data can be a string or a buffer.

staticappendFileSync(filename:FsPath, data:String, options:EitherType<String, FsWriteFileOptions>):Void

staticappendFileSync(filename:FsPath, data:Buffer):Void

staticappendFileSync(filename:FsPath, data:String):Void

staticappendFileSync(filename:FsPath, data:Buffer, options:EitherType<String, FsWriteFileOptions>):Void

The synchronous version of appendFile.

staticchmod(path:FsPath, mode:FsMode, callback:Error ‑> Void):Void

Asynchronous chmod(2).

staticchmodSync(path:FsPath, mode:FsMode):Void

Synchronous chmod(2).

staticchown(path:FsPath, uid:Int, gid:Int, callback:Error ‑> Void):Void

Asynchronous chown(2).

staticchownSync(path:FsPath, uid:Int, gid:Int):Void

Synchronous chown(2).

staticclose(fd:Int, callback:Error ‑> Void):Void

Asynchronous close(2).

staticcloseSync(fd:Int):Void

Synchronous close(2).

staticcreateReadStream(path:FsPath, ?options:EitherType<String, FsCreateReadStreamOptions>):ReadStream

Returns a new ReadStream object (See Readable Stream).

options can include start and end values to read a range of bytes from the file instead of the entire file. Both start and end are inclusive and start at 0.

The encoding can be 'utf8', 'ascii', or 'base64'.

If autoClose is false, then the file descriptor won't be closed, even if there's an error. It is your responsiblity to close it and make sure there's no file descriptor leak. If autoClose is set to true (default behavior), on error or end the file descriptor will be closed automatically.

staticcreateWriteStream(path:FsPath, ?options:Null<FsCreateWriteStreamOptions>):WriteStream

Returns a new WriteStream object (See Writable Stream).

options may also include a start option to allow writing data at some position past the beginning of the file.

Modifying a file rather than replacing it may require a flags mode of r+ rather than the default mode w.

staticexists(path:FsPath, callback:Bool ‑> Void):Void

Deprecated: "Use Fs.stat or Fs.access instead"

Test whether or not the given path exists by checking with the file system. Then call the callback argument with either true or false.

exists is an anachronism and exists only for historical reasons. There should almost never be a reason to use it in your own code.

In particular, checking if a file exists before opening it is an anti-pattern that leaves you vulnerable to race conditions: another process may remove the file between the calls to exists and open.

Just open the file and handle the error when it's not there.

staticexistsSync(path:FsPath):Bool

Synchronous version of exists.

staticfchmod(fd:Int, mode:FsMode, callback:Error ‑> Void):Void

Asynchronous fchmod(2).

staticfchmodSync(fd:Int, mode:FsMode):Void

Synchronous fchmod(2).

staticfchown(fd:Int, uid:Int, gid:Int, callback:Error ‑> Void):Void

Asynchronous fchown(2).

staticfchownSync(fd:Int, uid:Int, gid:Int):Void

Synchronous fchown(2).

staticfstat(fd:Int, callback:(Error, Stats) ‑> Void):Void

Asynchronous fstat(2).

fstat() is identical to stat(), except that the file to be stat-ed is specified by the file descriptor fd.

staticfstatSync(fd:Int):Stats

Synchronous fstat(2).

staticfsync(fd:Int, callback:Error ‑> Void):Void

Asynchronous fsync(2).

staticfsyncSync(fd:Int):Void

Synchronous fsync(2).

staticftruncate(fd:Int, len:Int, callback:Error ‑> Void):Void

Asynchronous ftruncate(2).

staticftruncateSync(fd:Int, len:Int):Void

Synchronous ftruncate(2).

staticfutimes(fd:Int, atime:Date, mtime:Date, callback:Error ‑> Void):Void

Change the file timestamps of a file referenced by the supplied file descriptor.

staticfutimesSync(fd:Int, atime:Date, mtime:Date):Void

Change the file timestamps of a file referenced by the supplied file descriptor.

staticlchmod(path:FsPath, mode:FsMode, callback:Error ‑> Void):Void

Asynchronous lchmod(2). Only available on Mac OS X.

staticlchmodSync(path:FsPath, mode:FsMode):Void

Synchronous lchmod(2).

staticlchown(path:FsPath, uid:Int, gid:Int, callback:Error ‑> Void):Void

Asynchronous lchown(2).

staticlchownSync(path:FsPath, uid:Int, gid:Int):Void

Synchronous lchown(2).

staticlink(srcpath:FsPath, dstpath:FsPath, callback:Error ‑> Void):Void

Asynchronous link(2).

staticlinkSync(srcpath:FsPath, dstpath:FsPath):Void

Synchronous link(2).

staticlstat(path:FsPath, callback:(Error, Stats) ‑> Void):Void

Asynchronous lstat(2).

lstat() is identical to stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to.

staticlstatSync(path:FsPath):Stats

Synchronous lstat(2).

staticmkdir(path:FsPath, mode:FsMode, callback:Error ‑> Void):Void

staticmkdir(path:FsPath, callback:Error ‑> Void):Void

Asynchronous mkdir(2). mode defaults to 0777.

staticmkdirSync(path:FsPath, ?mode:Null<FsMode>):Void

Synchronous mkdir(2).

staticmkdtemp(prefix:String, callback:(Error, String) ‑> Void):Void

Creates a unique temporary directory.

Generates six random characters to be appended behind a required prefix to create a unique temporary directory.

The created folder path is passed as a string to the callback's second parameter.

staticmkdtempSync(template:String):String

The synchronous version of mkdtemp.

Returns the created folder path.

staticopen(path:FsPath, flags:FsOpenFlag, mode:FsMode, callback:(Error, Int) ‑> Void):Void

staticopen(path:FsPath, flags:FsOpenFlag, callback:(Error, Int) ‑> Void):Void

Asynchronous file open. See open(2).

See FsOpenFlag for description of possible flags.

mode sets the file mode (permission and sticky bits), but only if the file was created. It defaults to 0666, readable and writeable.

The callback gets two arguments (err, fd).

staticopenSync(path:FsPath, flags:FsOpenFlag, mode:FsMode):Int

staticopenSync(path:FsPath, flags:FsOpenFlag):Int

Synchronous version of open().

staticread(fd:Int, buffer:Buffer, offset:Int, length:Int, position:Null<Int>, callback:(Error, Int, Buffer) ‑> Void):Void

Read data from the file specified by fd.

buffer is the buffer that the data will be written to.

offset is the offset in the buffer to start writing at.

length is an integer specifying the number of bytes to read.

position is an integer specifying where to begin reading from in the file. If position is null, data will be read from the current file position.

The callback is given the three arguments, (err, bytesRead, buffer).

staticreadFile(filename:FsPath, options:{flag:Null<FsOpenFlag>, encoding:String}, callback:(Error, String) ‑> Void):Void

staticreadFile(filename:FsPath, callback:(Error, Buffer) ‑> Void):Void

staticreadFile(filename:FsPath, options:{flag:FsOpenFlag}, callback:(Error, Buffer) ‑> Void):Void

staticreadFile(filename:FsPath, options:String, callback:(Error, String) ‑> Void):Void

Asynchronously reads the entire contents of a file.

The callback is passed two arguments (err, data), where data is the contents of the file. If no encoding is specified, then the raw buffer is returned.

If options is a string, then it specifies the encoding.

staticreadFileSync(filename:FsPath, options:{flag:Null<FsOpenFlag>, encoding:String}):String

staticreadFileSync(filename:FsPath):Buffer

staticreadFileSync(filename:FsPath, options:{flag:FsOpenFlag}):Buffer

staticreadFileSync(filename:FsPath, options:String):String

Synchronous version of readFile. Returns the contents of the filename. If the encoding option is specified then this function returns a string. Otherwise it returns a buffer.

staticreadSync(fd:Int, buffer:Buffer, offset:Int, length:Int, position:Null<Int>):Int

Synchronous version of read. Returns the number of bytes read.

staticreaddir(path:FsPath, callback:(Error, Array<String>) ‑> Void):Void

Asynchronous readdir(3). Reads the contents of a directory.

The callback gets two arguments (err, files) where files is an array of the names of the files in the directory excluding '.' and '..'.

staticreaddirSync(path:FsPath):Array<String>

Synchronous readdir(3). Returns an array of filenames excluding '.' and '..'.

staticreadlink(path:FsPath, callback:(Error, String) ‑> Void):Void

Asynchronous readlink(2).

staticreadlinkSync(path:FsPath):String

Synchronous readlink(2). Returns the symbolic link's string value.

staticrealpath(path:FsPath, cache:DynamicAccess<String>, callback:(Error, String) ‑> Void):Void

staticrealpath(path:FsPath, callback:(Error, String) ‑> Void):Void

Asynchronous realpath(2).

The callback gets two arguments (err, resolvedPath).

May use process.cwd to resolve relative paths.

cache is an object literal of mapped paths that can be used to force a specific path resolution or avoid additional stat calls for known real paths.

staticrealpathSync(path:FsPath, cache:DynamicAccess<String>):String

staticrealpathSync(path:FsPath):String

Synchronous realpath(2). Returns the resolved path.

staticrename(oldPath:FsPath, newPath:FsPath, callback:Error ‑> Void):Void

Asynchronous rename(2).

staticrenameSync(oldPath:FsPath, newPath:FsPath):Void

Synchronous rename(2).

staticrmdir(path:FsPath, options:FsRmdirOptions, callback:Error ‑> Void):Void

staticrmdir(path:FsPath, callback:Error ‑> Void):Void

Asynchronous rmdir(2).

staticrmdirSync(path:FsPath, ?options:Null<FsRmdirOptions>):Void

Synchronous rmdir(2).

staticstat(path:FsPath, callback:(Error, Stats) ‑> Void):Void

Asynchronous stat(2).

staticstatSync(path:FsPath):Stats

Synchronous stat(2).

staticsymlink(srcpath:FsPath, dstpath:FsPath, type:SymlinkType, callback:Error ‑> Void):Void

staticsymlink(srcpath:FsPath, dstpath:FsPath, callback:Error ‑> Void):Void

Asynchronous symlink(2).

The type argument can be set to 'dir', 'file', or 'junction' (default is 'file') and is only available on Windows (ignored on other platforms). Note that Windows junction points require the destination path to be absolute. When using 'junction', the destination argument will automatically be normalized to absolute path.

staticsymlinkSync(srcpath:FsPath, dstpath:FsPath, type:SymlinkType):Void

staticsymlinkSync(srcpath:FsPath, dstpath:FsPath):Void

Synchronous symlink(2).

statictruncate(path:FsPath, len:Int, callback:Error ‑> Void):Void

Asynchronous truncate(2).

statictruncateSync(path:FsPath, len:Int):Void

Synchronous truncate(2).

staticunlink(path:FsPath, callback:Error ‑> Void):Void

Asynchronous unlink(2).

staticunlinkSync(path:FsPath):Void

Synchronous unlink(2).

staticunwatchFile(filename:FsPath, ?listener:(Stats, Stats) ‑> Void):Void

Unstable. Use watch instead, if possible.

Stop watching for changes on filename. If listener is specified, only that particular listener is removed. Otherwise, all listeners are removed and you have effectively stopped watching filename. Calling unwatchFile with a filename that is not being watched is a no-op, not an error.

staticutimes(path:FsPath, atime:Date, mtime:Date, callback:Error ‑> Void):Void

Change file timestamps of the file referenced by the supplied path.

staticutimesSync(path:FsPath, atime:Date, mtime:Date):Void

Change file timestamps of the file referenced by the supplied path.

staticwatch(filename:FsPath, listener:(FSWatcherChangeType, FsPath) ‑> Void):FSWatcher

staticwatch(filename:FsPath):FSWatcher

staticwatch(filename:FsPath, options:{recursive:Null<Bool>, persistent:Bool}, listener:(FSWatcherChangeType, String) ‑> Void):FSWatcher

Watch for changes on filename, where filename is either a file or a directory.

persistent indicates whether the process should continue to run as long as files are being watched. Default is true.

The listener callback gets two arguments (event, filename). event is either 'rename' or 'change', and filename is the name of the file which triggered the event.

staticwatchFile(filename:FsPath, options:FsWatchFileOptions, listener:(Stats, Stats) ‑> Void):Void

staticwatchFile(filename:FsPath, listener:(Stats, Stats) ‑> Void):Void

Unstable. Use watch instead, if possible.

Watch for changes on filename. The callback listener will be called each time the file is accessed.

The options if provided should be an object containing two members:

- `persistent` indicates whether the process should continue to run as long as files are being watched.
- `interval` indicates how often the target should be polled, in milliseconds.

The default is { persistent: true, interval: 5007 }.

The listener gets two arguments: the current stat object and the previous stat object.

staticwrite(fd:Int, buffer:Buffer, offset:Int, length:Int, position:Int, callback:(Error, Int, Buffer) ‑> Void):Void

staticwrite(fd:Int, data:Dynamic, position:Int, encoding:String, callback:(Error, Int, String) ‑> Void):Void

staticwrite(fd:Int, data:Dynamic, position:Int, callback:(Error, Int, String) ‑> Void):Void

staticwrite(fd:Int, data:Dynamic, callback:(Error, Int, String) ‑> Void):Void

staticwrite(fd:Int, buffer:Buffer, offset:Int, length:Int, callback:(Error, Int, Buffer) ‑> Void):Void

Documentation for the overloads with the buffer argument:

Write buffer to the file specified by fd.

offset and length determine the part of the buffer to be written.

position refers to the offset from the beginning of the file where this data should be written. If position is null, the data will be written at the current position. See pwrite(2).

The callback will be given three arguments (err, written, buffer) where written specifies how many bytes were written from buffer.

Documentation for the overloads with the data argument:

Write data to the file specified by fd. If data is not a Buffer instance then the value will be coerced to a string.

position refers to the offset from the beginning of the file where this data should be written. If omitted, the data will be written at the current position. See pwrite(2).

encoding is the expected string encoding.

The callback will receive the arguments (err, written, string) where written specifies how many bytes the passed string required to be written. Note that bytes written is not the same as string characters. See Buffer.byteLength.

Unlike when writing buffer, the entire string must be written. No substring may be specified. This is because the byte offset of the resulting data may not be the same as the string offset.

Common notes:

Note that it is unsafe to use write multiple times on the same file without waiting for the callback. For this scenario, createWriteStream is strongly recommended.

On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.

staticwriteFile(filename:FsPath, data:String, options:EitherType<String, FsWriteFileOptions>, callback:Error ‑> Void):Void

staticwriteFile(filename:FsPath, data:Buffer, callback:Error ‑> Void):Void

staticwriteFile(filename:FsPath, data:String, callback:Error ‑> Void):Void

staticwriteFile(filename:FsPath, data:Buffer, options:EitherType<String, FsWriteFileOptions>, callback:Error ‑> Void):Void

Asynchronously writes data to a file, replacing the file if it already exists.

data can be a string or a buffer.

The encoding option is ignored if data is a buffer. It defaults to 'utf8'.

staticwriteFileSync(filename:FsPath, data:String, options:EitherType<String, FsWriteFileOptions>):Void

staticwriteFileSync(filename:FsPath, data:Buffer):Void

staticwriteFileSync(filename:FsPath, data:String):Void

staticwriteFileSync(filename:FsPath, data:Buffer, options:EitherType<String, FsWriteFileOptions>):Void

The synchronous version of writeFile.

staticwriteSync(fd:Int, buffer:Buffer, offset:Int, length:Int, ?position:Int):Int

staticwriteSync(fd:Int, data:Dynamic, position:Int, encoding:String):Int

staticwriteSync(fd:Int, data:Dynamic, ?position:Int):Int

Synchronous version of write. Returns the number of bytes written.