@start9labs/start-sdk 0.4.0-beta.50 → 0.4.0-beta.52

package/base/lib/exver/index.d.ts

@@ -1,7 +1,38 @@
 import { DeepMap } from 'deep-equality-data-structures';
 import * as P from './exver';
+/**
+ * Compile-time utility type that validates a version string literal conforms to semver format.
+ *
+ * Resolves to `unknown` if valid, `never` if invalid. Used with {@link testTypeVersion}.
+ *
+ * @example
+ * ```ts
+ * type Valid = ValidateVersion<"1.2.3">     // unknown (valid)
+ * type Invalid = ValidateVersion<"-3">      // never (invalid)
+ * ```
+ */
 export type ValidateVersion<T extends String> = T extends `-${infer A}` ? never : T extends `${infer A}-${string}` ? ValidateVersion<A> : T extends `${bigint}` ? unknown : T extends `${bigint}.${infer A}` ? ValidateVersion<A> : never;
+/**
+ * Compile-time utility type that validates an extended version string literal.
+ *
+ * Extended versions have the format `upstream:downstream` or `#flavor:upstream:downstream`.
+ *
+ * @example
+ * ```ts
+ * type Valid = ValidateExVer<"1.2.3:0">           // valid
+ * type Flavored = ValidateExVer<"#bitcoin:1.0:0">  // valid
+ * type Bad = ValidateExVer<"1.2-3">                // never (invalid)
+ * ```
+ */
 export type ValidateExVer<T extends string> = T extends `#${string}:${infer A}:${infer B}` ? ValidateVersion<A> & ValidateVersion<B> : T extends `${infer A}:${infer B}` ? ValidateVersion<A> & ValidateVersion<B> : never;
+/**
+ * Validates a tuple of extended version string literals at compile time.
+ *
+ * @example
+ * ```ts
+ * type Valid = ValidateExVers<["1.0:0", "2.0:0"]>  // valid
+ * ```
+ */
 export type ValidateExVers<T> = T extends [] ? unknown[] : T extends [infer A, ...infer B] ? ValidateExVer<A & string> & ValidateExVers<B> : never[];
 type Anchor = {
     type: 'Anchor';
@@ -85,55 +116,234 @@ declare class VersionRangeTable {
      */
     static minterms(tables: VersionRangeTables): VersionRange;
 }
+/**
+ * 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")
+ * ```
+ */
 export declare class VersionRange {
     atom: Anchor | And | Or | Not | P.Any | P.None | Flavor;
     constructor(atom: Anchor | And | Or | Not | P.Any | P.None | Flavor);
     toStringParens(parent: 'And' | 'Or' | 'Not'): string;
+    /** Serializes this version range back to its canonical string representation. */
     toString(): string;
     private static parseAtom;
     private static parseRange;
+    /**
+     * 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: string): 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: P.CmpOp, version: ExtendedVersion): VersionRange;
+    /**
+     * 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: string | null): VersionRange;
+    /**
+     * 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: string): VersionRange;
+    /** Returns the intersection of this range with another (logical AND). */
     and(right: VersionRange): VersionRange;
+    /** Returns the union of this range with another (logical OR). */
     or(right: VersionRange): VersionRange;
+    /** Returns the negation of this range (logical NOT). */
     not(): VersionRange;
+    /**
+     * Returns the logical AND (intersection) of multiple version ranges.
+     * Short-circuits on `none()` and skips `any()`.
+     */
     static and(...xs: Array<VersionRange>): VersionRange;
+    /**
+     * Returns the logical OR (union) of multiple version ranges.
+     * Short-circuits on `any()` and skips `none()`.
+     */
     static or(...xs: Array<VersionRange>): VersionRange;
+    /** Returns a version range that matches all versions (wildcard `*`). */
     static any(): VersionRange;
+    /** Returns a version range that matches no versions (`!`). */
     static none(): VersionRange;
+    /**
+     * Returns `true` if the given version satisfies this range.
+     *
+     * @param version - A {@link Version} or {@link ExtendedVersion} to test
+     */
     satisfiedBy(version: Version | ExtendedVersion): boolean;
     tables(): VersionRangeTables;
+    /** Returns `true` if any version exists that could satisfy this range. */
     satisfiable(): boolean;
+    /** Returns `true` if this range and `other` share at least one satisfying version. */
     intersects(other: VersionRange): boolean;
+    /**
+     * Returns a canonical (simplified) form of this range using minterm expansion.
+     * Useful for normalizing complex boolean expressions into a minimal representation.
+     */
     normalize(): 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)
+ * ```
+ */
 export declare class Version {
+    /** The numeric version segments (e.g. `[1, 2, 3]` for `"1.2.3"`). */
     number: number[];
+    /** Optional prerelease identifiers (e.g. `["beta", 1]` for `"-beta.1"`). */
     prerelease: (string | number)[];
-    constructor(number: number[], prerelease: (string | number)[]);
+    constructor(
+    /** The numeric version segments (e.g. `[1, 2, 3]` for `"1.2.3"`). */
+    number: number[], 
+    /** Optional prerelease identifiers (e.g. `["beta", 1]` for `"-beta.1"`). */
+    prerelease: (string | number)[]);
+    /** Serializes this version to its string form (e.g. `"1.2.3"` or `"1.0.0-beta.1"`). */
     toString(): string;
+    /**
+     * Compares this version against another using semver precedence rules.
+     *
+     * @param other - The version to compare against
+     * @returns `'greater'`, `'equal'`, or `'less'`
+     */
     compare(other: Version): 'greater' | 'equal' | 'less';
+    /**
+     * 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: Version): -1 | 0 | 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: string): Version;
+    /**
+     * Returns `true` if this version satisfies the given {@link VersionRange}.
+     * Internally treats this as an unflavored {@link ExtendedVersion} with downstream `0`.
+     */
     satisfies(versionRange: VersionRange): boolean;
 }
+/**
+ * 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
+ * ```
+ */
 export declare class ExtendedVersion {
+    /** The flavor identifier (e.g. `"bitcoin"`), or `null` for unflavored versions. */
     flavor: string | null;
+    /** The upstream software version. */
     upstream: Version;
+    /** The downstream packaging version. */
     downstream: Version;
-    constructor(flavor: string | null, upstream: Version, downstream: Version);
+    constructor(
+    /** The flavor identifier (e.g. `"bitcoin"`), or `null` for unflavored versions. */
+    flavor: string | null, 
+    /** The upstream software version. */
+    upstream: Version, 
+    /** The downstream packaging version. */
+    downstream: Version);
+    /** Serializes this extended version to its string form (e.g. `"#bitcoin:1.2.3:0"` or `"1.0.0:1"`). */
     toString(): string;
+    /**
+     * Compares this extended version against another.
+     *
+     * @returns `'greater'`, `'equal'`, `'less'`, or `null` if the flavors differ (incomparable)
+     */
     compare(other: ExtendedVersion): 'greater' | 'equal' | 'less' | null;
+    /**
+     * Lexicographic comparison — compares flavors alphabetically first, then versions.
+     * Unlike {@link compare}, this never returns `null`: different flavors are ordered alphabetically.
+     */
     compareLexicographic(other: ExtendedVersion): 'greater' | 'equal' | 'less';
+    /**
+     * Returns a numeric comparison result suitable for use with `Array.sort()`.
+     * Uses lexicographic ordering (flavors sorted alphabetically, then by version).
+     */
     compareForSort(other: ExtendedVersion): 1 | 0 | -1;
+    /** Returns `true` if this version is strictly greater than `other`. Returns `false` if flavors differ. */
     greaterThan(other: ExtendedVersion): boolean;
+    /** Returns `true` if this version is greater than or equal to `other`. Returns `false` if flavors differ. */
     greaterThanOrEqual(other: ExtendedVersion): boolean;
+    /** Returns `true` if this version equals `other` (same flavor, upstream, and downstream). */
     equals(other: ExtendedVersion): boolean;
+    /** Returns `true` if this version is strictly less than `other`. Returns `false` if flavors differ. */
     lessThan(other: ExtendedVersion): boolean;
+    /** Returns `true` if this version is less than or equal to `other`. Returns `false` if flavors differ. */
     lessThanOrEqual(other: ExtendedVersion): boolean;
+    /**
+     * 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: string): ExtendedVersion;
+    /**
+     * 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: string): ExtendedVersion;
     /**
      * Returns an ExtendedVersion with the Upstream major version version incremented by 1
@@ -153,6 +363,27 @@ export declare class ExtendedVersion {
      */
     satisfies(versionRange: VersionRange): boolean;
 }
+/**
+ * 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
+ * ```
+ */
 export declare const testTypeExVer: <T extends string>(t: T & ValidateExVer<T>) => T & ValidateExVer<T>;
+/**
+ * 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
+ * ```
+ */
 export declare const testTypeVersion: <T extends string>(t: T & ValidateVersion<T>) => T & ValidateVersion<T>;
 export {};

package/base/lib/exver/index.js

@@ -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;
@@ -386,6 +408,7 @@ class VersionRange {
             return this.toString();
         }
     }
+    /** Serializes this version range back to its canonical string representation. */
     toString() {
         switch (this.atom.type) {
             case 'Anchor':
@@ -448,27 +471,58 @@ 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' }));
     }
+    /**
+     * 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 });
     }
+    /**
+     * 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 });
     }
+    /**
+     * 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' }));
     }
+    /** Returns the intersection of this range with another (logical AND). */
     and(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 });
     }
+    /** Returns the negation of this range (logical NOT). */
     not() {
         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) {
@@ -487,6 +541,10 @@ class VersionRange {
         }
         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) {
@@ -505,12 +563,19 @@ class VersionRange {
         }
         return y;
     }
+    /** Returns a version range that matches all versions (wildcard `*`). */
     static any() {
         return new VersionRange({ type: 'Any' });
     }
+    /** Returns a version range that matches no versions (`!`). */
     static 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);
     }
@@ -554,25 +619,58 @@ class VersionRange {
                 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('.')}` : ''}`;
     }
+    /**
+     * 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++) {
@@ -616,6 +714,11 @@ class Version {
         }
         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':
@@ -626,25 +729,70 @@ class Version {
                 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' });
         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()}`;
     }
+    /**
+     * 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;
@@ -655,6 +803,10 @@ class ExtendedVersion {
         }
         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';
@@ -666,6 +818,10 @@ class ExtendedVersion {
             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':
@@ -676,25 +832,42 @@ class ExtendedVersion {
                 return -1;
         }
     }
+    /** Returns `true` if this version is strictly greater than `other`. Returns `false` if flavors differ. */
     greaterThan(other) {
         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));
     }
+    /** Returns `true` if this version equals `other` (same flavor, upstream, and downstream). */
     equals(other) {
         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';
     }
+    /** 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));
     }
+    /**
+     * 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 || 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' });
@@ -806,8 +979,29 @@ class ExtendedVersion {
     }
 }
 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() {