{
  "type": "module",
  "source": "doc/api/vfs.md",
  "modules": [
    {
      "textRaw": "Virtual File System",
      "name": "virtual_file_system",
      "introduced_in": "v26.4.0",
      "type": "module",
      "meta": {
        "added": [
          "v26.4.0"
        ],
        "changes": []
      },
      "stability": 1,
      "stabilityText": "Experimental",
      "desc": "<p>The <code>node:vfs</code> module provides a virtual file system with a <code>node:fs</code>-like API.\nIt is useful for tests, fixtures, embedded assets, and other scenarios where you\nneed a self-contained file system without touching the actual file-system.</p>\n<p>To access it:</p>\n<pre><code class=\"language-mjs\">import vfs from 'node:vfs';\n</code></pre>\n<pre><code class=\"language-cjs\">const vfs = require('node:vfs');\n</code></pre>\n<p>This module is only available under the <code>node:</code> scheme, and only when Node.js\nis started with the <code>--experimental-vfs</code> flag.</p>",
      "modules": [
        {
          "textRaw": "Security",
          "name": "security",
          "type": "module",
          "desc": "<p>The VFS API is not a sandbox, permission system, or access-control mechanism.\nIt does not isolate untrusted code from the host file system or from other\nNode.js capabilities. Code that can access a <a href=\"#class-virtualfilesystem\"><code>VirtualFileSystem</code></a> instance,\nmount it, select its provider, or pass paths to it is trusted application code.</p>\n<p>Mounting a VFS only redirects supported <a href=\"fs.html\"><code>node:fs</code></a> calls whose resolved paths\nare under the mount point. It does not prevent code from using other paths or\nother Node.js APIs to access resources available to the process.\n<a href=\"#class-realfsprovider\"><code>RealFSProvider</code></a> maps VFS paths under its configured root and rejects paths\nthat resolve outside that root, but that check is not a security boundary. Do\nnot rely on VFS to run untrusted code; use operating-system-level isolation,\nsuch as separate users, containers, or platform sandboxes, when a security\nboundary is required.</p>",
          "displayName": "Security"
        },
        {
          "textRaw": "Basic usage",
          "name": "basic_usage",
          "type": "module",
          "desc": "<pre><code class=\"language-cjs\">const vfs = require('node:vfs');\n\nconst myVfs = vfs.create();\nmyVfs.mkdirSync('/dir', { recursive: true });\nmyVfs.writeFileSync('/dir/hello.txt', 'Hello, VFS!');\n\nconsole.log(myVfs.readFileSync('/dir/hello.txt', 'utf8')); // 'Hello, VFS!'\n</code></pre>\n<p><code>vfs.create()</code> returns a <a href=\"#class-virtualfilesystem\"><code>VirtualFileSystem</code></a> instance backed by a\n<a href=\"#class-memoryprovider\"><code>MemoryProvider</code></a> by default. The instance exposes synchronous,\ncallback-based, and promise-based file system methods that mirror the\nshape of the <a href=\"fs.html\"><code>node:fs</code></a> API. All paths are POSIX-style and absolute\n(starting with <code>/</code>).</p>",
          "displayName": "Basic usage"
        },
        {
          "textRaw": "Implementation details",
          "name": "implementation_details",
          "type": "module",
          "modules": [
            {
              "textRaw": "`Stats` objects",
              "name": "`stats`_objects",
              "type": "module",
              "desc": "<p>VFS <code>Stats</code> objects are real instances of <a href=\"fs.html#class-fsstats\"><code>fs.Stats</code></a> (or\n<a href=\"fs.html#class-fsstats\"><code>fs.BigIntStats</code></a> when <code>{ bigint: true }</code> is requested). Their\nfields use synthetic but stable values:</p>\n<ul>\n<li><code>dev</code> is <code>4085</code> (the VFS device id).</li>\n<li><code>ino</code> is monotonically increasing per process.</li>\n<li><code>blksize</code> is <code>4096</code>.</li>\n<li><code>blocks</code> is <code>Math.ceil(size / 512)</code>.</li>\n<li>Times default to the moment the entry was created/last modified.</li>\n</ul>",
              "displayName": "`Stats` objects"
            }
          ],
          "displayName": "Implementation details"
        }
      ],
      "methods": [
        {
          "textRaw": "`vfs.create([provider][, options])`",
          "name": "create",
          "type": "method",
          "meta": {
            "added": [
              "v26.4.0"
            ],
            "changes": []
          },
          "signatures": [
            {
              "params": [
                {
                  "textRaw": "`provider` {VirtualProvider} The provider to use. **Default:** `new MemoryProvider()`.",
                  "name": "provider",
                  "type": "VirtualProvider",
                  "default": "`new MemoryProvider()`",
                  "desc": "The provider to use.",
                  "optional": true
                },
                {
                  "textRaw": "`options` {Object}",
                  "name": "options",
                  "type": "Object",
                  "options": [
                    {
                      "textRaw": "`emitExperimentalWarning` {boolean} Whether to emit the experimental warning when the instance is created. **Default:** `true`.",
                      "name": "emitExperimentalWarning",
                      "type": "boolean",
                      "default": "`true`",
                      "desc": "Whether to emit the experimental warning when the instance is created."
                    }
                  ],
                  "optional": true
                }
              ],
              "return": {
                "textRaw": "Returns: {VirtualFileSystem}",
                "name": "return",
                "type": "VirtualFileSystem"
              }
            }
          ],
          "desc": "<p>Convenience factory equivalent to <code>new VirtualFileSystem(provider, options)</code>.</p>\n<pre><code class=\"language-cjs\">const vfs = require('node:vfs');\n\n// Default in-memory provider\nconst memoryVfs = vfs.create();\n\n// Explicit provider\nconst realVfs = vfs.create(new vfs.RealFSProvider('/tmp/vfs-root'));\n</code></pre>"
        }
      ],
      "classes": [
        {
          "textRaw": "Class: `VirtualFileSystem`",
          "name": "VirtualFileSystem",
          "type": "class",
          "meta": {
            "added": [
              "v26.4.0"
            ],
            "changes": []
          },
          "desc": "<p>A <code>VirtualFileSystem</code> wraps a <a href=\"#class-virtualprovider\"><code>VirtualProvider</code></a> and exposes a\n<code>node:fs</code>-like API. Each instance maintains its own file tree.</p>",
          "signatures": [
            {
              "textRaw": "`new VirtualFileSystem([provider][, options])`",
              "name": "VirtualFileSystem",
              "type": "ctor",
              "meta": {
                "added": [
                  "v26.4.0"
                ],
                "changes": []
              },
              "params": [
                {
                  "textRaw": "`provider` {VirtualProvider} The provider to use. **Default:** `new MemoryProvider()`.",
                  "name": "provider",
                  "type": "VirtualProvider",
                  "default": "`new MemoryProvider()`",
                  "desc": "The provider to use.",
                  "optional": true
                },
                {
                  "textRaw": "`options` {Object}",
                  "name": "options",
                  "type": "Object",
                  "options": [
                    {
                      "textRaw": "`emitExperimentalWarning` {boolean} Whether to emit the experimental warning. **Default:** `true`.",
                      "name": "emitExperimentalWarning",
                      "type": "boolean",
                      "default": "`true`",
                      "desc": "Whether to emit the experimental warning."
                    }
                  ],
                  "optional": true
                }
              ]
            }
          ],
          "properties": [
            {
              "textRaw": "{VirtualProvider}",
              "name": "provider",
              "type": "VirtualProvider",
              "meta": {
                "added": [
                  "v26.4.0"
                ],
                "changes": []
              },
              "desc": "<p>The provider backing this VFS instance.</p>"
            },
            {
              "textRaw": "{boolean}",
              "name": "readonly",
              "type": "boolean",
              "meta": {
                "added": [
                  "v26.4.0"
                ],
                "changes": []
              },
              "desc": "<p><code>true</code> when the underlying provider is read-only.</p>"
            }
          ],
          "modules": [
            {
              "textRaw": "APIs",
              "name": "apis",
              "type": "module",
              "desc": "<p><code>VirtualFileSystem</code> implements the following methods, with the same\nsignatures as their <a href=\"fs.html\"><code>node:fs</code></a> counterparts:</p>",
              "modules": [
                {
                  "textRaw": "Synchronous API",
                  "name": "synchronous_api",
                  "type": "module",
                  "desc": "<ul>\n<li><code>existsSync(path)</code></li>\n<li><code>statSync(path[, options])</code></li>\n<li><code>lstatSync(path[, options])</code></li>\n<li><code>readFileSync(path[, options])</code></li>\n<li><code>writeFileSync(path, data[, options])</code></li>\n<li><code>appendFileSync(path, data[, options])</code></li>\n<li><code>readdirSync(path[, options])</code></li>\n<li><code>mkdirSync(path[, options])</code></li>\n<li><code>rmdirSync(path)</code></li>\n<li><code>unlinkSync(path)</code></li>\n<li><code>renameSync(oldPath, newPath)</code></li>\n<li><code>copyFileSync(src, dest[, mode])</code></li>\n<li><code>realpathSync(path[, options])</code></li>\n<li><code>readlinkSync(path[, options])</code></li>\n<li><code>symlinkSync(target, path[, type])</code></li>\n<li><code>accessSync(path[, mode])</code></li>\n<li><code>rmSync(path[, options])</code></li>\n<li><code>truncateSync(path[, len])</code></li>\n<li><code>ftruncateSync(fd[, len])</code></li>\n<li><code>linkSync(existingPath, newPath)</code></li>\n<li><code>chmodSync(path, mode)</code></li>\n<li><code>chownSync(path, uid, gid)</code></li>\n<li><code>lchownSync(path, uid, gid)</code></li>\n<li><code>utimesSync(path, atime, mtime)</code></li>\n<li><code>lutimesSync(path, atime, mtime)</code></li>\n<li><code>mkdtempSync(prefix)</code></li>\n<li><code>opendirSync(path[, options])</code></li>\n<li><code>openAsBlob(path[, options])</code></li>\n<li>File-descriptor ops: <code>openSync</code>, <code>closeSync</code>, <code>readSync</code>, <code>writeSync</code>,\n<code>fstatSync</code></li>\n<li>Streams: <code>createReadStream</code>, <code>createWriteStream</code></li>\n<li>Watchers: <code>watch</code>, <code>watchFile</code>, <code>unwatchFile</code></li>\n</ul>",
                  "displayName": "Synchronous API"
                },
                {
                  "textRaw": "Callback API",
                  "name": "callback_api",
                  "type": "module",
                  "desc": "<p><code>readFile</code>, <code>writeFile</code>, <code>stat</code>, <code>lstat</code>, <code>readdir</code>, <code>realpath</code>, <code>readlink</code>,\n<code>access</code>, <code>open</code>, <code>close</code>, <code>read</code>, <code>write</code>, <code>rm</code>, <code>fstat</code>, <code>truncate</code>,\n<code>ftruncate</code>, <code>link</code>, <code>mkdtemp</code>, <code>opendir</code>. Each takes a Node.js-style\ncallback <code>(err, ...result) => {}</code>.</p>",
                  "displayName": "Callback API"
                },
                {
                  "textRaw": "Promise API",
                  "name": "promise_api",
                  "type": "module",
                  "desc": "<p><code>vfs.promises</code> exposes the promise-based variants:</p>\n<pre><code class=\"language-cjs\">const vfs = require('node:vfs');\n\nasync function example() {\n  const myVfs = vfs.create();\n  await myVfs.promises.writeFile('/file.txt', 'hello');\n  const data = await myVfs.promises.readFile('/file.txt', 'utf8');\n  return data;\n}\nexample();\n</code></pre>\n<p>The promise namespace mirrors <code>fs.promises</code> and includes <code>readFile</code>,\n<code>writeFile</code>, <code>appendFile</code>, <code>stat</code>, <code>lstat</code>, <code>readdir</code>, <code>mkdir</code>, <code>rmdir</code>,\n<code>unlink</code>, <code>rename</code>, <code>copyFile</code>, <code>realpath</code>, <code>readlink</code>, <code>symlink</code>,\n<code>access</code>, <code>rm</code>, <code>truncate</code>, <code>link</code>, <code>mkdtemp</code>, <code>chmod</code>, <code>chown</code>, <code>lchown</code>,\n<code>utimes</code>, <code>lutimes</code>, <code>open</code>, <code>lchmod</code>, and <code>watch</code>.</p>",
                  "displayName": "Promise API"
                }
              ],
              "displayName": "APIs"
            }
          ]
        },
        {
          "textRaw": "Class: `VirtualProvider`",
          "name": "VirtualProvider",
          "type": "class",
          "meta": {
            "added": [
              "v26.4.0"
            ],
            "changes": []
          },
          "desc": "<p>The base class for all VFS providers. Subclasses implement the essential\nprimitives (such as <code>open</code>, <code>stat</code>, <code>readdir</code>, <code>mkdir</code>, <code>rmdir</code>, <code>unlink</code>,\n<code>rename</code>, etc.) and inherit default implementations of the derived\nmethods (such as <code>readFile</code>, <code>writeFile</code>, <code>exists</code>, <code>copyFile</code>, <code>access</code>, etc.).</p>",
          "modules": [
            {
              "textRaw": "Capability flags",
              "name": "capability_flags",
              "type": "module",
              "desc": "<ul>\n<li><code>provider.readonly</code> <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#boolean_type\"><code>&#x3C;boolean></code></a> <strong>Default:</strong> <code>false</code>.</li>\n<li><code>provider.supportsSymlinks</code> <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#boolean_type\"><code>&#x3C;boolean></code></a> <strong>Default:</strong> <code>false</code>.</li>\n<li><code>provider.supportsWatch</code> <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#boolean_type\"><code>&#x3C;boolean></code></a> <strong>Default:</strong> <code>false</code>.</li>\n</ul>",
              "displayName": "Capability flags"
            },
            {
              "textRaw": "Creating custom providers",
              "name": "creating_custom_providers",
              "type": "module",
              "desc": "<pre><code class=\"language-cjs\">const { VirtualProvider } = require('node:vfs');\n\nclass StaticProvider extends VirtualProvider {\n  get readonly() { return true; }\n\n  statSync(path) { /* ... */ }\n  openSync(path, flags) { /* ... */ }\n  readdirSync(path, options) { /* ... */ }\n  // ...\n}\n</code></pre>\n<p>The base class throws <code>ERR_METHOD_NOT_IMPLEMENTED</code> for any primitive\nthat has not been overridden, and rejects writes from a <code>readonly</code>\nprovider with <code>EROFS</code>.</p>",
              "displayName": "Creating custom providers"
            }
          ]
        },
        {
          "textRaw": "Class: `MemoryProvider`",
          "name": "MemoryProvider",
          "type": "class",
          "meta": {
            "added": [
              "v26.4.0"
            ],
            "changes": []
          },
          "desc": "<p>The default in-memory provider. Stores files, directories, and symbolic\nlinks in a <code>Map</code>-backed tree, supports symlinks (<code>supportsSymlinks === true</code>), and supports watching (<code>supportsWatch === true</code>).</p>",
          "methods": [
            {
              "textRaw": "`memoryProvider.setReadOnly()`",
              "name": "setReadOnly",
              "type": "method",
              "meta": {
                "added": [
                  "v26.4.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": []
                }
              ],
              "desc": "<p>Locks the provider into read-only mode. Subsequent writes through any\n<a href=\"#class-virtualfilesystem\"><code>VirtualFileSystem</code></a> using this provider throw <code>EROFS</code>. There is no\nway to revert the provider to writable.</p>\n<pre><code class=\"language-cjs\">const vfs = require('node:vfs');\n\nconst provider = new vfs.MemoryProvider();\nconst myVfs = vfs.create(provider);\nmyVfs.writeFileSync('/seed.txt', 'initial');\n\nprovider.setReadOnly();\n\nmyVfs.writeFileSync('/x.txt', 'fail'); // throws EROFS\n</code></pre>"
            }
          ]
        },
        {
          "textRaw": "Class: `RealFSProvider`",
          "name": "RealFSProvider",
          "type": "class",
          "meta": {
            "added": [
              "v26.4.0"
            ],
            "changes": []
          },
          "desc": "<p>A provider that wraps a directory (i.e. one on the actual file system) and\nexposes its contents through the VFS API. All VFS paths are resolved relative to\nthe root and verified to stay inside it; symbolic links resolving outside the\nroot are rejected. This path mapping is not a sandbox or access-control\nmechanism.</p>",
          "signatures": [
            {
              "textRaw": "`new RealFSProvider(rootPath)`",
              "name": "RealFSProvider",
              "type": "ctor",
              "meta": {
                "added": [
                  "v26.4.0"
                ],
                "changes": []
              },
              "params": [
                {
                  "textRaw": "`rootPath` {string} The absolute file-system path to use as the root. Must be a non-empty string.",
                  "name": "rootPath",
                  "type": "string",
                  "desc": "The absolute file-system path to use as the root. Must be a non-empty string."
                }
              ],
              "desc": "<pre><code class=\"language-cjs\">const vfs = require('node:vfs');\n\nconst realVfs = vfs.create(new vfs.RealFSProvider('/tmp/vfs-root'));\nrealVfs.writeFileSync('/file.txt', 'hello'); // writes /tmp/vfs-root/file.txt\n</code></pre>"
            }
          ],
          "properties": [
            {
              "textRaw": "{string}",
              "name": "rootPath",
              "type": "string",
              "meta": {
                "added": [
                  "v26.4.0"
                ],
                "changes": []
              },
              "desc": "<p>The resolved absolute path used as the root.</p>"
            }
          ]
        }
      ],
      "displayName": "Virtual File System"
    }
  ]
}