# coro-fs

Documentation for the module coro-fs, version 2.2.4.

coro-fs is a library for asynchronous non-blocking filesystem operations that keeps the synchronous code style, making use of Lua coroutines.

Luvit’s built-in fs module already has asynchronous non-blocking operations (the calls not suffixed with Sync, as Sync calls will block a thread in the threadpool!) but they use the ugly callbacks!

This allows you to perform all the FS operations Luvit built-in fs has, but with a synchronous code style making use of Lua coroutines.

Note: By choosing to do asynchronous FS, you are making a tradeoff. First off, Luvit (and coro-fs) uses Libuv for filesystem IO, while the synchronous blocking calls in the Luvit fs API (e.x. fs.writeFileSync) will block a thread, they still allow other I/O operations to happen, and the event loop can still tick just fine, this is because Libuv has a threadpool which all I/O happens in (by default 4 threads and can be changed with the UV_THREADPOOL_SIZE environment variable), one of those threads is blocked instead. So you can aboslutely be doing 4 blocking reads/writes (by default) before you actually run into issues where you need asynchronous FS. For example, if you are running a web server where you read a file and send it back, it is possible that you could receive 4 connections at the same time, they all concurrently read some file and send the responses back without interrupting each other. The tradeoff you make by using asynchronous FS is performance, synchronous I/O is much faster but it blocks a thread in the threadpool, while asynchronous I/O is much slower but won’t block any threads. Unless you are running a very busy server, I can’t imagine you need asynchronous FS!

Another Note: Luvit built-in async fs ALREADY has coroutine support which achieve a similar purpose to this module:

local fs = require('fs')
local co = coroutine.running()
local contents = fs.readFile('./my_file.txt', co)
print("The file contains: ", contents)

local coro_fs = require('coro-fs')
local contents = coro_fs.readFile('./my_file.txt')
print("The file contains: ", contents)

# Installation

lit install creationix/coro-fs

On Lit search.

# Errors

All of the functions documented here will return a fail tuple in case of failure, that is, nil, errMsg, therefor all of the first returns could also return nil. The errMsg return is a string that looks something similar to EEXIST: file already exists: foo.txt. Be aware that this only applies to IO failure, meaning, if you for example supply the wrong amount/type of parameters it may raise an error.

The first part of the error is the error code (the EEXIST: in the previous example), those are defined by libuv and listed up by man7 (each fs method individually). The second part explains what went wrong exactly, and the last part explains what file/directory path the error refers to.

# Functions

# mkdir(path[, mode])

Creates a new directory using the provided path.

The owner of the created directory should be the effective user/group ID of said process, or it could inherit the parent directory group-ID. The exact behavior is filesystem dependant.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description	Optional
path	string	The path of the directory you want to create	❌
mode	number	The inode bit mode at which to create said directory. Not implemented on Windows.	✔ Default: `511`.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# open(path[, flags[, mode]])

Opens a file, or possibly creates one using the said file path.

The owner of a created file should be the effective user/group ID of said process, or it could inherit the parent directory group-ID. The exact behavior is filesystem dependant.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description	Optional
path	string	The path of the file to open/create.	❌
flags	string	The access mode of the opened file. See *TODO* for valid values.	✔ Default: `"r"`.
mode	number	The file’s inode mode to be applied when a file is created. Note that this only applies to future access of the newly created file.	✔ Default: `438`.

# Returns

Name	Type	Description	Provided On
descriptor	number/nil	The file descriptor number of the opened file on success, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

# unlink(path)

Deletes (unlinks) a file from the filesystem.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The path of the file to be deleted/unlinked.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# stat(path)

Retrieves information about the file/directory pointed out by path.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The path to the file or directory you want to retrieve information about.

# Returns

Name	Type	Description	Provided On
info	table/nil	The information about said file/directory on success, see *TODO*, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

# lstat(path)

Identical to stat, except if the path was for a symbolic link, the information will be about the link itself instead of its target.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The path to the file or directory you want to retrieve information about.

# Returns

Name	Type	Description	Provided On
info	table/nil	The information about said file/directory on success, see *TODO*, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

# fstat(fd)

Identical to stat, except that instead of accepting a path to file/directory, this accepts a file descriptor.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
fd	number	The descriptor of the file you want to retrieve the information about.

# Returns

Name	Type	Description	Provided On
info	table/nil	The information about said file/directory on success, see *TODO*, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

# symlink(target, path, flags)

Creates a symbolic link (also known as soft link) at path that points up to target.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
target	string	The path of the file you want to link against.
path	string	The path to where to create the said link at.
flags	table / integer / nil	Optional table with `dir` and `junction` boolean fields that control how the symlink is created on Windows. See Libuv page for more details.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# readlink(path)

Retrieves the target path (the content) of the said symbolic link path.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The path to the symbolic link you want to retrieve its content.

# Returns

Name	Type	Description	Provided On
cont	string/nil	The target path (the content) of the symlink on success, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

# chmod(path, mode)

Changes the inode mode bits (e.g. the permissions) of said file.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	Path to the file you want to manipulate.
mode	number	Decimal number representing the bit mode.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# fchmod(fd, mode)

Identical to chmod, except that instead of accepting a file path, you use a file descriptor.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
fd	number	The descriptor of the file to manipulate.
mode	number	Decimal number representing the bit mode.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# read(fd[, length[, offset]])

Reads length bytes of fd file’s contents.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description	Optional
fd	number	The descriptor of the file to read from.	❌
length	number	How many bytes should be read from the file.	✔ Default: `49152`.
offset	number	How many bytes should be sought before start reading. `-1` means “Use current file position”.	✔ Default: `-1`.

# Returns

Name	Type	Description	Provided On
data	string/nil	The read contents on success, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

# write(fd, data[, offset])

Writes data to file using its descriptor fd.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description	Optional
fd	number	The descriptor of the file to write data to.	❌
data	string	The data you want to write to the file as string.	❌
offset	number	How many bytes should be sought before writing the data. `-1` means “Use the current file position”.	✔ Default: `-1`.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# close(fd)

Closes the opened file fd, so fd don’t refer to anything anymore.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
fd	number	The descriptor of the file to be closed.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# access(path[, mode])

Checks whether the current process have permissions to access the file/directory path.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description	Optional
path	string	The path to the file/directory you want to check against.	❌
mode	number/string	The accessibility check, number to specify the bit permissions mode, string to specify access mode (`"R"` for read, `"W"` for write, `"X"` for execute).	✔ Default: `""`.

# Returns

Name	Type	Description	Provided On
perm	boolean/nil	Boolean indicts whether you have permissions to access said file/directory or not on success, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

# rename(path, newPath)

Renames a file or a directory to newPath. Can be also used to move a file/directory just by specifying newPath to the target path to move files into.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The path to the file or directory you want to rename/move.
newPath	string	The new path/name of the renamed/moved file or directory.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# rmdir(path)

Removes and deletes an empty (and only an empty) directory. For recursive remove see rmrf.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The path to the directory you want to delete.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# rmrf(path)

Tries to recursively delete path, while handling most possible scenarios. Most suitable for deleting non-empty directories, or when you just want something to be deleted without having to handle additional exceptions.

If the path is a directory its contents will be deleted first then it will be removed.
If the path is a file it will be deleted.
If the path is a symbolic link it will be unlinked.

WARNING: You cannot undo this! There is no Recycle Bin.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The path to the object you want to remove.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# scandir(path)

An iterator that iterates a directory for files and sub-directories.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The directory path to be scanned.

# Returns

Name	Type	Description	Provided On
entry	table/nil	A table that contains two fields `name` and `type` on success, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

TODO: Example.

# readFile(path)

Fully reads a file and returns its contents as a single string.

Note: In some rare and system specific cases, only a chunk of the file will be read.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description
path	string	The path to the file you want to read.

# Returns

Name	Type	Description	Provided On
data	string/nil	The contents of the file on success, otherwise nil.	Always
err	string	A string describing the error.	Failure Only

# writeFile(path, data[, mkdir])

Writes data to file path in a one go.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description	Optional
path	string	The path to the file you want to write into.	❌
data	string	The data you want to write into the file as string.	❌
mkdir	boolean	Whether you want coro-fs to create any missing directories in the provided `path` or not.	✔️ Default: `false`.

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# mkdirp(path[, mode])

Recursively creates missing directories in a path with the said bit mode.

For example mkdir("./a/b/c/") this call will create a directory a that contains directory b if they don’t already exists, etc.

This method MUST be run in a coroutine

# Parameters

Param	Type	Description	Optional
path	string	The path that might contains the missing directories to be created.	❌
mode	number	Decimal number of the indoe mode bits (e.g. its permissions).	✔️

# Returns

Name	Type	Description	Provided On
success	boolean/nil	Whether or not the operation has succeeded.	Always
err	string	A string describing the error.	Failure Only

# chroot(base)

Returns a version of this module that can only operate inside base directory. This is supposed to be safe and unescapable, and is used in sensitive places such as the Lit server.

The table returned is identical to the module table, except an additional base field that is equal to the passed argument.

WARNING: In version 2.2.1 and before, there was a bug that allowed an attacker to escape the chroot. If you are using a vulnerable version, please update to 2.2.2 or newer!

This method does not require running in a coroutine

# Parameters

Param	Type	Description	Optional
base	string	The path to the directory FS operations will be contained in.	❌

# Returns

Name	Type	Description	Provided On
chroot	table	A table containing all methods this module contains.	Always