@appweaver/core 1.0.0

package/cache/cache-service.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheService = void 0;
+const common_1 = require("@appweaver/common");
+const flatted_1 = require("flatted");
+const context_1 = require("../context");
+class CacheService {
+    /** @internal */
+    _cache = (0, context_1.inject)(common_1.Cache);
+    /**
+     * Retrieves the cache instance associated with this service.
+     *
+     * @return {Cache} The current cache instance.
+     */
+    get cache() {
+        return this._cache;
+    }
+    /**
+     * Retrieves a cached value associated with the specified key.
+     *
+     * @param {string} key - The key used to look up the cached value.
+     * @return A promise that resolves to the cached value if the key exists, or null if the key is not found.
+     */
+    async getCachedValue(key) {
+        const exists = await this._cache.has(key);
+        if (exists) {
+            common_1.logger.debug({ key }, 'Retrieved value from cache');
+            return this._cache.get(key);
+        }
+        return null;
+    }
+    /**
+     * Adds a key-value pair to the cache if the key does not already exist.
+     * Optionally allows specifying a time-to-live (TTL) for the cached item.
+     *
+     * @param {string} key - The unique key to identify the value in the cache.
+     * @param {Object} value - The value to store in the cache.
+     * @param {number} [ttl] - Optional time-to-live for the cache entry in seconds.
+     * @param {boolean} [replace=false] - Optional flag that indicates if the existing cache entry should be replaced
+     * with the new value and ttl.
+     * @return {Promise<boolean>} A promise that resolves to true if the key-value pair was added, or false if the key
+     * already exists.
+     */
+    async addToCache(key, value, ttl, replace = false) {
+        const exists = await this._cache.has(key);
+        if (exists && !replace) {
+            return false;
+        }
+        common_1.logger.debug({ key, ttl, replace }, 'Added value to cache');
+        return this._cache.set(key, value, ttl);
+    }
+    /**
+     * Removes a cached value associated with the specified key from the cache store.
+     *
+     * @param {string} key - The key associated with the cached value to be removed.
+     * @return {Promise<boolean>} A promise that resolves to `true` if the value was successfully removed, or
+     * `false` otherwise.
+     */
+    async removeCachedValue(key) {
+        const removed = await this._cache.evict(key);
+        if (removed) {
+            common_1.logger.debug({ key }, 'Removed value from cache');
+        }
+        return removed;
+    }
+    /**
+     * Invalidates the cache for the specified model and action type based on the configured cache invalidation strategy.
+     *
+     * @param {string} modelName - The name of the model whose cache needs to be invalidated.
+     * @param {Extract<ActionType, 'create' | 'update' | 'delete' | 'uploadFiles' | 'deleteFiles'>} action - The action type
+     * that triggered the cache invalidation (e.g., 'create', 'update', 'delete', 'uploadFiles', or 'fileDelete').
+     * @return {Promise<void>} Resolves when the cache invalidation process is completed.
+     */
+    async invalidateCache(modelName, action) {
+        if (!common_1.config.CACHE_ENABLED) {
+            return;
+        }
+        const strategy = common_1.config.CACHE_INVALIDATION_STRATEGY;
+        common_1.logger.debug({ modelName, action, strategy }, `Invalidating resource cache`);
+        let invalidation;
+        switch (strategy) {
+            case common_1.CacheInvalidationStrategy.ExpireRelated:
+                invalidation = this._cache.expire(`*!${modelName}!*:inv`);
+                break;
+            case common_1.CacheInvalidationStrategy.ExpireAll:
+                invalidation = this._cache.expire(`*:inv`);
+                break;
+        }
+        if (invalidation) {
+            if (common_1.config.CACHE_INVALIDATION_DEFERRED) {
+                void invalidation.catch((error) => {
+                    common_1.logger.error(error, 'Cache invalidation error');
+                });
+            }
+            else {
+                try {
+                    await invalidation;
+                }
+                catch (error) {
+                    common_1.logger.error(error, 'Cache invalidation error');
+                }
+            }
+        }
+    }
+    /**
+     * Builds a unique cache key based on the provided input parameters. The key is constructed
+     * using properties such as the base key, HTTP method, URL, request body, model name, and any
+     * associated relations. It also includes optional user-specific data and cache invalidation settings.
+     *
+     * @param {Object} data Input data for constructing the cache key.
+     * @param {string} data.baseKey The base key that serves as the starting point of the cache key.
+     * @param {string} [data.method] The HTTP method (e.g., GET, POST) associated with the key.
+     * @param {string} [data.url] The URL associated with the request.
+     * @param {string} [data.body] The stringified request body, which will be hashed if present.
+     * @param {string} [data.modelName] The name of the model to associate with the cache key.
+     * @param {string[]} [data.relations] A list of related model names to associate with the cache key.
+     * @param {boolean} [data.skipInvalidation] Whether to skip invalidation logic for this cache key.
+     * @param {AuthUser} [data.authUser] The authenticated user information, if applicable, to create user-specific keys.
+     * @return {string} The generated cache key string.
+     */
+    buildCacheKey(data) {
+        const userPrefix = data.authUser ? data.authUser.id : '';
+        const bodyHash = data.body ? (0, common_1.makeHash)((0, flatted_1.stringify)(data.body)) : '';
+        // Extract model relations based on route cache config so they can be used to
+        // evict cache entries when related data changes
+        const allRelations = [];
+        if (data.relations?.[0] === '*' || data.modelName) {
+            if (data.modelName) {
+                // Add all relations from a specified model
+                const model = (0, context_1.injectModel)(data.modelName, false);
+                if (model) {
+                    allRelations.push(...this.collectAllRelations(model));
+                }
+            }
+            else {
+                // Add all defined models as relations
+                for (const model of context_1.context.resource.models.values()) {
+                    for (const relation of Object.values(model.config.relations ?? {})) {
+                        allRelations.push(relation.model);
+                    }
+                }
+            }
+        }
+        else if (data.relations && data.relations.length > 1) {
+            allRelations.push(...data.relations);
+        }
+        // Create a list of unique relation names
+        const relations = [...new Set(allRelations)];
+        const relationList = relations.length > 0 ? `!${relations.join('!')}!` : '';
+        const invalidateSuffix = data.skipInvalidation ? '' : 'inv';
+        return [
+            data.baseKey,
+            userPrefix,
+            data.method,
+            data.url,
+            bodyHash,
+            relationList,
+            invalidateSuffix
+        ]
+            .filter((v) => !!v)
+            .join(':');
+    }
+    /** @internal */
+    collectAllRelations(model) {
+        const relations = [];
+        // Add the model itself as a relation
+        relations.push(model.name);
+        // Traverse top-level relations (using their own output config)
+        for (const relation of Object.values(model.config.relations ?? {})) {
+            const outputType = relation.output?.type;
+            if (outputType === 'none') {
+                continue;
+            }
+            relations.push(relation.model);
+            // Traverse nested includes (if any)
+            if (relation.output?.include) {
+                this.traverseInclude(relation.output.include, model, relations);
+            }
+        }
+        return relations;
+    }
+    /** @internal */
+    traverseInclude(include, model, acc) {
+        const relations = model.config.relations ?? {};
+        for (const [relKey, includeConfig] of Object.entries(include)) {
+            const type = includeConfig.type;
+            if (type === 'none') {
+                continue;
+            }
+            const relationDef = relations[relKey];
+            if (!relationDef) {
+                continue;
+            }
+            acc.push(relationDef.model);
+            // If this include has nested includes, recurse
+            if (includeConfig.include) {
+                this.traverseInclude(includeConfig.include, model, acc);
+            }
+        }
+    }
+}
+exports.CacheService = CacheService;

package/cache/cache.d.ts

@@ -0,0 +1,12 @@
+import { Cache as CommonCache, Memory } from '@appweaver/common';
+export declare abstract class Cache extends CommonCache {
+    private readonly _memory;
+    protected constructor(_memory: Memory);
+    onInit(): Promise<void>;
+    get<T>(key: string): Promise<T | null>;
+    set(key: string, value: any, ttl?: number): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    evict(key: string): Promise<boolean>;
+    expire(pattern?: string): Promise<number>;
+    keys(pattern?: string): Promise<string[]>;
+}

package/cache/cache.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cache = void 0;
+const common_1 = require("@appweaver/common");
+const eviction_1 = require("./eviction");
+class Cache extends common_1.Cache {
+    _memory;
+    /** @internal */
+    _entryMeta = new Map();
+    /** @internal */
+    _evictionIndex = this.createEvictionIndex();
+    /** @internal */
+    _maxSizeBytes = (0, common_1.textToBytes)(common_1.config.CACHE_MAX_SIZE);
+    constructor(_memory) {
+        super();
+        this._memory = _memory;
+    }
+    async onInit() {
+        if (common_1.config.CACHE_ENABLED && common_1.config.CACHE_CLEAN_START) {
+            await this.expire();
+        }
+    }
+    async get(key) {
+        const prefixedKey = this.addPrefix(key);
+        const data = await this._memory.getValue(prefixedKey);
+        if (data) {
+            const keyMeta = this._entryMeta.get(prefixedKey);
+            const now = Date.now();
+            const count = keyMeta?.usedCount ?? 0;
+            const updatedMeta = {
+                ...(keyMeta || {
+                    key,
+                    createdAt: now,
+                    sizeBytes: await this._memory.valueSizeBytes(prefixedKey)
+                }),
+                usedCount: count + 1,
+                lastUsedAt: now
+            };
+            this._entryMeta.set(prefixedKey, updatedMeta);
+            this._evictionIndex.touch(prefixedKey, updatedMeta);
+        }
+        else if (prefixedKey in this._entryMeta) {
+            // Remove key from meta and index storage if it does not exist memory
+            this._entryMeta.delete(prefixedKey);
+            this._evictionIndex.remove(prefixedKey);
+        }
+        return data;
+    }
+    async set(key, value, ttl) {
+        const prefixedKey = this.addPrefix(key);
+        const expireMs = ttl === 0 ? undefined : (ttl ?? common_1.config.CACHE_DEFAULT_TTL);
+        await this.evictExcessEntries();
+        const result = await this._memory.putValue(prefixedKey, value, expireMs);
+        const sizeBytes = await this._memory.valueSizeBytes(prefixedKey);
+        const now = Date.now();
+        const meta = {
+            key,
+            sizeBytes,
+            usedCount: 0,
+            createdAt: now,
+            lastUsedAt: now,
+            expiresAt: expireMs ? now + expireMs : undefined
+        };
+        this._entryMeta.set(prefixedKey, meta);
+        this._evictionIndex.add(prefixedKey, meta);
+        await this.ensureMemoryLimit();
+        return result;
+    }
+    async has(key) {
+        return this._memory.hasKey(this.addPrefix(key));
+    }
+    async evict(key) {
+        const prefixedKey = this.addPrefix(key);
+        const result = await this._memory.removeValue(prefixedKey);
+        this._entryMeta.delete(prefixedKey);
+        this._evictionIndex.remove(prefixedKey);
+        return result;
+    }
+    async expire(pattern = '*') {
+        const prefixedPattern = this.addPrefix(pattern);
+        const prefixedKeys = await this._memory.findKeys(prefixedPattern);
+        await this._memory.removeEntries(prefixedPattern);
+        for (const prefixedKey of prefixedKeys) {
+            this._entryMeta.delete(prefixedKey);
+            this._evictionIndex.remove(prefixedKey);
+        }
+        return prefixedKeys.size;
+    }
+    async keys(pattern = '*') {
+        const prefixedPattern = this.addPrefix(pattern);
+        const prefixedKeys = await this._memory.findKeys(prefixedPattern);
+        return Array.from(prefixedKeys);
+    }
+    /** @internal */
+    async evictExcessEntries() {
+        const now = Date.now();
+        // Delete expired entries metadata first, underlying memory implementation
+        // should have already removed cached values
+        for (const [prefixedKey, meta] of this._entryMeta.entries()) {
+            if (meta.expiresAt && meta.expiresAt < now) {
+                this._entryMeta.delete(prefixedKey);
+                this._evictionIndex.remove(prefixedKey);
+            }
+        }
+        // Calculate the number of entries that should be evicted, plus one is added
+        // because this method is called before adding new cache entry
+        const excessItemsCount = this._entryMeta.size - common_1.config.CACHE_MAX_ITEMS + 1;
+        if (excessItemsCount <= 0) {
+            return;
+        }
+        const candidateKeys = this._evictionIndex.evictionCandidates(excessItemsCount, now, common_1.config.CACHE_EVICTION_GRACE_PERIOD);
+        const evictActions = candidateKeys.map((key) => this.evict(key));
+        if (common_1.config.CACHE_EVICTION_DEFERRED) {
+            Promise.all(evictActions).catch((error) => {
+                common_1.logger.error(error, 'Cache eviction error');
+            });
+        }
+        else {
+            await Promise.all(evictActions);
+        }
+    }
+    /** @internal */
+    async ensureMemoryLimit() {
+        if (!this._maxSizeBytes) {
+            return;
+        }
+        if (common_1.config.CACHE_EVICTION_DEFERRED) {
+            this.runEnsureMemoryLimit().catch((error) => {
+                common_1.logger.error(error, 'Cache memory limit eviction error');
+            });
+            return;
+        }
+        await this.runEnsureMemoryLimit();
+    }
+    /** @internal */
+    async runEnsureMemoryLimit() {
+        if (!this._maxSizeBytes) {
+            return;
+        }
+        const now = Date.now();
+        let currentSizeBytes = [...this._entryMeta.values()]
+            .map((e) => e.sizeBytes ?? 0)
+            .reduce((a, b) => a + b, 0);
+        // Evict candidates incrementally until memory usage falls within the limit
+        while (currentSizeBytes > this._maxSizeBytes) {
+            const candidateKeys = this._evictionIndex.evictionCandidates(10, now, common_1.config.CACHE_EVICTION_GRACE_PERIOD);
+            if (candidateKeys.length === 0) {
+                break;
+            }
+            const keysToEvict = [];
+            for (const candidateKey of candidateKeys) {
+                keysToEvict.push(candidateKey);
+                currentSizeBytes -= this._entryMeta.get(candidateKey)?.sizeBytes ?? 0;
+                // Skip eviction of the rest of candidates when memory usage falls
+                // within the configured limit
+                if (currentSizeBytes <= this._maxSizeBytes) {
+                    break;
+                }
+            }
+            const evictActions = keysToEvict.map((key) => this.evict(key));
+            await Promise.all(evictActions);
+        }
+    }
+    /** @internal */
+    addPrefix(key) {
+        const prefix = common_1.config.CACHE_KEY_PREFIX;
+        if (key.startsWith(prefix)) {
+            return key;
+        }
+        return `${prefix}${key}`;
+    }
+    /** @internal */
+    createEvictionIndex() {
+        switch (common_1.config.CACHE_EVICTION_STRATEGY) {
+            case common_1.CacheEvictionStrategy.LRU:
+                return new eviction_1.LruEvictionIndex();
+            case common_1.CacheEvictionStrategy.LFU:
+                return new eviction_1.LfuEvictionIndex();
+            case common_1.CacheEvictionStrategy.FIFO:
+                return new eviction_1.FifoEvictionIndex();
+        }
+    }
+}
+exports.Cache = Cache;

package/cache/caching.d.ts

@@ -0,0 +1,8 @@
+import { Server } from '../types';
+export type CacheEntry = {
+    statusCode: number;
+    headers: Record<string, string | string[]>;
+    payload: string;
+};
+declare const _default: (server: Server) => void;
+export default _default;

package/cache/caching.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const request_context_1 = require("@fastify/request-context");
+const common_1 = require("@appweaver/common");
+const cache_service_1 = require("./cache-service");
+const context_1 = require("../context");
+exports.default = (0, fastify_plugin_1.default)((server) => {
+    const { currentUser } = server;
+    const cacheService = (0, context_1.inject)(cache_service_1.CacheService);
+    server.addHook('preHandler', async (request, reply) => {
+        const config = getRouteConfig(request);
+        if (!shouldUseCache(request, config)) {
+            return;
+        }
+        const user = config.public ? undefined : currentUser();
+        const key = buildCacheKey(request, config, cacheService, user);
+        const entry = await cacheService.getCachedValue(key);
+        if (entry) {
+            request_context_1.requestContext.set('cached', true);
+            return reply
+                .code(entry.statusCode)
+                .headers(entry.headers)
+                .send(entry.payload);
+        }
+    });
+    server.addHook('onSend', async (request, reply, payload) => {
+        const config = getRouteConfig(request);
+        if (!shouldUseCache(request, config)) {
+            return payload;
+        }
+        if (reply.statusCode >= 200 &&
+            reply.statusCode < 300 &&
+            !request_context_1.requestContext.get('cached')) {
+            const user = config.public ? undefined : currentUser();
+            const key = buildCacheKey(request, config, cacheService, user);
+            await cacheService.addToCache(key, {
+                statusCode: reply.statusCode,
+                headers: reply.getHeaders(),
+                payload
+            }, config.cacheTTL);
+        }
+        return payload;
+    });
+});
+function getRouteConfig(req) {
+    return req.routeOptions.config;
+}
+function shouldUseCache(req, config) {
+    return !!((req.method === 'GET' || req.method === 'POST') &&
+        (config.cacheTTL || config.cacheKey || config.cache) &&
+        (config.cacheTTL === undefined || config.cacheTTL > 0) &&
+        config.cache !== false);
+}
+function buildCacheKey(req, config, cacheService, user) {
+    return (0, common_1.isFunction)(config.cacheKey)
+        ? config.cacheKey(req, user)
+        : config.cacheKey ||
+            cacheService.buildCacheKey({
+                baseKey: 'req',
+                method: req.method,
+                url: req.raw.url,
+                body: req.body,
+                modelName: config.cacheModelName,
+                relations: config.cacheRelations,
+                skipInvalidation: config.cacheSkipInvalidation,
+                authUser: user
+            });
+}

package/cache/eviction/eviction-index.d.ts

@@ -0,0 +1,35 @@
+import { CacheEntryMeta } from '@appweaver/common';
+/**
+ * Interface representing operations for managing eviction policies in a cache system.
+ */
+export interface EvictionIndex {
+    /**
+     * Called when a key-value pair is added to the cache with associated metadata.
+     *
+     * @param {string} key - The unique identifier for the cache entry.
+     * @param {CacheEntryMeta} meta - The metadata associated with the cache entry.
+     */
+    add(key: string, meta: CacheEntryMeta): void;
+    /**
+     * Called when a cache entry is removed from the cache by the specified key.
+     *
+     * @param {string} key - The unique identifier for the removed entry.
+     */
+    remove(key: string): void;
+    /**
+     * Updates the metadata of a cached entry identified by the provided key.
+     *
+     * @param {string} key - The unique identifier for the accessed cache entry.
+     * @param {CacheEntryMeta} meta - The metadata object containing updated information for the cache entry.
+     */
+    touch(key: string, meta: CacheEntryMeta): void;
+    /**
+     * Returns a list of cache keys that meet the eviction criteria.
+     *
+     * @param {number} count - The maximum number of candidates to evict.
+     * @param {number} now - The current timestamp used to determine eligibility for eviction.
+     * @param {number} gracePeriod - The allowed time period after which candidates are eligible for eviction.
+     * @return {string[]} A list of keys for the cache entries to evict.
+     */
+    evictionCandidates(count: number, now: number, gracePeriod: number): string[];
+}

package/cache/eviction/eviction-index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/cache/eviction/fifo-eviction-index.d.ts

@@ -0,0 +1,7 @@
+import { CacheEntryMeta } from '@appweaver/common';
+import { EvictionIndex } from './eviction-index';
+export declare class FifoEvictionIndex implements EvictionIndex {
+    add(key: string, meta: CacheEntryMeta): void;
+    remove(key: string): void;
+    touch(_key: string, _meta: CacheEntryMeta): void;
+}

package/cache/eviction/fifo-eviction-index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FifoEvictionIndex = void 0;
+class FifoEvictionIndex {
+    /** @internal */
+    _keys = new Map();
+    add(key, meta) {
+        this._keys.set(key, meta);
+    }
+    remove(key) {
+        this._keys.delete(key);
+    }
+    touch(_key, _meta) {
+        // FIFO strategy ignores access recency or frequency
+    }
+    /** @internal */
+    evictionCandidates(count) {
+        const candidates = [];
+        for (const [key] of this._keys) {
+            if (candidates.length >= count) {
+                break;
+            }
+            candidates.push(key);
+        }
+        return candidates;
+    }
+}
+exports.FifoEvictionIndex = FifoEvictionIndex;

package/cache/eviction/index.d.ts

@@ -0,0 +1,4 @@
+export * from './eviction-index';
+export * from './fifo-eviction-index';
+export * from './lfu-eviction-index';
+export * from './lru-eviction-index';

package/cache/eviction/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./eviction-index"), exports);
+__exportStar(require("./fifo-eviction-index"), exports);
+__exportStar(require("./lfu-eviction-index"), exports);
+__exportStar(require("./lru-eviction-index"), exports);

package/cache/eviction/lfu-eviction-index.d.ts

@@ -0,0 +1,8 @@
+import { CacheEntryMeta } from '@appweaver/common';
+import { EvictionIndex } from './eviction-index';
+export declare class LfuEvictionIndex implements EvictionIndex {
+    add(key: string, meta: CacheEntryMeta): void;
+    remove(key: string): void;
+    touch(key: string, meta: CacheEntryMeta): void;
+    evictionCandidates(count: number, now: number, gracePeriod: number): string[];
+}

package/cache/eviction/lfu-eviction-index.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LfuEvictionIndex = void 0;
+class LfuEvictionIndex {
+    /** @internal */
+    _entries = new Map();
+    add(key, meta) {
+        this._entries.set(key, meta);
+    }
+    remove(key) {
+        this._entries.delete(key);
+    }
+    touch(key, meta) {
+        this._entries.set(key, meta);
+    }
+    evictionCandidates(count, now, gracePeriod) {
+        // Build a min-heap of size `count` to find the k entries with the lowest
+        // frequency score (usedCount / age), avoiding a full sort.
+        // Time complexity: O(n log k) where k = count (typically 1).
+        const heap = [];
+        for (const [key, meta] of this._entries) {
+            if (meta.createdAt + gracePeriod >= now) {
+                continue;
+            }
+            const entry = { key, meta };
+            if (heap.length < count) {
+                heap.push(entry);
+                this.siftUp(heap, heap.length - 1, now);
+            }
+            else if (this.score(meta, now) < this.score(heap[0].meta, now)) {
+                heap[0] = entry;
+                this.siftDown(heap, 0, now);
+            }
+        }
+        // Extract candidates — heap contains the `count` lowest-scored entries
+        // We use a max-heap so heap[0] is the largest among selected candidates.
+        // All entries in the heap are valid eviction candidates.
+        return heap.map((e) => e.key);
+    }
+    /** @internal */
+    score(meta, now) {
+        const age = now - meta.createdAt;
+        return age > 0 ? (meta.usedCount + 1) / age : Infinity;
+    }
+    // Max-heap by score: the root has the highest score among selected candidates.
+    // When a new entry has a lower score than the root, it replaces the root,
+    // ensuring the heap always contains the k lowest-scored entries.
+    /** @internal */
+    siftUp(heap, index, now) {
+        while (index > 0) {
+            const parent = (index - 1) >> 1;
+            if (this.score(heap[index].meta, now) <= this.score(heap[parent].meta, now)) {
+                break;
+            }
+            [heap[index], heap[parent]] = [heap[parent], heap[index]];
+            index = parent;
+        }
+    }
+    /** @internal */
+    siftDown(heap, index, now) {
+        const length = heap.length;
+        while (true) {
+            let largest = index;
+            const left = 2 * index + 1;
+            const right = 2 * index + 2;
+            if (left < length &&
+                this.score(heap[left].meta, now) > this.score(heap[largest].meta, now)) {
+                largest = left;
+            }
+            if (right < length &&
+                this.score(heap[right].meta, now) > this.score(heap[largest].meta, now)) {
+                largest = right;
+            }
+            if (largest === index) {
+                break;
+            }
+            [heap[index], heap[largest]] = [heap[largest], heap[index]];
+            index = largest;
+        }
+    }
+}
+exports.LfuEvictionIndex = LfuEvictionIndex;