feat(semver): Add support for build metadata

[justinmchase]

Overview

Currently the build metadata is parsed but is not printed out in any form. A semver which is parsed will not be identical to
the printed output:

console.log(semver.parse("1.2.3+4").format()) // 1.2.3

Additionally, once set, there is no way to alter the metadata on the SemVer instance without formatting into a new string and re-parsing:

const build = "5";
const v0 = semver.parse("1.2.3+4").increment("pre");
const v1 = semver.parse(`${v0}+${build}`);

Therefore this PR attempts to address these two issues with the following APIs:

1. Add a new, optional, options object parameter onto the .format() function which contains a single field style. The style will dictate the format of the output of the function, it will not affect the format internal mutated fields this.version or this.raw, to preserve backwards compatibility and not require an extensive refactor.
2. The .increment() function will now have a new, optional, metadata: string parameter which will set the this.build field with the new metadata or reset it to empty. Incrementing with no build data will not retain the previous build metadata.

console.log(semver.parse("1.2.3+4").format({ style: "full" )) // 1.2.3+4

const build = "5";
const v0 = semver.parse("1.2.3+4").increment("pre", undefined, build);
console.log(v0.format({ style: "full" })) // 1.2.3-0+5

Related To

• fixes semver.format function is dropping build data #3110
• replaces feat(semver): Allow for passing includeBuild into format method #3117
• related Support build metadata npm/node-semver#174

Notes

• According to the semver spec the build metadata must not be used during the comparison calculations. For this reason the internal this.version and this.raw fields are preserved as they were since those fields can be part of the comparison calculations. The only modifications are to the output of the format function.
• Currently the parsing functions do actually parse the build metadata correctly, so there was no need to modify this. It handles it safely it simply does not output it or support modification correctly.

[CLAassistant]

All committers have signed the CLA.

[kt3k]

LGTM. Looks nice enhancement. Thanks for your contribution!

[kt3k]

nice exhausive tests!