Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(semver): improve docs #4846

Merged
merged 10 commits into from
May 27, 2024
1 change: 1 addition & 0 deletions _tools/check_docs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ const ENTRY_POINTS = [
"../internal/mod.ts",
"../jsonc/mod.ts",
"../media_types/mod.ts",
"../semver/mod.ts",
"../ulid/mod.ts",
"../webgpu/mod.ts",
"../http/mod.ts",
Expand Down
15 changes: 15 additions & 0 deletions semver/can_parse.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,21 @@
// This module is browser compatible.
import { parse } from "./parse.ts";

/**
* Returns true if the string can be parsed as semver.
kt3k marked this conversation as resolved.
Show resolved Hide resolved
*
* @example Usage
* ```ts
* import { canParse } from "@std/semver";
iuioiua marked this conversation as resolved.
Show resolved Hide resolved
* import { assert, assertFalse } from "@std/assert";
*
* assert(canParse("1.2.3"));
* assertFalse(canParse("invalid"));
* ```
*
* @param version The version string to check
* @returns `true` if the string can be parsed as semver, `false` otherwise
kt3k marked this conversation as resolved.
Show resolved Hide resolved
*/
export function canParse(version: string): boolean {
try {
parse(version);
Expand Down
17 changes: 17 additions & 0 deletions semver/compare.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,23 @@ import {
* greater.
*
* Sorts in ascending order if passed to `Array.sort()`,
*
* @example Usage
* ```ts
* import { parse, compare } from "@std/semver";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const s0 = parse("1.2.3");
* const s1 = parse("1.2.4");
*
* assertEquals(compare(s0, s1), -1);
* assertEquals(compare(s1, s0), 1);
* assertEquals(compare(s0, s0), 0);
* ```
*
* @param s0 The first SemVer to compare
* @param s1 The second SemVer to compare
* @returns `1` if `s0` is greater, `0` if equal, or `-1` if `s1` is greater
*/
export function compare(
s0: SemVer,
Expand Down
23 changes: 22 additions & 1 deletion semver/difference.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,28 @@ import type { ReleaseType, SemVer } from "./types.ts";
import { compareIdentifier } from "./_shared.ts";

/**
* Returns difference between two versions by the release type, or `undefined` if the versions are the same.
* Returns difference between two versions by the release type,
* or `undefined` if the versions are the same.
*
* @example Usage
* ```ts
* import { parse, difference } from "@std/semver";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const s0 = parse("1.2.3");
* const s1 = parse("1.2.4");
* const s2 = parse("1.3.0");
* const s3 = parse("2.0.0");
*
* assertEquals(difference(s0, s1), "patch");
* assertEquals(difference(s0, s2), "minor");
* assertEquals(difference(s0, s3), "major");
* assertEquals(difference(s0, s0), undefined);
* ```
*
* @param s0 The first SemVer to compare
* @param s1 The second SemVer to compare
* @returns The release type difference or `undefined` if the versions are the same
*/
export function difference(s0: SemVer, s1: SemVer): ReleaseType | undefined {
const hasPrerelease = s0.prerelease?.length || s1.prerelease?.length;
Expand Down
16 changes: 16 additions & 0 deletions semver/equals.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,22 @@ import type { SemVer } from "./types.ts";
* Returns `true` if both semantic versions are logically equivalent, even if they're not the exact same version object.
*
* This is equal to `compare(s0, s1) === 0`.
*
* @example Usage
* ```ts
* import { parse, equals } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const s0 = parse("1.2.3");
* const s1 = parse("1.2.3");
*
* assert(equals(s0, s1));
* assertFalse(equals(s0, parse("1.2.4")));
* ```
*
* @param s0 The first version to compare
* @param s1 The second version to compare
kt3k marked this conversation as resolved.
Show resolved Hide resolved
* @returns `true` if `s0` is equal to `s1`, `false` otherwise
*/
export function equals(s0: SemVer, s1: SemVer): boolean {
return compare(s0, s1) === 0;
Expand Down
13 changes: 13 additions & 0 deletions semver/format.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,19 @@ function formatNumber(value: number) {
*
* If any number is positive or negative infinity then '∞' or '⧞' will be printed instead.
*
* @example Usage
* ```ts
* import { format } from "@std/semver";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const semver = {
* major: 1,
* minor: 2,
* patch: 3,
* };
* assertEquals(format(semver), "1.2.3");
* ```
*
* @param semver The semantic version to format
kt3k marked this conversation as resolved.
Show resolved Hide resolved
* @returns The string representation of a semantic version.
*/
Expand Down
10 changes: 9 additions & 1 deletion semver/format_range.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,15 @@ function formatComparator(comparator: Comparator): string {

/**
* Formats the range into a string
* @example >=0.0.0 || <1.0.0
* @example Usage
* ```ts
* import { formatRange, parseRange } from "@std/semver";
* import { assertEquals } from "@std/assert";
*
* const range = parseRange(">=1.2.3 <1.2.4");
* assertEquals(formatRange(range), ">=1.2.3 <1.2.4");
* ```
*
* @param range The range to format
* @returns A string representation of the range
*/
Expand Down
16 changes: 16 additions & 0 deletions semver/greater_or_equal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,22 @@ import { compare } from "./compare.ts";
* Greater than or equal to comparison
*
* This is equal to `compare(s0, s1) >= 0`.
*
* @example Usage
* ```ts
* import { parse, greaterOrEqual } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const s0 = parse("1.2.3");
* const s1 = parse("1.2.4");
* assert(greaterOrEqual(s1, s0));
* assertFalse(greaterOrEqual(s0, s1));
* assert(greaterOrEqual(s0, s0));
* ```
*
* @param s0 The first version to compare
* @param s1 The second version to compare
* @returns `true` if `s0` is greater than or equal to `s1`, `false` otherwise
*/
export function greaterOrEqual(s0: SemVer, s1: SemVer): boolean {
return compare(s0, s1) >= 0;
Expand Down
16 changes: 16 additions & 0 deletions semver/greater_than.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,22 @@ import { compare } from "./compare.ts";
* Greater than comparison
*
* This is equal to `compare(s0, s1) > 0`.
*
* @example Usage
* ```ts
* import { parse, greaterThan } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const s0 = parse("1.2.3");
* const s1 = parse("1.2.4");
* assert(greaterThan(s1, s0));
* assertFalse(greaterThan(s0, s1));
* assertFalse(greaterThan(s0, s0));
* ```
*
* @param s0 The first version to compare
* @param s1 The second version to compare
* @returns `true` if `s0` is greater than `s1`, `false` otherwise
*/
export function greaterThan(s0: SemVer, s1: SemVer): boolean {
return compare(s0, s1) > 0;
Expand Down
20 changes: 19 additions & 1 deletion semver/greater_than_range.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,25 @@ import { testComparatorSet } from "./_test_comparator_set.ts";
import { isWildcardComparator } from "./_shared.ts";
import { compare } from "./compare.ts";

/** Check if the semver is greater than the range. */
/**
* Check if the semver is greater than the range.
kt3k marked this conversation as resolved.
Show resolved Hide resolved
*
* @example Usage
* ```ts
* import { parse, parseRange, greaterThanRange } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const v0 = parse("1.2.3");
* const v1 = parse("1.2.4");
* const range = parseRange(">=1.2.3 <1.2.4");
* assertFalse(greaterThanRange(v0, range));
* assert(greaterThanRange(v1, range));
* ```
*
* @param semver The version to check.
* @param range The range to check against.
* @returns `true` if the semver is greater than the range, `false` otherwise.
*/
export function greaterThanRange(semver: SemVer, range: Range): boolean {
return range.every((comparatorSet) =>
greaterThanComparatorSet(semver, comparatorSet)
Expand Down
20 changes: 18 additions & 2 deletions semver/increment.ts
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,27 @@ function bumpPrerelease(
* If the input version has build metadata it will be preserved on the resulting version
* unless a new build parameter is specified. Specifying `""` will unset existing build
* metadata.
*
* @example Usage
* ```ts
* import { increment, parse } from "@std/semver";
* import { assertEquals } from "@std/assert/assert-equals";
*
* const version = parse("1.2.3");
* assertEquals(increment(version, "major"), parse("2.0.0"));
* assertEquals(increment(version, "minor"), parse("1.3.0"));
* assertEquals(increment(version, "patch"), parse("1.2.4"));
* assertEquals(increment(version, "prerelease"), parse("1.2.4-0"));
*
* const prerelease = parse("1.2.3-beta.0");
* assertEquals(increment(prerelease, "prerelease"), parse("1.2.3-beta.1"));
* ```
*
* @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 build The build metadata of the new version
* @returns
* @param buildmetadata The build metadata of the new version
* @returns The new version
*/
export function increment(
version: SemVer,
Expand Down
10 changes: 10 additions & 0 deletions semver/is_range.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,16 @@ function isComparator(value: unknown): value is Comparator {
* least the correct fields.
*
* Adds a type assertion if true.
*
* @example Usage
* ```ts
* import { isRange } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const range = [[{ major: 1, minor: 2, patch: 3 }]];
* assert(isRange(range));
* assertFalse(isRange({}));
* ```
* @param value The value to check if its a valid Range
* @returns True if its a valid Range otherwise false.
*/
Expand Down
16 changes: 16 additions & 0 deletions semver/is_semver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,22 @@ import { isValidNumber, isValidString } from "./_shared.ts";
* considered SemVer objects and this will return true.
*
* A type assertion is added to the value.
*
* @example Usage
* ```ts
* import { isSemVer } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const value = {
* major: 1,
* minor: 2,
* patch: 3,
* };
*
* assert(isSemVer(value));
* assertFalse(isSemVer({ major: 1, minor: 2 }));
* ```
*
* @param value The value to check to see if its a valid SemVer object
* @returns True if value is a valid SemVer otherwise false
*/
Expand Down
16 changes: 16 additions & 0 deletions semver/less_or_equal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,22 @@ import { compare } from "./compare.ts";
* Less than or equal to comparison
*
* This is equal to `compare(s0, s1) <= 0`.
*
* @example Usage
* ```ts
* import { parse, lessOrEqual } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const s0 = parse("1.2.3");
* const s1 = parse("1.2.4");
* assert(lessOrEqual(s0, s1));
* assertFalse(lessOrEqual(s1, s0));
* assert(lessOrEqual(s0, s0));
* ```
*
* @param s0 the first version to compare
* @param s1 the second version to compare
* @returns `true` if `s0` is less than or equal to `s1`, `false` otherwise
*/
export function lessOrEqual(s0: SemVer, s1: SemVer): boolean {
return compare(s0, s1) <= 0;
Expand Down
16 changes: 16 additions & 0 deletions semver/less_than.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,22 @@ import { compare } from "./compare.ts";
* Less than comparison
*
* This is equal to `compare(s0, s1) < 0`.
*
* @example Usage
* ```ts
* import { parse, lessThan } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const s0 = parse("1.2.3");
* const s1 = parse("1.2.4");
* assert(lessThan(s0, s1));
* assertFalse(lessThan(s1, s0));
* assertFalse(lessThan(s0, s0));
* ```
*
* @param s0 the first version to compare
* @param s1 the second version to compare
* @returns `true` if `s0` is less than `s1`, `false` otherwise
*/
export function lessThan(s0: SemVer, s1: SemVer): boolean {
return compare(s0, s1) < 0;
Expand Down
20 changes: 19 additions & 1 deletion semver/less_than_range.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,25 @@ import { testComparatorSet } from "./_test_comparator_set.ts";
import { isWildcardComparator } from "./_shared.ts";
import { compare } from "./compare.ts";

/** Check if the semver is less than the range. */
/**
* Check if the semver is less than the range.
*
* @example Usage
* ```ts
* import { parse, parseRange, lessThanRange } from "@std/semver";
* import { assert, assertFalse } from "@std/assert";
*
* const v0 = parse("1.2.3");
* const v1 = parse("1.0.0");
* const range = parseRange(">=1.2.3 <1.2.4");
* assertFalse(lessThanRange(v0, range));
* assert(lessThanRange(v1, range));
* ```
*
* @param semver The version to check.
* @param range The range to check against.
* @returns `true` if the semver is less than the range, `false` otherwise.
*/
export function lessThanRange(semver: SemVer, range: Range): boolean {
return range.every((comparatorSet) =>
lessThanComparatorSet(semver, comparatorSet)
Expand Down
12 changes: 12 additions & 0 deletions semver/max_satisfying.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,18 @@ import { greaterThan } from "./greater_than.ts";
/**
* Returns the highest version in the list that satisfies the range, or `undefined`
* if none of them do.
*
* @example Usage
* ```ts
* import { parse, parseRange, maxSatisfying } from "@std/semver";
* import { assertEquals } from "@std/assert";
*
* const versions = ["1.2.3", "1.2.4", "1.3.0", "2.0.0", "2.1.0"].map(parse);
* const range = parseRange(">=1.0.0 <2.0.0");
*
* assertEquals(maxSatisfying(versions, range), parse("1.3.0"));
* ```
*
* @param versions The versions to check.
* @param range The range of possible versions to compare to.
* @returns The highest version in versions that satisfies the range.
Expand Down
12 changes: 12 additions & 0 deletions semver/min_satisfying.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,18 @@ import { lessThan } from "./less_than.ts";
/**
* Returns the lowest version in the list that satisfies the range, or `undefined` if
* none of them do.
*
* @example Usage
* ```ts
* import { parse, parseRange, minSatisfying } from "@std/semver";
* import { assertEquals } from "@std/assert";
*
* const versions = ["0.2.0", "1.2.3", "1.3.0", "2.0.0", "2.1.0"].map(parse);
* const range = parseRange(">=1.0.0 <2.0.0");
*
* assertEquals(minSatisfying(versions, range), parse("1.2.3"));
* ```
*
* @param versions The versions to check.
* @param range The range of possible versions to compare to.
* @returns The lowest version in versions that satisfies the range.
Expand Down
Loading