doc: distinguish between fs.Stats and fs.BigIntStats

[LiviaMedeiros]

fs.Stats and fs.BigIntStats are similar, but separate classes. Currently, the fs documentation gives wrong impression, as if BigIntStats is an alias or subclass of Stats.
Making the difference more clear and explicit might help improve the accuracy of type definitions.

[Renegade334]

My read was always that this was an intentional "legal fiction", similar to how classes like KeyObject are documented to be a single entity but are actually implemented as a class tree. The BigIntStats constructor isn't part of the public API surface, even though it's observable.

[LiviaMedeiros]

Yes, it can be viewed that way. IMHO unlike KeyObject which is an useful higher level abstraction, or e.g. StatFs which actually behaves similar to how Stats is described, Stats doesn't really benefit from being documented as single class. Are there any upsides, aside from functions having single-type return value?

[Renegade334]

Honestly, my gut feeling is that these would be better off as a single class anyway... the only areas of divergence are the setting of the properties in the constructor and the single bigint-to-number conversion in _checkModeProperty, both of which would be pretty easy to handle. YMMV though 🙂