@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.

Features

• Cross-platform support:

  • Windows 10+ (x64)
  • macOS 14+
  • Debian 11/Ubuntu 20.04+ (x64, arm64) (with Gnome GIO/GVfs mount support where available)
  • Alpine 3.21+ (x64, arm64)

• List all mounted volumes/drives

• Get detailed volume metadata

• File and directory hidden attribute support:

  • Get and set hidden attributes
  • POSIX-style support (macOS and Linux)
  • Filesystem metadata support (macOS and Windows)
  • Recursive hidden checks
  • Hidden metadata queries

• 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 and prebuildify

• Comprehensive test coverage

Supported Platforms

Prebuilt binaries are provided for the following platforms:

Platform	Architecture	Node.js	Minimum OS Version
Windows	x64	20+	Windows 10
macOS	x64	20+	macOS 14 (Sonoma)
macOS	arm64	20+	macOS 14 (Sonoma)
Linux (glibc)	x64	20+	Debian 11 (Bullseye), Ubuntu 20.04, GLIBC 2.31+
Linux (glibc)	arm64	20+	Debian 11 (Bullseye), Ubuntu 20.04, GLIBC 2.31+
Linux (musl)	x64	20+	Alpine 3.21
Linux (musl)	arm64	20+	Alpine 3.21

Notes:

• Linux binaries require GLIBC 2.31+ (Debian 11 Bullseye or newer). Note: this means the node:20 docker image is not supported, due to the last several major versions of node-gyp-build requiring both a newer python and newer C++ version.
• Electron is supported via Node-API compatibility

Installation

npm install @photostructure/fs-metadata
Copy

Usage

import {
  getVolumeMountPoints,
  getVolumeMetadata,
} from "@photostructure/fs-metadata";

// List all mounted volumes
const mountPoints = await getVolumeMountPoints();
console.dir({ mountPoints });

// Get metadata for a specific volume
const volumeMetadata = await getVolumeMetadata(mountPoints[0]);
console.dir({ volumeMetadata });
Copy

If you're using CommonJS:

const {
  getVolumeMountPoints,
  getVolumeMetadata,
} = require("@photostructure/fs-metadata");

// Usage is the same as the ESM example above 
// (except of course no top-level awaits!)
Copy

API

Read the API here

Options

Debug Logging

Set NODE_DEBUG=fs-meta or NODE_DEBUG=photostructure:fs-metadata. The native debuglog determines if debug logging is enabled. Debug messages from both JavaScript and native code are sent to stderr.

Timeouts

Operations use a default timeout, which may need adjustment for slower devices like optical drives (which can take 30+ seconds to spin up).

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.

Timeout duration may apply per-operation or per-system call, depending on the implementation.

System Volumes

Each platform handles system volumes differently:

• 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 for default values and customization.

Note: getAllVolumeMetadata() returns all volumes on Windows but only non-system volumes elsewhere by default.

License

This project is licensed under the MIT License.

Contributing

We welcome contributions! Please see our Contributing Guide for more details.

Security

For security-related issues, please refer to our Security Policy.