From 1a6aa99bc4479d2495761950c96e4a8226dbaca4 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 15 Jan 2026 19:00:28 +0000
Subject: [PATCH] docs: improve JSDoc for version comparison methods

- Clarify fail-closed behavior for invalid inputs in `isAtLeast`, `isAbove`, `isBelow`, `isAtMost`.
- Explicitly document strict equality behavior for `is()` method.
- Add link to Node.js release schedule in `EOL_DATES` documentation.
---
 .changeset/palette-docs-update.md |  5 +++++
 .jules/palette.md                 |  3 +++
 src/index.ts                      |  1 +
 src/types.ts                      | 10 ++++++----
 4 files changed, 15 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/palette-docs-update.md
 create mode 100644 .jules/palette.md

diff --git a/.changeset/palette-docs-update.md b/.changeset/palette-docs-update.md
new file mode 100644
index 00000000..b6d88b8b
--- /dev/null
+++ b/.changeset/palette-docs-update.md
@@ -0,0 +1,5 @@
+---
+"node-version": patch
+---
+
+Improve JSDoc comments for version comparison methods to clarify strict equality and invalid input handling.
diff --git a/.jules/palette.md b/.jules/palette.md
new file mode 100644
index 00000000..ddaf032f
--- /dev/null
+++ b/.jules/palette.md
@@ -0,0 +1,3 @@
+## 2026-01-03 - [Defining UX for Libraries]
+**Learning:** For backend libraries with no UI, "User Experience" (UX) translates directly to "Developer Experience" (DX). Improvements to JSDoc, error messages, and type definitions are valid UX enhancements.
+**Action:** When working on non-UI repositories, focus on API clarity, documentation links, and fail-closed/safe behavior descriptions in JSDoc.
diff --git a/src/index.ts b/src/index.ts
index 625ca808..e2b59f96 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -11,6 +11,7 @@ export type { NodeVersion };
 
 /**
  * End-of-Life dates for Node.js major versions.
+ * @see https://github.com/nodejs/release#release-schedule
  */
 export const EOL_DATES: Record<string, string> = {
     "18": "2025-04-30",
diff --git a/src/types.ts b/src/types.ts
index 4de06674..3e1186b0 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -35,23 +35,25 @@ export interface NodeVersion {
     /**
      * Check if the current Node version is at least the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version >= target version.
+     * @returns {boolean} True if current version >= target version. Returns false for invalid version strings.
      * @example
      * version.isAtLeast('18.0.0'); // true if current is 20.0.0
      */
     isAtLeast(version: string): boolean;
     /**
      * Check if the current Node version matches the specified version.
+     * Note: This performs a strict equality check and does NOT normalize 'v' prefixes.
      * @param version The version to compare against (e.g., '20.0.0').
      * @returns {boolean} True if current version === target version.
      * @example
      * version.is('20.0.0'); // true if current is 20.0.0
+     * version.is('v20.0.0'); // false if current is 20.0.0
      */
     is(version: string): boolean;
     /**
      * Check if the current Node version is strictly greater than the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version > target version.
+     * @returns {boolean} True if current version > target version. Returns false for invalid version strings.
      * @example
      * version.isAbove('18.0.0'); // true if current is 20.0.0
      */
@@ -59,7 +61,7 @@ export interface NodeVersion {
     /**
      * Check if the current Node version is strictly less than the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version < target version.
+     * @returns {boolean} True if current version < target version. Returns false for invalid version strings.
      * @example
      * version.isBelow('22.0.0'); // true if current is 20.0.0
      */
@@ -67,7 +69,7 @@ export interface NodeVersion {
     /**
      * Check if the current Node version is at most the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version <= target version.
+     * @returns {boolean} True if current version <= target version. Returns false for invalid version strings.
      * @example
      * version.isAtMost('22.0.0'); // true if current is 20.0.0
      */