@bjoernboss/mws 1.0.0

package/dist/cache.js

@@ -0,0 +1,708 @@
+/* SPDX-License-Identifier: BSD-3-Clause */
+/* Copyright (c) 2026 Bjoern Boss Henrichsen */
+import * as libLog from "./log.js";
+import * as libHelper from "./helper.js";
+import * as libFs from "fs";
+import * as libFsPromises from "fs/promises";
+import * as libStream from "stream";
+import * as libCrypto from "crypto";
+const UNIQUE_ID_CHARS = '0123456789abcdefghijklmnopqrstuvwxyz';
+const UNIQUE_ID_LENGTH = 14;
+const ID_EXTENSION_REGEX = RegExp(`^\\.[${UNIQUE_ID_CHARS}]{${UNIQUE_ID_LENGTH}}$`, 'i');
+function readStats(path) {
+    try {
+        const stats = libFs.statSync(path);
+        if (stats.isFile())
+            return [stats.size, stats.mtimeMs];
+    }
+    catch (err) {
+        if (err.code == 'ENOENT')
+            return null;
+        throw new Error(`Filesystem error while checking [${path}]: ${err.message}`);
+    }
+    return null;
+}
+async function atomicWrite(path, content, logger, options) {
+    const tempPath = (options?.temporary ?? `${path}.temp`);
+    let written = false;
+    try {
+        logger.trace(`Writing ${options?.what ?? 'data'} to [${path}]`);
+        /* write the content to the temporary file */
+        await libFsPromises.writeFile(tempPath, content);
+        written = true;
+        await libFsPromises.rename(tempPath, path);
+        return true;
+    }
+    catch (err) {
+        if (written)
+            logger.error(`Failed to replace the original file [${path}]: ${err.message}`);
+        else
+            logger.error(`Failed to write to temporary file [${tempPath}]: ${err.message}`);
+        try {
+            await libFsPromises.unlink(tempPath);
+        }
+        catch (err) {
+            if (err.code != 'ENOENT')
+                logger.warning(`Failed to remove temporary file [${tempPath}]: ${err.message}`);
+        }
+    }
+    return false;
+}
+class CacheManager {
+    logger;
+    map = {};
+    nextStamp = 0;
+    allocated = 0;
+    totalCapacity;
+    largestSize;
+    nextAge;
+    constructor(logger, cacheSize, fileSizeLimit) {
+        this.logger = logger;
+        this.totalCapacity = cacheSize;
+        this.largestSize = fileSizeLimit;
+        this.nextAge = 0;
+    }
+    reduce(maximum) {
+        /* create the list of all cached objects sorted by the touched count */
+        const paths = Object.keys(this.map).sort((a, b) => this.map[a].touched - this.map[b].touched);
+        /* drop the first half of the entries or more, if the size has not yet been freed */
+        for (let i = 0; i < (paths.length + 1) / 2 || this.allocated > maximum; ++i)
+            this.drop(paths[i]);
+    }
+    add(path, data, mtime, age) {
+        if (!this.cacheable(data.byteLength))
+            return;
+        /* check if the entry is already part of the cache and check if the current entry should be evicted */
+        if (path in this.map) {
+            const entry = this.map[path];
+            if (entry.age >= age)
+                return;
+            this.drop(path);
+        }
+        /* check if space needs to be reserved */
+        if (this.allocated + data.byteLength > this.totalCapacity)
+            this.reduce(this.totalCapacity - data.byteLength);
+        /* add the entry to the cache */
+        this.logger.log(`Added [${path}] to the cache (Size: ${data.byteLength})`);
+        this.allocated += data.byteLength;
+        this.map[path] = { data, encodings: {}, mtime, touched: ++this.nextStamp, age };
+    }
+    addEncoding(path, data, age, name) {
+        if (!this.cacheable(data.byteLength))
+            return;
+        /* check if the entry is still in the cache */
+        if (!(path in this.map) || this.map[path].age != age)
+            return;
+        /* check if the encoding already exists */
+        if (name in this.map[path].encodings)
+            return;
+        /* check if space needs to be reserved and check if the root entry is still available afterwards */
+        if (this.allocated + data.byteLength > this.totalCapacity)
+            this.reduce(this.totalCapacity - data.byteLength);
+        if (!(path in this.map))
+            return;
+        /* add the entry to the cache */
+        this.logger.log(`Added encoding [${name}] of [${path}] to the cache (Size: ${data.byteLength})`);
+        this.allocated += data.byteLength;
+        this.map[path].encodings[name] = data;
+    }
+    drop(path) {
+        if (!(path in this.map))
+            return;
+        this.logger.log(`Dropped [${path}] and encodings from the cache`);
+        /* remove all cached encodings and the entry itself */
+        const entry = this.map[path];
+        for (const key in entry.encodings)
+            this.allocated -= entry.encodings[key].byteLength;
+        this.allocated -= entry.data.byteLength;
+        delete this.map[path];
+    }
+    cacheable(size) {
+        return (size <= this.largestSize && size <= this.totalCapacity);
+    }
+    flush() {
+        this.map = {};
+        this.allocated = 0;
+    }
+    find(path, stats) {
+        const entry = this.map[path] ?? null;
+        if (entry == null)
+            return null;
+        /* check if the entry is still up-to-date and return it */
+        if (stats == null || (entry.mtime == stats.mtime && entry.data.length == stats.size)) {
+            entry.touched = ++this.nextStamp;
+            return entry;
+        }
+        /* remove the entry as it seems to be outdated */
+        this.drop(path);
+        return null;
+    }
+    allocAge() {
+        return ++this.nextAge;
+    }
+}
+class ImmutableManager {
+    logger;
+    map = {};
+    reverse = {};
+    writeBack = null;
+    alwaysValidate;
+    immutableTagging;
+    constructor(writeBackPath, logger, alwaysValidate, immutableTagging) {
+        this.logger = logger;
+        this.alwaysValidate = alwaysValidate;
+        this.immutableTagging = immutableTagging;
+        if (writeBackPath != '')
+            this.configureWriteBack(writeBackPath);
+    }
+    assignId(entry) {
+        const firstId = (entry.unique == '');
+        if (!firstId)
+            delete this.reverse[entry.unique];
+        /* setup the new unique id */
+        entry.unique = '';
+        for (let i = 0; i < UNIQUE_ID_LENGTH; ++i)
+            entry.unique += UNIQUE_ID_CHARS[libCrypto.randomInt(UNIQUE_ID_CHARS.length)];
+        /* patch the state up to contain the new id */
+        const [base, name, extension] = libHelper.splitFilePath(entry.path);
+        entry.immutable = `${base}${name}.${entry.unique}${extension}`;
+        this.reverse[entry.unique] = entry.identifier;
+        this.logger.trace(`${firstId ? 'Allocated' : 'Re-allocated'} immutable unique id [${entry.unique}] for [${entry.identifier}]`);
+    }
+    async storeState() {
+        if (this.writeBack == null)
+            return;
+        this.writeBack.dirty = true;
+        if (this.writeBack.writing != null)
+            return;
+        let resolver = () => { };
+        this.writeBack.writing = new Promise((res) => resolver = res);
+        /* check if the state is dirty and perform the write backs */
+        while (this.writeBack.dirty) {
+            this.writeBack.dirty = false;
+            /* collect the list of all relevant entries */
+            let output = [];
+            for (const identifier in this.map) {
+                const entry = this.map[identifier];
+                output.push({
+                    unique: entry.unique,
+                    identifier,
+                    path: entry.path,
+                    fileSystem: entry.fileSystem,
+                    size: entry.size,
+                    mtime: entry.mtime
+                });
+            }
+            const content = JSON.stringify(output);
+            /* ignore any read/write failures */
+            await atomicWrite(this.writeBack.path, Buffer.from(content, 'utf-8'), this.logger, { what: 'immutable state' });
+        }
+        this.writeBack.writing = null;
+        resolver();
+    }
+    async loadState(path) {
+        this.logger.trace(`Loading immutable state from [${path}]`);
+        /* load the current file and parse it as json (skip any content failed to be read or if the file did not exist) */
+        let state = null;
+        try {
+            state = JSON.parse(await libFsPromises.readFile(path, { encoding: 'utf-8' }));
+        }
+        catch (err) {
+            if (err.code != 'ENOENT')
+                this.logger.error(`Error while loading immutable state from [${path}]: ${err.message}`);
+            return [];
+        }
+        if (!Array.isArray(state)) {
+            this.logger.error(`Immutable state [${path}] is malformed (discarding state)`);
+            return [];
+        }
+        /* parse all of the values and validate their general structure */
+        let corrupted = 0, output = [];
+        for (const entry of state) {
+            if (typeof entry.unique != 'string' || typeof entry.identifier != 'string' || (typeof entry.fileSystem != 'string' && entry.fileSystem !== null))
+                ++corrupted;
+            else if (!`.${entry.unique}`.match(ID_EXTENSION_REGEX) || typeof entry.path != 'string')
+                ++corrupted;
+            else if (typeof entry.mtime != 'number' || !isFinite(entry.mtime) || entry.mtime < 0)
+                ++corrupted;
+            else if (typeof entry.size != 'number' || !isFinite(entry.size) || entry.size < 0 || Math.floor(entry.size) != entry.size)
+                ++corrupted;
+            else
+                output.push({ unique: entry.unique, identifier: entry.identifier, path: entry.path, fileSystem: entry.fileSystem, size: entry.size, mtime: entry.mtime });
+        }
+        if (corrupted > 0)
+            this.logger.error(`Immutable loaded state [${path}] contained [${corrupted}] malformed entires`);
+        return output;
+    }
+    updateEntry(entry, checkFreshness, firstAssign) {
+        if (entry.fetched && !checkFreshness && !this.alwaysValidate)
+            return true;
+        /* fetch the file states of the actual filesystem entry */
+        const stats = readStats(entry.fileSystem);
+        if (stats == null) {
+            this.logger.warning(`Immutable path [${entry.fileSystem}] does not exist`);
+            delete this.map[entry.identifier];
+            delete this.reverse[entry.unique];
+            this.storeState();
+            return false;
+        }
+        const [fileSize, mtime] = stats;
+        entry.fetched = true;
+        /* check if the stats have changed, in which case a new unique-id needs to be assigned (thus binding the it to the stats) */
+        if (!firstAssign) {
+            if (entry.size == fileSize && entry.mtime == mtime)
+                return true;
+            this.assignId(entry);
+        }
+        entry.size = fileSize;
+        entry.mtime = mtime;
+        this.storeState();
+        return true;
+    }
+    async configureWriteBack(path) {
+        let states = await this.loadState(path);
+        /* merge the loaded state into the current state (prefer current state over
+        *	loaded state; current state might already exist after awaiting the load) */
+        const performInitialWriteBack = (Object.keys(this.map).length > 0);
+        for (const state of states) {
+            if (state.identifier in this.map)
+                continue;
+            this.logger.trace(`Recovering immutable unique id [${state.unique}] for [${state.identifier}]`);
+            const [base, name, extension] = libHelper.splitFilePath(state.path);
+            this.map[state.identifier] = {
+                immutable: `${base}${name}.${state.unique}${extension}`,
+                identifier: state.identifier,
+                path: state.path,
+                fileSystem: state.fileSystem,
+                size: state.size,
+                mtime: state.mtime,
+                unique: state.unique,
+                fetched: false
+            };
+            this.reverse[state.unique] = state.identifier;
+        }
+        /* configure the actual writeback and check if an initial store needs to be triggered */
+        this.writeBack = { path, writing: null, dirty: false };
+        if (performInitialWriteBack)
+            this.storeState();
+    }
+    make(handler, path, checkFreshness) {
+        const identifier = `${handler}:${path}`;
+        if (!this.immutableTagging)
+            return path;
+        while (true) {
+            /* check if the entry does not yet exist and the id-tagged path needs to be created */
+            let entry = this.map[identifier] ?? null;
+            if (entry == null) {
+                entry = (this.map[identifier] = { immutable: '', identifier, path, unique: '', fileSystem: null, size: 0, mtime: 0, fetched: false });
+                this.assignId(entry);
+                this.storeState();
+            }
+            /* check if the stats can actually be validated or if the entry should just be served (if
+            *	the file does not exist/has been removed, simply restart the loop with to get a fresh id) */
+            else if (entry.fileSystem != null) {
+                try {
+                    if (!this.updateEntry(entry, checkFreshness, false))
+                        continue;
+                }
+                catch (err) {
+                    this.logger.warning(`Failed to validate immutable entry [${identifier}] and assuming unmodified: ${err.message}`);
+                }
+            }
+            return entry.immutable;
+        }
+    }
+    get(path, checkFreshness) {
+        if (!this.immutableTagging)
+            return [null, false];
+        /* check if it might be an immutable-tagged path */
+        const [base, temp, extension] = libHelper.splitFilePath(path);
+        const [_, name, tempId] = libHelper.splitFilePath(temp);
+        if (!tempId.match(ID_EXTENSION_REGEX))
+            return [null, false];
+        const unique = tempId.substring(1);
+        /* check if the entry does not exist in the reverse mapping anymore - indicating that the unique-id
+        *	is old/outdated, in which case it can be recovered by comparing the full actual path to all of
+        *	the entries, looking for the actual object, thereby recovering the most recent immutable path */
+        let identifier = this.reverse[unique] ?? null;
+        if (identifier == null) {
+            const fileSystemPath = `${base}${name}${extension}`;
+            for (const tempIdentifier in this.map) {
+                if (this.map[tempIdentifier].fileSystem != fileSystemPath)
+                    continue;
+                identifier = tempIdentifier;
+                break;
+            }
+            if (identifier == null)
+                return [null, false];
+        }
+        const entry = this.map[identifier], firstAssign = (entry.fileSystem == null);
+        if (entry.fileSystem == null)
+            entry.fileSystem = `${base}${name}${extension}`;
+        /* update the entry and return the final stats/if the unique-id changed */
+        if (!this.updateEntry(entry, checkFreshness, firstAssign))
+            return [null, false];
+        return [entry, entry.unique != unique];
+    }
+    invalidate() {
+        for (const identifier in this.map)
+            this.map[identifier].fetched = false;
+    }
+}
+class AlreadyCached {
+    cache;
+    path;
+    entry;
+    immutable;
+    constructor(cache, path, entry, immutable) {
+        this.cache = cache;
+        this.path = path;
+        this.entry = entry;
+        this.immutable = immutable;
+    }
+    isImmutable() {
+        return this.immutable;
+    }
+    filePath() {
+        return this.path;
+    }
+    fileSize() {
+        return this.entry.data.byteLength;
+    }
+    lastModified() {
+        return new Date(this.entry.mtime).toUTCString();
+    }
+    uniqueId() {
+        return `${this.entry.mtime}-${this.entry.data.byteLength}`;
+    }
+    stream(options) {
+        return libStream.Readable.from(this.entry.data.subarray(options?.start, (options?.end == null ? undefined : options.end + 1)));
+    }
+    async read() {
+        return this.entry.data;
+    }
+    readSync() {
+        return this.entry.data;
+    }
+    encoded(encoding) {
+        return EncodedCache(this.cache, this, this.entry, this.entry.age, encoding);
+    }
+}
+class NotCached {
+    cache;
+    path;
+    size;
+    mtime;
+    immutable;
+    age;
+    constructor(cache, path, size, mtime, age, immutable) {
+        this.cache = cache;
+        this.path = path;
+        this.size = size;
+        this.mtime = mtime;
+        this.immutable = immutable;
+        this.age = age;
+    }
+    makeStream(options) {
+        /* create the data stream */
+        let stream = null;
+        try {
+            stream = libFs.createReadStream(this.path, { flags: 'r', start: options?.start, end: options?.end });
+        }
+        catch (err) {
+            return new libStream.Readable({ read() { this.destroy(new Error(`Error reading file: ${err.message}`)); } });
+        }
+        /* check if only a partial file is being read, or it is too large, in which case it will not be added to the cache */
+        if (!this.cache.cacheable(this.size) || (options?.start != null && options.start != 0) || (options?.end != null && options.end + 1 != this.size))
+            return stream;
+        /* create the transformer stream to cache the data */
+        let buffers = [], settled = false, totalLength = 0;
+        const sniffer = new libStream.Transform({
+            transform: (chunk, _, cb) => {
+                if (settled)
+                    return cb(new Error('Reading already completed'));
+                totalLength += chunk.byteLength;
+                buffers.push(chunk);
+                cb(null, chunk);
+            },
+            final: (cb) => {
+                if (settled)
+                    return cb(new Error('Reading already completed'));
+                if (totalLength == this.size)
+                    this.cache.add(this.path, Buffer.concat(buffers), this.mtime, this.age);
+                cb(null);
+            }
+        });
+        /* setup the file exceptions to be propagated to the stream */
+        stream.pipe(sniffer);
+        stream.once('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            sniffer.destroy(err);
+        });
+        sniffer.once('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            stream.destroy(err);
+        });
+        return sniffer;
+    }
+    isImmutable() {
+        return this.immutable;
+    }
+    filePath() {
+        return this.path;
+    }
+    fileSize() {
+        return this.size;
+    }
+    lastModified() {
+        return new Date(this.mtime).toUTCString();
+    }
+    uniqueId() {
+        return `${this.mtime}-${this.size}`;
+    }
+    stream(options) {
+        return this.makeStream(options);
+    }
+    async read() {
+        return StreamToAsync(this.makeStream());
+    }
+    readSync() {
+        /* just let the errors propagate out */
+        const data = libFs.readFileSync(this.path);
+        /* add the read buffer back to the cache (using the fetched data from before reading the file - to
+        *	detect a file-change since before reading the file; dont error as stream also just proceeds) */
+        if (data.byteLength == this.size)
+            this.cache.add(this.path, data, this.mtime, this.age);
+        return data;
+    }
+    encoded(encoding) {
+        return EncodedCache(this.cache, this, null, this.age, encoding);
+    }
+}
+function StreamToAsync(stream) {
+    return new Promise((resolve, reject) => {
+        const buffers = [];
+        let settled = false;
+        /* register the handler to collect the data and stream them out */
+        stream.on("data", (chunk) => {
+            if (!settled)
+                buffers.push(chunk);
+        });
+        stream.once("error", (err) => {
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        });
+        stream.once("end", () => {
+            if (!settled) {
+                settled = true;
+                resolve(Buffer.concat(buffers));
+            }
+        });
+    });
+}
+function EncodedCache(cache, reader, entry, age, encoding) {
+    /* check if no encoding is used, in which case the source reader can just be wrapped */
+    if (encoding == null) {
+        return {
+            contentSize: () => reader.fileSize(),
+            stream: () => reader.stream(),
+            read: () => reader.read(),
+            readSync: () => reader.readSync()
+        };
+    }
+    /* check if the given encoding has already been cached */
+    if (entry != null && encoding.name in entry.encodings) {
+        const encoded = entry.encodings[encoding.name];
+        return {
+            contentSize: () => encoded.byteLength,
+            stream: () => libStream.Readable.from(encoded),
+            read: async () => encoded,
+            readSync: () => encoded
+        };
+    }
+    const makeStream = () => {
+        let settled = false;
+        /* create the encoded pipe */
+        const stream = reader.stream();
+        const encoder = encoding.makeEncode();
+        let sniffer = null;
+        stream.pipe(encoder);
+        /* setup the stream exceptions to be propgated through */
+        stream.once('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            encoder.destroy(err);
+            if (sniffer != null)
+                sniffer.destroy(err);
+        });
+        encoder.once('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            stream.destroy(err);
+            if (sniffer != null)
+                sniffer.destroy(err);
+        });
+        /* check if there is even a chance for the data to be cached */
+        if (!cache.cacheable(reader.fileSize()))
+            return encoder;
+        /* setup the sniffer stream to collect the cached data */
+        let buffers = [];
+        sniffer = new libStream.Transform({
+            transform: (chunk, _, cb) => {
+                if (settled)
+                    return cb(new Error('Reading already completed'));
+                buffers.push(chunk);
+                cb(null, chunk);
+            },
+            final: (cb) => {
+                if (settled)
+                    return cb(new Error('Reading already completed'));
+                cache.addEncoding(reader.filePath(), Buffer.concat(buffers), age, encoding.name);
+                cb(null);
+            }
+        });
+        /* setup the stream exceptions to be propgated through */
+        sniffer.once('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            stream.destroy(err);
+            encoder.destroy(err);
+        });
+        return encoder.pipe(sniffer);
+    };
+    /* wrap the original reader around the encoder (let errors propagate out) */
+    return {
+        contentSize: () => null,
+        stream: () => makeStream(),
+        read: () => StreamToAsync(makeStream()),
+        readSync: () => {
+            /* will be returned as buffer anyways, so might as well
+            *	try to write it back to the cache, no matter if its too large */
+            const data = encoding.encodeBuffer(reader.readSync());
+            cache.addEncoding(reader.filePath(), data, age, encoding.name);
+            return data;
+        }
+    };
+}
+export class CacheHost extends libLog.Logger {
+    _cacheManager;
+    _immutableManager;
+    _config;
+    constructor(config) {
+        super('cache');
+        this.info('Cache created');
+        this._config = BurntCacheConfig.from(config);
+        this._cacheManager = new CacheManager(this, this._config.cacheSize, this._config.fileSizeLimit);
+        this._immutableManager = new ImmutableManager(this._config.immutableStatePath, this, this._config.alwaysValidate, this._config.immutableTagging);
+    }
+    resolveCache(path, checkFreshness, checkImmutable) {
+        /* check if the entry is immutable and fetch its actual path or
+        *	if it has been moved (due to the id having been invalidated) */
+        const [immutable, immutableMoved] = (checkImmutable ? this._immutableManager.get(path, checkFreshness) : [null, false]);
+        if (immutable != null) {
+            path = immutable.fileSystem;
+            if (immutableMoved)
+                return immutable.immutable;
+        }
+        const isImmutable = (immutable != null);
+        /* check if does not need to be checked and the entry is already in the cache, in which case the file doesn't even need to be checked */
+        let entry = ((checkFreshness || this._config.alwaysValidate) ? null : this._cacheManager.find(path, null));
+        if (entry != null && (immutable == null || (immutable.size == entry.data.byteLength && immutable.mtime == entry.mtime)))
+            return new AlreadyCached(this._cacheManager, path, entry, isImmutable);
+        /* check if the file exists and read its file-size and mtime (not necessary
+        *	for immutable entries, as their stats are already up-to-date) */
+        const stats = (immutable == null ? readStats(path) : [immutable.size, immutable.mtime]);
+        if (stats == null)
+            return null;
+        const [fileSize, mtime] = stats;
+        /* check if the path exists in the validated cache and otherwise return the uncached entry */
+        entry = this._cacheManager.find(path, { mtime, size: fileSize });
+        if (entry != null)
+            return new AlreadyCached(this._cacheManager, path, entry, isImmutable);
+        return new NotCached(this._cacheManager, path, fileSize, mtime, this._cacheManager.allocAge(), isImmutable);
+    }
+    /* configuration used by this cache host */
+    get config() {
+        return this._config;
+    }
+    /* [throws] if [checkFreshness] is true, re-validate the file stats on disk before serving from cache (defaults
+    *	to false); resolve immutable ids automatically (Cached to interact with cache; null, if it does not exist,
+    *	string if the immutable path has been permanently moved to the new path in source space) */
+    fetchImmutable(path, options) {
+        return this.resolveCache(path, options?.checkFreshness ?? false, true);
+    }
+    /* [throws] if [checkFreshness] is true re-validate the file stats on disk before serving from cache (defaults
+    *	to false); no immutable ids are resolved (Cached to interact with cache; null, if it does not exist) */
+    fetchDirect(path, options) {
+        return this.resolveCache(path, options?.checkFreshness ?? false, false);
+    }
+    /* generate a unique tagged path for the given query path, which will change whenever the underlying file changes;
+    *	[checkFreshness]: if true, re-validate the file stats on disk to detect changes (defaults to false); creates
+    *	a path to a file, which looks similar to the source, except that the name includes a unique id, which will be used
+    *	to identity the given file state (will be removed from the final target path to be served, to identify the actual source) */
+    immutable(handler, path, options) {
+        return this._immutableManager.make(handler, path, options?.checkFreshness ?? false);
+    }
+    /* flush all cached data and invalidate immutable stats so they are re-checked on next access */
+    flush() {
+        this.info('Flushing cache and invalidating immutable entries');
+        this._cacheManager.flush();
+        this._immutableManager.invalidate();
+    }
+    /* [throws] read the data directly into a buffer (designed for modules to interact with) */
+    async read(path, options) {
+        const entry = this.resolveCache(path, options?.checkFreshness ?? false, false);
+        if (entry == null)
+            return null;
+        return entry.read();
+    }
+    /* [throws] write data atomically to the disk and update the cache (designed for modules to interact
+    *	with; writes as utf-8; writes data first to temporary file and then replaces the file atomically) */
+    async write(path, data, options) {
+        if (typeof data == 'string')
+            data = Buffer.from(data, 'utf-8');
+        /* write the data atomically to the destination */
+        if (!await atomicWrite(path, data, this, { what: (options?.what ?? 'via cache'), temporary: options?.temporary }))
+            throw new Error('Failed to atomically write data');
+        if (!this._cacheManager.cacheable(data.byteLength))
+            return;
+        const age = this._cacheManager.allocAge();
+        /* fetch the new state and update the cache (let errors propagate out; only if the write-state seems consistent) */
+        const stats = readStats(path);
+        if (stats == null)
+            this._cacheManager.drop(path);
+        else if (stats[0] == data.byteLength)
+            this._cacheManager.add(path, data, stats[1], age);
+    }
+}
+/* simple wrapper function to create a cache */
+export function createCache(config) {
+    return new CacheHost(config);
+}
+export class BurntCacheConfig {
+    immutableStatePath;
+    cacheSize;
+    fileSizeLimit;
+    alwaysValidate;
+    immutableTagging;
+    constructor(config) {
+        this.immutableStatePath = config?.immutableStatePath ?? '';
+        this.cacheSize = config?.cacheSize ?? 50_000_000;
+        this.fileSizeLimit = config?.fileSizeLimit ?? 10_000_000;
+        this.alwaysValidate = config?.alwaysValidate ?? false;
+        this.immutableTagging = config?.immutableTagging ?? true;
+    }
+    static from(config) {
+        return (config instanceof BurntCacheConfig ? config : new BurntCacheConfig(config));
+    }
+}
+//# sourceMappingURL=cache.js.map