@vicinae/api 0.19.8 → 0.20.0

package/dist/api/cache.d.ts

@@ -17,6 +17,20 @@ export declare namespace Cache {
          * The default capacity is 10 MB.
          */
         capacity?: number;
+        /**
+         * Default time-to-live in milliseconds for all keys.
+         * Individual keys can override this via the `ttl` option in {@link Cache.set}.
+         * If not set, keys do not expire, but are still subject to LRU eviction when the cache exceeds its capacity.
+         */
+        ttl?: number;
+    }
+    interface SetOptions {
+        /**
+         * Time-to-live in milliseconds for this key.
+         * Overrides the cache-level {@link Cache.Options.ttl}.
+         * If not set, the cache-level default is used. In both cases, keys are still subject to LRU eviction when the cache exceeds its capacity.
+         */
+        ttl?: number;
     }
     type Subscriber = (key: string | undefined, data: string | undefined) => void;
     type Subscription = () => void;
@@ -63,7 +77,7 @@ export declare class Cache {
      * This also notifies registered subscribers (see {@link subscribe}).
      * @remarks An individual cache entry cannot be bigger than the configured capacity. If this happens, an error will be thrown.
      */
-    set: (key: string, data: string) => void;
+    set: (key: string, data: string, options?: Cache.SetOptions) => void;
     /**
      * Removes the data for the given key.
      * This also notifies registered subscribers (see {@link subscribe}).
@@ -96,6 +110,8 @@ export declare class Cache {
     private loadIndex;
     private removeCacheDirectory;
     private syncIndex;
+    private isExpired;
+    private sweepExpired;
     private emptyIndex;
     /**
      * We store this inside the cache index file in order to know
@@ -105,6 +121,7 @@ export declare class Cache {
      */
     private revision;
     private capacity;
+    private defaultTtl?;
     private subscribers;
     private storageDir;
     private index;

package/dist/api/cache.js

@@ -25,6 +25,7 @@ class Cache {
     constructor(options) {
         this.storageDir = node_path_1.default.join(environment_1.environment.supportPath, Cache.CACHE_DIR_NAME);
         this.capacity = options?.capacity ?? Cache.DEFAULT_CACHE_SIZE;
+        this.defaultTtl = options?.ttl;
         if (options?.namespace) {
             this.storageDir = node_path_1.default.join(this.storageDir, options.namespace);
         }
@@ -33,6 +34,7 @@ class Cache {
         if (this.index.revision !== this.revision) {
             this.clear();
         }
+        this.sweepExpired();
     }
     /**
      * @returns the full path to the directory where the data is stored on disk.
@@ -51,6 +53,10 @@ class Cache {
         const info = this.index.keys[key];
         if (!info)
             return undefined;
+        if (this.isExpired(info)) {
+            this.remove(key);
+            return undefined;
+        }
         this.updateLRU(key);
         this.syncIndex();
         return this.readKeyData(key);
@@ -60,7 +66,14 @@ class Cache {
      * @remarks You can use this method to check for entries without affecting the LRU access.
      */
     has = (key) => {
-        return typeof this.index.keys[key] !== "undefined";
+        const info = this.index.keys[key];
+        if (!info)
+            return false;
+        if (this.isExpired(info)) {
+            this.remove(key);
+            return false;
+        }
+        return true;
     };
     /**
      * @returns whether the cache is empty.
@@ -74,7 +87,7 @@ class Cache {
      * This also notifies registered subscribers (see {@link subscribe}).
      * @remarks An individual cache entry cannot be bigger than the configured capacity. If this happens, an error will be thrown.
      */
-    set = (key, data) => {
+    set = (key, data, options) => {
         if (data.length > this.capacity) {
             throw new Error(`A single cache entry cannot be bigger than the total capacity of the cache. The data for key ${key} is ${data.length} bytes long while the capacity is set to ${this.capacity}. You should either reduce the amount of data stored or increase the cache's capacity.`);
         }
@@ -82,11 +95,13 @@ class Cache {
         const newTotalSize = this.index.size + data.length - (info?.size ?? 0);
         if (newTotalSize > this.capacity) {
             this.popLRU();
-            this.set(key, data); // FIXME: get rid of recursion
+            this.set(key, data, options); // FIXME: get rid of recursion
             return;
         }
+        const ttl = options?.ttl ?? this.defaultTtl;
+        const expiresAt = ttl !== undefined ? Date.now() + ttl : undefined;
         this.index.size = newTotalSize;
-        this.index.keys[key] = { size: data.length };
+        this.index.keys[key] = { size: data.length, expiresAt };
         this.updateLRU(key);
         this.writeKeyData(key, data);
         this.syncIndex();
@@ -198,6 +213,21 @@ class Cache {
     syncIndex() {
         (0, node_fs_1.writeFileSync)(this.indexPath, JSON.stringify(this.index, null, 2));
     }
+    isExpired(info) {
+        return info.expiresAt !== undefined && Date.now() > info.expiresAt;
+    }
+    sweepExpired() {
+        const expiredKeys = Object.entries(this.index.keys)
+            .filter(([, info]) => this.isExpired(info))
+            .map(([key]) => key);
+        for (const key of expiredKeys) {
+            this.removeImpl(key);
+        }
+        if (expiredKeys.length > 0) {
+            this.index.lru = this.index.lru.filter((entry) => !expiredKeys.includes(entry.key));
+            this.syncIndex();
+        }
+    }
     emptyIndex() {
         return { revision: this.revision, keys: {}, lru: [], size: 0 };
     }
@@ -209,6 +239,7 @@ class Cache {
      */
     revision = "1";
     capacity;
+    defaultTtl;
     subscribers = [];
     storageDir;
     index;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vicinae/api",
-	"version": "0.19.8",
+	"version": "0.20.0",
 	"description": "TypeScript SDK to build Vicinae extensions",
 	"scripts": {
 		"test": "echo \"Error: no test specified\" && exit 1",