README.md

pnp-rs

This crate implements the Yarn Plug'n'Play resolution algorithms for Rust so that it can be easily reused within Rust-based tools. It also includes utilities allowing to transparently read files from within zip archives.

Install

cargo add pnp

Resolution

fn example() {
    let manifest
        = load_pnp_manifest(".pnp.cjs").unwrap();

    let host = ResolutionHost {
        find_pnp_manifest: Box::new(move |_| Ok(Some(manifest.clone()))),
        ..Default::default()
    };

    let config = ResolutionConfig {
        host,
        ..Default::default()
    };

    let resolution = resolve_to_unqualified(
        "lodash/cloneDeep",
        std::path::PathBuf::from("/path/to/index.js"),
        &config,
    );

    match resolution {
        Ok(Resolution::Resolved(path, subpath)) => {
            // path = "/path/to/lodash.zip"
            // subpath = "cloneDeep"
        },
        Ok(Resolution::Skipped) => {
            // This is returned when the PnP resolver decides that it shouldn't
            // handle the resolution for this particular specifier. In that case,
            // the specifier should be forwarded to the default resolver.
        },
        Err(err) => {
            // An error happened during the resolution. Falling back to the default
            // resolver isn't recommended.
        },
    };
}

Filesystem utilities

While PnP only deals with the resolution, not the filesystem, the file maps generated by Yarn rely on virtual filesystem layers for two reasons:

• Virtual packages, which require a same package to have different paths to account for different set of dependencies (this only happens for packages that list peer dependencies)

• Zip storage, which Yarn uses so the installed files never have to be unpacked from their archives, leading to faster installs and fewer risks of cache corruption.

To make it easier to work with these virtual filesystems, the pnp crate also includes a VPath enum that lets you resolve virtual paths, and a set of zip manipulation utils (open_zip_via_read by default, and open_zip_via_mmap if the mmap feature is enabled).

use pnp::fs::{VPath, open_zip_via_read};

fn read_file(p: PathBuf) -> std::io::Result<String> {
    match VPath::from(&p).unwrap() {
        // The path was virtual and stored within a zip file; we need to read from the zip file
        // Note that this opens the zip file every time, which is expensive; we'll see how to optimize that
        VPath::Zip(info) => {
            open_zip_via_read(info.physical_base_path()).unwrap().read_to_string(&zip_path)
        },

        // The path was virtual but not a zip file; we just need to read from the provided location
        VPath::Virtual(info) => {
            std::fs::read_to_string(info.physical_base_path())
        },

        // Nothing special to do, it's a regular path
        VPath::Native(p) => {
            std::fs::read_to_string(&p)
        },
    }
}

Cache reuse

Opening and dropping a zip archive for every single file access would be expensive. To avoid that, pnp-rs provides an helper class called LruZipCache which lets you abstract away the zip opening and closing, and only keep the most recently used archives open.

use pnp::fs::{VPath, LruZipCache, open_zip_via_read};

const ZIP_CACHE: Lazy<LruZipCache<Vec<u8>>> = Lazy::new(|| {
    // It'll keep the last 50 zip archives open
    LruZipCache::new(50, open_zip_via_read_p)
});

fn read_file(p: PathBuf) -> std::io::Result<String> {
    match VPath::from(&p).unwrap() {
        // The path was virtual and stored within a zip file; we need to read from the zip file
        VPath::Zip(info) => {
            ZIP_CACHE.read_to_string(info.physical_base_path(), &zip_path)
        },

        // The path was virtual but not a zip file; we just need to read from the provided location
        VPath::Virtual(info) => {
            std::fs::read_to_string(info.physical_base_path())
        },

        // Nothing special to do, it's a regular path
        VPath::Native(p) => {
            std::fs::read_to_string(&p)
        },
    }
}