sls-version

Typescript utilities for manipulating SLS versions

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
sls-version
2.1.04 years ago4 years agoMinified + gzip package size for sls-version in KB

Readme

slsversion
Typescript utilities for manipulating SLS versions.

Overview

Comparison:
  • eq(lhs, rhs)lhs == rhs
    gt(lhs, rhs)lhs > rhs
  • gte(lhs, rhs)lhs >= rhs
  • lt(lhs, rhs)lhs < rhs
  • lte(lhs, rhs)lhs <= rhs

Parsing:
  • isValid() — Determine if a version string is valid
  • major() — Extract the major version number from a version string
  • minor() — Extract the minor version number from a version string
  • patch() — Extract the patch version number from a version string
  • rc() — Extract the release candidate number from a version string
  • snapshot()— Extract the snapshot number from a version string
  • isReleaseCandidate() — Returns true of the version is a release candidate
  • isSnapshot() — Returns true if the version is a snapshot version
SLS Product Version Specification
This specification describes orderable and non-orderable product version strings for use in an SLS manifest.

Orderable version strings

Orderable version strings fall into one of 4 version types as defined by a category (release or release candidate) and whether it is a snapshot version or not (snapshot versions contain a commit hash at the end), the cross section of which produces the following: ``` Version Type Example Format ------------ ------- ------ Release 1.0.0 ^0-9+\.0-9+\.0-9+$ Release Snapshot 1.0.0-1-gaaaaaaa ^0-9+\.0-9+\.0-9+-0-9+-ga-f0-9+$
Release candidate (rc) 1.0.0-rc1 ^0-9+\.0-9+\.0-9+-rc0-9+$ Release candidate (rc) snapshot 1.0.0-rc1-1-gaaaaaaa ^0-9+\.0-9+\.0-9+-rc0-9+-0-9+-ga-f0-9+$
Note that in each example above, we define the 'base' version as the  major/minor/patch-version component (in this
case, they are all the same, `1.0.0`).


#### Ordering

For any pair of orderable product version strings, it is straightforward to define an order governing which of the
product versions is newer and which one is older. The order allows deployment tooling to make informed
decisions about forward-vs-backwards product migrations. Further, it simplifies reasoning about product compatibility
via version ranges; for instance, a product may declare that it is compatible with a second product with a version in
`[1.2.3, 2.0.0)`.

For any two orderable versions, v1 and v2, we can define whether v1 is a *bigger* (equivalently, *later*, *newer*, etc)
than v2. For the four variants, there can be up to three numeric components identifying a version. From left to right,
they are: the usual notation of the base version (e.g., for `1.2.3`, 1=major, 2=minor, 3=patch), an optional second
numeric component to identify a release candidate (e.g. `-rc3`) or a snapshot version (e.g. `-5-gnm4s9ba`), and finally
an optional third numeric component to identify a release candidate snapshot version (e.g. `-rc3-5-gnm4s9ba`).

Intuitively, given the same base version, snapshot versions are bigger than non-snapshot versions, normal release
versions are bigger than release candidate versions, and a normal release snapshot version is bigger than a release
candidate of any kind. The following top-down procedure determines whether v1 is bigger than v2, written `v1 > v2`;
comparisons like `major(v1) > major(v2)` are by integer ordering (not lexicographic ordering):

- If `major(v1) > major(v2)`, then `v1 > v2`
- If `minor(v1) > minor(v2)`, then `v1 > v2`
- If `patch(v1) > patch(v2)`, then `v1 > v2`
- From here on, let us assume that the base versions (major/minor/patch) are the same for v1 and v2
- If v1 is a normal snapshot version and v2 is a normal release, then `v1 > v2`
- If v1 is a normal release version and v2 is a rc version, then `v1 > v2`
- If v1 and v2 are both normal snapshot versions and `snapshot(v1) > snapshot(v2)`, then `v1 > v2`
- If v1 and v2 are both rc versions and `rc(v1) > rc(v2)`, then `v1 > v2`
- From here on, let us assume that v1 and v2 are both rc versions of the same `rc()` number
- If v1 is a snapshot rc version and v2 is a normal rc version, then `v1 > v2`
- If v1 and v2 are both snapshot rc versions and `rcSnapshot(v1) > rcSnapshot(v2)`, then `v1 > v2`

Further, v1 is as big as v2, written `v1 == v2`, iff neither `v1 > v2` nor `v2 > v1`.
We write `v1 >= v2` if `v1 > v2` or `v1 == v2`.

Examples, with each greater than all the previous:
- RC: `1.0.0-rc1`
- Bigger RC: `1.0.0-rc2`
- RC Snapshot trumps RC: `1.0.0-rc2-4-gaaaaaaa`
- Bigger RC Snapshot: `1.0.0-rc2-5-gccccccc`
- Base trumps RC: `2.0.0`
- Snapshot trumps all: `2.0.0-3-gaaaaaaa`
- Bigger Snapshot: `2.0.0-4-gbbbbbbb`
- Bigger Base: `2.1.0-rc1`
- Release trumps RC: `2.1.0`

Examples of equality:
- `1.2.0 == 1.2.0`
- `2.0.0-rc1 == 2.0.0-rc1`
- `2.0.0-rc1-3-gaaaaaaa == 2.0.0-rc1-3-gbbbbbbb`
- `2.0.0-5-gbbbbbbb == 2.0.0-5-gaaaaaaa1`

Note that any two release and rc versions are equally big iff they are syntactically equal. As the second example
demonstrates, this does not hold for snapshot versions.

#### Orderable string regular expression

Version strings follow the *orderable* format if they match the follow regular expression:
^((x\.x\.x)|(0-9+\.x\.x)|(0-9+\.0-9+\.x)|(0-9+\.0-9+\.0-9+))$
For example, `1.x.x`, `2.0.x`, `x.x.x`, and `1.2.3` are valid version matchers, whereas `x.y.z`, `x.0.0`, `0.x.3`,
`x.x.2`,  `1.x`, and `^x\.[0-9]+\.[0-9]+$` are not. A matcher is said to *match* a release version if there are (independent)
substitutions for `x` that turn the matcher into the version. For example, `1.x.x` matches `1.0.0` and `1.2.3`, but it does
not match `2.0.0` or `0.1.1`.

### Non-orderable version strings

Version strings follow the *non-orderable* format if they match the follow regular expression:
^0-9+\.0-9+\.0-9+(-a-z0-9-+)?(\.dirty)?$ `` For example, 1.0.0.dirty, 0.0.1-custom-description-42, and 2.0.0-1-gaaaaaa.dirty` are valid but non-orderable version strings, whereas 5.0, 1.1.2.3-foo, 1.1.2.3 and 1.0.0-FOO are not valid version strings under this spec.
There are no ordering guarantees for a pair of non-orderable versions, or between an orderable and a non-orderable version string.