list-contents

Description

list-contents is a module that returns a list of paths to the subfolders and subfiles of the specified location.

• Any bugs found? Give me to know on [e-mail] or on GitHub
• Also check out file-assistant package that creates, copies or moves the folders and files into the specified path or modifies the files' content according to the given [Array] object (or .json file path) instructions.

Installation

npm install list-contents

const list = require('list-contents');

Usage

list(path,[config,]callback)

path [String]

• It should indicate the path to the chosen directory, which subfolders and subfiles should be listed

config [Object|Number|null]

• if omitted, the parameters are set to their default values [see below]
• if [Number], it sets deep to [Number] [see below]
• if [null], it sets deep to null [see below]
• if [Object], it takes the following properties:
  • deep [Number|null] (default:null) It indicates how deep the list-contents should explore the folders in the given path directory.
    If set to null (default) it lists all subfiles and subfolders of all levels of the path directory.
    If set to 1 it lists only the folders and files of the path directory.
    If set to 2 it lists the elements of the path directory and the contents of the path directory's folders.
    etc.
  • exclude [Array|String]
    It indicates the folders' and files' paths that should be ignored and not included into the files, dirs and inaccessible lists.
    If the folder is indicated, neither the folder nor its contents will be included. When [String], it can indicate the one path to ignore, eg "./bin" . When [Array], it can indicate more than one path to ignore, eg. ["./node_modules", "./bin"].
    The given paths must be relative to the path.
    You can ignore needless paths, eg. './node_modules' or './.git' to make the module faster.

const listContents = require('list-contents');

listContents('./dist', (data)=>{/*...*/});
listContents('./dist', null, (data)=>{/*...*/});
listContents('./dist', 3, (data)=>{/*...*/});
listContents('./dist', {deep: 5}, (data)=>{/*...*/});
listContents('./dist', {deep: 3, exclude: ['node_modules','.git']}, (data)=>{/*...*/})

callback [Function]

• the [Object] argument is passed through callback function. It has 5 properties:
  • error [Boolean|Error] null if the path is valid, otherwise [Error] object
  • dirs [Array]
    The list of all subfolders' paths of the specified path argument
  • files [Array]
    The list of all subfiles' paths of the specified path argument
  • inaccessible [Array] v3.*.*
    The list of all unrecognized or inaccessible elements' paths of the specified path argument.
    If the file or folder is inaccessible, it does not stop retrieving the further files and folders.
  • path [String]
    The path that was given as path parameter

const list = require('list-contents');

list("./dist",(o)=>{
  if(o.error) throw o.error;
  console.log('Folders: ', o.dirs);
  console.log('Files: ', o.files);
});

Samples

Assuming that "./dist" path contains the following subfolders and subfiles:

dist
 ├ scripts
 │  ├ index.js
 │  └ ajax.js
 ├ styles
 │  ├ css   
 │  │  ├ layout.css
 │  │  └ media.css
 │  └ scss
 │     └ mixins.scss
 └ templates
    ├ main.html
    ├ menubar.html
    ├ login.html
    └ contact.html

the module will pass the following object through the callback function:

{
  error: null,
  path: "./dist",
  dirs: [
    'scripts',
    'templates',
    'styles',
    'styles/css',
    'styles/scss'
  ],
  files: [
    'scripts/ajax.js',
    'scripts/index.js',
    'templates/contact.html',
    'templates/login.html',
    'templates/main.html',
    'templates/menubar.html',
    'styles/css/layout.css',
    'styles/css/media.css',
    'styles/scss/mixins.scss'
  ],
  inaccessible: []
}