https://github.com/photostructure/fs-metadata
Cross-platform native Node.js module for fetching filesystem metadata
https://github.com/photostructure/fs-metadata
cjs esm filesystem gio linux macos metadata mount native node-addon nodejs typescript volume windows
Last synced: about 2 months ago
JSON representation
Cross-platform native Node.js module for fetching filesystem metadata
- Host: GitHub
- URL: https://github.com/photostructure/fs-metadata
- Owner: photostructure
- License: mit
- Created: 2024-11-09T02:44:47.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-29T00:30:25.000Z (5 months ago)
- Last Synced: 2025-10-03T02:50:57.515Z (5 months ago)
- Topics: cjs, esm, filesystem, gio, linux, macos, metadata, mount, native, node-addon, nodejs, typescript, volume, windows
- Language: TypeScript
- Homepage: https://photostructure.github.io/fs-metadata/
- Size: 2.57 MB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
Cross-platform native Node.js module for filesystem metadata, mount points, and volume information. Built for and supported by [PhotoStructure](https://photostructure.com).
[](https://www.npmjs.com/package/@photostructure/fs-metadata)
[](https://github.com/photostructure/fs-metadata/actions/workflows/build.yml)
[](https://nodejs.org/dist/latest/docs/api/n-api.html#node-api-version-matrix)
[](https://github.com/photostructure/fs-metadata)
## Quick Start
```bash
npm install @photostructure/fs-metadata
```
```typescript
import {
getVolumeMountPoints,
getVolumeMetadata,
} from "@photostructure/fs-metadata";
// List all mounted volumes
const mountPoints = await getVolumeMountPoints();
console.log(mountPoints);
// Get metadata for a specific volume
const metadata = await getVolumeMetadata("/");
console.log(metadata);
```
## Key Features
- **Volume Management**: List mount points, get volume metadata, space usage
- **Hidden Files**: Get/set hidden attributes, recursive checks, cross-platform support
- **Performance**: Non-blocking async operations with timeout protection
- **TypeScript**: Full type definitions with ESM and CommonJS support
## Supported Platforms
| Platform | Architecture | Node.js | OS Version |
| ------------- | ------------ | ------- | ------------------------- |
| Windows | x64, arm64 | 20+ | Windows 10+ |
| macOS | x64, arm64 | 20+ | macOS 14+ |
| Linux (glibc) | x64, arm64 | 20+ | Debian 11+, Ubuntu 20.04+ |
| Linux (musl) | x64, arm64 | 20+ | Alpine 3.21+ |
> **Note**: Linux binaries require GLIBC 2.31+. The `node:20` Docker image is not supported.
## Documentation
- [Security reporting](./SECURITY.md) - How to report security issues
- [API Reference](https://photostructure.github.io/fs-metadata/modules.html)
- [Examples](./doc/examples.md) - Common usage patterns and recipes
- [Gotchas](./doc/gotchas.md) - Platform quirks, timeouts, and troubleshooting
- [Contributing](./CONTRIBUTING.md) - Build instructions and development guide
### Options
- **Debug**: Set `NODE_DEBUG=fs-meta` for debug output
- **Timeouts**: Configure [timeout duration](https://photostructure.github.io/fs-metadata/functions/getTimeoutMsDefault.html) for slow devices
- Set `FS_METADATA_TIMEOUT_MS` environment variable to override the default (5000ms)
- **System Volumes**: Control [system volume filtering](https://photostructure.github.io/fs-metadata/interfaces/Options.html)
## Development
Development of this library was assisted by AI coding tools. All changes are human-reviewed and tested.