m-io

(Incomplete) replacement for q-io

This package is a replacement for the functions of q-io that I use in my projects. I have use q-io/fs a lot since it has functions like makeTree, listTree and removeTree. Furthermore, its read and write function work with strings by default, which makes it easier to read text files.

Sadly, q-io@1 depends on collections@1, which overwrites the function Array.prototype.find with an implementation that does not match the ES6-spec. This causes problems in jsdoc-parse. This is another example of why modifying objects you don’t own is a bad practice.

This problem could be solved by using q-io@2 instead of version 1. This version has other problems which were solved in version 1. It may be a silly feeling, but version 2 of q-io vseems not to receive too much care at the moment.

Since I do not use many functions, I have decided to write a drop-in replacement for my own purposes, and this is it: m-io. If you like this and want to provide more methods for your needs, please go ahead and make a PR.

Installation

npm install m-io

Usage

The following example demonstrates how to use this module:

var FS = require('m-io/fs')
 
// Create some files
FS.makeTree('city/germany')
  .then(() => FS.write('city/germany/darmstadt.md', 'Darmstadt is nice'))
  .then(() => FS.makeTree('city/usa'))
  .then(() => FS.write('city/usa/new-york.md', 'New York is huge'))
  .then(() => FS.makeTree('city/france'))
  .then(() => FS.write('city/france/paris.md', 'Olala'))
 
  // Existance of files
  .then(() => FS.exists('city'))
  .then((exists) => console.log('Directory city exists?', exists))
 
  .then(() => FS.exists('something-else'))
  .then((exists) => console.log('Directory something-else exists?', exists))
 
  // Checking for directories
  .then(() => FS.isDirectory('city/germany'))
  .then((isDirectory) => console.log('Is `city/germany` a directory?', isDirectory))
 
  .then(() => FS.isDirectory('city/germany/darmstadt.md'))
  .then((isDirectory) => console.log('Is `city/germany/darmstadt.md` a directory?', isDirectory))
 
  .then(() => FS.isDirectory('city/germany/non-existing-file'))
  .then((isDirectory) => console.log('Is `city/germany/non-existing-file` a directory?', isDirectory))
 
  // Directory listings
  .then(() => FS.list('city'))
  .then((list) => console.log('Directory entries of city', list.sort()))
 
  // List files
  .then(() => FS.listTree('city', (filename, stats) => stats.isFile()))
  .then((filelist) => console.log('List files:', filelist.sort()))
 
  // List dirs and files
  .then(() => FS.listTree('city'))
  .then((list) => console.log('List dirs and files:', list.sort()))
 
  // Read file contents
  .then(() => FS.read('city/usa/new-york.md'))
  .then((nyc) => console.log('Read file contents:', nyc))
 
  // Remove subdir
  .then(() => FS.removeTree('city/usa'))
  .done(() => console.log('Done'))

This will generate the following output

Directory city exists? true
Directory something-else exists? false
Is `city/germany` a directory? true
Is `city/germany/darmstadt.md` a directory? false
Is `city/germany/non-existing-file` a directory? false
Directory entries of city [ 'france', 'germany', 'usa' ]
List files: [ 'city/france/paris.md',
  'city/germany/darmstadt.md',
  'city/usa/new-york.md' ]
List dirs and files: [ 'city',
  'city/france',
  'city/france/paris.md',
  'city/germany',
  'city/germany/darmstadt.md',
  'city/usa',
  'city/usa/new-york.md' ]
Read file contents: New York is huge
Done

After deleting city/usa, the city-subtree looks liks this:


city
├─┬ france
│ └── paris.md
└─┬ germany
  └── darmstadt.md

API-reference

`require("m-io/fs")`

fs

fs
- .exists(existsPath) ⇒ Promise.<boolean>
- .listTree(directoryPath, filter) ⇒ Promise.<Array.<string>>
- .list(directoryPath) ⇒ Promise.<Array.<string>>
- .makeTree(aPath, [mode])
- .read(aPath)
- .write(aPath, content)
- .copy(source, target)
- .copyTree(source, target)
- .stat(aPath)
- .isDirectory(directory)

fs.exists(existsPath) ⇒ `Promise.<boolean>`

Custom implementation of q-io/fs#exists to avoid dependency on q-io

Kind: static method of fs
Returns: Promise.<boolean> - a promise for the existance (true/false) of the file/dir at the path

Param	Type	Description
existsPath	`string`	the path to check

fs.listTree(directoryPath, filter) ⇒ `Promise.<Array.<string>>`

Custom implementation of q-io/fs#listTree to avoid dependency on q-io

Kind: static method of fs
Returns: Promise.<Array.<string>> - a promise for the collector, that is fulfilled after traversal

Param	Type	Description
directoryPath	`string`	the base path
filter	`function`	a function that returns true, false or null to show that a file should be included or ignored and that a directory should be ignored completely (null)

fs.list(directoryPath) ⇒ `Promise.<Array.<string>>`

Custom implementation of q-io/fs#list to avoid dependency on q-io

Kind: static method of fs
Returns: Promise.<Array.<string>> - a promise for the collector, that is fulfilled with a list of directory entries

Param	Type	Description
directoryPath	`string`	the base path