version

go-version

A zero-dependency Go library that ports the PHP Composer version and constraint parsing semantics to Go — including caret (^), tilde (~), wildcards (*), hyphen ranges, stability flags, and prerelease comparison.

Forked from hashicorp/go-version and fundamentally extended with full Composer compatibility.

Installation

go get github.com/shyim/go-version

Requires Go 1.23+.

Quick Start

import "github.com/shyim/go-version"

// Check if a version satisfies a constraint
ok, err := version.Satisfies("1.2.3", "^1.0")   // true
ok, err  = version.Satisfies("7.0.0", "^1.0")   // false

// Parse a version
v, err := version.NewVersion("1.2.3-beta1")
fmt.Println(v.Major())            // 1
fmt.Println(v.Minor())            // 2
fmt.Println(v.Patch())            // 3
fmt.Println(v.Prerelease())       // "beta1"
fmt.Println(v.NormalizedString()) // "1.2.3.0-beta1"

// Compare versions
a := version.Must(version.NewVersion("1.2.3-rc2"))
b := version.Must(version.NewVersion("1.2.3-rc1"))
a.GreaterThan(b)  // true — numeric suffixes compared correctly

// Parse a constraint with multiple conditions
c, err := version.NewConstraint(">=1.0,<2.0")
c.Check(v)  // true

// Check constraint intersection (for dependency solvers)
ok, err = version.ConstraintIntersects("^1.0", ">=1.0,<2.0")  // true
ok, err = version.ConstraintIntersects("^1.0", "^2.0")         // false

// Check subset relationship
ok, err = version.ConstraintSubsetOf("^1.2", "^1.0 || ^2.0")   // true

API Reference

Version Parsing & Comparison

Constraint Parsing & Checking

Convenience API

Constraint Intersection (for dependency solvers)

Sorting

Stability Constants

const (
    StabilityDev    = "dev"
    StabilityAlpha  = "alpha"
    StabilityBeta   = "beta"
    StabilityRC     = "RC"
    StabilityStable = "stable"
)

Feature Overview

Version Formats

The library parses a wide range of version strings following Composer's conventions:

Constraint Operators

Composer-Specific Semantics

Prerelease rank ordering — versions sort in Composer's stability order: dev < alpha < beta < RC < stable

With numeric suffixes compared numerically: 1.0.0-rc1 < 1.0.0-rc2 < 1.0.0-rc10

Caret (^) — allows changes that do not modify the leftmost non-zero digit:

Tilde (~) — allows changes at the last specified segment:

Hyphen ranges — Composer-style range with intelligent upper bound logic:

Stability flags (@stable, @beta, @dev, @alpha, @RC):

c := version.MustConstraints(version.NewConstraint(">=1.0@stable"))
c.Check(version.Must(version.NewVersion("1.0.0")))       // true
c.Check(version.Must(version.NewVersion("1.0.0-beta")))  // false

Stability-appended operators — >=1.0@beta expands to >=1.0.0-beta, making the minimum-stable constraint automatically aware of its stability level.

Branch versions (dev-*) — treated as unordered for ordering operators; only equality (=/==) and inequality (!=) give meaningful results. Wildcards (*) and anyBranch domains include all branch versions.

Constraint composition — supports both || and | as OR separators, with , and whitespace as AND:

• >=1.0,<2.0 — AND: version must satisfy both
• ^1.0 || ^2.0 — OR: version must satisfy at least one
• >=1.0 <2.0 — AND (whitespace delimiter)

Differences from hashicorp/go-version

Performance

The library includes an optimized fast path for the common case of plain numeric versions (1.2.3, v1.2), avoiding regexp overhead. Benchmarks are available:

go test -bench=. -benchmem ./...

Testing

The library has comprehensive test coverage:

Fuzz tests are included for all public entry points:

go test -run=Fuzz -fuzz=FuzzNewVersion -fuzztime=30s ./...
go test -run=Fuzz -fuzz=FuzzNewConstraint -fuzztime=30s ./...
go test -run=Fuzz -fuzz=FuzzSatisfies -fuzztime=30s ./...
go test -run=Fuzz -fuzz=FuzzConstraintIntersects -fuzztime=30s ./...

Run all tests:

go test ./...

Architecture

The library follows a clean two-phase pipeline:

normalizer.go → version.go → constraint.go → intersect.go
                         ↕
              version_collection.go

• normalizer.go — Canonicalizes raw version strings (aliases, stability suffixes, branches, date versions, classical semver modifiers)
• version.go — Version type, regex parsing, ranked prerelease comparison
• constraint.go — Disjunctive Normal Form constraint model, all operators, hyphen ranges, stability constraints
• domain.go / interval.go / snapshot.go / intersect.go — Domain algebra for constraint intersection and subset queries
• version_collection.go — sort.Interface for version slices
• api.go — Public convenience API (Satisfies, NormalizeComposerVersion, Stability)

Zero external dependencies.

License

MIT — see LICENSE for details. Forked from hashicorp/go-version (also MIT licensed).