npm

Documentation

Overview

Package npm provides an HTTP client for the npm registry API.

Overview

This package fetches package metadata from the npm registry (https://registry.npmjs.org), the package manager for JavaScript.

Usage

client, err := npm.NewClient(24 * time.Hour)
if err != nil {
    log.Fatal(err)
}

pkg, err := client.FetchPackage(ctx, "express", false)
if err != nil {
    log.Fatal(err)
}

fmt.Println(pkg.Name, pkg.Version)
fmt.Println("Dependencies:", pkg.Dependencies)

PackageInfo

[FetchPackage] returns a PackageInfo containing:

• Name, Version: Package identity (latest version)
• Dependencies: Runtime dependencies from "dependencies" field
• Description: Package description
• License, Author: Package metadata
• Repository, HomePage: URLs for enrichment

Caching

Responses are cached to reduce load on the registry. The cache TTL is set when creating the client. Pass refresh=true to bypass the cache.

Version Selection

The client fetches the version tagged as "latest" in dist-tags. devDependencies, peerDependencies, and optionalDependencies are not included.

Index

• type Client
  • func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client
  • func (c *Client) FetchPackage(ctx context.Context, pkg string, refresh bool) (*PackageInfo, error)
  • func (c *Client) FetchPackageVersion(ctx context.Context, pkg, version string, refresh bool) (*PackageInfo, error)
  • func (c *Client) ListVersions(ctx context.Context, pkg string, refresh bool) ([]string, error)
  • func (c *Client) ListVersionsWithConstraints(ctx context.Context, pkg string, refresh bool) (map[string]string, error)
• type Dependency
• type PackageInfo

Types

type Client

type Client struct {
	*integrations.Client
	// contains filtered or unexported fields
}

Client provides access to the npm package registry API. It handles HTTP requests with caching and automatic retries.

All methods are safe for concurrent use by multiple goroutines.

func NewClient

func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client

NewClient creates an npm client with the given cache backend.

Parameters:

• backend: Cache backend for HTTP response caching (use storage.NullBackend{} for no caching)
• cacheTTL: How long responses are cached (typical: 1-24 hours)

The returned Client is safe for concurrent use.

func (*Client) FetchPackage

func (c *Client) FetchPackage(ctx context.Context, pkg string, refresh bool) (*PackageInfo, error)

FetchPackage retrieves metadata for a JavaScript/TypeScript package from npm (latest version).

The pkg parameter is normalized to lowercase with whitespace trimmed. Supports scoped packages (e.g., "@types/node"). Package name cannot be empty; an empty string will result in an API error.

If refresh is true, the cache is bypassed and a fresh API call is made. If refresh is false, cached data is returned if available and not expired.

Returns:

• PackageInfo populated with metadata for the "latest" dist-tag version
• integrations.ErrNotFound if the package doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)
• Other errors for JSON decoding failures or missing "latest" version

The returned PackageInfo pointer is never nil if err is nil. This method is safe for concurrent use.

func (*Client) FetchPackageVersion

func (c *Client) FetchPackageVersion(ctx context.Context, pkg, version string, refresh bool) (*PackageInfo, error)

FetchPackageVersion retrieves metadata for a specific version of an npm package.

The pkg parameter is normalized to lowercase. The version must be an exact version string (e.g., "4.17.21").

If refresh is true, the cache is bypassed and a fresh API call is made.

Returns:

• PackageInfo populated with metadata on success
• integrations.ErrNotFound if the package or version doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)

This method is safe for concurrent use.

func (*Client) ListVersions

func (c *Client) ListVersions(ctx context.Context, pkg string, refresh bool) ([]string, error)

ListVersions returns all available versions for a package. Versions are sorted lexicographically (not by semver), so "1.10.0" sorts before "1.2.0". Callers that need semver ordering should sort the result with a semver-aware comparator.

func (*Client) ListVersionsWithConstraints

func (c *Client) ListVersionsWithConstraints(ctx context.Context, pkg string, refresh bool) (map[string]string, error)

ListVersionsWithConstraints returns all versions and their Node.js runtime constraints. Returns a map of version -> engines.node (empty string if not specified).

type Dependency

type Dependency struct {
	Name       string // Package name
	Constraint string // Version constraint (e.g., "^4.17.0", ">=2.0.0"), empty for no constraint
}

Dependency represents a package dependency with version constraint.

type PackageInfo

type PackageInfo struct {
	Name         string       // Package name as published (e.g., "@scope/package", never empty in valid info)
	Version      string       // Latest version tag (e.g., "4.18.2", never empty in valid info)
	Dependencies []Dependency // Runtime dependencies with version constraints (nil or empty if none)
	Repository   string       // Normalized repository URL (empty if not provided)
	HomePage     string       // Homepage URL (may be empty)
	Description  string       // Package description (may be empty)
	License      string       // License identifier (e.g., "MIT", may be empty)
	LicenseText  string       // Full license text for custom licenses (may be empty)
	Author       string       // Author name (may be empty)
	RequiredNode string       // Node.js version constraint from engines.node (e.g., ">=18", may be empty)
}

PackageInfo holds metadata for a JavaScript/TypeScript package from npm.

The Version field always contains the "latest" dist-tag version. Dependencies include only runtime "dependencies", not devDependencies or peerDependencies.

Zero values: All string fields are empty, Dependencies is nil. This struct is safe for concurrent reads after construction.