find

find files or directories by path.

these functions are like the dir command. wild cards are allowed. both the block and non-block version contain a basic mode and progressive mode.

basic mode will wait till the search finishes and return all results in an array. the progressive mode will return every single result as soon as it is available. this mode is useful when you are listing many files or the callback has much works to do. during the process the file information might be outdated. if you don't want to waste another I/O on each file for doing this job, try this mode.

the value of property REPARSE_POINT_TAG could be one of CSV, DEDUP, DFS, DFSR, HSM, HSM2, MOUNT_POINT, NFS, PLACE_HOLDER, SIS, SYMLINK, WIM, UNKNOWN and an empty string(which means no tag). for more infomation see https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-win32_find_dataw

NOTE: if you don't need to use wildcards, you may wanna try fswin.getAttribues for better performance.

usage

callback:

fswin.find(pathToFind, callback, [isProgressiveMode]);

async:

var result = await fswin.findAsync(pathToFind);

sync:

var result = fswin.findSync(pathToFind, [syncCallback]);

• pathToFind is a string specifies the path to find. it may contain wildcards.
• isProgressiveMode is a bollean value to determine whether to use progressive callback, the default value is false.
• callback is a function. in basic mode it takes only one argument result. in progressive mode it takes 2 arguments event and message. for details see example.
• syncCallback is a function. if this argument is specified, fswin.findSync will run in progressive mode. the syncCallback function takes only one argument file to receive each file at a time. for example if there are 10 files found, this callback will be called 10 times. all callbacks return before the the main function returns.
• in basic mode, result is an array that contains all found files. in progressive mode, result is a number to indicate how many files are found.

example

var fswin = require('fswin');
var path = 'c:\\windows\\system32\\*';

//sync basic mode
var i;
var files = fswin.findSync(path);
for (i = 0; i < files.length; i++) {
	console.log(files[i].LONG_NAME + '	' + (files[i].IS_DIRECTORY ? '<DIR>' : files[i].SIZE));
}

//sync progressive mode
var n = fswin.findSync(path, function (file) {
	console.log(file.LONG_NAME + '	' + (file.IS_DIRECTORY ? '<DIR>' : file.SIZE));
	if (file.LONG_NAME.toLowerCase() === 'drivers') {
		return true; //stop the search process by returning this value
	}
});
console.log('found ' + n + ' file(s) or dir(s)');

//async basic mode
var working = fswin.find(path, function (files) {
	var i;
	for (i = 0; i < files.length; i++) {
		console.log(files[i].LONG_NAME + '	' + (files[i].IS_DIRECTORY ? '<DIR>' : files[i].SIZE));
	}
});
console.log(working ? 'job queued' : 'failed to queue job');

//async progressive mode
var working = fswin.find(path, function (event, message) {
	if (event === 'FOUND') {
		console.log(message.LONG_NAME + '	' + (message.IS_DIRECTORY ? '<DIR>' : message.SIZE));
		if (message.LONG_NAME.toLowerCase() === 'shell32.dll') {
			return true; //stop the search process by returning this value, and 'INTERRUPTED' event will fire
		}
	} else if (event === 'SUCCEEDED') {
		console.log('this operation is completed successfully. found ' + message + ' file(s) or dir(s)');
	} else if (event === 'FAILED') {
		console.log('unable to search next file. the result might be incomplete. found ' + message + ' file(s) or dir(s)');
	} else if (event === 'INTERRUPTED') {
		console.log('this operation is interrupted by user. found ' + message + ' file(s) or dir(s)');
	}
}, true);
console.log(working ? 'job queued' : 'failed to queue job');