pwd-fs 3.5.0 → 3.5.5

package/readme.md

@@ -1,591 +1,438 @@
-# pwd-fs
+# Powered File System
 
-[![License](https://img.shields.io/npm/l/pwd-fs)](https://github.com/woodger/pwd-fs/blob/master/LICENSE)
-[![CI](https://github.com/woodger/pwd-fs/actions/workflows/ci.yml/badge.svg)](https://github.com/woodger/pwd-fs/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/pwd-fs.svg)](https://www.npmjs.com/package/pwd-fs)
+[![node](https://img.shields.io/node/v/pwd-fs.svg)](https://www.npmjs.com/package/pwd-fs)
+[![types](https://img.shields.io/npm/types/pwd-fs.svg)](https://www.npmjs.com/package/pwd-fs)
+[![license](https://img.shields.io/npm/l/pwd-fs.svg)](LICENSE)
 
-`pwd-fs` is a path-aware wrapper around Node.js file system APIs.
+This module extends the [Node.js®](https://nodejs.org) file system API with a declared `pwd` (working directory) and recursive execution helpers. By default, all file system operations have asynchronous forms. The API provides an alternative set of asynchronous file system methods that return `Promise` objects.
 
-It provides:
+## Getting Started
 
-- a dedicated working directory per instance
-- Promise-based async methods
-- matching synchronous variants via `{ sync: true }`
-- recursive helpers for copy, remove, chmod, chown, and mkdir
+### Installation
 
-Relative paths are resolved against `pfs.pwd`. Absolute paths are used as-is, so `pfs.pwd` is a convenience base path, not a sandbox.
-
-## Why Use It
-
-Use `pwd-fs` when you want file system operations to be rooted at a specific working directory without manually calling `path.resolve()` before every operation.
-
-It is especially useful for:
-
-- CLI tools that operate inside a project root
-- build or code generation scripts
-- isolated test fixtures
-- small automation tasks that need Promise-based file system helpers
-
-## Installation
+To use `Powered File System` in your project, run:
 
 ```bash
 npm install pwd-fs
 ```
 
-## Table of Contents
-
-- [Quick Start](#quick-start)
-- [Common Recipes](#common-recipes)
-- [Compatibility](#compatibility)
-- [Exports](#exports)
-- [API](#api)
-- [`new PoweredFileSystem(pwd?)`](#new-poweredfilesystempwd)
-- [`pfs.pwd`](#pfspwd)
-- [`pfs.resolve(src)`](#pfsresolvesrc)
-- [`pfs.constants`](#pfsconstants)
-- [`PoweredFileSystem.bitmask(mode)`](#poweredfilesystembitmaskmode)
-- [`pfs.test(src, options?)`](#pfstestsrc-options)
-- [`pfs.stat(src, options?)`](#pfsstatsrc-options)
-- [`pfs.chmod(src, mode, options?)`](#pfschmodsrc-mode-options)
-- [`pfs.chown(src, options?)`](#pfschownsrc-options)
-- [`pfs.symlink(src, dest, options?)`](#pfssymlinksrc-dest-options)
-- [`pfs.copy(src, dest, options?)`](#pfscopysrc-dest-options)
-- [`pfs.rename(src, dest, options?)`](#pfsrenamesrc-dest-options)
-- [`pfs.remove(src, options?)`](#pfsremovesrc-options)
-- [`pfs.emptyDir(src, options?)`](#pfsemptydirsrc-options)
-- [`pfs.read(src, options?)`](#pfsreadsrc-options)
-- [`pfs.write(src, data, options?)`](#pfswritesrc-data-options)
-- [`pfs.append(src, data, options?)`](#pfsappendsrc-data-options)
-- [`pfs.readdir(dir, options?)`](#pfsreaddirdir-options)
-- [`pfs.readlink(src, options?)`](#pfsreadlinksrc-options)
-- [`pfs.realpath(src, options?)`](#pfsrealpathsrc-options)
-- [`pfs.mkdir(dir, options?)`](#pfsmkdirdir-options)
-- [Sync Mode](#sync-mode)
-- [Error Behavior](#error-behavior)
-- [Umask Behavior](#umask-behavior)
-- [Notes](#notes)
-- [Platform Caveats](#platform-caveats)
-- [When To Use Native `fs`](#when-to-use-native-fs)
-- [Development](#development)
-- [License](#license)
-
-## Quick Start
+#### Table of Contents
 
-```ts
-import { pfs } from 'pwd-fs';
+[class PoweredFileSystem](#class-poweredfilesystem)
 
-await pfs.mkdir('./own/project'); // recursively create the directory
-```
+* [constructor: new PoweredFileSystem([path])](#constructor-new-poweredfilesystempath)
+* [pfs.test(src[, options])](#pfstestsrc-options)
+* [pfs.stat(src[, options])](#pfsstatsrc-options)
+* [pfs.chmod(src, mode[, options])](#pfschmodsrc-mode-options)
+* [pfs.chown(src[, options])](#pfschownsrc-options)
+* [pfs.symlink(src, dest[, options])](#pfssymlinksrc-dest-options)
+* [pfs.copy(src, dir[, options])](#pfscopysrc-dir-options)
+* [pfs.rename(src, dest[, options])](#pfsrenamesrc-dest-options)
+* [pfs.remove(src[, options])](#pfsremovesrc-options)
+* [pfs.emptyDir(src[, options])](#pfsemptydirsrc-options)
+* [pfs.read(src[, options])](#pfsreadsrc-options)
+* [pfs.write(src, data[, options])](#pfswritesrc-data-options)
+* [pfs.append(src, data[, options])](#pfsappendsrc-data-options)
+* [pfs.readdir(dir[, options])](#pfsreaddirdir-options)
+* [pfs.readlink(src[, options])](#pfsreadlinksrc-options)
+* [pfs.realpath(src[, options])](#pfsrealpathsrc-options)
+* [pfs.mkdir(dir[, options])](#pfsmkdirdir-options)
+* [pfs.pwd](#pfspwd)
+* [static: bitmask(mode)](#static-bitmaskmode)
 
-## Common Recipes
+The class methods are divided into resource groups.
 
-### Work inside a project directory
+| Resource                    | Methods                                                          |
+|-----------------------------|------------------------------------------------------------------|
+| Common (file and directory) | `chmod` `chown` `copy` `realpath` `remove` `rename` `stat` `test` |
+| File only                   | `append` `read` `write`                                           |
+| Directory only              | `emptyDir` `mkdir` `readdir`                                      |
+| Link only                   | `readlink` `symlink`                                              |
 
-```ts
-import { PoweredFileSystem } from 'pwd-fs';
 
-const projectFs = new PoweredFileSystem('/workspace/my-project');
+#### class PoweredFileSystem
 
-await projectFs.write('./.cache/build.txt', 'ok');
-const exists = await projectFs.test('./.cache/build.txt');
-```
+This class is implemented in TypeScript and follows [Node.js](https://nodejs.org) file system semantics.
 
-### Copy assets into a build directory
+#### constructor: new PoweredFileSystem([path])
 
-```ts
-await pfs.mkdir('./dist');
-await pfs.copy('./assets', './dist');
-```
-
-Result:
-
-- source: `./assets`
-- destination directory: `./dist`
-- created output: `./dist/assets`
+- `path` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative directory name. `path` sets the `pfs.pwd` value. By default, it is [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd).
 
-### Empty a directory but keep it
+String paths are interpreted as UTF-8 character sequences identifying absolute or relative file names.
 
 ```ts
-await pfs.emptyDir('./cache');
+import { pfs } from 'pwd-fs';
+
+// pfs.pwd === process.cwd()
 ```
 
-### Resolve a symlink target
+Relative paths will be resolved relative to the current working directory as specified by `process.cwd()`:
 
 ```ts
-const target = await pfs.readlink('./current');
-const resolved = await pfs.realpath('./current');
-```
+import { PoweredFileSystem } from 'pwd-fs';
 
-### Append to a file
+// pfs.pwd === `${process.cwd()}/foo/bar`
 
-```ts
-await pfs.write('./app.log', 'first line\n');
-await pfs.write('./app.log', 'second line\n', { flag: 'a' });
+const pfs = new PoweredFileSystem('./foo/bar');
 ```
 
-### Read a file as a buffer
+Absolute paths:
 
 ```ts
-const raw = await pfs.read('./archive.bin', { encoding: null });
-```
+import { PoweredFileSystem } from 'pwd-fs';
 
-### Remove a temporary directory recursively
+// pfs.pwd === __dirname
 
-```ts
-if (await pfs.test('./tmp')) {
-  await pfs.remove('./tmp');
-}
+const pfs = new PoweredFileSystem(__dirname);
 ```
 
-## Compatibility
+#### pfs.test(src[, options])
 
-- package `engines`: Node.js `>=18`
-- module format: CommonJS package output with TypeScript declarations
-- platform notes:
-  - `chown()` is effectively a no-op on Windows apart from path validation
-  - `chmod()` behavior on Windows is limited by the platform
-  - `x` access checks in `test()` do not have the same meaning on Windows as on Unix-like systems
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `flag` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Is an optional string that specifies the accessibility checks to be performed. **Default:** `'e'`.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with a `boolean`.
 
-## Exports
+Tests a user's permissions for the file or directory specified by path.
 
 ```ts
-import PoweredFileSystem, { pfs, bitmask } from 'pwd-fs';
+const access = await pfs.test('./path');
+console.log(access); // true
 ```
+> Function `pfs.test()` resolves with `false` for access errors instead of rejecting.
 
-- `default`: `PoweredFileSystem`
-- `pfs`: default instance rooted at `process.cwd()`
-- `bitmask(mode)`: helper that extracts standard permission bits from `fs.Stats.mode`
-
-## API
-
-### `new PoweredFileSystem(pwd?)`
+The following `flag` values are meant for use with `pfs.test()`.
 
-Creates a new instance with `pwd` as the base directory for relative paths.
+Flag | Description
+-----|-------------
+`'e'` | Source exists
+`'r'` | Source can be read
+`'w'` | Source can be written
+`'x'` | Source can be executed. This has no effect on Windows system (will behave like `e`).
 
-- `pwd?: string`
-- default: `process.cwd()`
-
-```ts
-import { PoweredFileSystem } from 'pwd-fs';
+#### pfs.stat(src[, options])
 
-const pfs = new PoweredFileSystem('./workspace');
-```
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `fs.Stats`.
 
-### `pfs.pwd`
+These functions return `lstat` information about a resource in the file system. Symbolic links are reported as links instead of followed targets.
 
-Absolute base directory used to resolve relative paths.
+#### pfs.chmod(src, mode[, options])
 
-### `pfs.resolve(src)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `mode` <[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> Is a numeric `bitmask` created using a logical `OR`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-Resolves `src` against `pfs.pwd`.
+Asynchronously changes the permissions of a file or directory tree.
 
 ```ts
-const pfs = new PoweredFileSystem('/workspace/project');
-const file = pfs.resolve('./src/index.ts');
-```
+import { bitmask } from 'pwd-fs';
 
-Absolute paths are preserved:
+await pfs.chmod('./path', 0o750);
+const { mode } = await pfs.stat('./path');
 
-```ts
-pfs.resolve('/tmp/outside.txt'); // '/tmp/outside.txt'
+console.log(bitmask(mode) === 0o750); // true
 ```
 
-### `pfs.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.
 
-Access mode aliases used by `pfs.test()`:
+See manuals [chmod(2)](http://man7.org/linux/man-pages/man2/chmod.2.html)
 
-- `e`: existence
-- `r`: readable
-- `w`: writable
-- `x`: executable
+#### pfs.chown(src[, options])
 
-### `PoweredFileSystem.bitmask(mode)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+  - `uid` <[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> The file's new owner's user id.
+  - `gid` <[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> The file's new group's group id.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-Static alias for `bitmask(mode)`.
+Asynchronously changes owner and group of a file or directory tree.
+If `uid` or `gid` is omitted, the current value is preserved. On Windows, `chown()` validates the path but does not change POSIX ownership.
+See manuals [chown(2)](http://man7.org/linux/man-pages/man2/chown.2.html).
 
-```ts
-const { mode } = await pfs.stat('./file.txt');
-const permissions = PoweredFileSystem.bitmask(mode);
-```
+#### pfs.symlink(src, dest[, options])
 
-### `pfs.test(src, options?)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `dest` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the symbolic link to create. If `dest` exists, it will not be overwritten.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-Checks whether a path is accessible.
+Asynchronously creates a new symbolic link (also known as a soft link).
 
 ```ts
-test<T extends boolean = false>(
-  src: string,
-  options?: { sync?: T; flag?: 'e' | 'r' | 'w' | 'x' }
-): T extends true ? boolean : Promise<boolean>
-```
+await pfs.symlink('./path', './link');
+const stats = await pfs.stat('./link');
 
-- `src`: absolute or instance-relative path
-- `flag`: access check to perform
-- default flag: `'e'`
-
-```ts
-const exists = await pfs.test('./notes.txt');
-const writable = pfs.test('./notes.txt', { sync: true, flag: 'w' });
+console.log(stats.isSymbolicLink()); // true
 ```
 
-### `pfs.stat(src, options?)`
-
-Returns `fs.lstat()` information for a path.
-
-```ts
-stat<T extends boolean = false>(
-  src: string,
-  options?: { sync?: T }
-): T extends true ? Stats : Promise<Stats>
-```
+See manuals [symlink(2)](http://man7.org/linux/man-pages/man2/symlink.2.html).
 
-This method uses `lstat`, so symbolic links are reported as links instead of followed targets.
+#### pfs.copy(src, dir[, options])
 
-### `pfs.chmod(src, mode, options?)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `dir` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the directory to which the resource is to be copied.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `umask` <[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> Umask or file [mode creation mask](#mode-creation-mask) is a grouping of bits, each of which restricts how its corresponding permission is set for newly created files or directories. See manuals [umask(2)](http://man7.org/linux/man-pages/man2/umask.2.html). Not supported on Windows system. **Default:** `0o000`.
+  - `overwrite` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Replace an existing target before copying. **Default:** `false`.
+  - `filter` <[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)> Optional `(src, dest) => boolean` predicate. Return `false` to skip a resource.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-Recursively applies permissions to a file or directory tree.
+Asynchronously copies a file or directory recursively into `dir`. The destination directory must exist. The created target is `path.join(dir, path.basename(src))`.
 
 ```ts
-chmod<T extends boolean = false>(
-  src: string,
-  mode: number,
-  options?: { sync?: T }
-): T extends true ? void : Promise<void>
-```
+import { pfs } from 'pwd-fs';
 
-```ts
-await pfs.chmod('./build', 0o755);
+await pfs.mkdir('./dist');
+await pfs.copy('./path/file.txt', './dist');
 ```
 
-Note: on Windows, permission handling is limited by platform behavior.
+#### pfs.rename(src, dest[, options])
 
-### `pfs.chown(src, options?)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `dest` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative destination path in the file system.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-Recursively applies ownership to a file or directory tree.
+Rename file or directory. See manuals [rename(2)](http://man7.org/linux/man-pages/man2/rename.2.html).
 
 ```ts
-chown<T extends boolean = false>(
-  src: string,
-  options?: { sync?: T; uid?: number; gid?: number }
-): T extends true ? void : Promise<void>
+await pfs.rename('./path/old_name.txt', './path/new_name.txt');
 ```
 
-- `uid` and `gid` default to `0`
-- when `uid` or `gid` is `0`, the current value from the source entry is preserved
-- on Windows, ownership changes are not performed, but path validation still happens
-
-### `pfs.symlink(src, dest, options?)`
+#### pfs.remove(src[, options])
 
-Creates a symbolic link from `dest` to `src`.
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-```ts
-symlink<T extends boolean = false>(
-  src: string,
-  dest: string,
-  options?: { sync?: T }
-): T extends true ? void : Promise<void>
-```
+Asynchronously removes a file or directory recursively. Missing paths reject or throw, matching `fs.rm(..., { force: false })`.
 
-```ts
-await pfs.symlink('./target.txt', './target-link.txt');
-```
+#### pfs.emptyDir(src[, options])
 
-### `pfs.copy(src, dest, options?)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the directory in the file system. Relative paths are resolved against `pfs.pwd`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-Copies `src` into the destination directory.
+Asynchronously removes all entries inside a directory while preserving the directory itself.
 
 ```ts
-copy<T extends boolean = false>(
-  src: string,
-  dest: string,
-  options?: {
-    sync?: T;
-    umask?: number;
-    overwrite?: boolean;
-    filter?: (src: string, dest: string) => boolean;
-  }
-): T extends true ? void : Promise<void>
+await pfs.emptyDir('./cache');
 ```
 
-Behavior:
+#### pfs.read(src[, options])
 
-- copying a file creates `dest/<basename(src)>`
-- copying a directory creates `dest/<basename(src)>` recursively
-- the target must not already exist
-- `overwrite: true` replaces an existing target entry with the same basename
-- `filter()` can skip specific source entries during the copy
-
-```ts
-await pfs.copy('./assets', './dist');
-```
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `encoding` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | <[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null)> Is the expected [string encoding](#string-encoding). **Default:** `'utf8'`.
+  - `flag` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> See support of [file system flags](#file-system-flags). **Default:** `'r'`.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with a `string`. If `encoding` is <[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null)>, the data is returned as a <[Buffer](https://nodejs.org/api/buffer.html)> object.
 
-This creates `./dist/assets`, not a direct rename to `./dist`.
+Asynchronously reads the entire contents of a file.
 
 ```ts
-await pfs.copy('./assets', './dist', {
-  overwrite: true,
-  filter: (src) => !src.endsWith('.map')
-});
+const content = await pfs.read('./file.txt');
+console.log(content); // 'Lorem Ipsum...'
 ```
 
-### `pfs.rename(src, dest, options?)`
-
-Renames or moves a file system entry.
-
-```ts
-rename<T extends boolean = false>(
-  src: string,
-  dest: string,
-  options?: { sync?: T }
-): T extends true ? void : Promise<void>
-```
+#### pfs.write(src, data[, options])
 
-### `pfs.remove(src, options?)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `data` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | <[Buffer](https://nodejs.org/api/buffer.html)>
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `umask` <[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> Umask or file [mode creation mask](#mode-creation-mask) is a grouping of bits, each of which restricts how its corresponding permission is set for newly created files or directories. See manuals [umask(2)](http://man7.org/linux/man-pages/man2/umask.2.html). Not supported on Windows system. **Default:** `0o000`.
+  - `encoding` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Is the expected [string encoding](#string-encoding). **Default:** `'utf8'`.
+  - `flag` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> See support of [file system flags](#file-system-flags). **Default:** `'w'`.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-Removes a file, directory, or symbolic link.
+Asynchronously writes `data` to a file, replacing the file if it already exists. If the file does not exist, a new file is created.
+The encoding option is ignored if data is a buffer.
 
 ```ts
-remove<T extends boolean = false>(
-  src: string,
-  options?: { sync?: T }
-): T extends true ? void : Promise<void>
+await pfs.write('./file.txt', '... some text');
 ```
 
-Behavior:
+> For `stream`, `fs.createWriteStream()` is recommended.
 
-- directories are removed recursively
-- symbolic links are unlinked without deleting the target
+#### pfs.append(src, data[, options])
 
-### `pfs.emptyDir(src, options?)`
 
-Removes all entries inside a directory while preserving the directory itself.
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `data` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | <[Buffer](https://nodejs.org/api/buffer.html)>
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `umask` <[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> Umask or file [mode creation mask](#mode-creation-mask) is a grouping of bits, each of which restricts how its corresponding permission is set for newly created files or directories. See manuals [umask(2)](http://man7.org/linux/man-pages/man2/umask.2.html). Not supported on Windows system. **Default:** `0o000`.
+  - `encoding` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Is the expected [string encoding](#string-encoding). **Default:** `'utf8'`.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-```ts
-emptyDir<T extends boolean = false>(
-  src: string,
-  options?: { sync?: T }
-): T extends true ? void : Promise<void>
-```
-
-```ts
-await pfs.emptyDir('./tmp');
-```
+Asynchronously appends data to a file, creating the file if it does not yet exist.
 
-### `pfs.read(src, options?)`
+> NOTE Method is deprecated. May be removed in the next major version
 
-Reads a file.
+**Use instead [pfs.write(src, data[, options])](#pfswritesrc-data-options) with { flag: 'a' } option**
 
 ```ts
-read<T extends boolean = false>(
-  src: string,
-  options?: {
-    sync?: T;
-    encoding?: BufferEncoding | null;
-    flag?: string;
-  }
-): T extends true ? string | Buffer : Promise<string | Buffer>
+await pfs.write('./file', 'some content', {
+  flag: 'a'
+});
 ```
 
-- default `encoding`: `'utf8'`
-- use `encoding: null` to get a `Buffer`
-- default `flag`: `'r'`
-
-```ts
-const text = await pfs.read('./file.txt');
-const buffer = pfs.read('./file.txt', { sync: true, encoding: null });
-```
+#### pfs.readdir(dir[, options])
 
-### `pfs.write(src, data, options?)`
+- `dir` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the directory you want to read.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `encoding` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> | <[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null)> Is the expected [string encoding](#string-encoding). **Default:** `'utf8'`.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with an `Array` of file names in the directory excluding `'.'` and `'..'`. If `encoding` is <[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null)>, entries are returned as <[Buffer](https://nodejs.org/api/buffer.html)> objects. Otherwise, entries are strings.
 
-Writes a file and explicitly reapplies the computed mode.
+Asynchronously reads the contents of a directory. Returns an empty `Array` if the directory is empty. See manuals [readdir(3)](http://man7.org/linux/man-pages/man3/readdir.3.html).
 
 ```ts
-write<T extends boolean = false>(
-  src: string,
-  data: Buffer | string,
-  options?: {
-    sync?: T;
-    encoding?: BufferEncoding | null;
-    umask?: number;
-    flag?: string;
-  }
-): T extends true ? void : Promise<void>
+const list = await pfs.readdir('./files');
+console.log(list); // ["icons", "logo.svg"]
 ```
 
-- default `encoding`: `'utf8'`
-- default `umask`: `0o000`
-- default `flag`: `'w'`
-- use `flag: 'a'` to append
-- any valid Node.js string file flag is accepted, such as `'r'`, `'w'`, `'a'`, `'wx'`, or `'a+'`
-
-```ts
-await pfs.write('./report.txt', 'generated output');
-await pfs.write('./report.txt', '\nnext line', { flag: 'a' });
-```
+#### pfs.readlink(src[, options])
 
-### `pfs.append(src, data, options?)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the symbolic link in the file system. Relative paths are resolved against `pfs.pwd`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `encoding` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Is the expected [string encoding](#string-encoding). **Default:** `'utf8'`.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with a `string`.
 
-Deprecated wrapper around `write(..., { flag: 'a' })`.
+Asynchronously reads the path stored in a symbolic link.
 
 ```ts
-append<T extends boolean = false>(
-  src: string,
-  data: Buffer | string,
-  options?: {
-    sync?: T;
-    encoding?: BufferEncoding | null;
-    umask?: number;
-  }
-): T extends true ? void : Promise<void>
+const target = await pfs.readlink('./current');
+console.log(target); // "./releases/current"
 ```
 
-Prefer:
+#### pfs.realpath(src[, options])
 
-```ts
-await pfs.write('./file.txt', 'content', { flag: 'a' });
-```
-
-### `pfs.readdir(dir, options?)`
+- `src` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the resource in the file system. Relative paths are resolved against `pfs.pwd`.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `encoding` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Is the expected [string encoding](#string-encoding). **Default:** `'utf8'`.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with a `string`.
 
-Reads a directory and returns entry names.
+Asynchronously resolves a path to its canonical absolute location.
 
 ```ts
-readdir<T extends boolean = false>(
-  dir: string,
-  options?: { sync?: T; encoding?: BufferEncoding | null }
-): T extends true ? string[] : Promise<string[]>
+const realpath = await pfs.realpath('./current');
+console.log(realpath); // "/absolute/path/to/releases/current"
 ```
 
-- default `encoding`: `'utf8'`
+#### pfs.mkdir(dir[, options])
 
-### `pfs.readlink(src, options?)`
+- `dir` <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)> Absolute or relative path to the directory you want to create.
+- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>
+  - `umask` <[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)> Umask or file [mode creation mask](#mode-creation-mask) is a grouping of bits, each of which restricts how its corresponding permission is set for newly created files or directories. See manuals [umask(2)](http://man7.org/linux/man-pages/man2/umask.2.html). Not supported on Windows system. **Default:** `0o000`.
+  - `sync` <[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)> Synchronous execution. **Default:** `false`.
+- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)> Resolves with `undefined`.
 
-Reads the stored target path from a symbolic link.
+Recursively creates directories. Resolves successfully if the directory already exists.
 
 ```ts
-readlink<T extends boolean = false>(
-  src: string,
-  options?: { sync?: T; encoding?: BufferEncoding }
-): T extends true ? string : Promise<string>
+await pfs.mkdir('./static/images');
 ```
 
-### `pfs.realpath(src, options?)`
+#### pfs.pwd
 
-Resolves a path to its canonical absolute location.
+- <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>
 
-```ts
-realpath<T extends boolean = false>(
-  src: string,
-  options?: { sync?: T; encoding?: BufferEncoding }
-): T extends true ? string : Promise<string>
-```
+The full path from the root directory to the working directory: in the context of which relative paths will be resolved.
 
-### `pfs.mkdir(dir, options?)`
+#### static: bitmask(mode)
 
-Creates a directory tree recursively.
+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.
 
 ```ts
-mkdir<T extends boolean = false>(
-  dir: string,
-  options?: { sync?: T; umask?: number }
-): T extends true ? void : Promise<void>
-```
+import { bitmask } from 'pwd-fs';
 
-- existing directories are accepted
-- default `umask`: `0o000`
+// Access: (0644/-rw-r--r--)
+const { mode } = await pfs.stat('./things.txt');
+const access = bitmask(mode);
 
-```ts
-await pfs.mkdir('./public/assets/icons');
+console.log(access === 0o644); // true
 ```
 
-## Sync Mode
-
-Every API method supports a synchronous form through `{ sync: 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:
 
-```ts
-pfs.mkdir('./cache', { sync: true });
-pfs.write('./cache/data.json', '{}', { sync: true });
-const content = pfs.read('./cache/data.json', { sync: true });
+```
+mode:   33188
+mask:   0o644 (rw-rw-r--)
 ```
 
-## Error Behavior
-
-Most async methods reject with the underlying Node.js error. Their sync variants throw the same class of error synchronously.
-
-Typical cases:
-
-- `test()` is the exception:
-  it returns `false` for inaccessible or missing paths instead of rejecting or throwing
-- `read()`, `stat()`, `readdir()`, `chmod()`, `chown()`, `rename()`, and `remove()` fail for missing paths
-- `readlink()` and `realpath()` fail for missing paths
-- `read()` fails when the target is a directory
-- `readdir()` fails when the target is not a directory
-- `emptyDir()` fails when the target is not a directory
-- `write()` fails when the target path points to a directory
-- `copy()` fails when the source does not exist
-- `copy()` fails when the destination already contains an entry with the same basename as the source, unless `overwrite: true` is used
-- `copy()` fails when a directory is copied into itself
-- `symlink()` fails when the destination already exists
-- `mkdir()` accepts an existing directory, but fails when a path segment is a file
-
-Practical pattern:
-
-```ts
-if (await pfs.test('./dist')) {
-  await pfs.remove('./dist');
-}
+#### Mode creation mask
 
-await pfs.mkdir('./dist');
-```
+The following table shows some examples of how to set the extension `mode` or `umask` for files and directories.
 
-## Umask Behavior
+| Umask | Mode files        | Mode directories  |
+|-------|-------------------|-------------------|
+| 0o000 | 0o666 (rw-rw-rw-) | 0o777 (rwxrwxrwx) |
+| 0o002 | 0o664 (rw-rw-r--) | 0o775 (rwxrwxr-x) |
+| 0o007 | 0o660 (rw-rw----) | 0o770 (rwxrwx---) |
+| 0o022 | 0o644 (rw-r--r--) | 0o755 (rwxr-xr-x) |
+| 0o027 | 0o640 (rw-r-----) | 0o750 (rwxr-x---) |
+| 0o077 | 0o600 (rw-------) | 0o700 (rwx------) |
+| 0o277 | 0o400 (r--------) | 0o500 (r-x------) |
 
-`copy()`, `write()`, and `mkdir()` support `umask`.
+#### String encoding
 
-Effective permissions:
+The following encodings are available wherever the encoding option takes a <[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>.
 
-| Umask | File mode | Directory mode |
-| --- | --- | --- |
-| `0o000` | `0o666` | `0o777` |
-| `0o022` | `0o644` | `0o755` |
-| `0o027` | `0o640` | `0o750` |
-| `0o077` | `0o600` | `0o700` |
+Encoding | Description
+---------|------------
+`'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](https://tools.ietf.org/html/rfc1421) and [RFC 2045](https://tools.ietf.org/html/rfc2045).
+`'hex'` | Encode each byte as two hexadecimal characters.
+`'ucs2'` | 2 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](https://tools.ietf.org/html/rfc1345), only in node 6.4.0+.
+`'binary'` | Like `'latin1`.
 
-## Notes
+#### File system flags
 
-- Relative paths are resolved against `pfs.pwd`
-- Absolute paths are not constrained by `pfs.pwd`
-- `stat()` returns `lstat()` data
-- `remove()` does not follow symbolic links
-- `append()` is kept for backward compatibility and is deprecated
+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)>.
 
-## Platform Caveats
+Flag | Description
+-----|------------
+`'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. Fails if the file does not exist.
+`'r+'` | Open file for reading and writing. Fails 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.
 
-| Area | Unix-like systems | Windows |
-| --- | --- | --- |
-| `chmod()` | Recursive permission changes work as expected | Permission handling is limited by platform behavior |
-| `chown()` | Recursive ownership changes are applied | Ownership is not changed; only path validation is performed |
-| `symlink()` | Link type is inferred by the platform | The implementation resolves the source first and chooses `file` or `junction` explicitly |
-| `test(..., { flag: 'x' })` | Uses executable access checks | Does not have the same semantics as Unix execute checks |
-| `remove()` on symlinks | Removes the link, not the target | Removes the link, not the target |
+The behavior of some flags is platform-specific.
 
-## When To Use Native `fs`
+#### When To Use Native `fs`
 
 Prefer native `node:fs` APIs directly when you need:
 
 - streams such as `createReadStream()` or `createWriteStream()`
 - advanced flags and options not exposed by this wrapper
 - very low-level control over file descriptors
-- exact parity with Node's callback-based APIs
-
-## Development
-
-```bash
-yarn install --frozen-lockfile
-yarn lint
-yarn build
-yarn test
-```
-
-## License
-
-MIT
+- exact parity with Node's callback-based APIs