qir

another fs

If links in this document not avaiable, please access README on GitHub directly.

Description

qir is variant of dir which is abbreviation of directory. Actually, this package is based on built-in module fs and offers easy utilities helping access with file system.

ToC

• Get Started
• API
• Examples
• Why qir

Links

• CHANGE LOG
• Homepage

Get Started

const qir = require('qir');

// Sync mode.
qir.syncing.mkd('/foo/bar/quz');

// Async mode.
qir.asyncing.rmfr('/foo').then(() => {
    // ...
});

API

There are two collections of methods in this package.

const qir       = require('qir');
const qirSync   = require('qir/syncing');
const qirAsync  = require('qir/asyncing');
const SyncDir   = require('qir/SyncDir');
const AsyncDir  = require('qir/AsyncDir');

qir.syncing  === qirSync    // true
qir.asyncing === qirAsync   // true
qir.SyncDir  === SyncDir    // true
qir.AsyncDir === AsyncDir   // true

• class qir.AsyncDir( string basepath )
• class qir.SyncDir( string basepath )
• Object qir.syncing
• Object qir.asyncing

The method collections syncing and asyncing are parallel, so are the classes AsyncDir and SyncDir.

Each of the method collections and class instances has following methods:

• void | Promise(void)
  appendFile( string filename, string | Buffer data )

• void | Promise(void)
  clear()
  Only available for instances of AsyncDir and SyncDir.
  Remove everything in the directory and the directory itself.

• void | Promise(void)
  copy( string src, string dest)

• void | Promise(void)
  copyFile( string src, string dest, number flags )

• stream.Readable | Promise(stream.Readable)
  createReadStream( string filename[, Object options] )

• stream.Writable | Promise(stream.Writable)
  createWriteStream( string filename[, Object options] )

• boolean
  exists( string pathname )
  Only available for instances of AsyncDir and SyncDir.

• string[]
  find( object options )
  Only available for asyncing and instances of AsyncDir.
  See sore/find for details of options.

• void | Promise(void)
  link( string existingPath, string newPath )

• void | Promise(void)
  mkd( string dirname )

• void | Promise(void)
  mkd_temp( string dirname [, string prefix] )

• void | Promise(void)
  mkd_parent( string pathname )

• integer | Promise(integer)
  open( string filename [, string | number flags [, integer mode ] ] )

• string | Buffer | Promis(string) | Promise(Buffer)
  readFile( string pathname )
  Only available for instances of AsyncDir and SyncDir.

• JSON | Promise(JSON)
  readJSON( string filename )

• string[] | Promis(string[])
  readdir( string dirname )

• void | Promise(void)
  rename( string oldPath, string newPath )

• string
  resolve( string pathname )
  Only available for instances of AsyncDir and SyncDir.

• void | Promise(void)
  rmfr( string pathname )

• fs.Stats | Promise(fs.Stats)
  stat( string pathname )
  ATTENTION： This method is some different from built-in fs.stats which will throws an Error if the target is not accessible. It will return null in such case.

• void | Promise(void)
  symlink( string target, string pathname [, string type ] )

• void | Promise(void)
  touch( string filename )

• void | Promise(void)
  writeFile ( string filename, string | Buffer | TypedArray | DataView data )

• void | Promise(void)
  writeJSON ( string filename, JSON json )

ATTENTIONS:

• In asynchronous mode, the leading type names represent NOT what the function will return on invoked, BUT data in .then(data). Actually, each function will return an instance of Promise in asynchronous mode.

• When pathname (dirname or filename) occurs in methods of new AsyncDir() and new SyncDir(), it will be regarded to be relative to the basepath.

• Some methods accept same arguments with the homonynic methods in fs. But not each method has a symmetrical one in fs.

• All methods in qir.asyncing and new AsyncDir() will return an instance of Promise.

• All methods will automatically create parent directories if necessary.

Why qir

It is tedious to create an embedded directory with built-in module fs. E.g.

// If you wannt to create a directory /foo/bar/quz while /foo doesnot exist:
fs.mkdirSync('/foo');
fs.mkdirSync('/foo/bar');
fs.mkdirSync('/foo/bar/quz');

// You may complete these operations in one step via `qir`.
qir.syncing.mkd('/foo/bar/quz');