@darco2903/expiry-cache 2.0.0-beta.0

package/README.md

@@ -0,0 +1,70 @@
+# Expiry Cache
+
+## Description
+
+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.
+
+## Installation
+
+You can find the package here: [**@darco2903/expiry-cache**](https://github.com/users/Darco2903/packages/npm/package/expiry-cache)
+
+## Example Usage
+
+### Basic Example
+
+```ts
+import { ExpiryCache } from "@darco2903/expiry-cache";
+
+const cache = new ExpiryCache("initial", () => "string", 1000); // infering 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
+
+cache.refresh();
+console.log(cache.getData()); // Outputs: string
+```
+
+### With Async Fetcher
+
+```ts
+import { ExpiryCache } from "@darco2903/expiry-cache";
+
+async function getApiData(): Promise<string> {
+    // Simulating an API call
+    return new Promise((resolve) => {
+        setTimeout(() => {
+            resolve("fetched data from API");
+        }, 500);
+    });
+}
+
+const cache = new ExpiryCache("initial data", getApiData, 5000);
+
+await cache.refresh();
+console.log(cache.getData()); // Outputs: fetched data from API
+```
+
+### With Parameters
+
+```ts
+import { ExpiryCache } from "@darco2903/expiry-cache";
+
+const cache = new ExpiryCache(10, (a: number, b: number) => a + b, 200);
+
+cache.refresh(5, 7); // typed: refresh(a: number, b: number)
+console.log(cache.getData()); // Outputs: 12
+```
+
+### Setting Expiry Manually
+
+```ts
+import { ExpiryCache } from "@darco2903/expiry-cache";
+
+const cache = new ExpiryCache(0, () => 0);
+
+cache.refresh();
+cache.refreshExpiresAt(Date.now());
+cache.refreshExpiresIn(1000);
+```

package/dist/ExpiryCache.d.ts

@@ -0,0 +1,27 @@
+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> {
+    /**
+     * 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: T, callback: U, expirationTime?: number | Time);
+    /**
+     * Refreshes the cached data using the callback function.
+     */
+    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;
+}

package/dist/ExpiryCache.js

@@ -0,0 +1,41 @@
+import { Minute } from "@darco2903/secondthought";
+import { ExpiryCacheBase } from "./ExpiryCacheBase.js";
+export class ExpiryCache extends ExpiryCacheBase {
+    /**
+     * 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);
+    }
+    /**
+     * Refreshes the cached data using the callback function.
+     */
+    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

@@ -0,0 +1,29 @@
+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;
+    /**
+     * 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: T, callback: U, expirationTime?: number | Time);
+    /**
+     * Refreshes the cached data using the callback function.
+     */
+    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>;
+}

package/dist/ExpiryCacheAsync.js

@@ -0,0 +1,52 @@
+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;
+    }
+    /**
+     * Refreshes the cached data using the callback function.
+     */
+    async refresh(...args) {
+        if (this.refreshing) {
+            await this._refreshCb;
+        }
+        else {
+            this._refreshCb = this.callback(...args);
+            this.setData(await this._refreshCb);
+            this._refreshCb = null;
+        }
+    }
+    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/ExpiryCacheBase.d.ts

@@ -0,0 +1,95 @@
+import { type Time, Millisecond } from "@darco2903/secondthought";
+import type { RefreshFunction, RefreshFunctionAsync } from "./types.js";
+export declare abstract class ExpiryCacheBase<T, U extends RefreshFunction<T> | RefreshFunctionAsync<T>> {
+    protected data: T;
+    protected callback: U;
+    readonly expirationTime: number;
+    /** The expiration timestamp in milliseconds. 0 means never expires, -1 means already expired or no data. */
+    protected _expiresAt: Millisecond;
+    /**
+     * Gets the expiration timestamp in milliseconds.
+     */
+    get expiresAt(): number;
+    /**
+     * Checks if the cache is set to expire.
+     */
+    get doesExpire(): boolean;
+    /**
+     * Checks if the cache is expired.
+     */
+    get isExpired(): boolean;
+    /**
+     * Gets the time to live (TTL) in milliseconds.
+     */
+    get timeToLive(): number | null;
+    /**
+     * Converts a number or Time object to milliseconds.
+     */
+    protected argToMs(arg: number | Time): Millisecond;
+    /**
+     * 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: T, callback: U, expirationTime?: number | Time);
+    /**
+     * Expires the cache immediately.
+     */
+    expire(): void;
+    /**
+     * Sets the cache to never expire.
+     */
+    neverExpire(): void;
+    protected expIn(ms: Millisecond): Millisecond;
+    /**
+     * Sets the expiration timestamp based on the current time plus the given milliseconds.
+     * @param ms The time in milliseconds after which the cache should expire. If set to 0, the cache will never expire.
+     */
+    setExpiresIn(ms: number | Time): void;
+    /**
+     * Sets the expiration timestamp to a specific time.
+     * @param timestamp The expiration timestamp in milliseconds.
+     */
+    setExpiresAt(timestamp: number | Time): void;
+    /**
+     * Sets the cached data and resets the expiration timestamp based on the expiration time.
+     */
+    protected setData(data: T): void;
+    /**
+     * Sets the cached data and sets a new expiration timestamp.
+     * @param expiresAt The new expiration timestamp in milliseconds.
+     */
+    protected setDataExpiresAt(data: T, expiresAt: Millisecond): void;
+    /**
+     * Sets the cached data and sets a new expiration time.
+     * @param expirationTime The new expiration time in milliseconds.
+     */
+    protected setDataExpiresIn(data: T, expirationTime: Millisecond): void;
+    /**
+     * Gets the raw cached data without checking expiration.
+     */
+    getRawData(): T;
+    /**
+     * Gets the cached data if not expired, otherwise returns null.
+     */
+    getData(): T | null;
+    /**
+     * Refreshes the cached data using the callback function.
+     */
+    abstract refresh(...args: Parameters<U>): void | Promise<void>;
+    /**
+     * Gets the cached data or refreshes it if expired.
+     */
+    abstract getDataOrRefresh(...args: Parameters<U>): T | Promise<T>;
+    /**
+     * Refreshes the cached data and sets a new expiration timestamp.
+     * @param expiresAt The new expiration timestamp in milliseconds.
+     */
+    abstract refreshExpiresAt(expiresAt: number | Time, ...args: Parameters<U>): void | Promise<void>;
+    /**
+     * Refreshes the cached data and sets a new expiration time.
+     * @param expirationTime The new expiration time in milliseconds.
+     */
+    abstract refreshExpiresIn(expirationTime: number | Time, ...args: Parameters<U>): void | Promise<void>;
+}

package/dist/ExpiryCacheBase.js

@@ -0,0 +1,115 @@
+import { Millisecond, Minute } from "@darco2903/secondthought";
+export class ExpiryCacheBase {
+    /**
+     * Gets the expiration timestamp in milliseconds.
+     */
+    get expiresAt() {
+        return this._expiresAt.time;
+    }
+    /**
+     * Checks if the cache is set to expire.
+     */
+    get doesExpire() {
+        return this._expiresAt.time !== 0;
+    }
+    /**
+     * Checks if the cache is expired.
+     */
+    get isExpired() {
+        return this.doesExpire && Millisecond.now().greaterThanOrEqual(this._expiresAt);
+    }
+    /**
+     * Gets the time to live (TTL) in milliseconds.
+     */
+    get timeToLive() {
+        if (this.doesExpire) {
+            return Math.max(0, this._expiresAt.clone().subtract(Millisecond.now()).time);
+        }
+        return null;
+    }
+    /**
+     * Converts a number or Time object to milliseconds.
+     */
+    argToMs(arg) {
+        return typeof arg === "number" ? new Millisecond(arg) : arg.toMillisecond();
+    }
+    /**
+     * 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)) {
+        const expTime = this.argToMs(expirationTime);
+        this.data = data;
+        this._expiresAt = expTime.time === 0 ? expTime : Millisecond.now().add(expTime);
+        this.expirationTime = expTime.time;
+        this.callback = callback;
+    }
+    /**
+     * Expires the cache immediately.
+     */
+    expire() {
+        this._expiresAt = new Millisecond(-1);
+    }
+    /**
+     * Sets the cache to never expire.
+     */
+    neverExpire() {
+        this._expiresAt = new Millisecond(0);
+    }
+    expIn(ms) {
+        return ms.time === 0 ? ms : Millisecond.now().add(ms);
+    }
+    /**
+     * Sets the expiration timestamp based on the current time plus the given milliseconds.
+     * @param ms The time in milliseconds after which the cache should expire. If set to 0, the cache will never expire.
+     */
+    setExpiresIn(ms) {
+        const t = this.argToMs(ms);
+        this._expiresAt = this.expIn(t);
+    }
+    /**
+     * Sets the expiration timestamp to a specific time.
+     * @param timestamp The expiration timestamp in milliseconds.
+     */
+    setExpiresAt(timestamp) {
+        this._expiresAt = this.argToMs(timestamp);
+    }
+    /**
+     * Sets the cached data and resets the expiration timestamp based on the expiration time.
+     */
+    setData(data) {
+        this.setDataExpiresIn(data, new Millisecond(this.expirationTime));
+    }
+    /**
+     * Sets the cached data and sets a new expiration timestamp.
+     * @param expiresAt The new expiration timestamp in milliseconds.
+     */
+    setDataExpiresAt(data, expiresAt) {
+        this.data = data;
+        this._expiresAt = expiresAt;
+    }
+    /**
+     * Sets the cached data and sets a new expiration time.
+     * @param expirationTime The new expiration time in milliseconds.
+     */
+    setDataExpiresIn(data, expirationTime) {
+        this.setDataExpiresAt(data, this.expIn(expirationTime));
+    }
+    /**
+     * Gets the raw cached data without checking expiration.
+     */
+    getRawData() {
+        return this.data;
+    }
+    /**
+     * Gets the cached data if not expired, otherwise returns null.
+     */
+    getData() {
+        if (this.isExpired) {
+            return null;
+        }
+        return this.data;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ExpiryCache.js";
+export * from "./ExpiryCacheAsync.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./ExpiryCache.js";
+export * from "./ExpiryCacheAsync.js";

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export type RefreshFunction<T> = (...args: any[]) => T;
+export type RefreshFunctionAsync<T> = (...args: any[]) => Promise<T>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@darco2903/expiry-cache",
+  "version": "2.0.0-beta.0",
+  "author": "Darco2903",
+  "description": "",
+  "keywords": [],
+  "license": "ISC",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "repository": {
+    "url": "https://github.com/Darco2903/expiry-cache.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@darco2903/secondthought": "^1.1.0"
+  },
+  "devDependencies": {
+    "@darco2903/web-common": "^0.7.0",
+    "@vitest/ui": "^3.2.4",
+    "rimraf": "^6.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "clean": "rimraf -g dist darco2903-expiry-cache-*.tgz"
+  }
+}