Nimble Pirate Monitor

    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

    Keywords

    none

    Install

    npm i torpor

    DownloadsWeekly Downloads

    8

    Version

    0.1.0

    License

    ISC

    Unpacked Size

    145 kB

    Total Files

    5

    Last publish

    Collaborators

    • brekk