files-path

JS Library to List Files in a Folder List

Super simple to use

files-path is designed to be the simplest way possible to list files in a path.

var fp = require('files-path');
var files = fp.sync({
  basePath: 'tests/documents',
  path: 'dir-b/dir-z'
});
 
console.log(JSON.stringify(files, null, 2));

console output:

[
  {
    "name": "file-dir-b.txt",
    "path": "dir-b",
    "fullName": "tests/documents/dir-b/file-dir-b.txt",
    "fullPath": "tests/documents/dir-b"
  },
  {
    "name": "file-dir-z.txt",
    "path": "dir-b/dir-z",
    "fullName": "tests/documents/dir-b/dir-z/file-dir-z.txt",
    "fullPath": "tests/documents/dir-b/dir-z"
  }
]

Table of contents

• Methods
• Options
• Full Samples
• License

back to top

Methods

See: Options

Get files list synchronous

var files = require('files-path').sync(options);

Get files list asynchronous with callback

require('files-path').async(options, callback(err, files));

Get files list asynchronous with Promise

require('files-path').async(options).then(files).catch(err);

Require lib with default options and get files list synchronous

var files = require('files-path')(defaultOptions).sync(options);

Require lib with default options and get files list asynchronous with callback

require('files-path')(defaultOptions).async(options, callback(err, files));

Require lib with default options and get files list asynchronous with Promise

require('files-path')(defaultOptions).async(options).then(files).catch(err);

back to top

Options

basePath

Default: . (current folder)
Initial folder search
The files on this path will not be returned
./my/relative/initial/path

useBasePath

Default: false
The files distributed on this path will be listed
The files on this path will not be returned
./my/relative/initial/path

filters

Default: undefined
If you add at least one filter, only the files that match this filters will be returned

Note: If no filter is informed, all files are returned

---

Simple string

filters: ["*.txt", "*.js"]

---

Simple regex

filters: [ /^file.*m\.(txt|js)$/gi ]

---

Simple string with callback

filters: [ { pattern: "file*.txt", callback: function (file) {console.log(file.fullName)} ]

---

Simple regex with callback

filters: [ { pattern: /^file.*m\.(txt|js)$/gi, callback: function (file) {console.log(file.fullName)} ]

---

verbose

Default: false
Show logs on console

verboseFilters

Default: false
Depend of verbose:true
Filter logs.
Samples:
verboseFilters:['file-name.js']
verboseFilters:[/.*test\d+.*/g]
verboseFilters:['contained text', /.*\d{10}.*/g]

maxDeep

Default: 50
Maximum number of folders to be scanned

back to top

Full Samples

With this folder structure:

♦
└┄ ▼ tests
   └┄ ▼ documents
      ├┄ ▼ dir-a
      │  └┄ • file-dir-a.txt
      ├┄ ▼ dir-b
      │  ├┄ ▼ dir-x
      │  │  ├┄ ▼ dir-a
      │  │  │  └┄ • file-dir-a.txt
      │  │  ├┄ • 1file-dir-x.js
      │  │  └┄ • 2file-dir-x.txt
      │  └┄ • file-dir-b.txt
      └┄ • basePath.txt

Basic

var fp = require('files-path');
var files = fp.sync({
  basePath: 'tests/documents',
  path: 'dir-b/dir-x'
});
console.log(JSON.stringify(files, null, 2));

[
  {
    "name": "file-dir-b.txt",
    "path": "dir-b",
    "fullName": "tests\\documents\\dir-b\\file-dir-b.txt",
    "fullPath": "tests\\documents\\dir-b"
  },
  {
    "name": "1file-dir-x.js",
    "path": "dir-b\\dir-x",
    "fullName": "tests\\documents\\dir-b\\dir-x\\1file-dir-x.js",
    "fullPath": "tests\\documents\\dir-b\\dir-x"
  },
  {
    "name": "2file-dir-x.txt",
    "path": "dir-b\\dir-x",
    "fullName": "tests\\documents\\dir-b\\dir-x\\2file-dir-x.txt",
    "fullPath": "tests\\documents\\dir-b\\dir-x"
  }
]

Use basePath + Simple Filters (string, regex and callback)

var fp = require('files-path');
fp.sync({
  basePath: 'tests/documents',
  path: 'dir-b/dir-x',
  useBasePath: true,
  filters: [{
    pattern: '*.js',
    callback: function (file) {
      console.log('filter1: ' + file.name);
    }
  }, {
    pattern: /^[a-zA-Z\.]+$/g,
    callback: function (file) {
      console.log('filter2: ' + file.fullName);
    },
  }]
});

filter2: tests\documents\basePath.txt
filter1: 1file-dir-x.js

Use default options

var fp = require('files-path')({
  basePath: 'tests/documents'
});
var exec1 = fp.sync({
  path: 'dir-b/dir-x',
  filters: ['*.txt']
});
var exec2 = fp.sync({
  path: 'dir-a'
});
console.log(JSON.stringify(exec1, null, 2));
console.log('--');
console.log(JSON.stringify(exec2, null, 2));

[
  {
    "name": "file-dir-b.txt",
    "path": "dir-b",
    "fullName": "tests\\documents\\dir-b\\file-dir-b.txt",
    "fullPath": "tests\\documents\\dir-b"
  },
  {
    "name": "2file-dir-x.txt",
    "path": "dir-b\\dir-x",
    "fullName": "tests\\documents\\dir-b\\dir-x\\2file-dir-x.txt",
    "fullPath": "tests\\documents\\dir-b\\dir-x"
  }
]
--
[
  {
    "name": "file-dir-a.txt",
    "path": "dir-a",
    "fullName": "tests\\documents\\dir-a\\file-dir-a.txt",
    "fullPath": "tests\\documents\\dir-a"
  }
]

Basic Asyncronous with Callback

var fp = require('files-path');
var files = fp.async({
  basePath: 'tests/documents',
  path: 'dir-b/dir-x',
  filters: '*.txt'
}, function(err, files) {
  if (err) console.log(JSON.stringify(err, null, 2));
  console.log(JSON.stringify(files, null, 2));
});

[
  {
    "name": "file-dir-b.txt",
    "path": "dir-b",
    "fullName": "tests\\documents\\dir-b\\file-dir-b.txt",
    "fullPath": "tests\\documents\\dir-b"
  },
  {
    "name": "2file-dir-x.txt",
    "path": "dir-b\\dir-x",
    "fullName": "tests\\documents\\dir-b\\dir-x\\2file-dir-x.txt",
    "fullPath": "tests\\documents\\dir-b\\dir-x"
  }
]

Basic Asyncronous with Promise

var fp = require('files-path');
var files = fp.async({
  basePath: 'tests/documents',
  path: 'dir-b/dir-x',
  filters: '*.txt'
}).then(function(files) {
  console.log(JSON.stringify(files, null, 2));
}).catch(function(err) {
  console.log(JSON.stringify(err, null, 2))
});

[
  {
    "name": "file-dir-b.txt",
    "path": "dir-b",
    "fullName": "tests\\documents\\dir-b\\file-dir-b.txt",
    "fullPath": "tests\\documents\\dir-b"
  },
  {
    "name": "2file-dir-x.txt",
    "path": "dir-b\\dir-x",
    "fullName": "tests\\documents\\dir-b\\dir-x\\2file-dir-x.txt",
    "fullPath": "tests\\documents\\dir-b\\dir-x"
  }
]

back to top

Todo list

• filter by function
• make log.js to become an external npm package

License

Apache-2.0 © Flavio L Sousa (flasoft@gmail.com)