Semver

npm install @seedcli/semver

Inside Seed commands and middleware, this module is already available as seed.semver; no extra install is required for that usage.

The semver module wraps the semver npm package with a clean API for version validation, comparison, and manipulation.

Validation

seed.semver.valid('1.2.3')     // '1.2.3'
seed.semver.valid('not.a.ver') // null

Returns the cleaned version string if valid, or null if invalid.

Cleaning

Strip leading v or extra whitespace:

seed.semver.clean('  v1.2.3  ')  // '1.2.3'
seed.semver.clean('invalid')     // null

Coercion

Attempt to coerce a loose string into a valid semver:

seed.semver.coerce('v1')      // '1.0.0'
seed.semver.coerce('3.2')     // '3.2.0'
seed.semver.coerce('nope')    // null

Comparison

These helpers throw Error if any version argument is not valid semver.

seed.semver.gt('2.0.0', '1.0.0')   // true
seed.semver.gte('1.0.0', '1.0.0')  // true
seed.semver.lt('1.0.0', '2.0.0')   // true
seed.semver.lte('1.0.0', '1.0.0')  // true
seed.semver.eq('1.0.0', '1.0.0')   // true

seed.semver.compare('1.0.0', '2.0.0')  // -1
seed.semver.compare('2.0.0', '1.0.0')  // 1
seed.semver.compare('1.0.0', '1.0.0')  // 0

Range Satisfaction

seed.semver.satisfies('1.2.3', '>=1.0.0')        // true
seed.semver.satisfies('1.2.3', '>=1.0.0 <2.0.0') // true
seed.semver.satisfies('2.0.0', '^1.0.0')          // false

Version Parts

seed.semver.major('1.2.3')       // 1
seed.semver.minor('1.2.3')       // 2
seed.semver.patch('1.2.3')       // 3
seed.semver.prerelease('1.2.3-beta.1')  // ['beta', 1]
seed.semver.prerelease('1.2.3')         // null

major, minor, and patch also throw Error for invalid versions.

Bumping Versions

seed.semver.bump('1.2.3', 'major')      // '2.0.0'
seed.semver.bump('1.2.3', 'minor')      // '1.3.0'
seed.semver.bump('1.2.3', 'patch')      // '1.2.4'
seed.semver.bump('1.2.3', 'premajor')   // '2.0.0-0'
seed.semver.bump('1.2.3', 'preminor')   // '1.3.0-0'
seed.semver.bump('1.2.3', 'prepatch')   // '1.2.4-0'
seed.semver.bump('1.2.3-0', 'prerelease') // '1.2.3-1'

Sorting

const sorted = seed.semver.sort(['3.0.0', '1.0.0', '2.0.0'])
// ['1.0.0', '2.0.0', '3.0.0']

Finding Best Match

const best = seed.semver.maxSatisfying(
  ['1.0.0', '1.1.0', '1.2.0', '2.0.0'],
  '^1.0.0'
)
// '1.2.0'

Diff

Determine the release type between two versions:

seed.semver.diff('1.0.0', '2.0.0')     // 'major'
seed.semver.diff('1.0.0', '1.1.0')     // 'minor'
seed.semver.diff('1.0.0', '1.0.1')     // 'patch'
seed.semver.diff('1.0.0', '1.0.0')     // null

API Reference

Export	Signature	Description
`valid`	`(version: string) => string \| null`	Return cleaned version or null
`clean`	`(version: string) => string \| null`	Clean version string
`coerce`	`(version: string) => string \| null`	Coerce to valid semver
`satisfies`	`(version: string, range: string) => boolean`	Check range satisfaction
`gt`	`(a: string, b: string) => boolean`	Greater than; throws on invalid semver
`gte`	`(a: string, b: string) => boolean`	Greater than or equal; throws on invalid semver
`lt`	`(a: string, b: string) => boolean`	Less than; throws on invalid semver
`lte`	`(a: string, b: string) => boolean`	Less than or equal; throws on invalid semver
`eq`	`(a: string, b: string) => boolean`	Equal; throws on invalid semver
`compare`	`(a: string, b: string) => -1 \| 0 \| 1`	Compare two versions; throws on invalid semver
`diff`	`(a: string, b: string) => ReleaseType \| null`	Get release type between versions; throws on invalid semver
`bump`	`(version: string, release: ReleaseType, identifier?: string) => string \| null`	Bump version
`major`	`(version: string) => number`	Get major version; throws on invalid semver
`minor`	`(version: string) => number`	Get minor version; throws on invalid semver
`patch`	`(version: string) => number`	Get patch version; throws on invalid semver
`prerelease`	`(version: string) => ReadonlyArray<string \| number> \| null`	Get prerelease identifiers
`sort`	`(versions: string[]) => string[]`	Sort versions ascending
`maxSatisfying`	`(versions: string[], range: string) => string \| null`	Find best match
`ReleaseType`	`"major" \| "minor" \| "patch" \| "premajor" \| "preminor" \| "prepatch" \| "prerelease"`	Release kinds accepted by `bump` and returned by `diff`

Semver

On this page