@vltpkg/semver 0.0.0-0.1730239248325

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) vlt technology, Inc.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+   Subject to the terms and conditions of this license, each copyright holder and contributor hereby grants to those receiving rights under this license a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except for failure to satisfy the conditions of this license) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer this software, where such license applies only to those patent claims, already acquired or hereafter acquired, licensable by such copyright holder or contributor that are necessarily infringed by:
+
+(a) their Contribution(s) (the licensed copyrights of copyright holders and non-copyrightable additions of contributors, in source or binary form) alone; or
+(b) combination of their Contribution(s) with the work of authorship to which such Contribution(s) was added by such copyright holder or contributor, if, at the time the Contribution is added, such addition causes such combination to be necessarily infringed. The patent license shall not apply to any other combinations which include the Contribution.
+Except as expressly stated above, no rights or licenses from any copyright holder or contributor is granted under this license, whether expressly, by implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,152 @@
+# `@vltpkg/semver`
+
+<img src="https://github.com/darcyclarke/octofiles/assets/459713/8ee74129-34e6-4bd4-8686-82954f424709" width="85" />
+
+## Semantic Versions
+
+Parsing, validating & comparing Semantic Versions used by `vlt`.
+
+## Usage
+
+```js
+import {
+  parse,
+  valid,
+  parseRange,
+  validRange,
+  increment,
+  satisfies,
+  sort,
+  compare,
+  rsort,
+  rcompare,
+  filter,
+  filterMethod,
+  gt,
+  lt,
+  gte,
+  lte,
+  eq,
+  neq,
+  maxSatisfying,
+  sortedMaxSatisfying,
+  rsortedMaxSatisfying,
+  Version,
+  Range,
+  Comparator,
+} from '@vltpkg/semver'
+```
+
+## Functions
+
+- `parse(v)`: Attempt to parse a string as a semantic version,
+  returning either a `Version` object or `undefined`.
+- `valid(v)`: Return true if the version is valid
+- `increment(v, type, [identifier])` Increment the specified part
+  of the version, and return the resulting object. If a Version
+  object is provided, it will be modified in-place.
+- `major(v)`: Return the major version number.
+- `minor(v)`: Return the minor version number.
+- `patch(v)`: Return the patch version number.
+- `prerelease(v)`: Returns an array of prerelease components, or
+  `undefined` if none exist. Example: `prerelease('1.2.3-alpha.1') ->
+['alpha', 1]`
+- `build(v)`: Returns an array of build components, or
+  `undefined` if none exist. Example: `prerelease('1.2.3+linux.33') ->
+['linux', '33']`
+- `stable(v)`: Returns an array of releases that are considered
+  "stable" (ie. no prereleases), or an empty array if non exist.
+
+### Comparison
+
+These functions all compare version strings or objects
+by their SemVer precedence. (Note that build metadata is not
+considered, as per the SemVer 2.0 specification.)
+
+Unless otherwise noted, they throw an error on invalid versions.
+
+- `gt(v1, v2)`: `v1 > v2`
+- `gte(v1, v2)`: `v1 >= v2`
+- `lt(v1, v2)`: `v1 < v2`
+- `lte(v1, v2)`: `v1 <= v2`
+- `eq(v1, v2)`: `v1 == v2` This is true even if they're not the
+  exact same string. You already know how to compare strings.
+- `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
+- `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
+  `v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
+- `sortMethod(v1, v2)`: The same as `compare`, except that
+  invalid versions are sorted to the end of the list rather than
+  throwing an error.
+- `rcompare(v1, v2)`: Inverse of `compare`
+- `rsortMethod(v1, v2)`: Inverse of `sortMethod`. (Invalid
+  versions are still sorted to the end of the list.)
+
+### Ranges
+
+- `validRange(range)`: Return the valid range or null if it's not valid
+- `satisfies(version, range)`: Return true if the version satisfies the
+  range.
+- `highest(versions, range)`: Return the highest version in the list
+  that satisfies the range, or `null` if none of them do.
+- `sortedHighest(versions, range)`: Optimized form of `highest`,
+  if the version list is known to be sorted in ascending SemVer
+  precedence order. If the list is not sorted already, may return
+  an incorrect result.
+- `rsortedHighest(versions, range)`: Optimized form of `highest`,
+  if the version list is known to be sorted in descending SemVer
+  precedence order. If the list is not sorted already, may return
+  an incorrect result.
+- `lowest(versions, range)`: Return the lowest version in the list
+  that satisfies the range, or `null` if none of them do.
+- `sortedLowest(versions, range)`: Optimized form of `lowest`,
+  if the version list is known to be sorted in ascending SemVer
+  precedence order. If the list is not sorted already, may return
+  an incorrect result.
+- `rsortedLowest(versions, range)`: Optimized form of `lowest`,
+  if the version list is known to be sorted in descending SemVer
+  precedence order. If the list is not sorted already, may return
+  an incorrect result.
+
+### Classes
+
+- `Version` Object representation of a SemVer version. Create
+  from a string with `Version.parse(versionString)`.
+- `Range` Representation of a version range.
+- `Comparator` The representation of a single part of a Range,
+  which does most of the heavy lifting for parsing and testing
+  versions. This is an internal class, and should usually not be
+  used directly.
+
+## Differences from `node-semver` (the one used by `npm`)
+
+- The API is slightly different. Most notably, `@vltpkg/semver`
+  lacks range intersection and other methods that are not needed
+  by `vlt`. Of course, these may be added eventually if we find a
+  need for them.
+
+- Build metadata is preserved on `Version` objects and in
+  `toString()` values.
+
+- It's significantly faster. About 40-50% faster at parsing
+  versions, 15-20% faster at parsing ranges, and 60-70% faster at
+  testing versions against ranges, which results in the
+  `highest()` method being around 2-3 times as fast as
+  node-semver's `maxSatisfying`.
+
+  Of course, if you're not writing a package manager or some
+  other program that does millions of version comparisons in
+  the course of its operations, this is likely not relevant.)
+
+- There's no switch for `loose` vs `strict` mode. It just always
+  works the same way.
+
+  - A leading `v` or `=` on a version is always allowed
+  - Prereleases _must_ be prefixed by a `-`.
+  - Excessively large numbers in prerelease identifiers are
+    treated as strings, rather than throwing an error.
+
+  For example, `v1.2.3` will be parsed, but `1.2.3foo` will be
+  considered invalid. `toString()` values are always the strict
+  representation.
+
+- There is no CLI implementation, and thus, no dependencies.

package/dist/esm/comparator.d.ts

@@ -0,0 +1,76 @@
+import { Version } from './version.js';
+/** all comparators are expressed in terms of these operators */
+export type SimpleOperator = '' | '<' | '<=' | '>' | '>=';
+/** operators that are expanded to simpler forms */
+export type ComplexOperator = '^' | '~' | '~>';
+/** comparator expressed as a [operator,version] tuple */
+export type OVTuple = [SimpleOperator, Version];
+/**
+ * The result of parsing a version value that might be either a full
+ * version like `1.2.3` or an X-Range like `1.2.x`
+ */
+export type ParsedXRange = ParsedXMajor | ParsedXMinor | ParsedXPatch | ParsedXVersion;
+/**
+ * a {@link ParsedXRange} that is just a `*`
+ */
+export type ParsedXMajor = [];
+/**
+ * a {@link ParsedXRange} that is just a major version
+ */
+export type ParsedXMinor = [number];
+/**
+ * a {@link ParsedXRange} that is just a major and minor version
+ */
+export type ParsedXPatch = [number, number];
+/**
+ * a {@link ParsedXRange} that is a full version
+ */
+export type ParsedXVersion = [
+    M: number,
+    m: number,
+    p: number,
+    pr?: string | undefined,
+    b?: string | undefined
+];
+/**
+ * Class used to parse the `||` separated portions
+ * of a range, and evaluate versions against it.
+ *
+ * This does most of the heavy lifting of range testing, and provides
+ * little affordance for improperly formatted strings. It should be
+ * considered an internal class, and usually not accessed directly.
+ */
+export declare class Comparator {
+    #private;
+    /**
+     * does this range include prereleases, even when they do not
+     * match the tuple in the comparator?
+     */
+    includePrerelease: boolean;
+    /** raw string used to create this comparator */
+    raw: string;
+    /** tokens extracted from the raw string input */
+    tokens: string[];
+    /**
+     * Either the `any` comparator, the `none` comparator, or an operator
+     * and a {@link ParsedXRange}
+     */
+    tuples: (Comparator | OVTuple)[];
+    /** true if this comparator can not match anything */
+    isNone: boolean;
+    /**
+     * true if this comparator is a `'*'` type of range.
+     *
+     * Note that it still will not match versions with a prerelease value,
+     * unless the tuple in the version matches the tuple provided to the
+     * comparator, and the comparator version also has a prerelease value,
+     * unless `includePrerelease` is set.
+     */
+    isAny: boolean;
+    /** the canonical strict simplified parsed form of this constructor */
+    toString(): string;
+    constructor(comp: string, includePrerelease?: boolean);
+    /** return true if the version is a match for this comparator */
+    test(v: Version): boolean;
+}
+//# sourceMappingURL=comparator.d.ts.map

package/dist/esm/comparator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparator.d.ts","sourceRoot":"","sources":["../../src/comparator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,gEAAgE;AAChE,MAAM,MAAM,cAAc,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAA;AACzD,mDAAmD;AACnD,MAAM,MAAM,eAAe,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,CAAA;AAe9C,yDAAyD;AACzD,MAAM,MAAM,OAAO,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;AA+C/C;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,cAAc,CAAA;AAClB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,EAAE,CAAA;AAC7B;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,CAAC,CAAA;AACnC;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAC3C;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,MAAM;IACT,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS;IACvB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS;CACvB,CAAA;AAYD;;;;;;;GAOG;AACH,qBAAa,UAAU;;IACrB;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAA;IAC1B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAA;IACX,iDAAiD;IACjD,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB;;;OAGG;IACH,MAAM,EAAE,CAAC,UAAU,GAAG,OAAO,CAAC,EAAE,CAAK;IACrC,qDAAqD;IACrD,MAAM,UAAQ;IACd;;;;;;;OAOG;IACH,KAAK,UAAQ;IAEb,sEAAsE;IACtE,QAAQ;gBASI,IAAI,EAAE,MAAM,EAAE,iBAAiB,UAAQ;IAydnD,gEAAgE;IAChE,IAAI,CAAC,CAAC,EAAE,OAAO;CAqChB"}