feat(semver): add input validation to parseVersion and compareVersions

Signed-off-by: leocavalcante <leo@cavalcante.dev>

Author: leocavalcante

src/semver.d.mts

@@ -16,10 +16,12 @@ export interface ParsedVersion {
  *
  * @param version - The version string (e.g., "1.2.3")
  * @returns Parsed version object or null if invalid
+ * @throws {TypeError} If version is not a string
  *
  * @example
  * parseVersion("1.2.3")  // { major: 1, minor: 2, patch: 3 }
  * parseVersion("invalid")  // null
+ * parseVersion(null)  // throws TypeError
  */
 export function parseVersion(version: string): ParsedVersion | null
 
@@ -29,11 +31,13 @@ export function parseVersion(version: string): ParsedVersion | null
  * @param a - First version
  * @param b - Second version
  * @returns -1 if a < b, 0 if a == b, 1 if a > b
+ * @throws {TypeError} If a or b is not a valid ParsedVersion object with numeric major, minor, and patch properties
  *
  * @example
  * compareVersions({ major: 1, minor: 0, patch: 0 }, { major: 2, minor: 0, patch: 0 })  // -1
  * compareVersions({ major: 1, minor: 0, patch: 0 }, { major: 1, minor: 0, patch: 0 })  // 0
  * compareVersions({ major: 2, minor: 0, patch: 0 }, { major: 1, minor: 0, patch: 0 })  // 1
+ * compareVersions({}, {})  // throws TypeError
  */
 export function compareVersions(a: ParsedVersion, b: ParsedVersion): -1 | 0 | 1
 

src/semver.mjs

@@ -10,8 +10,14 @@
  *
  * @param {string} version - The version string (e.g., "1.2.3")
  * @returns {{ major: number, minor: number, patch: number } | null} Parsed version or null if invalid
+ * @throws {TypeError} If version is not a string
  */
 export function parseVersion(version) {
+	if (typeof version !== "string") {
+		throw new TypeError(
+			`parseVersion: version must be a string, got ${version === null ? "null" : typeof version}`,
+		)
+	}
 	const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/)
 	if (!match) return null
 	return {
@@ -21,14 +27,43 @@ export function parseVersion(version) {
 	}
 }
 
+/**
+ * Validates that a value is a valid ParsedVersion object.
+ *
+ * @param {unknown} value - The value to validate
+ * @param {string} paramName - The parameter name for error messages
+ * @throws {TypeError} If value is not a valid ParsedVersion object
+ */
+function validateParsedVersion(value, paramName) {
+	if (value === null || value === undefined) {
+		throw new TypeError(
+			`compareVersions: ${paramName} must be a ParsedVersion object, got ${value === null ? "null" : "undefined"}`,
+		)
+	}
+	if (typeof value !== "object") {
+		throw new TypeError(
+			`compareVersions: ${paramName} must be a ParsedVersion object, got ${typeof value}`,
+		)
+	}
+	const v = /** @type {Record<string, unknown>} */ (value)
+	if (typeof v.major !== "number" || typeof v.minor !== "number" || typeof v.patch !== "number") {
+		throw new TypeError(
+			`compareVersions: ${paramName} must have numeric major, minor, and patch properties`,
+		)
+	}
+}
+
 /**
  * Compares two parsed version objects.
  *
  * @param {{ major: number, minor: number, patch: number }} a - First version
  * @param {{ major: number, minor: number, patch: number }} b - Second version
  * @returns {number} -1 if a < b, 0 if a == b, 1 if a > b
+ * @throws {TypeError} If a or b is not a valid ParsedVersion object
  */
 export function compareVersions(a, b) {
+	validateParsedVersion(a, "a")
+	validateParsedVersion(b, "b")
 	if (a.major !== b.major) return a.major < b.major ? -1 : 1
 	if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1
 	if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1

tests/semver.test.ts

@@ -24,6 +24,31 @@ describe("semver.mjs exports", () => {
 			expect(parseVersion("0.0.1")).toEqual({ major: 0, minor: 0, patch: 1 })
 			expect(parseVersion("999.999.999")).toEqual({ major: 999, minor: 999, patch: 999 })
 		})
+
+		it("should throw TypeError for null", () => {
+			expect(() => parseVersion(null as unknown as string)).toThrow(TypeError)
+			expect(() => parseVersion(null as unknown as string)).toThrow(
+				"parseVersion: version must be a string, got null",
+			)
+		})
+
+		it("should throw TypeError for undefined", () => {
+			expect(() => parseVersion(undefined as unknown as string)).toThrow(TypeError)
+			expect(() => parseVersion(undefined as unknown as string)).toThrow(
+				"parseVersion: version must be a string, got undefined",
+			)
+		})
+
+		it("should throw TypeError for non-string inputs", () => {
+			expect(() => parseVersion(123 as unknown as string)).toThrow(TypeError)
+			expect(() => parseVersion(123 as unknown as string)).toThrow(
+				"parseVersion: version must be a string, got number",
+			)
+			expect(() => parseVersion({} as unknown as string)).toThrow(TypeError)
+			expect(() => parseVersion({} as unknown as string)).toThrow(
+				"parseVersion: version must be a string, got object",
+			)
+		})
 	})
 
 	describe("compareVersions", () => {
@@ -76,6 +101,95 @@ describe("semver.mjs exports", () => {
 				compareVersions({ major: 1, minor: 2, patch: 0 }, { major: 1, minor: 1, patch: 9 }),
 			).toBe(1)
 		})
+
+		it("should throw TypeError for null parameter a", () => {
+			expect(() =>
+				compareVersions(null as unknown as { major: number; minor: number; patch: number }, {
+					major: 1,
+					minor: 0,
+					patch: 0,
+				}),
+			).toThrow(TypeError)
+			expect(() =>
+				compareVersions(null as unknown as { major: number; minor: number; patch: number }, {
+					major: 1,
+					minor: 0,
+					patch: 0,
+				}),
+			).toThrow("compareVersions: a must be a ParsedVersion object, got null")
+		})
+
+		it("should throw TypeError for undefined parameter b", () => {
+			expect(() =>
+				compareVersions(
+					{ major: 1, minor: 0, patch: 0 },
+					undefined as unknown as { major: number; minor: number; patch: number },
+				),
+			).toThrow(TypeError)
+			expect(() =>
+				compareVersions(
+					{ major: 1, minor: 0, patch: 0 },
+					undefined as unknown as { major: number; minor: number; patch: number },
+				),
+			).toThrow("compareVersions: b must be a ParsedVersion object, got undefined")
+		})
+
+		it("should throw TypeError for non-object parameters", () => {
+			expect(() =>
+				compareVersions("1.0.0" as unknown as { major: number; minor: number; patch: number }, {
+					major: 1,
+					minor: 0,
+					patch: 0,
+				}),
+			).toThrow(TypeError)
+			expect(() =>
+				compareVersions("1.0.0" as unknown as { major: number; minor: number; patch: number }, {
+					major: 1,
+					minor: 0,
+					patch: 0,
+				}),
+			).toThrow("compareVersions: a must be a ParsedVersion object, got string")
+		})
+
+		it("should throw TypeError for empty objects", () => {
+			expect(() =>
+				compareVersions({} as unknown as { major: number; minor: number; patch: number }, {
+					major: 1,
+					minor: 0,
+					patch: 0,
+				}),
+			).toThrow(TypeError)
+			expect(() =>
+				compareVersions({} as unknown as { major: number; minor: number; patch: number }, {
+					major: 1,
+					minor: 0,
+					patch: 0,
+				}),
+			).toThrow("compareVersions: a must have numeric major, minor, and patch properties")
+		})
+
+		it("should throw TypeError for objects with non-numeric properties", () => {
+			expect(() =>
+				compareVersions(
+					{ major: "1", minor: 0, patch: 0 } as unknown as {
+						major: number
+						minor: number
+						patch: number
+					},
+					{ major: 1, minor: 0, patch: 0 },
+				),
+			).toThrow(TypeError)
+			expect(() =>
+				compareVersions(
+					{ major: 1, minor: null, patch: 0 } as unknown as {
+						major: number
+						minor: number
+						patch: number
+					},
+					{ major: 1, minor: 0, patch: 0 },
+				),
+			).toThrow("compareVersions: a must have numeric major, minor, and patch properties")
+		})
 	})
 
 	describe("checkVersionCompatibility", () => {