m-io

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

fs.makeTree(aPath, [mode])

Replacement for q-io/fs#makeTree

Kind: static method of fs

Param	Type	Description
aPath	string	the directory to be created
[mode]	number	(e.g. 0644)

fs.read(aPath)

Replacement for q-io/fs#read

Kind: static method of fs

Param
aPath

fs.write(aPath, content)

Replacement for q-io/fs#write

Kind: static method of fs

Param
aPath
content

fs.copy(source, target)

Replacement for q-io/fs#copy

Kind: static method of fs

Param
source
target

fs.copyTree(source, target)

Replacement for q-io/fs#copyTree

Kind: static method of fs

Param
source
target

fs.stat(aPath)

Replacement for q-io/fs#stat

Kind: static method of fs

Param
aPath

fs.isDirectory(directory)

Replacement for q-io/fs#isDirectory

Kind: static method of fs

Param
directory

License

m-io is published under the MIT-license. See LICENSE.md for details.

Release-Notes

For release notes, see CHANGELOG.md

Contributing guidelines

See CONTRIBUTING.md.