Package Exports

nofs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (nofs) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

nofs

Overview

nofs extends Node's native fs module with some useful methods. It tries to make your functional programming experience better. It's one of the core lib of nokit.

Features

Introduce map and reduce to folders.
Recursive glob, move, copy, remove, etc.
Promise by default.
Unified intuitive API. Support Promise, Sync and Callbackparadigms.
Much lighter than gulp, but much more flexible.

Install

npm install nofs

API Convention

Path & Pattern

Any path that can be a pattern it will do.

Unix Path Separator

When the system is Windows and process.env.force_unix_sep != 'off', nofs will force all the path separator to /, such as C:\a\b will be transformed to C:/a/b.

Promise, Sync and Callback

Any function that has a Sync version will has a promise version that ends with P. For example the fs.remove will have fs.removeSync for sync IO, and fs.removeP for Promise.

eachDir

It is the core function for directory manipulation. Other abstract functions like mapDir, reduceDir, glob are built on top of it. You can play with it if you don't like other functions.

nofs & Node Native fs

nofs only extends the native module, no pollution will be found. You can still call nofs.readFile as easy as pie.

Inheritance of Options

A Function's options may inherit other function's, especially the functions it calls internally. Such as the glob extends the eachDir's option, therefore glob also has a filter option.

Quick Start

# You can replace "require('fs')" with "require('nofs')"
fs = require 'nofs'


###
# Callback
###
fs.outputFile 'x.txt', 'test', (err) ->
    console.log 'done'


###
# Sync
###
fs.readFileSync 'x.txt'
fs.copySync 'dir/a', 'dir/b'


###
# Promise
###
fs.mkdirsP 'deep/dir/path'
.then ->
    fs.outputFileP 'a.txt', 'hello world'
.then ->
    fs.moveP 'dir/path', 'other'
.then ->
    fs.copyP 'one/**/*.js', 'two'
.then ->
    # Get all txt files.
    fs.globP 'deep/**'
.then (list) ->
    console.log list
.then ->
    # Remove only js files.
    fs.removeP 'deep/**/*.js'


###
# Concat all css files.
###
fs.reduceDirP 'dir/**/*.css', {
    init: '/* Concated by nofs */\n'
}, (sum, { path }) ->
    fs.readFileP(path).then (str) ->
        sum += str + '\n'
.then (concated) ->
    console.log concated


###
# Compile files from one place to another.
###
fs.mapDirP 'from', 'to', (src, dest) ->
    fs.readFileP(src, 'utf8').then (str) ->
        compiled = '/* Compiled by nofs */\n' + str
        fs.outputFileP dest, compiled



###
# Play with the low level api.
# Filter all the ignored files with high performance.
###
patterns = fs.readFileSync('.gitignore', 'utf8').split '\n'

filter = ({ path }) ->
    for ptn in patterns
        if fs.pmatch.minimath path, ptn
            return false
    return true

fs.eachDirP('.', {
    searchFilter: filter # Ensure subdirectory won't be searched.
    filter: filter
}, (info) ->
    info  # Directly return the file info object.
).then (tree) ->
    # Instead a list as usual,
    # here we get a file tree for further usage.
    console.log tree

VS Gulp

If you know Promise, no learning curve.
If you use it with nokit spawn, you can esaily take advantage of multi-core cpu, and compile much faster.
Error handling is more unified and flexible, since it is just Promise.
Async sequence chainning is also more unified and flexible.
Will works great with ES7 async / await.

fs = require 'nofs'

# coffee plugin
coffee = (path) ->
    fs.readFileP path, 'utf8'
    .then (coffee) ->
        # Unlike pipe, you can still control all the details esaily.
        '/* Add Lisence Info */\n\n' + coffee

# writer plugin: A simple curried function.
writer = (path) -> (js) ->
    fs.outputFileP path, js

# minify plugin
minify = (js) ->
    uglify = require 'uglify-js'
    uglify.minify js, { fromString: true }

# Use the plugins.
jsTask = ->
    # All files will be compiled concurrently.
    # Unlike Gulp, you don't have to wait glob finished to compile a file.
    fs.mapDirP 'src/**/*.coffee', 'dist', (src, dest) ->
        # Here's the work flow, simple yet readable.
        coffee src
        .then minify
        .then writer(dest)

cssTask = -> # ...

cleanTask = -> # ...

# Run all tasks concurrently, and sequence groups.
compileGroup = [jsTask(), cssTask()]
fs.Promise.all compileGroup
.then cleanTask # The clean will work after all compilers are settled.
.then ->
    console.log 'All Done!'

Changelog

Goto changelog

Function Alias

For some naming convention reasons, nofs also uses some common alias for fucntions. See src/alias.coffee.

API

No native fs funtion will be listed.

Overview
I hate to reinvent the wheel. But to purely use promise, I don't have many choices.
Promise
Here I use [Bluebird][Bluebird] only as an ES6 shim for Promise. No APIs other than ES6 spec will be used. In the future it will be removed. [Bluebird]: https://github.com/petkaantonov/bluebird
copyDirP
Copy an empty directory.
- param: src { String }
- param: dest { String }
- param: opts { Object }
```
{
    isForce: false
    mode: auto
}
```
- return: { Promise }
copyFileP
Copy a single file.
- param: src { String }
- param: dest { String }
- param: opts { Object }
```
{
    isForce: false
    mode: auto
}
```
- return: { Promise }
copyP
Like cp -r.
- param: from { String }
  
  Source path.
- param: to { String }
  
  Destination path.
- param: opts { Object }
  
  Extends the options of eachDir. Defaults:
```
{
    # Overwrite file if exists.
    isForce: false
    isFnFileOnly: false
}
```
- return: { Promise }
dirExistsP
Check if a path exists, and if it is a directory.
- param: path { String }
- return: { Promise }
  
  Resolves a boolean value.

eachDirP

Concurrently walks through a path recursively with a callback. The callback can return a Promise to continue the sequence. The resolving order is also recursive, a directory path resolves after all its children are resolved.

param: spath { String }

The path may point to a directory or a file.

param: opts { Object }

Optional. Defaults:

{
    # Auto check if the spath is a minimatch pattern.
    isAutoMimimatch: true

    # Include entries whose names begin with a dot (.).
    all: true

    # To filter paths. It can also be a RegExp or a glob pattern string.
    # When it's a string, it extends the Minimatch's options.
    filter: (fileInfo) -> true

    # The current working directory to search.
    cwd: ''

    # Call fn only when it is a file.
    isFnFileOnly: false

    # Whether to include the root directory or not.
    isIncludeRoot: true

    # Whehter to follow symbol links or not.
    isFollowLink: true

    # Iterate children first, then parent folder.
    isReverse: false

    # When isReverse is false, it will be the previous fn resolve value.
    val: any

    # If it return false, sub-entries won't be searched.
    # When the `filter` option returns false, its children will
    # still be itered. But when `searchFilter` returns false, children
    # won't be itered by the fn.
    searchFilter: (fileInfo) -> true

    # If you want sort the names of each level, you can hack here.
    # Such as `(names) -> names.sort()`.
    handleNames: (names) -> names
}

param: fn { Function }

(fileInfo) -> Promise | Any. The fileInfo object has these properties: { path, isDir, children, stats }. Assume we call the function: nofs.eachDirP('dir', (f) -> f), the resolved directory object array may look like:

{
    path: 'dir/path'
    name: 'path'
    baseDir: 'dir'
    isDir: true
    val: 'test'
    children: [
        { path: 'dir/path/a.txt', name: 'a.txt', baseDir: 'dir', isDir: false, stats: { ... } }
        { path: 'dir/path/b.txt', name: 'b.txt', baseDir: 'dir', isDir: false, stats: { ... } }
    ]
    stats: {
        size: 527
        atime: Mon, 10 Oct 2011 23:24:11 GMT
        mtime: Mon, 10 Oct 2011 23:24:11 GMT
        ctime: Mon, 10 Oct 2011 23:24:11 GMT
        ...
    }
}

The stats is a native nofs.Stats object.

return: { Promise }

Resolves a directory tree object.

example:

# Print all file and directory names, and the modification time.
nofs.eachDirP 'dir/path', (obj, stats) ->
    console.log obj.path, stats.mtime

# Print path name list.
nofs.eachDirP 'dir/path', (curr) -> curr
.then (tree) ->
    console.log tree

# Find all js files.
nofs.eachDirP 'dir/path', {
    filter: '**/*.js', nocase: true
}, ({ path }) ->
    console.log paths

# Find all js files.
nofs.eachDirP 'dir/path', { filter: /\.js$/ }, ({ path }) ->
    console.log paths

# Custom filter
nofs.eachDirP 'dir/path', {
    filter: ({ path, stats }) ->
        path.slice(-1) != '/' and stats.size > 1000
}, (path) ->
    console.log path

fileExistsP
Check if a path exists, and if it is a file.
- param: path { String }
- return: { Promise }
  
  Resolves a boolean value.

globP

Get files by patterns.

param: pattern { String | Array }

The minimatch pattern. Patterns that starts with '!' in the array will be used to exclude paths.
param: opts { Object }

Extends the options of eachDir. But the filter property will be fixed with the pattern. Defaults:
```
{
    all: false

    # The minimatch option object.
    pmatch: {}
}
```
param: fn { Function }

(fileInfo, list) -> Promise | Any. It will be called after each match. By default it is: (fileInfo, list) -> list.push fileInfo.path
return: { Promise }

Resolves the list array.

example:

# Get all js files.
nofs.globP(['**/*.js', '**/*.css']).then (paths) ->
    console.log paths

# Exclude some files. "a.js" will be ignored.
nofs.globP(['**/*.js', '**/a.js']).then (paths) ->
    console.log paths

# Custom the iterator. Append '/' to each directory path.
nofs.globP('**/*.js', (info, list) ->
    list.push if info.isDir
        info.path + '/'
    else
        info.path
).then (paths) ->
    console.log paths

mapDirP
Map file from a directory to another recursively with a callback.
- param: from { String }
  
  The root directory to start with.
- param: to { String }
  
  This directory can be a non-exists path.
- param: opts { Object }
  
  Extends the options of eachDir. But cwd is fixed with the same as the from parameter. Defaults:
```
{
    isFnFileOnly: true
}
```
- param: fn { Function }
  
  (src, dest, fileInfo) -> Promise | Any The callback will be called with each path. The callback can return a Promise to keep the async sequence go on.
- return: { Promise }
  
  Resolves a tree object.
- example:
```
# Copy and add license header for each files
# from a folder to another.
nofs.mapDirP(
    'from'
    'to'
    (src, dest) ->
        nofs.readFileP(src).then (buf) ->
            buf += 'License MIT\n' + buf
            nofs.outputFileP dest, buf
)
```
mkdirsP
Recursively create directory path, like mkdir -p.
- param: path { String }
- param: mode { String }
  
  Defaults: 0o777 & ~process.umask()
- return: { Promise }
moveP
Moves a file or directory. Also works between partitions. Behaves like the Unix mv.
- param: from { String }
  
  Source path.
- param: to { String }
  
  Destination path.
- param: opts { Object }
  
  Defaults:
```
{
    isForce: false
}
```
- return: { Promise }
  
  It will resolve a boolean value which indicates whether this action is taken between two partitions.
outputFileP
Almost the same as writeFile, except that if its parent directories do not exist, they will be created.
- param: path { String }
- param: data { String | Buffer }
- param: opts { String | Object }
  
  Same with the writeFile.
- return: { Promise }
outputJsonP
Write a object to a file, if its parent directory doesn't exists, it will be created.
- param: path { String }
- param: obj { Any }
  
  The data object to save.
- param: opts { Object | String }
  
  Extends the options of outputFileP. Defaults:
```
{
    replacer: null
    space: null
}
```
- return: { Promise }
path
The native io.js path lib.
- type: { Object }
pmatch
The minimatch lib. It has two extra methods:
- isPmatch(String | Object) -> Pmatch | undefined It helps to detect if a string or an object is a minimatch.
- getPlainPath(Pmatch) -> String Helps to get the plain root path of a pattern. Such as src/js/*.js will get src/js
Documentation

Offline Documentation
Promise
What promise this lib is using.
- type: { Bluebird }
promisify
A callback style to promise helper. It doesn't depends on Bluebird.
- type: { Function }
readJsonP
Read A Json file and parse it to a object.
- param: path { String }
- param: opts { Object | String }
  
  Same with the native nofs.readFile.
- return: { Promise }
  
  Resolves a parsed object.
- example:
```
nofs.readJsonP('a.json').then (obj) ->
    console.log obj.name, obj.age
```

reduceDirP

Walk through directory recursively with a callback.

param: path { String }

param: opts { Object }

Extends the options of eachDir, with some extra options:

{
    # The init value of the walk.
    init: undefined

    isFnFileOnly: true
}

param: fn { Function }

(prev, path, isDir, stats) -> Promise
return: { Promise }

Final resolved value.

example:

# Concat all files.
nofs.reduceDirP 'dir/path', { init: '' }, (val, { path }) ->
    nofs.readFileP(path).then (str) ->
        val += str + '\n'
.then (ret) ->
    console.log ret

removeP
Remove a file or directory peacefully, same with the rm -rf.
- param: path { String }
- param: opts { Object }
  
  Extends the options of eachDir. But the isReverse is fixed with true.
- return: { Promise }
touchP
Change file access and modification times. If the file does not exist, it is created.
- param: path { String }
- param: opts { Object }
  
  Default:
```
{
    atime: Date.now()
    mtime: Date.now()
    mode: undefined
}
```
- return: { Promise }
  
  If new file created, resolves true.
watchFileP
Watch a file. If the file changes, the handler will be invoked. You can change the polling interval by using process.env.pollingWatch. Use process.env.watchPersistent = 'off' to disable the persistent. Why not use nofs.watch? Because nofs.watch is unstable on some file systems, such as Samba or OSX.
- param: path { String }
  
  The file path
- param: handler { Function }
  
  Event listener. The handler has these params:
  - file path
  - current nofs.Stats
  - previous nofs.Stats
  - if its a deletion
- param: autoUnwatch { Boolean }
  
  Auto unwatch the file while file deletion. Default is true.
- return: { Promise }
  
  It resolves the wrapped watch listener.
- example:
```
process.env.watchPersistent = 'off'
nofs.watchFileP 'a.js', (path, curr, prev, isDeletion) ->
    if curr.mtime != prev.mtime
        console.log path
```
watchFilesP
Watch files, when file changes, the handler will be invoked. It is build on the top of nofs.watchFileP.
- param: patterns { Array }
  
  String array with minimatch syntax. Such as ['*/**.css', 'lib/**/*.js'].
- param: handler { Function }
- return: { Promise }
  
  It contains the wrapped watch listeners.
- example:
```
nofs.watchFiles '*.js', (path, curr, prev, isDeletion) ->
    console.log path
```
watchDirP
Watch directory and all the files in it. It supports three types of change: create, modify, move, delete. By default, move event is disabled. It is build on the top of nofs.watchFileP.
- param: root { String }
- param: opts { Object }
  
  Defaults:
```
{
    pattern: '**' # minimatch, string or array

    # Whether to watch POSIX hidden file.
    all: false

    # The minimatch options.
    pmatch: {}

    isEnableMoveEvent: false
}
```
- param: fn { Function }
  
  (type, path, oldPath) ->. If the "path" ends with '/' it's a directory, else a file.
- return: { Promise }
  
  Resolves a object that keys are paths, values are listeners.
- example:
```
# Only current folder, and only watch js and css file.
nofs.watchDir 'lib', {
    pattern: '*.+(js|css)'
}, (type, path) ->
        console.log type, path
```
writeFileP
A writeFile shim for < Node v0.10.
- param: path { String }
- param: data { String | Buffer }
- param: opts { String | Object }
- return: { Promise }

Benckmark

nofs.copy vs ncp

Lisence

MIT