tiny-essentials 1.28.19 → 1.29.0

package/dist/v1/libs/plugin/TinyVersion.cjs

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * Parses semantic versioning strings.
+ * Expected format: "major.minor.patch" or "major.minor.patch-tag" (e.g., "1.25.0" or "2.0.1-beta").
+ * @template {string} VersionString
+ */
+class TinyVersion {
+  /**
+   * The major version number.
+   * @type {number}
+   */
+  #major = 0;
+
+  /**
+   * The minor version number.
+   * @type {number}
+   */
+  #minor = 0;
+
+  /**
+   * The patch version number.
+   * @type {number}
+   */
+  #patch = 0;
+
+  /**
+   * The optional pre-release tag or build metadata.
+   * @type {string | null}
+   */
+  #tag = null;
+
+  /**
+   * Creates a new TinyVersion instance.
+   *
+   * @param {VersionString} versionString - The version string to parse.
+   * @throws {TypeError} If the provided versionString is not a string.
+   * @throws {Error} If the version string does not match the expected format.
+   */
+  constructor(versionString) {
+    if (typeof versionString !== 'string') {
+      throw new TypeError(
+        `[TinyVersion] Expected version to be a string, received type: ${typeof versionString}`,
+      );
+    }
+
+    // Regex captures: 1: major, 2: minor, 3: patch, 4: optional tag (without the hyphen)
+    const match = versionString.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+
+    /** @param {RegExpMatchArray} match */
+    const startInstance = (match) => {
+      if (typeof match[1] === 'string') this.#major = parseInt(match[1], 10);
+      if (typeof match[2] === 'string') this.#minor = parseInt(match[2], 10);
+      if (typeof match[3] === 'string') this.#patch = parseInt(match[3], 10);
+      if (typeof match[4] === 'string') this.#tag = match[4];
+    };
+
+    if (!match) {
+      const match2 = versionString.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+      if (!match2) {
+        const match3 = versionString.match(/^(\d+)\.(\d+)$/);
+        if (!match3) {
+          const match4 = versionString.match(/^(\d+)$/);
+          if (!match4) {
+            throw new Error(
+              `[TinyVersion] Invalid version format: "${versionString}". Expected format: "X.Y.Z" or "X.Y.Z-tag".`,
+            );
+          } else startInstance(match4);
+        } else startInstance(match3);
+      } else startInstance(match2);
+    } else startInstance(match);
+  }
+
+  /**
+   * Retrieves the major version number (incompatible API changes).
+   * @returns {number}
+   */
+  get major() {
+    return this.#major;
+  }
+
+  /**
+   * Retrieves the minor version number (added functionality in a backwards-compatible manner).
+   * @returns {number}
+   */
+  get minor() {
+    return this.#minor;
+  }
+
+  /**
+   * Retrieves the patch version number (backwards-compatible bug fixes).
+   * @returns {number}
+   */
+  get patch() {
+    return this.#patch;
+  }
+
+  /**
+   * Retrieves the release tag, or null if it does not exist (e.g., "alpha", "rc.1").
+   * @returns {string | null}
+   */
+  get tag() {
+    return this.#tag;
+  }
+
+  /**
+   * Compares this version with another version to see if it is greater.
+   *
+   * @template {TinyVersion<string>} VersionInstance
+   * @param {VersionInstance} version - The version to compare against.
+   * @returns {boolean} True if this version is greater than the provided version.
+   * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+   */
+  isGreaterThan(version) {
+    if (!(version instanceof TinyVersion)) {
+      throw new TypeError(
+        `[TinyVersion] Comparison target must be an instance of TinyVersion. Received: ${typeof version}`,
+      );
+    }
+
+    // 1. Compare Major
+    if (this.#major !== version.major) {
+      return this.#major > version.major;
+    }
+
+    // 2. Compare Minor
+    if (this.#minor !== version.minor) {
+      return this.#minor > version.minor;
+    }
+
+    // 3. Compare Patch
+    if (this.#patch !== version.patch) {
+      return this.#patch > version.patch;
+    }
+
+    // 4. Compare Tags (SemVer rule: version without tag > version with tag)
+    if (this.#tag === null && version.tag !== null) {
+      return true;
+    }
+    if (this.#tag !== null && version.tag === null) {
+      return false;
+    }
+    if (this.#tag === null && version.tag === null) {
+      return false; // They are equal
+    }
+
+    // Both have tags, compare them lexicographically
+    return (this.#tag ?? '') > (version.tag ?? '');
+  }
+
+  /**
+   * Compares this version with another version to see if they are equal.
+   *
+   * @template {TinyVersion<string>} VersionInstance
+   * @param {VersionInstance} version - The version to compare against.
+   * @returns {boolean} True if both versions are identical.
+   * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+   */
+  isEqualTo(version) {
+    if (!(version instanceof TinyVersion)) {
+      throw new TypeError(
+        `[TinyVersion] Comparison target must be an instance of TinyVersion. Received: ${typeof version}`,
+      );
+    }
+
+    return (
+      this.#major === version.major &&
+      this.#minor === version.minor &&
+      this.#patch === version.patch &&
+      this.#tag === version.tag
+    );
+  }
+
+  /**
+   * Compares this version with another version to see if it is less.
+   *
+   * @template {TinyVersion<string>} VersionInstance
+   * @param {VersionInstance} version - The version to compare against.
+   * @returns {boolean} True if this version is less than the provided version.
+   * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+   */
+  isLessThan(version) {
+    if (!(version instanceof TinyVersion)) {
+      throw new TypeError(
+        `[TinyVersion] Comparison target must be an instance of TinyVersion. Received: ${typeof version}`,
+      );
+    }
+
+    // A version is less than another if it is neither greater than nor equal to it.
+    return !this.isGreaterThan(version) && !this.isEqualTo(version);
+  }
+
+  /**
+   * Returns the string representation of the version.
+   * @returns {VersionString} The reconstructed version string.
+   */
+  toString() {
+    const baseVersion = `${this.#major}.${this.#minor}.${this.#patch}`;
+    // @ts-ignore
+    return this.#tag ? `${baseVersion}-${this.#tag}` : baseVersion;
+  }
+}
+
+module.exports = TinyVersion;

package/dist/v1/libs/plugin/TinyVersion.d.mts

@@ -0,0 +1,70 @@
+/**
+ * Parses semantic versioning strings.
+ * Expected format: "major.minor.patch" or "major.minor.patch-tag" (e.g., "1.25.0" or "2.0.1-beta").
+ * @template {string} VersionString
+ */
+declare class TinyVersion<VersionString extends string> {
+    #private;
+    /**
+     * Creates a new TinyVersion instance.
+     *
+     * @param {VersionString} versionString - The version string to parse.
+     * @throws {TypeError} If the provided versionString is not a string.
+     * @throws {Error} If the version string does not match the expected format.
+     */
+    constructor(versionString: VersionString);
+    /**
+     * Retrieves the major version number (incompatible API changes).
+     * @returns {number}
+     */
+    get major(): number;
+    /**
+     * Retrieves the minor version number (added functionality in a backwards-compatible manner).
+     * @returns {number}
+     */
+    get minor(): number;
+    /**
+     * Retrieves the patch version number (backwards-compatible bug fixes).
+     * @returns {number}
+     */
+    get patch(): number;
+    /**
+     * Retrieves the release tag, or null if it does not exist (e.g., "alpha", "rc.1").
+     * @returns {string | null}
+     */
+    get tag(): string | null;
+    /**
+     * Compares this version with another version to see if it is greater.
+     *
+     * @template {TinyVersion<string>} VersionInstance
+     * @param {VersionInstance} version - The version to compare against.
+     * @returns {boolean} True if this version is greater than the provided version.
+     * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+     */
+    isGreaterThan<VersionInstance extends TinyVersion<string>>(version: VersionInstance): boolean;
+    /**
+     * Compares this version with another version to see if they are equal.
+     *
+     * @template {TinyVersion<string>} VersionInstance
+     * @param {VersionInstance} version - The version to compare against.
+     * @returns {boolean} True if both versions are identical.
+     * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+     */
+    isEqualTo<VersionInstance extends TinyVersion<string>>(version: VersionInstance): boolean;
+    /**
+     * Compares this version with another version to see if it is less.
+     *
+     * @template {TinyVersion<string>} VersionInstance
+     * @param {VersionInstance} version - The version to compare against.
+     * @returns {boolean} True if this version is less than the provided version.
+     * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+     */
+    isLessThan<VersionInstance extends TinyVersion<string>>(version: VersionInstance): boolean;
+    /**
+     * Returns the string representation of the version.
+     * @returns {VersionString} The reconstructed version string.
+     */
+    toString(): VersionString;
+}
+export default TinyVersion;
+//# sourceMappingURL=TinyVersion.d.mts.map

package/dist/v1/libs/plugin/TinyVersion.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyVersion.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/plugin/TinyVersion.mjs"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAM,WAAW,CAFK,aAAa,SAArB,MAAqB;;IA2BjC;;;;;;OAMG;IACH,YAAY,aAAa,EAJd,aAIc,EAgCxB;IAED;;;OAGG;IACH,IAAI,KAAK,IAFI,MAAM,CAIlB;IAED;;;OAGG;IACH,IAAI,KAAK,IAFI,MAAM,CAIlB;IAED;;;OAGG;IACH,IAAI,KAAK,IAFI,MAAM,CAIlB;IAED;;;OAGG;IACH,IAAI,GAAG,IAFM,MAAM,GAAG,IAAI,CAIzB;IAED;;;;;;;OAOG;IACH,aAAa,CALsB,eAAe,SAApC,WAAW,CAAC,MAAM,CAAkB,EAKpC,OAAO,EAJV,eAIU,GAHR,OAAO,CAsCnB;IAED;;;;;;;OAOG;IACH,SAAS,CAL0B,eAAe,SAApC,WAAW,CAAC,MAAM,CAAkB,EAKxC,OAAO,EAJN,eAIM,GAHJ,OAAO,CAgBnB;IAED;;;;;;;OAOG;IACH,UAAU,CALyB,eAAe,SAApC,WAAW,CAAC,MAAM,CAAkB,EAKvC,OAAO,EAJP,eAIO,GAHL,OAAO,CAYnB;IAED;;;OAGG;IACH,QAAQ,IAFK,aAAa,CAMzB;CACF;eAEc,WAAW"}

package/dist/v1/libs/plugin/TinyVersion.mjs

@@ -0,0 +1,179 @@
+/**
+ * Parses semantic versioning strings.
+ * Expected format: "major.minor.patch" or "major.minor.patch-tag" (e.g., "1.25.0" or "2.0.1-beta").
+ * @template {string} VersionString
+ */
+class TinyVersion {
+    /**
+     * The major version number.
+     * @type {number}
+     */
+    #major = 0;
+    /**
+     * The minor version number.
+     * @type {number}
+     */
+    #minor = 0;
+    /**
+     * The patch version number.
+     * @type {number}
+     */
+    #patch = 0;
+    /**
+     * The optional pre-release tag or build metadata.
+     * @type {string | null}
+     */
+    #tag = null;
+    /**
+     * Creates a new TinyVersion instance.
+     *
+     * @param {VersionString} versionString - The version string to parse.
+     * @throws {TypeError} If the provided versionString is not a string.
+     * @throws {Error} If the version string does not match the expected format.
+     */
+    constructor(versionString) {
+        if (typeof versionString !== 'string') {
+            throw new TypeError(`[TinyVersion] Expected version to be a string, received type: ${typeof versionString}`);
+        }
+        // Regex captures: 1: major, 2: minor, 3: patch, 4: optional tag (without the hyphen)
+        const match = versionString.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+        /** @param {RegExpMatchArray} match */
+        const startInstance = (match) => {
+            if (typeof match[1] === 'string')
+                this.#major = parseInt(match[1], 10);
+            if (typeof match[2] === 'string')
+                this.#minor = parseInt(match[2], 10);
+            if (typeof match[3] === 'string')
+                this.#patch = parseInt(match[3], 10);
+            if (typeof match[4] === 'string')
+                this.#tag = match[4];
+        };
+        if (!match) {
+            const match2 = versionString.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+            if (!match2) {
+                const match3 = versionString.match(/^(\d+)\.(\d+)$/);
+                if (!match3) {
+                    const match4 = versionString.match(/^(\d+)$/);
+                    if (!match4) {
+                        throw new Error(`[TinyVersion] Invalid version format: "${versionString}". Expected format: "X.Y.Z" or "X.Y.Z-tag".`);
+                    }
+                    else
+                        startInstance(match4);
+                }
+                else
+                    startInstance(match3);
+            }
+            else
+                startInstance(match2);
+        }
+        else
+            startInstance(match);
+    }
+    /**
+     * Retrieves the major version number (incompatible API changes).
+     * @returns {number}
+     */
+    get major() {
+        return this.#major;
+    }
+    /**
+     * Retrieves the minor version number (added functionality in a backwards-compatible manner).
+     * @returns {number}
+     */
+    get minor() {
+        return this.#minor;
+    }
+    /**
+     * Retrieves the patch version number (backwards-compatible bug fixes).
+     * @returns {number}
+     */
+    get patch() {
+        return this.#patch;
+    }
+    /**
+     * Retrieves the release tag, or null if it does not exist (e.g., "alpha", "rc.1").
+     * @returns {string | null}
+     */
+    get tag() {
+        return this.#tag;
+    }
+    /**
+     * Compares this version with another version to see if it is greater.
+     *
+     * @template {TinyVersion<string>} VersionInstance
+     * @param {VersionInstance} version - The version to compare against.
+     * @returns {boolean} True if this version is greater than the provided version.
+     * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+     */
+    isGreaterThan(version) {
+        if (!(version instanceof TinyVersion)) {
+            throw new TypeError(`[TinyVersion] Comparison target must be an instance of TinyVersion. Received: ${typeof version}`);
+        }
+        // 1. Compare Major
+        if (this.#major !== version.major) {
+            return this.#major > version.major;
+        }
+        // 2. Compare Minor
+        if (this.#minor !== version.minor) {
+            return this.#minor > version.minor;
+        }
+        // 3. Compare Patch
+        if (this.#patch !== version.patch) {
+            return this.#patch > version.patch;
+        }
+        // 4. Compare Tags (SemVer rule: version without tag > version with tag)
+        if (this.#tag === null && version.tag !== null) {
+            return true;
+        }
+        if (this.#tag !== null && version.tag === null) {
+            return false;
+        }
+        if (this.#tag === null && version.tag === null) {
+            return false; // They are equal
+        }
+        // Both have tags, compare them lexicographically
+        return (this.#tag ?? '') > (version.tag ?? '');
+    }
+    /**
+     * Compares this version with another version to see if they are equal.
+     *
+     * @template {TinyVersion<string>} VersionInstance
+     * @param {VersionInstance} version - The version to compare against.
+     * @returns {boolean} True if both versions are identical.
+     * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+     */
+    isEqualTo(version) {
+        if (!(version instanceof TinyVersion)) {
+            throw new TypeError(`[TinyVersion] Comparison target must be an instance of TinyVersion. Received: ${typeof version}`);
+        }
+        return (this.#major === version.major &&
+            this.#minor === version.minor &&
+            this.#patch === version.patch &&
+            this.#tag === version.tag);
+    }
+    /**
+     * Compares this version with another version to see if it is less.
+     *
+     * @template {TinyVersion<string>} VersionInstance
+     * @param {VersionInstance} version - The version to compare against.
+     * @returns {boolean} True if this version is less than the provided version.
+     * @throws {TypeError} If the provided version is not an instance of TinyVersion.
+     */
+    isLessThan(version) {
+        if (!(version instanceof TinyVersion)) {
+            throw new TypeError(`[TinyVersion] Comparison target must be an instance of TinyVersion. Received: ${typeof version}`);
+        }
+        // A version is less than another if it is neither greater than nor equal to it.
+        return !this.isGreaterThan(version) && !this.isEqualTo(version);
+    }
+    /**
+     * Returns the string representation of the version.
+     * @returns {VersionString} The reconstructed version string.
+     */
+    toString() {
+        const baseVersion = `${this.#major}.${this.#minor}.${this.#patch}`;
+        // @ts-ignore
+        return this.#tag ? `${baseVersion}-${this.#tag}` : baseVersion;
+    }
+}
+export default TinyVersion;