From d45ee82295672c2bbc69e451d0ee5c8cf4bfce96 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Sat, 10 Jan 2026 18:50:02 +0000
Subject: [PATCH] docs: enhance JSDoc for version comparison methods

- Explicitly documented fail-closed behavior for comparison methods (returns false for invalid inputs).
- Clarified strict string equality behavior for `is()` method.
- Added internal journal for UX/DX learnings.
---
 .changeset/palette-docs-update.md |  5 +++++
 .jules/palette.md                 |  5 +++++
 src/types.ts                      | 15 +++++++++++----
 3 files changed, 21 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..2b55be00
--- /dev/null
+++ b/.changeset/palette-docs-update.md
@@ -0,0 +1,5 @@
+---
+"node-version": patch
+---
+
+docs: enhance JSDoc for version comparison methods
diff --git a/.jules/palette.md b/.jules/palette.md
new file mode 100644
index 00000000..f7409ac4
--- /dev/null
+++ b/.jules/palette.md
@@ -0,0 +1,5 @@
+# Palette's Journal
+
+## 2026-01-03 - Documenting Fail-Closed Behaviors
+**Learning:** In utility libraries, "fail-closed" behavior (returning false for invalid inputs) is excellent for security but can be confusing for developers if not documented. Users might assume a "garbage" version string throws an error, but instead it silently returns false.
+**Action:** Always explicitly document the return value for invalid/edge-case inputs in JSDoc, especially when the behavior is "silent failure" rather than throwing an exception.
diff --git a/src/types.ts b/src/types.ts
index 4de06674..84aa162e 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -35,41 +35,47 @@ 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` if the input version string is invalid or contains whitespace.
      * @example
      * version.isAtLeast('18.0.0'); // true if current is 20.0.0
+     * version.isAtLeast('invalid'); // false
      */
     isAtLeast(version: string): boolean;
     /**
      * Check if the current Node version matches the specified version.
+     * Performs a strict string comparison and does not handle 'v' prefix.
      * @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
      */
     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` if the input version string is invalid or contains whitespace.
      * @example
      * version.isAbove('18.0.0'); // true if current is 20.0.0
+     * version.isAbove('invalid'); // false
      */
     isAbove(version: string): boolean;
     /**
      * 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` if the input version string is invalid or contains whitespace.
      * @example
      * version.isBelow('22.0.0'); // true if current is 20.0.0
+     * version.isBelow('invalid'); // false
      */
     isBelow(version: string): boolean;
     /**
      * 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` if the input version string is invalid or contains whitespace.
      * @example
      * version.isAtMost('22.0.0'); // true if current is 20.0.0
+     * version.isAtMost('invalid'); // false
      */
     isAtMost(version: string): boolean;
     /**
@@ -84,6 +90,7 @@ export interface NodeVersion {
     ltsName: string | undefined;
     /**
      * Check if the current version is considered End-of-Life (EOL).
+     * Only tracks versions defined in the internal `EOL_DATES` map. Returns `false` for unknown or untracked versions.
      * @see https://github.com/nodejs/release#end-of-life-releases
      */
     isEOL: boolean;