@darco2903/expiry-cache 2.0.0 → 2.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darco2903
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,9 +4,22 @@
 
 A simple in-memory cache with expiry functionality. It allows you to store data that automatically expires after a specified duration, with support for synchronous and asynchronous data fetching.
 
+> Note: This package utilizes the [**@darco2903/secondthought**](https://www.npmjs.com/package/@darco2903/secondthought) package for time-related operations, providing enhanced capabilities for handling and manipulating time-related data. While its use is not mandatory, it is recommended for optimal safety and reliability when working with time values.
+
+## Features
+
+- **Type Safety**: Strongly typed cache entries and fetcher functions.
+- **Automatic Expiry**: Cache entries automatically expire after a specified duration.
+- **Manual Expiry**: Manually expire cache entries when needed.
+- **Synchronous and Asynchronous Fetching**: Support for both synchronous and asynchronous data fetching.
+- **Raw Data Access**: Access the raw cached data even if it has expired.
+- **Parameterized Fetching**: Support for fetcher functions that require parameters.
+
 ## Installation
 
-You can find the package here: [**@darco2903/expiry-cache**](https://github.com/users/Darco2903/packages/npm/package/expiry-cache)
+```bash
+npm install @darco2903/expiry-cache
+```
 
 ## Example Usage
 
@@ -15,24 +28,36 @@ You can find the package here: [**@darco2903/expiry-cache**](https://github.com/
 ```ts
 import { ExpiryCache } from "@darco2903/expiry-cache";
 
-const cache = new ExpiryCache("initial", () => "string", 1000); // infering to ExpiryCache<string, () => string>
+const cache = new ExpiryCache("initial", () => "refreshed", 1000); // inferring to ExpiryCache<string, () => string>
 console.log(cache.getData()); // Outputs: initial
 
 await new Promise((resolve) => setTimeout(resolve, 1100)); // wait for cache to expire
 console.log(cache.isExpired); // Outputs: true
 console.log(cache.getData()); // Outputs: null
+console.log(cache.getRawData()); // Outputs: initial (returns the raw data even if expired)
 
 cache.refresh();
-console.log(cache.getData()); // Outputs: string
+console.log(cache.getData()); // Outputs: refreshed
+
+await new Promise((resolve) => setTimeout(resolve, 1100)); // wait for cache to expire
+console.log(cache.isExpired); // Outputs: true
+console.log(cache.getDataOrRefresh()); // Outputs: refreshed (refreshes the cache and returns the new value)
+
+console.log(cache.expirationTime); // Outputs: 1000
+console.log(cache.expiresAt); // Outputs: current timestamp + 1000 milliseconds
+console.log(cache.timeToLive); // Outputs: time remaining until expiration in milliseconds
+
+console.log(cache.expire()); // Manually expire the cache
+console.log(cache.isExpired); // Outputs: true
 ```
 
 ### With Async Fetcher
 
 ```ts
-import { ExpiryCache } from "@darco2903/expiry-cache";
+import { ExpiryCacheAsync } from "@darco2903/expiry-cache";
 
 async function getApiData(): Promise<string> {
-    // Simulating an API call
+    // Simulate an API call
     return new Promise((resolve) => {
         setTimeout(() => {
             resolve("fetched data from API");
@@ -40,7 +65,7 @@ async function getApiData(): Promise<string> {
     });
 }
 
-const cache = new ExpiryCache("initial data", getApiData, 5000);
+const cache = new ExpiryCacheAsync("initial data", getApiData, 5000);
 
 await cache.refresh();
 console.log(cache.getData()); // Outputs: fetched data from API
@@ -62,9 +87,18 @@ console.log(cache.getData()); // Outputs: 12
 ```ts
 import { ExpiryCache } from "@darco2903/expiry-cache";
 
-const cache = new ExpiryCache(0, () => 0);
+const cache = new ExpiryCache(0, () => 0); // Cache with no expiry by default
 
 cache.refresh();
 cache.refreshExpiresAt(Date.now());
 cache.refreshExpiresIn(1000);
 ```
+
+### SecondThought Integration
+
+```ts
+import { ExpiryCache } from "@darco2903/expiry-cache";
+import { Minute } from "@darco2903/secondthought";
+
+const cache = new ExpiryCache("data", () => "data", new Minute(5)); // Cache expires in 5 minutes
+```

package/dist/ExpiryCacheBase.js

@@ -23,7 +23,7 @@ export class ExpiryCacheBase {
      */
     get timeToLive() {
         if (this.doesExpire) {
-            return Math.max(0, this._expiresAt.clone().subtract(Millisecond.now()).time);
+            return Math.max(0, this._expiresAt.clone().sub(Millisecond.now()).time);
         }
         return null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darco2903/expiry-cache",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "author": "Darco2903",
   "description": "",
   "keywords": [],
@@ -15,7 +15,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@darco2903/secondthought": "^1.1.0"
+    "@darco2903/secondthought": "^1.3.0"
   },
   "devDependencies": {
     "@darco2903/web-common": "^0.7.0",