draxt.js – NodeList-like/jQuery-like package for File System (node.js)

Draxt is an open-source utility module for selecting and manipulating filesystem objects in a Node.js environment. It uses glob patterns as its "selector engine" to select filesytem objects (files, directories, ...).

Draxt also provides several DOM-like interfaces representing filesystem objects which build on promisified APIs for the fs and fs-extra.

Why?

Writing readble and maintable code by using node fs module is not an easy task. One usually has to write helper structures for doing basic and common tasks. Draxt is an attempt for faciliating this process. The library, in addition to wrappers for promisified fs and fs-extra module APIs, provides several DOM/jQuery-like APIs for selecting and manipulating files and directories and traversing filesystem.

Key Points

Draxt has only 2 dependencies: glob and fs-extra modules.
Draxt uses glob patterns to select filesystem objects.
Each item in a draxt collection is an instance of a File, Directory, or SymbolicLink class, which is a subclass of Node.
Every asynchronous method has a synchronous version. E.g., node.siblingsSync() for node.siblings().
Interfaces function-wrappers for fs and fs-extra functions use the same names as the original functions. E.g. file.lchmod() is a wrapper for promisified fs.lchmod().
Interfaces synchronous methods that do not work as a getter – like the node.chmodSync() – are chainable.
draxt is a simple constructor function. You can extend/overwrite its methods via its prototype property (or its fn alias) or by using the draxt.extend() method.

The project is hosted on GitHub. You can report bugs and discuss features on the issues page.

Example

// Let's use a familiar variable name!
const $ = require('draxt');

(async () => {
// Select `/app` directory contents and create a new `draxt` collection.
const $app = await $('/app/**');
$app
  // Let's filter js files:
  .filter(node => node.extension === 'js')
  // Now we have a new `draxt` collection with 2 nodes.
  .forEach(async (node, index, allNodes) => {
    // `node` is instance of `File` class. Because it's a file!
    console.log(node.pathName);
    // → '/app/controllers/index.js' for the first node!

    console.log(node instanceof $.File); // → `true`

    // Let's get contents of the node. `file.read` returns a promise object.
    const content = await node.read('utf8');

    // Let's use some synchronous methods!
    node.appendSync('\na new line!')
        .chmodSync('765')
        // move the file into another directory!
        .appendToSync('/hell') // or `.moveToSync('/hell')`

    console.log(node.pathName);
    // → '/hell/index.js' for the first node in the list!

    // get the parent directory of the node.
    // returns a `Directory` instance with the pathName of '/hell'!
    const parentNode = node.parentSync(); // or `await node.parent()`

    // is the directory empty?
    console.log(parentNode.isEmptySync()); // → `false`
});
})();

Installation

npm npm install draxt
yarn yarn add draxt

Queries (Globbing)

draxt module exports a constructor function. Whenever a string is passed as the first parameter to the function, parameters are passed to the glob package. The matching pathNames returned by the glob package, if any, are converted into an array of node instances. The returned value of draxt is a draxt instance (a draxt collection) which wraps an array of nodes. In this respect, draxt constructor function works like jQuery function, but unlike jQuery collections, draxt collections are not array-like objects. draxt collections store the array of nodes as a property named items. The length property of draxt collections is a getter for the collection's items.length property.

// Let's use a familiar variable name!
const $ = require('draxt')
// glob options
const globOptions = { dot: true }

// using await syntax in an async function context
(async () => {
  const draxtCollection = await $('/example_pattern/**', globOptions)
})()

// using promises
$('/example_pattern/**').then(draxtCollection => {
  // ...
})

// synchronous query
const draxtCollection = $.sync('/example_pattern/**', globOptions)

Draxt

draxt function is the main method of draxt package. The function can be called with new as a constructor function (not recommended) and without new as a factory function. draxt uses promisified glob package as it's selector engine. All query results of glob package are converted into one of Node's sub-class (File, Directory or SymbolicLink) instances by analyzing pathNames' fs.Stats object. The returned value of draxt is a draxt collection which to some extent works like jQuery collections but unlike jQuery collections it's not an array-like object. The collection items are stored as an array property (.items).

Syntax:

const draxtCollection = draxt([pattern, options])

pattern (string|array.<node>|node|draxt) – pattern parameter can contain several values:
- string which is passed to glob package as glob pattern. In this case draxt returns a promise object representing a draxt collection/instance.
- A Node or one it's sub-classes (File, Directory or SymbolicLink) instance. In this case a draxt collection containing the passed node is returned.
- An array of node instances.
- A draxt collection to clone (shallow).
- undefined which returns an empty draxt collection.
options (object|string) – Options for glob package. The options parameter can also be a string representing a pathName which will be used as context for the query, similar to jQuery's $(selector, context) syntax.

→ promise.<draxt> | draxt

Static Methods:

draxt.sync(pattern [, options])

pattern (string) – Glob pattern.
options (object) – Options for glob package.

Synchronously query the file system by using glob package and return a new draxt collection.

→ draxt An instance of draxt, a.k.a. a draxt collection.

Interfaces

Inherited Static Methods

Inherited Methods

Inherited Static Methods

Inherited Methods

Inherited Static Methods

Inherited Methods