path-nice

English | 简体中文

path-nice - The elegant and handy alternative to path, fs and glob

If sometimes you do not feel nice about the original path or fs of Node.js, then just

All existing code still works, while the path evolves.

Why this lib?

One lib does work for two, simplifies the code greatly

Original ver:

1import path from 'path';
2import fs from 'fs';
3
4const app = await fs.promises.realpath('./app');
5const publicDir = path.join(app, 'public');
6await fs.promises.writeFile(
7    path.join(publicDir, 'manifest.json'),
8    JSON.stringify({ name: 'App' }),
9);

nice ver:

1import path from 'path-nice';
2
3const app = await path('./app').realpath();
4const publicDir = app.join('public');
5await publicDir.join('manifest.json')
6               .writeJSON({ name: 'App' });

Especially when you need to import some predefined paths from other modules, path-nice is doubly convenient: instead of importing additional path and fs modules, just import the paths you need, type a dot, and all the methods you need are present.

Detailed JSDoc, no need to go through docs, examples are all there

Can bind other filesystem implementations, e.g. memory file system memfs

1import path from 'path-nice';
2import { fs as memfs } from 'memfs';
3
4const mpath = path
5    .posix          // Use POSIX-style paths (memfs only supports POSIX-style)
6    .bindFS(memfs); // bind file system
7
8await mpath('/index.ts')
9    .writeFile('export default 42;');

Metaprogramming, the path is known at compile time

(Coming soon in version 2.1.0)

Installation

1npm install path-nice

or

1yarn add path-nice

• Requires: Node.js >= v12.0.0
• Provided: CommonJS, ESModule and TypeScript typings
• ESModule version can be used directly in Node.

Documents

Please refer to API Reference.

3 minutes guide

Add a pair of () after path to enter "nice" mode.

1import path from 'path-nice'
2
3const dir = path('./src')

dir is the instance of class PathNice:

1dir instanceof path.PathNice    // true

A PathNice instance is a wrapper of the raw path string, so that the path can be easily used to generate additional paths or manipulate files.:

1dir.raw === './src'             // true

Each PathNice instance is an immutable object, all properties are read-only:

1Object.isFrozen(dir)            // true

Path related methods

1let f = path('path-nice/src')
2
3f = f.join('index.ts')           // path('path-nice/src/index.ts')
4
5// For the following 4 methods: 0 args = get, 1 arg = set
6
7f.dirname()                     // path('path-nice/src')
8f.dirname('another-dir')        // path('another-dir/index.ts')
9
10f.filename()                    // 'index.ts'
11f.filename('types.ts')          // path('path-nice/src/types.ts')
12
13f.ext()                         // '.ts'
14f.ext('.js')                    // path('path-nice/src/index.js')
15
16f.separaotr()                   // '/'
17f.separaotr('\\')               // path('path-nice\\src\\index.ts')
18
19// .parent is an alias for .dirname(), can get the path to the parent directory
20f.parent.raw === f.dirname().raw // true
21
22const f2 = f.parent.parent.join('package.json')
23f2.raw                          // 'path-nice/package.json'
24
25f2.isAbsolute()                 // false
26f2.toAbsolute()                 // path('/work/path-nice/package.json'), suppose cwd is '/work'
27
28// Use .realpath() to get the absolute path and resolve the
29// soft links that may exist in the path at the same time.
30await f2.realpath()             // path('/project/path-nice/package.json')
31                                // suppose cwd is '/work', and '/work' points to '/project'
32
33f2.toRelative('path-nice/docs') // path('../package.json')
34
35f2.prefixFilename('old.')       // path('path-nice/old.package.json')
36f2.postfixBeforeExt('.old')     // path('path-nice/package.old.json')
37f2.postfix('.old')              // path('path-nice/package.json.old')

For more path-related methods, see docs of PathNice.

File system related methods

It can be noted that, many functions in the fs module, such as readFile and writeFile, almost always have path as their first parameter. path-nice rewrites them as member methods of class PathNice, and makes it easier to call them by automatically filling this parameter with the current path.

Most of the following methods are asynchronous methods, returning a Promise. Add the suffix Sync to the function names to get their synchronous versions.

Read and write

• readFile

• readFileToString: Same as readFile, but guaranteed to return a string. Default: UTF-8

• readJSON: read the file, then parse as json. Default: UTF-8

• writeFile

• writeJSON: Serialize the json object, then write it to the file. Default: UTF-8, 4 spaces as indent

• outputFile: Same as writeFile, automatically create the parent directory if it does not exist

• outputJSON: Same as writeJSON, automatically create the parent directory if it does not exist

• updateFileAsString

  Execute a function to quickly update a file.

  e.g.

  1await path('README.md')
  2    .updateFileAsString(str => str.replace(/path/g, 'path-nice'))

• updateJSON

  Execute a function to quickly update a JSON file.

  e.g.

  1await path('package.json')
  2    .updateJSON(json => { json.version = '1.0.0' })

• appendFile

• createReadStream

• createWriteStream

• open

Copy, move and remove

Directories containing files can also be copied, moved, or deleted directly. Supports moving files across devices.

• copy
• move
• remove
• delete: Alias of remove
• rename
• emptyDir: Empty the folder, and ensure it exists

Ensure

Ensure the directory or file exists. If it doesn't, create it automatically.

• emptyDir: Empty the folder, and ensure it exists
• ensureDir
• ensureFile

Is ... ?

• isDir
• isEmptyDir
• isFile
• isSymbolicLink
• exists

List directory contents

• ls: Returns Promise<{ dirs: PathNiceArr, files: PathNiceArr }>, directories and files already sorted out, all absolute paths, easier to use
• readdir

Watch

• watchWithChokidar: use npm package chokidar to watch files, API is more friendly and powerful
• watch
• watchFile
• unwatchFile

File info

• fileSize: Get the file size, including the size in B, KB, MB, GB, etc.
• fileMode: Gets the file mode
• fileOwner: Get the file owner
• chmod
• chown
• lchown
• stat
• lstat

PathNiceArr

When multiple arguments are passed to path(), or an array, it returns a PathNiceArr:

1import path from 'path-nice';
2
3let arr = path('./README.md', './package.json', './tsconfig.json');

class PathNiceArr is a subclass of class Array. The methods of Array can be called in a normal way:

1arr = arr.filter(f => f.ext() === '.json')
2// PathNiceArr [
3//     PathNice { raw: './package.json' },
4//     PathNice { raw: './tsconfig.json' },
5// ]

It also adds some additional methods to holistically manipulate files in the array:

1await arr.copyToDir('. /json-config'); // each file in arr is copied to the json-config directory

If arr.base is set, the files will maintain their directory structure relative to base when copying or moving files. When not set, files are copied or moved one by one. For example:

1/*
2Assuming cwd = /work, and ./src contains the following files:
3   ./src
4    ├── lib/
5    │   ├── jquery.js
6    │   └── types.ts
7    └── index.ts
8*/
9
10const { dirs, files } = await path('./src').ls(/* recursive */ true);
11
12console.log(files);
13// PathNiceArr(3) [
14//     PathNice { raw: '/work/src/index.ts' },
15//     PathNice { raw: '/work/src/lib/jquery.js' },
16//     PathNice { raw: '/work/src/lib/types.ts' },
17//     base: PathNice { raw: '/work/src' }
18// ]
19
20await files.copyToDir('dist');
21/*
22The directory structure of dist at this point:
23   ./dist
24    ├── lib/
25    │   ├── jquery.js
26    │   └── types.ts
27    └── index.ts
28*/
29
30await path('dist').emptyDir();  // empty the dist directory
31files.base = undefined;         // clear base
32
33await files.copyToDir('dist');
34/*
35The directory structure of dist at this point:
36   ./dist
37    ├── jquery.js
38    ├── types.ts
39    └── index.ts
40*/

For detailed usage of PathNiceArr, see docs of PathNiceArr.