@start9labs/start-sdk 0.4.0-beta.8 → 0.4.0

package/base/lib/exver/index.js

@@ -67,8 +67,8 @@ function adjacentVersionRangePoints(a, b) {
     return a.side == -1 && b.side == 1;
 }
 function flavorAnd(a, b) {
-    if (a.type == "Flavor") {
-        if (b.type == "Flavor") {
+    if (a.type == 'Flavor') {
+        if (b.type == 'Flavor') {
             if (a.flavor == b.flavor) {
                 return a;
             }
@@ -86,7 +86,7 @@ function flavorAnd(a, b) {
         }
     }
     else {
-        if (b.type == "Flavor") {
+        if (b.type == 'Flavor') {
             if (a.flavors.has(b.flavor)) {
                 return null;
             }
@@ -97,7 +97,7 @@ function flavorAnd(a, b) {
         else {
             // TODO: use Set.union if targeting esnext or later
             return {
-                type: "FlavorNot",
+                type: 'FlavorNot',
                 flavors: new Set([...a.flavors, ...b.flavors]),
             };
         }
@@ -173,12 +173,12 @@ class VersionRangeTable {
     static eqFlavor(flavor) {
         return new deep_equality_data_structures_1.DeepMap([
             [
-                { type: "Flavor", flavor },
+                { type: 'Flavor', flavor },
                 new VersionRangeTable([], [true]),
             ],
             // make sure the truth table is exhaustive, or `not` will not work properly.
             [
-                { type: "FlavorNot", flavors: new Set([flavor]) },
+                { type: 'FlavorNot', flavors: new Set([flavor]) },
                 new VersionRangeTable([], [false]),
             ],
         ]);
@@ -190,12 +190,12 @@ class VersionRangeTable {
     static cmpPoint(flavor, point, left, right) {
         return new deep_equality_data_structures_1.DeepMap([
             [
-                { type: "Flavor", flavor },
+                { type: 'Flavor', flavor },
                 new VersionRangeTable([point], [left, right]),
             ],
             // make sure the truth table is exhaustive, or `not` will not work properly.
             [
-                { type: "FlavorNot", flavors: new Set([flavor]) },
+                { type: 'FlavorNot', flavors: new Set([flavor]) },
                 new VersionRangeTable([], [false]),
             ],
         ]);
@@ -311,7 +311,7 @@ class VersionRangeTable {
         let sum_terms = [];
         for (let [flavor, table] of tables) {
             let cmp_flavor = null;
-            if (flavor.type == "Flavor") {
+            if (flavor.type == 'Flavor') {
                 cmp_flavor = flavor.flavor;
             }
             for (let i = 0; i < table.values.length; i++) {
@@ -319,7 +319,7 @@ class VersionRangeTable {
                 if (!table.values[i]) {
                     continue;
                 }
-                if (flavor.type == "FlavorNot") {
+                if (flavor.type == 'FlavorNot') {
                     for (let not_flavor of flavor.flavors) {
                         term.push(VersionRange.flavor(not_flavor).not());
                     }
@@ -333,20 +333,20 @@ class VersionRangeTable {
                     q = table.points[i];
                 }
                 if (p != null && q != null && adjacentVersionRangePoints(p, q)) {
-                    term.push(VersionRange.anchor("=", new ExtendedVersion(cmp_flavor, p.upstream, p.downstream)));
+                    term.push(VersionRange.anchor('=', new ExtendedVersion(cmp_flavor, p.upstream, p.downstream)));
                 }
                 else {
                     if (p != null && p.side < 0) {
-                        term.push(VersionRange.anchor(">=", new ExtendedVersion(cmp_flavor, p.upstream, p.downstream)));
+                        term.push(VersionRange.anchor('>=', new ExtendedVersion(cmp_flavor, p.upstream, p.downstream)));
                     }
                     if (p != null && p.side >= 0) {
-                        term.push(VersionRange.anchor(">", new ExtendedVersion(cmp_flavor, p.upstream, p.downstream)));
+                        term.push(VersionRange.anchor('>', new ExtendedVersion(cmp_flavor, p.upstream, p.downstream)));
                     }
                     if (q != null && q.side < 0) {
-                        term.push(VersionRange.anchor("<", new ExtendedVersion(cmp_flavor, q.upstream, q.downstream)));
+                        term.push(VersionRange.anchor('<', new ExtendedVersion(cmp_flavor, q.upstream, q.downstream)));
                     }
                     if (q != null && q.side >= 0) {
-                        term.push(VersionRange.anchor("<=", new ExtendedVersion(cmp_flavor, q.upstream, q.downstream)));
+                        term.push(VersionRange.anchor('<=', new ExtendedVersion(cmp_flavor, q.upstream, q.downstream)));
                     }
                 }
                 if (term.length == 0) {
@@ -358,6 +358,28 @@ class VersionRangeTable {
         return VersionRange.or(...sum_terms);
     }
 }
+/**
+ * Represents a parsed version range expression used to match against {@link Version} or {@link ExtendedVersion} values.
+ *
+ * Version ranges support standard comparison operators (`=`, `>`, `<`, `>=`, `<=`, `!=`),
+ * caret (`^`) and tilde (`~`) ranges, boolean logic (`&&`, `||`, `!`), and flavor matching (`#flavor`).
+ *
+ * @example
+ * ```ts
+ * const range = VersionRange.parse(">=1.0.0:0 && <2.0.0:0")
+ * const version = ExtendedVersion.parse("1.5.0:0")
+ * console.log(range.satisfiedBy(version)) // true
+ *
+ * // Combine ranges with boolean logic
+ * const combined = VersionRange.and(
+ *   VersionRange.parse(">=1.0:0"),
+ *   VersionRange.parse("<3.0:0"),
+ * )
+ *
+ * // Match a specific flavor
+ * const flavored = VersionRange.parse("#bitcoin")
+ * ```
+ */
 class VersionRange {
     constructor(atom) {
         this.atom = atom;
@@ -365,61 +387,62 @@ class VersionRange {
     toStringParens(parent) {
         let needs = true;
         switch (this.atom.type) {
-            case "And":
-            case "Or":
+            case 'And':
+            case 'Or':
                 needs = parent != this.atom.type;
                 break;
-            case "Anchor":
-            case "Any":
-            case "None":
-                needs = parent == "Not";
+            case 'Anchor':
+            case 'Any':
+            case 'None':
+                needs = parent == 'Not';
                 break;
-            case "Not":
-            case "Flavor":
+            case 'Not':
+            case 'Flavor':
                 needs = false;
                 break;
         }
         if (needs) {
-            return "(" + this.toString() + ")";
+            return '(' + this.toString() + ')';
         }
         else {
             return this.toString();
         }
     }
+    /** Serializes this version range back to its canonical string representation. */
     toString() {
         switch (this.atom.type) {
-            case "Anchor":
+            case 'Anchor':
                 return `${this.atom.operator}${this.atom.version}`;
-            case "And":
+            case 'And':
                 return `${this.atom.left.toStringParens(this.atom.type)} && ${this.atom.right.toStringParens(this.atom.type)}`;
-            case "Or":
+            case 'Or':
                 return `${this.atom.left.toStringParens(this.atom.type)} || ${this.atom.right.toStringParens(this.atom.type)}`;
-            case "Not":
+            case 'Not':
                 return `!${this.atom.value.toStringParens(this.atom.type)}`;
-            case "Flavor":
+            case 'Flavor':
                 return this.atom.flavor == null ? `#` : `#${this.atom.flavor}`;
-            case "Any":
-                return "*";
-            case "None":
-                return "!";
+            case 'Any':
+                return '*';
+            case 'None':
+                return '!';
         }
     }
     static parseAtom(atom) {
         switch (atom.type) {
-            case "Not":
+            case 'Not':
                 return new VersionRange({
-                    type: "Not",
+                    type: 'Not',
                     value: VersionRange.parseAtom(atom.value),
                 });
-            case "Parens":
+            case 'Parens':
                 return VersionRange.parseRange(atom.expr);
-            case "Anchor":
+            case 'Anchor':
                 return new VersionRange({
-                    type: "Anchor",
-                    operator: atom.operator || "^",
+                    type: 'Anchor',
+                    operator: atom.operator || '^',
                     version: new ExtendedVersion(atom.version.flavor, new Version(atom.version.upstream.number, atom.version.upstream.prerelease), new Version(atom.version.downstream.number, atom.version.downstream.prerelease)),
                 });
-            case "Flavor":
+            case 'Flavor':
                 return VersionRange.flavor(atom.flavor);
             default:
                 return new VersionRange(atom);
@@ -429,17 +452,17 @@ class VersionRange {
         let result = VersionRange.parseAtom(range[0]);
         for (const next of range[1]) {
             switch (next[1]?.[0]) {
-                case "||":
+                case '||':
                     result = new VersionRange({
-                        type: "Or",
+                        type: 'Or',
                         left: result,
                         right: VersionRange.parseAtom(next[2]),
                     });
                     break;
-                case "&&":
+                case '&&':
                 default:
                     result = new VersionRange({
-                        type: "And",
+                        type: 'And',
                         left: result,
                         right: VersionRange.parseAtom(next[2]),
                     });
@@ -448,257 +471,407 @@ class VersionRange {
         }
         return result;
     }
+    /**
+     * Parses a version range string into a `VersionRange`.
+     *
+     * @param range - A version range expression, e.g. `">=1.0.0:0 && <2.0.0:0"`, `"^1.2:0"`, `"*"`
+     * @returns The parsed `VersionRange`
+     * @throws If the string is not a valid version range expression
+     */
     static parse(range) {
-        return VersionRange.parseRange(P.parse(range, { startRule: "VersionRange" }));
+        return VersionRange.parseRange(P.parse(range, { startRule: 'VersionRange' }));
     }
+    /**
+     * Creates a version range from a comparison operator and an {@link ExtendedVersion}.
+     *
+     * @param operator - One of `"="`, `">"`, `"<"`, `">="`, `"<="`, `"!="`, `"^"`, `"~"`
+     * @param version - The version to compare against
+     */
     static anchor(operator, version) {
-        return new VersionRange({ type: "Anchor", operator, version });
+        return new VersionRange({ type: 'Anchor', operator, version });
     }
+    /**
+     * Creates a version range that matches only versions with the specified flavor.
+     *
+     * @param flavor - The flavor string to match, or `null` for the default (unflavored) variant
+     */
     static flavor(flavor) {
-        return new VersionRange({ type: "Flavor", flavor });
+        return new VersionRange({ type: 'Flavor', flavor });
     }
+    /**
+     * Parses a legacy "emver" format version range string.
+     *
+     * @param range - A version range in the legacy emver format
+     * @returns The parsed `VersionRange`
+     */
     static parseEmver(range) {
-        return VersionRange.parseRange(P.parse(range, { startRule: "EmverVersionRange" }));
+        return VersionRange.parseRange(P.parse(range, { startRule: 'EmverVersionRange' }));
     }
+    /** Returns the intersection of this range with another (logical AND). */
     and(right) {
-        return new VersionRange({ type: "And", left: this, right });
+        return new VersionRange({ type: 'And', left: this, right });
     }
+    /** Returns the union of this range with another (logical OR). */
     or(right) {
-        return new VersionRange({ type: "Or", left: this, right });
+        return new VersionRange({ type: 'Or', left: this, right });
     }
+    /** Returns the negation of this range (logical NOT). */
     not() {
-        return new VersionRange({ type: "Not", value: this });
+        return new VersionRange({ type: 'Not', value: this });
     }
+    /**
+     * Returns the logical AND (intersection) of multiple version ranges.
+     * Short-circuits on `none()` and skips `any()`.
+     */
     static and(...xs) {
         let y = VersionRange.any();
         for (let x of xs) {
-            if (x.atom.type == "Any") {
+            if (x.atom.type == 'Any') {
                 continue;
             }
-            if (x.atom.type == "None") {
+            if (x.atom.type == 'None') {
                 return x;
             }
-            if (y.atom.type == "Any") {
+            if (y.atom.type == 'Any') {
                 y = x;
             }
             else {
-                y = new VersionRange({ type: "And", left: y, right: x });
+                y = new VersionRange({ type: 'And', left: y, right: x });
             }
         }
         return y;
     }
+    /**
+     * Returns the logical OR (union) of multiple version ranges.
+     * Short-circuits on `any()` and skips `none()`.
+     */
     static or(...xs) {
         let y = VersionRange.none();
         for (let x of xs) {
-            if (x.atom.type == "None") {
+            if (x.atom.type == 'None') {
                 continue;
             }
-            if (x.atom.type == "Any") {
+            if (x.atom.type == 'Any') {
                 return x;
             }
-            if (y.atom.type == "None") {
+            if (y.atom.type == 'None') {
                 y = x;
             }
             else {
-                y = new VersionRange({ type: "Or", left: y, right: x });
+                y = new VersionRange({ type: 'Or', left: y, right: x });
             }
         }
         return y;
     }
+    /** Returns a version range that matches all versions (wildcard `*`). */
     static any() {
-        return new VersionRange({ type: "Any" });
+        return new VersionRange({ type: 'Any' });
     }
+    /** Returns a version range that matches no versions (`!`). */
     static none() {
-        return new VersionRange({ type: "None" });
+        return new VersionRange({ type: 'None' });
     }
+    /**
+     * Returns `true` if the given version satisfies this range.
+     *
+     * @param version - A {@link Version} or {@link ExtendedVersion} to test
+     */
     satisfiedBy(version) {
         return version.satisfies(this);
     }
     tables() {
         switch (this.atom.type) {
-            case "Anchor":
+            case 'Anchor':
                 switch (this.atom.operator) {
-                    case "=":
+                    case '=':
                         // `=1.2.3` is equivalent to `>=1.2.3 && <=1.2.4 && #flavor`
                         return VersionRangeTable.and(VersionRangeTable.cmp(this.atom.version, -1, false, true), VersionRangeTable.cmp(this.atom.version, 1, true, false));
-                    case ">":
+                    case '>':
                         return VersionRangeTable.cmp(this.atom.version, 1, false, true);
-                    case "<":
+                    case '<':
                         return VersionRangeTable.cmp(this.atom.version, -1, true, false);
-                    case ">=":
+                    case '>=':
                         return VersionRangeTable.cmp(this.atom.version, -1, false, true);
-                    case "<=":
+                    case '<=':
                         return VersionRangeTable.cmp(this.atom.version, 1, true, false);
-                    case "!=":
+                    case '!=':
                         // `!=1.2.3` is equivalent to `!(>=1.2.3 && <=1.2.3 && #flavor)`
                         // **not** equivalent to `(<1.2.3 || >1.2.3) && #flavor`
                         return VersionRangeTable.not(VersionRangeTable.and(VersionRangeTable.cmp(this.atom.version, -1, false, true), VersionRangeTable.cmp(this.atom.version, 1, true, false)));
-                    case "^":
+                    case '^':
                         // `^1.2.3` is equivalent to `>=1.2.3 && <2.0.0 && #flavor`
                         return VersionRangeTable.and(VersionRangeTable.cmp(this.atom.version, -1, false, true), VersionRangeTable.cmp(this.atom.version.incrementMajor(), -1, true, false));
-                    case "~":
+                    case '~':
                         // `~1.2.3` is equivalent to `>=1.2.3 && <1.3.0 && #flavor`
                         return VersionRangeTable.and(VersionRangeTable.cmp(this.atom.version, -1, false, true), VersionRangeTable.cmp(this.atom.version.incrementMinor(), -1, true, false));
                 }
-            case "Flavor":
+            case 'Flavor':
                 return VersionRangeTable.eqFlavor(this.atom.flavor);
-            case "Not":
+            case 'Not':
                 return VersionRangeTable.not(this.atom.value.tables());
-            case "And":
+            case 'And':
                 return VersionRangeTable.and(this.atom.left.tables(), this.atom.right.tables());
-            case "Or":
+            case 'Or':
                 return VersionRangeTable.or(this.atom.left.tables(), this.atom.right.tables());
-            case "Any":
+            case 'Any':
                 return true;
-            case "None":
+            case 'None':
                 return false;
         }
     }
+    /** Returns `true` if any version exists that could satisfy this range. */
     satisfiable() {
         return VersionRangeTable.collapse(this.tables()) !== false;
     }
+    /** Returns `true` if this range and `other` share at least one satisfying version. */
     intersects(other) {
         return VersionRange.and(this, other).satisfiable();
     }
+    /**
+     * Returns a canonical (simplified) form of this range using minterm expansion.
+     * Useful for normalizing complex boolean expressions into a minimal representation.
+     */
     normalize() {
         return VersionRangeTable.minterms(this.tables());
     }
 }
 exports.VersionRange = VersionRange;
+/**
+ * Represents a semantic version number with numeric segments and optional prerelease identifiers.
+ *
+ * Follows semver precedence rules: numeric segments are compared left-to-right,
+ * and a version with prerelease identifiers has lower precedence than the same version without.
+ *
+ * @example
+ * ```ts
+ * const v = Version.parse("1.2.3")
+ * console.log(v.toString())             // "1.2.3"
+ * console.log(v.compare(Version.parse("1.3.0"))) // "less"
+ *
+ * const pre = Version.parse("2.0.0-beta.1")
+ * console.log(pre.compare(Version.parse("2.0.0"))) // "less" (prerelease < release)
+ * ```
+ */
 class Version {
-    constructor(number, prerelease) {
+    constructor(
+    /** The numeric version segments (e.g. `[1, 2, 3]` for `"1.2.3"`). */
+    number, 
+    /** Optional prerelease identifiers (e.g. `["beta", 1]` for `"-beta.1"`). */
+    prerelease) {
         this.number = number;
         this.prerelease = prerelease;
     }
+    /** Serializes this version to its string form (e.g. `"1.2.3"` or `"1.0.0-beta.1"`). */
     toString() {
-        return `${this.number.join(".")}${this.prerelease.length > 0 ? `-${this.prerelease.join(".")}` : ""}`;
+        return `${this.number.join('.')}${this.prerelease.length > 0 ? `-${this.prerelease.join('.')}` : ''}`;
     }
+    /**
+     * Compares this version against another using semver precedence rules.
+     *
+     * @param other - The version to compare against
+     * @returns `'greater'`, `'equal'`, or `'less'`
+     */
     compare(other) {
         const numLen = Math.max(this.number.length, other.number.length);
         for (let i = 0; i < numLen; i++) {
             if ((this.number[i] || 0) > (other.number[i] || 0)) {
-                return "greater";
+                return 'greater';
             }
             else if ((this.number[i] || 0) < (other.number[i] || 0)) {
-                return "less";
+                return 'less';
             }
         }
         if (this.prerelease.length === 0 && other.prerelease.length !== 0) {
-            return "greater";
+            return 'greater';
         }
         else if (this.prerelease.length !== 0 && other.prerelease.length === 0) {
-            return "less";
+            return 'less';
         }
-        const prereleaseLen = Math.max(this.number.length, other.number.length);
+        const prereleaseLen = Math.max(this.prerelease.length, other.prerelease.length);
         for (let i = 0; i < prereleaseLen; i++) {
             if (typeof this.prerelease[i] === typeof other.prerelease[i]) {
                 if (this.prerelease[i] > other.prerelease[i]) {
-                    return "greater";
+                    return 'greater';
                 }
                 else if (this.prerelease[i] < other.prerelease[i]) {
-                    return "less";
+                    return 'less';
                 }
             }
             else {
                 switch (`${typeof this.prerelease[1]}:${typeof other.prerelease[i]}`) {
-                    case "number:string":
-                        return "less";
-                    case "string:number":
-                        return "greater";
-                    case "number:undefined":
-                    case "string:undefined":
-                        return "greater";
-                    case "undefined:number":
-                    case "undefined:string":
-                        return "less";
+                    case 'number:string':
+                        return 'less';
+                    case 'string:number':
+                        return 'greater';
+                    case 'number:undefined':
+                    case 'string:undefined':
+                        return 'greater';
+                    case 'undefined:number':
+                    case 'undefined:string':
+                        return 'less';
                 }
             }
         }
-        return "equal";
+        return 'equal';
     }
+    /**
+     * Compares two versions, returning a numeric value suitable for use with `Array.sort()`.
+     *
+     * @returns `-1` if less, `0` if equal, `1` if greater
+     */
     compareForSort(other) {
         switch (this.compare(other)) {
-            case "greater":
+            case 'greater':
                 return 1;
-            case "equal":
+            case 'equal':
                 return 0;
-            case "less":
+            case 'less':
                 return -1;
         }
     }
+    /**
+     * Parses a version string into a `Version` instance.
+     *
+     * @param version - A semver-compatible string, e.g. `"1.2.3"` or `"1.0.0-beta.1"`
+     * @throws If the string is not a valid version
+     */
     static parse(version) {
-        const parsed = P.parse(version, { startRule: "Version" });
+        const parsed = P.parse(version, { startRule: 'Version' });
         return new Version(parsed.number, parsed.prerelease);
     }
+    /**
+     * Returns `true` if this version satisfies the given {@link VersionRange}.
+     * Internally treats this as an unflavored {@link ExtendedVersion} with downstream `0`.
+     */
     satisfies(versionRange) {
         return new ExtendedVersion(null, this, new Version([0], [])).satisfies(versionRange);
     }
 }
 exports.Version = Version;
-// #flavor:0.1.2-beta.1:0
+/**
+ * Represents an extended version with an optional flavor, an upstream version, and a downstream version.
+ *
+ * The format is `#flavor:upstream:downstream` (e.g. `#bitcoin:1.2.3:0`) or `upstream:downstream`
+ * for unflavored versions. Flavors allow multiple variants of a package to coexist.
+ *
+ * - **flavor**: An optional string identifier for the variant (e.g. `"bitcoin"`, `"litecoin"`)
+ * - **upstream**: The version of the upstream software being packaged
+ * - **downstream**: The version of the StartOS packaging itself
+ *
+ * Versions with different flavors are incomparable (comparison returns `null`).
+ *
+ * @example
+ * ```ts
+ * const v = ExtendedVersion.parse("#bitcoin:1.2.3:0")
+ * console.log(v.flavor)      // "bitcoin"
+ * console.log(v.upstream)    // Version { number: [1, 2, 3] }
+ * console.log(v.downstream)  // Version { number: [0] }
+ * console.log(v.toString())  // "#bitcoin:1.2.3:0"
+ *
+ * const range = VersionRange.parse(">=1.0.0:0")
+ * console.log(v.satisfies(range)) // true
+ * ```
+ */
 class ExtendedVersion {
-    constructor(flavor, upstream, downstream) {
+    constructor(
+    /** The flavor identifier (e.g. `"bitcoin"`), or `null` for unflavored versions. */
+    flavor, 
+    /** The upstream software version. */
+    upstream, 
+    /** The downstream packaging version. */
+    downstream) {
         this.flavor = flavor;
         this.upstream = upstream;
         this.downstream = downstream;
     }
+    /** Serializes this extended version to its string form (e.g. `"#bitcoin:1.2.3:0"` or `"1.0.0:1"`). */
     toString() {
-        return `${this.flavor ? `#${this.flavor}:` : ""}${this.upstream.toString()}:${this.downstream.toString()}`;
+        return `${this.flavor ? `#${this.flavor}:` : ''}${this.upstream.toString()}:${this.downstream.toString()}`;
     }
+    /**
+     * Compares this extended version against another.
+     *
+     * @returns `'greater'`, `'equal'`, `'less'`, or `null` if the flavors differ (incomparable)
+     */
     compare(other) {
         if (this.flavor !== other.flavor) {
             return null;
         }
         const upstreamCmp = this.upstream.compare(other.upstream);
-        if (upstreamCmp !== "equal") {
+        if (upstreamCmp !== 'equal') {
             return upstreamCmp;
         }
         return this.downstream.compare(other.downstream);
     }
+    /**
+     * Lexicographic comparison — compares flavors alphabetically first, then versions.
+     * Unlike {@link compare}, this never returns `null`: different flavors are ordered alphabetically.
+     */
     compareLexicographic(other) {
-        if ((this.flavor || "") > (other.flavor || "")) {
-            return "greater";
+        if ((this.flavor || '') > (other.flavor || '')) {
+            return 'greater';
         }
-        else if ((this.flavor || "") > (other.flavor || "")) {
-            return "less";
+        else if ((this.flavor || '') > (other.flavor || '')) {
+            return 'less';
         }
         else {
             return this.compare(other);
         }
     }
+    /**
+     * Returns a numeric comparison result suitable for use with `Array.sort()`.
+     * Uses lexicographic ordering (flavors sorted alphabetically, then by version).
+     */
     compareForSort(other) {
         switch (this.compareLexicographic(other)) {
-            case "greater":
+            case 'greater':
                 return 1;
-            case "equal":
+            case 'equal':
                 return 0;
-            case "less":
+            case 'less':
                 return -1;
         }
     }
+    /** Returns `true` if this version is strictly greater than `other`. Returns `false` if flavors differ. */
     greaterThan(other) {
-        return this.compare(other) === "greater";
+        return this.compare(other) === 'greater';
     }
+    /** Returns `true` if this version is greater than or equal to `other`. Returns `false` if flavors differ. */
     greaterThanOrEqual(other) {
-        return ["greater", "equal"].includes(this.compare(other));
+        return ['greater', 'equal'].includes(this.compare(other));
     }
+    /** Returns `true` if this version equals `other` (same flavor, upstream, and downstream). */
     equals(other) {
-        return this.compare(other) === "equal";
+        return this.compare(other) === 'equal';
     }
+    /** Returns `true` if this version is strictly less than `other`. Returns `false` if flavors differ. */
     lessThan(other) {
-        return this.compare(other) === "less";
+        return this.compare(other) === 'less';
     }
+    /** Returns `true` if this version is less than or equal to `other`. Returns `false` if flavors differ. */
     lessThanOrEqual(other) {
-        return ["less", "equal"].includes(this.compare(other));
+        return ['less', 'equal'].includes(this.compare(other));
     }
+    /**
+     * Parses an extended version string into an `ExtendedVersion`.
+     *
+     * @param extendedVersion - A string like `"1.2.3:0"` or `"#bitcoin:1.0.0:0"`
+     * @throws If the string is not a valid extended version
+     */
     static parse(extendedVersion) {
-        const parsed = P.parse(extendedVersion, { startRule: "ExtendedVersion" });
-        return new ExtendedVersion(parsed.flavor, new Version(parsed.upstream.number, parsed.upstream.prerelease), new Version(parsed.downstream.number, parsed.downstream.prerelease));
+        const parsed = P.parse(extendedVersion, { startRule: 'ExtendedVersion' });
+        return new ExtendedVersion(parsed.flavor || null, new Version(parsed.upstream.number, parsed.upstream.prerelease), new Version(parsed.downstream.number, parsed.downstream.prerelease));
     }
+    /**
+     * Parses a legacy "emver" format extended version string.
+     *
+     * @param extendedVersion - A version string in the legacy emver format
+     * @throws If the string is not a valid emver version (error message includes the input string)
+     */
     static parseEmver(extendedVersion) {
         try {
-            const parsed = P.parse(extendedVersion, { startRule: "Emver" });
-            return new ExtendedVersion(parsed.flavor, new Version(parsed.upstream.number, parsed.upstream.prerelease), new Version(parsed.downstream.number, parsed.downstream.prerelease));
+            const parsed = P.parse(extendedVersion, { startRule: 'Emver' });
+            return new ExtendedVersion(parsed.flavor || null, new Version(parsed.upstream.number, parsed.upstream.prerelease), new Version(parsed.downstream.number, parsed.downstream.prerelease));
         }
         catch (e) {
             if (e instanceof Error) {
@@ -754,22 +927,22 @@ class ExtendedVersion {
      */
     satisfies(versionRange) {
         switch (versionRange.atom.type) {
-            case "Anchor":
+            case 'Anchor':
                 const otherVersion = versionRange.atom.version;
                 switch (versionRange.atom.operator) {
-                    case "=":
+                    case '=':
                         return this.equals(otherVersion);
-                    case ">":
+                    case '>':
                         return this.greaterThan(otherVersion);
-                    case "<":
+                    case '<':
                         return this.lessThan(otherVersion);
-                    case ">=":
+                    case '>=':
                         return this.greaterThanOrEqual(otherVersion);
-                    case "<=":
+                    case '<=':
                         return this.lessThanOrEqual(otherVersion);
-                    case "!=":
+                    case '!=':
                         return !this.equals(otherVersion);
-                    case "^":
+                    case '^':
                         const nextMajor = versionRange.atom.version.incrementMajor();
                         if (this.greaterThanOrEqual(otherVersion) &&
                             this.lessThan(nextMajor)) {
@@ -778,7 +951,7 @@ class ExtendedVersion {
                         else {
                             return false;
                         }
-                    case "~":
+                    case '~':
                         const nextMinor = versionRange.atom.version.incrementMinor();
                         if (this.greaterThanOrEqual(otherVersion) &&
                             this.lessThan(nextMinor)) {
@@ -788,57 +961,78 @@ class ExtendedVersion {
                             return false;
                         }
                 }
-            case "Flavor":
+            case 'Flavor':
                 return versionRange.atom.flavor == this.flavor;
-            case "And":
+            case 'And':
                 return (this.satisfies(versionRange.atom.left) &&
                     this.satisfies(versionRange.atom.right));
-            case "Or":
+            case 'Or':
                 return (this.satisfies(versionRange.atom.left) ||
                     this.satisfies(versionRange.atom.right));
-            case "Not":
+            case 'Not':
                 return !this.satisfies(versionRange.atom.value);
-            case "Any":
+            case 'Any':
                 return true;
-            case "None":
+            case 'None':
                 return false;
         }
     }
 }
 exports.ExtendedVersion = ExtendedVersion;
+/**
+ * Compile-time type-checking helper that validates an extended version string literal.
+ * If the string is invalid, TypeScript will report a type error at the call site.
+ *
+ * @example
+ * ```ts
+ * testTypeExVer("1.2.3:0")         // compiles
+ * testTypeExVer("#bitcoin:1.0:0")  // compiles
+ * testTypeExVer("invalid")         // type error
+ * ```
+ */
 const testTypeExVer = (t) => t;
 exports.testTypeExVer = testTypeExVer;
+/**
+ * Compile-time type-checking helper that validates a version string literal.
+ * If the string is invalid, TypeScript will report a type error at the call site.
+ *
+ * @example
+ * ```ts
+ * testTypeVersion("1.2.3")  // compiles
+ * testTypeVersion("-3")     // type error
+ * ```
+ */
 const testTypeVersion = (t) => t;
 exports.testTypeVersion = testTypeVersion;
 function tests() {
-    (0, exports.testTypeVersion)("1.2.3");
-    (0, exports.testTypeVersion)("1");
-    (0, exports.testTypeVersion)("12.34.56");
-    (0, exports.testTypeVersion)("1.2-3");
-    (0, exports.testTypeVersion)("1-3");
-    (0, exports.testTypeVersion)("1-alpha");
+    (0, exports.testTypeVersion)('1.2.3');
+    (0, exports.testTypeVersion)('1');
+    (0, exports.testTypeVersion)('12.34.56');
+    (0, exports.testTypeVersion)('1.2-3');
+    (0, exports.testTypeVersion)('1-3');
+    (0, exports.testTypeVersion)('1-alpha');
     // @ts-expect-error
-    (0, exports.testTypeVersion)("-3");
+    (0, exports.testTypeVersion)('-3');
     // @ts-expect-error
-    (0, exports.testTypeVersion)("1.2.3:1");
+    (0, exports.testTypeVersion)('1.2.3:1');
     // @ts-expect-error
-    (0, exports.testTypeVersion)("#cat:1:1");
-    (0, exports.testTypeExVer)("1.2.3:1.2.3");
-    (0, exports.testTypeExVer)("1.2.3.4.5.6.7.8.9.0:1");
-    (0, exports.testTypeExVer)("100:1");
-    (0, exports.testTypeExVer)("#cat:1:1");
-    (0, exports.testTypeExVer)("1.2.3.4.5.6.7.8.9.11.22.33:1");
-    (0, exports.testTypeExVer)("1-0:1");
-    (0, exports.testTypeExVer)("1-0:1");
+    (0, exports.testTypeVersion)('#cat:1:1');
+    (0, exports.testTypeExVer)('1.2.3:1.2.3');
+    (0, exports.testTypeExVer)('1.2.3.4.5.6.7.8.9.0:1');
+    (0, exports.testTypeExVer)('100:1');
+    (0, exports.testTypeExVer)('#cat:1:1');
+    (0, exports.testTypeExVer)('1.2.3.4.5.6.7.8.9.11.22.33:1');
+    (0, exports.testTypeExVer)('1-0:1');
+    (0, exports.testTypeExVer)('1-0:1');
     // @ts-expect-error
-    (0, exports.testTypeExVer)("1.2-3");
+    (0, exports.testTypeExVer)('1.2-3');
     // @ts-expect-error
-    (0, exports.testTypeExVer)("1-3");
+    (0, exports.testTypeExVer)('1-3');
     // @ts-expect-error
-    (0, exports.testTypeExVer)("1.2.3.4.5.6.7.8.9.0.10:1");
+    (0, exports.testTypeExVer)('1.2.3.4.5.6.7.8.9.0.10:1');
     // @ts-expect-error
-    (0, exports.testTypeExVer)("1.-2:1");
+    (0, exports.testTypeExVer)('1.-2:1');
     // @ts-expect-error
-    (0, exports.testTypeExVer)("1..2.3:3");
+    (0, exports.testTypeExVer)('1..2.3:3');
 }
 //# sourceMappingURL=index.js.map