feat: implement statfsSync and statfs functions with StatFs class

Co-authored-by: streamich <[email protected]>

Author: Copilot

src/node/StatFs.ts

@@ -0,0 +1,54 @@
+import { Superblock } from '../core';
+import type { IStatFs } from './types/misc';
+
+export type TStatNumber = number | bigint;
+
+/**
+ * Statistics about a file system, like `fs.StatFs`.
+ */
+export class StatFs<T = TStatNumber> implements IStatFs<T> {
+  static build(superblock: Superblock, bigint: false): StatFs<number>;
+  static build(superblock: Superblock, bigint: true): StatFs<bigint>;
+  static build(superblock: Superblock, bigint?: boolean): StatFs<TStatNumber>;
+  static build(superblock: Superblock, bigint: boolean = false): StatFs<TStatNumber> {
+    const statfs = new StatFs<TStatNumber>();
+
+    const getStatNumber = !bigint ? number => number : number => BigInt(number);
+
+    // For in-memory filesystem, provide mock but reasonable values
+    // Magic number for in-memory filesystem type (similar to ramfs)
+    statfs.type = getStatNumber(0x858458f6);
+
+    // Optimal transfer block size - commonly 4096 bytes
+    statfs.bsize = getStatNumber(4096);
+
+    // Calculate filesystem stats based on current state
+    const totalInodes = Object.keys(superblock.inodes).length;
+
+    // Mock large filesystem capacity (appears as a large filesystem to applications)
+    const totalBlocks = 1000000;
+    const usedBlocks = Math.min(totalInodes * 2, totalBlocks); // Rough estimation
+    const freeBlocks = totalBlocks - usedBlocks;
+
+    statfs.blocks = getStatNumber(totalBlocks); // Total data blocks
+    statfs.bfree = getStatNumber(freeBlocks); // Free blocks in file system
+    statfs.bavail = getStatNumber(freeBlocks); // Free blocks available to unprivileged users
+
+    // File node statistics
+    const maxFiles = 1000000; // Mock large number of available inodes
+    statfs.files = getStatNumber(maxFiles); // Total file nodes in file system
+    statfs.ffree = getStatNumber(maxFiles - totalInodes); // Free file nodes
+
+    return statfs;
+  }
+
+  type: T;
+  bsize: T;
+  blocks: T;
+  bfree: T;
+  bavail: T;
+  files: T;
+  ffree: T;
+}
+
+export default StatFs;

src/node/__tests__/volume.test.ts

@@ -3,6 +3,7 @@ import { URL } from 'url';
 import { Link } from '../../core';
 import Stats from '../Stats';
 import Dirent from '../Dirent';
+import StatFs from '../StatFs';
 import { Volume, StatWatcher } from '../volume';
 import hasBigInt from '../../__tests__/hasBigInt';
 import { tryGetChild, tryGetChildNode } from '../../__tests__/util';
@@ -1097,6 +1098,92 @@ describe('volume', () => {
     describe('.fstat(fd, callback)', () => {
       xit('...', () => {});
     });
+    describe('.statfsSync(path)', () => {
+      const vol = new Volume();
+      vol.mkdirSync('/test');
+      vol.writeFileSync('/test/file.txt', 'hello world');
+
+      it('Returns StatFs instance', () => {
+        const statfs = vol.statfsSync('/test');
+        expect(statfs).toBeInstanceOf(StatFs);
+      });
+
+      it('Returns filesystem statistics', () => {
+        const statfs = vol.statfsSync('/');
+        expect(typeof statfs.type).toBe('number');
+        expect(typeof statfs.bsize).toBe('number');
+        expect(typeof statfs.blocks).toBe('number');
+        expect(typeof statfs.bfree).toBe('number');
+        expect(typeof statfs.bavail).toBe('number');
+        expect(typeof statfs.files).toBe('number');
+        expect(typeof statfs.ffree).toBe('number');
+
+        expect(statfs.bsize).toBeGreaterThan(0);
+        expect(statfs.blocks).toBeGreaterThan(0);
+        expect(statfs.files).toBeGreaterThan(0);
+      });
+
+      it('Works with bigint option', () => {
+        const statfs = vol.statfsSync('/', { bigint: true });
+        expect(typeof statfs.type).toBe('bigint');
+        expect(typeof statfs.bsize).toBe('bigint');
+        expect(typeof statfs.blocks).toBe('bigint');
+        expect(typeof statfs.bfree).toBe('bigint');
+        expect(typeof statfs.bavail).toBe('bigint');
+        expect(typeof statfs.files).toBe('bigint');
+        expect(typeof statfs.ffree).toBe('bigint');
+      });
+
+      it('Throws when path does not exist', () => {
+        expect(() => vol.statfsSync('/nonexistent')).toThrow();
+      });
+
+      it('Works with different paths in same filesystem', () => {
+        const statfs1 = vol.statfsSync('/');
+        const statfs2 = vol.statfsSync('/test');
+
+        // Should return same filesystem stats for any path
+        expect(statfs1.type).toBe(statfs2.type);
+        expect(statfs1.bsize).toBe(statfs2.bsize);
+        expect(statfs1.blocks).toBe(statfs2.blocks);
+      });
+    });
+    describe('.statfs(path, callback)', () => {
+      const vol = new Volume();
+      vol.mkdirSync('/test');
+      vol.writeFileSync('/test/file.txt', 'hello world');
+
+      it('Calls callback with StatFs instance', done => {
+        vol.statfs('/test', (err, statfs) => {
+          expect(err).toBeNull();
+          expect(statfs).toBeInstanceOf(StatFs);
+          expect(statfs).toBeDefined();
+          expect(typeof statfs!.type).toBe('number');
+          expect(statfs!.bsize).toBeGreaterThan(0);
+          done();
+        });
+      });
+
+      it('Works with bigint option', done => {
+        vol.statfs('/', { bigint: true }, (err, statfs) => {
+          expect(err).toBeNull();
+          expect(statfs).toBeDefined();
+          expect(typeof statfs!.type).toBe('bigint');
+          expect(typeof statfs!.bsize).toBe('bigint');
+          done();
+        });
+      });
+
+      it('Calls callback with error when path does not exist', done => {
+        vol.statfs('/nonexistent', (err, statfs) => {
+          expect(err).toBeTruthy();
+          expect(err).toBeDefined();
+          expect(err!.code).toBe('ENOENT');
+          expect(statfs).toBeUndefined();
+          done();
+        });
+      });
+    });
     describe('.linkSync(existingPath, newPath)', () => {
       const vol = new Volume();
       it('Create a new link', () => {

src/node/options.ts

@@ -108,6 +108,19 @@ export const getStatOptsAndCb: (
 ) => [opts.IStatOptions, misc.TCallback<misc.IStats>] = (options, callback?) =>
   typeof options === 'function' ? [getStatOptions(), options] : [getStatOptions(options), validateCallback(callback)];
 
+const statfsDefaults: opts.IStafsOptions = {
+  bigint: false,
+};
+export const getStatfsOptions: (options?: any) => opts.IStafsOptions = (options = {}) =>
+  Object.assign({}, statfsDefaults, options);
+export const getStatfsOptsAndCb: (
+  options: any,
+  callback?: misc.TCallback<misc.IStatFs>,
+) => [opts.IStafsOptions, misc.TCallback<misc.IStatFs>] = (options, callback?) =>
+  typeof options === 'function'
+    ? [getStatfsOptions(), options]
+    : [getStatfsOptions(options), validateCallback(callback)];
+
 const realpathDefaults: opts.IReadFileOptions = optsDefaults;
 export const getRealpathOptions = optsGenerator<opts.IRealpathOptions>(realpathDefaults);
 export const getRealpathOptsAndCb = optsAndCbGenerator<opts.IRealpathOptions, misc.TDataOut>(getRealpathOptions);

src/node/volume.ts

@@ -2,6 +2,7 @@ import * as pathModule from 'path';
 import { Link, Superblock } from '../core';
 import Stats from './Stats';
 import Dirent from './Dirent';
+import StatFs from './StatFs';
 import { Buffer, bufferAllocUnsafe, bufferFrom } from '../internal/buffer';
 import queueMicrotask from '../queueMicrotask';
 import setTimeoutUnref, { TSetTimeout } from '../setTimeoutUnref';
@@ -32,6 +33,8 @@ import {
   getAppendFileOpts,
   getStatOptsAndCb,
   getStatOptions,
+  getStatfsOptsAndCb,
+  getStatfsOptions,
   getRealpathOptsAndCb,
   getRealpathOptions,
   getWriteFileOptions,
@@ -1442,10 +1445,29 @@ export class Volume implements FsCallbackApi, FsSynchronousApi {
     this.wrapAsync(this._cp, [srcFilename, destFilename, opts_], callback);
   };
 
-  /** @todo Implement statfs */
-  public statfsSync: FsSynchronousApi['statfsSync'] = notImplemented;
-  /** @todo Implement statfs */
-  public statfs: FsCallbackApi['statfs'] = notImplemented;
+  private _statfs(filename: string): StatFs<number>;
+  private _statfs(filename: string, bigint: false): StatFs<number>;
+  private _statfs(filename: string, bigint: true): StatFs<bigint>;
+  private _statfs(filename: string, bigint = false): StatFs {
+    // Verify the path exists to match Node.js behavior
+    this._core.getResolvedLinkOrThrow(filename, 'statfs');
+    return StatFs.build(this._core, bigint);
+  }
+
+  statfsSync(path: PathLike): StatFs<number>;
+  statfsSync(path: PathLike, options: { bigint: false }): StatFs<number>;
+  statfsSync(path: PathLike, options: { bigint: true }): StatFs<bigint>;
+  statfsSync(path: PathLike, options?: opts.IStafsOptions): StatFs {
+    const { bigint = false } = getStatfsOptions(options);
+    return this._statfs(pathToFilename(path), bigint as any);
+  }
+
+  statfs(path: PathLike, callback: misc.TCallback<StatFs>): void;
+  statfs(path: PathLike, options: opts.IStafsOptions, callback: misc.TCallback<StatFs>): void;
+  statfs(path: PathLike, a: misc.TCallback<StatFs> | opts.IStafsOptions, b?: misc.TCallback<StatFs>): void {
+    const [{ bigint = false }, callback] = getStatfsOptsAndCb(a, b);
+    this.wrapAsync(this._statfs, [pathToFilename(path), bigint], callback);
+  }
   /** @todo Implement openAsBlob */
   public openAsBlob: FsCallbackApi['openAsBlob'] = notImplemented;