Fs

View source
js.node.Fs (extern class)

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 Members

constants: FsConstants

An object containing commonly used constants for file system operations.

F_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.

R_OK: Int

A mode flag for access and accessSync methods:

File can be read by the calling process.

W_OK: Int

A mode flag for access and accessSync methods:

File can be written by the calling process.

X_OK: Int

A mode flag for access and accessSync methods:

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

rename(oldPath: FsPath, newPath: FsPath, callback: Function): Void

Asynchronous rename(2).

Name Type
oldPath FsPath
newPath FsPath
callback Function
renameSync(oldPath: FsPath, newPath: FsPath): Void

Synchronous rename(2).

Name Type
oldPath FsPath
newPath FsPath
ftruncate(fd: Int, len: Int, callback: Function): Void

Asynchronous ftruncate(2).

Name Type
fd Int
len Int
callback Function
ftruncateSync(fd: Int, len: Int): Void

Synchronous ftruncate(2).

Name Type
fd Int
len Int
truncate(path: FsPath, len: Int, callback: Function): Void

Asynchronous truncate(2).

Name Type
path FsPath
len Int
callback Function
truncateSync(path: FsPath, len: Int): Void

Synchronous truncate(2).

Name Type
path FsPath
len Int
chown(path: FsPath, uid: Int, gid: Int, callback: Function): Void

Asynchronous chown(2).

Name Type
path FsPath
uid Int
gid Int
callback Function
chownSync(path: FsPath, uid: Int, gid: Int): Void

Synchronous chown(2).

Name Type
path FsPath
uid Int
gid Int
fchown(fd: Int, uid: Int, gid: Int, callback: Function): Void

Asynchronous fchown(2).

Name Type
fd Int
uid Int
gid Int
callback Function
fchownSync(fd: Int, uid: Int, gid: Int): Void

Synchronous fchown(2).

Name Type
fd Int
uid Int
gid Int
lchown(path: FsPath, uid: Int, gid: Int, callback: Function): Void

Asynchronous lchown(2).

Name Type
path FsPath
uid Int
gid Int
callback Function
lchownSync(path: FsPath, uid: Int, gid: Int): Void

Synchronous lchown(2).

Name Type
path FsPath
uid Int
gid Int
chmod(path: FsPath, mode: FsMode, callback: Function): Void

Asynchronous chmod(2).

Name Type
path FsPath
mode FsMode
callback Function
chmodSync(path: FsPath, mode: FsMode): Void

Synchronous chmod(2).

Name Type
path FsPath
mode FsMode
fchmod(fd: Int, mode: FsMode, callback: Function): Void

Asynchronous fchmod(2).

Name Type
fd Int
mode FsMode
callback Function
fchmodSync(fd: Int, mode: FsMode): Void

Synchronous fchmod(2).

Name Type
fd Int
mode FsMode
lchmod(path: FsPath, mode: FsMode, callback: Function): Void

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

Name Type
path FsPath
mode FsMode
callback Function
lchmodSync(path: FsPath, mode: FsMode): Void

Synchronous lchmod(2).

Name Type
path FsPath
mode FsMode
stat(path: FsPath, callback: Function): Void

Asynchronous stat(2).

Name Type
path FsPath
callback Function
lstat(path: FsPath, callback: Function): 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.

Name Type
path FsPath
callback Function
fstat(fd: Int, callback: Function): Void

Asynchronous fstat(2).

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

Name Type
fd Int
callback Function
statSync(path: FsPath): js.node.fs.Stats

Synchronous stat(2).

Name Type
path FsPath
Returns
js.node.fs.Stats
lstatSync(path: FsPath): js.node.fs.Stats

Synchronous lstat(2).

Name Type
path FsPath
Returns
js.node.fs.Stats
fstatSync(fd: Int): js.node.fs.Stats

Synchronous fstat(2).

Name Type
fd Int
Returns
js.node.fs.Stats

Asynchronous link(2).

Name Type
srcpath FsPath
dstpath FsPath
callback Function
linkSync(srcpath: FsPath, dstpath: FsPath): Void

Synchronous link(2).

Name Type
srcpath FsPath
dstpath FsPath

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.

Name Type
srcpath FsPath
dstpath FsPath
type SymlinkType
callback Function
symlinkSync(srcpath: FsPath, dstpath: FsPath, type: SymlinkType): Void

Synchronous symlink(2).

Name Type
srcpath FsPath
dstpath FsPath
type SymlinkType

Asynchronous readlink(2).

Name Type
path FsPath
callback Function
readlinkSync(path: FsPath): String

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

Name Type
path FsPath
Returns
String
realpath(path: FsPath, cache: haxe.DynamicAccess<String>, callback: Function): 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.

Name Type
path FsPath
cache haxe.DynamicAccess<String>
callback Function
realpathSync(path: FsPath, cache: haxe.DynamicAccess<String>): String

Synchronous realpath(2). Returns the resolved path.

Name Type
path FsPath
cache haxe.DynamicAccess<String>
Returns
String

Asynchronous unlink(2).

Name Type
path FsPath
callback Function
unlinkSync(path: FsPath): Void

Synchronous unlink(2).

Name Type
path FsPath
rmdir(path: FsPath, options: FsRmdirOptions, callback: Function): Void

Asynchronous rmdir(2).

Name Type
path FsPath
options FsRmdirOptions
callback Function
rmdirSync(path: FsPath, ?options: Null<FsRmdirOptions>): Void

Synchronous rmdir(2).

Name Type Default
path FsPath
options Null<FsRmdirOptions> (optional)
mkdir(path: FsPath, mode: FsMode, callback: Function): Void

Asynchronous mkdir(2). mode defaults to 0777.

Name Type
path FsPath
mode FsMode
callback Function
mkdirSync(path: FsPath, ?mode: Null<FsMode>): Void

Synchronous mkdir(2).

Name Type Default
path FsPath
mode Null<FsMode> (optional)
mkdtemp(prefix: String, callback: Function): 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.

Name Type
prefix String
callback Function
mkdtempSync(template: String): String

The synchronous version of mkdtemp.

Returns the created folder path.

Name Type
template String
Returns
String
readdir(path: FsPath, callback: Function): 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 '..'.

Name Type
path FsPath
callback Function
readdirSync(path: FsPath): Array<String>

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

Name Type
path FsPath
Returns
Array<String>
close(fd: Int, callback: Function): Void

Asynchronous close(2).

Name Type
fd Int
callback Function
closeSync(fd: Int): Void

Synchronous close(2).

Name Type
fd Int
open(path: FsPath, flags: FsOpenFlag, mode: FsMode, callback: Function): 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).

Name Type
path FsPath
flags FsOpenFlag
mode FsMode
callback Function
openSync(path: FsPath, flags: FsOpenFlag, mode: FsMode): Int

Synchronous version of open().

Name Type
path FsPath
flags FsOpenFlag
mode FsMode
Returns
Int
utimes(path: FsPath, atime: Date, mtime: Date, callback: Function): Void

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

Name Type
path FsPath
atime Date
mtime Date
callback Function
utimesSync(path: FsPath, atime: Date, mtime: Date): Void

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

Name Type
path FsPath
atime Date
mtime Date
futimes(fd: Int, atime: Date, mtime: Date, callback: Function): Void

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

Name Type
fd Int
atime Date
mtime Date
callback Function
futimesSync(fd: Int, atime: Date, mtime: Date): Void

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

Name Type
fd Int
atime Date
mtime Date
fsync(fd: Int, callback: Function): Void

Asynchronous fsync(2).

Name Type
fd Int
callback Function
fsyncSync(fd: Int): Void

Synchronous fsync(2).

Name Type
fd Int
write(fd: Int, buffer: Buffer, offset: Int, length: Int, position: Int, callback: Function): 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.

Name Type
fd Int
buffer Buffer
offset Int
length Int
position Int
callback Function
writeSync(fd: Int, buffer: Buffer, offset: Int, length: Int, ?position: Int): Int

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

Name Type Default
fd Int
buffer Buffer
offset Int
length Int
position Int (optional)
Returns
Int
read(fd: Int, buffer: Buffer, offset: Int, length: Int, position: Null<Int>, callback: Function): 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).

Name Type
fd Int
buffer Buffer
offset Int
length Int
position Null<Int>
callback Function
readSync(fd: Int, buffer: Buffer, offset: Int, length: Int, position: Null<Int>): Int

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

Name Type
fd Int
buffer Buffer
offset Int
length Int
position Null<Int>
Returns
Int
readFile(filename: FsPath, options: AnonStruct, callback: Function): 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.

Name Type
filename FsPath
options AnonStruct
callback Function
readFileSync(filename: FsPath, options: AnonStruct): 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.

Name Type
filename FsPath
options AnonStruct
Returns
String
writeFile(filename: FsPath, data: String, options: haxe.extern.EitherType<String, FsWriteFileOptions>, callback: Function): 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'.

Name Type
filename FsPath
data String
options haxe.extern.EitherType<String, FsWriteFileOptions>
callback Function
writeFileSync(filename: FsPath, data: String, options: haxe.extern.EitherType<String, FsWriteFileOptions>): Void

The synchronous version of writeFile.

Name Type
filename FsPath
data String
options haxe.extern.EitherType<String, FsWriteFileOptions>
appendFile(filename: FsPath, data: String, options: haxe.extern.EitherType<String, FsWriteFileOptions>, callback: Function): Void

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

Name Type
filename FsPath
data String
options haxe.extern.EitherType<String, FsWriteFileOptions>
callback Function
appendFileSync(filename: FsPath, data: String, options: haxe.extern.EitherType<String, FsWriteFileOptions>): Void

The synchronous version of appendFile.

Name Type
filename FsPath
data String
options haxe.extern.EitherType<String, FsWriteFileOptions>
watchFile(filename: FsPath, options: FsWatchFileOptions, listener: Function): 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.

Name Type
filename FsPath
options FsWatchFileOptions
listener Function
unwatchFile(filename: FsPath, ?listener: Function): 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.

Name Type Default
filename FsPath
listener Function (optional)
watch(filename: FsPath, listener: Function): js.node.fs.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.

Name Type
filename FsPath
listener Function
Returns
js.node.fs.FSWatcher
exists(path: FsPath, callback: Function): Void

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.

Name Type
path FsPath
callback Function
existsSync(path: FsPath): Bool

Synchronous version of exists.

Name Type
path FsPath
Returns
Bool
access(path: FsPath, mode: Int, callback: Function): 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.

Name Type
path FsPath
mode Int
callback Function
accessSync(path: FsPath, ?mode: Int): Void

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

Name Type Default
path FsPath
mode Int (optional)

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.

Name Type Default
path FsPath
options haxe.extern.EitherType<String, FsCreateReadStreamOptions> (optional)
Returns
js.node.fs.ReadStream
createWriteStream(path: FsPath, ?options: Null<FsCreateWriteStreamOptions>): js.node.fs.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.

Name Type Default
path FsPath
options Null<FsCreateWriteStreamOptions> (optional)
Returns
js.node.fs.WriteStream

Metadata

Name Parameters
:jsRequire "fs"