recursive-readdir-async - npm Package Compare versions

Comparing version 1.1.3 to 1.1.4

module.js

 /**
  * project: recursive-readdir-async
  * author: m0rtadelo (ricard.figuls)
- * license: MIT
+ * @license MIT
  * 2018
  */
 'use strict'
+
+/**
+ * A fs.Stats object provides information about a file.
+ * @external stats
+ * @see https://nodejs.org/api/fs.html#fs_class_fs_stats
+ */
+
+/**
+ * Definition for the main Error object that contains information of the current exception
+ * @typedef Error
+ * @type {object}
+ * @property {object} error - The error object. The structure is variable
+ * @property {string} path - The path where the error is related to
+ */
+
+/**
+ * Definition for the Item object that contains information of files used but this module
+*  @typedef File
+*  @type {object}
+*  @property {string} name - The filename of the file
+*  @property {string} path - The path of the file
+*  @property {string} fullname - The fullname of the file (path & name)
+*  @property {string} [extension] - The extension of the file in lowercase
+*  @property {boolean} [isDirectory] - Always false in files
+*  @property {string} [data] - The content of the file in a base64 string
+*  @property {external:stats} [stats] - The stats (information) of the file
+*  @property {Error} [error] - If something goes wrong the error comes here
+*  @property {number} [deep] - The depth of current content
+*/
+
+/**
+ * Definition for the Item object that contains information of folders used but this module
+*  @typedef Folder
+*  @type {object}
+*  @property {string} name - The filename of the folder
+*  @property {string} path - The path of the folder
+*  @property {string} fullname - The fullname of the folder (path & name)
+*  @property {string} [extension] - The extension of the folder in lowercase
+*  @property {boolean} [isDirectory] - Always true in folders
+*  @property {File[]|Folder[]} [content] - Array of File/Folder content
+*  @property {Error} [error] - If something goes wrong the error comes here
+*  @property {number} [deep] - The depth of current content
+*/
+
+/**
+*  @typedef CallbackFunction
+*  @type {function}
+*  @param {File|Folder} item - The item object with all the required fields
+*  @param {number} index - The current index in the array/collection of Files and/or Folders
+*  @param {number} total - The total number of Files and/or Folders
+*  @returns {boolean} - true to delete the item from the list
+*/
+
 // constants
 /**
- * mode structure
+ * @readonly
+ * @enum {number} constant for mode LIST to be used in Options
  */
 const LIST = 1
+module.exports.LIST = LIST
+/**
+ * @readonly
+ * @enum {number} constant for mode TREE to be used in Options
+ */
 const TREE = 2
+module.exports.TREE = TREE
 /**
- * Native modules
+ * native FS module
+ * @see https://nodejs.org/api/fs.html#fs_file_system
+ * @external
  */
 const FS = require('fs')
+module.exports.fs = FS
+/**
+ * native PATH module
+ * @external
+ * @see https://nodejs.org/api/path.html#path_path
+ */
 const PATH = require('path')
-/**
+module.exports.path = PATH
+/*
  * Variables
@@ -25,4 +94,4 @@ */
  * Returns a Promise with Stats info of the item (file/folder/...)
- * @param {string} file
- * @returns {Promise} promise stat object info
+ * @param {string} file the name of the object to get stats from
+ * @returns {Promise<stat>} stat object information
  */
@@ -40,6 +109,7 @@ async function stat (file) {
 }
+module.exports.stat = stat
 /**
- * Returns a Promise with Stats info of the item (file/folder/...)
- * @param {string} file
- * @returns {Promise} promise stat object info
+ * Returns a Promise with content (data) of the file
+ * @param {string} file the name of the file to read content from
+ * @returns {Promise<string>} data content string (base64 format)
  */
@@ -57,7 +127,9 @@ async function readFile (file) {
 }
+module.exports.readFile = readFile
 /**
  * Returns if an item should be added based on include/exclude options.
- * @param {string} path item path
- * @param {object} settings options
- * @returns {boolean} returns if item must be added
+ * @param {string} path the item fullpath
+ * @param {Options} settings the options configuration to use
+ * @returns {boolean} if item must be added
+ * @private
  */
@@ -74,6 +146,7 @@ function checkItem (path, settings) {
  * Returns a Promise with an objects info array
- * @param {string} path the path to be searched for
- * @param {object} settings options
- * @param {number} deep folder depth
- * @returns {Promise} promise file object info
+ * @param {string} path the item fullpath to be searched for
+ * @param {Options} settings the options configuration to use
+ * @param {number} deep folder depth value
+ * @returns {Promise} the file object info
+ * @private
  */
@@ -126,4 +199,5 @@ async function myReaddir (path, settings, deep) {
      * Adds optional keys to item
-     * @param {object} obj item object
-     * @param {string} file filename
+     * @param {object} obj the item object
+     * @param {string} file the filename
+     * @private
      */
@@ -143,2 +217,3 @@ function addOptionalKeys (obj, file) {
  * @return {string} normalized path (unix style)
+ * @private
  */
@@ -151,5 +226,6 @@ function normalizePath (path) {
  * @param {string} path path
- * @param {object} settings options
+ * @param {object} settings the options to be used
  * @param {function} progress callback progress
- * @returns {object} array with file information
+ * @returns {object[]} array with file information
+ * @private
  */
@@ -178,5 +254,2 @@ async function listDir (path, settings, progress, deep) {
 
-        // do not check directory entries in TREE mode where we already know
-        // there's at least one(1) content entry which matches the `include`
-        // criteria:
         if (settings.mode === TREE && item.isDirectory && item.content) continue
@@ -194,6 +267,7 @@
  * @param {object} list items list
- * @param {object} settings options
+ * @param {object} settings the options to use
  * @param {function} progress callback progress
  * @param {number} deep folder depth
- * @returns {object} array with file information
+ * @returns {object[]} array with file information
+ * @private
  */
@@ -221,6 +295,7 @@ async function statDir (list, settings, progress, deep) {
  * @param {number} i index of item
- * @param {object} settings options
+ * @param {object} settings the options to use
  * @param {function} progress callback progress
  * @param {number} deep folder depth
- * @returns {object} array with file information
+ * @returns {object[]} array with file information
+ * @private
  */
@@ -253,7 +328,8 @@ async function statDirItem (list, i, settings, progress, deep) {
  * @param {string} path the path to start reading contents
- * @param {object} options options (mode, recursive, stats, ignoreFolders)
- * @param {function} progress callback with item data and progress info for each item
- * @returns {object} array with file information
+ * @param {Options} options options (mode, recursive, stats, ignoreFolders)
+ * @param {CallbackFunction} progress callback with item data and progress info for each item
+ * @returns {Promise<File[]|Folder[]>} promise array with file/folder information
+ * @async
  */
-async function list (path, options, progress) {
+module.exports.list = async function list (path, options, progress) {
   // options skipped?
@@ -264,2 +340,17 @@ if (typeof options === 'function') {
 
+  /**
+  *  @typedef Options
+  *  @type {object}
+  *  @property {LIST|TREE} mode - The list will return an array of items. The tree will return the items structured like the file system. Default: LIST
+  *  @property {boolean} recursive - If true, files and folders of folders and subfolders will be listed. If false, only the files and folders of the select directory will be listed. Default: true
+  *  @property {boolean} stats - If true a stats object (with file information) will be added to every item. If false this info is not added. Default: false.
+  *  @property {boolean} ignoreFolders - If true and mode is LIST, the list will be returned with files only. If true and mode is TREE, the directory structures without files will be deleted. If false, all empty and non empty directories will be listed. Default: true
+  *  @property {boolean} extensions - If true, lowercase extensions will be added to every item in the extension object property (file.TXT => info.extension = ".txt"). Default: false
+  *  @property {boolean} deep - If true, folder depth information will be added to every item starting with 0 (initial path), and will be incremented by 1 in every subfolder. Default: false
+  *  @property {boolean} realPath - Computes the canonical pathname by resolving ., .. and symbolic links. Default: true
+  *  @property {boolean} normalizePath - Normalizes windows style paths by replacing double backslahes with single forward slahes (unix style). Default: true
+  *  @property {string[]} include - Positive filter the items: only items which DO (partially or completely) match one of the strings in the include array will be returned. Default: []
+  *  @property {string[]} exclude - Negative filter the items: only items which DO NOT (partially or completely) match any of the strings in the exclude array will be returned. Default: []
+  *  @property {boolean} readContent -  Adds the content of the file into the item (base64 format). Default: false
+  */
   // Setting default settings
@@ -293,2 +384,3 @@ const settings = {
 
+  // sets the user settings
   function setOptions () {
@@ -332,46 +424,1 @@ if (options) {
 }
-module.exports = {
-  /**
-     * creates list object with content
-     * @preserve
-    */
-  LIST: LIST,
-  /**
-     * creates tree object with content
-     * @preserve
-    */
-  TREE: TREE,
-  /**
-     * Returns a javascript object with directory items information (non blocking async with Promises)
-     * @param {string} path the path to start reading contents
-     * @param {object} options options (mode, recursive, stats, ignoreFolders)
-     * @param {function} progress callback with item data and progress info for each item
-     * @returns {Promise} object array with file information
-     * @preserve
-     */
-  list: list,
-  /**
-     * Returns a Promise with Stats info of the item (file/folder/...)
-     * @param {string} file
-     * @returns {Promise} promise stat object info
-     * @preserve
-     */
-  stat: stat,
-  /**
-     * Returns a Promise with Stats info of the item (file/folder/...)
-     * @param {string} file
-     * @returns {Promise} promise stat object info
-     * @preserve
-     */
-  readFile: readFile,
-  /**
-     * Native FS module
-     * @preserve
-     */
-  fs: FS,
-  /**
-     * Native PATH module
-     * @preserve
-     */
-  path: PATH
-}

package.json

 {
   "name": "recursive-readdir-async",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Module to recursive read directory async (non blocking). Must be used with Promises. Configurable, extended filtering. etc.",
@@ -9,4 +9,4 @@ "main": "module.js",
     "coverage": "nyc --reporter=lcov --reporter=text-lcov npm test",
-    "coveralls": "nyc npm test && nyc report --reporter=text-lcov | coveralls",
-    "build": "uglifyjs --compress --mangle reserved=[file,path,options,progress] --comments -- module.js > module.min.js",
+    "coveralls": "jsdoc module.js -d ./docs -R ./README.md && nyc npm test && nyc report --reporter=text-lcov | coveralls",
+    "build": "uglifyjs --compress --mangle reserved=[file,path,options,progress] --comments -- module.js > module.min.js && jsdoc module.js -d ./docs -R ./README.md",
     "lint": "eslint ."
@@ -51,6 +51,7 @@ },
     "fs-extra": "^7.0.0",
+    "jsdoc": "^3.6.2",
     "mocha": "^5.2.0",
-    "nyc": "^13.3.0",
+    "nyc": "^14.1.1",
     "uglify-es": "^3.3.10"
   }
 }

README.md

@@ -213,2 +213,2 @@ [![Build Status](https://travis-ci.org/m0rtadelo/recursive-readdir-async.svg?branch=master)](https://travis-ci.org/m0rtadelo/recursive-readdir-async)
 ```
-More information in the Wiki page https://github.com/m0rtadelo/recursive-readdir-async/wiki
+More information on: https://m0rtadelo.github.io/recursive-readdir-async/global.html

No alert changes

Improved metrics

Total package byte prevSize

27969

increased by16.11%

Lines of code

388

increased by11.82%

Worsened metrics

Dev dependency count

12

increased by9.09%

No dependency changes