nodejs/node

Missing documentation in `fs.StatFs`

Open

#50749 opened on Nov 15, 2023

View on GitHub
 (9 comments) (5 reactions) (0 assignees)JavaScript (117,218 stars) (35,535 forks)batch import
docfsgood first issue

Description

Affected URL(s)

https://nodejs.org/api/fs.html#class-fsstatfs

Description of the problem

  • statfs.bsize fails to mention if the size is reported in bits or bytes
  • While statfs.bavail and statfs.bfree can be used to calculate available and free space, it would be appropriate to put an example on how to use them Example: 
    import { statfs } from "fs/promises"
const statsfs = await statfs("/tmp")
const available_bits_or_bytes_not_documented = statsfs.bsize * statsfs.bavail
  • Similarly, statfs.blocks and statfs.files would strongly benefit from an example
  • What's statfs.type and why is it a number?

Contributor guide

Tech stack
nodejstypescript
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
basic Node.js knowledgefamiliarity with fs module
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80
Research direction
The issue requests clarifications and examples for properties of the `StatFs` class in the Node.js `fs` documentation, specifically `bsize`, `bavail`, `bfree`, `blocks`, `files`, and `type`. The relevant file is likely `doc/api/fs.md` in the Node.js repository. The maintainer may have already commented on the correct units and usage. To address this, review the existing documentation and any linked references (e.g., POSIX `statvfs`). Then update the description to specify that `bsize` is in bytes, provide a code example showing how to calculate available space, and explain that `type` refers to the filesystem type identifier (e.g., from Linux's `f type` header).