@sdxc/semver 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# @sdxc/semver
+
+SemVer 2.0.0 parsing, precedence ordering and range-free version comparisons.
+
+## Installation
+
+```bash
+npm add @sdxc/semver
+```
+
+`parse()` reports failures as a `Result` from [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result), which installs alongside this package.
+
+## Usage
+
+### Comparing Two Versions
+
+```typescript
+import { satisfies } from "@sdxc/semver";
+
+satisfies("1.9.0", "^", "1.4.2"); // true
+satisfies("1.5.0", "~", "1.4.2"); // false
+satisfies("2.0.0", ">", "1.99.99"); // true
+
+satisfies("nightly", ">", "1.0.0"); // false — "nightly" is not a version
+```
+
+### Sorting A List Of Versions
+
+```typescript
+import { compare } from "@sdxc/semver";
+
+["2026.10.1", "2026.9.4", "2026.9.30"].sort(compare);
+// ["2026.9.4", "2026.9.30", "2026.10.1"]
+
+["1.0.0", "1.0.0-rc.1", "1.0.0-beta.11", "1.0.0-beta.2"].sort(compare);
+// ["1.0.0-beta.2", "1.0.0-beta.11", "1.0.0-rc.1", "1.0.0"]
+```
+
+### Reading A Version's Elements
+
+```typescript
+import { parse } from "@sdxc/semver";
+import { isFailure } from "@sdxc/result";
+
+let result = parse("v2.1.0-rc.3+build.9");
+
+if (isFailure(result)) {
+	console.error(result.error.message); // Invalid version: "v2.1.0-rc.3+build.9"
+	return;
+}
+
+result.data; // { major: 2, minor: 1, patch: 0, prerelease: ["rc", "3"] }
+```
+
+## API
+
+### `parse(text: string): Result<SemVer, InvalidSemVerError>`
+
+Read a version string into its elements, returning a `Success<SemVer>` or a `Failure<InvalidSemVerError>` naming the rejected text. The grammar is SemVer 2.0.0 with one addition: an optional leading `v`, as a git tag or a user agent writes it. Build metadata is dropped, since it carries no precedence.
+
+```typescript
+parse("1.2.3"); // { status: "success", data: { major: 1, minor: 2, patch: 3, prerelease: [] } }
+parse("v1.0.0-rc.1"); // prerelease: ["rc", "1"]
+parse("01.2.3"); // { status: "failure", error: InvalidSemVerError } — a padded element
+```
+
+### `compare(a: string, b: string): number`
+
+Order two version strings by SemVer 2.0.0 precedence, ready to hand to [`Array.prototype.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort). Returns a negative number when `a` comes first, a positive one when `b` does, and `0` when the two rank equally.
+
+The ordering is total, so a list whose entries come from somewhere unchecked — a registry, a tag listing, user input — sorts in one call. Text that is not a version ranks below every version and ties with other such text, which collects those entries at the front where the caller can see them.
+
+```typescript
+compare("1.9.0", "1.10.0"); // negative — elements compare as numbers
+compare("1.0.0-rc.1", "1.0.0"); // negative — a prerelease precedes its release
+compare("1.2.3+a", "1.2.3+b"); // 0 — build metadata carries no precedence
+compare("latest", "0.0.0"); // negative — text that is not a version sorts first
+```
+
+### `satisfies(value: string, comparison: SemVerComparison, against: string): boolean`
+
+Answer whether `value` stands in the named relation to `against`. Either side that is not a version answers `false`, so a field holding something else matches nothing instead of failing the check.
+
+A prerelease takes part by precedence alone: `1.2.4-rc.1` satisfies `^ 1.2.3`, because it outranks `1.2.3` and shares its major. Test a release channel by comparing against the prerelease you mean — `satisfies(value, ">=", "1.2.4-rc.1")` — when that is the boundary you want.
+
+```typescript
+satisfies("1.2.3", "=", "1.2.3"); // true
+satisfies("1.4.5", "~", "1.4.2"); // true, the same minor
+satisfies("1.5.0", "~", "1.4.2"); // false, a later minor
+satisfies("0.3.0", "^", "0.2.3"); // false, the left-most non-zero element moved
+```
+
+| Comparison | Holds when                                                             |
+| ---------- | ---------------------------------------------------------------------- |
+| `=`        | The two rank equally                                                   |
+| `!=`       | The two rank differently                                               |
+| `<`        | `value` precedes `against`                                             |
+| `<=`       | `value` precedes `against` or ranks equally                            |
+| `>`        | `value` follows `against`                                              |
+| `>=`       | `value` follows `against` or ranks equally                             |
+| `~`        | `value` is at least `against` and shares its major and minor           |
+| `^`        | `value` is at least `against` and keeps its left-most non-zero element |
+
+### `InvalidSemVerError`
+
+Error describing text that fails the SemVer 2.0.0 grammar. It arrives inside a `Failure` value.
+
+- `text`: `string` - The rejected text, kept verbatim for diagnostics
+- `name`: `string` - Always `"InvalidSemVerError"`
+- `message`: `string` - `Invalid version: "<text>"`, quoted so whitespace and empty strings stay visible in logs
+
+### Types
+
+#### `SemVer`
+
+```typescript
+interface SemVer {
+	major: number;
+	minor: number;
+	patch: number;
+	prerelease: string[];
+}
+```
+
+A version taken apart for precedence. `prerelease` holds the dot-separated identifiers after the `-` and is empty for a release. Build metadata is absent, so two versions differing only in it are the same `SemVer`.
+
+#### `SemVerComparison`
+
+```typescript
+type SemVerComparison = "=" | "!=" | "<" | "<=" | ">" | ">=" | "~" | "^";
+```
+
+The comparisons `satisfies()` accepts. It is a closed union, so an editor offers the eight as a list and a stored value round-trips through a schema.
+
+### Precedence Rules
+
+Versions compare element by element: major, then minor, then patch, each as a number rather than as text, so `1.10.0` follows `1.9.0`. Build metadata is ignored throughout.
+
+A version carrying a prerelease precedes the same version without one. Two prereleases compare identifier by identifier: numerically when both identifiers are numeric, by character otherwise, with a numeric identifier ranking below a textual one. When one list runs out while the other continues, the shorter one comes first, so `1.0.0-alpha` precedes `1.0.0-alpha.1`.
+
+## Pattern: Gating A Feature On A Client Version
+
+Store the comparison and the version as data, and let an operator edit the rule without a deploy.
+
+```typescript
+import type { SemVerComparison } from "@sdxc/semver";
+
+import { satisfies } from "@sdxc/semver";
+
+interface VersionRule {
+	comparison: SemVerComparison;
+	version: string;
+}
+
+function allows(rule: VersionRule, clientVersion: string): boolean {
+	return satisfies(clientVersion, rule.comparison, rule.version);
+}
+
+allows({ comparison: "^", version: "2.0.0" }, "2.4.1"); // true
+allows({ comparison: ">=", version: "3.0.0" }, "2.4.1"); // false
+```
+
+## Pattern: Picking The Newest Published Version
+
+Registries hand back whatever they hold, including placeholders and tags. Sorting with `compare()` needs no filtering pass first, because the newest version is the last entry either way.
+
+```typescript
+import { compare } from "@sdxc/semver";
+
+function newest(versions: string[]): string | undefined {
+	return [...versions].sort(compare).at(-1);
+}
+
+newest(["0.0.0-pre.1", "2026.9.4", "2026.10.1"]); // "2026.10.1"
+newest(["0.0.0-pre.9", "0.0.0-pre.10"]); // "0.0.0-pre.10"
+```
+
+## Pattern: Deciding Whether An Upgrade Is Breaking
+
+Parse both sides once and read the elements, when the question is about the shape of the change rather than about a threshold.
+
+```typescript
+import { parse } from "@sdxc/semver";
+import { isFailure } from "@sdxc/result";
+
+function isBreaking(from: string, to: string): boolean {
+	let before = parse(from);
+	let after = parse(to);
+
+	if (isFailure(before) || isFailure(after)) return true;
+	if (before.data.major !== 0) return after.data.major !== before.data.major;
+
+	return after.data.minor !== before.data.minor;
+}
+
+isBreaking("1.4.2", "1.9.0"); // false
+isBreaking("0.2.3", "0.3.0"); // true — below 1.0.0 the minor carries compatibility
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/semver": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/compare.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Total SemVer 2.0.0 ordering over version strings, so a list read from a
+ * registry or a tag listing sorts in one call even when some entry in it turns
+ * out to be something other than a version.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Order two version strings by SemVer 2.0.0 precedence, ready to hand to
+ * `Array.prototype.sort`. Text that is not a version ranks below every version
+ * and ties with other such text, which keeps the ordering total.
+ *
+ * @returns A negative number when `a` comes first, zero when the two rank equally.
+ *
+ * @example
+ * ["2026.10.1", "2026.9.4"].sort(compare); // ["2026.9.4", "2026.10.1"]
+ * @example
+ * compare("1.0.0-rc.1", "1.0.0"); // negative, a prerelease preceding its release
+ * @example
+ * ["1.0.0", "latest"].sort(compare); // ["latest", "1.0.0"]
+ */
+export declare function compare(a: string, b: string): number;

package/dist/compare.js

@@ -0,0 +1,34 @@
+/**
+ * Total SemVer 2.0.0 ordering over version strings, so a list read from a
+ * registry or a tag listing sorts in one call even when some entry in it turns
+ * out to be something other than a version.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure } from "@sdxc/result";
+import { parse } from "./parse.js";
+import { precedence } from "./precedence.js";
+/**
+ * Order two version strings by SemVer 2.0.0 precedence, ready to hand to
+ * `Array.prototype.sort`. Text that is not a version ranks below every version
+ * and ties with other such text, which keeps the ordering total.
+ *
+ * @returns A negative number when `a` comes first, zero when the two rank equally.
+ *
+ * @example
+ * ["2026.10.1", "2026.9.4"].sort(compare); // ["2026.9.4", "2026.10.1"]
+ * @example
+ * compare("1.0.0-rc.1", "1.0.0"); // negative, a prerelease preceding its release
+ * @example
+ * ["1.0.0", "latest"].sort(compare); // ["latest", "1.0.0"]
+ */
+export function compare(a, b) {
+    let left = parse(a);
+    let right = parse(b);
+    if (isFailure(left))
+        return isFailure(right) ? 0 : -1;
+    if (isFailure(right))
+        return 1;
+    return precedence(left.data, right.data);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public surface of the semver package: the version shape and the comparison
+ * union, strict SemVer 2.0.0 reading with its error, the total precedence
+ * ordering, and the eight comparisons one version can be tested against another.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { SemVer, SemVerComparison } from "./types.js";
+export { compare } from "./compare.js";
+export { InvalidSemVerError } from "./invalid-semver-error.js";
+export { parse } from "./parse.js";
+export { satisfies } from "./satisfies.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public surface of the semver package: the version shape and the comparison
+ * union, strict SemVer 2.0.0 reading with its error, the total precedence
+ * ordering, and the eight comparisons one version can be tested against another.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { compare } from "./compare.js";
+export { InvalidSemVerError } from "./invalid-semver-error.js";
+export { parse } from "./parse.js";
+export { satisfies } from "./satisfies.js";

package/dist/invalid-semver-error.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The failure value `parse()` reports for text SemVer 2.0.0 rejects. It keeps the
+ * offending text on the error so a version read from a registry, a tag or a user
+ * agent can be named in a log line.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Error describing text that fails the SemVer 2.0.0 grammar, delivered to
+ * callers inside a `Failure` value.
+ */
+export declare class InvalidSemVerError extends Error {
+    /** The rejected text, kept verbatim for diagnostics. */
+    readonly text: string;
+    /**
+     * Builds an error whose message quotes the rejected text, so whitespace and
+     * empty strings stay visible in logs.
+     *
+     * @param text - Text that did not match the SemVer 2.0.0 grammar.
+     */
+    constructor(text: string);
+}

package/dist/invalid-semver-error.js

@@ -0,0 +1,27 @@
+/**
+ * The failure value `parse()` reports for text SemVer 2.0.0 rejects. It keeps the
+ * offending text on the error so a version read from a registry, a tag or a user
+ * agent can be named in a log line.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Error describing text that fails the SemVer 2.0.0 grammar, delivered to
+ * callers inside a `Failure` value.
+ */
+export class InvalidSemVerError extends Error {
+    /** The rejected text, kept verbatim for diagnostics. */
+    text;
+    /**
+     * Builds an error whose message quotes the rejected text, so whitespace and
+     * empty strings stay visible in logs.
+     *
+     * @param text - Text that did not match the SemVer 2.0.0 grammar.
+     */
+    constructor(text) {
+        super(`Invalid version: ${JSON.stringify(text)}`);
+        this.name = "InvalidSemVerError";
+        this.text = text;
+    }
+}

package/dist/parse.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Strict SemVer 2.0.0 reading, the single gate every other export goes through
+ * so one grammar decides what counts as a version. Text arrives from registries,
+ * git tags and user agents, so a rejection is a `Result` failure instead of a throw.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { SemVer } from "./types.js";
+import { InvalidSemVerError } from "./invalid-semver-error.js";
+/**
+ * Read a version string into its elements, accepting an optional leading `v` and
+ * dropping build metadata, which SemVer 2.0.0 excludes from precedence.
+ *
+ * @param text - Text to read, e.g. a version served by a registry.
+ * @returns The version's elements, or an `InvalidSemVerError` naming the rejected text.
+ *
+ * @example
+ * parse("v1.2.3"); // { status: "success", data: { major: 1, minor: 2, patch: 3, prerelease: [] } }
+ * @example
+ * parse("1.2"); // { status: "failure", error: InvalidSemVerError }
+ */
+export declare function parse(text: string): Result<SemVer, InvalidSemVerError>;

package/dist/parse.js

@@ -0,0 +1,39 @@
+/**
+ * Strict SemVer 2.0.0 reading, the single gate every other export goes through
+ * so one grammar decides what counts as a version. Text arrives from registries,
+ * git tags and user agents, so a rejection is a `Result` failure instead of a throw.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { InvalidSemVerError } from "./invalid-semver-error.js";
+/**
+ * SemVer 2.0.0, with the `v` a git tag or a user agent tends to carry in front
+ * of it. Each core element is canonical, so a padded `01.2.3` is rejected rather
+ * than silently read as `1.2.3`.
+ */
+const VERSION = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][\da-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][\da-zA-Z-]*))*))?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?$/;
+/**
+ * Read a version string into its elements, accepting an optional leading `v` and
+ * dropping build metadata, which SemVer 2.0.0 excludes from precedence.
+ *
+ * @param text - Text to read, e.g. a version served by a registry.
+ * @returns The version's elements, or an `InvalidSemVerError` naming the rejected text.
+ *
+ * @example
+ * parse("v1.2.3"); // { status: "success", data: { major: 1, minor: 2, patch: 3, prerelease: [] } }
+ * @example
+ * parse("1.2"); // { status: "failure", error: InvalidSemVerError }
+ */
+export function parse(text) {
+    let match = VERSION.exec(text);
+    if (match === null)
+        return failure(new InvalidSemVerError(text));
+    return success({
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] === undefined ? [] : match[4].split("."),
+    });
+}

package/dist/precedence.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SemVer 2.0.0 precedence over already-parsed versions, shared by the string
+ * ordering and by the comparison set so both answer from one definition of which
+ * version comes first.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { SemVer } from "./types.js";
+/**
+ * Order two parsed versions: the core elements first, then the prerelease, with a
+ * prerelease ranking below the release it leads to.
+ *
+ * @returns A negative number when `left` comes first, zero when the two rank equally.
+ */
+export declare function precedence(left: SemVer, right: SemVer): number;

package/dist/precedence.js

@@ -0,0 +1,56 @@
+/**
+ * SemVer 2.0.0 precedence over already-parsed versions, shared by the string
+ * ordering and by the comparison set so both answer from one definition of which
+ * version comes first.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** A whole numeric identifier, which sorts by value where a textual one sorts by character. */
+const NUMERIC = /^\d+$/;
+/**
+ * Order two parsed versions: the core elements first, then the prerelease, with a
+ * prerelease ranking below the release it leads to.
+ *
+ * @returns A negative number when `left` comes first, zero when the two rank equally.
+ */
+export function precedence(left, right) {
+    if (left.major !== right.major)
+        return left.major - right.major;
+    if (left.minor !== right.minor)
+        return left.minor - right.minor;
+    if (left.patch !== right.patch)
+        return left.patch - right.patch;
+    if (left.prerelease.length === 0 && right.prerelease.length === 0)
+        return 0;
+    if (left.prerelease.length === 0)
+        return 1;
+    if (right.prerelease.length === 0)
+        return -1;
+    return comparePrerelease(left.prerelease, right.prerelease);
+}
+/**
+ * Compare prerelease identifiers pairwise: numerically where both are numeric, by
+ * character otherwise, with a numeric identifier ranking below a textual one. A
+ * list that runs out first ranks below the one that continues.
+ */
+function comparePrerelease(left, right) {
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        let one = left[index];
+        let other = right[index];
+        if (one === undefined)
+            return -1;
+        if (other === undefined)
+            return 1;
+        if (one === other)
+            continue;
+        if (NUMERIC.test(one) && NUMERIC.test(other))
+            return Number(one) - Number(other);
+        if (NUMERIC.test(one))
+            return -1;
+        if (NUMERIC.test(other))
+            return 1;
+        return one < other ? -1 : 1;
+    }
+    return 0;
+}

package/dist/satisfies.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The eight comparisons one version can be asked to stand in against another,
+ * covering what a rollout rule or a compatibility check needs without the range
+ * grammar and its parser.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { SemVerComparison } from "./types.js";
+/**
+ * Answer whether `value` stands in the named relation to `against`. A prerelease
+ * takes part by precedence alone, so `1.2.4-rc.1` satisfies `^ 1.2.3`. Either
+ * side that is not a version answers `false`, matching nothing rather than failing.
+ *
+ * @param value - The version being tested, e.g. one read from a request.
+ * @param comparison - Which relation must hold.
+ * @param against - The version the rule was written against.
+ *
+ * @example
+ * satisfies("1.4.0", "~", "1.4.2"); // false
+ * @example
+ * satisfies("1.9.0", "^", "1.4.2"); // true
+ * @example
+ * satisfies("nightly", ">", "1.0.0"); // false
+ */
+export declare function satisfies(value: string, comparison: SemVerComparison, against: string): boolean;

package/dist/satisfies.js

@@ -0,0 +1,68 @@
+/**
+ * The eight comparisons one version can be asked to stand in against another,
+ * covering what a rollout rule or a compatibility check needs without the range
+ * grammar and its parser.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure } from "@sdxc/result";
+import { parse } from "./parse.js";
+import { precedence } from "./precedence.js";
+/**
+ * Answer whether `value` stands in the named relation to `against`. A prerelease
+ * takes part by precedence alone, so `1.2.4-rc.1` satisfies `^ 1.2.3`. Either
+ * side that is not a version answers `false`, matching nothing rather than failing.
+ *
+ * @param value - The version being tested, e.g. one read from a request.
+ * @param comparison - Which relation must hold.
+ * @param against - The version the rule was written against.
+ *
+ * @example
+ * satisfies("1.4.0", "~", "1.4.2"); // false
+ * @example
+ * satisfies("1.9.0", "^", "1.4.2"); // true
+ * @example
+ * satisfies("nightly", ">", "1.0.0"); // false
+ */
+export function satisfies(value, comparison, against) {
+    let left = parse(value);
+    let right = parse(against);
+    if (isFailure(left) || isFailure(right))
+        return false;
+    let order = precedence(left.data, right.data);
+    switch (comparison) {
+        case "=":
+            return order === 0;
+        case "!=":
+            return order !== 0;
+        case "<":
+            return order < 0;
+        case "<=":
+            return order <= 0;
+        case ">":
+            return order > 0;
+        case ">=":
+            return order >= 0;
+        case "~":
+            return order >= 0 && sharesMinor(left.data, right.data);
+        case "^":
+            return order >= 0 && sharesLeadingElement(left.data, right.data);
+    }
+}
+/** Holds when `left` sits in the same minor series `right` names, which is the width of a `~`. */
+function sharesMinor(left, right) {
+    return left.major === right.major && left.minor === right.minor;
+}
+/**
+ * Holds when `left` keeps the element `right` stakes its compatibility on — the
+ * major, or for a `0.x` version the minor, or for a `0.0.x` version the patch —
+ * which is what makes `^0.2.3` exclude `0.3.0`.
+ */
+function sharesLeadingElement(left, right) {
+    if (right.major !== 0)
+        return left.major === right.major;
+    if (right.minor !== 0)
+        return left.major === 0 && left.minor === right.minor;
+    return left.major === 0 && left.minor === 0 && left.patch === right.patch;
+}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The shapes the package speaks in: a version taken apart for precedence, and
+ * the closed set of comparisons one version can be asked to stand in against
+ * another.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * A version taken apart for precedence. Build metadata carries no precedence, so
+ * a parsed version keeps none of it and two versions differing only in build
+ * metadata rank equally.
+ */
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    /** The dot-separated identifiers after the `-`, empty for a release. */
+    prerelease: string[];
+}
+/**
+ * The comparisons available without range syntax, small enough that an editor
+ * can render it as a list: `~` holds within one minor, `^` within the left-most
+ * non-zero element.
+ */
+export type SemVerComparison = "=" | "!=" | "<" | "<=" | ">" | ">=" | "~" | "^";

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * The shapes the package speaks in: a version taken apart for precedence, and
+ * the closed set of comparisons one version can be asked to stand in against
+ * another.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */

package/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "@sdxc/semver",
+	"version": "0.0.0-pre.1",
+	"description": "SemVer 2.0.0 parsing, precedence ordering and range-free version comparisons",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/result": "2026.9.11"
+	},
+	"gitHead": "d56f75a79171aab3be101d8fa624d51972cd6028",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/semver"
+	}
+}