BREAKING(semver): replace prerelease and buildmetadata arguments with options object (#5471)

BREAKING(semver): replace `prerelease` and `build` arguments with options object

semver/increment.ts

@@ -35,6 +35,14 @@ function bumpPrerelease(
   return values;
 }
 
+/** Options for {@linkcode increment}. */
+export interface IncrementOptions {
+  /** The pre-release metadata of the new version. */
+  prerelease?: string;
+  /** The build metadata of the new version. */
+  build?: string;
+}
+
 /**
  * Returns the new SemVer resulting from an increment by release type.
  *
@@ -73,18 +81,16 @@ function bumpPrerelease(
  *
  * @param version The version to increment
  * @param release The type of increment to perform
- * @param prerelease The pre-release metadata of the new version
- * @param buildmetadata The build metadata of the new version
+ * @param options Additional options
  * @returns The new version
  */
 export function increment(
   version: SemVer,
   release: ReleaseType,
-  prerelease?: string,
-  buildmetadata?: string,
+  options?: IncrementOptions,
 ): SemVer {
-  const build = buildmetadata !== undefined
-    ? parseBuild(buildmetadata)
+  const build = options?.build !== undefined
+    ? parseBuild(options?.build)
     : version.build;
 
   switch (release) {
@@ -93,7 +99,7 @@ export function increment(
         major: version.major + 1,
         minor: 0,
         patch: 0,
-        prerelease: bumpPrerelease(version.prerelease, prerelease),
+        prerelease: bumpPrerelease(version.prerelease, options?.prerelease),
         build,
       };
     case "preminor":
@@ -101,7 +107,7 @@ export function increment(
         major: version.major,
         minor: version.minor + 1,
         patch: 0,
-        prerelease: bumpPrerelease(version.prerelease, prerelease),
+        prerelease: bumpPrerelease(version.prerelease, options?.prerelease),
         build,
       };
     case "prepatch":
@@ -109,7 +115,7 @@ export function increment(
         major: version.major,
         minor: version.minor,
         patch: version.patch + 1,
-        prerelease: bumpPrerelease(version.prerelease, prerelease),
+        prerelease: bumpPrerelease(version.prerelease, options?.prerelease),
         build,
       };
     case "prerelease": {
@@ -120,7 +126,7 @@ export function increment(
         major: version.major,
         minor: version.minor,
         patch,
-        prerelease: bumpPrerelease(version.prerelease, prerelease),
+        prerelease: bumpPrerelease(version.prerelease, options?.prerelease),
         build,
       };
     }
@@ -180,7 +186,7 @@ export function increment(
         major: version.major,
         minor: version.minor,
         patch: version.patch,
-        prerelease: bumpPrerelease(version.prerelease, prerelease),
+        prerelease: bumpPrerelease(version.prerelease, options?.prerelease),
         build,
       };
     }

semver/increment_test.ts

@@ -963,11 +963,11 @@ Deno.test("increment()", async (t) => {
     ],
   ];
 
-  for (const [version, op, identifier, metadata, expected] of versions) {
+  for (const [version, op, prerelease, build, expected] of versions) {
     await t.step({
       name: `${op} ${format(version)}`,
       fn: () => {
-        const actual = increment(version, op, identifier, metadata);
+        const actual = increment(version, op, { prerelease, build });
         assertEquals(format(actual), expected);
       },
     });

semver/mod.ts

@@ -130,7 +130,7 @@
  * import { increment, parse } from "@std/semver";
  * import { assertEquals } from "@std/assert";
  *
- * assertEquals(increment(parse("1.2.3"), "prerelease", "alpha"), parse("1.2.4-alpha.0"));
+ * assertEquals(increment(parse("1.2.3"), "prerelease", { prerelease: "alpha" }), parse("1.2.4-alpha.0"));
  * ```
  *
  * ### Build Metadata