compound-callback-subtree

A subtree method that offers great flexibility and features to the developer.

npm i compound-callback-subtree

const CompoundCallbackSubTree = require("compound-callback-subtree");

Class: CompoundCallbackSubTree

new CompoundCallbackSubTree([options])

options <Object>
dirStatsCb <Function> Default: (branchData, callback) => callback() Optional
branchData <Object> Parameter required!
path <string>
This is the full-path of the currently found directory.
stats <fs.Stats>
This is the <fs.Stats> of the currently found directory.
branch <Object>
This is the branch of the currently found directory. All branches thogether fortake part of the end result tree that gets returend. Updating the branch affects the end result tree.
Contains data of the current directory that is found.
callback <Function> Parameter required!
Compound callback subtree is asynchrononous. When initiating another asynchronous process do make sure to invoke callback or else this phase and the end result tree get blocked.
Trees are generated by recursively finding files and directories starting from the path. In order to know if the currently found thing is a file or directory <fs.Stats> must be generated. When there is a directory found dirStatsCb is invoked.
fileStatsCb <Function> Default: (data, callback) => callback() Optional
branchData <Object> Parameter required!
path <string>
This is the full-path of the currently found file.
stats <fs.Stats>
This is the <fs.Stats> of the currently found file. Interesting properties could be birthtimeMs or size.
branch <Object>
This is the branch of the currently found file. All branches thogether take part of the end result tree that gets returend. Updating the branch affects the end result tree.
Contains data of the current file that is found.
callback <Function> Parameter required!
Compound callback subtree is asynchrononous. When initiating another asynchronous process do make sure to invoke callback or else this phase and the end result tree get blocked.
Trees are generated by recursively finding files and directories starting from the base-path. In order to know if the currently found thing is a file or directory <fs.Stats> must be generated. When there is a file found fileStatsCb is invoked.
subBranchCb <Function> Default: (data, nextBranch, blockBranch) => nextBranch()
branchData <Object> Parameter required!
path <string>
This is the full-path of the currently found file/directory.
dirpath <string>
This is the full-path of the parent directory in which the current file/directory is found in.
file <string>
This is the name of the currently found file/directory.
dirbranch <Object>
This is the branch of the parent directory. All branches thogether take part of the end result tree that gets returend. Updating the dirbranch affects the end result tree.
proceed <Function> Parameter required!
nextBranch <Object> | <undefined>
If the first argument nextBranch is passed to the proceed it becomes the next branch for that file/directory.
Compound callback subtree is asynchrononous. When initiating another asynchronous process do make sure to invoke proceed/block or else this phase and the end result tree get blocked. In case invoking proceed the process continues by calling fs.stat() on the currently found file/directroy.
block <Function> Parameter not required
Compound callback subtree is asynchrononous. When initiating another asynchronous process do make sure to invoke proceed/block or else this phase and the end result tree get blocked. In case invoking block the process ends and this file/directory is not taking part in the en result tree and therefore block is usefull for ignoring.
Trees are generated by recursively finding files and directories starting from the base-path. After having found a directory, with fs.readdir() each file gets passed through subBranchCb.
A substance formed from two or more elements chemically united in fixed proportions.

compoundCallbackSubTree.fromPath(path[,callback])

path <string>
This is the starting path from where a tree is generated from.
callback <Function> Default: (err, tree) => console.log(tree)
err <Null> | <Error>
The error returned from fs.stat() or fs.readdir().
tree <Object>
This is the end result tree. Check out the the example below to see a tree.
Compound callback subtree is asynchrononous.

Recursively generated a tree from a path. In order to increase efficiëncy, when invoking this method multiple times with the same path while the first process of that same path hasn't finished yet, the callback is appended to a callbacks array of the first process. When fromPath is invoked for different paths at the same time, the latter calls are queued untill the first process has finished, unless offcourse a separate instance of CompoundCallbackSubtree is processing the latter.

Example

/*
node_modules (root)
|__test.js
|__compund-callback-subtree
|     |__ .git
|     |     |__ etc...
|     |__ MONKEY.json
|     |__ index.js
|     |__ package.json
|     |__ README.md
|__etc...
*/
const CompoundCallbackSubTree = require("compound-callback-subtree");
const statCallback = (branchData, callback) => callback(branchData.branch.path = branchData.path);
const subtree = new CompoundCallbackSubTree({
    dirStatCb: statCallback,
    fileStatCb: statCallback,
    subBranchCb: (branchData, proceed, block) => branchData.file.includes(".git") ? block() : proceed()
});

// posix no absolute path
subtree.fromPath("./");
{
    path: './',
    'index.d.ts': { path: 'index.d.ts' },
    'index.js': { path: 'index.js' },
    'MONKEY.json': { path: 'MONKEY.json' },
    'package.json': { path: 'package.json' },
    'README.md': { path: 'README.md' }
}

// win32 with absolute path (only if process.platform === "win32")
subtree.fromPath(path.resolve("./"));
{
  path: 'D:\\js\\node_modules\\compound-callback-subtree',
  'index.d.ts': {
    path: 'D:\\js\\node_modules\\compound-callback-subtree\\index.d.ts'
  },
  'index.js': { path: 'D:\\js\\node_modules\\compound-callback-subtree\\index.js' },
  'MONKEY.json': {
    path: 'D:\\js\\node_modules\\compound-callback-subtree\\MONKEY.json'
  },
  'package.json': {
    path: 'D:\\js\\node_modules\\compound-callback-subtree\\package.json'
  },
  'README.md': {
    path: 'D:\\js\\node_modules\\compound-callback-subtree\\README.md'
  }
}

// posix with absolute path
subtree.fromPath(path.posix.resolve("./"));
{
  path: '/js/node_modules/compound-callback-subtree',
  'index.js': { path: '/js/node_modules/compound-callback-subtree/index.js' },
  'MONKEY.json': { path: '/js/node_modules/compound-callback-subtree/MONKEY.json' },
  'package.json': { path: '/js/node_modules/compound-callback-subtree/package.json' },
  'README.md': { path: '/js/node_modules/compound-callback-subtree/README.md' }
}
subtree.fromPath("./");