Crate npm_utils 

Pure-Rust utilities for the npm registry and web assets.

Building blocks for fetching browser/JS dependencies at build time without Node or npm:

• registry — talk to an npm registry: build tarball URLs, fetch a package’s metadata, resolve the newest version matching a semver range, and search the registry (Registry::search).
• download — fetch bytes over HTTP (with a retry) and build GitHub archive URLs.
• extract — unpack .tar.gz and .zip archives into a destination directory, selecting all files, an explicit file map, or a predicate, with path-traversal protection.
• path_safety — the path-traversal hardening shared by extract and install: reject ../absolute paths and refuse symlink-redirected writes.
• cache — content-hash markers, a cross-process build lock, and directory helpers for skip-if-unchanged download caches.
• package_json — read pinned dependency versions from a package.json, and resolve its exports/module/browser/main to browser entry points (for generating an ES-module import map).
• resolve — locate files inside an installed dependency under node_modules/: walk up to node_modules/<name> and map a <name>/<subpath> to a real file, honoring the package’s exports when declared.
• install — produce a real node_modules/ directory, pure Rust, with every tarball sha512-verified: resolve a package.json’s transitive dependencies against the registry (install::node_modules), or install the exact tree a package-lock.json pins — devDependencies included, .bin shims and all — an npm ci in Rust (install::from_lockfile).
• project — mutate a package.json project: keep the lock + node_modules/ in sync (project::sync), upgrade dependencies within their ranges with a dry-run plan (project::plan_upgrade / project::upgrade), and remove them (project::remove).
• integrity — verify a downloaded tarball’s sha512 Subresource-Integrity (both install paths check it before trusting bytes).
• sbom — render the packages a package-lock.json pins as a license summary, a CycloneDX 1.6 document, or an SPDX 2.3 document — compliance artifacts, pure Rust, no Node.
• audit — check those same pinned packages against vulnerability advisories from multiple sources (npm’s registry endpoint, OSV) behind a small source trait — npm audit, pure Rust.

use npm_utils::{download, extract, registry::Registry};

let reg = Registry::npm();
let lit = reg.resolve("lit", &"^3".parse()?)?;
let tgz = download::fetch(&lit.tarball_url)?;
extract::tar_gz(&tgz, "dist/lit".as_ref(), Some("package/"), extract::Select::All)?;

Modules

audit

Vulnerability auditing for a parsed package-lock.json — npm audit, pure Rust.

cache

Skip-if-unchanged cache helpers: content-hash markers, a cross-process build lock, and directory utilities.

download

HTTP download helpers.

extract

Archive extraction, hardened against hostile archives.

install

Install a dependency tree into a node_modules/ directory — a pure-Rust “npm install” (node_modules, from a package.json) and “npm ci” (from_lockfile, from a package-lock.json). Each downloads, integrity-verifies, and extracts every package; the lockfile path also creates node_modules/.bin/ shims. Both are skip-if-unchanged (a marker beside node_modules/) and concurrency-safe via a cross-process lock.

integrity

Subresource-Integrity verification of downloaded tarballs.

package_json

Pure-Rust npm manifest + lockfile schemas, modeled on the npm specs:

path_safety

Path-traversal hardening shared by crate::extract and crate::install.

project

Project-level mutations: operations on a directory that holds a package.json — keep the lock and node_modules/ in step with the manifest (sync), upgrade dependencies within their ranges (upgrade, previewable with plan_upgrade), and remove them (remove).

registry

npm registry interaction: tarball URLs, package metadata, and version resolution against a semver range.

resolve

Locate files inside an installed dependency under node_modules/.

sbom

Software bill of materials + license output for a parsed package-lock.json.

Type Aliases

Error

The crate’s boxed, thread-safe error type. A single alias so the whole crate shares one error spelling, errors cross thread boundaries, and a future switch to a structured enum is one edit.

Result

The crate’s result type, defaulting the error to Error.