npm_utils/lib.rs
1//! Pure-Rust utilities for the npm registry and web assets.
2//!
3//! Building blocks for fetching browser/JS dependencies at build time without
4//! Node or npm:
5//!
6//! - [`registry`] — talk to an npm registry: build tarball URLs, fetch a
7//! package's metadata, and resolve the newest version matching a semver range.
8//! - [`download`] — fetch bytes over HTTP (with a retry) and build GitHub
9//! archive URLs.
10//! - [`extract`] — unpack `.tar.gz` and `.zip` archives into a destination
11//! directory, selecting all files, an explicit file map, or a predicate, with
12//! path-traversal protection.
13//! - [`path_safety`] — the path-traversal hardening shared by `extract` and
14//! `install`: reject `..`/absolute paths and refuse symlink-redirected writes.
15//! - [`cache`] — content-hash markers, a cross-process build lock, and directory
16//! helpers for skip-if-unchanged download caches.
17//! - [`package_json`] — read pinned dependency versions from a `package.json`, and
18//! resolve its `exports`/`module`/`browser`/`main` to browser entry points (for
19//! generating an ES-module import map).
20//! - [`install`] — produce a real `node_modules/` directory, pure Rust, with every tarball
21//! sha512-verified: resolve a `package.json`'s transitive `dependencies` against the registry
22//! ([`install::node_modules`]), or install the exact tree a `package-lock.json` pins —
23//! devDependencies included, `.bin` shims and all — an `npm ci` in Rust
24//! ([`install::from_lockfile`]).
25//! - [`integrity`] — verify a downloaded tarball's `sha512` Subresource-Integrity (both
26//! install paths check it before trusting bytes).
27//!
28//! ```no_run
29//! use npm_utils::{download, extract, registry::Registry};
30//!
31//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
32//! let reg = Registry::npm();
33//! let lit = reg.resolve("lit", &"^3".parse()?)?;
34//! let tgz = download::fetch(&lit.tarball_url)?;
35//! extract::tar_gz(&tgz, "dist/lit".as_ref(), Some("package/"), extract::Select::All)?;
36//! # Ok(()) }
37//! ```
38
39pub mod cache;
40pub mod download;
41pub mod extract;
42pub mod install;
43pub mod integrity;
44// The npm `package.json` / `package-lock.json` schemas — a pure-parsing module (no IO),
45// modeled on the npm specs, with strict spec-conformance tests living beside it.
46pub mod package_json;
47pub mod path_safety;
48pub mod registry;