deprecation(semver): deprecate eq(), neq(), lt(), lte(), gt() and gte()

semver/compare.ts

@@ -9,21 +9,30 @@ import {
 /**
  * Compare two semantic version objects.
  *
- * Returns `0` if `v1 === v2`, or `1` if `v1` is greater, or `-1` if `v2` is
+ * Returns `0` if `a === b`, or `1` if `a` is greater, or `-1` if `b` is
  * greater.
  *
- * Sorts in ascending order if passed to `Array.sort()`,
+ * Sorts in ascending order if passed to `Array.sort()`.
+ *
+ * The number returned by `compare` can then be compared to `0` in order to
+ * determine some common cases:
+ * - `compare(a, b) === 0` a equal to b
+ * - `compare(a, b) !== 0` a not equal to b
+ * - `compare(a, b) < 0`   a less than b
+ * - `compare(a, b) <= 0`  a less than or equal to b
+ * - `compare(a, b) > 0`   a greater than b
+ * - `compare(a, b) >= 0`  a greater than or equal to b
  */
 export function compare(
-  s0: SemVer,
-  s1: SemVer,
+  a: SemVer,
+  b: SemVer,
 ): 1 | 0 | -1 {
-  if (s0 === s1) return 0;
+  if (a === b) return 0;
   return (
-    compareNumber(s0.major, s1.major) ||
-    compareNumber(s0.minor, s1.minor) ||
-    compareNumber(s0.patch, s1.patch) ||
-    checkIdentifier(s0.prerelease, s1.prerelease) ||
-    compareIdentifier(s0.prerelease, s1.prerelease)
+    compareNumber(a.major, b.major) ||
+    compareNumber(a.minor, b.minor) ||
+    compareNumber(a.patch, b.patch) ||
+    checkIdentifier(a.prerelease, b.prerelease) ||
+    compareIdentifier(a.prerelease, b.prerelease)
   );
 }

semver/compare_test.ts

@@ -3,7 +3,7 @@ import { assertEquals } from "../assert/mod.ts";
 import { parse } from "./parse.ts";
 import { compare } from "./compare.ts";
 
-Deno.test("compare ignores build metadata", async (t) => {
+Deno.test("compare() ignores build metadata", async (t) => {
   // v+b > v
   const steps: [string, string, number][] = [
     ["1.0.0", "1.0.0+0", 0],
@@ -28,7 +28,7 @@ Deno.test("compare ignores build metadata", async (t) => {
 });
 
 Deno.test({
-  name: "comparePre",
+  name: "compare() handles prerelease",
   fn: async (t) => {
     const cases: [string, string, number][] = [
       ["1.2.3", "1.2.3", 0],
@@ -54,3 +54,171 @@ Deno.test({
     }
   },
 });
+
+// taken over from `eq_test.ts`
+Deno.test({
+  name: "compare()",
+  fn: async (t) => {
+    // [version1, version2]
+    // version1 should be greater than version2
+    const versions: [string, string, number][] = [
+      ["0.0.0", "0.0.0", 0],
+      ["1.2.3", "1.2.3", 0],
+      ["1.2.3-pre.0", "1.2.3-pre.0", 0],
+      ["1.2.3-pre.0+abc", "1.2.3-pre.0+abc", 0],
+      ["0.0.0", "0.0.0-foo", 1],
+      ["0.0.1", "0.0.0", 1],
+      ["1.0.0", "0.9.9", 1],
+      ["0.10.0", "0.9.0", 1],
+      ["0.99.0", "0.10.0", 1],
+      ["2.0.0", "1.2.3", 1],
+      ["1.2.3", "1.2.3-asdf", 1],
+      ["1.2.3", "1.2.3-4", 1],
+      ["1.2.3", "1.2.3-4-foo", 1],
+      ["1.2.3-5", "1.2.3-5-foo", -1], // numbers > strings, `5-foo` is a string not a number
+      ["1.2.3-5", "1.2.3-4", 1],
+      ["1.2.3-5-foo", "1.2.3-5-Foo", 1],
+      ["3.0.0", "2.7.2+asdf", 1],
+      ["1.2.3-a.10", "1.2.3-a.5", 1],
+      ["1.2.3-a.5", "1.2.3-a.b", -1],
+      ["1.2.3-a.b", "1.2.3-a", 1],
+      ["1.2.3-a.b.c.10.d.5", "1.2.3-a.b.c.5.d.100", 1],
+      ["1.2.3-r2", "1.2.3-r100", 1],
+      ["1.2.3-r100", "1.2.3-R2", 1],
+    ];
+
+    for (const [v0, v1, expected] of versions) {
+      await t.step(`${v0} == ${v1}`, () => {
+        const s0 = parse(v0);
+        const s1 = parse(v1);
+
+        const eq = compare(s0, s1);
+        const op = expected ? "==" : "!=";
+        assertEquals(eq, expected, `${s0} ${op} ${s1}`);
+      });
+    }
+  },
+});
+
+// taken over from `neq_test.ts`
+Deno.test({
+  name: "compare()",
+  fn: async (t) => {
+    // [version1, version2]
+    // version1 should be greater than version2
+    const versions: [string, string, number][] = [
+      ["0.0.0", "0.0.0", 0],
+      ["1.2.3", "1.2.3", 0],
+      ["1.2.3-pre.0", "1.2.3-pre.0", 0],
+      ["1.2.3-pre.0+abc", "1.2.3-pre.0+abc", 0],
+      ["0.0.0", "0.0.0-foo", 1],
+      ["0.0.1", "0.0.0", 1],
+      ["1.0.0", "0.9.9", 1],
+      ["0.10.0", "0.9.0", 1],
+      ["0.99.0", "0.10.0", 1],
+      ["2.0.0", "1.2.3", 1],
+      ["1.2.3", "1.2.3-asdf", 1],
+      ["1.2.3", "1.2.3-4", 1],
+      ["1.2.3", "1.2.3-4-foo", 1],
+      ["1.2.3-5", "1.2.3-5-foo", -1], // numbers > strings, `5-foo` is a string not a number
+      ["1.2.3-5", "1.2.3-4", 1],
+      ["1.2.3-5-foo", "1.2.3-5-Foo", 1],
+      ["3.0.0", "2.7.2+asdf", 1],
+      ["1.2.3-a.10", "1.2.3-a.5", 1],
+      ["1.2.3-a.5", "1.2.3-a.b", -1],
+      ["1.2.3-a.b", "1.2.3-a", 1],
+      ["1.2.3-a.b.c.10.d.5", "1.2.3-a.b.c.5.d.100", 1],
+      ["1.2.3-r2", "1.2.3-r100", 1],
+      ["1.2.3-r100", "1.2.3-R2", 1],
+    ];
+
+    for (const [v0, v1, expected] of versions) {
+      await t.step(`${v0} != ${v1}`, () => {
+        const s0 = parse(v0);
+        const s1 = parse(v1);
+
+        const op = expected ? "==" : "!=";
+
+        assertEquals(compare(s0, s1), expected, `${s0} ${op} ${s1}`);
+      });
+    }
+  },
+});
+
+// taken over from `lt_test.ts`
+Deno.test({
+  name: "compare()",
+  fn: async (t) => {
+    // [version1, version2]
+    // version1 should be greater than version2
+    const versions: [string, string][] = [
+      ["0.0.0", "0.0.0-foo"],
+      ["0.0.1", "0.0.0"],
+      ["1.0.0", "0.9.9"],
+      ["0.10.0", "0.9.0"],
+      ["0.99.0", "0.10.0"],
+      ["2.0.0", "1.2.3"],
+      ["1.2.3", "1.2.3-asdf"],
+      ["1.2.3", "1.2.3-4"],
+      ["1.2.3", "1.2.3-4-foo"],
+      ["1.2.3-5-foo", "1.2.3-5"], // numbers < strings, `5-foo` is a string not a number
+      ["1.2.3-5", "1.2.3-4"],
+      ["1.2.3-5-foo", "1.2.3-5-Foo"],
+      ["3.0.0", "2.7.2+asdf"],
+      ["1.2.3-a.10", "1.2.3-a.5"],
+      ["1.2.3-a.b", "1.2.3-a.5"],
+      ["1.2.3-a.b", "1.2.3-a"],
+      ["1.2.3-a.b.c.10.d.5", "1.2.3-a.b.c.5.d.100"],
+      ["1.2.3-r2", "1.2.3-r100"],
+      ["1.2.3-r100", "1.2.3-R2"],
+    ];
+
+    for (const [v0, v1] of versions) {
+      await t.step(`${v0} <=> ${v1}`, () => {
+        const s0 = parse(v0);
+        const s1 = parse(v1);
+        const actual = compare(s0, s1);
+        assertEquals(actual, 1, `${v0} < ${v1} : ${actual}`);
+      });
+    }
+  },
+});
+
+// taken over from `gt_test.ts`
+Deno.test({
+  name: "compare()",
+  fn: async (t) => {
+    // [version1, version2]
+    // version1 should be greater than version2
+    const versions: [string, string][] = [
+      ["0.0.0", "0.0.0-foo"],
+      ["0.0.1", "0.0.0"],
+      ["1.0.0", "0.9.9"],
+      ["0.10.0", "0.9.0"],
+      ["0.99.0", "0.10.0"],
+      ["2.0.0", "1.2.3"],
+      ["1.2.3", "1.2.3-asdf"],
+      ["1.2.3", "1.2.3-4"],
+      ["1.2.3", "1.2.3-4-foo"],
+      ["1.2.3-5-foo", "1.2.3-5"], // numbers < strings, `5-foo` is a string not a number
+      ["1.2.3-5", "1.2.3-4"],
+      ["1.2.3-5-foo", "1.2.3-5-Foo"],
+      ["3.0.0", "2.7.2+asdf"],
+      ["1.2.3-a.10", "1.2.3-a.5"],
+      ["1.2.3-a.b", "1.2.3-a.5"],
+      ["1.2.3-a.b", "1.2.3-a"],
+      ["1.2.3-a.b.c.10.d.5", "1.2.3-a.b.c.5.d.100"],
+      ["1.2.3-r2", "1.2.3-r100"],
+      ["1.2.3-r100", "1.2.3-R2"],
+    ];
+
+    for (const [v0, v1] of versions) {
+      await t.step(`${v0} <=> ${v1}`, () => {
+        const s0 = parse(v0);
+        const s1 = parse(v1);
+        const actual = compare(s0, s1);
+        assertEquals(actual, 1, `${v0} >= ${v1} : ${actual}`);
+      });
+    }
+  },
+});

semver/eq.ts

@@ -2,8 +2,12 @@
 import { compare } from "./compare.ts";
 import type { SemVer } from "./types.ts";
 
-/** Returns `true` if they're logically equivalent, even if they're not the exact
- * same version object. */
+/**
+ * Returns `true` if they're logically equivalent, even if they're not the exact same version object.
+ * @deprecated (will be removed in 0.213.0) Use {@linkcode compare} instead.
+ *
+ * This is equal to `compare(s0, s1) === 0`.
+ */
 export function eq(s0: SemVer, s1: SemVer): boolean {
   return compare(s0, s1) === 0;
 }

semver/gt.ts

@@ -2,7 +2,12 @@
 import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
-/** Greater than comparison */
+/**
+ * Greater than comparison
+ * @deprecated (will be removed in 0.213.0) use {@linkcode compare} instead.
+ *
+ * This is equal to `compare(s0, s1) > 0`
+ */
 export function gt(
   s0: SemVer,
   s1: SemVer,

semver/gte.ts

@@ -2,7 +2,12 @@
 import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
-/** Greater than or equal to comparison */
+/**
+ * Greater than or equal to comparison
+ * @deprecated (will be removed in 0.213.0) use {@linkcode compare} instead.
+ *
+ * This is equal to `compare(s0, s1) >= 0`
+ */
 export function gte(
   s0: SemVer,
   s1: SemVer,

semver/lt.ts

@@ -2,7 +2,12 @@
 import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
-/** Less than comparison */
+/**
+ *  Less than comparison
+ * @deprecated (will be removed in 0.213.0) use {@linkcode compare} instead.
+ *
+ * This is equal to `compare(s0, s1) < 0`
+ */
 export function lt(
   s0: SemVer,
   s1: SemVer,

semver/lte.ts

@@ -2,7 +2,12 @@
 import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
-/** Less than or equal to comparison */
+/**
+ * Less than or equal to comparison
+ * @deprecated (will be removed in 0.213.0) use {@linkcode compare} instead.
+ *
+ * This is equal to `compare(s0, s1) <= 0`
+ */
 export function lte(
   s0: SemVer,
   s1: SemVer,

semver/neq.ts

@@ -2,7 +2,12 @@
 import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
-/** Not equal comparison */
+/**
+ * Not equal comparison
+ * @deprecated (will be removed in 0.213.0) use {@linkcode compare} instead.
+ *
+ * This is equal to `compare(s0, s1) !== 0`
+ */
 export function neq(
   s0: SemVer,
   s1: SemVer,