npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

torpor

v0.1.0

Published

lazy and monadic file systems

Downloads

9

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

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

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

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

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