@nebulaaa/lru 0.0.0-stage → 1.1.0

package/dist/lru.cjs

@@ -0,0 +1,213 @@
+'use strict';
+
+/**
+ * LRU (Least Recently Used) 缓存
+ *
+ * 最近最少使用淘汰策略的缓存实现
+ */
+class LRU {
+    constructor(capacity) {
+        // Number.isInteger 一并拦截 NaN / Infinity / 小数：NaN 时 size > NaN 恒为 false，缓存永不淘汰
+        if (!Number.isInteger(capacity) || capacity <= 0) {
+            throw new Error('LRU capacity must be an integer greater than 0');
+        }
+        this._capacity = capacity;
+        this._cache = new Map();
+        this._head = null;
+        this._tail = null;
+    }
+    /**
+     * 获取缓存值，并提升为最近使用
+     * 注意：未命中返回 null；若业务可能存入 null 值，返回值无法与未命中区分，请用 Has 判断
+     */
+    Get(key) {
+        const node = this._cache.get(key);
+        if (!node) {
+            return null;
+        }
+        // 移动到头部（标记为最近使用）
+        this.moveToHead(node);
+        return node.Value;
+    }
+    /**
+     * 读取缓存值，但不提升新鲜度（不改变淘汰顺序）
+     * 注意：未命中返回 null，与存入的 null 值无法区分，请用 Has 判断
+     */
+    Peek(key) {
+        const node = this._cache.get(key);
+        return node ? node.Value : null;
+    }
+    /**
+     * 读取缓存值，未命中时用 creator 计算并写入缓存（写入视为最近使用）
+     * 注意：creator 抛出的异常会向上传播，不会写入缓存
+     */
+    GetOrSet(key, creator) {
+        const node = this._cache.get(key);
+        if (node) {
+            this.moveToHead(node);
+            return node.Value;
+        }
+        const value = creator(key);
+        this.Set(key, value);
+        return value;
+    }
+    /**
+     * 设置缓存值
+     */
+    Set(key, value) {
+        const existing = this._cache.get(key);
+        if (existing) {
+            // 更新现有节点
+            existing.Value = value;
+            this.moveToHead(existing);
+            return;
+        }
+        // 创建新节点
+        const node = {
+            Key: key,
+            Value: value,
+            Prev: null,
+            Next: null,
+        };
+        // 添加到缓存
+        this._cache.set(key, node);
+        this.addToHead(node);
+        // 检查容量，淘汰最久未使用的节点
+        if (this._cache.size > this._capacity) {
+            this.removeTail();
+        }
+    }
+    /**
+     * 检查是否包含键
+     */
+    Has(key) {
+        return this._cache.has(key);
+    }
+    /**
+     * 删除缓存值
+     */
+    Delete(key) {
+        const node = this._cache.get(key);
+        if (!node) {
+            return false;
+        }
+        this._cache.delete(key);
+        this.removeNode(node);
+        return true;
+    }
+    /**
+     * 清空缓存
+     */
+    Clear() {
+        this._cache.clear();
+        this._head = null;
+        this._tail = null;
+    }
+    /**
+     * 获取缓存大小
+     */
+    get Size() {
+        return this._cache.size;
+    }
+    /**
+     * 获取缓存容量
+     */
+    get Capacity() {
+        return this._capacity;
+    }
+    /**
+     * 添加节点到头部
+     */
+    addToHead(node) {
+        node.Prev = null;
+        node.Next = this._head;
+        if (this._head) {
+            this._head.Prev = node;
+        }
+        this._head = node;
+        if (!this._tail) {
+            this._tail = node;
+        }
+    }
+    /**
+     * 移动节点到头部
+     */
+    moveToHead(node) {
+        // 先移除节点
+        this.removeNode(node);
+        // 添加到头部
+        this.addToHead(node);
+    }
+    /**
+     * 移除节点
+     */
+    removeNode(node) {
+        if (node.Prev) {
+            node.Prev.Next = node.Next;
+        }
+        else {
+            this._head = node.Next;
+        }
+        if (node.Next) {
+            node.Next.Prev = node.Prev;
+        }
+        else {
+            this._tail = node.Prev;
+        }
+    }
+    /**
+     * 移除尾部节点（最久未使用）
+     */
+    removeTail() {
+        if (!this._tail) {
+            return;
+        }
+        this._cache.delete(this._tail.Key);
+        this.removeNode(this._tail);
+    }
+    /**
+     * 获取所有键（按最近使用到最久使用排序，与 values() / forEach() 同序）
+     */
+    Keys() {
+        const result = [];
+        let node = this._head;
+        while (node) {
+            result.push(node.Key);
+            node = node.Next;
+        }
+        return result;
+    }
+    /**
+     * 获取所有值
+     */
+    Values() {
+        const result = [];
+        let node = this._head;
+        while (node) {
+            result.push(node.Value);
+            node = node.Next;
+        }
+        return result;
+    }
+    /**
+     * 遍历缓存（按最近使用到最久使用）
+     * 注意：内部为快照遍历，回调中增删改/清空缓存是安全的——已被删除或淘汰的条目不再回调，
+     * 遍历期间新增的条目不参与本次遍历
+     */
+    Each(callback) {
+        const snapshot = [];
+        let node = this._head;
+        while (node) {
+            snapshot.push(node);
+            node = node.Next;
+        }
+        for (const item of snapshot) {
+            // 节点身份校验：Set 更新已有键不会更换节点，仍会回调；Delete 后重设的同键新节点则跳过
+            if (this._cache.get(item.Key) === item) {
+                callback(item.Value, item.Key);
+            }
+        }
+    }
+}
+
+exports.LRU = LRU;

package/dist/lru.d.ts

@@ -0,0 +1,98 @@
+/**
+ * LRU 缓存节点
+ */
+interface LRUNode<K, V> {
+    Key: K;
+    Value: V;
+    Prev: LRUNode<K, V> | null;
+    Next: LRUNode<K, V> | null;
+}
+
+/**
+ * LRU (Least Recently Used) 缓存
+ *
+ * 最近最少使用淘汰策略的缓存实现
+ */
+declare class LRU<K, V> {
+    /** 容量 */
+    private _capacity;
+    /** 存储 Map */
+    private _cache;
+    /** 头节点（最近使用） */
+    private _head;
+    /** 尾节点（最久未使用） */
+    private _tail;
+    constructor(capacity: number);
+    /**
+     * 获取缓存值，并提升为最近使用
+     * 注意：未命中返回 null；若业务可能存入 null 值，返回值无法与未命中区分，请用 Has 判断
+     */
+    Get(key: K): V | null;
+    /**
+     * 读取缓存值，但不提升新鲜度（不改变淘汰顺序）
+     * 注意：未命中返回 null，与存入的 null 值无法区分，请用 Has 判断
+     */
+    Peek(key: K): V | null;
+    /**
+     * 读取缓存值，未命中时用 creator 计算并写入缓存（写入视为最近使用）
+     * 注意：creator 抛出的异常会向上传播，不会写入缓存
+     */
+    GetOrSet(key: K, creator: (key: K) => V): V;
+    /**
+     * 设置缓存值
+     */
+    Set(key: K, value: V): void;
+    /**
+     * 检查是否包含键
+     */
+    Has(key: K): boolean;
+    /**
+     * 删除缓存值
+     */
+    Delete(key: K): boolean;
+    /**
+     * 清空缓存
+     */
+    Clear(): void;
+    /**
+     * 获取缓存大小
+     */
+    get Size(): number;
+    /**
+     * 获取缓存容量
+     */
+    get Capacity(): number;
+    /**
+     * 添加节点到头部
+     */
+    private addToHead;
+    /**
+     * 移动节点到头部
+     */
+    private moveToHead;
+    /**
+     * 移除节点
+     */
+    private removeNode;
+    /**
+     * 移除尾部节点（最久未使用）
+     */
+    private removeTail;
+    /**
+     * 获取所有键（按最近使用到最久使用排序，与 values() / forEach() 同序）
+     */
+    Keys(): K[];
+    /**
+     * 获取所有值
+     */
+    Values(): V[];
+    /**
+     * 遍历缓存（按最近使用到最久使用）
+     * 注意：内部为快照遍历，回调中增删改/清空缓存是安全的——已被删除或淘汰的条目不再回调，
+     * 遍历期间新增的条目不参与本次遍历
+     */
+    Each(callback: (value: V, key: K) => void): void;
+}
+
+export { LRU };
+export type { LRUNode };

package/dist/lru.min.cjs

@@ -0,0 +1 @@
+"use strict";exports.LRU=class{constructor(e){if(!Number.isInteger(e)||e<=0)throw new Error("LRU capacity must be an integer greater than 0");this._capacity=e,this._cache=new Map,this._head=null,this._tail=null}Get(e){const t=this._cache.get(e);return t?(this.moveToHead(t),t.Value):null}Peek(e){const t=this._cache.get(e);return t?t.Value:null}GetOrSet(e,t){const h=this._cache.get(e);if(h)return this.moveToHead(h),h.Value;const s=t(e);return this.Set(e,s),s}Set(e,t){const h=this._cache.get(e);if(h)return h.Value=t,void this.moveToHead(h);const s={Key:e,Value:t,Prev:null,Next:null};this._cache.set(e,s),this.addToHead(s),this._cache.size>this._capacity&&this.removeTail()}Has(e){return this._cache.has(e)}Delete(e){const t=this._cache.get(e);return!!t&&(this._cache.delete(e),this.removeNode(t),!0)}Clear(){this._cache.clear(),this._head=null,this._tail=null}get Size(){return this._cache.size}get Capacity(){return this._capacity}addToHead(e){e.Prev=null,e.Next=this._head,this._head&&(this._head.Prev=e),this._head=e,this._tail||(this._tail=e)}moveToHead(e){this.removeNode(e),this.addToHead(e)}removeNode(e){e.Prev?e.Prev.Next=e.Next:this._head=e.Next,e.Next?e.Next.Prev=e.Prev:this._tail=e.Prev}removeTail(){this._tail&&(this._cache.delete(this._tail.Key),this.removeNode(this._tail))}Keys(){const e=[];let t=this._head;for(;t;)e.push(t.Key),t=t.Next;return e}Values(){const e=[];let t=this._head;for(;t;)e.push(t.Value),t=t.Next;return e}Each(e){const t=[];let h=this._head;for(;h;)t.push(h),h=h.Next;for(const h of t)this._cache.get(h.Key)===h&&e(h.Value,h.Key)}};

package/dist/lru.min.mjs

@@ -0,0 +1 @@
+class e{constructor(e){if(!Number.isInteger(e)||e<=0)throw new Error("LRU capacity must be an integer greater than 0");this._capacity=e,this._cache=new Map,this._head=null,this._tail=null}Get(e){const t=this._cache.get(e);return t?(this.moveToHead(t),t.Value):null}Peek(e){const t=this._cache.get(e);return t?t.Value:null}GetOrSet(e,t){const h=this._cache.get(e);if(h)return this.moveToHead(h),h.Value;const a=t(e);return this.Set(e,a),a}Set(e,t){const h=this._cache.get(e);if(h)return h.Value=t,void this.moveToHead(h);const a={Key:e,Value:t,Prev:null,Next:null};this._cache.set(e,a),this.addToHead(a),this._cache.size>this._capacity&&this.removeTail()}Has(e){return this._cache.has(e)}Delete(e){const t=this._cache.get(e);return!!t&&(this._cache.delete(e),this.removeNode(t),!0)}Clear(){this._cache.clear(),this._head=null,this._tail=null}get Size(){return this._cache.size}get Capacity(){return this._capacity}addToHead(e){e.Prev=null,e.Next=this._head,this._head&&(this._head.Prev=e),this._head=e,this._tail||(this._tail=e)}moveToHead(e){this.removeNode(e),this.addToHead(e)}removeNode(e){e.Prev?e.Prev.Next=e.Next:this._head=e.Next,e.Next?e.Next.Prev=e.Prev:this._tail=e.Prev}removeTail(){this._tail&&(this._cache.delete(this._tail.Key),this.removeNode(this._tail))}Keys(){const e=[];let t=this._head;for(;t;)e.push(t.Key),t=t.Next;return e}Values(){const e=[];let t=this._head;for(;t;)e.push(t.Value),t=t.Next;return e}Each(e){const t=[];let h=this._head;for(;h;)t.push(h),h=h.Next;for(const h of t)this._cache.get(h.Key)===h&&e(h.Value,h.Key)}}export{e as LRU};

package/dist/lru.mjs

@@ -0,0 +1,211 @@
+/**
+ * LRU (Least Recently Used) 缓存
+ *
+ * 最近最少使用淘汰策略的缓存实现
+ */
+class LRU {
+    constructor(capacity) {
+        // Number.isInteger 一并拦截 NaN / Infinity / 小数：NaN 时 size > NaN 恒为 false，缓存永不淘汰
+        if (!Number.isInteger(capacity) || capacity <= 0) {
+            throw new Error('LRU capacity must be an integer greater than 0');
+        }
+        this._capacity = capacity;
+        this._cache = new Map();
+        this._head = null;
+        this._tail = null;
+    }
+    /**
+     * 获取缓存值，并提升为最近使用
+     * 注意：未命中返回 null；若业务可能存入 null 值，返回值无法与未命中区分，请用 Has 判断
+     */
+    Get(key) {
+        const node = this._cache.get(key);
+        if (!node) {
+            return null;
+        }
+        // 移动到头部（标记为最近使用）
+        this.moveToHead(node);
+        return node.Value;
+    }
+    /**
+     * 读取缓存值，但不提升新鲜度（不改变淘汰顺序）
+     * 注意：未命中返回 null，与存入的 null 值无法区分，请用 Has 判断
+     */
+    Peek(key) {
+        const node = this._cache.get(key);
+        return node ? node.Value : null;
+    }
+    /**
+     * 读取缓存值，未命中时用 creator 计算并写入缓存（写入视为最近使用）
+     * 注意：creator 抛出的异常会向上传播，不会写入缓存
+     */
+    GetOrSet(key, creator) {
+        const node = this._cache.get(key);
+        if (node) {
+            this.moveToHead(node);
+            return node.Value;
+        }
+        const value = creator(key);
+        this.Set(key, value);
+        return value;
+    }
+    /**
+     * 设置缓存值
+     */
+    Set(key, value) {
+        const existing = this._cache.get(key);
+        if (existing) {
+            // 更新现有节点
+            existing.Value = value;
+            this.moveToHead(existing);
+            return;
+        }
+        // 创建新节点
+        const node = {
+            Key: key,
+            Value: value,
+            Prev: null,
+            Next: null,
+        };
+        // 添加到缓存
+        this._cache.set(key, node);
+        this.addToHead(node);
+        // 检查容量，淘汰最久未使用的节点
+        if (this._cache.size > this._capacity) {
+            this.removeTail();
+        }
+    }
+    /**
+     * 检查是否包含键
+     */
+    Has(key) {
+        return this._cache.has(key);
+    }
+    /**
+     * 删除缓存值
+     */
+    Delete(key) {
+        const node = this._cache.get(key);
+        if (!node) {
+            return false;
+        }
+        this._cache.delete(key);
+        this.removeNode(node);
+        return true;
+    }
+    /**
+     * 清空缓存
+     */
+    Clear() {
+        this._cache.clear();
+        this._head = null;
+        this._tail = null;
+    }
+    /**
+     * 获取缓存大小
+     */
+    get Size() {
+        return this._cache.size;
+    }
+    /**
+     * 获取缓存容量
+     */
+    get Capacity() {
+        return this._capacity;
+    }
+    /**
+     * 添加节点到头部
+     */
+    addToHead(node) {
+        node.Prev = null;
+        node.Next = this._head;
+        if (this._head) {
+            this._head.Prev = node;
+        }
+        this._head = node;
+        if (!this._tail) {
+            this._tail = node;
+        }
+    }
+    /**
+     * 移动节点到头部
+     */
+    moveToHead(node) {
+        // 先移除节点
+        this.removeNode(node);
+        // 添加到头部
+        this.addToHead(node);
+    }
+    /**
+     * 移除节点
+     */
+    removeNode(node) {
+        if (node.Prev) {
+            node.Prev.Next = node.Next;
+        }
+        else {
+            this._head = node.Next;
+        }
+        if (node.Next) {
+            node.Next.Prev = node.Prev;
+        }
+        else {
+            this._tail = node.Prev;
+        }
+    }
+    /**
+     * 移除尾部节点（最久未使用）
+     */
+    removeTail() {
+        if (!this._tail) {
+            return;
+        }
+        this._cache.delete(this._tail.Key);
+        this.removeNode(this._tail);
+    }
+    /**
+     * 获取所有键（按最近使用到最久使用排序，与 values() / forEach() 同序）
+     */
+    Keys() {
+        const result = [];
+        let node = this._head;
+        while (node) {
+            result.push(node.Key);
+            node = node.Next;
+        }
+        return result;
+    }
+    /**
+     * 获取所有值
+     */
+    Values() {
+        const result = [];
+        let node = this._head;
+        while (node) {
+            result.push(node.Value);
+            node = node.Next;
+        }
+        return result;
+    }
+    /**
+     * 遍历缓存（按最近使用到最久使用）
+     * 注意：内部为快照遍历，回调中增删改/清空缓存是安全的——已被删除或淘汰的条目不再回调，
+     * 遍历期间新增的条目不参与本次遍历
+     */
+    Each(callback) {
+        const snapshot = [];
+        let node = this._head;
+        while (node) {
+            snapshot.push(node);
+            node = node.Next;
+        }
+        for (const item of snapshot) {
+            // 节点身份校验：Set 更新已有键不会更换节点，仍会回调；Delete 后重设的同键新节点则跳过
+            if (this._cache.get(item.Key) === item) {
+                callback(item.Value, item.Key);
+            }
+        }
+    }
+}
+
+export { LRU };

package/dist/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nebulaaa/lru",
+  "version": "1.1.0",
+  "description": "LRU",
+  "author": "doooreyn",
+  "license": "MIT",
+  "keywords": [
+    "lru",
+    "nebulaaa"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "main": "./lru.cjs",
+  "module": "./lru.mjs",
+  "types": "./lru.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lru.d.ts",
+      "require": "./lru.cjs",
+      "import": "./lru.mjs",
+      "default": "./lru.cjs"
+    },
+    "./min": {
+      "require": "./lru.min.cjs",
+      "import": "./lru.min.mjs"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/package.json

@@ -1,6 +1,66 @@
-{
-  "name": "@nebulaaa/lru",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@nebulaaa/lru",
+  "version": "1.1.0",
+  "description": "LRU",
+  "main": "./dist/lru.cjs",
+  "module": "./dist/lru.mjs",
+  "types": "./dist/lru.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/lru.cjs",
+      "import": "./dist/lru.mjs",
+      "types": "./dist/lru.d.ts",
+      "default": "./dist/lru.cjs"
+    },
+    "./min": {
+      "require": "./dist/lru.min.cjs",
+      "import": "./dist/lru.min.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && rollup -c rollup.config.mjs && node ../scripts/write-dist-package.mjs lru",
+    "test": "jest"
+  },
+  "keywords": [
+    "lru",
+    "nebulaaa"
+  ],
+  "author": "doooreyn",
+  "license": "MIT",
+  "devEngines": {
+    "packageManager": {
+      "name": "npm",
+      "version": ">=10.0.0",
+      "onFail": "warn"
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "allowScripts": {
+    "unrs-resolver@1.12.2": true,
+    "@parcel/watcher@2.6.0": true
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.2",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.2",
+    "jest": "^30.5.2",
+    "rollup": "^4.28.1",
+    "rollup-plugin-dts": "^6.1.1",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "5.7.3"
+  },
+  "dependencies": {}
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.