@photostructure/fs-metadata 0.0.1

package/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2024 Matthew McEachen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# @photostructure/fs-metadata
+
+A cross-platform native Node.js module for retrieving filesystem metadata including mount points, volume information, and space utilization statistics.
+
+Built and supported by [PhotoStructure](https://photostructure.com).
+
+[![npm version](https://img.shields.io/npm/v/@photostructure/fs-metadata.svg)](https://www.npmjs.com/package/@photostructure/fs-metadata)
+[![Test](https://github.com/photostructure/fs-metadata/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/photostructure/fs-metadata/actions/workflows/test.yml)
+[![GitHub issues](https://img.shields.io/github/issues/photostructure/fs-metadata.svg)](https://github.com/photostructure/fs-metadata/issues)
+[![Known Vulnerabilities](https://snyk.io/test/github/photostructure/fs-metadata/badge.svg?targetFile=package.json)](https://snyk.io/test/github/photostructure/fs-metadata?targetFile=package.json)
+[![Node-API v9 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v9%20Badge.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#node-api-version-matrix)
+[![View on GitHub](https://img.shields.io/badge/View%20on-GitHub-blue)](https://github.com/photostructure/fs-metadata)
+
+## Features
+
+- List all mounted volumes/drives on the system
+- Get detailed volume metadata including:
+  - Total size, used space, and available space
+  - Filesystem type and volume label
+  - Volume UUID (when available)
+  - Remote/network share information
+- Cross-platform support:
+  - Windows (x64, arm64)
+  - macOS (x64, arm64)
+  - Linux (x64, arm64) (including Gnome GIO/`GVfs` mounts, if available)
+- Written in modern TypeScript with full type definitions
+- Native async implementations avoid blocking the event loop
+- Support for both ESM and CJS consumers
+- Comprehensive test coverage
+
+## Installation
+
+```bash
+npm install @photostructure/fs-metadata
+```
+
+## Usage
+
+```ts
+import {
+  getVolumeMountPoints,
+  getVolumeMetadata,
+} from "@photostructure/fs-metadata";
+
+// List all mounted volumes
+const mountPoints = await getVolumeMountPoints();
+console.dir({ mountPoints });
+// Example output: ['C:\\', 'D:\\'] on Windows
+// Example output: ['/', '/home', '/Users'] on Unix-like systems
+
+// Get metadata for a specific volume
+const metadata = await getVolumeMetadata("C:\\"); // Windows
+// Or for Unix-like systems:
+// const metadata = await getVolumeMetadata('/');
+```
+
+If you're using CommonJS:
+
+```js
+const {
+  getVolumeMountPoints,
+  getVolumeMetadata,
+} = require("@photostructure/fs-metadata");
+
+// Usage is the same as the ESM example above
+```
+
+## Documentation
+
+[Read the API here](https://photostructure.github.io/fs-metadata/modules.html)
+
+## Options
+
+### Timeouts
+
+There is a [default timeout](https://photostructure.github.io/fs-metadata/variables/TimeoutMsDefault.html) applied to all operations. This may not be sufficient for some OSes and volumes--especially powered-down optical drives (which may take 10s of seconds to wake up). Disable timeouts by setting `{timeoutMs: 0}`.
+
+### Filtering
+
+Linux and macOS have a (surprisingly large) number of mountpoints that are for internal use (especially if your Linux distribution uses `snap` and/or other loopback ~~hacks~~ systems).
+
+This library tries to avoid those with a bunch of exclusion patterns--see the [Options](https://photostructure.github.io/fs-metadata/interfaces/Options.html) interface for details.
+
+To disable these filters, provide an empty array for these `excluded*` fields, like so:
+
+```ts
+const allMountPoints = await getVolumeMountPoints({
+  excludedFileSystemTypes: [],
+  excludedMountPointGlobs: [],
+  onlyDirectories: false,
+});
+```
+
+## Platform-Specific Behaviors
+
+This module's results are inherently platform-specific. Here are some things to
+keep in mind:
+
+### Mount Points
+
+#### Windows
+
+- Mount points are drive letters with trailing backslash (e.g., `C:\`, `D:\`)
+- Network shares appear as mounted drives with UNC paths
+- Volume GUIDs are available through Windows API
+- Hidden and system volumes may be included
+
+#### macOS
+
+- Uses forward slashes for paths (e.g., `/`, `/Users`)
+- Volume UUIDs may be available through the DiskArbitration framework
+- Time Machine volumes should be detected and handled appropriately
+
+#### Linux
+
+- Uses forward slashes for paths (e.g., `/`, `/home`)
+- Network mounts (NFS/CIFS) handled through mount table
+- If `GIO` support is installed, it will be queried for additional mountpoints and volume metadata
+- Depending on your distribution, you may want to use `{ linuxMountTablePath: "/etc/mtab" }` instead of the default, `/proc/mounts`.
+- UUID detection is via `libblkid`, which must be installed.
+
+### Volume Metadata
+
+#### Windows
+
+- Size information from GetDiskFreeSpaceEx
+- Volume information (label, filesystem) from GetVolumeInformation
+- Remote status from GetDriveType
+- `fileSystem` will be `NTFS` for remote filesystems, as that's how Windows presents the local volume. Fixing this to be more accurate requires additional heuristics that have diminshing returns.
+- The UUID is the volume serial number that the operating system assigns when a hard disk is formatted, and **not the physical UUID assigned by the manufacturer**. This lets us avoid one more syscall (and it's a doozy, the Windows Management Instrumentation (WMI) Win32_PhysicalMedia function loves to hang).
+
+#### macOS
+
+- Size calculations via statvfs
+- Volume details through DiskArbitration framework
+- Network share detection via volume characteristics
+- Time Machine volume detection
+
+#### Linux
+
+- Size information from statvfs
+- Filesystem type from mount table
+- Block device metadata via libblkid
+- Network filesystem detection from mount options
+- Optional GIO integration for additional metadata
+
+### Filesystem Types
+
+#### Windows
+
+- NTFS
+- FAT32
+- exFAT
+- ReFS
+- Network shares (CIFS/SMB)
+
+#### macOS
+
+- APFS (default since macOS High Sierra)
+- HFS+ (legacy)
+- FAT32
+- exFAT
+- Network shares (AFP, SMB, NFS)
+
+#### Linux
+
+- ext2/3/4
+- XFS
+- Btrfs
+- ZFS
+- Network filesystems (NFS, CIFS)
+- Pseudo filesystems (procfs, sysfs) - excluded by default
+
+### Default Excluded Mount Points
+
+#### Windows
+
+- None by default
+
+#### macOS
+
+- `/dev`
+- `/dev/fd`
+- System volume internal mounts
+
+#### Linux
+
+- `/proc`
+- `/sys`
+- `/dev`
+- `/run`
+- Snap mounts
+- Other virtual filesystems
+
+### Network Share Metadata
+
+#### Windows
+
+- UNC paths parsed for host/share information
+- SMB/CIFS protocol support
+- Network status via GetDriveType
+
+#### macOS
+
+- AFP and SMB protocol support
+- Network status via volume characteristics
+- Host/share parsing from mount URLs
+
+#### Linux
+
+- NFS and CIFS support
+- Network detection from filesystem type
+- Remote info parsed from mount spec
+
+### Performance Considerations
+
+#### Windows
+
+- Drive letter enumeration is fast
+- Volume metadata queries may block
+
+#### macOS
+
+- DiskArbitration queries are generally fast
+- Network volume operations may be slow
+
+#### Linux
+
+- Mount table parsing is fast
+- Block device operations may block
+- GIO operations are asynchronous
+
+### Error Handling
+
+#### Windows
+
+- Access denied errors for restricted volumes
+- Network timeout errors for disconnected shares
+- Invalid drive letter errors
+
+#### macOS
+
+- DiskArbitration framework errors
+- Network disconnection handling
+- Volume unmount detection
+
+#### Linux
+
+- Mount table parsing errors
+- Block device access errors
+- GIO operation failures
+- Network filesystem timeouts
+
+### Configuration Options
+
+Common options across platforms:
+
+- Timeout duration
+- Excluded mount point patterns
+- Directory-only filter
+
+Platform-specific options:
+
+- Linux: Mount table path selection
+- Linux: GIO support enable/disable
+- Windows: Network share handling
+- macOS: Time Machine volume handling
+
+### Recommendations
+
+#### Windows
+
+- Handle access denied errors gracefully
+- Check drive type before operations
+
+#### macOS
+
+- Monitor volume mount/unmount notifications
+- Handle Time Machine volumes appropriately
+- Check network status before operations
+
+#### Linux
+
+- Use default mount table when possible
+- Enable GIO support if available
+- Handle remote filesystem timeouts
+
+## Building from Source
+
+Requirements:
+
+- Supported Node.js version
+- Python 3
+- C++ build tools:
+  - Windows: Visual Studio Build Tools
+  - macOS: Xcode Command Line Tools
+  - Linux: GCC and development headers
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+Please make sure to update tests and documentation as appropriate.
+
+## Security
+
+If you discover a security vulnerability, please send an email to [security@photostructure.com](mailto:security@photostructure.com)

package/binding.gyp

@@ -0,0 +1,111 @@
+{
+  "variables": {
+    "enable_gio%": "false"
+  },
+  "targets": [
+    {
+      "target_name": "node_fs_meta",
+      "sources": [
+        "src/binding.cpp"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "src"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "defines": [
+        "NAPI_CPP_EXCEPTIONS"
+      ],
+      "conditions": [
+        [
+          "OS=='linux'",
+          {
+            "sources": [
+              "src/linux/blkid_cache.cpp",
+              "src/linux/volume_metadata.cpp"
+            ],
+            "libraries": [
+              "-lblkid"
+            ],
+            "cflags": [
+              "-fPIC"
+            ],
+            "cflags_cc": [
+              "-fexceptions",
+              "-fPIC"
+            ],
+            "conditions": [
+              [
+                "enable_gio=='true'",
+                {
+                  "sources": [
+                    "src/linux/gio_utils.cpp",
+                    "src/linux/gio_worker.cpp"
+                  ],
+                  "defines": [
+                    "ENABLE_GIO=1"
+                  ],
+                  "libraries": [
+                    "<!@(pkg-config --libs gio-2.0)"
+                  ],
+                  "cflags": [
+                    "<!@(pkg-config --cflags gio-2.0)"
+                  ]
+                }
+              ]
+            ]
+          }
+        ],
+        [
+          "OS=='win'",
+          {
+            "sources": [
+              "src/windows/volume_mount_points.cpp",
+              "src/windows/volume_metadata.cpp"
+            ],
+            "libraries": [
+              "-lMpr.lib"
+            ],
+            "msvs_settings": {
+              "VCCLCompilerTool": {
+                "ExceptionHandling": 1,
+                "RuntimeTypeInfo": "true"
+              }
+            }
+          }
+        ],
+        [
+          "OS=='mac'",
+          {
+            "sources": [
+              "src/darwin/volume_mount_points.cpp",
+              "src/darwin/volume_metadata.cpp"
+            ],
+            "xcode_settings": {
+              "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
+              "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+              "CLANG_CXX_LIBRARY": "libc++",
+              "MACOSX_DEPLOYMENT_TARGET": "10.15"
+            },
+            "cflags": [
+              "-fexceptions",
+              "-fPIC"
+            ],
+            "cflags_cc": [
+              "-fexceptions"
+            ],
+            "link_settings": {
+              "libraries": [
+                "DiskArbitration.framework",
+                "Foundation.framework",
+                "IOKit.framework"
+              ]
+            }
+          }
+        ]
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@photostructure/fs-metadata",
+  "version": "0.0.1",
+  "description": "Cross-platform native filesystem metadata retrieval for Node.js",
+  "homepage": "https://photostructure.github.io/fs-metadata/",
+  "type": "module",
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.mjs",
+  "// exports": "https://nodejs.org/api/packages.html#conditional-exports",
+  "exports": {
+    ".": {
+      "require": {
+        "default": "./lib/cjs/index.cjs",
+        "types": "./lib/cjs/index.d.ts"
+      },
+      "import": {
+        "default": "./lib/esm/index.js",
+        "types": "./lib/esm/index.d.ts"
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/photostructure/fs-metadata.git"
+  },
+  "license": "MIT",
+  "scripts": {
+    "install": "node-gyp-build",
+    "clean": "run-p clean:*",
+    "clean:dist": "rimraf dist",
+    "clean:gyp": "node-gyp clean",
+    "// scripts/configure.js checks if gio is installed": "",
+    "configure": "node scripts/configure.mjs",
+    "// prebuild": "is called by .github/workflows/build.yml",
+    "preprebuild": "run-s clean configure",
+    "prebuild": "prebuildify --napi --tag-libc --strip",
+    "tsc": "run-p tsc:*",
+    "tsc:esm": "tsc -p tsconfig.esm.json",
+    "tsc:cjs": "tsc -p tsconfig.cjs.json",
+    "tsc:tests": "tsc -p tsconfig.json",
+    "watch": "tsc --watch",
+    "docs": "typedoc --out docs src/index.ts",
+    "jest:coverage": "jest --coverage",
+    "jest:watch": "npm t -- --watch",
+    "jest:clear": "jest --clearCache",
+    "// tests": "is called by .github/workflows/test.yml",
+    "tests": "run-s test test:memory",
+    "test": "node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js",
+    "// test:memory:todo": "set up valgrind or similar",
+    "test:memory": "cross-env TEST_MEMORY=1 node --expose-gc --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js src/__tests__/memory.test.ts",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "fmt": "run-p fmt:*",
+    "// fmt:cpp": "on ubuntu: `sudo apt install clang-format`",
+    "fmt:cpp": "clang-format --style=LLVM -i src/*/*.cpp src/*/*.h || true",
+    "fmt:js": "prettier --write \"scripts/**/*.?js\" \"*.?js\"",
+    "fmt:json": "prettier --write \"**/*.json\"",
+    "fmt:pkg": "npm pkg fix",
+    "fmt:ts": "prettier --write \"src/**/*.ts\"",
+    "// precommit": "is called manually before committing",
+    "precommit": "run-s clean fmt lint prebuild tsc tests",
+    "// release": "is called by .github/workflows/release.yml and should only be run via GitHub Actions",
+    "prerelease": "tsc",
+    "release": "release-it"
+  },
+  "gypfile": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "keywords": [
+    "filesystem",
+    "metadata",
+    "native",
+    "node-addon",
+    "windows",
+    "linux",
+    "macos",
+    "cross-platform"
+  ],
+  "dependencies": {
+    "node-addon-api": "^8.2.2",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.15.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.15.0",
+    "@typescript-eslint/parser": "^8.15.0",
+    "cross-env": "^7.0.3",
+    "eslint": "^9.15.0",
+    "globals": "^15.12.0",
+    "jest": "^29.7.0",
+    "jest-environment-node": "^29.7.0",
+    "jest-extended": "^4.0.2",
+    "node-gyp": "^10.2.0",
+    "npm-run-all": "4.1.5",
+    "prebuildify": "^6.0.1",
+    "prettier": "^3.3.3",
+    "prettier-plugin-organize-imports": "4.1.0",
+    "release-it": "^17.10.0",
+    "rimraf": "^5.0.9",
+    "terser": "^5.36.0",
+    "ts-jest": "^29.2.5",
+    "typedoc": "^0.26.11",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.15.0"
+  }
+}

package/scripts/configure.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+// scripts/configure.mjs
+
+import { execSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { platform } from "node:os";
+import { argv } from "node:process";
+import { pathToFileURL } from "node:url";
+
+function hasGio() {
+  if (platform() !== "linux") return false;
+  try {
+    execSync("pkg-config --exists gio-2.0", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function configure() {
+  // Create a gyp config file that node-gyp will read
+  const config = {
+    variables: {
+      "enable_gio%": hasGio() ? "true" : "false",
+    },
+  };
+
+  const payload = JSON.stringify(config, null, 2);
+  writeFileSync("config.gypi", payload);
+}
+
+// If the script is run directly, call the configure function
+if (import.meta.url === pathToFileURL(argv[1]).href) {
+  configure();
+}

package/src/binding.cpp

@@ -0,0 +1,68 @@
+// src/binding.cpp
+
+#include <napi.h>
+#include <string>
+
+#if defined(_WIN32)
+#include "windows/fs_meta.h"
+#elif defined(__APPLE__)
+#include "darwin/fs_meta.h"
+#elif defined(__linux__)
+#include "common/volume_metadata.h"
+#ifdef ENABLE_GIO
+#include "linux/gio_utils.h"
+#endif
+#endif
+
+namespace {
+
+Napi::Value GetVolumeMetadata(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    
+    if (info.Length() < 1 || !info[0].IsString()) {
+        throw Napi::TypeError::New(env, "String expected for mountPoint");
+    }
+    
+    std::string mountPoint = info[0].As<Napi::String>();
+    Napi::Object options = info.Length() > 1 && info[1].IsObject() 
+        ? info[1].As<Napi::Object>() 
+        : Napi::Object::New(env);
+        
+    return FSMeta::GetVolumeMetadata(env, mountPoint, options);
+}
+
+#ifdef ENABLE_GIO
+Napi::Value GetGioMountPoints(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    return FSMeta::gio::GetMountPoints(env);
+}
+#endif
+
+#if defined(_WIN32) || defined(__APPLE__)
+Napi::Value GetVolumeMountPoints(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    return FSMeta::GetVolumeMountPoints(env);
+}
+#endif
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    
+#if defined(_WIN32) || defined(__APPLE__)
+    exports.Set("getVolumeMountPoints",
+        Napi::Function::New(env, GetVolumeMountPoints));
+#endif
+
+    exports.Set("getVolumeMetadata", 
+        Napi::Function::New(env, GetVolumeMetadata));
+
+#ifdef ENABLE_GIO
+    exports.Set("getGioMountPoints",
+        Napi::Function::New(env, GetGioMountPoints));
+#endif
+
+    return exports;
+}
+
+NODE_API_MODULE(node_fs_meta, Init)
+
+} // namespace

package/src/common/error_utils.h

@@ -0,0 +1,19 @@
+// src/common/error_utils.h
+#pragma once
+#include <stdexcept>
+#include <string>
+
+namespace FSMeta {
+
+class FSException : public std::runtime_error {
+public:
+  explicit FSException(const std::string &message)
+      : std::runtime_error(message) {}
+};
+
+inline std::string CreateErrorMessage(const char *operation, int error) {
+  return std::string(operation) +
+         " failed with error: " + std::to_string(error);
+}
+
+} // namespace FSMeta