3.2.4 • Published 3 months ago

pwd-fs v3.2.4

Weekly downloads
137
License
MIT
Repository
github
Last release
3 months ago

Powered File System

License Build Status Build status Coverage Status Known Vulnerabilities

npm

This module expands the Node.js® module with the capabilities of declaring the pwd (present working directory) and recursive execution. By default all file system operations have asynchronous forms. API provides an alternative set of asynchronous file system methods that return Promise objects.

To improve reliability and maintainability the code is migrated to TypeScript.

Getting Started

Installation

To use Powered File System in your project, run:

npm install pwd-fs

Table of Contents

class PoweredFileSystem

The scope URI of the class methods are divided into groups.

URIMethods
Common (file and directory)chmod chown copy remove rename symlink stat test
File onlyread write
Directory onlymkdir readdir

class PoweredFileSystem

This class implemented by following the ECMAScript® 2018 Language Specification Standard.

constructor: new PoweredFileSystem(path)

String form paths are interpreted as UTF-8 character sequences identifying the absolute or relative filename.

import { pfs } from 'pwd-fs';

// pfs.pwd === process.cwd()

Relative paths will be resolved relative to the current working directory as specified by process.cwd():

import { PoweredFileSystem } from 'pwd-fs';

// pfs.pwd === `${process.cwd()}/foo/bar`

const pfs = new PoweredFileSystem('./foo/bar');

Absolute paths:

import { PoweredFileSystem } from 'pwd-fs';

// pfs.pwd === __dirname

const pfs = new PoweredFileSystem(__dirname);

pfs.test(src, options)

Tests a user's permissions for the file or directory specified by path.

const access = await pfs.test('./path');
console.log(test); // true

Function pfs.test() return only Promise.resolve()

The following flag are meant for use with pfs.test().

FlagDescription
'e'Source is visible
'r'Permitted can be read
'w'Permitted can be written
'x'Permitted can be executed. This has no effect on Windows system (will behave like e).

pfs.stat(src, options)

These functions return information about a resource in the file system.

pfs.chmod(src, mode, options)

Asynchronously changes the permissions of a file.

import { bitmask } from 'pwd-fs';

await pfs.chmod('./path', 0o750);
const { mode } = await pfs.stat('./path');

console.log(bitmask(mode) === 0o750); // true

Caveats: on Windows only the write permission can be changed, and the distinction among the permissions of group, owner or others is not implemented.

See manuals chmod(2)

pfs.chown(src, , options)

Asynchronously changes owner and group of a file. See manuals chown(2).

pfs.symlink(src, use, options)

Asynchronously creates a new symbolic link (also known as a soft link) may point to an existing file or to a nonexistent one.

await pfs.symlink('./path', './link');
const stats = await pfs.stat('./link');

console.log(stats.isSymbolicLink()); // true

See manuals symlink(2).

pfs.copy(src, dir, options)

Asynchronously recursively copy a file or directory.

import { pfs } from 'pwd-fs';

await pfs.copy('./path/file.txt', './dist');

pfs.rename(src, use, options)

Rename file or directory. See manuals rename(2).

await pfs.rename('./path/old_name.txt', './path/new_name.txt');

pfs.remove(src, options)

Asynchronously recursively remove a file or directory. Will be resolve if the directory already not exists.

pfs.read(src, options)]

Asynchronously reads the entire contents of a file.

const content = await pfs.read('./file.txt');
console.log(content); // 'Lorem Ipsum...'

pfs.write(src, data, options)

Asynchronously writes data to a file, replacing the file if it already exists. if the file does not exist, it will create a new one. The encoding option is ignored if data is a buffer.

await pfs.write('./file.txt', '... some text');

This function is limited to writing only string. For stream, fs.createWriteStream() is recommended.

pfs.append(src, data, options) deprecated

Asynchronously append data to a file, creating the file if it does not yet exist.

NOTE Method is deprecated. May be removed in the next major version

Use instead pfs.write(src, data[, options]) with { flag: 'a' } option

await pfs.write('./file', 'some content', {
  flag: 'a'
});

pfs.readdir(dir, options

Asynchronous reads the contents of a directory. The Gets an [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of the names of the files in the directory excluding '.' and '..'. Returns an empty Array if the directory is empty. See manuals readdir(3).

const list = await pfs.readdir('./files');
console.log(list); // ["icons", "logo.svg"]

pfs.mkdir(dir, options)

Recursive directory creation. Will be resolve if the directory already exists.

await pfs.mkdir('./static/images');

pfs.pwd

The full path from the root directory to the present working directory: in the context of which relative paths will be resolved.

static: bitmask(mode)

Masking is the act of applying a mask to a value. Bitwise ANDing in order to extract a subset of the bits in the value.

import { bitmask } from 'pwd-fs';

// Access: (0644/-rw-r--r--)
const { mode } = await pfs.stat('./things.txt');
const access = bitmask(mode);

console.log(access === 0o644); // true

Applying the mask to the value means that we want to clear the first (higher) 4 bits, and keep the last (lower) 4 bits. Thus we have extracted the lower 4 bits. The result is:

mode:   33188
mask:   0o644 (rw-rw-r--)

Mode creation mask

The following table shows some examples of how to set the extension mode or umask for files and directories.

UmaskMode filesMode directories
0o0000o666 (rw-rw-rw-)0o777 (rwxrwxrwx)
0o0020o664 (rw-rw-r--)0o775 (rwxrwxr-x)
0o0070o660 (rw-rw----)0o770 (rwxrwx---)
0o0220o644 (rw-r--r--)0o755 (rwxr-xr-x)
0o0270o640 (rw-r-----)0o750 (rwxr-x---)
0o0770o600 (rw-------)0o700 (rwx------)
0o2770o400 (r--------)0o500 (r-x------)

String encoding

The following encoding are available wherever the encoding option takes a [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).

EncodingDescription
'ascii'Each alphabetic, numeric or special character is represented by a 7-bit binary number (a string of seven 0 or 1), which is assigned a number from 0 to 127.
'base64'Three 8-bit bytes (i.e., a total of 24 bits) can be represented by four 6-bit digits. The full specification of this form is contained in IANA RFC 1421 and RFC 2045.
'hex'Encode each byte as two hexadecimal characters.
'ucs22 or 4 bytes, little-endian encoded Unicode characters. Surrogate pairs (U+10000 to U+10FFFF) are supported.
'utf16le'Like 'ucs2.
'utf8'Multibyte encoded Unicode characters. The first 128 characters of Unicode, which correspond one-to-one with ascii, are encoded using a single octet with the same binary value as ascii, so that valid ascii text is valid utf8-encoded Unicode as well.
'latin1'Defined by the IANA in RFC1345, only in node 6.4.0+.
'binary'Like 'latin1.

File system flags

The following flags are available for pfs.read and pfs.write the flag option takes a [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).

FlagDescription
'a'Open file for appending. The file is created if it does not exist.
'ax'Like 'a' but fails if the path exists.
'a+'Open file for reading and appending. The file is created if it does not exist.
'ax+'Like 'a+' but fails if the path exists.
'as'Open file for appending in synchronous mode. The file is created if it does not exist.
'as+'Open file for reading and appending in synchronous mode. The file is created if it does not exist.
'r'Open file for reading. An exception occurs if the file does not exist.
'r+'Open file for reading and writing. An exception occurs if the file does not exist.
'rs+'Open file for reading and writing in synchronous mode. Instructs the operating system to bypass the local file system cache. Using this flag is not recommended unless it is needed.
'w'Open file for writing. The file is created (if it does not exist) or truncated (if it exists).
'wx'Like 'w' but fails if the path exists.
'w+'Open file for reading and writing. The file is created (if it does not exist) or truncated (if it exists).
'wx+'Like 'w+' but fails if the path exists.

The behavior of some flags are platform-specific.

umaskteststatchmodchownsymlinkcopyrenameremovereadwritereaddirmkdir
@infinitebrahmanuniverse/nolb-pw@everything-registry/sub-chunk-2497nanma@schalltech/honeycomb-cli@thantrik/nanmafwa
3.2.4

3 months ago

3.2.2

7 months ago

3.2.1

7 months ago

3.2.0

7 months ago

3.2.3

7 months ago

3.1.4

7 months ago

3.1.3

7 months ago

2.3.0

2 years ago

2.4.1

2 years ago

2.4.2

2 years ago

2.2.0

4 years ago

2.1.11

4 years ago

2.1.10

4 years ago

2.1.6

4 years ago

2.1.5

4 years ago

2.1.8

4 years ago

2.1.7

4 years ago

2.1.9

4 years ago

2.1.4

4 years ago

2.1.3

4 years ago

2.1.1

4 years ago

2.0.1

4 years ago

2.0.0

4 years ago

1.3.0

4 years ago

1.2.14

4 years ago

1.2.13

5 years ago

1.2.12

6 years ago

1.1.11

6 years ago

1.1.10

6 years ago

1.0.9

6 years ago

1.0.8

6 years ago

1.0.7

6 years ago

1.0.6

6 years ago

1.0.5

6 years ago

1.0.4

6 years ago

1.0.3

6 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago