btn-cache 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+import EventEmitter from "events";
+type BaseCacheOptions = {
+    evictionPolicy: "LRU" | "LFU" | "FIFO" | "RANDOM";
+    deleteOnExpire: boolean;
+    maxKeys: number;
+    useClones: boolean;
+    checkPeriod: number;
+};
+type invalidationPolicyOptions<T> = {
+    invalidationPolicy: "NONE";
+} | {
+    invalidationPolicy: "TTL";
+    stdTTL: number;
+} | {
+    invalidationPolicy: "EVENT";
+    predicate: (data: StoredData<T>) => boolean;
+};
+export type CacheOptions<T> = BaseCacheOptions & invalidationPolicyOptions<T>;
+export type CacheOptionsInput<T> = Partial<BaseCacheOptions> & ({
+    invalidationPolicy?: "NONE";
+} | {
+    invalidationPolicy?: "TTL";
+    stdTTL?: number;
+} | {
+    invalidationPolicy?: "EVENT";
+    predicate?: (data: StoredData<T>) => boolean;
+});
+export type CacheStats = {
+    keys: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+    ksize: number;
+    vsize: number;
+};
+export type StoredData<T> = {
+    value: T;
+    ttl?: number;
+    numberOfAccess: number;
+    lastAccessTimeStamp: number;
+};
+export type CacheEventMap<T> = {
+    set: [key: string | number, data: T];
+    get: [key: string | number, data: T];
+    del: [key: string | number, data?: T];
+    miss: [key: string | number];
+    expired: [key: string | number, cachedData: StoredData<T>];
+    error: [message: string];
+    evicted: [key: string | number, data?: T];
+    flush: [];
+    "flush-stats": [];
+};
+export declare class BTNCache<T = any> extends EventEmitter<CacheEventMap<T>> {
+    private data;
+    private options;
+    private stats;
+    private checkTimeout;
+    private queue;
+    /**
+     * Creates a new in memory cache using the options given to the constructor
+     * @param options the options object: \
+     * **evictionPolicy**: the type of eviction policy, one of RANDOM, LRU, LFU. (default: RANDOM)\
+     * **deleteOnExpire**: if the data gets deleted when it expires. \
+     * **maxKeys**: maximum amount of keys that can be stored in the cache, defaults to -1 (unlimited) \
+     * **useClones**: if the get and set operators copy the entered/received data or return a reference \
+     * **checkPeriod**: how often the cache runs an invalidation check. \
+     *
+     * **invalidationPolicy**: the type of invalidation policy, one of NONE, TTL or EVENT. (default: TTL) \
+     *
+     * When *invalidationPolicy == "TTL"*:
+     * **stdTTL**: the standard time to live on any data point unless specified other wise.
+     *
+     * When *invalidationPolicy == "EVENT"*:
+     * **predicate**: function that given a data point's state, returns if it should be considered invalid or not.
+     */
+    constructor(options?: CacheOptionsInput<T>);
+    /**
+     * Retrieves a data point from the cache
+     * @emits "miss" Indicates that a cache miss happened
+     * @emits "get" Indicates that a cache hit happened
+     * @param key Key of the data to retrieve
+     */
+    get(key: string | number): T | undefined;
+    /**
+     * Method to get many keys at once
+     * @emits "miss" Indicates that a cache miss happened
+     * @emits "get" Indicates that a cache hit happened
+     * @param keys Array of keys
+     * @returns
+     */
+    many_get(keys: (string | number)[]): {
+        [key: string]: T;
+        [key: number]: T;
+    };
+    /**
+     * Function to set a certain key in the cache.
+     * @param key   Key of the data to be set.
+     * @param data  The data to be entered into the cache.
+     * @param ttl   The TTL of the new data point, will be ignored if the invalidation policy isn't set to TTL
+     * @emits "set" Indicates that the data has been set successfully
+     * @returns
+     */
+    set(key: string | number, data: T, ttl?: number): boolean;
+    /**
+     * Function to add multiple data points to the cache
+     * @param keyValueSet All of the keys that will be added, optional ttl argument will be ignored if not in TTL invalidation mode.
+     * @emits "set" Indicates that a value has been set correctly.
+     */
+    many_set(keyValueSet: {
+        [key: string | number]: {
+            ttl?: number;
+            data: T;
+        };
+    }): void;
+    /**
+     * Function to get a key while removing it from the cache
+     * @param key Key to be taken out of the cache
+     * @returns value that was stored to that key
+     */
+    take(key: string | number): T | undefined;
+    /**
+     * Function to check if a key is present in the cache
+     * @param key key for the lookup
+     * @returns a boolean value specifying if the value is present.
+     */
+    has(key: string | number): boolean;
+    /**
+     * Function to delete a certain set of keys from the cache
+     * @emits "del" Indicates that the data has been deleted successfully
+     * @param keys The array of keys to be deleted.
+     * @returns Number of elements deleted from the cache.
+     */
+    del(keys: (string | number)[]): number;
+    /**
+     * Function to change the TTL of a given key in TTL mode
+     * @param key key to be changed
+     * @param newTTL the new TTL that will be assigned, if less than 0 key will be deleted.
+     * @returns boolean value representing if the change was successful
+     */
+    ttl(key: string | number, newTTL?: number): boolean;
+    /**
+     * Function to get metadata about the key, such as TTL, time since last accessed, number of accesses
+     * @param key key for the lookup
+     * @returns metadata information about the key.
+     */
+    getMeta(key: string | number): {
+        lastAccessTime: number;
+        numberOfAccesses: number;
+        ttl: number | undefined;
+    } | undefined;
+    /**
+     * Function to get the data of the cache
+     * @returns the statistics of the cache
+     */
+    getStats(): CacheStats;
+    /**
+     *  Function to flush all the data and the statistics of the cache
+     */
+    flushAll(): void;
+    /**
+     * Function to flush the statistics of the cache
+     */
+    flushStats(): void;
+    /**
+     * Function to change some of the settings of the cache
+     * @param newOptions
+     */
+    setSettings(newOptions: CacheOptionsInput<T>): void;
+    /**
+     * Function to close the cache.
+     */
+    close(): void;
+    /**
+     * Function that returns all the present keys in the cache
+     * @returns List of keys present in the cache.
+     */
+    keys(): (string | number)[];
+    /**
+     * Internal function to check the keys for expiration
+     * @param start decides if the next check will happen
+     */
+    private _checkClock;
+    /**
+     * This function will evict a data point based on the set options
+     * @param numberOfEvictions number of keys that will get evicted, defaults to 1
+     * @emits "error" will emit an error if an undefined key is trying to be evicted.
+     */
+    private _evictData;
+    /**
+     * Internal function that implements the RANDOM eviction policy
+     * @returns the key to be removed
+     */
+    private _evictRandom;
+    /**
+     * Internal function that implements the LRU eviction policy
+     * @returns the key to be removed
+     */
+    private _evictLRU;
+    /**
+     * Internal function that implements the LFU eviction policy
+     * @returns the key to be removed
+     */
+    private _evictLFU;
+    /**
+     * Internal function that implements the FIFO eviction policy
+     * @returns the key to be removed
+     */
+    private _evictFIFO;
+    /**
+     * Internal function to check if the cache is full, if so evict data according to the eviction policy
+     * @param [padding=0] How big the empty space should be.
+     */
+    private _checkAndEvict;
+    /**
+     * Internal method to roughly calculate the size of the value
+     * @param value Value to process its size
+     */
+    private _getDataLength;
+    /**
+     * Internal method to check if a data point is invalidated or not.
+     * @emits "expired" Indicates that some data has been invalidated.
+     * @param key   The key of the checked data
+     * @param data  The Stored data
+     * @returns If the data is invalidated or not
+     */
+    private _checkData;
+    /**
+     * Internal method to standardize the returns of getters.
+     * @param data The data to be unwrapped
+     * @param asClone Option if to return a copy of the data or a reference
+     */
+    private _unwrap;
+    /**
+     * Internal method to wrap any value into the stored value type.
+     * @param value     Value that will be wrapped
+     * @param ttl       Time to live, will be ignored if the invalidation policy is not set to "TTL"
+     * @param asClone   If the wrapped value is a clone or a reference to the original
+     */
+    private _wrap;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,507 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BTNCache = void 0;
+const events_1 = __importDefault(require("events"));
+const clone_1 = __importDefault(require("clone"));
+const DEFAULT_OPTIONS = {
+    evictionPolicy: "RANDOM",
+    deleteOnExpire: true,
+    maxKeys: -1,
+    invalidationPolicy: "TTL",
+    stdTTL: 500 * 1000,
+    useClones: true,
+    checkPeriod: 300 * 1000,
+};
+class BTNCache extends events_1.default {
+    /**
+     * Creates a new in memory cache using the options given to the constructor
+     * @param options the options object: \
+     * **evictionPolicy**: the type of eviction policy, one of RANDOM, LRU, LFU. (default: RANDOM)\
+     * **deleteOnExpire**: if the data gets deleted when it expires. \
+     * **maxKeys**: maximum amount of keys that can be stored in the cache, defaults to -1 (unlimited) \
+     * **useClones**: if the get and set operators copy the entered/received data or return a reference \
+     * **checkPeriod**: how often the cache runs an invalidation check. \
+     *
+     * **invalidationPolicy**: the type of invalidation policy, one of NONE, TTL or EVENT. (default: TTL) \
+     *
+     * When *invalidationPolicy == "TTL"*:
+     * **stdTTL**: the standard time to live on any data point unless specified other wise.
+     *
+     * When *invalidationPolicy == "EVENT"*:
+     * **predicate**: function that given a data point's state, returns if it should be considered invalid or not.
+     */
+    constructor(options = {}) {
+        super();
+        this.data = new Map();
+        this.queue = null;
+        this.options = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+        };
+        if (this.options.invalidationPolicy == "EVENT" &&
+            typeof this.options.predicate !== "function") {
+            throw new Error("EVENT invalidation requires a predicate");
+        }
+        if (this.options.evictionPolicy == "FIFO") {
+            this.queue = [];
+        }
+        this.stats = {
+            keys: 0,
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            ksize: 0,
+            vsize: 0,
+        };
+        this._checkClock();
+    }
+    /**
+     * Retrieves a data point from the cache
+     * @emits "miss" Indicates that a cache miss happened
+     * @emits "get" Indicates that a cache hit happened
+     * @param key Key of the data to retrieve
+     */
+    get(key) {
+        const found = this.data.get(key);
+        if (found && this._checkData(key, found)) {
+            this.stats.hits++;
+            found.numberOfAccess++;
+            found.lastAccessTimeStamp = Date.now();
+            this.emit("get", key, this._unwrap(found));
+            return this._unwrap(found);
+        }
+        else {
+            this.stats.misses++;
+            this.emit("miss", key);
+            return undefined;
+        }
+    }
+    /**
+     * Method to get many keys at once
+     * @emits "miss" Indicates that a cache miss happened
+     * @emits "get" Indicates that a cache hit happened
+     * @param keys Array of keys
+     * @returns
+     */
+    many_get(keys) {
+        let all_found = {};
+        for (const key of keys) {
+            const found = this.data.get(key);
+            if (found && this._checkData(key, found)) {
+                this.stats.hits++;
+                found.numberOfAccess++;
+                found.lastAccessTimeStamp = Date.now();
+                all_found[key] = this._unwrap(found);
+                this.emit("get", key, this._unwrap(found));
+            }
+            else {
+                this.stats.misses++;
+                this.emit("miss", key);
+            }
+        }
+        return all_found;
+    }
+    /**
+     * Function to set a certain key in the cache.
+     * @param key   Key of the data to be set.
+     * @param data  The data to be entered into the cache.
+     * @param ttl   The TTL of the new data point, will be ignored if the invalidation policy isn't set to TTL
+     * @emits "set" Indicates that the data has been set successfully
+     * @returns
+     */
+    set(key, data, ttl) {
+        this._checkAndEvict();
+        if (this.options.invalidationPolicy == "TTL" && !ttl) {
+            ttl = this.options.stdTTL;
+        }
+        let existent = false;
+        if (this.data.has(key)) {
+            existent = true;
+            this.stats.vsize -= this._getDataLength(data);
+        }
+        this.data.set(key, this._wrap(data, ttl));
+        this.stats.vsize += this._getDataLength(data);
+        if (this.options.evictionPolicy == "FIFO" && this.queue) {
+            this.queue.push(key);
+        }
+        if (!existent) {
+            this.stats.ksize += this._getDataLength(key);
+            this.stats.keys++;
+        }
+        this.emit("set", key, data);
+        return true;
+    }
+    /**
+     * Function to add multiple data points to the cache
+     * @param keyValueSet All of the keys that will be added, optional ttl argument will be ignored if not in TTL invalidation mode.
+     * @emits "set" Indicates that a value has been set correctly.
+     */
+    many_set(keyValueSet) {
+        this._checkAndEvict(Object.keys(keyValueSet).length);
+        for (const keyValuePair of Object.entries(keyValueSet)) {
+            const [key, { ttl, data }] = keyValuePair;
+            this.set(key, data, ttl);
+            this.emit("set", key, data);
+        }
+    }
+    /**
+     * Function to get a key while removing it from the cache
+     * @param key Key to be taken out of the cache
+     * @returns value that was stored to that key
+     */
+    take(key) {
+        const found = this.get(key);
+        if (found) {
+            this.del([key]);
+        }
+        return found;
+    }
+    /**
+     * Function to check if a key is present in the cache
+     * @param key key for the lookup
+     * @returns a boolean value specifying if the value is present.
+     */
+    has(key) {
+        const found = this.data.get(key);
+        if (!found)
+            return false;
+        return this._checkData(key, found);
+    }
+    /**
+     * Function to delete a certain set of keys from the cache
+     * @emits "del" Indicates that the data has been deleted successfully
+     * @param keys The array of keys to be deleted.
+     * @returns Number of elements deleted from the cache.
+     */
+    del(keys) {
+        let delCount = 0;
+        for (const key of keys) {
+            if (this.data.has(key)) {
+                const found = this.data.get(key);
+                this.stats.vsize -= this._getDataLength(found);
+                this.stats.ksize -= this._getDataLength(key);
+                this.stats.keys--;
+                delCount++;
+                this.data.delete(key);
+                if (this.options.evictionPolicy == "FIFO" && this.queue) {
+                    this.queue = this.queue.filter((k) => key !== k);
+                }
+                this.emit("del", key, found?.value);
+            }
+        }
+        return delCount;
+    }
+    /**
+     * Function to change the TTL of a given key in TTL mode
+     * @param key key to be changed
+     * @param newTTL the new TTL that will be assigned, if less than 0 key will be deleted.
+     * @returns boolean value representing if the change was successful
+     */
+    ttl(key, newTTL) {
+        if (this.options.invalidationPolicy !== "TTL")
+            return false;
+        if (!newTTL) {
+            newTTL = this.options.stdTTL;
+        }
+        const found = this.data.get(key);
+        if (found && this._checkData(key, found)) {
+            if (newTTL >= 0) {
+                this.data.set(key, this._wrap(found.value, newTTL, false));
+            }
+            else {
+                this.del([key]);
+            }
+            return true;
+        }
+        else {
+            return false;
+        }
+    }
+    /**
+     * Function to get metadata about the key, such as TTL, time since last accessed, number of accesses
+     * @param key key for the lookup
+     * @returns metadata information about the key.
+     */
+    getMeta(key) {
+        const found = this.data.get(key);
+        if (found && this._checkData(key, found)) {
+            return {
+                lastAccessTime: found.lastAccessTimeStamp,
+                numberOfAccesses: found.numberOfAccess,
+                ttl: found.ttl,
+            };
+        }
+    }
+    /**
+     * Function to get the data of the cache
+     * @returns the statistics of the cache
+     */
+    getStats() {
+        return this.stats;
+    }
+    /**
+     *  Function to flush all the data and the statistics of the cache
+     */
+    flushAll() {
+        this.data = new Map();
+        this.stats = {
+            keys: 0,
+            vsize: 0,
+            evictions: 0,
+            ksize: 0,
+            hits: 0,
+            misses: 0,
+        };
+        this.emit("flush");
+    }
+    /**
+     * Function to flush the statistics of the cache
+     */
+    flushStats() {
+        this.stats = {
+            keys: 0,
+            vsize: 0,
+            ksize: 0,
+            evictions: 0,
+            hits: 0,
+            misses: 0,
+        };
+        this.emit("flush-stats");
+    }
+    /**
+     * Function to change some of the settings of the cache
+     * @param newOptions
+     */
+    setSettings(newOptions) {
+        this.options = {
+            ...this.options,
+            ...newOptions,
+        };
+        this.emit("settings-change", this.options);
+    }
+    /**
+     * Function to close the cache.
+     */
+    close() {
+        if (this.checkTimeout)
+            clearTimeout(this.checkTimeout);
+    }
+    /**
+     * Function that returns all the present keys in the cache
+     * @returns List of keys present in the cache.
+     */
+    keys() {
+        const keys = [];
+        for (const key of this.data.keys()) {
+            keys.push(key);
+        }
+        return keys;
+    }
+    /**
+     * Internal function to check the keys for expiration
+     * @param start decides if the next check will happen
+     */
+    _checkClock(start = true) {
+        for (const [key, value] of this.data.entries()) {
+            this._checkData(key, value);
+        }
+        if (start && this.options.checkPeriod) {
+            this.checkTimeout = setTimeout(() => this._checkClock(start), this.options.checkPeriod);
+            this.checkTimeout.unref();
+        }
+        return;
+    }
+    /**
+     * This function will evict a data point based on the set options
+     * @param numberOfEvictions number of keys that will get evicted, defaults to 1
+     * @emits "error" will emit an error if an undefined key is trying to be evicted.
+     */
+    _evictData(numberOfEvictions = 1) {
+        const evictors = {
+            FIFO: () => this._evictFIFO(),
+            LRU: () => this._evictLRU(),
+            LFU: () => this._evictLFU(),
+            RANDOM: () => this._evictRandom(),
+        };
+        let evicted = undefined;
+        for (let i = 0; i < numberOfEvictions; i++) {
+            evicted = evictors[this.options.evictionPolicy]();
+            if (evicted === undefined) {
+                this.emit("error", "ERROR_UNDEFINED_EVICTION");
+                break;
+            }
+            this.emit("evicted", evicted, this.get(evicted));
+            this.del([evicted]);
+            this.stats.evictions++;
+        }
+    }
+    /**
+     * Internal function that implements the RANDOM eviction policy
+     * @returns the key to be removed
+     */
+    _evictRandom() {
+        const keys = this.keys();
+        if (keys.length === 0)
+            return undefined;
+        const evictedIndex = Math.floor(Math.random() * keys.length);
+        return keys[evictedIndex];
+    }
+    /**
+     * Internal function that implements the LRU eviction policy
+     * @returns the key to be removed
+     */
+    _evictLRU() {
+        const now = Date.now();
+        return this.keys().reduce((accumulator, current) => {
+            const meta = this.getMeta(current);
+            if (!meta)
+                return accumulator;
+            const difference = now - meta.lastAccessTime;
+            if (!accumulator || difference >= accumulator.difference) {
+                return {
+                    key: current,
+                    difference,
+                };
+            }
+            return accumulator;
+        }, undefined)?.key;
+    }
+    /**
+     * Internal function that implements the LFU eviction policy
+     * @returns the key to be removed
+     */
+    _evictLFU() {
+        return this.keys().reduce((accumulator, current) => {
+            const meta = this.getMeta(current);
+            if (!meta)
+                return accumulator;
+            if (!accumulator || meta.numberOfAccesses <= accumulator.minimum) {
+                return {
+                    key: current,
+                    minimum: meta.numberOfAccesses,
+                };
+            }
+            return accumulator;
+        }, undefined)?.key;
+    }
+    /**
+     * Internal function that implements the FIFO eviction policy
+     * @returns the key to be removed
+     */
+    _evictFIFO() {
+        if (this.queue) {
+            return this.queue.shift();
+        }
+    }
+    /**
+     * Internal function to check if the cache is full, if so evict data according to the eviction policy
+     * @param [padding=0] How big the empty space should be.
+     */
+    _checkAndEvict(padding = 1) {
+        if (this.options.maxKeys < 0)
+            return;
+        const overflow = this.stats.keys + padding - this.options.maxKeys;
+        if (overflow > 0) {
+            this._evictData(overflow);
+        }
+    }
+    /**
+     * Internal method to roughly calculate the size of the value
+     * @param value Value to process its size
+     */
+    _getDataLength(value) {
+        if (typeof value === "string") {
+            return value.length;
+        }
+        else if (typeof value === "number") {
+            return 8;
+        }
+        else {
+            return JSON.stringify(value).length;
+        }
+    }
+    /**
+     * Internal method to check if a data point is invalidated or not.
+     * @emits "expired" Indicates that some data has been invalidated.
+     * @param key   The key of the checked data
+     * @param data  The Stored data
+     * @returns If the data is invalidated or not
+     */
+    _checkData(key, data) {
+        let returnValue = true;
+        const deleteAndEmit = () => {
+            if (this.options.deleteOnExpire) {
+                returnValue = false;
+                this.del([key]);
+            }
+            this.emit("expired", key, data);
+        };
+        if (this.options.invalidationPolicy === "TTL") {
+            if (data.ttl && data.ttl < Date.now()) {
+                deleteAndEmit();
+            }
+        }
+        else if (this.options.invalidationPolicy === "EVENT") {
+            const predicateResult = this.options.predicate(data);
+            if (predicateResult) {
+                deleteAndEmit();
+            }
+        }
+        return returnValue;
+    }
+    /**
+     * Internal method to standardize the returns of getters.
+     * @param data The data to be unwrapped
+     * @param asClone Option if to return a copy of the data or a reference
+     */
+    _unwrap(data, asClone = true) {
+        if (!this.options.useClones) {
+            asClone = false;
+        }
+        if (asClone)
+            return (0, clone_1.default)(data.value);
+        else
+            return data.value;
+    }
+    /**
+     * Internal method to wrap any value into the stored value type.
+     * @param value     Value that will be wrapped
+     * @param ttl       Time to live, will be ignored if the invalidation policy is not set to "TTL"
+     * @param asClone   If the wrapped value is a clone or a reference to the original
+     */
+    _wrap(value, ttl, asClone = true) {
+        if (!this.options.useClones) {
+            asClone = false;
+        }
+        const now = Date.now();
+        let lifetime = -1;
+        if (this.options.invalidationPolicy === "TTL") {
+            const TTLMultiplication = 1;
+            if (ttl == 0) {
+                lifetime = 0;
+            }
+            else if (ttl) {
+                lifetime = now + ttl * TTLMultiplication;
+            }
+            else {
+                if (this.options.stdTTL == 0) {
+                    lifetime = 0;
+                }
+                else {
+                    lifetime = now + this.options.stdTTL * TTLMultiplication;
+                }
+            }
+        }
+        const returned = {
+            value: asClone ? (0, clone_1.default)(value) : value,
+            ttl: lifetime,
+            numberOfAccess: 0,
+            lastAccessTimeStamp: now,
+        };
+        return returned;
+    }
+}
+exports.BTNCache = BTNCache;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "btn-cache",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Type safe implementation of in-memory caching inspired by node-cache",
+  "keywords": [
+    "caching",
+    "in-memory",
+    "backend",
+    "server-side",
+    "server",
+    "library",
+    "lightweight",
+    "light",
+    "simple"
+  ],
+  "author": "imaaann",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@types/clone": "^2.1.4",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "clone": "^2.1.2"
+  }
+}