Compatibility and limits

The four published Effect Virtual FS packages implement a documented subset of POSIX filesystem behavior. They do not provide a mounted host filesystem, a complete POSIX implementation, or a way to intercept direct calls to node:fs.

This page records the supported package format, runtime evidence, filesystem differences, and resource limits. Follow the API links for exact types and signatures.

Package compatibility

PackageModule formatPurpose
@effect-vfs/coreESM onlyRuntime-neutral volumes, callers, handles, snapshots, and overlays
@effect-vfs/memoryESM onlyEffect FileSystem.FileSystem adapter
@effect-vfs/persistenceESM onlyNamed SQLite checkpoints and live-image storage
@effect-vfs/nfsESM onlyNFSv4.1 export with guarded experimental writes

Use an ES module build. Each published package declares its supported Effect range in peerDependencies.effect. To check a specific release, run npm view @effect-vfs/core@VERSION peerDependencies.effect with its version. The current core and memory source manifests declare ~4.1.4, and the qualification jobs use Effect 4.1.4. Match any @effect/* providers to the installed Effect version.

The published manifests do not declare a minimum consumer Node.js version. See the tested configurations below. The SQLite provider requires Bun. Core and memory can also run on Node.js.

Memory execution mode

Memory volumes default to execution: "cooperative". Opt in to execution: "sync" when namespace and handle operations must complete synchronously. Operations still return Effects, and construction can require asynchronous setup.

import { Effect } from "effect"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
 
const program = Effect.gen(function*() {
  const volume = yield* Vfs.make({ execution: "sync" })
  const caller = yield* volume.caller()
  yield* caller.mkdir("/work")
  return yield* caller.stat("/work")
})

All callers and handles on that volume share the mode. Fixture, snapshot and overlay constructors accept the same option. Restoring without it selects cooperative scheduling; snapshots and images do not store execution policy. MemoryFileSystem.layerFromFixture(fixture, { execution: "sync" }) also supports the mode. Existing make and layer values keep their cooperative defaults. A live storage constructor rejects sync mode, even for a store reporting memory-only durability.

Sync coordination does not yield while owning state. Large paths, files, directories or subscriber sets can therefore block the thread. Snapshot and overlay processing can yield after immutable capture, and watch streams wait for events. The mode does not promise synchronous completion for arbitrary Effect programs, custom runtime hooks or community work outside the engine. It does not provide a native node:fs adapter.

Ordinary same-volume reentry fails with VolumeBusy. Scope cleanup can invalidate a handle during an active operation and reclaim its inode before that operation returns. Once a transition starts, installation and cleanup finish before interruption is delivered; an interruption can therefore report a completed mutation. Recursive helpers retain their existing partial-progress boundaries. No failed synchronous operation is left queued to mutate later.

Runtime evidence

Core and memory support the following runtime configurations. Both CI jobs import the built package exports, read and write a seeded file, interrupt a watch and check its release, apply a snapshot delta, search the restored snapshot, and round-trip a reference key. They exercise both the runtime's Effect crypto provider and asynchronous WebCrypto.

Supported runtimeOperating systemCI check
Node.js 24.21.0Ubuntu 24.04 x64Core and memory, Node 24.21.0
Bun 1.4.4Ubuntu 24.04 x64Core and memory, Bun 1.4.4

The Bun job also checks seek, sparse writes and truncate against both the memory adapter and host files. Earlier host-file failures on Bun 1.4.0 on macOS are recorded in #275. The Linux checks do not qualify macOS, Windows, or other runtime versions.

Browser bundling. The memory build bundles for a browser target and executes the bundle under Node.js. Browser and worker execution. These environments are outside the supported list. CI does not run the packages there.

The native Node filesystem provider and SQLite persistence have separate runtime checks. The core and memory rows do not extend to those packages.

Portable snapshot-delta operations use Effect's Digest and SecureRandom services. Supply the appropriate Effect crypto layer for the runtime at the application boundary.

Implemented filesystem behavior

The core supports regular files, directories, symbolic links, hard links, component-by-component path lookup, directory-relative lookup, scoped file and directory handles, metadata, permissions, namespace changes, watches, and snapshot capture.

The behavior follows documented POSIX.1-2024 rules for this subset, with these important boundaries:

  • typed Effect failures replace global errno;
  • Effect scopes manage derived callers, handles, and watch subscriptions;
  • caller privilege is explicit and does not come from the host process;
  • storage is dense and in memory, not sparse or host-backed; and
  • the memory adapter may follow Effect FileSystem behavior where it differs from the lower-level core contract.

These packages do not claim full POSIX conformance. They do not provide a C filesystem API, simulated process, device files, FIFOs, filesystem sockets, or descriptor duplication. Directory trees move between a host and a volume only as explicit copies through TreeTransfer, within the losses its Effect FileSystem adapter declares. The NFS server tracks read locks between NFS clients, but direct VFS callers do not participate in those locks. Named checkpoints are explicit copies. The separate SQLite live-image store does not currently qualify for host fsync durability.

Reference keys

volume.referenceKey(reference) returns a ReferenceKey: the volume identity, an epoch, the object's inode number, and a tag. The tag is 16 bytes of HMAC-SHA-256 over the other three under a secret only the volume holds. The schema carries the identity, epoch and tag as base64 and the inode number as a decimal string, so a key can be stored or sent and decoded again. volume.resolveReferenceKey(key) returns the same reference traversal would.

  • Every construction draws a new epoch and secret: make, fromSnapshot, fromFixture, and makeOverlay. A key never resolves in another volume, even one restored under the same identity.
  • A live volume keeps its epoch and secret across a reopen, so its keys resolve to the same objects after a restart.
  • A key from another identity or epoch fails ForeignReference, a key whose object is gone StaleReference, and a malformed key or one whose tag the volume did not compute InvalidReference. An unlinked file stays resolvable while a handle holds it.
  • Resolution is on the volume, not a caller, and checks no permission. Inode numbers are sequential, but a holder of one key cannot write another's tag, so a key reaches only an object some key was issued for.
  • Rolling a live store back to an older image can reuse an inode number for a different object. The key cannot detect that.
  • Two live volumes opened from one image, such as a copied store or a second open of the same bytes, share its identity, epoch and secret, so a key minted in one resolves to whatever holds that inode in the other. A live image has one writer; do not serve a copied store under persistent NFS filehandles beside the original.

Path limits

LimitValueConfigurable
Path component255 bytesNo
Symbolic-link traversals during one resolution40No
Total encoded path lengthUnlimited by defaultYes, with maxPathBytes
String path encodingValid UTF-8 without NUL or lone surrogatesNo

BytePath preserves arbitrary non-NUL filename bytes. String-returning operations fail when a stored name cannot be represented as UTF-8.

Absolute paths ignore a supplied directory base. Relative paths can use a live DirectoryHandle from the same volume.

Volume capacity limits

Pass optional limits when creating or restoring a core volume.

OptionWhat it limitsDefault
maxEntriesNamespace entriesNo configured limit
maxBytesLogical bytes held by regular files and symbolic-link targetsNo configured limit
maxFileBytesBytes in one regular file4,294,967,295 bytes
maxPathBytesTotal encoded bytes accepted for one pathNo configured limit

The dense-file ceiling of 4,294,967,295 bytes is fixed. maxFileBytes may lower it but cannot raise it. File contents and symbolic-link targets are charged once per inode, so hard links do not duplicate their byte charge. An unlinked file remains charged while an open handle keeps it alive.

The VirtualFileSystem API reference documents VolumeOptions and the constructors that accept it.

Watch behavior

volume.watch() opens a scoped stream of future committed create, update, and remove events.

  • Events are not replayed.
  • Registration is coordinated with mutations so an event cannot be lost while the subscription becomes active.
  • maxWatchEvents defaults to 256 queued events per subscriber and can be configured on a volume.
  • When a subscriber loses events, it receives Rescan at / and must read the volume again.
  • Closing the owning scope releases the subscription.
  • volume.watch({ scope }) narrows the stream to one object reference and, unless recursive is false, its subtree. Changes outside the scope never count toward its queue. The scope follows renames of the object and its ancestors, a move out of it arrives as Remove and a move into it as Create, Rescan names the object's current path, and the stream ends after Remove for the object once its last name is gone.

A slow consumer does not retain an unbounded event history. Treat Rescan as an invalidation signal, not a replay.

Tree operations

Three caller verbs work on a whole tree. Only a recursive mkdir is one change; the other two are compositions of smaller operations, so another caller can change the tree while they run.

  • caller.walk(directory) streams every entry below a directory, depth first and in the byte order of each directory's names, with its path relative to the directory, its reference, its kind, and its depth. It reads one directory at a time, holds no handle, reports symbolic links without following them, and refreshes no access time. It reaches each directory by name, as a path does, so it needs search permission on the directories above it and skips a directory that went away or was renamed out of the tree after it was listed. maxDepth, maxEntries, and maxBytes are optional and fail with LimitExceeded when passed.
  • mkdir(path, { recursive: true }) creates every missing directory on the path in one change, as mkdir -p does, so a failure creates none of them. It follows symbolic links on the way, walks dot names, and succeeds when the final directory exists.
  • remove(entry, { recursive: true }) empties a directory entry by entry, each by name, and stops at the first failure, whose path names the entry it stopped at. A directory with entries must be readable; no permission is changed to make it so. force forgives only the target itself going missing.

Glob limits

Globbing belongs to the memory adapter. Patterns may be relative to the selected root or absolute.

The local portable implementation supports *, Unicode-aware ?, **, character classes and ranges, POSIX character classes, class negation, escaping, and nested comma-list brace expansion. Expansion uses the upstream limits of 10,000 alternatives, a maximum expanded length of 2²² and 64 brace levels. It does not support extglobs, numeric brace ranges or whole-pattern negation.

A trailing slash matches directories only. Hidden names require an explicit leading dot in the pattern segment through the published FileSystem interface. Symlink directories are followed through explicit segments, and never recursively through **. Results follow depth-first order with sorted entries per directory. Excluded directories are pruned before reading them. Unreadable wildcard-reached directories are skipped; named unreadable directories fail.

Snapshot decode limits

decodeSnapshot and decodeSnapshotSink require a DecodeLimits value with its four counts. There is no default decode policy.

FieldWork it bounds
maxEncodedBytesEncoded snapshot input bytes
maxRecordsStored objects, one node each, the root included
maxEntriesNamespace entries, counting every name of a hard link
maxDecodedBytesDecoded bytes of names, file contents and link targets
maxLineBytesOne line of the encoding; optional, maxEncodedBytes

Encoded and decoded byte budgets use ByteSize.ByteSize. Record and entry limits are numbers. Restoring the decoded snapshot also applies the destination volume's capacity limits.

See the Snapshot API reference and VirtualFileSystem API reference.

Snapshot delta limits

One complete SnapshotDeltaLimits policy applies to delta creation, inspection, encoding, decoding, and application. Omitting it selects the frozen SnapshotDeltaLimits.default policy. SnapshotDeltaLimits.constrained is a smaller preset for memory-sensitive environments. A custom policy must provide every field.

The policy bounds encoded and decoded delta bytes, the bytes hashed for each snapshot's identity, base and target records, the changes a delta holds, the records an applied delta produces, namespace entries, output payload bytes, and the target records carried over from the base. Byte budgets use ByteSize.ByteSize; record and entry budgets use numbers.

See the Snapshot delta API reference for the preset values and complete policy schema.

Volume limits and delta-work limits apply independently. The default delta budget rejects a measured 10,000-file workspace that fits its volume quotas. See the qualified 10,000-file example for the complete volume and delta settings, the measured memory cost, and the workload's limits.

Which limits callers can configure

AreaCaller-configurable
Volume capacity and total path lengthYes, through VolumeOptions
Snapshot decodingYes, and a complete policy is required
Snapshot delta workYes, through a preset or complete custom policy
Path component length and symlink traversal countNo
Dense-file hard ceilingNo, but maxFileBytes can lower it
Watch queueYes, through maxWatchEvents
Glob brace expansionNo

Effect 4.1 migration

Effect 4.1 replaces the Crypto service with Digest and SecureRandom from effect/crypto. Volume constructors and layers, snapshot deltas and the NFS server now require Digest.Digest | SecureRandom.SecureRandom where they required Crypto.Crypto; the live image stores require only Digest.Digest. NodeCrypto.layer and BunCrypto.layer provide both, so a program that already provides one needs no change. Digest.layerWebCrypto and SecureRandom.layerWebCrypto provide them without a platform package. BunServices.layer does not include them. Provider defects remain defects. Effect peers are restricted to the 4.1 patch line.

Effect 4.1's FileSystem.make requires readDirectoryEntries and derives glob. The memory adapter now exposes its typed entry listing as readDirectoryEntries and keeps the local glob implementation described below, so glob results are unchanged. FileSystemTesting gains a readDirectoryEntries handler; its glob traversal still passes through the decorated readDirectory, stat and readLink handlers.

Effect 4.0.5 migration

This migration uses published Effect 4.0.5 packages. Its crypto requirements remain Crypto.Crypto, supplied by the matching Node or Bun crypto layer. Crypto provider failures are defects; filesystem, storage I/O and protocol failures retain their domain errors. The unreleased SecureRandom and Digest service split is tracked by TODOs at the capture points.

Device, inode and link-count metadata now use bigint values. Keep these values as bigints, including when grouping hard links. Positioned reads and readAlloc leave the sequential cursor unchanged. Opening with noFollow rejects the final symlink while following symlinks in parents. Watch onReady runs after registration can buffer events. Access checks enforce every requested readable and writable permission; access without flags remains an existence check.

The local glob implementation follows the pinned Effect portable algorithm. It matches Unicode characters, accepts absolute and normalized patterns, returns depth-first results, prunes excluded directories before reading them and skips unreadable directories reached through wildcards. Explicitly named unreadable directories still fail. Traversal performs ordinary directory reads, which may update access times under relatime. Snapshot Search retains its bounded contract. The FileSystemTesting glob handler runs once before traversal, and nested reads and stats pass through the decorated primitive handlers.

Effect 4.0.5 does not expose portable Glob, readDirectoryEntries or lstat. The adapter's internal typed-entry helper returns bare names and entry kinds, including dangling symlinks, for local glob traversal. These are internal implementation details, not additional methods promised on Effect's FileSystem service. The local matcher supports the future dot option, but the published service interface does not yet advertise it. TODOs identify when upstream implementations can replace these helpers. No compatibility service or fake upstream module is introduced.