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.01.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
Please cite the source for reprints, feel free to verify the sources cited in the article, and point out any errors or lack of clarity of expression. You can comment in the comments section below or email to GreenMeeple@yahoo.com