vfs: address review comments

- doc: expand VFS examples to show addFile and mount usage
- vfs: add comment explaining async event emission in streams
- vfs: use createEBADF error code instead of generic Error
- test: expand test-vfs-sea.js with more comprehensive tests
- test: add full SEA VFS integration test

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mcollina

doc/api/fs.md

@@ -8306,12 +8306,34 @@ Use `fs.createVirtual()` to create a new VFS instance:
 const fs = require('node:fs');
 
 const vfs = fs.createVirtual();
+
+// Add files to the VFS
+vfs.addFile('/config.json', JSON.stringify({ debug: true }));
+vfs.addFile('/data.txt', 'Hello, World!');
+
+// Mount the VFS at a specific path
+vfs.mount('/app');
+
+// Now files are accessible via standard fs APIs
+const config = JSON.parse(fs.readFileSync('/app/config.json', 'utf8'));
+console.log(config.debug); // true
 ```
 
 ```mjs
 import fs from 'node:fs';
 
 const vfs = fs.createVirtual();
+
+// Add files to the VFS
+vfs.addFile('/config.json', JSON.stringify({ debug: true }));
+vfs.addFile('/data.txt', 'Hello, World!');
+
+// Mount the VFS at a specific path
+vfs.mount('/app');
+
+// Now files are accessible via standard fs APIs
+const config = JSON.parse(fs.readFileSync('/app/config.json', 'utf8'));
+console.log(config.debug); // true
 ```
 
 ### `fs.createVirtual([options])`

lib/internal/vfs/streams.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { Readable } = require('stream');
+const { createEBADF } = require('internal/vfs/errors');
 
 /**
  * Creates a readable stream for a virtual file.
@@ -57,6 +58,8 @@ class VirtualReadStream extends Readable {
 
   /**
    * Opens the virtual file.
+   * Events are emitted synchronously within this method, which runs
+   * asynchronously via process.nextTick - matching real fs behavior.
    * @private
    */
   _openFile() {
@@ -84,7 +87,7 @@ class VirtualReadStream extends Readable {
       try {
         const vfd = require('internal/vfs/fd').getVirtualFd(this._fd);
         if (!vfd) {
-          this.destroy(new Error('Invalid file descriptor'));
+          this.destroy(createEBADF('read'));
           return;
         }
         this._content = vfd.getContentSync();

test/parallel/test-vfs-sea.js

@@ -1,26 +1,48 @@
 'use strict';
 
+// Tests for SEA VFS functions when NOT running as a Single Executable Application.
+// For full SEA VFS integration tests, see test/sea/test-single-executable-application-vfs.js
+
 const common = require('../common');
 const assert = require('assert');
 const fs = require('fs');
 
-// Test that SEA functions exist
-assert.strictEqual(typeof fs.getSeaVfs, 'function');
-assert.strictEqual(typeof fs.hasSeaAssets, 'function');
+// Test that SEA functions are exported from fs module
+assert.strictEqual(typeof fs.getSeaVfs, 'function', 'fs.getSeaVfs should be a function');
+assert.strictEqual(typeof fs.hasSeaAssets, 'function', 'fs.hasSeaAssets should be a function');
 
-// Test that SEA functions return appropriate values when not in SEA
+// Test hasSeaAssets() returns false when not running as SEA
 {
-  // hasSeaAssets should return false when not running as SEA
   const hasAssets = fs.hasSeaAssets();
-  assert.strictEqual(hasAssets, false);
+  assert.strictEqual(hasAssets, false, 'hasSeaAssets() should return false when not in SEA');
+}
 
-  // getSeaVfs should return null when not running as SEA
+// Test getSeaVfs() returns null when not running as SEA
+{
   const seaVfs = fs.getSeaVfs();
-  assert.strictEqual(seaVfs, null);
+  assert.strictEqual(seaVfs, null, 'getSeaVfs() should return null when not in SEA');
+}
+
+// Test getSeaVfs() with options still returns null when not in SEA
+{
+  const seaVfs = fs.getSeaVfs({ prefix: '/custom-sea' });
+  assert.strictEqual(seaVfs, null, 'getSeaVfs() with prefix option should return null when not in SEA');
+}
+
+{
+  const seaVfs = fs.getSeaVfs({ moduleHooks: false });
+  assert.strictEqual(seaVfs, null, 'getSeaVfs() with moduleHooks option should return null when not in SEA');
+}
+
+{
+  const seaVfs = fs.getSeaVfs({ prefix: '/my-app', moduleHooks: true });
+  assert.strictEqual(seaVfs, null, 'getSeaVfs() with multiple options should return null when not in SEA');
 }
 
-// Test with custom options (should still return null when not in SEA)
+// Verify that calling getSeaVfs multiple times is safe (caching behavior)
 {
-  const seaVfs = fs.getSeaVfs({ prefix: '/custom-sea', moduleHooks: false });
-  assert.strictEqual(seaVfs, null);
+  const vfs1 = fs.getSeaVfs();
+  const vfs2 = fs.getSeaVfs();
+  assert.strictEqual(vfs1, vfs2, 'Multiple calls to getSeaVfs() should return the same value');
+  assert.strictEqual(vfs1, null, 'Both should be null when not in SEA');
 }

test/sea/test-single-executable-application-vfs.js

@@ -0,0 +1,141 @@
+'use strict';
+
+require('../common');
+
+const {
+  generateSEA,
+  skipIfSingleExecutableIsNotSupported,
+} = require('../common/sea');
+
+skipIfSingleExecutableIsNotSupported();
+
+// This tests the SEA VFS integration - fs.getSeaVfs() and fs.hasSeaAssets()
+
+const tmpdir = require('../common/tmpdir');
+const { writeFileSync } = require('fs');
+const { spawnSyncAndAssert } = require('../common/child_process');
+const { join } = require('path');
+
+const configFile = tmpdir.resolve('sea-config.json');
+const seaPrepBlob = tmpdir.resolve('sea-prep.blob');
+const outputFile = tmpdir.resolve(process.platform === 'win32' ? 'sea.exe' : 'sea');
+
+// The script that will run inside the SEA
+const seaMain = `
+'use strict';
+const fs = require('fs');
+const assert = require('assert');
+
+// Test hasSeaAssets() returns true when we have assets
+const hasAssets = fs.hasSeaAssets();
+assert.strictEqual(hasAssets, true, 'hasSeaAssets() should return true');
+console.log('hasSeaAssets:', hasAssets);
+
+// Test getSeaVfs() returns a VFS instance
+const vfs = fs.getSeaVfs();
+assert.ok(vfs !== null, 'getSeaVfs() should not return null');
+console.log('getSeaVfs returned VFS instance');
+
+// Test that the VFS is mounted at /sea by default
+// and contains our assets
+
+// Read the config file through standard fs (via VFS hooks)
+const configContent = fs.readFileSync('/sea/config.json', 'utf8');
+const config = JSON.parse(configContent);
+assert.strictEqual(config.name, 'test-app', 'config.name should match');
+assert.strictEqual(config.version, '1.0.0', 'config.version should match');
+console.log('Read config.json:', config);
+
+// Read a text file
+const greeting = fs.readFileSync('/sea/data/greeting.txt', 'utf8');
+assert.strictEqual(greeting, 'Hello from SEA VFS!', 'greeting should match');
+console.log('Read greeting.txt:', greeting);
+
+// Test existsSync
+assert.strictEqual(fs.existsSync('/sea/config.json'), true);
+assert.strictEqual(fs.existsSync('/sea/data/greeting.txt'), true);
+assert.strictEqual(fs.existsSync('/sea/nonexistent.txt'), false);
+console.log('existsSync tests passed');
+
+// Test statSync
+const configStat = fs.statSync('/sea/config.json');
+assert.strictEqual(configStat.isFile(), true);
+assert.strictEqual(configStat.isDirectory(), false);
+console.log('statSync tests passed');
+
+// Test readdirSync
+const entries = fs.readdirSync('/sea');
+assert.ok(entries.includes('config.json'), 'Should include config.json');
+assert.ok(entries.includes('data'), 'Should include data directory');
+console.log('readdirSync tests passed, entries:', entries);
+
+// Test requiring a module from SEA VFS
+const mathModule = require('/sea/modules/math.js');
+assert.strictEqual(mathModule.add(2, 3), 5, 'math.add should work');
+assert.strictEqual(mathModule.multiply(4, 5), 20, 'math.multiply should work');
+console.log('require from VFS tests passed');
+
+// Test getSeaVfs with custom prefix
+const customVfs = fs.getSeaVfs({ prefix: '/custom' });
+// Note: getSeaVfs is a singleton, so it returns the same instance
+// with the same mount point (/sea) regardless of options passed after first call
+assert.strictEqual(customVfs, vfs, 'Should return the same cached instance');
+console.log('Cached VFS instance test passed');
+
+console.log('All SEA VFS tests passed!');
+`;
+
+// Create the main script file
+writeFileSync(tmpdir.resolve('sea-main.js'), seaMain);
+
+// Create asset files
+writeFileSync(tmpdir.resolve('config.json'), JSON.stringify({
+  name: 'test-app',
+  version: '1.0.0',
+}));
+
+writeFileSync(tmpdir.resolve('greeting.txt'), 'Hello from SEA VFS!');
+
+writeFileSync(tmpdir.resolve('math.js'), `
+module.exports = {
+  add: (a, b) => a + b,
+  multiply: (a, b) => a * b,
+};
+`);
+
+// Create SEA config with assets
+writeFileSync(configFile, JSON.stringify({
+  main: 'sea-main.js',
+  output: 'sea-prep.blob',
+  assets: {
+    'config.json': 'config.json',
+    'data/greeting.txt': 'greeting.txt',
+    'modules/math.js': 'math.js',
+  },
+}));
+
+// Generate the SEA prep blob
+spawnSyncAndAssert(
+  process.execPath,
+  ['--experimental-sea-config', 'sea-config.json'],
+  { cwd: tmpdir.path },
+  {}
+);
+
+// Generate the SEA executable
+generateSEA(outputFile, process.execPath, seaPrepBlob);
+
+// Run the SEA and verify output
+spawnSyncAndAssert(
+  outputFile,
+  [],
+  {
+    env: {
+      ...process.env,
+      NODE_DEBUG_NATIVE: undefined,
+    },
+  },
+  {
+    stdout: /All SEA VFS tests passed!/,
+  }
+);