[FEATURE] decrement/truncate

[isaacs]

Not pressing or urgent, but mostly for API symmetry, it'd be nice to have truncate/decrement functions.

1. semver.truncate('1.2.3-foo', 'patch') == '1.2.3'
2. semver.truncate('1.2.3', 'minor') == '1.2.0'
3. semver.truncate('1.2.3', 'major') == '1.0.0'
4. semver.dec('1.2.3-foo', 'patch') == '1.2.2'
5. semver.dec('1.2.3', 'minor') == '1.1.0'
6. semver.dec('1.2.3', 'major') == '0.0.0'

Re #46, but the use case presented there turned out to not require this functionality. It's still probably useful, though.

cc @ronkorving

[aschearer]

Would be handy to have semver.dec. I would like to generate a change log from git based on the current version and the previous version. Not sure of a way to get the previous version short of decrementing the package's version.

[sindresorhus]

I didn't have time to do a proper patch, but I did a quick module for truncation if anyone else needs it: https://github.com/sindresorhus/semver-truncate

[anko]

What should semver.dec('2.0.0', 'patch') be? 1.99.99? 1.0.0? Something in between? The semver spec doesn't define how to decrement a semver or what it even means. I suspect this is why.

[ypicard]

Any news on this?

[kenshanta]

An issue open for 12 years is insane!

[pjohnmeyer]

What should semver.dec('2.0.0', 'patch') be? 1.99.99? 1.0.0? Something in between? The semver spec doesn't define how to decrement a semver or what it even means. I suspect this is why.

Three ideas. If any of these are still desirable, I might consider working up a patch.

Cannot decrement a "0"

This argument says that "decrementing" a 0 isn't valid and isn't what we're trying to accomplish; we're solely operating on the version string and so we cannot do this. Using @anko's example, semver.dec('2.0.0', 'patch') would throw.

Can decrement a "0" if a list of candidates are provided

If we are saying decrementing a 0 is valid, in that case then we would have to provide a list of "candidates" to roll back to, and throw only if there is no suitable candidate:

semver.dec('2.0.0', 'patch') // throws, no suitable candidate
semver.dec('2.0.0', 'patch', ['2.0.1']) // throws, no suitable candidate
semver.dec('2.0.0', 'patch', ['1.0.1', '1.0.2', '2.0.1']) == '1.0.2'

Close this ticket

An enhancement issue this old maybe should just be closed. If it hasn't been implemented by now then maybe it isn't needed -- or at least it isn't needed in npm/node-semver.

[mbtools]

Ideally, semver.dec( semver.inc( version, type ), type, ... ) == version.

The most common use case of dec will certainly be to "go back to previous version". That's only possible if a list of versions - usually from the registry packument - is provided.

So I like your second option most 👍

I can't see dec working with pre-releases or builds. Therefore, dec should always truncate first.

Just go for it, @pjohnmeyer 🙏

[pjohnmeyer]

I can't see dec working with pre-releases or builds. Therefore, dec should always truncate first.

@mbtools in the course of working on #855, I think dec can work with pre-releases in some situations, but not all. I support pre* in that PR, but considered not.

Depending on the response to that PR, we may still choose to initially restrict both functions to only major, minor, and patch, then add more later if the needs / requests come in.

[pjohnmeyer]

Ideally, semver.dec( semver.inc( version, type ), type, ... ) == version.

@mbtools -- As I started on this tonight, I noticed that this statement does not hold. As an example:

semver.dec( semver.inc ('1.2.3', 'minor'), 'minor' ) === '1.2.0'

Just a note I wanted to put out there, to make it clear that dec is NOT the inverse function of inc if we are to follow the examples presented in the original ticket.

If we do want the output of dec in this case to be 1.2.3, then:

1. 1.2.3 would have to be in the list of candidates, and
2. The behavior of dec(version, 'minor') would be to find the highest patch of the next lower minor, not just blindly zero the patch level as @isaacs originally specified.

I feel like this interpretation might be more desirable, but if anybody else has thoughts feel free to chime in.

[mbtools]

You're right. My formular only works for minor if patch is zero (or for major if minor and patch are zero) ie if there's a truncate before.

There are two cases: dec(version) and "dec" with a list of candidates. The latter is more a "predecessor" function (with a complimentary "successor"). Might be better to distinguish them.

For the plain dec(v), I would return null if the part of the version matching the release type is already zero. Otherwise decrease the part by one.