diff --git a/.gitignore b/.gitignore index fdb463b..c6206d7 100644 --- a/.gitignore +++ b/.gitignore @@ -55,3 +55,4 @@ npm-debug.log .directory ._* *.iml +examples/city \ No newline at end of file diff --git a/.thought/partials/api.md.hbs b/.thought/partials/api.md.hbs new file mode 100644 index 0000000..e8a6fe1 --- /dev/null +++ b/.thought/partials/api.md.hbs @@ -0,0 +1,7 @@ +{{#if package.main}} +## API-reference + +### `require("m-io/fs")` + +{{{jsdoc 'fs.js' '#'}}} +{{/if}} diff --git a/.thought/partials/overview.md.hbs b/.thought/partials/overview.md.hbs new file mode 100644 index 0000000..a924888 --- /dev/null +++ b/.thought/partials/overview.md.hbs @@ -0,0 +1,19 @@ +This package is a replacement for the functions of {{npm '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 {{npm 'collections'}}@1, which +[overwrites the function `Array.prototype.find` with an implementation that does not match the ES6-spec](https://github.com/montagejs/collections/issues/139). +This causes problems in {{npm 'jsdoc-parse'}}. This is another example of why [modifying objects you don’t own][zakas dont modify] +is a bad practice. + +This problem *could* be solved by using `q-io@2` instead of version 1. This version has [other problems](https://github.com/kriskowal/q-io/pull/155) 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. + + + + +[zakas dont modify]: https://www.nczonline.net/blog/2010/03/02/maintainable-javascript-dont-modify-objects-you-down-own/ \ No newline at end of file diff --git a/.thought/partials/usage.md.hbs b/.thought/partials/usage.md.hbs new file mode 100644 index 0000000..494f5cf --- /dev/null +++ b/.thought/partials/usage.md.hbs @@ -0,0 +1,16 @@ +{{#if (exists 'examples/example.js')}} + +## Usage + +The following example demonstrates how to use this module: + +{{{example 'examples/example.js'}}} + +This will generate the following output + +{{{exec 'node example.js' cwd='examples/'}}} +{{/if}} + +After deleting `city/usa`, the `city`-subtree looks liks this: + +{{dirTree 'examples' 'city/**'}} diff --git a/README.md b/README.md index 327e4d2..c7d23f0 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,27 @@ [![Coverage Status](https://img.shields.io/coveralls/nknapp/m-io.svg)](https://coveralls.io/r/nknapp/m-io) -> (Incomplete) replacement for `q-io` +> (Incomplete) replacement for q-io +This package is a replacement for the functions of [q-io](https://npmjs.com/package/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](https://npmjs.com/package/collections)@1, which +[overwrites the function `Array.prototype.find` with an implementation that does not match the ES6-spec](https://github.com/montagejs/collections/issues/139). +This causes problems in [jsdoc-parse](https://npmjs.com/package/jsdoc-parse). This is another example of why [modifying objects you don’t own][zakas dont modify] +is a bad practice. + +This problem *could* be solved by using `q-io@2` instead of version 1. This version has [other problems](https://github.com/kriskowal/q-io/pull/155) 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. + + + + +[zakas dont modify]: https://www.nczonline.net/blog/2010/03/02/maintainable-javascript-dont-modify-objects-you-down-own/ # Installation ``` @@ -20,24 +38,111 @@ npm install m-io The following example demonstrates how to use this module: ```js - +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')) + + // 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 ``` - +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' ] +undefined +Read file contents: New York is huge +Done ``` -## API-reference +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](#module_fs)
+ * [.listTree(directoryPath, filter)](#module_fs.listTree) ⇒ Promise.<Array.<string>>
+ * [.makeTree(aPath, [mode])](#module_fs.makeTree)
+ * [.read(aPath)](#module_fs.read)
+
+
+
+### .listTree(directoryPath, filter) ⇒ Promise.<Array.<string>>
+Custom implementation of [q-io/fs#listTree](http://documentup.com/kriskowal/q-io#listtreepath-guardpath-stat)
+to avoid dependency on q-io
+
+**Kind**: static method of [fs](#module_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) |
+
+
+
+### .makeTree(aPath, [mode])
+Replacement for [q-io/fs#makeTree](http://documentup.com/kriskowal/q-io#maketreepath-mode)
+
+**Kind**: static method of [fs](#module_fs)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| aPath | string
| the directory to be created |
+| [mode] | number
| (e.g. 0644) |
+
+
+
+### .read(aPath)
+Replacement for [q-io/fs#read](http://documentup.com/kriskowal/q-io#readpath-options)
-
+**Kind**: static method of [fs](#module_fs)
-## mIo()
-Describe your module here
+| Param |
+| --- |
+| aPath |
-**Kind**: global function
-**Access:** public
diff --git a/examples/example.js b/examples/example.js
index e69de29..33db0a1 100644
--- a/examples/example.js
+++ b/examples/example.js
@@ -0,0 +1,25 @@
+var FS = require('../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'))
+
+ // 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'))
diff --git a/fs.js b/fs.js
index d65b9a7..512faaf 100644
--- a/fs.js
+++ b/fs.js
@@ -11,12 +11,16 @@ var fs = require('fs')
var Q = require('q')
var path = require('path')
+/**
+ *
+ * @module
+ */
module.exports = {
/**
* Custom implementation of [q-io/fs#listTree](http://documentup.com/kriskowal/q-io#listtreepath-guardpath-stat)
* to avoid dependency on q-io
* @param {string} directoryPath the base path
- * @param {function(string,fs.Stats):boolean} filter a function that returns true, false or null to show that a file
+ * @param {function(string,fs.Stats):boolean=} filter 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)
* @returns {Promise