torpor
v0.1.0
Published
lazy and monadic file systems
Downloads
1
Readme
██████████████████████████████████████
██████████████████████████████████████
██████████████████████████████████████
██ ██████████████████████████████████
█ ██ ██ █ █ ███ ██ █ █
██ ██ █ █ █ █ █ █ █
██ ██ █ █ █████ █ █ █ █ █████
██ ██ █ █ █████ █ █ █ █ █████
██ ██ █ █ █████ █ █ █ █ █████
██ ██ ██ █████ ███ ██ █████
███████████████████ █████████████████
███████████████████ █████████████████
███████████████████ █████████████████
██████████████████████████████████████
██████████████████████████████████████
lazy and monadic file system operations
features
- multiple potential input sources
- lazy execution and cancellable asynchronous operations
- excellent error handling
- parallel execution if wanted
built with
API
Table of Contents
- TypedArray
- chainRej
- close
- fdatasync
- fsync
- rmdir
- unlink
- access
- chmod
- fchmod
- fstat
- lchmod
- link
- mkdir
- rename
- appendFile
- chown
- copyFile
- fchown
- futimes
- lchown
- symlink
- utimes
- writeFile
- Future
- readAnyWithFormatOr
- readAnyWithFormat
- readAny
- callbackToTheFuture
- proxifyN
TypedArray
It's a TypedArray
Type: Object
chainRej
It's a Future!
Type: Object
close
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L398 for the source function this function wraps. **
Wraps fs.close with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
close(2)
.No arguments other than a possible exception are given to the completion callback.
Parameters
fd
number -
Returns Future a future value
fdatasync
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L738 for the source function this function wraps. **
Wraps fs.fdatasync with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
fdatasync(2)
.No arguments other than a possible exception are given to the completion callback.
Parameters
fd
number -
Returns Future a future value
fsync
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L752 for the source function this function wraps. **
Wraps fs.fsync with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
fsync(2)
.No arguments other than a possible exception are given to the completion callback.
Parameters
fd
number -
Returns Future a future value
rmdir
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L723 for the source function this function wraps. **
Wraps fs.rmdir with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
rmdir(2)
.No arguments other than a possible exception are given to the completion callback.
Using
fs.rmdir()
on a file (not a directory) results in anENOENT
error on Windows and anENOTDIR
error on POSIX.
Parameters
Returns Future a future value
unlink
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1006 for the source function this function wraps. **
Wraps fs.unlink with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronously removes a file or symbolic link.
No arguments other than a possible exception are given to the completion callback.
`// Assuming that 'path/file.txt' is a regular file. fs.unlink('path/file.txt', (err) => { if (err) throw err; console.log('path/file.txt was deleted'); }); `.
fs.unlink()
will not work on a directory, empty or otherwise.To remove a directory, use
fs.rmdir()
.See also:
unlink(2)
.
Parameters
Returns Future a future value
access
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L179 for the source function this function wraps. **
Wraps fs.access with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Tests a user's permissions for the file or directory specified by
path
. Themode
argument is an optional number that specifies the accessibility checks to be performed.Check File Access Constants for possible values of
mode
.It is possible to create a mask consisting of the bitwise OR of two or more values (e.g.
fs.constants.W_OK | fs.constants.R_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 an
Error
object.The following examples check if
package.json
exists, and if it is readable or writable.`const file = 'package.json'; // Check if the file exists in the current directory. fs.access(file, fs.constants.F_OK, (err) => { console.log(\`${file} ${err ? 'does not exist' : 'exists'}\`); }); // Check if the file is readable. fs.access(file, fs.constants.R_OK, (err) => { console.log(\`${file} ${err ? 'is not readable' : 'is readable'}\`); }); // Check if the file is writable. fs.access(file, fs.constants.W_OK, (err) => { console.log(\`${file} ${err ? 'is not writable' : 'is writable'}\`); }); // Check if the file exists in the current directory, and if it is writable. fs.access(file, fs.constants.F_OK | fs.constants.W_OK, (err) => { if (err) { console.error( \`${file} ${err.code === 'ENOENT' ? 'does not exist' : 'is read-only'}\`); } else { console.log(\`${file} exists, and it is writable\`); } }); `.
Using
fs.access()
to check for the accessibility of a file before callingfs.open()
,fs.readFile()
orfs.writeFile()
is not recommended.Doing so introduces a race condition, since other processes may change the file's state between the two calls.
Instead, user code should open/read/write the file directly and handle the error raised if the file is not accessible.
`fs.access('myfile', (err) => { if (!err) { console.error('myfile already exists'); return; } fs.open('myfile', 'wx', (err, fd) => { if (err) throw err; writeMyData(fd); }); }); `. `fs.open('myfile', 'wx', (err, fd) => { if (err) { if (err.code === 'EEXIST') { console.error('myfile already exists'); return; } throw err; } writeMyData(fd); }); `. `fs.access('myfile', (err) => { if (err) { if (err.code === 'ENOENT') { console.error('myfile does not exist'); return; } throw err; } fs.open('myfile', 'r', (err, fd) => { if (err) throw err; readMyData(fd); }); }); `. `fs.open('myfile', 'r', (err, fd) => { if (err) { if (err.code === 'ENOENT') { console.error('myfile does not exist'); return; } throw err; } readMyData(fd); }); `.
The "not recommended" examples above check for accessibility and then use the file; the "recommended" examples are better because they use the file directly and handle the error, if any.
In general, check for the accessibility of a file only if the file will not be used directly, for example when its accessibility is a signal from another process.
On Windows, access-control policies (ACLs) on a directory may limit access to a file or directory.
The
fs.access()
function, however, does not check the ACL and therefore may report that a path is accessible even if the ACL restricts the user from reading or writing to it.
Parameters
Returns Future a future value
chmod
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1071 for the source function this function wraps. **
Wraps fs.chmod with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronously changes the permissions of a file.
No arguments other than a possible exception are given to the completion callback.
See also:
chmod(2)
.`fs.chmod('my_file.txt', 0o775, (err) => { if (err) throw err; console.log('The permissions for file "my_file.txt" have been changed!'); }); `.
The
mode
argument used in both thefs.chmod()
andfs.chmodSync()
methods is a numeric bitmask created using a logical OR of the following constants: ConstantOctalDescriptionfs.constants.S_IRUSR``0o400
read by ownerfs.constants.S_IWUSR``0o200
write by ownerfs.constants.S_IXUSR``0o100
execute/search by ownerfs.constants.S_IRGRP``0o40
read by groupfs.constants.S_IWGRP``0o20
write by groupfs.constants.S_IXGRP``0o10
execute/search by groupfs.constants.S_IROTH``0o4
read by othersfs.constants.S_IWOTH``0o2
write by othersfs.constants.S_IXOTH``0o1
execute/search by others.An easier method of constructing the
mode
is to use a sequence of three octal digits (e.g.
765
).The left-most digit (
7
in the example), specifies the permissions for the file owner.The middle digit (
6
in the example), specifies permissions for the group.The right-most digit (
5
in the example), specifies the permissions for others. NumberDescription7
read, write, and execute6
read and write5
read and execute4
read only3
write and execute2
write only1
execute only0
no permission.For example, the octal value
0o765
means:When using raw numbers where file modes are expected, any value larger than
0o777
may result in platform-specific behaviors that are not supported to work consistently.Therefore constants like
S_ISVTX
,S_ISGID
orS_ISUID
are not exposed infs.constants
.Caveats: on Windows only the write permission can be changed, and the distinction among the permissions of group, owner or others is not implemented.
Parameters
path
(string | Buffer | URL) -mode
number -The
owner may read, write and execute the fileThe
group may read and write the fileOthers
may read and execute the file
Returns Future a future value
fchmod
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1021 for the source function this function wraps. **
Wraps fs.fchmod with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
fchmod(2)
.No arguments other than a possible exception are given to the completion callback.
Parameters
Returns Future a future value
fstat
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L841 for the source function this function wraps. **
Wraps fs.fstat with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
fstat(2)
.The callback gets two arguments
(err, stats)
wherestats
is anfs.Stats
object.
fstat()
is identical tostat()
, except that the file to be stat-ed is specified by the file descriptorfd
.
Parameters
Returns Future a future value
lchmod
Wraps fs.lchmod with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
lchmod(2)
.No arguments other than a possible exception are given to the completion callback.
Only available on macOS.
Parameters
Returns Future a future value
link
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L980 for the source function this function wraps. **
Wraps fs.link with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
link(2)
.No arguments other than a possible exception are given to the completion callback.
Parameters
Returns Future a future value
mkdir
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L766 for the source function this function wraps. **
Wraps fs.mkdir with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronously creates a directory.
No arguments other than a possible exception are given to the completion callback.
The optional
options
argument can be an number specifying mode (permission and sticky bits), or an object with amode
property and arecursive
property indicating whether parent folders should be created.Calling
fs.mkdir()
whenpath
is a directory that exists results in an error only whenrecursive
is false.`// Creates /tmp/a/apple, regardless of whether \`/tmp\` and /tmp/a exist. fs.mkdir('/tmp/a/apple', { recursive: true }, (err) => { if (err) throw err; }); `.
On Windows, using
fs.mkdir()
on the root directory even with recursion will result in an error:`fs.mkdir('/', { recursive: true }, (err) => { // => [Error: EPERM: operation not permitted, mkdir 'C:\'] }); `.
See also:
mkdir(2)
.
Parameters
Returns Future a future value
rename
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L634 for the source function this function wraps. **
Wraps fs.rename with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronously rename file at
oldPath
to the pathname provided asnewPath
.In the case that
newPath
already exists, it will be overwritten.If there is a directory at
newPath
, an error will be raised instead.No arguments other than a possible exception are given to the completion callback.
See also:
rename(2)
.`fs.rename('oldFile.txt', 'newFile.txt', (err) => { if (err) throw err; console.log('Rename complete!'); }); `.
Parameters
Returns Future a future value
appendFile
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1270 for the source function this function wraps. **
Wraps fs.appendFile with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronously append data to a file, creating the file if it does not yet exist.
data
can be a string or aBuffer
.`fs.appendFile('message.txt', 'data to append', (err) => { if (err) throw err; console.log('The "data to append" was appended to file!'); }); `.
If
options
is a string, then it specifies the encoding:`fs.appendFile('message.txt', 'data to append', 'utf8', callback); `
The
path
may be specified as a numeric file descriptor that has been opened for appending (usingfs.open()
orfs.openSync()
).The file descriptor will not be closed automatically.
`fs.open('message.txt', 'a', (err, fd) => { if (err) throw err; fs.appendFile(fd, 'data to append', 'utf8', (err) => { fs.close(fd, (err) => { if (err) throw err; }); if (err) throw err; }); }); `.
Parameters
path
(string | Buffer | URL | number) filename or file descriptordata
(string | Buffer) -options
(Object | string) -
Returns Future a future value
chown
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1129 for the source function this function wraps. **
Wraps fs.chown with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronously changes owner and group of a file.
No arguments other than a possible exception are given to the completion callback.
See also:
chown(2)
.
Parameters
Returns Future a future value
copyFile
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1743 for the source function this function wraps. **
Wraps fs.copyFile with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Added in: v8.5.0
Asynchronously copies
src
todest
.By default,
dest
is overwritten if it already exists.No arguments other than a possible exception are given to the callback function.
Node.js makes no guarantees about the atomicity of the copy operation.
If an error occurs after the destination file has been opened for writing, Node.js will attempt to remove the destination.
flags
is an optional number that specifies the behavior of the copy operation.It is possible to create a mask consisting of the bitwise OR of two or more values (e.g.
fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE
).`const fs = require('fs'); // destination.txt will be created or overwritten by default. fs.copyFile('source.txt', 'destination.txt', (err) => { if (err) throw err; console.log('source.txt was copied to destination.txt'); }); `.
If the third argument is a number, then it specifies
flags
:`const fs = require('fs'); const { COPYFILE_EXCL } = fs.constants; // By using COPYFILE_EXCL, the operation will fail if destination.txt exists. fs.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL, callback); `.
Parameters
src
(string | Buffer | URL) source filename to copydest
(string | Buffer | URL) destination filename of the copy operationflags
number modifiers for copy operation Default: 0
Returns Future a future value
fchown
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1109 for the source function this function wraps. **
Wraps fs.fchown with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
fchown(2)
.No arguments other than a possible exception are given to the completion callback.
Parameters
Returns Future a future value
futimes
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1170 for the source function this function wraps. **
Wraps fs.futimes with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Change the file system timestamps of the object referenced by the supplied file descriptor.
See
fs.utimes()
.This function does not work on AIX versions before 7.1, it will return the error
UV_ENOSYS
.
Parameters
Returns Future a future value
lchown
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1090 for the source function this function wraps. **
Wraps fs.lchown with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
lchown(2)
.No arguments other than a possible exception are given to the completion callback.
Parameters
Returns Future a future value
symlink
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L921 for the source function this function wraps. **
Wraps fs.symlink with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Asynchronous
symlink(2)
.No arguments other than a possible exception are given to the completion callback.
The
type
argument is only available on Windows and ignored on other platforms.It can be set to
'dir'
,'file'
, or'junction'
.If the
type
argument is not set, Node will autodetecttarget
type and use'file'
or'dir'
.If the
target
does not exist,'file'
will be used.Windows junction points require the destination path to be absolute. When using
'junction'
, thetarget
argument will automatically be normalized to absolute path.Here is an example below:
`fs.symlink('./foo', './new-port', callback); `
It creates a symbolic link named "new-port" that points to "foo".
Parameters
Returns Future a future value
utimes
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1149 for the source function this function wraps. **
Wraps fs.utimes with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
Change the file system timestamps of the object referenced by
path
.The
atime
andmtime
arguments follow these rules:
Parameters
path
(string | Buffer | URL) -atime
(number | string | Date) -mtime
(number | string | Date) -Values
can be either numbers representing Unix epoch time, Dates, or aIf
the value can not be converted to a number, or is NaN, Infinity or
Returns Future a future value
writeFile
- **See: https://github.com/nodejs/node/blob/e6872f5f4bf7dc418bd77a3f2a911fb2c48e3df1/lib/fs.js#L1216 for the source function this function wraps. **
Wraps fs.writeFile with fluture so that instead of taking a callback it returns a Future. Unlike the raw function it wraps, this function now returns a Future which wraps a value indicating whether the operation succeeded.
via node API docs:
When
file
is a filename, asynchronously writes data to the file, replacing the file if it already exists.
data
can be a string or a buffer.When
file
is a file descriptor, the behavior is similar to callingfs.write()
directly (which is recommended).See the notes below on using a file descriptor.
The
encoding
option is ignored ifdata
is a buffer.`const data = new Uint8Array(Buffer.from('Hello Node.js')); fs.writeFile('message.txt', data, (err) => { if (err) throw err; console.log('The file has been saved!'); }); `.
If
options
is a string, then it specifies the encoding:`fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback); `
It is unsafe to use
fs.writeFile()
multiple times on the same file without waiting for the callback.For this scenario,
fs.createWriteStream()
is recommended.When
file
is a file descriptor, the behavior is almost identical to directly callingfs.write()
like:.`fs.write(fd, Buffer.from(data, options.encoding), callback); `
The difference from directly calling
fs.write()
is that under some unusual conditions,fs.write()
may write only part of the buffer and will need to be retried to write the remaining data, whereasfs.writeFile()
will retry until the data is entirely written (or an error occurs).The implications of this are a common source of confusion.
In the file descriptor case, the file is not replaced! The data is not necessarily written to the beginning of the file, and the file's original data may remain before and/or after the newly written data.
For example, if
fs.writeFile()
is called twice in a row, first to write the string'Hello'
, then to write the string', World'
, the file would contain'Hello, World'
, and might contain some of the file's original data (depending on the size of the original file, and the position of the file descriptor).If a file name had been used instead of a descriptor, the file would be guaranteed to contain only
', World'
.
Parameters
file
(string | Buffer | URL | number) filename or file descriptordata
(string | Buffer | TypedArray | DataView) -options
(Object | string) -
Returns Future a future value
Future
Type: Object
Properties
bimap
functionchain
functionfold
functionfork
functionmap
functionmapRej
functionpipe
functionswap
function It's a future
readAnyWithFormatOr
Parameters
Returns Future the first matching file which resolves
readAnyWithFormat
Parameters
Returns Future the first matching file which resolves
readAny
Parameters
Returns Future the first matching file which resolves
callbackToTheFuture
takes an arity and nodeback function and returns a future-returning function NB: arity in this case doesn't take the callback into the count so arity = 2 means a function with the shape (a, b, callback) => {}
Parameters
Examples
import fs from "fs"
import { callbackToTheFuture, fork } from "torpor/utils"
import { trace } from "xtrace"
const readFile = callbackToTheFuture(2, fs.readFile)
fork(trace("bad"), trace("good"), readFile("myfile.txt", "utf8"))
Returns Function Future-returning function
proxifyN
- **See: callbackToTheFuture **
takes an arity and nodeback function and returns a curried future-returning function NB: arity in this case doesn't take the callback into the count so arity = 2 means a function with the shape (a, b, callback) => {}
Parameters
Examples
import fs from "fs"
import { proxifyN, fork } from "torpor/utils"
import { trace } from "xtrace"
import { pipe, map, __ as $ } from "ramda"
const readFile = proxifyN(2, fs.readFile)
const utf8 = readFile($, "utf8")
pipe(map(JSON.parse), fork(trace("bad"))(trace("good")))(utf8("package.json"))
Returns Function curried Future-returning function