npmmod

Documentation

Overview

Package npmmod contains the core implementation of code used to parse, interpret and modify `package.json` and `package-lock.json` files.

In particular it seeks to replace versions in `package.json` from

> { > // ... > "dependencies": { > "react": "^18.0.0", > // ... > }, > "devDependencies": { > "@types/react": "^18.0.0", > // ... > }, > "peerDependencies": { > "@babel/core" "^7.0.0" > // ... > }, > // ... > }

to

> { > // ... > "dependencies": { > "react": "file:vendor/react-18.0.0.tgz", > // ... > }, > "devDependencies": { > "@types/react": "file:vendor/types__react-18.0.6.tgz", > // ... > }, > "peerDependencies": { > "@babel/core" "file:vendor/babel__core-7.17.9.tgz" > // ... > }, > // ... > }

And to replace all resolved packages in `package-lock.json` from

> { > // ... > "packages": { > // ... > "node_modules/@babel/core": { > "version": "7.17.9", > "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.17.9.tgz", > // ... > }, > // ... > "node_modules/@types/react": { > "version": "18.0.6", > "resolved": "https://registry.npmjs.org/@types/react/-/react-18.0.6.tgz", > // ... > }, > // ... > "node_modules/react": { > "version": "18.0.0", > "resolved": "https://registry.npmjs.org/react/-/react-18.0.0.tgz", > // ... > }, > // ... > }, > "dependencies": { > // ... > "@babel/core": { > "version": "7.17.9", > "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.17.9.tgz", > // ... > "dependencies": { > "semver": { > "version": "6.3.0", > "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", > // ... > } > } > }, > // ... > "@types/react": { > "version": "18.0.6", > "resolved": "https://registry.npmjs.org/@types/react/-/react-18.0.6.tgz", > // ... > }, > // ... > "react": { > "version": "18.0.0", > "resolved": "https://registry.npmjs.org/react/-/react-18.0.0.tgz", > // ... > }, > // ... > } > }

to

> { > // ... > "packages": { > // ... > "node_modules/@babel/core": { > "version": "file:vendor/babel__core-7.17.9.tgz", > "resolved": "file:vendor/babel__core-7.17.9.tgz", > // ... > }, > // ... > "node_modules/@types/react": { > "version": "file:vendor/types__react-18.0.6.tgz", > "resolved": "file:vendor/types__react-18.0.6.tgz", > // ... > }, > // ... > "node_modules/react": { > "version": "file:vendor/react-18.0.0.tgz", > "resolved": "file:vendor/react-18.0.0.tgz", > // ... > }, > // ... > }, > "dependencies": { > // ... > "@babel/core": { > "version": "file:vendor/babel__core-7.17.9.tgz", > "resolved": "file:vendor/babel__core-7.17.9.tgz", > // ... > "dependencies": { > "semver": { > "version": "file:vendor/semver-6.3.0.tgz", > "resolved": "file:vendor/semver-6.3.0.tgz", > // ... > } > } > }, > // ... > "@types/react": { > "version": "file:vendor/types__react-18.0.6.tgz", > "resolved": "file:vendor/types__react-18.0.6.tgz", > // ... > }, > // ... > "react": { > "version": "file:vendor/react-18.0.0.tgz", > "resolved": "file:vendor/react-18.0.0.tgz", > // ... > }, > // ... > } > }

Index

• func Fetch(ctx context.Context, url, algorithm, hash, filename string) error
• func FilenameFromURL(url string) (string, error)
• func Locate(dir string) (string, error)
• func PackageJSONReplaceDependencies(packageJSON *ordered.OrderedMap, replace ReplacePairFunc) error
• func PackageLockExtractDependencies(packageLock *ordered.OrderedMap) (map[string]RegistryPackage, map[string]RegistryPackage, error)
• func PackageLockReplaceDependencies(packageLock *ordered.OrderedMap, replace ReplaceFunc) error
• func ValidateIntegrity(data []byte, algorithm, hash string) error
• type CollectPackages
  • func (cp *CollectPackages) Visit(deps *ordered.OrderedMap, k string, v any) error
• type PackageJSONReplace
  • func (pjr *PackageJSONReplace) Replace(name, version string) string
• type PackageLockReplace
  • func (plr *PackageLockReplace) Replace(resolved string) string
• type RegistryPackage
  • func (rp RegistryPackage) Equal(other RegistryPackage) bool
  • func (rp RegistryPackage) Filename() (string, error)
• type ReplaceDependency
  • func (rd *ReplaceDependency) Visit(deps *ordered.OrderedMap, k string, v any) error
• type ReplaceFunc
• type ReplacePairFunc
• type ReplaceResolved
  • func (rr *ReplaceResolved) Visit(deps *ordered.OrderedMap, k string, v any) error
• type TidyFile
  • func GenerateTidyFile(root string) (*TidyFile, error)
  • func ReadTidyFile(root string) (*TidyFile, error)
  • func (tf *TidyFile) Persist() error
  • func (tf *TidyFile) Restore() error
  • func (tf *TidyFile) TidyPackageJSON() error
  • func (tf *TidyFile) TidyPackageLockJSON() error
• type VisitorFunc

Functions

func Fetch

func Fetch(ctx context.Context, url, algorithm, hash, filename string) error

Fetch downloads a package from `npm`, validates the checksum and then writes it to disk.

func FilenameFromURL

func FilenameFromURL(url string) (string, error)

FilenameFromURL creates a normalized filename from an `npm` registry URL.

func Locate

func Locate(dir string) (string, error)

Locate determines the location of the `package.json` file. It searches the current directory and then all parents until the file is found. This errors if the file cannot be found, if the file cannot be accessed by the current user or if the package lock cannot be found.

func PackageJSONReplaceDependencies

func PackageJSONReplaceDependencies(packageJSON *ordered.OrderedMap, replace ReplacePairFunc) error

PackageJSONReplaceDependencies iterates through all entries in the `package.json` dependencies maps and then replaces each package version based on a "replace" function.

func PackageLockExtractDependencies

func PackageLockExtractDependencies(packageLock *ordered.OrderedMap) (map[string]RegistryPackage, map[string]RegistryPackage, error)

PackageLockExtractDependencies iterates through all entries in the `package-lock.json` packages and dependencies maps and extracts the "resolved" URL.

func PackageLockReplaceDependencies

func PackageLockReplaceDependencies(packageLock *ordered.OrderedMap, replace ReplaceFunc) error

PackageLockReplaceDependencies iterates through all entries in the `package-lock.json` packages and dependencies maps and then replaces each package version based on a "replace" function.

func ValidateIntegrity

func ValidateIntegrity(data []byte, algorithm, hash string) error

ValidateIntegrity checks the hash of a downloaded package.

Types

type CollectPackages

type CollectPackages struct {
	ByNodeModulesPath map[string]RegistryPackage
	ByURL             map[string]RegistryPackage
	ParentKey         string
}

CollectPackages produces a vis]]]itor function that collects informationa about all packages in a `package-lock.json` (in particular, about the `resolved` URLs).

func (*CollectPackages) Visit

func (cp *CollectPackages) Visit(deps *ordered.OrderedMap, k string, v any) error

Visit is a visitor function that **tracks** a package `resolved` URL.

type PackageJSONReplace

type PackageJSONReplace struct {
	ByNodeModulesPath map[string]RegistryPackage
}

PackageJSONReplace provides a `replace` helper that replaces a `package.json` package version with a local `file:` reference.

func (*PackageJSONReplace) Replace

func (pjr *PackageJSONReplace) Replace(name, version string) string

Replace replaces a `package.json` package version with a local `file:` reference. In the case that the package name or version can't be matched or the filename can't be determined, this just returns the `version`.

type PackageLockReplace

type PackageLockReplace struct {
	ByURL map[string]RegistryPackage
}

PackageLockReplace provides a `replace` helper that replaces a `resolved` URL with a local `file:` reference.

func (*PackageLockReplace) Replace

func (plr *PackageLockReplace) Replace(resolved string) string

Replace replaces a `resolved` URL with a local `file:` reference. In the case that the URL can't be matched or the filename can't be determined, this just returns the `resolved`.

type RegistryPackage

type RegistryPackage struct {
	URL       string `json:"url"`
	Algorithm string `json:"algorithm"`
	Hash      string `json:"hash"`
}

RegistryPackage represents a package in an `npm` package registry.

func (RegistryPackage) Equal

func (rp RegistryPackage) Equal(other RegistryPackage) bool

Equal compares two registry packages for equality.

func (RegistryPackage) Filename

func (rp RegistryPackage) Filename() (string, error)

Filename creates a normalized filename from the `npm` registry URL.

type ReplaceDependency

type ReplaceDependency struct {
	Replace ReplacePairFunc
}

ReplaceDependency produces a visitor function that **replaces** a package version based on a `replace` function.

func (*ReplaceDependency) Visit

func (rd *ReplaceDependency) Visit(deps *ordered.OrderedMap, k string, v any) error

Visit is a visitor function that **replaces** a package version based on a `replace` function.

type ReplaceFunc

type ReplaceFunc func(value string) string

ReplaceFunc replaces a value based on the value.

type ReplacePairFunc

type ReplacePairFunc func(key, value string) string

ReplacePairFunc replaces a value based on the existing key/value pair.

type ReplaceResolved

type ReplaceResolved struct {
	Replace   ReplaceFunc
	ParentKey string
}

ReplaceResolved produces a visitor function that **replaces** a package `resolved` (and `version`) key based on a `replace` function.

func (*ReplaceResolved) Visit

func (rr *ReplaceResolved) Visit(deps *ordered.OrderedMap, k string, v any) error

Visit is a visitor function that **replaces** a package `resolved` (and `version`) key based on a `replace` function.

type TidyFile

type TidyFile struct {
	Version         string            `json:"version"`
	PackageJSON     []byte            `json:"package.json"`
	PackageLockJSON []byte            `json:"package-lock.json"`
	Packages        []RegistryPackage `json:"packages"`

	Root              string              `json:"-"`
	PackageParsed     *ordered.OrderedMap `json:"-"`
	PackageLockParsed *ordered.OrderedMap `json:"-"`
}

TidyFile represents a `.npm-mod.tidy.json`

func GenerateTidyFile

func GenerateTidyFile(root string) (*TidyFile, error)

GenerateTidyFile generates a `.npm-mod.tidy.json` by reading files from a `package.json` and `package-lock.json`.

func ReadTidyFile

func ReadTidyFile(root string) (*TidyFile, error)

ReadTidyFile reads a `.npm-mod.tidy.json` file.

func (*TidyFile) Persist

func (tf *TidyFile) Persist() error

Persist writes a `.npm-mod.tidy.json` to disk.

func (*TidyFile) Restore

func (tf *TidyFile) Restore() error

Restore writes back a `package.json` and `package-lock.json` based on the contents of a `.npm-mod.tidy.json` file.

func (*TidyFile) TidyPackageJSON

func (tf *TidyFile) TidyPackageJSON() error

TidyPackageJSON updates (and writes) a `package.json` file with the vendored dependencies.

This is a bit hacky. The algorithm is as follows:

• Iterate over every package in `dependencies`, `devDependencies` and `peerDependencies`
• Find the package in `packages` in the `package-lock.json`, for example the `node_modules/@testing-library/jest-dom` key corresponds to the `@testing-library/jest-dom` dependency
• Use the `resolved` URL for the `node_modules/...` match to determine the local filename to use

func (*TidyFile) TidyPackageLockJSON

func (tf *TidyFile) TidyPackageLockJSON() error

TidyPackageJSON updates (and writes) a `package-lock.json` file with the vendored dependencies.

type VisitorFunc

type VisitorFunc func(m *ordered.OrderedMap, k string, v any) error

VisitorFunc is a function for visiting a value in an ordered map. In addition to taking the key / value pair as input, it also returns the parent map so it can be modified if needed.