Documentation
¶
Overview ¶
Package pkgjson handles package.json file reading, writing, and manipulation.
It provides a strongly-typed representation of package.json that preserves unknown fields during read/write operations and includes helpers for dependency management and remote package lookups.
Index ¶
- func FormatVersion(version string, useExactVersion bool) string
- func IsDowngrade(oldVersion, newVersion string) bool
- func StripVersionPrefix(version string) string
- func Write(fs afero.Fs, path string, pkg *PackageJSON) error
- type Author
- type DependencyMatcher
- type PackageJSON
- type PnpmConfig
- type UpdateOptions
- type UpdateResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatVersion ¶
FormatVersion formats a version string with optional caret prefix. If useExactVersion is true, returns the version as-is. Otherwise, adds a caret (^) prefix.
func IsDowngrade ¶ added in v0.12.0
IsDowngrade returns true if updating from oldVersion to newVersion would result in a version downgrade. If either version cannot be parsed as valid semver, returns false (allowing the update to proceed).
func StripVersionPrefix ¶ added in v0.12.0
StripVersionPrefix removes common version prefixes (^, ~, >=, >, <=, <, =) from a version string, returning the raw semver portion.
Types ¶
type Author ¶
type Author struct {
Name string `json:"name"`
Email string `json:"email,omitempty"`
URL string `json:"url,omitempty"`
}
Author represents a package.json author or contributor. Can be used for author, contributors, and maintainers fields.
type DependencyMatcher ¶
DependencyMatcher is a function that determines whether a dependency should be updated.
type PackageJSON ¶
type PackageJSON struct {
// Strongly-typed fields for common package.json properties.
Name string `json:"name,omitempty"`
Description string `json:"description,omitempty"`
License string `json:"license,omitempty"`
Private any `json:"private,omitempty"` // Can be string or bool
Type string `json:"type,omitempty"`
Version string `json:"version,omitempty"`
Scripts map[string]any `json:"scripts,omitempty"`
Dependencies map[string]string `json:"dependencies,omitempty"`
DevDependencies map[string]string `json:"devDependencies,omitempty"`
PeerDependencies map[string]string `json:"peerDependencies,omitempty"`
PackageManager string `json:"packageManager,omitempty"`
Engines map[string]any `json:"engines,omitempty"`
Workspaces any `json:"workspaces,omitempty"`
Repository any `json:"repository,omitempty"`
Keywords []string `json:"keywords,omitempty"`
Author any `json:"author,omitempty"` // Can be string or object
Contributors any `json:"contributors,omitempty"`
Maintainers any `json:"maintainers,omitempty"`
Homepage string `json:"homepage,omitempty"`
Bugs any `json:"bugs,omitempty"`
Funding any `json:"funding,omitempty"`
Files []string `json:"files,omitempty"`
Main string `json:"main,omitempty"`
Module string `json:"module,omitempty"`
Browser any `json:"browser,omitempty"`
Bin any `json:"bin,omitempty"`
Man any `json:"man,omitempty"`
Directories any `json:"directories,omitempty"`
Config any `json:"config,omitempty"`
Pnpm any `json:"pnpm,omitempty"`
Overrides any `json:"overrides,omitempty"`
Resolutions any `json:"resolutions,omitempty"`
// contains filtered or unexported fields
}
PackageJSON represents a package.json file structure. This type preserves all fields during read/write operations while providing strongly-typed access to common fields.
Unknown fields are automatically captured by marshmallow during unmarshaling and merged back during marshaling, ensuring complete preservation.
func FetchFromRemote ¶
func FetchFromRemote(ctx context.Context, url string) (*PackageJSON, error)
FetchFromRemote fetches and parses a package.json from a remote URL.
func Read ¶
func Read(fs afero.Fs, path string) (*PackageJSON, error)
Read parses package.json from disk and preserves unknown fields in raw.
func (*PackageJSON) GetDependencyVersion ¶ added in v0.12.0
func (pkg *PackageJSON) GetDependencyVersion(name string) string
GetDependencyVersion returns the version string for a dependency across all dependency types. Returns an empty string if the dependency is not found in any type.
func (*PackageJSON) HasAnyDependency ¶
func (pkg *PackageJSON) HasAnyDependency(matcher DependencyMatcher) bool
HasAnyDependency checks if the package has any dependencies matching the matcher.
func (*PackageJSON) HasDependency ¶
func (pkg *PackageJSON) HasDependency(name string) bool
HasDependency checks if the package has a specific dependency in any dependency type.
func (*PackageJSON) IsDevDependency ¶
func (pkg *PackageJSON) IsDevDependency(name string) bool
IsDevDependency checks if a package is in devDependencies.
type PnpmConfig ¶
type PnpmConfig struct {
OnlyBuiltDependencies []string `json:"onlyBuiltDependencies,omitempty"`
}
PnpmConfig represents pnpm-specific configuration in package.json.
type UpdateOptions ¶ added in v0.12.0
type UpdateOptions struct {
// AllowDowngrades permits updating to a lower version than currently installed.
AllowDowngrades bool
}
UpdateOptions configures the behaviour of UpdateDependencies.
type UpdateResult ¶
type UpdateResult struct {
Updated []string
Skipped []string // Dependencies skipped because updating would downgrade them.
OldVersions map[string]string
}
UpdateResult contains information about what dependencies were updated.
func UpdateDependencies ¶
func UpdateDependencies( pkg *PackageJSON, matcher DependencyMatcher, versionFormatter func(name, version string) string, opts ...UpdateOptions, ) *UpdateResult
UpdateDependencies updates dependencies that match the provided matcher function. It updates dependencies across all dependency types (dependencies, devDependencies, peerDependencies). By default, downgrades are prevented. Pass UpdateOptions with AllowDowngrades to override.
The versionFormatter function determines how to format the version string for each dependency. For example, regular dependencies might use "^1.0.0" while devDependencies use "1.0.0".
Source Files