kwaeri-node-kit-filesystem

A Massively Modified Open Source Project by kirvedx

The @kwaeri/filesystem component for the @kwaeri/node-kit application platform

TOC

• The Implementation
• Getting Started
  • Installation
  • Usage
• How to Contribute Code
• Other Ways to Contribute
  • Bug Reports
  • Vulnerability Reports
    • Confidential Issues
  • Donations

Updates

As of version 0.5.0 @kwaeri/filesystem is a pure ESM module which leverages the promises based fs library wrapper; Several changes to the implementation were made:

• All methods dropped type limiting
• All methods return boolean results, or null|undefined|string where applicable
• Extended types were removed; there are only two types now provided:
  • FilesystemEntry
  • FilesystemRecord
• GitLab specific tests were removed

The legacy implementation can be found on the legacy branch, and can be installed by targeting version 0.4.0.

The Implementation

@kwaeri/filesystem provides a wrapper for the NodeJS core fs module, and offers myriad methods for helping both simple and complex tasks which are commonly leveraged in everyday application logic. These methods allow developers to easily query the contents of a path, get the directory structure underlying a path, determine the types of resources found, check if resources exist, write resources, format file-name-safe and code-safe strings, sort a directory entry array alpha-numerically, and even get the full path to the current working directory, user directory, and system configuration directory.

The API is asynchronous, and uses promises, through and through. Most methods have a simple true/false expectation - string or null where applicable - and any rejections thrown bubble up.

Getting Started

The following sections cover how to get started with @kwaeri/filesystem. For a more formal experience, browse the online documentation.

Installation

Start off by installing the module in your project:

npm install @kwaeri/filesystem

Usage

To leverage the filesystem module, you'll first need to include it:

// INCLUDES
import { Filesystem } from '@kwaeri/filesystem';

Follow up by creating an instance of the filesystem object:

// DEFINES
const filesystem = new Filesystem();

Now you're ready to start manipulating the Filesystem object. It's recommended to take a look at the @kwaeri/configuration and @kwaeri/migration components - for now - to get a fairly good example of how to make use of the filesystem module.

How to Contribute Code

Our Open Source projects are always open to contribution. If you'd like to cocntribute, all we ask is that you follow the guidelines for contributions, which can be found at the Massively Modified Wiki

There you'll find topics such as the guidelines for contributions; step-by-step walk-throughs for getting set up, Coding Standards, CSS Naming Conventions, and more.

The project also leverages Keybase for communication and alerts - outside of standard email. To join our keybase chat, run the following from terminal (assuming you have keybase installed and running):

keybase team request-access kwaeri

Alternatively, you could search for the team in the GUI application and request access from there.

Other Ways to Contribute

There are other ways to contribute to the project other than with code. Consider testing the software, or in case you've found an Bug - please report it. You can also support the project monetarly through donations via PayPal.

Regardless of how you'd like to contribute, you can also find in-depth information for how to do so at the Massively Modified Wiki

Bug Reports

To submit bug reports, request enhancements, and/or new features - please make use of the issues system baked-in to our source control project space at Gitlab

You may optionally start an issue, track, and manage it via email by sending an email to our project's support desk.

For more in-depth documentation on the process of submitting bug reports, please visit the Massively Modified Wiki on Bug Reports

Vulnerability Reports

Our Vulnerability Reporting process is very similar to Gitlab's. In fact, you could say its a fork.

To submit vulnerability reports, please email our Security Group. We will try to acknowledge receipt of said vulnerability by the next business day, and to also provide regular updates about our progress. If you are curious about the status of your report feel free to email us again. If you wish to encrypt your disclosure email, like with gitlab - please email us to ask for our GPG Key.

Please refrain from requesting compensation for reporting vulnerabilities. We will publicly acknowledge your responsible disclosure, if you request us to do so. We will also try to make the confidential issue public after the vulnerability is announced.

You are not allowed, and will not be able, to search for vulnerabilities on Gitlab.com. As our software is open source, you may download a copy of the source and test against that.

Confidential Issues

When a vulnerability is discovered, we create a [confidential issue] to track it internally. Security patches will be pushed to private branches and eventually merged into a security branch. Security issues that are not vulnerabilites can be seen on our public issue tracker.

For more in-depth information regarding vulnerability reports, confidentiality, and our practices; Please visit the Massively Modified Wiki on Vulnerability

Donations

If you cannot contribute time or energy to neither the code base, documentation, nor community support; please consider making a monetary contribution which is extremely useful for maintaining the Massively Modified network and all the goodies offered free to the public.