fsprogress v1.0.0

fsprogress

fsprogress is a light-weight javascript (NodeJS) library to copy and move file(s), folder(s) along with method-call and event based progress tracking, managing concurrency of operation and a little more.

Installation

Use the package manager npm to install.

npm install fsprogress

Usage

const { DaemonicProgress } = require("fsprogress");
const dp = new DaemonicProgress("fullSourcePath", "fullDestinationPath");

Basic

dp.on("progress", (theFileData, overallSize, theFiles) => {
  // listen to event for progress
  // put your logic here for the file's progress
}).start();
// or
dp.start();
dp.getProgress(); // method call to get progress

Events

//register the events

// begin
dp.on("begin", (totalSize) => {
  console.log(totalSize); // 123456789
  // do something when got notified that the operation has finally begun
});

// progress
dp.on("progress", (theFileData, overallSize, theFiles) => {
  // do something with these progress data, especially with this file's (theFileData) progress.
});

// finish
dp.on("finish", (theFileData, overallSize, theFiles) => {
  // do something with these progress data, especially with this file's (theFileData) data when the operation of this file is complete.
});

// done
dp.on("done", (theFileData, overallSize, theFiles) => {
  console.log(theFileData); // {}
  // do something with thses progress data when the overall operation of source(s) is compelete.
});

// error
dp.on("error", (theFileData, overallSize, theFiles) => {
  console.log(theFileData.error); // some error message describing the error
  // do something with these progress data, especially with this file's data (theFileData) which has error value in it.
});

// aborted
dp.on("aborted", (theFileData, overallSize, theFiles) => {
  // do something with these progress data, especially with this file(s) (theFileData) data which consist a list of the file(s) thats aborted.
});

// and at last, you can simply start your operation
dp.start();

DaemonicOptions

// you can also pass callback(s) for an event in an array for registering event listeners.
const callbackOptions = {
  callbacks: [
    {
      event: "progress",
      callback: (theFileData, overallSize, theFiles) => {
        // do something here with the progress data for each file.
      },
    },
  ],
};

// you can make your progress event be emitted in timely fashion.
// emit progress forEvery 1000 milliseconds
const callbackOptions = {
  eventTiming: { unit: "ms", value: 1000, forEvery: true },
};

// emit progress forEvery 1MB of data being processed
const callbackOptions = {
  eventTiming: { unit: "ms", value: 1048576, forEvery: true },
};

// emit progress forEvery 10 percent of data being processed
const callbackOptions = {
  eventTiming: { unit: "percent", value: 10, forEvery: true },
};

// emit progress only once for 50 percent of data being processed
const callbackOptions = {
  eventTiming: { unit: "percent", value: 50, forEvery: false },
};

// emit progress only once after 10 seconds when file operation has begun
const callbackOptions = {
  eventTiming: { unit: "ms", value: 10000, forEvery: false },
};

const dp = new DaemonicProgress(
  "yourSourcePath",
  "yourDestinationPath",
  callbackOptions
);

Arguments | Options

Constructor Arguments

daemonicOptions?

callbackOptions?

callbackItem

eventTimingObject?

callbackArgs

theFileData

overallSize

events

units

Methods

const { DaemonicProgress } = new require("fsprogress");
const dp = new DaemonicProgress(yourSource, yourDestination, daemonicOptions);

• start(): void This method is called to start operation for the provided source(s). After calling this method, begin event will be emitted once calculation of total size of source(s) is done.

dp.start();

• abortOperation(file?: string | Array<string>): void This method aborts operation for the file(s) given in argument, or for all the file(s)/source(s) of this operation. After all the operation has been aborted, aborted event will be emited where the listener of this event will be called by passing callbackArgs where theFileData will be an array of file(s) specified by the user while manually aborting, or all file(s) if specified none or aborted internally.

// you can listen to the 'aborted' event
dp.on("aborted", (theFileData, overallSize, theFiles) => {
  console.log(theFileData); // ['fullFilePathname', ...]
  // do something
});

• getOverallSizes(): overallSize This method takes no argument and returns overallSize data. You can track progress of overall operation also via this method call.

dp.getOverallSizes(); // { totalBytesCopied: 12345, totalSize: 123456789 }

• getProgress(file?: string | null): { false | theFileData | Array<theFileData> } If filename is passed as an argument, this method will return theFileData for the specified file if the file exists in the progress record, else null. If nothing is passed as an argument, this method will return an array of theFileData for each file/source.

• getRegisteredOptions(): { src: Array<string>, dest: string, daemonicOptions } This method returns daemonicOptions along with passed source(s) and destination as an object.

• getFilesInOperation(): Array<string> This method returns the file(s) concurrently in operation as an array.

• eventNames(): events This method takes no argument and returns an array of all the event.

dp.eventNames(); //["begin", "progress", "finish", "done", "error", "abort", "aborted"]

Static Method

• getSizeOf(path: string): number This method returns the total size of the specified pathname of argument if exist, else 0.

• sizify(size: number): [number, string] This method returns the total size and unit closes to the matched unit, as an array.

DaemonicProgress.sizify(12345); // [ 12.0556640625, 'KB' ]

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT