Windrive

SlimIO Windrive is a NodeJS binding which expose low-level Microsoft APIs on Logical Drive, Disk and Devices.

This binding expose the following methods/struct:

• GetLogicalDrives
• GetDiskFreeSpace
• GetDriveType
• QueryDosDevice
• DISK_PERFORMANCE
• DISK_GEOMETRY_EX
• DISK_CACHE_INFORMATION

!!! All method are called asynchronously without blocking the libuv event-loop !!!

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slimio/windrive
# or
$ yarn add @slimio/windrive

Usage example

Get all active logical drives and retrieve disk performance for each of them!

const windrive = require("@slimio/windrive");

async function main() {
    const logicalDrives = await windrive.getLogicalDrives();

    for (const drive of logicalDrives) {
        console.log(`drive name: ${drive.name}`);
        const diskPerformance = await windrive.getDevicePerformance(drive.name);
        console.log(diskPerformance);
    }
}
main().catch(console.error);

API

getLogicalDrives(): Promise< LogicalDrive[] >

Retrieves the currently available disk drives. An array of LogicalDrive is returned.

type LogicalDriveType = "UNKNOWN" | "NO_ROOT_DIR" | "REMOVABLE" | "FIXED" | "REMOTE" | "CDROM" | "RAMDISK";

export interface LogicalDrive {
    name: string;
    type: LogicalDriveType;
    bytesPerSect?: number;
    freeClusters?: number;
    totalClusters?: number;
    usedClusterPourcent?: number;
    freeClusterPourcent?: number;
}

Possible drive types are:

| type | description | | --- | --- | | UNKNOWN | The drive type cannot be determined. | | NO_ROOT_DIR | The root path is invalid; for example, there is no volume mounted at the specified path. | | REMOVABLE | The drive has removable media; for example, a floppy drive, thumb drive, or flash card reader. | | FIXED | The drive has fixed media; for example, a hard disk drive or flash drive. | | REMOTE | The drive is a remote (network) drive. | | CDROM | The drive is a CD-ROM drive. | | RAMDISK | The drive is a RAM disk. |

CDROM Type have no FreeSpaces (only name and type are returned).

getDosDevices(): Promise< DosDevices >

Retrieves information about MS-DOS device names. Return an key -> value Object where the key is the device name and value the path to the device.

interface DosDevices {
    [name: string]: string;
}

For example, you can filter the result to retrieves Logical and Physical Drives information & performance:

const isDisk = /^[A-Za-z]{1}:{1}$/;
const isPhysicalDrive = /^PhysicalDrive[0-9]+$/;
function isLogicalOrPhysicalDrive(driveNameStr) {
    return isDisk.test(driveNameStr) || isPhysicalDrive.test(driveNameStr) ? true : false;
}

async function main() {
    const dosDevices = await windrive.getDosDevices();
    const physicalAndLogicalDriveDevices = Object.keys(dosDevices).filter(isLogicalOrPhysicalDrive);
    const allDrivePerformance = await Promise.all(
        physicalAndLogicalDriveDevices.map(dev => windrive.getDevicePerformance(dev))
    );
    console.log(allDrivePerformance);
}
main().catch(console.error);

getDevicePerformance(deviceName: string): Promise< DevicePerformance >

Provides disk performance information about a given device (drive). Return a DevicePerformance Object.

interface DevicePerformance {
    bytesRead: number;
    bytesWritten: number;
    readTime: number;
    writeTime: number;
    idleTime: number;
    readCount: number;
    writeCount: number;
    queueDepth: number;
    splitCount: number;
    queryTime: number;
    storageDeviceNumber: number;
    storageManagerName: string;
}

getDiskCacheInformation(deviceName: string): Promise< DiskCacheInformation >

Provides information about the disk cache. Return a DiskCacheInformation Object.

The result of the property prefetchScalar define which of scalarPrefetch (true) or blockPrefect (false) should be filled/completed.

interface DiskCacheInformation {
    parametersSavable: boolean;
    readCacheEnabled: boolean;
    writeCacheEnabled: boolean;
    prefetchScalar: boolean;
    readRetentionPriority: "EqualPriority" | "KeepPrefetchedData" | "KeepReadData";
    writeRetentionPriority: number;
    disablePrefetchTransferLength: number;
    scalarPrefetch?: {
        minimum: number;
        maximum: number;
        maximumBlocks: number;
    };
    blockPrefetch?: {
        minimum: number;
        maximum: number;
    };
}

getDeviceGeometry(deviceName: string): Promise< DeviceGeometry >

Describes the geometry of disk devices and media. Return a DeviceGeometry Object.

interface DeviceGeometry {
    diskSize: number;
    mediaType: number;
    cylinders: number;
    bytesPerSector: number;
    sectorsPerTrack: number;
    tracksPerCylinder: number;
    partition: {
        diskId: string;
        size: number;
        style: "MBR" | "GPT" | "RAW";
        mbr: {
            signature: number;
            checksum: number;
        }
    };
    detection: {
        size: number;
        type: "ExInt13" | "Int13" | "None";
        int13?: {
            driveSelect: number;
            maxCylinders: number;
            sectorsPerTrack: number;
            maxHeads: number;
            numberDrives: number;
        };
        exInt13?: {
            bufferSize: number;
            flags: number;
            cylinders: number;
            heads: number;
            sectorsPerTrack: number;
            sectorsPerDrive: number;
            sectorSize: number;
            reserved: number;
        };
    }
}

Media type enumeration can be retrieved here.

How to build the project

Before building the project, be sure to get the following npm package installed:

• Install (or upgrade to) NodeJS v10+ and npm v6+
• Windows build tools

Then, just run normal npm install command:

$ npm install

Available commands

All projects commands are described here:

| command | description | | --- | --- | | npm run prebuild | Generate addon prebuild | | npm run doc | Generate JSDoc .HTML documentation (in the /docs root directory) | | npm run coverage | Generate coverage of tests | | npm run report | Generate .HTML report of tests coverage |

the report command have to be triggered after the coverage command.