Repository files navigation

Importable Volume — a drop-in replacement formemfs'sVolume

Import scripts and modules frommemfs' virtual filesystems.

import{impvol}from'impvol';/** * `impVol` is a `memfs.Volume` -- except it is ✨special✨ * *@type {import('impvol').ImportableVolume} */constimpVol=impvol({'/foo.mjs':'export const foo = 42;','/bar.cjs':'exports.bar = 42;',});awaitimpVol.promises.writeFile('/baz.mjs','export const baz = 42;');constfoo=awaitimport('/foo.mjs');// {foo: 42}constbar=awaitimport('/bar.cjs');// {bar: 42}constbaz=awaitimport('/baz.mjs');// {baz: 42}

Once anImportableVolume has been created, any specifier in the virtual filesystemwill be preferred over one in thereal file system. In other words:as long as/foo.mjs exists in theImportableVolume, a realfoo.mjs living in your FS root (/)cannot be imported viaimport(). You must firstremove/foo.mjs from theImportableVolume (e.g., viaimpvol.unlink() or otherwise).

Note:impvolonly works withimport(). It does not work withrequire().

• Node.js v20.0.0+
• memfs v4.49.0+

npm install impvol memfs -D

impvol is a dual ESM/CJS package. Thanks,tshy!

ImportableVolume creates a "customization hook", which runs in a worker thread. The worker thread maintains a "clone" of theImportableVolume's underlying filesystem (it's just a standardVolume in the worker thread).

When anImportableVolume's filesystem changes, it generates a snapshot of the filesystem and stores this in a temp file, then sets a "dirty bit" which is shared with the worker thread.

When the worker thread's resolve hook is hit, the dirty bit is checked. If it's set, the worker overwrites its virtual filesystem with the contents of the snapshot temp file, then finally resets the dirty bit. After the refresh, the resolve hook checks if the requested specifier matches a file in its filesystem.

If there's a match, the resolve hook short-circuits with a URL using a custom protocol -- which is subsequently handled by the loader hook. The loader hook reads the file from the worker thread's filesystem if the custom protocol is detected.

Repeatedly creatingImportableVolume instances will result in memory leaks because the worker threads running customization hooks are never terminated. As far as I can tell, such "module loader" worker threads are unable to be terminated by the parent process.

• JSON support
• WASM support, if anyone uses WASM in Node.js
• If Node.js ever allowsde-registration of customization hooks, then we can theoretically prevent memory leaks.
• How canimpvol be used via--import? Does that even make sense?

©️ 2024Christopher "boneskull" Hiller. Licensed Apache-2.0