fswin32
Version:
The ultimate Node.js module for detailed Windows file system access.
649 lines (447 loc) • 16.3 kB
Markdown
# 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
```bash
npm install fswin32
```
## Usage
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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();
```