262 lines
6.7 KiB
Markdown
262 lines
6.7 KiB
Markdown
[](https://github.com/asamuzaK/semverParser/actions?query=workflow%3Abuild)
|
||
[](https://github.com/asamuzaK/semverParser/actions?query=workflow%3ACodeQL)
|
||
[](https://www.npmjs.com/package/semver-parser)
|
||
|
||
# SemVer Parser
|
||
|
||
Parse, verify, compare [SemVer](https://semver.org/ "Semantic Versioning 2.0.0 | Semantic Versioning").
|
||
|
||
## Install
|
||
|
||
```console
|
||
npm install semver-parser
|
||
```
|
||
|
||
## API
|
||
|
||
APIs can be used either synchronously or asynchronously.
|
||
Async function returns Promise which resolves with the result.
|
||
|
||
sync:
|
||
```javascript
|
||
import { compareSemVer, isValidSemVer, parseSemVer } from 'semver-parser';
|
||
```
|
||
|
||
async:
|
||
```javascript
|
||
import { promises } from 'semver-parser';
|
||
const { compareSemVer, isValidSemVer, parseSemVer } = promises;
|
||
```
|
||
|
||
NOTE: [Is "v1.2.3" a semantic version?](https://github.com/mojombo/semver/blob/master/semver.md#is-v123-a-semantic-version "semver/semver.md at master · mojombo/semver")
|
||
|
||
> Is "v1.2.3" a semantic version?
|
||
>
|
||
> No, "v1.2.3" is not a semantic version. However, prefixing a semantic version with a "v" is a common way (in English) to indicate it is a version number.
|
||
|
||
For ease of use, this parser supports "v" prefixed string.
|
||
If you do not want to accept "v" prefix, set `strict` param to `true`.
|
||
|
||
### parseSemVer(version, strict)
|
||
|
||
Parses version string.
|
||
|
||
* @param {string} version - version string
|
||
* @param {boolean} [strict] - reject 'v' prefixed
|
||
* @returns {Object} - parsed result, contains properties below
|
||
- version {string} - given version string
|
||
- matches {boolean} - matches SemVer format
|
||
- major {number|undefined} - major version
|
||
- minor {number|undefined} - minor version
|
||
- patch {number|undefined} - patch version
|
||
- pre {Array<string|number>|undefined} - pre release version in array
|
||
- build {Array<string|number>|undefined} - build ID in array
|
||
|
||
### isValidSemVer(version, strict)
|
||
|
||
Determine whether the given argument is a valid SemVer string.
|
||
|
||
* @param {string} version - version string
|
||
* @param {boolean} [strict] - reject 'v' prefixed
|
||
* @returns {boolean} - result
|
||
|
||
### compareSemVer(version, base, strict)
|
||
|
||
Compare versions in SemVer format.
|
||
|
||
* @param {string} version - version string
|
||
* @param {string} base - base version string to compare from
|
||
* @param {boolean} [strict] - reject 'v' prefixed
|
||
* @returns {number}
|
||
- -1 or negative number, if version is less than base version
|
||
- 0, if version is equal to base version
|
||
- 1 or positive number, if version is greater than base version
|
||
|
||
## [Backus–Naur Form Grammar for Valid SemVer Versions](https://github.com/mojombo/semver/blob/master/semver.md#backusnaur-form-grammar-for-valid-semver-versions "semver/semver.md at master · mojombo/semver") to JavaScript RegExp
|
||
|
||
### valid semver
|
||
```bnf
|
||
<valid semver> ::= <version core>
|
||
| <version core> "-" <pre-release>
|
||
| <version core> "+" <build>
|
||
| <version core> "-" <pre-release> "+" <build>
|
||
```
|
||
```javascript
|
||
(?:0|[1-9]\d*)(?:\.(?:0|[1-9]\d*)){2}(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*))*)?(?:\+(?:\d*[A-Za-z-][\dA-Za-z-]*|\d+)(?:\.(?:\d*[A-Za-z-][\dA-Za-z-]*|\d+))*)?
|
||
```
|
||
|
||
### version core
|
||
```bnf
|
||
<version core> ::= <major> "." <minor> "." <patch>
|
||
```
|
||
```javascript
|
||
(?:0|[1-9]\d*)(?:\.(?:0|[1-9]\d*)){2}
|
||
```
|
||
|
||
### major
|
||
```bnf
|
||
<major> ::= <numeric identifier>
|
||
```
|
||
```javascript
|
||
0|[1-9]\d*
|
||
```
|
||
|
||
### minor
|
||
```bnf
|
||
<minor> ::= <numeric identifier>
|
||
```
|
||
```javascript
|
||
0|[1-9]\d*
|
||
```
|
||
|
||
### patch
|
||
```bnf
|
||
<patch> ::= <numeric identifier>
|
||
```
|
||
```javascript
|
||
0|[1-9]\d*
|
||
```
|
||
|
||
### pre-release
|
||
```bnf
|
||
<pre-release> ::= <dot-separated pre-release identifiers>
|
||
```
|
||
```javascript
|
||
(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*))*
|
||
```
|
||
|
||
### dot-separated pre-release identifiers
|
||
```bnf
|
||
<dot-separated pre-release identifiers> ::= <pre-release identifier>
|
||
| <pre-release identifier> "." <dot-separated pre-release identifiers>
|
||
```
|
||
```javascript
|
||
(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*))*
|
||
```
|
||
|
||
### build
|
||
```bnf
|
||
<build> ::= <dot-separated build identifiers>
|
||
```
|
||
```javascript
|
||
(?:\d*[A-Za-z-][\dA-Za-z-]*|\d+)(?:\.(?:\d*[A-Za-z-][\dA-Za-z-]*|\d+))*
|
||
```
|
||
|
||
### dot-separated build identifiers
|
||
```bnf
|
||
<dot-separated build identifiers> ::= <build identifier>
|
||
| <build identifier> "." <dot-separated build identifiers>
|
||
```
|
||
```javascript
|
||
(?:\d*[A-Za-z-][\dA-Za-z-]*|\d+)(?:\.(?:\d*[A-Za-z-][\dA-Za-z-]*|\d+))*
|
||
```
|
||
|
||
### pre-release identifier
|
||
```bnf
|
||
<pre-release identifier> ::= <alphanumeric identifier>
|
||
| <numeric identifier>
|
||
```
|
||
```javascript
|
||
0|[1-9]\d*|\d*[A-Za-z-][\dA-Za-z-]*
|
||
```
|
||
|
||
### build identifier
|
||
```bnf
|
||
<build identifier> ::= <alphanumeric identifier>
|
||
| <digits>
|
||
```
|
||
```javascript
|
||
\d*[A-Za-z-][\dA-Za-z-]*|\d+
|
||
```
|
||
|
||
### alphanumeric identifier
|
||
```bnf
|
||
<alphanumeric identifier> ::= <non-digit>
|
||
| <non-digit> <identifier characters>
|
||
| <identifier characters> <non-digit>
|
||
| <identifier characters> <non-digit> <identifier characters>
|
||
```
|
||
```javascript
|
||
[\dA-Za-z-]*[A-Za-z-][\dA-Za-z-]*
|
||
```
|
||
optimized:
|
||
```javascript
|
||
\d*[A-Za-z-][\dA-Za-z-]*
|
||
```
|
||
|
||
### numeric identifier
|
||
```bnf
|
||
<numeric identifier> ::= "0"
|
||
| <positive digit>
|
||
| <positive digit> <digits>
|
||
```
|
||
```javascript
|
||
0|[1-9]\d*
|
||
```
|
||
|
||
### identifier characters
|
||
```bnf
|
||
<identifier characters> ::= <identifier character>
|
||
| <identifier character> <identifier characters>
|
||
```
|
||
```javascript
|
||
[\dA-Za-z-]+
|
||
```
|
||
|
||
### identifier character
|
||
```bnf
|
||
<identifier character> ::= <digit>
|
||
| <non-digit>
|
||
```
|
||
```javascript
|
||
[\dA-Za-z-]
|
||
```
|
||
|
||
### non-digit
|
||
```bnf
|
||
<non-digit> ::= <letter>
|
||
| "-"
|
||
```
|
||
```javascript
|
||
[A-Za-z-]
|
||
```
|
||
|
||
### digits
|
||
```bnf
|
||
<digits> ::= <digit>
|
||
| <digit> <digits>
|
||
```
|
||
```javascript
|
||
\d+
|
||
```
|
||
|
||
### digit
|
||
```bnf
|
||
<digit> ::= "0"
|
||
| <positive digit>
|
||
```
|
||
```javascript
|
||
\d
|
||
```
|
||
|
||
### positive digit
|
||
```bnf
|
||
<positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
|
||
```
|
||
```javascript
|
||
[1-9]
|
||
```
|
||
|
||
### letter
|
||
```bnf
|
||
<letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"
|
||
| "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"
|
||
| "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d"
|
||
| "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n"
|
||
| "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
|
||
| "y" | "z"
|
||
```
|
||
```javascript
|
||
[A-Za-z]
|
||
```
|