pwd-fs 3.3.5 → 3.5.0

package/readme.md

@@ -12,11 +12,11 @@ It provides:
 - matching synchronous variants via `{ sync: true }`
 - recursive helpers for copy, remove, chmod, chown, and mkdir
 
-All relative paths are resolved against `pfs.pwd`.
+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 scoped to a specific working directory without manually calling `path.resolve()` before every operation.
+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:
 
@@ -31,6 +31,43 @@ It is especially useful for:
 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
 
 ```ts
@@ -41,7 +78,7 @@ await pfs.mkdir('./own/project'); // recursively create the directory
 
 ## Common Recipes
 
-### Work inside a scoped directory
+### Work inside a project directory
 
 ```ts
 import { PoweredFileSystem } from 'pwd-fs';
@@ -65,6 +102,19 @@ Result:
 - destination directory: `./dist`
 - created output: `./dist/assets`
 
+### Empty a directory but keep it
+
+```ts
+await pfs.emptyDir('./cache');
+```
+
+### Resolve a symlink target
+
+```ts
+const target = await pfs.readlink('./current');
+const resolved = await pfs.realpath('./current');
+```
+
 ### Append to a file
 
 ```ts
@@ -88,7 +138,7 @@ if (await pfs.test('./tmp')) {
 
 ## Compatibility
 
-- package `engines`: Node.js `>=13.2.0`
+- 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
@@ -109,7 +159,7 @@ import PoweredFileSystem, { pfs, bitmask } from 'pwd-fs';
 
 ### `new PoweredFileSystem(pwd?)`
 
-Creates a new instance rooted at `pwd`.
+Creates a new instance with `pwd` as the base directory for relative paths.
 
 - `pwd?: string`
 - default: `process.cwd()`
@@ -122,7 +172,22 @@ const pfs = new PoweredFileSystem('./workspace');
 
 ### `pfs.pwd`
 
-Absolute base directory used to resolve all relative paths.
+Absolute base directory used to resolve relative paths.
+
+### `pfs.resolve(src)`
+
+Resolves `src` against `pfs.pwd`.
+
+```ts
+const pfs = new PoweredFileSystem('/workspace/project');
+const file = pfs.resolve('./src/index.ts');
+```
+
+Absolute paths are preserved:
+
+```ts
+pfs.resolve('/tmp/outside.txt'); // '/tmp/outside.txt'
+```
 
 ### `pfs.constants`
 
@@ -232,7 +297,12 @@ Copies `src` into the destination directory.
 copy<T extends boolean = false>(
   src: string,
   dest: string,
-  options?: { sync?: T; umask?: number }
+  options?: {
+    sync?: T;
+    umask?: number;
+    overwrite?: boolean;
+    filter?: (src: string, dest: string) => boolean;
+  }
 ): T extends true ? void : Promise<void>
 ```
 
@@ -241,6 +311,8 @@ Behavior:
 - 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');
@@ -248,6 +320,13 @@ await pfs.copy('./assets', './dist');
 
 This creates `./dist/assets`, not a direct rename to `./dist`.
 
+```ts
+await pfs.copy('./assets', './dist', {
+  overwrite: true,
+  filter: (src) => !src.endsWith('.map')
+});
+```
+
 ### `pfs.rename(src, dest, options?)`
 
 Renames or moves a file system entry.
@@ -276,6 +355,21 @@ Behavior:
 - directories are removed recursively
 - symbolic links are unlinked without deleting the target
 
+### `pfs.emptyDir(src, options?)`
+
+Removes all entries inside a directory while preserving the directory itself.
+
+```ts
+emptyDir<T extends boolean = false>(
+  src: string,
+  options?: { sync?: T }
+): T extends true ? void : Promise<void>
+```
+
+```ts
+await pfs.emptyDir('./tmp');
+```
+
 ### `pfs.read(src, options?)`
 
 Reads a file.
@@ -363,6 +457,28 @@ readdir<T extends boolean = false>(
 
 - default `encoding`: `'utf8'`
 
+### `pfs.readlink(src, options?)`
+
+Reads the stored target path from a symbolic link.
+
+```ts
+readlink<T extends boolean = false>(
+  src: string,
+  options?: { sync?: T; encoding?: BufferEncoding }
+): T extends true ? string : Promise<string>
+```
+
+### `pfs.realpath(src, options?)`
+
+Resolves a path to its canonical absolute location.
+
+```ts
+realpath<T extends boolean = false>(
+  src: string,
+  options?: { sync?: T; encoding?: BufferEncoding }
+): T extends true ? string : Promise<string>
+```
+
 ### `pfs.mkdir(dir, options?)`
 
 Creates a directory tree recursively.
@@ -400,11 +516,14 @@ 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()` also fails when the destination already contains an entry with the same basename as the source
+- `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
 
@@ -433,7 +552,8 @@ Effective permissions:
 
 ## Notes
 
-- Relative paths are always resolved against `pfs.pwd`
+- 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
@@ -460,9 +580,10 @@ Prefer native `node:fs` APIs directly when you need:
 ## Development
 
 ```bash
-npm install
-npm run build
-npm test
+yarn install --frozen-lockfile
+yarn lint
+yarn build
+yarn test
 ```
 
 ## License