Explaination of version range operators in package.json for package dependencies

To see the syntax and Railroad diagram version, goto here

Basic Structure

Package dependecies are a tuple of [major, minor, patch] with numeric values.

{
    "name": "project name",
    "version": "0.0.1",
    "description": "description of the project",
    "keywords": [
        "keyword 1",
        "keyword 2"
    ],
    "author": "John Doe",
    "dependencies": {
      "package-1": "~0.6.2",
      "package-2": ">=2.6.2"
    }
}

Version Range operator

Basic Range

For x in exmaple, see Advanced Range below.

Operator	Explaination	Example
=	package version must be exactly matched	1.0.0 := =1.0.0 (They are equivalent)
<	package version must be less than indicated	<2.0.0 :=version from 0.0.1 to 1.x.x
<=	package version must be less than or euqal to indicated	<=2.0.0 :=version from 0.0.1 to 2.0.0
>	package version must be greater than indicated	>2.0.0:= version from 2.0.1 to x (x >= 2)
>=	package version must be greater than or euqal to indicated	>=2.0.0 :=version from 2.0.0 to x (x >= 2)
||	joined one or more operator	>2.0.1 || <1.7.3 :=version greater than 2.0.1 or less than 1.7.3
space	Intersected one or more operator	>=2.0.1 <=1.7.3 :=version from 2.0.1 to 1.7.3 (inclusive)

Advanced Range

Advanced ranges may be combined in the same way as primitive comparators using space or ||.

Operator	Explaination	Example
X, x, *	A Wildcard may be used for any values in the [major, minor, patch] tuple (missing value are consider using Wildcard x)	* := (empty string) := >=0.0.0 1.x.x := 1.x := 1 := >=1.0.0 <2.0.0
-	Specifies an inclusive set of package version	1.2 - 2.3.4 := >=1.2.0 <=2.3.4 (missing pieces of first version are replaced with zeroes) 1.2.3 - 2.3 := >=1.2.3 <2.4.x (missing pieces of second version replace with X-range)
~	Allows patch or minor level version changes, depends on specification	~1.2.3 := any version starts with 1.2 and greater than 1.2.3 ~1.2 := any version starts with 1.2 (same as 1.2.x)
^	Allows version changes in the [major, minor, patch] tuple without modify the left-most non-zero element.	^1.2.3 := >=1.2.3 <2.0.0 (minor update) ^0.2.3 := >=0.2.3 <0.3.0 (patch update) ^0.0.3 := >=0.0.3 <0.0.4 (no updates)

Further Explaination on Caret Ranges ^

Special interaction with Wildcard operator x

When parsing caret ranges, minor and patch values with wildcard x desugars to the number 0 (missing values are consider as x):

Example:

• ^1.2.x := >=1.2.0 <2.0.0-0 (equivalent to ^1.2.0)
• ^1.x := >=1.0.0 <2.0.0-0 (equivalent to ^1.0.0)

However, when both major and minor versions are 0, Caret range allow flexibility within wildcard x:

Example:

• ^0.0.x := >=0.0.0 <0.1.0-0 (NOT equivalent to ^0.0.0, but similar to ^0.1.0)

Usage and Common Practices

Caret ranges usually ideally used when an author may make breaking changes. For example, between 0.2.4 and 0.3.0 releases, which is a common practice.

However, it presumes that there will not be breaking changes between 0.2.4 and 0.2.5. It allows for changes that are presumed to be additive (but non-breaking), according to commonly observed practices.

---

Further Reading: version range in npm-semver, setup-node in GitHub Actions