@darco2903/expiry-cache 2.0.2 → 3.0.0

package/README.md

@@ -12,8 +12,11 @@ A simple in-memory cache with expiry functionality. It allows you to store data
 - **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.
+- **Safe Fetching**: Safe cache fetching that returns a `Result` type, allowing for error handling without throwing exceptions.
+- **Stale Data Access**: Option to access stale data even after it has expired.
 - **Parameterized Fetching**: Support for fetcher functions that require parameters.
+- **Return Options**: Allow to set expiry time when refreshing the cache. For exemple API tokens that return their expiry time.
+- **Event Emission**: Emit events on cache refresh and expiry for better integration with other parts of your application.
 
 ## Installation
 
@@ -28,31 +31,46 @@ npm install @darco2903/expiry-cache
 ```ts
 import { ExpiryCache } from "@darco2903/expiry-cache";
 
-const cache = new ExpiryCache("initial", () => "refreshed", 1000); // inferring to ExpiryCache<string, () => string>
-console.log(cache.getData()); // Outputs: initial
+const cache = new ExpiryCache("initial", () => "refreshed", 1000); // ExpiryCache<string, () => string>
+console.log(cache.getData()); // 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)
+console.log(cache.isExpired); // true
+console.log(cache.getData()); // null
+console.log(cache.getRawData()); // initial (returns the raw data even if expired)
 
 cache.refresh();
-console.log(cache.getData()); // Outputs: refreshed
+console.log(cache.getData()); // 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.isExpired); // true
+console.log(cache.getDataOrRefresh()); // 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.expirationTime); // 1000
+console.log(cache.expiresAt); // current timestamp + 1000 milliseconds
+console.log(cache.timeToLive); // time remaining until expiration in milliseconds
 
-console.log(cache.expire()); // Manually expire the cache
-console.log(cache.isExpired); // Outputs: true
+cache.expire(); // Manually expire the cache
+console.log(cache.isExpired); // true
+```
+
+### With Parameters
+
+You can also use the cache with a fetcher function that requires parameters. In this case, the `refresh` method accepts the necessary parameters to fetch the new data.
+
+```ts
+import { ExpiryCache } from "@darco2903/expiry-cache";
+
+const cache = new ExpiryCache(10, (a: number, b: number) => a + b, 200); // ExpiryCache<number, (a: number, b: number) => number>
+
+cache.refresh(5, 7); // typed: refresh(a: number, b: number)
+console.log(cache.getData()); // 12
 ```
 
 ### With Async Fetcher
 
+Same as the ExpiryCache, but with an asynchronous fetcher function. The `refresh` method will return a promise that resolves when the cache has been updated.
+
 ```ts
 import { ExpiryCacheAsync } from "@darco2903/expiry-cache";
 
@@ -68,37 +86,127 @@ async function getApiData(): Promise<string> {
 const cache = new ExpiryCacheAsync("initial data", getApiData, 5000);
 
 await cache.refresh();
-console.log(cache.getData()); // Outputs: fetched data from API
+console.log(cache.getData()); // fetched data from API
 ```
 
-### With Parameters
+### With Result
+
+Allows to handle errors without throwing exceptions, returning a `Result` type instead. The cache will be updated only if the result is `Ok`, otherwise nothing is changed and the cache is not refreshed when the result is `Err`.
+
+In this example, we have a fetcher function that performs a division operation. If the divisor is zero, it returns an error instead of throwing an exception.
 
 ```ts
-import { ExpiryCache } from "@darco2903/expiry-cache";
+import { ExpiryCacheSafe } from "@darco2903/expiry-cache";
+import { err, ok } from "neverthrow";
 
-const cache = new ExpiryCache(10, (a: number, b: number) => a + b, 200);
+const cache = new ExpiryCacheSafe(1, (a: number, b: number) => (b === 0 ? err("Division by zero") : ok(a / b)), 100);
+console.log(cache.getData()); // 1
+console.log(cache.timeToLiveAsTime?.toStringWithUnit()); // ~100ms
 
-cache.refresh(5, 7); // typed: refresh(a: number, b: number)
-console.log(cache.getData()); // Outputs: 12
+await new Promise((resolve) => setTimeout(resolve, 200));
+console.log(cache.isExpired); // true
+
+cache.refresh(4, 2); // ok(2)
+console.log(cache.getData()); // 2
+console.log(cache.timeToLiveAsTime?.toStringWithUnit()); // ~100ms
+
+await new Promise((resolve) => setTimeout(resolve, 200));
+console.log(cache.isExpired); // true
+
+cache.refresh(4, 0); // err("Division by zero")
+console.log(cache.getData()); // null
+console.log(cache.isExpired); // true
 ```
 
-### Setting Expiry Manually
+### Event Emission
 
 ```ts
 import { ExpiryCache } from "@darco2903/expiry-cache";
 
-const cache = new ExpiryCache(0, () => 0); // Cache with no expiry by default
+const cache = new ExpiryCache(0, () => 10, 1000);
+cache.on("expired", () => {
+    console.log("Cache expired");
+});
+
+cache.on("refreshed", (value) => {
+    console.log("Cache refreshed with value:", value);
+});
+
+cache.expire(); // trigger the expired event
+
+cache.refresh(); // trigger the refreshed event
+```
+
+### Setting expiry time when refreshing
+
+#### ExpiresIn
+
+```ts
+import { ExpiryCache, ReturnOptions } from "@darco2903/expiry-cache";
+
+const cache = new ExpiryCache(0, () => ReturnOptions.ExpiresIn(0, 200), 1000);
+console.log(cache.expirationTime); // 1000
 
 cache.refresh();
-cache.refreshExpiresAt(Date.now());
-cache.refreshExpiresIn(1000);
+console.log(cache.expirationTime); // 200
+```
+
+#### ExpiresAt
+
+```ts
+import { ExpiryCache, ReturnOptions } from "@darco2903/expiry-cache";
+
+const cache = new ExpiryCache(0, () => ReturnOptions.ExpiresAt(0, Date.now() + 200), 1000);
+console.log(cache.expiresAt - Date.now()); //  ~1000
+
+cache.refresh();
+console.log(cache.expiresAt - Date.now()); //  ~200
 ```
 
 ### SecondThought Integration
 
 ```ts
 import { ExpiryCache } from "@darco2903/expiry-cache";
-import { Minute } from "@darco2903/secondthought";
+import { Millisecond, Second, Minute, Hour } from "@darco2903/secondthought";
 
 const cache = new ExpiryCache("data", () => "data", new Minute(5)); // Cache expires in 5 minutes
+
+cache.setExpiresIn(new Hour(1)); // Update the cache to expire in 1 hour
+cache.setExpiresAt(Millisecond.now().add(new Second(2))); // Set the cache to expire in 2 seconds
+```
+
+### Full Example with Async Fetcher, Result and ReturnOptions
+
+```ts
+import { ExpiryCacheSafeAsync, ReturnOptions } from "@darco2903/expiry-cache";
+import { Second } from "@darco2903/secondthought";
+import { ResultAsync, okAsync } from "neverthrow";
+
+type TokenData = {
+    token: string;
+    expiresIn: number;
+};
+
+function fetchApiToken(): ResultAsync<TokenData, string> {
+    return ResultAsync.fromPromise(
+        fetch("https://example.com/api/token").then((res) => res.json()),
+        (err) => String(err),
+    );
+}
+
+const cache = new ExpiryCacheSafeAsync("", () => {
+    return fetchApiToken().andThen((res) => {
+        return okAsync(ReturnOptions.ExpiresIn(res.token, new Second(res.expiresIn)));
+    });
+});
+cache.expire(); // expire the cache immediately to force a refresh on the first call
+
+await cache.refresh().match(
+    (token) => {
+        console.log("Fetched API token:", token);
+    },
+    (err) => {
+        console.error("Error fetching API token:", err);
+    },
+);
 ```

package/dist/ExpiryCache.d.ts

@@ -1,27 +1,14 @@
-import { type Time } from "@darco2903/secondthought";
-import { ExpiryCacheBase } from "./ExpiryCacheBase.js";
-import type { RefreshFunction } from "./types.js";
-export declare class ExpiryCache<T, U extends RefreshFunction<T>> extends ExpiryCacheBase<T, U> {
+import { ExpiryCacheSyncBase } from "./base/index.js";
+import type { RefreshFunctionUnsafeSync } from "./types/index.js";
+import type { IExpiryCacheSync, IExpiryCacheUnsafe } from "./interface/index.js";
+import type { CacheEventsUnsafe } from "./types/events.js";
+export declare class ExpiryCache<T, F extends RefreshFunctionUnsafeSync<T>> extends ExpiryCacheSyncBase<T, F, CacheEventsUnsafe<T>> implements IExpiryCacheSync<T, F>, IExpiryCacheUnsafe<T, F> {
     /**
-     * Creates an instance of ExpiryCache.
-     * @param data  The initial data to be cached.
-     * @param callback The function to refresh the cached data.
-     * @param expirationTime The time in milliseconds after which the cache expires. Defaults to 60_000 (1 minute). If set to 0, the cache will never expire.
+     * Refreshes the cache by calling the refresh function with the provided arguments and updates the cache data. Returns the updated cache data.
      */
-    constructor(data: T, callback: U, expirationTime?: number | Time);
+    refresh(...args: Parameters<F>): T;
     /**
-     * Refreshes the cached data using the callback function.
+     * Returns the cached data if it is not expired. If the cache is expired, it refreshes the cache by calling the refresh function with the provided arguments and returns the updated cache data.
      */
-    refresh(...args: Parameters<U>): void;
-    getDataOrRefresh(...args: Parameters<U>): T;
-    /**
-     * Refreshes the cached data and sets a new expiration timestamp.
-     * @param expiresAt The new expiration timestamp in milliseconds.
-     */
-    refreshExpiresAt(expiresAt: number | Time, ...args: Parameters<U>): void;
-    /**
-     * Refreshes the cached data and sets a new expiration time.
-     * @param expirationTime The new expiration time in milliseconds.
-     */
-    refreshExpiresIn(expirationTime: number | Time, ...args: Parameters<U>): void;
+    getDataOrRefresh(...args: Parameters<F>): T;
 }

package/dist/ExpiryCache.js

@@ -1,41 +1,20 @@
-import { Minute } from "@darco2903/secondthought";
-import { ExpiryCacheBase } from "./ExpiryCacheBase.js";
-export class ExpiryCache extends ExpiryCacheBase {
+import { ExpiryCacheSyncBase } from "./base/index.js";
+export class ExpiryCache extends ExpiryCacheSyncBase {
     /**
-     * Creates an instance of ExpiryCache.
-     * @param data  The initial data to be cached.
-     * @param callback The function to refresh the cached data.
-     * @param expirationTime The time in milliseconds after which the cache expires. Defaults to 60_000 (1 minute). If set to 0, the cache will never expire.
+     * Refreshes the cache by calling the refresh function with the provided arguments and updates the cache data. Returns the updated cache data.
      */
-    constructor(data, callback, expirationTime = new Minute(1)) {
-        super(data, callback, expirationTime);
+    refresh(...args) {
+        this.setData(this.refreshFn(...args));
+        this._emit("refreshed", this.data);
+        return this.data;
     }
     /**
-     * Refreshes the cached data using the callback function.
+     * Returns the cached data if it is not expired. If the cache is expired, it refreshes the cache by calling the refresh function with the provided arguments and returns the updated cache data.
      */
-    refresh(...args) {
-        this.setData(this.callback(...args));
-    }
     getDataOrRefresh(...args) {
         if (this.isExpired) {
             this.refresh(...args);
         }
         return this.data;
     }
-    /**
-     * Refreshes the cached data and sets a new expiration timestamp.
-     * @param expiresAt The new expiration timestamp in milliseconds.
-     */
-    refreshExpiresAt(expiresAt, ...args) {
-        const expAt = this.argToMs(expiresAt);
-        this.setDataExpiresAt(this.callback(...args), expAt);
-    }
-    /**
-     * Refreshes the cached data and sets a new expiration time.
-     * @param expirationTime The new expiration time in milliseconds.
-     */
-    refreshExpiresIn(expirationTime, ...args) {
-        const expTime = this.argToMs(expirationTime);
-        this.setDataExpiresIn(this.callback(...args), expTime);
-    }
 }

package/dist/ExpiryCacheAsync.d.ts

@@ -1,29 +1,16 @@
-import { type Time } from "@darco2903/secondthought";
-import { ExpiryCacheBase } from "./ExpiryCacheBase.js";
-import type { RefreshFunctionAsync } from "./types.js";
-export declare class ExpiryCacheAsync<T, U extends RefreshFunctionAsync<T>> extends ExpiryCacheBase<T, U> {
-    protected _refreshCb: Promise<T> | null;
-    get refreshing(): boolean;
+import { ExpiryCacheAsyncBase } from "./base/index.js";
+import type { ReturnOptions } from "./ReturnOptions.js";
+import type { RefreshFunctionUnsafeAsync, ReturnTypeUnsafeAsync } from "./types/index.js";
+import type { IExpiryCacheAsync, IExpiryCacheUnsafe } from "./interface/index.js";
+import type { CacheEventsUnsafe } from "./types/events.js";
+export declare class ExpiryCacheAsync<T, F extends RefreshFunctionUnsafeAsync<T>> extends ExpiryCacheAsyncBase<T, F, ReturnTypeUnsafeAsync<T | ReturnOptions<T>>, CacheEventsUnsafe<T>> implements IExpiryCacheAsync<T, F>, IExpiryCacheUnsafe<T, F> {
     /**
-     * Creates an instance of ExpiryCache.
-     * @param data  The initial data to be cached.
-     * @param callback The function to refresh the cached data.
-     * @param expirationTime The time in milliseconds after which the cache expires. Defaults to 60_000 (1 minute). If set to 0, the cache will never expire.
+     * Refreshes the cache by calling the refresh function with the provided arguments and updates the cache data. Returns the updated cache data.
+     * If a refresh is already in progress, it returns the existing refresh promise instead of calling the callback again.
      */
-    constructor(data: T, callback: U, expirationTime?: number | Time);
+    refresh(...args: Parameters<F>): Promise<T>;
     /**
-     * Refreshes the cached data using the callback function.
+     * Returns the cached data if it is not expired. If the cache is expired, it refreshes the cache by calling the refresh function with the provided arguments and returns the updated cache data.
      */
-    refresh(...args: Parameters<U>): Promise<void>;
-    getDataOrRefresh(...args: Parameters<U>): Promise<T>;
-    /**
-     * Refreshes the cached data and sets a new expiration timestamp.
-     * @param expiresAt The new expiration timestamp in milliseconds.
-     */
-    refreshExpiresAt(expiresAt: number | Time, ...args: Parameters<U>): Promise<void>;
-    /**
-     * Refreshes the cached data and sets a new expiration time.
-     * @param expirationTime The new expiration time in milliseconds.
-     */
-    refreshExpiresIn(expirationTime: number | Time, ...args: Parameters<U>): Promise<void>;
+    getDataOrRefresh(...args: Parameters<F>): Promise<T>;
 }

package/dist/ExpiryCacheAsync.js

@@ -1,52 +1,28 @@
-import { Minute } from "@darco2903/secondthought";
-import { ExpiryCacheBase } from "./ExpiryCacheBase.js";
-export class ExpiryCacheAsync extends ExpiryCacheBase {
-    get refreshing() {
-        return this._refreshCb !== null;
-    }
-    /**
-     * Creates an instance of ExpiryCache.
-     * @param data  The initial data to be cached.
-     * @param callback The function to refresh the cached data.
-     * @param expirationTime The time in milliseconds after which the cache expires. Defaults to 60_000 (1 minute). If set to 0, the cache will never expire.
-     */
-    constructor(data, callback, expirationTime = new Minute(1)) {
-        super(data, callback, expirationTime);
-        this._refreshCb = null;
-    }
+import { ExpiryCacheAsyncBase } from "./base/index.js";
+export class ExpiryCacheAsync extends ExpiryCacheAsyncBase {
     /**
-     * Refreshes the cached data using the callback function.
+     * Refreshes the cache by calling the refresh function with the provided arguments and updates the cache data. Returns the updated cache data.
+     * If a refresh is already in progress, it returns the existing refresh promise instead of calling the callback again.
      */
     async refresh(...args) {
         if (this.refreshing) {
             await this._refreshCb;
         }
         else {
-            this._refreshCb = this.callback(...args);
+            this._refreshCb = this.refreshFn(...args);
             this.setData(await this._refreshCb);
+            this._emit("refreshed", this.data);
             this._refreshCb = null;
         }
+        return this.data;
     }
+    /**
+     * Returns the cached data if it is not expired. If the cache is expired, it refreshes the cache by calling the refresh function with the provided arguments and returns the updated cache data.
+     */
     async getDataOrRefresh(...args) {
         if (this.isExpired) {
             await this.refresh(...args);
         }
         return this.data;
     }
-    /**
-     * Refreshes the cached data and sets a new expiration timestamp.
-     * @param expiresAt The new expiration timestamp in milliseconds.
-     */
-    async refreshExpiresAt(expiresAt, ...args) {
-        const expAt = this.argToMs(expiresAt);
-        this.setDataExpiresAt(await this.callback(...args), expAt);
-    }
-    /**
-     * Refreshes the cached data and sets a new expiration time.
-     * @param expirationTime The new expiration time in milliseconds.
-     */
-    async refreshExpiresIn(expirationTime, ...args) {
-        const expTime = this.argToMs(expirationTime);
-        this.setDataExpiresIn(await this.callback(...args), expTime);
-    }
 }

package/dist/ExpiryCacheSafe.d.ts

@@ -0,0 +1,18 @@
+import { type Result } from "neverthrow";
+import { ExpiryCacheSyncBase } from "./base/index.js";
+import type { RefreshFunctionSafeSync } from "./types/index.js";
+import type { IExpiryCacheSafe, IExpiryCacheSync } from "./interface/index.js";
+import type { CacheEventsSafe } from "./types/events.js";
+export declare class ExpiryCacheSafe<T, E, F extends RefreshFunctionSafeSync<T, E>> extends ExpiryCacheSyncBase<T, F, CacheEventsSafe<T, E>, E> implements IExpiryCacheSync<T, F, E>, IExpiryCacheSafe<T, F, E> {
+    /**
+     * Refreshes the cache by calling the refresh function with the provided arguments and updates the cache data if the result is Ok, otherwise it does not update the cache data.
+     * Returns the refresh function result.
+     */
+    refresh(...args: Parameters<F>): Result<T, E>;
+    /**
+     * Returns the cached data if it is not expired.
+     * If the cache is expired, it refreshes the cache by calling the refresh function with the provided arguments and returns the refresh function result.
+     * It behaves the same as the refresh method if the cache is expired, otherwise it returns the cached data wrapped in an Ok result.
+     */
+    getDataOrRefresh(...args: Parameters<F>): Result<T, E>;
+}

package/dist/ExpiryCacheSafe.js

@@ -0,0 +1,31 @@
+import { ok } from "neverthrow";
+import { ExpiryCacheSyncBase } from "./base/index.js";
+import { mapRefreshReturn } from "./utils.js";
+export class ExpiryCacheSafe extends ExpiryCacheSyncBase {
+    /**
+     * Refreshes the cache by calling the refresh function with the provided arguments and updates the cache data if the result is Ok, otherwise it does not update the cache data.
+     * Returns the refresh function result.
+     */
+    refresh(...args) {
+        return this.refreshFn(...args)
+            .andTee((data) => this.setData(data))
+            .map((mapRefreshReturn))
+            .andTee((data) => {
+            this._emit("refreshed", data);
+        })
+            .orTee((err) => {
+            this._emit("error", err);
+        });
+    }
+    /**
+     * Returns the cached data if it is not expired.
+     * If the cache is expired, it refreshes the cache by calling the refresh function with the provided arguments and returns the refresh function result.
+     * It behaves the same as the refresh method if the cache is expired, otherwise it returns the cached data wrapped in an Ok result.
+     */
+    getDataOrRefresh(...args) {
+        if (this.isExpired) {
+            return this.refresh(...args);
+        }
+        return ok(this.data);
+    }
+}

package/dist/ExpiryCacheSafeAsync.d.ts

@@ -0,0 +1,20 @@
+import { type ResultAsync } from "neverthrow";
+import { ExpiryCacheAsyncBase } from "./base/index.js";
+import type { ReturnOptions } from "./ReturnOptions.js";
+import type { RefreshFunctionSafeAsync, ReturnTypeSafeAsync } from "./types/index.js";
+import type { IExpiryCacheAsync, IExpiryCacheSafe } from "./interface/index.js";
+import type { CacheEventsSafe } from "./types/events.js";
+export declare class ExpiryCacheSafeAsync<T, E, F extends RefreshFunctionSafeAsync<T, E>> extends ExpiryCacheAsyncBase<T, F, ReturnTypeSafeAsync<T | ReturnOptions<T>, E>, CacheEventsSafe<T, E>, E> implements IExpiryCacheAsync<T, F, E>, IExpiryCacheSafe<T, F, E> {
+    /**
+     * Refreshes the cache by calling the refresh function with the provided arguments and updates the cache data if the result is Ok, otherwise it does not update the cache data.
+     * Returns the refresh function result.
+     * If a refresh is already in progress, it returns the existing refresh promise instead of calling the callback again.
+     */
+    refresh(...args: Parameters<F>): ResultAsync<T, E>;
+    /**
+     * Returns the cached data if it is not expired.
+     * If the cache is expired, it refreshes the cache by calling the refresh function with the provided arguments and returns the refresh function result.
+     * It behaves the same as the refresh method if the cache is expired, otherwise it returns the cached data wrapped in an Ok result.
+     */
+    getDataOrRefresh(...args: Parameters<F>): ResultAsync<T, E>;
+}

package/dist/ExpiryCacheSafeAsync.js

@@ -0,0 +1,40 @@
+import { okAsync } from "neverthrow";
+import { ExpiryCacheAsyncBase } from "./base/index.js";
+import { mapRefreshReturn } from "./utils.js";
+export class ExpiryCacheSafeAsync extends ExpiryCacheAsyncBase {
+    /**
+     * Refreshes the cache by calling the refresh function with the provided arguments and updates the cache data if the result is Ok, otherwise it does not update the cache data.
+     * Returns the refresh function result.
+     * If a refresh is already in progress, it returns the existing refresh promise instead of calling the callback again.
+     */
+    refresh(...args) {
+        if (this._refreshCb !== null) {
+            return this._refreshCb.map((mapRefreshReturn));
+        }
+        else {
+            this._refreshCb = this.refreshFn(...args);
+            return this._refreshCb
+                .andTee((res) => this.setData(res))
+                .map((mapRefreshReturn))
+                .andTee((data) => {
+                this._refreshCb = null;
+                this._emit("refreshed", data);
+            })
+                .orTee((err) => {
+                this._refreshCb = null;
+                this._emit("error", err);
+            });
+        }
+    }
+    /**
+     * Returns the cached data if it is not expired.
+     * If the cache is expired, it refreshes the cache by calling the refresh function with the provided arguments and returns the refresh function result.
+     * It behaves the same as the refresh method if the cache is expired, otherwise it returns the cached data wrapped in an Ok result.
+     */
+    getDataOrRefresh(...args) {
+        if (this.isExpired) {
+            return this.refresh(...args);
+        }
+        return okAsync(this.data);
+    }
+}

package/dist/ReturnOptions.d.ts

@@ -0,0 +1,15 @@
+import { Millisecond, type Time } from "@darco2903/secondthought";
+export declare abstract class ReturnOptions<T> {
+    readonly data: T;
+    constructor(data: T);
+    static ExpiresAt<T>(data: T, expiresAt: number | Time): ReturnOptionsExpiresAtClass<T>;
+    static ExpiresIn<T>(data: T, expiresIn: number | Time): ReturnOptionsExpiresInClass<T>;
+}
+export declare class ReturnOptionsExpiresInClass<T> extends ReturnOptions<T> {
+    readonly expiresIn: Millisecond;
+    constructor(data: T, expiresIn: number | Time);
+}
+export declare class ReturnOptionsExpiresAtClass<T> extends ReturnOptions<T> {
+    readonly expiresAt: Millisecond;
+    constructor(data: T, expiresAt: number | Time);
+}

package/dist/ReturnOptions.js

@@ -0,0 +1,24 @@
+import { argToMs } from "./utils.js";
+export class ReturnOptions {
+    constructor(data) {
+        this.data = data;
+    }
+    static ExpiresAt(data, expiresAt) {
+        return new ReturnOptionsExpiresAtClass(data, expiresAt);
+    }
+    static ExpiresIn(data, expiresIn) {
+        return new ReturnOptionsExpiresInClass(data, expiresIn);
+    }
+}
+export class ReturnOptionsExpiresInClass extends ReturnOptions {
+    constructor(data, expiresIn) {
+        super(data);
+        this.expiresIn = argToMs(expiresIn);
+    }
+}
+export class ReturnOptionsExpiresAtClass extends ReturnOptions {
+    constructor(data, expiresAt) {
+        super(data);
+        this.expiresAt = argToMs(expiresAt);
+    }
+}

package/dist/base/ExpiryCacheAsyncBase.d.ts

@@ -0,0 +1,13 @@
+import { Time } from "@darco2903/secondthought";
+import { ExpiryCacheBase } from "./ExpiryCacheBase.js";
+import type { ReturnOptions } from "../ReturnOptions.js";
+import type { RefreshFunctionAsync } from "../types/RefreshFunction.js";
+import type { ReturnTypeAsync } from "../types/ReturnType.js";
+import type { CacheEvents } from "../types/events.js";
+export declare abstract class ExpiryCacheAsyncBase<T, F extends RefreshFunctionAsync<T, E>, V extends ReturnTypeAsync<T | ReturnOptions<T>, E>, M extends CacheEvents<T, E>, E = any> extends ExpiryCacheBase<T, F, M, E> {
+    /** The promise of the current refresh operation, or null if no refresh is in progress. */
+    protected _refreshCb: V | null;
+    /** Indicates whether the cache is currently being refreshed. */
+    get refreshing(): boolean;
+    constructor(data: T, callback: F, expirationTime?: number | Time);
+}

package/dist/base/ExpiryCacheAsyncBase.js

@@ -0,0 +1,11 @@
+import { ExpiryCacheBase } from "./ExpiryCacheBase.js";
+export class ExpiryCacheAsyncBase extends ExpiryCacheBase {
+    /** Indicates whether the cache is currently being refreshed. */
+    get refreshing() {
+        return this._refreshCb !== null;
+    }
+    constructor(data, callback, expirationTime) {
+        super(data, callback, expirationTime);
+        this._refreshCb = null;
+    }
+}