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

Name	Description	Type	Default
source	full path name(s).	string | Array
destination	full directory name.	string
options	full directory name.	daemonicOptions	{ log: false, resume: false, chunkSize: 4096, mode: 'copy', maxConcurrentOperation: 1, abortAllOnError: false, callbackOptions: { eventTiming: { unit: 'ms', value: 1000, forEvery: true } } }

daemonicOptions?

Property	Description	Type	Default
log	Whether to log on to console about what's happening	boolean	false
resume	Whether to resume file from how much data it currently has. Having value false means overwriting the file	boolean	false
chunkSize	file's data size to read at a time for writing	number	4096
mode	Mode of operation. Values can be either 'copy' or 'move'.	string	copy
mode	Whether to log on to console about what's happening	boolean	false
maxConcurrentOperation	Number of concurrent operation to process at a time. 0 indicates no limit.	number	1
abortAllOnError	Whether to abort complete operation (for all files) if an error occurs for any file.	boolean	false
callbackOptions	Callback options for overall operation	callbackOptions

callbackOptions?

Property	Description	Type	Default
callbacks	Callback item(s) for the operation	Array
eventTiming	Callback item(s) for the operation	eventTimingObject	{ unit: 'ms', value: 1000, forEvery: true }

callbackItem

Property	Description	Type	Default
event	Name of event to listen to.	event
callback	Callback function to execute.	(callbackArgs)=>{}

eventTimingObject?

Property	Description	Type	Default
unit	Unit on which the progress event emission is based on. See unit list.	string	ms
value	Value based on the unit for which the progress event will be emitted. It's like a timing.	number	1000
forEvery	Whether the progress event should be emitted for every value as per unit.	boolean	true

callbackArgs

Property	Description	Type	Default
theFileData	Data about the status of the file for which the event is emitted.	theFileDataObject
overallSize	Overall size data for the whole operation.	overallSizeData
theFiles	Data about the status of all the files of the source(s).	Array

theFileData

Property	Description	Type	Default
file	Name of the file (full pathname) for the event is based on.	string
totalBytesCopied	Total bytes processed for the file.	number
totalSize	Total size of the file.	number
startTime	Start time of the file's operation.	Date
endTime	End time of the file's operaiton.	Date
error?	Error object for the file's operation if any.	Error

overallSize

Property	Description	Type	Default
totalBytesCopied	Total bytes processed for all the file(s)/source(s).	number
totalSize	Total size of all the file(s)/source(s).	number

events

Event	Description
begin	This event will emit once the overall source(s) totalSize has been calculated. The listener of this event will be called by passing totalSize of all the source(s) as an argument. This event also indicates that the actual operation has now begun. You can also show some sort of message like 'Calculating total size...' to the user after calling start() and before this event is emitted, and then you can show actual progress of the operation once the operation has begun.
progress	This event will be emitted as per eventTiming option for an individual file. The listener of this event will be called by passing callbackArgs.
finish	This event will be emitted whenever a file's operation has been completed successfully without an error. The listener of this event will be called by passing callbackArgs.
done	This event will be emitted when overall operation is complete with or without any error(s). i.e. of every source(s). The listener of this event will be called by passing callbackArgs where theFileData will be an empty object. If mode is 'move' for the daemonicOptions, deletion of overall source(s) will begin after this event has been emitted.
error	This event will be emitted if any error occurs while processing a file. This indicates that the file's operation has been completed with an error. The listener of this event will be called by passing callbackArgs.
abort	This event can be emitted to abort operation for all or any specific file(s). While emitting this event, you could pass a string, Array of full file pathname for aborting operation of the file(s) or pass nothing to abort all operations.
aborted	This event will be emitted when operation for file(s) are aborted either internally or manually by the user via abortOperation method. 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.

units

Value	Description
ms	Milliseconds for which the progress event should be emitted as per the value specified in eventTiming options.
bytes	Bytes for which the progress event should be emitted as per the value specified in eventTiming options.
percent	Percent for which the progress event should be emitted as per the value specified in eventTiming options.

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