❤
npm
Sign UpSign In

torpor

0.1.0 • Public • Published 
██████████████████████████████████████
██████████████████████████████████████
██████████████████████████████████████
██  ██████████████████████████████████
█    ██   ██  █   █    ███   ██  █   █
██  ██     █   █  █     █     █   █  █
██  ██  █  █  █████  █  █  █  █  █████
██  ██  █  █  █████  █  █  █  █  █████
██  ██  █  █  █████  █  █  █  █  █████
██   ██   ██  █████    ███   ██  █████
███████████████████  █████████████████
███████████████████  █████████████████
███████████████████  █████████████████
██████████████████████████████████████
██████████████████████████████████████

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

It's a TypedArray

Type: Object

chainRej

It's a Future!

Type: Object

close

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

Returns Future a future value

fdatasync

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

Returns Future a future value

fsync

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

Returns Future a future value

rmdir

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 an ENOENT error on Windows and an ENOTDIR error on POSIX.

Parameters

Returns Future a future value

unlink

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

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. The mode 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 calling fs.open(), fs.readFile() or fs.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

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 the fs.chmod() and fs.chmodSync() methods is a numeric bitmask created using a logical OR of the following constants: ConstantOctalDescriptionfs.constants.S_IRUSR``0o400read by ownerfs.constants.S_IWUSR``0o200write by ownerfs.constants.S_IXUSR``0o100execute/search by ownerfs.constants.S_IRGRP``0o40read by groupfs.constants.S_IWGRP``0o20write by groupfs.constants.S_IXGRP``0o10execute/search by groupfs.constants.S_IROTH``0o4read by othersfs.constants.S_IWOTH``0o2write by othersfs.constants.S_IXOTH``0o1execute/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. NumberDescription7read, write, and execute6read and write5read and execute4read only3write and execute2write only1execute only0no 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 or S_ISUID are not exposed in fs.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 file
  • The group may read and write the file
  • Others may read and execute the file

Returns Future a future value

fchmod

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

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) where stats is an fs.Stats object.

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

Parameters

  • fd number -
  • options Object -
    • options.bigint boolean Whether the numeric values in the returned

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

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

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 a mode property and a recursive property indicating whether parent folders should be created.

Calling fs.mkdir() when path is a directory that exists results in an error only when recursive 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

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 as newPath.

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

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 a Buffer.

`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 (using fs.open() or fs.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

Returns Future a future value

chown

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

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 to dest.

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

Returns Future a future value

fchown

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

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

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

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 autodetect target 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', the target 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

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 and mtime 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 a
  • If the value can not be converted to a number, or is NaN, Infinity or

Returns Future a future value

writeFile

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 calling fs.write() directly (which is recommended).

See the notes below on using a file descriptor.

The encoding option is ignored if data 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 calling fs.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, whereas fs.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

Returns Future a future value

Future

Type: Object

Properties

readAnyWithFormatOr

Parameters

  • def any default
  • format string probably utf8?
  • sources Array<string> a list of possible file sources

Returns Future the first matching file which resolves

readAnyWithFormat

Parameters

Returns Future the first matching file which resolves

readAny

Parameters

  • sources Array<string> a list of possible file sources

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

Readme

Keywords

none

Package Sidebar

Install

npm i torpor

Weekly Downloads

0

Version

0.1.0

License

ISC

Unpacked Size

145 kB

Total Files

5

Last publish

Collaborators

  • brekk
Try on RunKit
Report malware