fswin32

The ultimate Node.js module for detailed Windows file system access. This module provides a comprehensive set of tools for interacting with the Windows file system, including drives, files, folders, permissions, symbolic links, system info, network drives, the recycle bin, advanced search, and file watching.

Installation

npm install fswin32

Usage

import * as fswin32 from 'fswin32';

// Example: Get a list of accessible drives
async function listDrives() {
  try {
    const drives = await fswin32.getAccessibleDrives();
    console.log('Accessible Drives:', drives);
  } catch (error) {
    console.error('Error getting drives:', error);
  }
}

listDrives();

API Reference

Drives

getAccessibleDrives()

Gets a list of accessible Windows drives. This function iterates through all possible drive letters (A-Z) and checks for their accessibility.

• Returns: Promise<Array<string>> - A promise that resolves to an array of accessible drive letters (e.g., ['C', 'D']).

• Example:

  import { getAccessibleDrives } from 'fswin32';
  
  async function showDrives() {
    try {
      const drives = await getAccessibleDrives();
      console.log('Available drives:', drives);
    } catch (error) {
      console.error('Failed to get drives:', error);
    }
  }
  
  showDrives();

getDriveDetails(driveLetter)

Gets detailed information about a specific Windows drive, including total space, free space, and volume name.

• Parameters:

  • driveLetter (string) - The letter of the drive to get details for (e.g., 'C').

• Returns: Promise<Object|null> - A promise that resolves to an object containing drive details, or null if the drive is not found or an error occurs. The object has the following properties:

  • drive: The drive letter.
  • volumeName: The name of the volume.
  • totalSpace: Total space in a human-readable format.
  • freeSpace: Free space in a human-readable format.
  • usedSpace: Used space in a human-readable format.
  • totalSpaceBytes: Total space in bytes.
  • freeSpaceBytes: Free space in bytes.
  • usedSpaceBytes: Used space in bytes.

• Example:

  import { getDriveDetails } from 'fswin32';
  
  async function showDriveDetails(drive) {
    try {
      const details = await getDriveDetails(drive);
      if (details) {
        console.log(`Details for drive ${drive}:`, details);
      } else {
        console.log(`Drive ${drive} not found.`);
      }
    } catch (error) {
      console.error(`Error getting details for drive ${drive}:`, error);
    }
  }
  
  showDriveDetails('C');

Files

getFileDetails(filePath)

Gets detailed information about a specific file.

• Parameters:

  • filePath (string) - The absolute path of the file.

• Returns: Promise<Object|null> - An object with detailed file information, or null on failure.

• Example:

  import { getFileDetails } from 'fswin32';
  
  async function showFileDetails(file) {
    try {
      const details = await getFileDetails(file);
      console.log('File Details:', details);
    } catch (error) {
      console.error('Error getting file details:', error);
    }
  }
  
  showFileDetails('C:\Users\Public\Documents\example.txt');

Folders

getFolderDetails(folderPath)

Gets detailed information about a specific folder.

• Parameters:

  • folderPath (string) - The absolute path of the folder.

• Returns: Promise<Object|null> - An object with detailed folder information, or null on failure.

• Example:

  import { getFolderDetails } from 'fswin32';
  
  async function showFolderDetails(folder) {
    try {
      const details = await getFolderDetails(folder);
      console.log('Folder Details:', details);
    } catch (error) {
      console.error('Error getting folder details:', error);
    }
  }
  
  showFolderDetails('C:\Users\Public\Documents');

getFolderSizeAndCount(folderPath)

Recursively calculates the size of a folder and counts its contents.

• Parameters:

  • folderPath (string) - The absolute path of the folder.

• Returns: Promise<{totalSize: number, fileCount: number, folderCount: number}> - An object with the total size in bytes, number of files, and number of subfolders.

• Example:

  import { getFolderSizeAndCount } from 'fswin32';
  
  async function showFolderSize(folder) {
    try {
      const info = await getFolderSizeAndCount(folder);
      console.log('Folder Size Info:', info);
    } catch (error) {
      console.error('Error getting folder size:', error);
    }
  }
  
  showFolderSize('C:\Users\Public\Documents');

Permissions

getPermissions(path)

Gets the permissions of a file or folder using icacls.

• Parameters:

  • path (string) - The absolute path of the file or folder.

• Returns: Promise<string|null> - The output of the icacls command, or null on failure.

• Example:

  import { getPermissions } from 'fswin32';
  
  async function showPermissions(path) {
    try {
      const permissions = await getPermissions(path);
      console.log('Permissions:', permissions);
    } catch (error) {
      console.error('Error getting permissions:', error);
    }
  }
  
  showPermissions('C:\Users\Public\Documents\example.txt');

setPermissions(path, user, permissions)

Sets the permissions of a file or folder using icacls.

• Parameters:

  • path (string) - The absolute path of the file or folder.
  • user (string) - The user to set the permissions for.
  • permissions (string) - The permissions to set (e.g., 'F' for full access, 'M' for modify, 'RX' for read and execute).

• Returns: Promise<string|null> - The result of the command, or null on failure.

• Example:

  import { setPermissions } from 'fswin32';
  
  async function grantFullAccess(path, user) {
    try {
      await setPermissions(path, user, 'F');
      console.log(`Full access granted to ${user} for ${path}`);
    } catch (error) {
      console.error('Error setting permissions:', error);
    }
  }
  
  grantFullAccess('C:\Users\Public\Documents\example.txt', 'Users');

takeOwnership(path)

Takes ownership of a file or folder.

• Parameters:

  • path (string) - The absolute path of the file or folder.

• Returns: Promise<string|null> - The result of the command, or null on failure.

• Example:

  import { takeOwnership } from 'fswin32';
  
  async function claimOwnership(path) {
    try {
      await takeOwnership(path);
      console.log(`Ownership of ${path} taken.`);
    } catch (error) {
      console.error('Error taking ownership:', error);
    }
  }
  
  claimOwnership('C:\Users\Public\Documents\example.txt');

Symbolic Links

createSymbolicLink(source, destination, isDirectory)

Creates a symbolic link.

• Parameters:

  • source (string) - The path where the symbolic link will be created.
  • destination (string) - The path that the symbolic link will point to.
  • isDirectory (boolean) - Set to true if the destination is a directory. Defaults to false.

• Returns: Promise<string|null> - The result of the command, or null on failure.

• Example:

  import { createSymbolicLink } from 'fswin32';
  
  async function createLink(source, destination) {
    try {
      await createSymbolicLink(source, destination);
      console.log(`Symbolic link created from ${source} to ${destination}`);
    } catch (error) {
      console.error('Error creating symbolic link:', error);
    }
  }
  
  createLink('C:\Users\Public\Documents\my_link.txt', 'C:\Users\Public\Documents\example.txt');

isSymbolicLink(path)

Checks if a path is a symbolic link.

• Parameters:

  • path (string) - The path to check.

• Returns: Promise<boolean> - true if the path is a symbolic link, false otherwise.

• Example:

  import { isSymbolicLink } from 'fswin32';
  
  async function checkLink(path) {
    try {
      const isLink = await isSymbolicLink(path);
      console.log(`Is ${path} a symbolic link? ${isLink}`);
    } catch (error) {
      console.error('Error checking symbolic link:', error);
    }
  }
  
  checkLink('C:\Users\Public\Documents\my_link.txt');

readSymbolicLink(path)

Reads the target of a symbolic link.

• Parameters:

  • path (string) - The path of the symbolic link.

• Returns: Promise<string|null> - The target of the symbolic link, or null on failure.

• Example:

  import { readSymbolicLink } from 'fswin32';
  
  async function getLinkTarget(path) {
    try {
      const target = await readSymbolicLink(path);
      console.log(`Target of ${path}: ${target}`);
    } catch (error) {
      console.error('Error reading symbolic link:', error);
    }
  }
  
  getLinkTarget('C:\Users\Public\Documents\my_link.txt');

Info

getSystemInfo()

Gets detailed system information.

• Returns: Promise<Object> - An object with system information.

• Example:

  import { getSystemInfo } from 'fswin32';
  
  async function showSystemInfo() {
    try {
      const info = await getSystemInfo();
      console.log('System Info:', info);
    } catch (error) {
      console.error('Error getting system info:', error);
    }
  }
  
  showSystemInfo();

getDiskUsage()

Gets disk usage information for all drives.

• Returns: Promise<Array<Object>> - An array of objects with disk usage information for each drive.

• Example:

  import { getDiskUsage } from 'fswin32';
  
  async function showDiskUsage() {
    try {
      const usage = await getDiskUsage();
      console.log('Disk Usage:', usage);
    } catch (error) {
      console.error('Error getting disk usage:', error);
    }
  }
  
  showDiskUsage();

Network

mapNetworkDrive(driveLetter, remotePath)

Maps a network drive.

• Parameters:

  • driveLetter (string) - The drive letter to map (e.g., 'Z').
  • remotePath (string) - The remote path to map (e.g., '\server\share').

• Returns: Promise<string|null> - The result of the command, or null on failure.

• Example:

  import { mapNetworkDrive } from 'fswin32';
  
  async function mapDrive(letter, path) {
    try {
      await mapNetworkDrive(letter, path);
      console.log(`Drive ${letter} mapped to ${path}`);
    } catch (error) {
      console.error('Error mapping network drive:', error);
    }
  }
  
  mapDrive('Z', '\\server\share');

unmapNetworkDrive(driveLetter)

Unmaps a network drive.

• Parameters:

  • driveLetter (string) - The drive letter to unmap.

• Returns: Promise<string|null> - The result of the command, or null on failure.

• Example:

  import { unmapNetworkDrive } from 'fswin32';
  
  async function unmapDrive(letter) {
    try {
      await unmapNetworkDrive(letter);
      console.log(`Drive ${letter} unmapped.`);
    } catch (error) {
      console.error('Error unmapping network drive:', error);
    }
  }
  
  unmapDrive('Z');

getMappedDrives()

Gets a list of mapped network drives.

• Returns: Promise<Array<Object>|null> - A list of mapped network drives, or null on failure.

• Example:

  import { getMappedDrives } from 'fswin32';
  
  async function showMappedDrives() {
    try {
      const drives = await getMappedDrives();
      console.log('Mapped Drives:', drives);
    } catch (error) {
      console.error('Error getting mapped drives:', error);
    }
  }
  
  showMappedDrives();

Recycle Bin

moveToRecycleBin(path)

Moves a file or folder to the recycle bin.

• Parameters:

  • path (string) - The absolute path of the file or folder.

• Returns: Promise<string|null> - The result of the command, or null on failure.

• Example:

  import { moveToRecycleBin } from 'fswin32';
  
  async function recycleFile(path) {
    try {
      await moveToRecycleBin(path);
      console.log(`${path} moved to recycle bin.`);
    } catch (error) {
      console.error('Error moving to recycle bin:', error);
    }
  }
  
  recycleFile('C:\Users\Public\Documents\example.txt');

getRecycleBinItems()

Gets a list of items in the recycle bin.

• Returns: Promise<Array<Object>|null> - A list of items in the recycle bin, or null on failure.

• Example:

  import { getRecycleBinItems } from 'fswin32';
  
  async function showRecycleBin() {
    try {
      const items = await getRecycleBinItems();
      console.log('Recycle Bin Items:', items);
    } catch (error) {
      console.error('Error getting recycle bin items:', error);
    }
  }
  
  showRecycleBin();

emptyRecycleBin()

Empties the recycle bin.

• Returns: Promise<string|null> - The result of the command, or null on failure.

• Example:

  import { emptyRecycleBin } from 'fswin32';
  
  async function clearRecycleBin() {
    try {
      await emptyRecycleBin();
      console.log('Recycle bin emptied.');
    } catch (error) {
      console.error('Error emptying recycle bin:', error);
    }
  }
  
  clearRecycleBin();

Search

searchFiles(directory, pattern, options)

Searches for files based on various criteria.

• Parameters:

  • directory (string) - The directory to search in.
  • pattern (string) - The file name pattern to search for (e.g., '*.txt').
  • options (Object) - The search options:
    • content (string) - The content to search for in the files.
    • minSize (number) - The minimum file size in bytes.
    • maxSize (number) - The maximum file size in bytes.
    • minDate (Date) - The minimum modification date.
    • maxDate (Date) - The maximum modification date.

• Returns: Promise<Array<string>|null> - A list of files that match the criteria, or null on failure.

• Example:

  import { searchFiles } from 'fswin32';
  
  async function findFiles(directory, pattern) {
    try {
      const files = await searchFiles(directory, pattern, {
        content: 'hello world',
        minSize: 1024, // 1 KB
      });
      console.log('Found Files:', files);
    } catch (error) {
      console.error('Error searching files:', error);
    }
  }
  
  findFiles('C:\Users\Public\Documents', '*.txt');

Watch

watchPath(path, callback)

Watches a file or folder for changes.

• Parameters:

  • path (string) - The absolute path of the file or folder to watch.
  • callback (Function) - The callback to execute when a change is detected. It receives two arguments: eventType ('rename' or 'change') and filename.

• Returns: fs.FSWatcher - The file system watcher instance. You can call .close() on it to stop watching.

• Example:

  import { watchPath } from 'fswin32';
  
  const watcher = watchPath('C:\Users\Public\Documents', (eventType, filename) => {
    console.log(`Event type: ${eventType}`);
    if (filename) {
      console.log(`Filename provided: ${filename}`);
    } else {
      console.log('Filename not provided');
    }
  });
  
  // To stop watching
  // watcher.close();