feat: add missing Node.js fs APIs with proper TypeScript types and stubs

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

Author: Copilot

docs/missing-apis.md

@@ -0,0 +1,89 @@
+# Missing Node.js fs APIs in memfs
+
+This document lists the Node.js filesystem APIs that are not yet implemented in memfs.
+
+## APIs with stub implementations (throw "Not implemented")
+
+These APIs are defined with proper TypeScript types but currently throw "Not implemented" errors when called:
+
+### File System Statistics
+
+- `fs.statfs(path[, options], callback)` - Get file system statistics
+- `fs.statfsSync(path[, options])` - Synchronous version of statfs
+- `fs.promises.statfs(path[, options])` - Promise-based statfs
+
+### File as Blob (Node.js 19+)
+
+- `fs.openAsBlob(path[, options])` - Open a file as a Blob object for web API compatibility
+
+### Pattern Matching (Node.js 20+)
+
+- `fs.glob(pattern[, options], callback)` - Find files matching a glob pattern
+- `fs.globSync(pattern[, options])` - Synchronous version of glob
+- `fs.promises.glob(pattern[, options])` - Promise-based glob
+
+## Implementation Status
+
+### ✅ Fully Implemented APIs
+
+All core Node.js fs APIs are implemented including:
+
+- Basic file operations (read, write, open, close, etc.)
+- Directory operations (mkdir, rmdir, readdir, etc.)
+- File metadata (stat, lstat, fstat, chmod, chown, utimes, etc.)
+- Symbolic links (symlink, readlink, etc.)
+- File watching (watch, watchFile, unwatchFile)
+- Streams (createReadStream, createWriteStream)
+- File copying (copyFile, cp)
+- File truncation (truncate, ftruncate)
+
+### 🚧 Stubbed APIs (not implemented)
+
+- `statfs` / `statfsSync` - File system statistics
+- `openAsBlob` - Open file as Blob
+- `glob` / `globSync` - Pattern matching
+
+## Usage
+
+When calling these unimplemented APIs, they will throw an error:
+
+```javascript
+const { Volume } = require('memfs');
+const vol = new Volume();
+
+try {
+  vol.globSync('*.js');
+} catch (err) {
+  console.log(err.message); // "Not implemented"
+}
+```
+
+## TypeScript Support
+
+All missing APIs have proper TypeScript type definitions:
+
+```typescript
+interface IGlobOptions {
+  cwd?: string | URL;
+  exclude?: string | string[];
+  maxdepth?: number;
+  withFileTypes?: boolean;
+}
+
+interface IOpenAsBlobOptions {
+  type?: string;
+}
+```
+
+## Contributing
+
+To implement any of these missing APIs:
+
+1. Replace the `notImplemented` stub with actual implementation
+2. Add tests for the new functionality
+3. Update this documentation
+
+## References
+
+- [Node.js fs API Documentation](https://nodejs.org/api/fs.html)
+- [memfs source code](https://github.com/streamich/memfs)

src/fsa-to-node/FsaNodeFs.ts

@@ -801,6 +801,7 @@ export class FsaNodeFs extends FsaNodeCore implements FsCallbackApi, FsSynchrono
   public readonly opendir: FsCallbackApi['opendir'] = notImplemented;
   public readonly readv: FsCallbackApi['readv'] = notImplemented;
   public readonly statfs: FsCallbackApi['statfs'] = notImplemented;
+  public readonly glob: FsCallbackApi['glob'] = notImplemented;
 
   /**
    * @todo Watchers could be implemented in the future on top of `FileSystemObserver`,
@@ -1088,6 +1089,7 @@ export class FsaNodeFs extends FsaNodeCore implements FsCallbackApi, FsSynchrono
   public readonly opendirSync: FsSynchronousApi['opendirSync'] = notImplemented;
   public readonly statfsSync: FsSynchronousApi['statfsSync'] = notImplemented;
   public readonly readvSync: FsSynchronousApi['readvSync'] = notImplemented;
+  public readonly globSync: FsSynchronousApi['globSync'] = notImplemented;
 
   public readonly symlinkSync: FsSynchronousApi['symlinkSync'] = notSupported;
   public readonly linkSync: FsSynchronousApi['linkSync'] = notSupported;

src/node/FsPromises.ts

@@ -137,6 +137,7 @@ export class FsPromises implements FsPromisesApi {
   public readonly opendir = promisify(this.fs, 'opendir');
   public readonly statfs = promisify(this.fs, 'statfs');
   public readonly lutimes = promisify(this.fs, 'lutimes');
+  public readonly glob = promisify(this.fs, 'glob');
   public readonly access = promisify(this.fs, 'access');
   public readonly chmod = promisify(this.fs, 'chmod');
   public readonly chown = promisify(this.fs, 'chown');

src/node/__tests__/missing-apis.test.ts

@@ -0,0 +1,43 @@
+import { Volume } from '../volume';
+
+describe('Missing APIs', () => {
+  let vol: Volume;
+
+  beforeEach(() => {
+    vol = new Volume();
+  });
+
+  describe('glob APIs', () => {
+    it('globSync should throw "Not implemented"', () => {
+      expect(() => vol.globSync('*.js')).toThrow('Not implemented');
+    });
+
+    it('glob should throw "Not implemented"', () => {
+      expect(() => vol.glob('*.js', () => {})).toThrow('Not implemented');
+    });
+
+    it('promises.glob should throw "Not implemented"', async () => {
+      await expect(vol.promises.glob('*.js')).rejects.toThrow('Not implemented');
+    });
+  });
+
+  describe('openAsBlob API', () => {
+    it('should throw "Not implemented"', () => {
+      expect(() => vol.openAsBlob('/test/file.txt')).toThrow('Not implemented');
+    });
+  });
+
+  describe('statfs APIs', () => {
+    it('statfsSync should throw "Not implemented"', () => {
+      expect(() => vol.statfsSync('/test')).toThrow('Not implemented');
+    });
+
+    it('statfs should throw "Not implemented"', () => {
+      expect(() => vol.statfs('/test', () => {})).toThrow('Not implemented');
+    });
+
+    it('promises.statfs should throw "Not implemented"', async () => {
+      await expect(vol.promises.statfs('/test')).rejects.toThrow('Not implemented');
+    });
+  });
+});

src/node/types/FsCallbackApi.ts

@@ -42,6 +42,10 @@ export interface FsCallbackApi {
     (fd: number, len: number, callback: misc.TCallback<void>): void;
   };
   futimes: (fd: number, atime: misc.TTime, mtime: misc.TTime, callback: misc.TCallback<void>) => void;
+  glob: {
+    (pattern: string, callback: misc.TCallback<string[]>): void;
+    (pattern: string, options: opts.IGlobOptions, callback: misc.TCallback<string[]>): void;
+  };
   lchmod: (path: misc.PathLike, mode: misc.TMode, callback: misc.TCallback<void>) => void;
   lchown: (path: misc.PathLike, uid: number, gid: number, callback: misc.TCallback<void>) => void;
   lutimes: (

src/node/types/FsPromisesApi.ts

@@ -38,4 +38,5 @@ export interface FsPromisesApi {
     options?: opts.IWatchOptions,
   ) => AsyncIterableIterator<{ eventType: string; filename: string | Buffer }>;
   writeFile: (id: misc.TFileHandle, data: misc.TPromisesData, options?: opts.IWriteFileOptions) => Promise<void>;
+  glob: (pattern: string, options?: opts.IGlobOptions) => Promise<string[]>;
 }

src/node/types/FsSynchronousApi.ts

@@ -21,6 +21,7 @@ export interface FsSynchronousApi {
   fsyncSync: (fd: number) => void;
   ftruncateSync: (fd: number, len?: number) => void;
   futimesSync: (fd: number, atime: misc.TTime, mtime: misc.TTime) => void;
+  globSync: (pattern: string, options?: opts.IGlobOptions) => string[];
   lchmodSync: (path: misc.PathLike, mode: misc.TMode) => void;
   lchownSync: (path: misc.PathLike, uid: number, gid: number) => void;
   lutimesSync: (path: misc.PathLike, atime: number | string | Date, time: number | string | Date) => void;

src/node/types/options.ts

@@ -200,6 +200,17 @@ export interface IOpenAsBlobOptions {
   type?: string;
 }
 
+export interface IGlobOptions {
+  /** Current working directory. */
+  cwd?: string | URL;
+  /** Exclude patterns. */
+  exclude?: string | string[];
+  /** Maximum search depth. */
+  maxdepth?: number;
+  /** Whether to include symbolic links. */
+  withFileTypes?: boolean;
+}
+
 export interface IOpendirOptions extends IOptions {
   /**
    * Number of directory entries that are buffered internally when reading from

src/node/volume.ts

@@ -1449,6 +1449,12 @@ export class Volume implements FsCallbackApi, FsSynchronousApi {
   /** @todo Implement openAsBlob */
   public openAsBlob: FsCallbackApi['openAsBlob'] = notImplemented;
 
+  /** @todo Implement glob */
+  public glob: FsCallbackApi['glob'] = notImplemented;
+
+  /** @todo Implement globSync */
+  public globSync: FsSynchronousApi['globSync'] = notImplemented;
+
   private readonly _opendir = (filename: string, options: opts.IOpendirOptions): Dir => {
     const link: Link = this._core.getResolvedLinkOrThrow(filename, 'scandir');
     const node = link.getNode();