File System
Node.js filesystem API easily usable with Promises and arrays. It does:
- absolute paths with the root as the running script.
'utf-8'
and strings. Won't return Buffers.Promises
through themagic-promises
interface.
Example: find the content of all readme.md
in the directory and sub-dirs:
const read walk = ; const files = await ; console;// ['# fs-array', '# sub-dir', ...]
Documentation
function | description |
---|---|
abs() | retrieve the absolute path of the path |
cat()* | alias of read() |
dir() | get the directory of the path |
exists() | check whenever a file or folder exists |
home() | get the home directory |
join() | put several path parts together in a cross-browser way |
list() | list all of the files and folders of the path |
ls()* | alias of .list() |
mkdir() | create the specified directory |
name() | get the filename of the path |
read() | read the file from the specified path |
remove() | remove a file or folder (recursively) |
stat() | get some information about the current file |
tmp() | find the temporary directory or a folder inside |
walk() | recursively list all of the files and folders |
write() | create a new file or put data into a file |
*Alias of another method
Magic promises
Any method that specifies an output of :Promise(type)
, it will be following magic-promises
specification.
Magic Promises are fully compatible with native promises:
const all = await ;const files = all;// ['a.js', 'b.js', ...] (all of the files and folders except node_modules)
Or with the magic-promises workflow, you can use it as the type inside :Promise(type)
, and then await
for the final value:
const files = await ;// ['a.js', 'b.js', ...] (all of the files and folders except node_modules)
See how we applied the .filter()
straight into the output of list(__dirname)
. Then we have to await for the whole thing to resolve since list()
is async. If this seems a bit confusing, read along the examples and try it yourself.
abs()
:string
Retrieve the absolute path of the passed argument relative of the directory running the script:
// cd ~/me/projects/fs/ && node index.js console;// /home/me/projects/fs/demo console;// /home/me/Documents
It will return the same string if the path is already absolute.
You can pass a second parameter to specify any base directory different from the executing environment:
// cd ~/me/projects/fs && node ./demo/abs.js // default; Relative to the place where the script is runconsole;// /home/me/projects/fs/demo // default; relative to the console location where the script is runconsole;// /home/me/projects/fs/demo // relative to the current directory (./demo)console;// /home/me/projects/fs/demo/demo // relative to the user's home directory https://stackoverflow.com/q/9080085console;// /home/me/demo
If the second parameter is undefined, or if it's not a string, it will be completely ignored and the default of the current running dir will be used. This is great for looping on arrays or similar:
console;// [ '/home/me/projects/fs/a', '/home/me/projects/fs/b' ]
cat()
alias of
read()
.
dir()
:string
Get the directory of the passed path:
console;// /home/me/hello
exists()
:Promise:boolean
Check whenever a file or folder exists:
console;// true console;// false
This cannot (yet) be used with .filter()
, since .filter()
is sync and doesn't expect an array of promises to be returned.
To filter based on whether it exists or not, extend it to an array of promises, then filter that asynchronously and finally retrieve the original file:
const keeper = ;console;
home()
Promise:string
Find the home directory if called without arguments, or the specified directory inside the home folder as specified in the arguments.
console;// /home/me/ console;// /home/me/demo/ console;// /home/me/demo/a/
It will create the specified folder if it does not exist yet.
To make sure the new folder is empty, you can call remove()
and mkdir()
consecutively:
const dir = await ;console;// /home/me/demo/ (empty)
join()
:string
Put several path segments together in a cross-browser way and return the absolute path:
console;// /home/me/projects/fs/demo/a
list()
:Promise:Array:string
Get all of the files and folders of the specified directory into an array:
console;// ['/home/me/fs/node_modules', '/home/me/fs/demo/abs.js', ...]
To scan any other directory specify it as a parameter:
console;// ['/home/me/fs/demo/a', '/home/me/fs/demo/abs.js', ...]
Magic Promises: you can iterate and treat the returned value as a normal array, except that you'll have to
await
at some point for the whole thing.
// Retrieve all of the files, filter for javascript and get their absolute pathsconsole;// ['/home/me/projects/fs/fs.js', '/home/me/projects/fs/fs.test.js', ...]
Related methods:
walk()
recursively list all of the files in a directory. Does not output directories.
ls()
alias of .list()
mkdir()
:Promise:string
Create the specified directory. If it already exists, do nothing. Returns the directory that was created.
// cd ~/projects/fs && node index.js console;// /home/me/fs/demo/b
Related methods:
- exists(): check whether a directory exists.
- remove(): remove a folder or file.
- list(): read all the contents of a directory.
name()
:string
Get the filename of the passed path:
console;// world.js
read()
:Promise:string
Read the specified file contents into a string:
console;// # fs-array ...
File reads are relative as always to the executing script. It expects a single argument so you can easily put an array on it:
// Read two files manuallyconsole;// ['# A', '# B'] // Read all markdown files in all subfoldersconsole;// ['# A', '# B', ...]
It also follows the magic-promises
specification, so you can perform any normal string operations on it:
// Find all the secondary headers in a markdown fileconsole;// ['## cat()', '## dir()', ...]
remove()
:Promise:string
Remove a file or folder (recursively) and return the absolute path that was removed
console;// /home/me/projects/readme.md console;// /home/me/old-project
stat()
:Promise:object
Get some information about the current path:
console;// true (the current directory) console;// true console;// 2018-08-27T23:42:16.206Z
tmp()
Promise:string
Find the temporary directory. If arguments are passed, find the specified directory inside the tmp folder:
console;// /tmp/ console;// /tmp/demo/ console;// /tmp/demo/a/
It will create the specified folder if it does not exist yet.
To make sure the new folder is empty, you can call remove()
and mkdir()
consecutively:
const dir = await ;console;// /tmp/demo/ (empty)
walk()
:Promise:Array:string
Recursively list all of the files from the specified folder:
// Retrieve all files inside './demo'console;// ['/home/me/projects/fs/demo/readme.md', '/home/me/projects/fs/demo/a/readme.md', ...]
It will not return directories. You can then use filter
to filter e.g. by filename:
// Retrieve the content of all markdown files inside democonsole;// ['# Readme A', '# Me also', ...]
write()
:Promise:string
Create a new file or put data into a file that already exists. Returns the path of the file:
// Write to a file and then read its contentsconsole;// 'Hello!'