# 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();
    ```