cleanup semver

[timreichen]

Background

There are several inconsistencies in the semver mod:

File names and exported functions

The semver mod is not well structured. The file names and functions are not consistent. range_format.ts and comparator_format.ts uses [*_verb].ts and *Format(), but parse_range.ts and parse_comparator.ts uses [verb_*].ts and parse*().
Another inconsistency is: parse_comparator.ts and parse_range.ts but is_semver_comparator.ts and is_semver_range.ts. The _semver in the name seems obsolete.

eq, neq, gt, gte, lt, lte

These functuons are wrapper functions for compare() compare the result to 0 with different comparators:
return compare(s0, s1) [===|!==|>|>=|<|<=] 0. These seem too trivial.

rcompare

This function calls compare() with switched arguments. This seems too trivial.

Proposal

File names and exported functions

Rename [*_verb].ts to [verb_*].ts and *Format() to format*() for all filenames and functions and deprecate old functions and remove _semver from file names and function:

• rangeFormat() => formatRange() deprecation(semver): rename rangeFormat() to formatRange() #4090
• comparatorFormat() => formatComparator() deprecated
• isSemVerComparator() => isComparator() deprecation(semver): rename isSemVerComparator() #3957
• isSemVerRange() => isRange() deprecation(semver): deprecate SemVerRange, introduce Range #4161
• testRange() => inRange() or rangeIncludes() deprecation(semver): rename testRange() to satisfies() #4364

eq, neq, gt, gte, lt, lte

• deprecate all these functions deprecation(semver): deprecate eq(), neq(), lt(), lte(), gt() and gte() #4048
• rename all these functions deprecation(semver): rename eq(), neq(), lt(), lte(), gt() and gte() #4083
• discuss if these functions should be put in compare.ts

rcompare

• deprecate this function deprecation(semver): deprecate rcompare() #3958

Others

• investigate Comparator necessity Discussion(semver): Necessity of Comparator #4047
• investigate possible obsolete OPERATORS ("", "==", "===", "!==") deprecation(semver): deprecate ==, ===, !==, and "" operators #4271
• investigate deprecate compareBuild() deprecation(semver): deprecate compareBuild() #4088
• deprecate outside() deprecation(semver): deprecate outside() #4185

@iuioiua @kt3k WDYT?

[iuioiua]

• range_format.ts => format_range.ts
• rangeFormat() => formatRange()
• comparator_format.ts => format_comparator.ts
• comparatorFormat() => formatComparator()

I mostly agree. But I think these functions should probably have a stringify prefix instead. The strings returned in other functions with "format" are usually configurable. WDYT?

• is_semver_comparator.ts => is_comparator.ts
• isSemVerComparator() => isComparator()
• is_semver_range.ts => is_range.ts
• isSemVerRange() => isRange()

I agree.

eq, neq, gt, gte, lt, lte

deprecate all these functions

I weakly agree. However, doing so would require the dev to learn these comparison concepts. Happy to hear other opinions.

rcompare

deprecate this function

I agree.

[timreichen]

I mostly agree. But I think these functions should probably have a stringify prefix instead. The strings returned in other functions with "format" are usually configurable. WDYT?

I agree but the current format() implementation in format.ts is kinda configurable with where on can pass FormatStyle.
Maybe this should also be renamed to stringify and instead of passing a style arg, just stringify what is passed?
format(semver, "primary") => stringify({major: 1, minor: 0, patch: 0})
format(semver, "build") => stringify({ build: ["x", "y", "z" })
etc.

eq, neq, gt, gte, lt, lte

deprecate all these functions

I weakly agree. However, doing so would require the dev to learn these comparison concepts. Happy to hear other opinions.

I agree to gather more opinions.
For most users this might already be known concept as in localeCompare or Intl.Collator compare.

[timreichen]

@iuioiua I have a question about rangeMin, rangeMax, comparatorMin, comparatorMax: Their name also don't follow the naming convention but is also not descriptive on what they actually do.
I think we should also rename them.
Do you have an idea to what? Maybe something like minForRange?

[timreichen]

outside as a function name seems weird. Normally in js it is positively formulated: includes, contains etc.
I think we should rename that to rangeIncludes and reverse the output boolean.

[timreichen]

eq, neq, gt, gte, lt, lte

deprecate all these functions

I weakly agree. However, doing so would require the dev to learn these comparison concepts. Happy to hear other opinions.

I think this would be not too hard to achieve because we can write some

/**
  * @deprecated (...)
  * use ```ts
  compare(...) > 0
  ``` instead.
  */

or similar into the deprecation note.

[timreichen]

testRange() is kinda a misnomer. I think that should be called inRange or something similar. Opinions?

[iuioiua]

@iuioiua I have a question about rangeMin, rangeMax, comparatorMin, comparatorMax: Their name also don't follow the naming convention but is also not descriptive on what they actually do. I think we should also rename them. Do you have an idea to what? Maybe something like minForRange?

These sound fine how they are to me.

outside as a function name seems weird. Normally in js it is positively formulated: includes, contains etc. I think we should rename that to rangeIncludes and reverse the output boolean.

I agree.

testRange() is kinda a misnomer. I think that should be called inRange or something similar. Opinions?

I agree.

eq, neq, gt, gte, lt, lte

deprecate all these functions

What if we had a SemVer class that implemented a well-thought-out valueOf() method such that we can do these comparison operators directly instead of using functions? Perhaps, an idea worth exploring.

Before:

import { gt, parse } from "https://deno.land/std/semver/mod.ts"

const s0 = parse(v0);
const s1 = parse(v1);
gt(s0, s1);

After:

import { SemVer } from "https://deno.land/std/semver/mod.ts"

const s0 = new SemVer(v0);
const s1 = new SemVer(v1);
s0 > s1;

[timreichen]

eq, neq, gt, gte, lt, lte

deprecate all these functions

What if we had a SemVer class that implemented a well-thought-out valueOf() method such that we can do these comparison operators directly instead of using functions? Perhaps, an idea worth exploring.

Before:

import { gt, parse } from "https://deno.land/std/semver/mod.ts"

const s0 = parse(v0);
const s1 = parse(v1);
gt(s0, s1);

After:

import { SemVer } from "https://deno.land/std/semver/mod.ts"

const s0 = new SemVer(v0);
const s1 = new SemVer(v1);
s0 > s1;

I am not for a SemVer class approach. This is how the implementation initially was and we moved away because a semver can be represented by a native object and we got overlaps and special case handlings for class instances as well as class instantiation overhead for the simplest things.

[timreichen]

@iuioiua I think it would not be a big deal to change from

eq(s0, s1)
neq(s0, s1)
gt(s0, s1)
gte(s0, s1)
lt(s0, s1)
lte(s0, s1)

to

compare(s0, s1) === 0
compare(s0, s1) !== 0
compare(s0, s1) > 0
compare(s0, s1) >= 0
compare(s0, s1) < 0
compare(s0, s1) <= 0

with enough time to switch.

How should we go about it?

[iuioiua]

@iuioiua I think it would not be a big deal to change from

eq(s0, s1)
neq(s0, s1)
gt(s0, s1)
gte(s0, s1)
lt(s0, s1)
lte(s0, s1)

to

compare(s0, s1) === 0
compare(s0, s1) !== 0
compare(s0, s1) > 0
compare(s0, s1) >= 0
compare(s0, s1) < 0
compare(s0, s1) <= 0

with enough time to switch.

How should we go about it?

I feel two ways about this. On one hand, I like a smaller, simpler API. It'd reduce engineering costs. Also, this makes comparisons more "organic" and closer to comparing numbers, which I like. However, you can argue that this might be a slightly poorer DX. I'd be keen to hear other's opinions.

[timreichen]

I feel two ways about this. On one hand, I like a smaller, simpler API. It'd reduce engineering costs. Also, this makes comparisons more "organic" and closer to comparing numbers, which I like. However, you can argue that this might be a slightly poorer DX. I'd be keen to hear other's opinions.

I posted this issue on discord for more opinions.

In addition, removing them would also solve the issue of their current names, since std functions should not use abbreviations and acronyms if possible. In std we have multiple other mods who use equal, not eq (assertEquals, assertAlmostEquals for example). Same with neq.

[marvinhagemeister]

I like the generic compare function because it would allow us to use it for Array.prototype.sort() as is.

[iuioiua]

@marvinhagemeister, do you think compare() is good enough on its own to justify removing eq() and others?

I'm leaning more in favour of this change now. I do still understand those that want to use eq(), etc.

[marvinhagemeister]

I'd add the compare function and base the other's internally on that. I think there isn't a reason enough to do a breaking API change.

[timreichen]

@marvinhagemeister that is exactly what we have now: We have compare and based the other functions on that.
The question is more about if these functions should exist at all because the are one-liner abstractions and sorta bloat the api.
It would not be a breaking change, if anything we would deprecate them first with a deprecation note on how to replace them with compare().