check-disk-space

check-disk-space is a zero-dependency Node.js library that reports free and total disk space for any file or directory path, working transparently across Windows, macOS, and Linux. On Windows it shells out to PowerShell’s Get-CimInstance (falling back to wmic on older systems), and on Unix-like systems it parses df output, automatically walking up the path to the nearest existing parent directory so it can report accurate figures even for paths that don’t exist yet.

The library exposes a single async function, checkDiskSpace(path), that resolves to a small { diskPath, free, size } object with values in bytes. It ships with full TypeScript types, distinguishes invalid paths and no-match conditions with dedicated InvalidPathError and NoMatchError classes, and its internal OS-calling logic is injected as a dependencies parameter — the same seam the maintainers use in their own AVA test suite to simulate Windows XP through Windows 11 and multiple Linux/macOS locales without touching a real filesystem.

What You Get

• A single checkDiskSpace(path) async function returning { diskPath, free, size } in bytes
• Zero runtime dependencies — no native bindings or third-party packages to install or audit
• Cross-platform disk queries via PowerShell/wmic on Windows and df on Unix-like systems
• Full TypeScript typings plus dedicated InvalidPathError and NoMatchError classes for precise error handling
• A dependency-injection seam (the dependencies param) that makes OS-specific behavior mockable in your own tests

Common Use Cases

• Disk space health checks in CLI tools, monitoring agents, or system dashboards
• Pre-flight checks before a build, backup, or file-upload job to ensure enough free space exists
• Cross-platform Electron or desktop-agent apps that need consistent disk stats on Windows, macOS, and Linux
• Node.js server processes that warn or throttle writes when a mounted volume is nearly full

Under The Hood

Architecture The entire library funnels through a single exported function, checkDiskSpace() in src/index.ts, which branches into a checkWin32 or checkUnix nested function based on dependencies.platform. Both paths delegate to a shared check()/mapOutput() pair that runs an OS command via an injected cpExecFile and parses its tabular stdout into a normalized { diskPath, free, size } shape, filtering rows differently per platform (drive-letter match on Windows, single-row passthrough on Unix). Unix paths first resolve through getFirstExistingParentPath(), which recurses via isDirectoryExisting() until it finds a real parent directory, letting the library report space for not-yet-created paths. All OS-facing calls (platform, release, fs access, path handling, child-process exec) are bundled into one dependencies object with real implementations as defaults, giving the whole module a single, well-defined seam for testing and error handling (InvalidPathError, NoMatchError) is done via dedicated typed classes rather than generic Error throws.

Tech Stack Written in TypeScript targeting Node >=16, the library is built with Rollup into dual ESM (check-disk-space.mjs) and CJS (check-disk-space.cjs) bundles, with a separate rollup-plugin-dts pass generating the .d.ts declaration file. Tests run on AVA with ts-node and tsconfig-paths for the @/ path alias, coverage is collected via nyc/@istanbuljs, and linting uses a shared @alex-d/eslint-config. GitHub Actions runs a CI matrix across Node 16/18/20 for tests plus a separate lint+typecheck job, and a tag-triggered npm-publish workflow builds and publishes to the registry.

Code Quality The test suite (test/index.spec.ts) is fixture-driven, covering Windows XP through Windows 11 PowerShell/wmic output formats, multiple Unix df variants including a non-English (Russian) locale header, and explicit negative-path tests for invalid paths, no matching drive, and a failing child process — all exercised through a mocked dependencies object rather than real OS calls. CI enforces linting, type checking, and coverage across three Node versions on every push, and errors are raised as typed InvalidPathError/NoMatchError classes instead of generic throws, making failure modes easy for callers to branch on.

What Makes It Unique The library’s defining choice is pushing every OS-facing call — exec, fs.access, path.normalize, even os.release() — behind one injectable dependencies parameter with sensible real-world defaults. That single design decision is what lets the maintainers simulate a decade of Windows versions and multiple Unix locale formats in unit tests without spinning up VMs or mocking Node’s internals piecemeal, and it gives consumers of the library the same option if they need to stub disk checks in their own test suites. Combined with a deliberately tiny public API (one function, two error types, one result shape) and zero runtime dependencies, it trades feature breadth for a very low-friction, low-risk integration surface.