@photostructure/fs-metadata 0.0.1 → 0.1.0

package/README.md

@@ -1,11 +1,11 @@
 # @photostructure/fs-metadata
 
-A cross-platform native Node.js module for retrieving filesystem metadata including mount points, volume information, and space utilization statistics.
+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)
+[![Build](https://github.com/photostructure/fs-metadata/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/photostructure/fs-metadata/actions/workflows/build.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)
@@ -13,19 +13,32 @@ Built and supported by [PhotoStructure](https://photostructure.com).
 
 ## 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
+  - Windows 10+ (x64, arm64)
+  - macOS 14+ (x64, arm64)
+  - Ubuntu 22+ (x64, arm64) (with Gnome GIO/`GVfs` mount support when available)
+
+- [List all mounted volumes/drives](https://photostructure.github.io/fs-metadata/functions/getVolumeMountPoints.html)
+
+- [Get detailed volume metadata](https://photostructure.github.io/fs-metadata/functions/getVolumeMetadata.html)
+
+- File and directory hidden attribute support:
+  - [Get](https://photostructure.github.io/fs-metadata/functions/isHidden.html) and [set](https://photostructure.github.io/fs-metadata/functions/setHidden.html) hidden attributes
+  - POSIX-style support (macOS and Linux)
+  - Filesystem metadata support (macOS and Windows)
+  - [Recursive hidden checks](https://photostructure.github.io/fs-metadata/functions/isHiddenRecursive.html)
+  - [Hidden metadata queries](https://photostructure.github.io/fs-metadata/functions/getHiddenMetadata.html)
+
+- ESM and CJS support
+
+- Full TypeScript type definitions
+
+- Non-blocking async native implementations
+
+- Timeout handling for wedged network volumes
+
+- Compatible with all current Node.js and Electron versions via [Node-API v9](https://nodejs.org/api/n-api.html#node-api) and [prebuildify](https://github.com/prebuild/prebuildify)
+
 - Comprehensive test coverage
 
 ## Installation
@@ -45,13 +58,10 @@ import {
 // 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('/');
+const volumeMetadata = await getVolumeMetadata(mountPoints[0]);
+console.dir({ volumeMetadata });
 ```
 
 If you're using CommonJS:
@@ -62,34 +72,38 @@ const {
   getVolumeMetadata,
 } = require("@photostructure/fs-metadata");
 
-// Usage is the same as the ESM example above
+// Usage is the same as the ESM example above 
+// (except of course no top-level awaits!)
 ```
 
-## Documentation
+## API
 
 [Read the API here](https://photostructure.github.io/fs-metadata/modules.html)
 
 ## Options
 
+### Debug Logging
+
+Set `NODE_DEBUG=fs-meta` or `NODE_DEBUG=photostructure:fs-metadata`. The native [debuglog](https://nodejs.org/api/util.html#utildebuglogsection-callback) determines if debug logging is enabled. Debug messages from both JavaScript and native code are sent to `stderr`.
+
 ### 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}`.
+Operations use a [default timeout](https://photostructure.github.io/fs-metadata/variables/TimeoutMsDefault.html), which may need adjustment for slower devices like optical drives (which can take 30+ seconds to spin up).
 
-### Filtering
+Windows can block system calls when remote filesystems are unhealthy due to host downtime or network issues. To handle this, we use a separate thread per mountpoint to check volume health status. While this approach uses more resources than the async N-API thread, it enables reliable timeouts for operations that would otherwise hang indefinitely.
 
-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).
+Timeout duration may apply per-operation or per-system call, depending on the implementation.
 
-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.
+### System Volumes
 
-To disable these filters, provide an empty array for these `excluded*` fields, like so:
+Each platform handles system volumes differently:
 
-```ts
-const allMountPoints = await getVolumeMountPoints({
-  excludedFileSystemTypes: [],
-  excludedMountPointGlobs: [],
-  onlyDirectories: false,
-});
-```
+- Windows provides explicit metadata for "system" or "reserved" devices, though `C:\` is both a system volume and typical user storage
+- Linux and macOS include various system-only mountpoints: pseudo devices, snap loopback devices, virtual memory partitions, and recovery partitions
+
+This library uses heuristics to identify system volumes. See [Options](https://photostructure.github.io/fs-metadata/interfaces/Options.html) for default values and customization.
+
+Note: [`getAllVolumeMetadata()`](https://photostructure.github.io/fs-metadata/functions/getAllVolumeMetadata.html) returns all volumes on Windows but only non-system volumes elsewhere by default.
 
 ## Platform-Specific Behaviors
 
@@ -123,189 +137,43 @@ keep in mind:
 
 #### 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).
+- Volume status from `GetDriveType`
+- Size information from `GetDiskFreeSpaceEx`
+- Volume information (label, filesystem) from `GetVolumeInformation`
+- `fstype` 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](https://photostructure.github.io/fs-metadata/interfaces/VolumeMetadata.html#uuid)
+  is attempted to be extracted from the partition UUID, but if this is a remote
+  volume, or system permissions do not provide access to this, we will fall back
+  to returning the volume serial number that the operating system assigns. You
+  can tell that it's a serial number UUID in that it only contains 8 characters
+  (32 bits of entropy).
 
 #### macOS
 
-- Size calculations via statvfs
+- 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
+- Size information from `statvfs`
+- Filesystem type from mount table and from `gio`
+- 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
+- Backfills with `lsblk` metadata if native code fails
 
 ## License
 
-MIT
+[MIT](https://github.com/photostructure/fs-metadata/blob/main/LICENSE.txt)
 
 ## 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.
+See [CONTRIBUTING.md](https://github.com/photostructure/fs-metadata/blob/main/CONTRIBUTING.md) on GitHub.
 
 ## Security
 
-If you discover a security vulnerability, please send an email to [security@photostructure.com](mailto:security@photostructure.com)
+See [SECURITY.md](https://github.com/photostructure/fs-metadata/blob/main/SECURITY.md) on GitHub.

package/binding.gyp

@@ -42,7 +42,8 @@
                 {
                   "sources": [
                     "src/linux/gio_utils.cpp",
-                    "src/linux/gio_worker.cpp"
+                    "src/linux/gio_mount_points.cpp",
+                    "src/linux/gio_volume_metadata.cpp"
                   ],
                   "defines": [
                     "ENABLE_GIO=1"
@@ -63,7 +64,8 @@
           {
             "sources": [
               "src/windows/volume_mount_points.cpp",
-              "src/windows/volume_metadata.cpp"
+              "src/windows/volume_metadata.cpp",
+              "src/windows/hidden.cpp"
             ],
             "libraries": [
               "-lMpr.lib"
@@ -81,7 +83,8 @@
           {
             "sources": [
               "src/darwin/volume_mount_points.cpp",
-              "src/darwin/volume_metadata.cpp"
+              "src/darwin/volume_metadata.cpp",
+              "src/darwin/hidden.cpp"
             ],
             "xcode_settings": {
               "CLANG_CXX_LANGUAGE_STANDARD": "c++17",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photostructure/fs-metadata",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Cross-platform native filesystem metadata retrieval for Node.js",
   "homepage": "https://photostructure.github.io/fs-metadata/",
   "type": "module",
@@ -27,38 +27,41 @@
   "scripts": {
     "install": "node-gyp-build",
     "clean": "run-p clean:*",
-    "clean:dist": "rimraf dist",
+    "clean:dist": "del-cli coverage dist docs \"*.tsbuildinfo\"",
+    "clean:gyp-cache": "del-cli build %USERPROFILE%/.node-gyp ~/.node-gyp",
     "clean:gyp": "node-gyp clean",
+    "node-gyp-rebuild": "node-gyp rebuild",
     "// scripts/configure.js checks if gio is installed": "",
     "configure": "node scripts/configure.mjs",
+    "prebuildify": "prebuildify --napi --tag-libc --strip",
     "// prebuild": "is called by .github/workflows/build.yml",
-    "preprebuild": "run-s clean configure",
-    "prebuild": "prebuildify --napi --tag-libc --strip",
+    "prebuild": "run-s configure prebuildify",
+    "prep": "run-s clean prebuild tsc",
     "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",
+    "watch": "tsc --watch --project tsconfig.watch.json",
     "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",
+    "tests": "run-s lint test test:memory",
+    "test": "node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js --coverage",
     "// 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",
+    "test:memory": "cross-env TEST_MEMORY=1 node --expose-gc --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js --no-coverage src/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:cpp": "clang-format --style=LLVM -i src/*.cpp 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",
+    "precommit": "run-s fmt prep tests",
     "// release": "is called by .github/workflows/release.yml and should only be run via GitHub Actions",
     "prerelease": "tsc",
     "release": "release-it"
@@ -90,32 +93,32 @@
     "cross-platform"
   ],
   "dependencies": {
-    "node-addon-api": "^8.2.2",
+    "node-addon-api": "^8.3.0",
     "node-gyp-build": "^4.8.4"
   },
   "devDependencies": {
-    "@eslint/js": "^9.15.0",
+    "@eslint/js": "^9.17.0",
     "@types/jest": "^29.5.14",
-    "@types/node": "^22.9.1",
-    "@typescript-eslint/eslint-plugin": "^8.15.0",
-    "@typescript-eslint/parser": "^8.15.0",
+    "@types/node": "^22.10.2",
+    "@typescript-eslint/eslint-plugin": "^8.18.1",
+    "@typescript-eslint/parser": "^8.18.1",
     "cross-env": "^7.0.3",
-    "eslint": "^9.15.0",
-    "globals": "^15.12.0",
+    "del-cli": "^6.0.0",
+    "eslint": "^9.17.0",
+    "globals": "^15.13.0",
     "jest": "^29.7.0",
     "jest-environment-node": "^29.7.0",
     "jest-extended": "^4.0.2",
-    "node-gyp": "^10.2.0",
+    "node-gyp": "^11.0.0",
     "npm-run-all": "4.1.5",
     "prebuildify": "^6.0.1",
-    "prettier": "^3.3.3",
+    "prettier": "^3.4.2",
     "prettier-plugin-organize-imports": "4.1.0",
     "release-it": "^17.10.0",
-    "rimraf": "^5.0.9",
-    "terser": "^5.36.0",
+    "terser": "^5.37.0",
     "ts-jest": "^29.2.5",
-    "typedoc": "^0.26.11",
-    "typescript": "^5.6.3",
-    "typescript-eslint": "^8.15.0"
+    "typedoc": "^0.27.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.1"
   }
 }

package/src/binding.cpp

@@ -1,66 +1,96 @@
 // src/binding.cpp
-
 #include <napi.h>
 #include <string>
 
+#include "common/debug_log.h"
 #if defined(_WIN32)
 #include "windows/fs_meta.h"
+#include "windows/hidden.h"
 #elif defined(__APPLE__)
 #include "darwin/fs_meta.h"
+#include "darwin/hidden.h"
 #elif defined(__linux__)
 #include "common/volume_metadata.h"
 #ifdef ENABLE_GIO
-#include "linux/gio_utils.h"
+#include "linux/gio_mount_points.h"
+#include "linux/gio_volume_metadata.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);
+Napi::Value SetDebugLogging(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1 || !info[0].IsBoolean()) {
+    throw Napi::TypeError::New(env, "Boolean argument expected");
+  }
+
+  FSMeta::Debug::enableDebugLogging = info[0].As<Napi::Boolean>();
+  return env.Undefined();
+}
+
+Napi::Value SetDebugPrefix(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 1 || !info[0].IsString()) {
+    throw Napi::TypeError::New(env, "String argument expected");
+  }
+
+  // Set the debug prefix directly
+  FSMeta::Debug::SetDebugPrefix(info[0].As<Napi::String>().Utf8Value());
+  return env.Undefined();
 }
 
 #ifdef ENABLE_GIO
-Napi::Value GetGioMountPoints(const Napi::CallbackInfo& info) {
-    Napi::Env env = info.Env();
-    return FSMeta::gio::GetMountPoints(env);
+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);
+// Fix: Remove extra parameter and use correct signature
+Napi::Value GetVolumeMountPoints(const Napi::CallbackInfo &info) {
+  return FSMeta::GetVolumeMountPoints(info);
+}
+#endif
+
+Napi::Value GetVolumeMetadata(const Napi::CallbackInfo &info) {
+  return FSMeta::GetVolumeMetadata(info);
+}
+
+#if defined(_WIN32) || defined(__APPLE__)
+Napi::Value GetHiddenAttribute(const Napi::CallbackInfo &info) {
+  return FSMeta::GetHiddenAttribute(info);
+}
+
+Napi::Value SetHiddenAttribute(const Napi::CallbackInfo &info) {
+  return FSMeta::SetHiddenAttribute(info);
 }
 #endif
 
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
-    
+  exports.Set("setDebugLogging", Napi::Function::New(env, SetDebugLogging));
+  exports.Set("setDebugPrefix", Napi::Function::New(env, SetDebugPrefix));
+
 #if defined(_WIN32) || defined(__APPLE__)
-    exports.Set("getVolumeMountPoints",
-        Napi::Function::New(env, GetVolumeMountPoints));
+  exports.Set("getVolumeMountPoints",
+              Napi::Function::New(env, GetVolumeMountPoints));
 #endif
 
-    exports.Set("getVolumeMetadata", 
-        Napi::Function::New(env, GetVolumeMetadata));
+  exports.Set("getVolumeMetadata", Napi::Function::New(env, GetVolumeMetadata));
 
 #ifdef ENABLE_GIO
-    exports.Set("getGioMountPoints",
-        Napi::Function::New(env, GetGioMountPoints));
+  exports.Set("getGioMountPoints", Napi::Function::New(env, GetGioMountPoints));
+#endif
+
+#if defined(_WIN32) || defined(__APPLE__)
+  exports.Set("isHidden", Napi::Function::New(env, GetHiddenAttribute));
+  exports.Set("setHidden", Napi::Function::New(env, SetHiddenAttribute));
 #endif
 
-    return exports;
+  return exports;
 }
 
 NODE_API_MODULE(node_fs_meta, Init)