From 711cc855d815c5e9e2bafdb98092e87a71fa04f5 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Fri, 9 Jan 2026 19:02:14 +0000
Subject: [PATCH] docs: improve JSDoc for comparisons and EOL dates

---
 .changeset/calm-pandas-sing.md | 5 +++++
 .jules/palette.md              | 5 +++++
 src/index.ts                   | 1 +
 src/types.ts                   | 8 ++++----
 4 files changed, 15 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/calm-pandas-sing.md
 create mode 100644 .jules/palette.md

diff --git a/.changeset/calm-pandas-sing.md b/.changeset/calm-pandas-sing.md
new file mode 100644
index 00000000..42d7fc9e
--- /dev/null
+++ b/.changeset/calm-pandas-sing.md
@@ -0,0 +1,5 @@
+---
+"node-version": patch
+---
+
+Improve JSDoc for version comparison methods and EOL dates.
diff --git a/.jules/palette.md b/.jules/palette.md
new file mode 100644
index 00000000..57102588
--- /dev/null
+++ b/.jules/palette.md
@@ -0,0 +1,5 @@
+# Palette's Journal
+
+## 2026-01-03 - Documenting Fail-Closed Behavior
+**Learning:** For utility libraries, explicitly documenting "fail-closed" behavior (returning false/undefined instead of throwing) is a critical DX improvement, as users might assume validation errors throw.
+**Action:** Always check edge case return values and ensure they are documented in JSDoc/TSDoc.
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..887afc03 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -35,7 +35,7 @@ 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
      */
@@ -51,7 +51,7 @@ export interface NodeVersion {
     /**
      * 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 +59,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 +67,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
      */