pkggodev

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 22, 2026 License: MIT Imports: 14 Imported by: 0

README

Typed Go client for pkg.go.dev

tag Go Version GoDoc Build Status Go report Contributors License

A typed Go client for the pkg.go.dev API (the "Go Pkgsite API", https://pkg.go.dev/v1beta): search packages and symbols, read documentation (whole package or a single symbol), list versions, importers and known vulnerabilities.

The public API lives at the module root (package pkggodev): context-first methods, functional options, clean typed results (no codegen leakage) and auto-paginating iterators. It wraps an ogen-generated client kept under internal/api.

[!TIP] Looking for a CLI or MCP instead of a Go library? Use samber/godig — the pkg.go.dev CLI powered by this client.

🚀 Install

go get github.com/samber/go-pkggodev-client

This library is v0 and follows SemVer. It is compatible with Go >= 1.25 (uses iter.Seq2).

💡 Quick start

import pkggodev "github.com/samber/go-pkggodev-client"

c, err := pkggodev.New(pkggodev.WithUserAgent("my-app/1.0"))
if err != nil {
	panic(err)
}

// Single object.
pkg, _ := c.Package(ctx, "github.com/samber/lo")
fmt.Println(pkg.Path, pkg.Synopsis) // clean strings, no Opt wrappers

// A single symbol's documentation (token-efficient, no full package blob).
sym, err := c.Symbol(ctx, "github.com/samber/lo", "Map", pkggodev.WithExamples())
if errors.Is(err, pkggodev.ErrSymbolNotFound) {
	// symbol does not exist in the package
}
fmt.Println(sym.Kind, sym.Signature) // "Function", "func Map[...](...) ..."
fmt.Println(sym.Synopsis)            // first sentence of the doc

// One page.
page, _ := c.Versions(ctx, "github.com/samber/lo", pkggodev.WithLimit(10))
fmt.Println(page.Total, page.NextToken)

// All results, auto-paginated.
for v, err := range c.AllVersions(ctx, "github.com/samber/lo") {
	if err != nil {
		break
	}
	fmt.Println(v.Version, v.CommitTime)
}

🧠 Spec

GoDoc: https://pkg.go.dev/github.com/samber/go-pkggodev-client

Client constructor
func New(opts ...ClientOption) (*Client, error)
  • WithBaseURL(url) — override the API base URL.
  • WithHTTPClient(*http.Client) — custom timeouts / transport.
  • WithUserAgent(string) — set the User-Agent header.
  • WithGoproxy(string) — override the module proxy list used by MajorVersions (same syntax as the GOPROXY env var; honored by default, defaulting to https://proxy.golang.org).
Methods

All take context.Context first and return clean, typed values:

Method Returns
Search(ctx, opts...) *Page[SearchResult]
Package(ctx, path, opts...) *Package
ImportedBy(ctx, path, opts...) *ImportedByResult
Packages(ctx, path, opts...) *PackagesResult
Module(ctx, path, opts...) *Module
Versions(ctx, path, opts...) *Page[ModuleVersion]
Symbols(ctx, path, opts...) *Page[SymbolInfo]
Symbol(ctx, path, symbol, opts...) *Symbol
Vulns(ctx, path, opts...) *Page[Vulnerability]
MajorVersions(ctx, modulePath, opts...) *Page[MajorVersion]

Symbols lists the package symbols as lightweight SymbolInfo values (name, kind, synopsis, parent). Symbol returns the full documentation of a single symbol (func, type, method, var or const) instead of the whole package doc blob — handy to keep token usage low. symbol is the exported identifier ("Map") or "Type.Method" ("Either.ForEach"); matching is case-sensitive. The doc is derived client-side from the package documentation (always fetched as Markdown, so WithDoc is ignored here) and the method returns ErrSymbolNotFound when the symbol is absent. Pass WithExamples to include runnable examples.

Major versions

In Go, major versions beyond v1 live as separate modules (path, path/v2, path/v3…) and can be non-contiguous (e.g. v1, v2, v4, v6). pkg.go.dev does not yet expose a MajorVersions endpoint (golang/go#76718), so MajorVersions derives the answer from the Go module proxy — honoring GOPROXY (see WithGoproxy). It lists the tagged versions of the base path (which yields v0, v1 and any +incompatible majors that share it) and probes path/vN for higher majors. gopkg.in/pkg.vN paths are supported too.

page, _ := c.MajorVersions(ctx, "github.com/samber/do")
for _, mv := range page.Items {
	fmt.Println(mv.Major, mv.ModulePath, mv.Version, mv.IsLatest)
	// v2 github.com/samber/do/v2 v2.0.0 true
	// v1 github.com/samber/do    v1.6.0 false
}

Each MajorVersion carries its own ModulePath, the Major ("v2"), the latest Version in that major, and IsLatest for the highest major. Results are sorted newest-major-first. The module proxy has no pagination cursor, so the result is a single page. WithExcludePseudo drops majors whose latest version is a pseudo-version (reflecting ExcludePseudo from the proposal); WithLimit caps the number of returned majors (the proposal's Max); WithFilter matches each major's module path. MajorVersions returns ErrProxyDisabled when GOPROXY is off/direct-only and ErrInvalidModulePath for an unparsable path.

Call options

WithVersion, WithModule, WithLimit, WithToken, WithFilter, WithGOOS, WithGOARCH, WithDoc, WithQuery, WithSymbol, WithExamples, WithImports, WithLicenses, WithReadme, WithExcludePseudo. Each method ignores options that do not apply to it.

Iterators (auto-pagination)

Each listing endpoint has an All… variant returning a Go 1.25 iter.Seq2[T, error] that lazily follows NextToken across pages:

AllSearch, AllVersions, AllVulns, AllSymbols, AllPackages, AllImportedBy.

for v, err := range c.AllVersions(ctx, "github.com/samber/lo") {
	if err != nil {
		return err
	}
	fmt.Println(v.Version, v.CommitTime)
}

WithLimit controls the page size; WithToken sets the starting cursor.

🤝 Contributing

# Install dev dependencies
make tools

# Run tests
make test

# Lint
make lint

👤 Contributors

Contributors

💫 Show your support

Give a ⭐️ if this project helped you!

GitHub Sponsors

📝 License

Copyright © 2026 Samuel Berthe.

This project is MIT licensed.

Documentation

Overview

Package pkggodev is a typed Go client for the pkg.go.dev API.

It wraps the ogen-generated client (under internal/api) with an ergonomic, context-first surface and clean response types.

Index

Constants

View Source 
const DefaultBaseURL = api.DefaultBaseURL

DefaultBaseURL is the production pkg.go.dev API base URL.

View Source 
const DefaultMaxIdleConns = 1000

DefaultMaxIdleConns is the number of idle keep-alive connections the default HTTP client keeps open for reuse, shared across the API and proxy calls. The standard http.DefaultTransport keeps only 2 idle connections per host, which throttles the highly concurrent calls this client is built for.

Variables

View Source 
var ErrInvalidModulePath = errors.New("pkggodev: invalid module path")

ErrInvalidModulePath is returned when a module path cannot be parsed, e.g. by MajorVersions.

View Source 
var ErrProxyDisabled = errors.New("pkggodev: no usable module proxy (GOPROXY)")

ErrProxyDisabled is returned by MajorVersions when no usable module proxy is configured (GOPROXY is "off" or resolves to "direct" only).

View Source 
var ErrSymbolNotFound = errors.New("pkggodev: symbol not found")

ErrSymbolNotFound is returned by Client.Symbol when the requested symbol is absent from the package documentation.

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the pkg.go.dev API api.

func New 

func New(opts ...ClientOption) (*Client, error)

New builds a pkg.go.dev client with sane defaults.

func (*Client) AllImportedBy 

func (c *Client) AllImportedBy(ctx context.Context, path string, opts ...Option) iter.Seq2[string, error]

AllImportedBy iterates all packages that import the package at path.

func (*Client) AllPackages 

func (c *Client) AllPackages(ctx context.Context, path string, opts ...Option) iter.Seq2[PackageInfo, error]

AllPackages iterates all packages contained in the module at path.

func (*Client) AllSearch 

func (c *Client) AllSearch(ctx context.Context, opts ...Option) iter.Seq2[SearchResult, error]

AllSearch iterates all search results, fetching pages lazily.

func (*Client) AllSymbols 

func (c *Client) AllSymbols(ctx context.Context, path string, opts ...Option) iter.Seq2[SymbolInfo, error]

AllSymbols iterates all exported symbols of the package at path.

func (*Client) AllVersions 

func (c *Client) AllVersions(ctx context.Context, path string, opts ...Option) iter.Seq2[ModuleVersion, error]

AllVersions iterates all versions of the module at path, fetching pages lazily.

func (*Client) AllVulns 

func (c *Client) AllVulns(ctx context.Context, path string, opts ...Option) iter.Seq2[Vulnerability, error]

AllVulns iterates all vulnerabilities for the module or package at path.

func (*Client) ImportedBy 

func (c *Client) ImportedBy(ctx context.Context, path string, opts ...Option) (*ImportedByResult, error)

ImportedBy lists the packages that import the package at path.

func (*Client) MajorVersions added in v0.2.0 

func (c *Client) MajorVersions(ctx context.Context, modulePath string, opts ...Option) (*Page[MajorVersion], error)

MajorVersions discovers the major versions of the module at modulePath.

In Go, majors beyond v1 live as separate modules (path, path/v2, path/v3...) and can be non-contiguous. pkg.go.dev does not (yet) expose a MajorVersions endpoint (golang/go#76718), so this derives the answer from the module proxy (honoring GOPROXY, see WithGoproxy). modulePath may already carry a major suffix (path/v2 or gopkg.in/pkg.v2); it is normalized to the base path first.

WithExcludePseudo drops majors whose latest version is a pseudo-version. WithFilter applies a regular expression to each major's module path. WithLimit caps the number of returned majors (the proposal's Max), keeping the most recent ones. The module proxy has no pagination cursor, so the result is always a single page (NextToken is empty); Total is the count before WithLimit.

func (*Client) Module 

func (c *Client) Module(ctx context.Context, path string, opts ...Option) (*Module, error)

Module returns metadata for the module at path.

func (*Client) Package 

func (c *Client) Package(ctx context.Context, path string, opts ...Option) (*Package, error)

Package returns documentation and metadata for the package at path.

func (*Client) Packages 

func (c *Client) Packages(ctx context.Context, path string, opts ...Option) (*PackagesResult, error)

Packages lists the packages contained in the module at path.

func (*Client) Search 

func (c *Client) Search(ctx context.Context, opts ...Option) (*Page[SearchResult], error)

Search finds packages and symbols. Use WithQuery and/or WithSymbol.

func (*Client) Symbol added in v0.2.0 

func (c *Client) Symbol(ctx context.Context, path, symbol string, opts ...Option) (*Symbol, error)

Symbol returns the full documentation of a single symbol of the package at path. symbol is the exported identifier (e.g. "Map") or "Type.Method" (e.g. "Either.ForEach"); matching is case-sensitive. WithExamples includes runnable examples.

The documentation is derived client-side from the package documentation, which is always requested in Markdown form, so WithDoc has no effect here. It returns ErrSymbolNotFound when the symbol is absent from the package.

func (*Client) Symbols 

func (c *Client) Symbols(ctx context.Context, path string, opts ...Option) (*Page[SymbolInfo], error)

Symbols lists the exported symbols of the package at path.

func (*Client) Versions 

func (c *Client) Versions(ctx context.Context, path string, opts ...Option) (*Page[ModuleVersion], error)

Versions lists the versions of the module at path.

func (*Client) Vulns 

func (c *Client) Vulns(ctx context.Context, path string, opts ...Option) (*Page[Vulnerability], error)

Vulns lists known vulnerabilities for the module or package at path.

type ClientOption 

type ClientOption func(*clientConfig)

ClientOption configures the Client built by New.

func WithBaseURL 

func WithBaseURL(u string) ClientOption

WithBaseURL overrides the API base URL.

func WithGoproxy added in v0.2.0 

func WithGoproxy(s string) ClientOption

WithGoproxy overrides the module proxy list used by MajorVersions. The value uses the same syntax as the GOPROXY environment variable (a "," or "|" separated list of base URLs, plus the keywords "direct" and "off"). When unset, the client honors the GOPROXY environment variable, defaulting to https://proxy.golang.org.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) ClientOption

WithHTTPClient sets a custom *http.Client (timeouts, transport, etc.).

func WithUserAgent 

func WithUserAgent(ua string) ClientOption

WithUserAgent sets the User-Agent header sent on every request.

type Example added in v0.2.0 

type Example struct {
	Name   string `json:"name,omitempty"` // Suffix of "Example (name)", empty for a bare "Example".
	Code   string `json:"code"`
	Output string `json:"output,omitempty"`
}

Example is a runnable example attached to a symbol.

type ImportedByResult 

type ImportedByResult struct {
	ModulePath string       `json:"modulePath,omitempty"`
	Version    string       `json:"version,omitempty"`
	Packages   Page[string] `json:"packages"`
}

ImportedByResult lists the packages that import a given package.

type License 

type License struct {
	Contents string   `json:"contents,omitempty"`
	FilePath string   `json:"filePath,omitempty"`
	Types    []string `json:"types,omitempty"`
}

License describes a license file detected in a module or package.

type MajorVersion added in v0.2.0 

type MajorVersion struct {
	ModulePath string `json:"modulePath"` // e.g. "github.com/samber/do/v2"
	Major      string `json:"major"`      // e.g. "v2"
	Version    string `json:"version"`    // latest version in this major, e.g. "v2.0.0"
	IsLatest   bool   `json:"isLatest"`   // true for the highest major
}

MajorVersion is one major version of a module, discovered via the module proxy (see Client.MajorVersions). Majors beyond v1 live as separate modules (path, path/v2, path/v3...), so each MajorVersion carries its own module path.

type Module 

type Module struct {
	Path              string    `json:"path"`
	Version           string    `json:"version,omitempty"`
	RepoURL           string    `json:"repoUrl,omitempty"`
	GoModContents     string    `json:"goModContents,omitempty"`
	CommitTime        time.Time `json:"commitTime,omitzero"`
	HasGoMod          bool      `json:"hasGoMod"`
	IsLatest          bool      `json:"isLatest"`
	IsRedistributable bool      `json:"isRedistributable"`
	IsStandardLibrary bool      `json:"isStandardLibrary"`
	Licenses          []License `json:"licenses,omitempty"`
	Readme            Readme    `json:"readme,omitzero"`
}

Module is metadata about a single module.

type ModuleVersion 

type ModuleVersion struct {
	ModulePath        string    `json:"modulePath"`
	Version           string    `json:"version"`
	LatestVersion     string    `json:"latestVersion"`
	CommitTime        time.Time `json:"commitTime"`
	HasGoMod          bool      `json:"hasGoMod"`
	IsRedistributable bool      `json:"isRedistributable"`
	Deprecated        bool      `json:"deprecated"`
	DeprecationReason string    `json:"deprecationReason"`
	Retracted         bool      `json:"retracted"`
	RetractionReason  string    `json:"retractionReason"`
}

ModuleVersion is one entry from a /versions response.

type Option 

type Option func(*params)

Option configures optional query parameters for a single API call. Each method ignores options that do not apply to it.

func WithDoc 

func WithDoc(s string) Option

WithDoc sets the documentation format (text, html, md or markdown).

func WithExamples 

func WithExamples() Option

WithExamples includes examples with returned documentation.

func WithExcludePseudo added in v0.2.0 

func WithExcludePseudo() Option

WithExcludePseudo drops majors whose latest version is a pseudo-version (untagged commits). It reflects the ExcludePseudo flag of the proposed pkg.go.dev MajorVersions endpoint (golang/go#76718) and applies to MajorVersions only.

func WithFilter 

func WithFilter(f string) Option

WithFilter applies a regular-expression filter to listing results.

func WithGOARCH 

func WithGOARCH(s string) Option

WithGOARCH sets the GOARCH documentation build context.

func WithGOOS 

func WithGOOS(s string) Option

WithGOOS sets the GOOS documentation build context.

func WithImports 

func WithImports() Option

WithImports includes the list of packages the target imports.

func WithLicenses 

func WithLicenses() Option

WithLicenses includes licenses in the result.

func WithLimit 

func WithLimit(n int) Option

WithLimit caps the number of items returned.

func WithModule 

func WithModule(m string) Option

WithModule sets the module path for package-scoped calls.

func WithQuery 

func WithQuery(q string) Option

WithQuery sets the package search query (Search only).

func WithReadme 

func WithReadme() Option

WithReadme includes the README in the result (Module only).

func WithSymbol 

func WithSymbol(s string) Option

WithSymbol sets the symbol search query (Search only).

func WithToken 

func WithToken(t string) Option

WithToken resumes a listing from a pagination token.

func WithVersion 

func WithVersion(v string) Option

WithVersion selects a module version (semver, "latest", "master" or "main").

type Package 

type Package struct {
	Path              string    `json:"path"`
	ModulePath        string    `json:"modulePath,omitempty"`
	Name              string    `json:"name,omitempty"`
	Synopsis          string    `json:"synopsis,omitempty"`
	Version           string    `json:"version,omitempty"`
	Goos              string    `json:"goos,omitempty"`
	Goarch            string    `json:"goarch,omitempty"`
	Docs              string    `json:"docs,omitempty"`
	Imports           []string  `json:"imports,omitempty"`
	IsLatest          bool      `json:"isLatest"`
	IsRedistributable bool      `json:"isRedistributable"`
	IsStandardLibrary bool      `json:"isStandardLibrary"`
	Licenses          []License `json:"licenses,omitempty"`
}

Package is documentation and metadata about a single package.

type PackageInfo 

type PackageInfo struct {
	Path              string `json:"path"`
	Name              string `json:"name"`
	Synopsis          string `json:"synopsis"`
	IsRedistributable bool   `json:"isRedistributable"`
}

PackageInfo is one entry from a /packages response.

type PackagesResult 

type PackagesResult struct {
	ModulePath        string            `json:"modulePath,omitempty"`
	Version           string            `json:"version,omitempty"`
	IsStandardLibrary bool              `json:"isStandardLibrary"`
	Packages          Page[PackageInfo] `json:"packages"`
}

PackagesResult lists the packages contained in a module.

type Page 

type Page[T any] struct {
	Items     []T    `json:"items"`
	NextToken string `json:"nextToken,omitempty"`
	Total     int    `json:"total"`
}

Page is a paginated slice of T returned by listing endpoints.

type Readme 

type Readme struct {
	Contents string `json:"contents,omitempty"`
	Filepath string `json:"filepath,omitempty"`
}

Readme is a module README.

type SearchResult 

type SearchResult struct {
	ModulePath  string `json:"modulePath"`
	PackagePath string `json:"packagePath"`
	Synopsis    string `json:"synopsis"`
	Version     string `json:"version"`
}

SearchResult is one entry from a /search response.

type Symbol 

type Symbol struct {
	Path      string    `json:"path"`
	Name      string    `json:"name"`
	Kind      string    `json:"kind"` // Function, Method, Type, Variable or Constant.
	Signature string    `json:"signature"`
	Synopsis  string    `json:"synopsis,omitempty"`
	Doc       string    `json:"doc,omitempty"`
	Examples  []Example `json:"examples,omitempty"` // Populated only when WithExamples is set.
	Version   string    `json:"version,omitempty"`
	Goos      string    `json:"goos,omitempty"`
	Goarch    string    `json:"goarch,omitempty"`
}

Symbol is the full documentation of a single package symbol, derived client-side from the package documentation. See Client.Symbol.

type SymbolInfo added in v0.2.0 

type SymbolInfo struct {
	Name     string `json:"name"`
	Kind     string `json:"kind"`
	Synopsis string `json:"synopsis"`
	Parent   string `json:"parent"`
}

SymbolInfo is one entry from a /symbols response: lightweight metadata about a package symbol. Use Client.Symbol to fetch the full documentation of one symbol.

type Vulnerability 

type Vulnerability struct {
	ID           string `json:"id"`
	Summary      string `json:"summary"`
	Details      string `json:"details"`
	FixedVersion string `json:"fixedVersion"`
}

Vulnerability is one entry from a /vulns response.

Source Files

View all Source files

Directories

Path Synopsis
internal
api
Package api is the ogen-generated pkg.go.dev API client.
 Package api is the ogen-generated pkg.go.dev API client.
godoc
Package godoc derives the documentation of a single symbol from the package documentation returned by pkg.go.dev in Markdown form (doc=markdown).
 Package godoc derives the documentation of a single symbol from the package documentation returned by pkg.go.dev in Markdown form (doc=markdown).
majors
Package majors discovers the major versions of a Go module from the module proxy.
 Package majors discovers the major versions of a Go module from the module proxy.
proxy
Package proxy is a minimal Go module proxy client (https://go.dev/ref/mod#goproxy-protocol).
 Package proxy is a minimal Go module proxy client (https://go.dev/ref/mod#goproxy-protocol).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.