From 04304f106a83d860d2122dd5a7fd851abdeadda0 Mon Sep 17 00:00:00 2001
From: Hans Kokx <hans.d.kokx@gmail.com>
Date: Wed, 17 Sep 2025 18:47:28 +0200
Subject: [PATCH] v1.4.7

- Added the `isExpired` and `expiresSoon` getters to JWT tokens.

Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>
---
 CHANGELOG.md                  | 14 +++++++++++++-
 README.md                     |  8 +++++++-
 lib/src/extensions/jwt.dart   | 23 +++++++++++++++++++++++
 pubspec.yaml                  |  2 +-
 test/extensions/jwt_test.dart | 12 ++++++++++++
 5 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index db3135f..b517f70 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,15 @@
+## 1.4.7
+
+- Added the `isExpired` and `expiresSoon` getters to JWT tokens.
+
+Example:
+
+```dart
+String token = "your.jwt.token";
+bool isExpired = token.isExpired;
+bool expiresSoon = token.expiresSoon;
+```
+
 ## 1.4.6
 
 - Updated dependencies to the latest versions
@@ -17,7 +29,7 @@
 ## 1.4.2
 
 - Added the `isLeapYear` extension to the `DateTime` and `int` objects.
-- Added the `FixedSizeList` class. See the readme and examples for details.
+- Added the `FixedSizeList` class. See the README and examples for details.
 
 ## 1.4.1
 
diff --git a/README.md b/README.md
index 26ea7a4..b7d9acf 100644
--- a/README.md
+++ b/README.md
@@ -267,7 +267,13 @@ Here are some examples of how to use the utilities and extensions provided by th
       ```dart
       String jwt = "your.jwt.token";
       // Returns a `DateTime?` when the token expires
-      final DateTime? email = jwt.jwt.expiryTime;
+      final DateTime? expiryTime = jwt.jwt.expiryTime;
+      
+      // Returns `true` if the token has expired
+      final bool jwt.jwt.isExpired;
+
+      // Returns `true` if the token expires within the next (1) minute
+      final bool jwt.jwt.expiresSoon;
       ```
 
     - Extracting the user ID (`jwt["uid"]`)
diff --git a/lib/src/extensions/jwt.dart b/lib/src/extensions/jwt.dart
index 1e63abb..c77f298 100644
--- a/lib/src/extensions/jwt.dart
+++ b/lib/src/extensions/jwt.dart
@@ -149,6 +149,29 @@ extension JWTMapUtility on JwtPayload {
     }
   }
 
+  /// Determines whether the JWT has expired.
+  ///
+  /// If the current `expiryTime` is `null`, this value always returns `true`.
+  /// Otherwise, the current `expiryTime` is compared to the current `DateTime`.
+  /// Returns `true` if `DateTime.now()` is after the `expiryTime`. Otherwise,
+  /// returns `false`.
+  bool get isExpired {
+    if (expiryTime == null) return true;
+    return DateTime.now().isAfter(expiryTime!);
+  }
+
+  /// Determines whether the JWT will expire within the next (1) minute.
+  ///
+  /// If the current `expiryTime` is `null`, this value always returns `true`.
+  /// Otherwise, the current `expiryTime` is compared to the current `DateTime`,
+  /// plus (1) minute..
+  /// Returns `true` if the token expires within the next (1) minute. Otherwise,
+  /// returns `false`.
+  bool get expiresSoon {
+    if (expiryTime == null) return true;
+    return DateTime.now().add(const Duration(minutes: 1)).isAfter(expiryTime!);
+  }
+
   /// Extracts the user ID from the JWT payload.
   ///
   /// This method retrieves the `uid` field, which is typically the unique user identifier.
diff --git a/pubspec.yaml b/pubspec.yaml
index f7e65c1..95b832d 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
 name: arcane_helper_utils
 description: Provides a variety of helpful utilities and extensions for Flutter
   and Dart.
-version: 1.4.6
+version: 1.4.7
 repository: https://github.com/hanskokx/arcane_helper_utils
 issue_tracker: https://github.com/hanskokx/arcane_helper_utils/issues
 
diff --git a/test/extensions/jwt_test.dart b/test/extensions/jwt_test.dart
index 2577f2b..1b3d63f 100644
--- a/test/extensions/jwt_test.dart
+++ b/test/extensions/jwt_test.dart
@@ -59,6 +59,18 @@ void main() {
       expect(expiry?.year, 2025); // Based on the exp value in the test token
     });
 
+    test("jwt.isExpired checks expiration on tokens properly", () {
+      final bool isExpired = validToken.jwt.isExpired;
+      expect(isExpired, isNotNull);
+      expect(isExpired, true);
+    });
+
+    test("jwt.expiresSoon checks expiration on tokens properly", () {
+      final bool expiresSoon = validToken.jwt.expiresSoon;
+      expect(expiresSoon, isNotNull);
+      expect(expiresSoon, true);
+    });
+
     test("jwt.expiryTime throws an exception for invalid token", () {
       expect(
         () => "invalid.token".jwt.expiryTime,