@bjoernboss/mws 1.0.0 → 1.1.0

package/README.md

@@ -13,8 +13,6 @@ Only depends on [`ws`](https://github.com/websockets/ws) at runtime.
 
 Requires Node.js 22 or later.
 
-Note: Look into the source `TypeScript` code on [`GitHub`](https://github.com/BjoernBoss/mws).
-
 ## Quick Start
 
 ```typescript
@@ -45,12 +43,34 @@ server.listen(new HelloModule(), {
 });
 ```
 
+## Listeners
+
+`server.listen()` returns a `Listener` that emits `'listening'`, `'failed'`, and `'stopped'` events:
+
+```typescript
+const listener = server.listen(handler, { port: 8080 });
+
+listener.on('listening', (address) => console.log(`Listening on port ${address.port}`));
+listener.on('failed', (err) => console.error(`Failed: ${err.message}`));
+listener.on('stopped', () => console.log('Stopped'));
+```
+
+A serverless listener does not bind to a port. Instead, connections are passed to it manually via `listener.handleRequest()` and `listener.handleUpgrade()` (can also be used for other listeners):
+
+```typescript
+const listener = server.listen(handler, { serverless: { secure: false } });
+
+/* forward requests from an external HTTP server */
+externalServer.on('request', (req, resp) => listener.handleRequest(req, resp));
+externalServer.on('upgrade', (req, sock, head) => listener.handleUpgrade(req, sock, head));
+```
+
 ## Writing Modules
 
 A module extends `ModuleHandler` and implements up to three lifecycle hooks:
 
 ```typescript
-import { ModuleHandler, ClientRequest, Server } from "@bjoernboss/mws";
+import { ModuleHandler, ClientRequest, Server, Params } from "@bjoernboss/mws";
 
 export class MyModule extends ModuleHandler {
 	constructor() {
@@ -63,7 +83,7 @@ export class MyModule extends ModuleHandler {
 	}
 
 	/* Called for every incoming request routed to this module */
-	protected override async handleRequest(client: ClientRequest, params?: object): Promise<void> {
+	protected override async handleRequest(client: ClientRequest, params?: Params): Promise<void> {
 		/* respond to the client */
 	}
 
@@ -221,6 +241,8 @@ if (!await client.tryRespondFile('/var/www/index.html'))
 await client.respondHtml(page, { status: Status.Ok });
 ```
 
+**Important:** Streams returned by `receiveData()` and `respondData()` can emit `'error'` events. Always register an `'error'` handler on these streams to prevent unhandled errors from crashing the process. Generally: correspondingly tagged functions may throw or error and must handle errors accordingly, to prevent crashing the process.
+
 Convenience methods: `respondOk`, `respondNotFound`, `respondBadRequest`, `respondForbidden`, `respondInternalError`, `respondConflict`, `respondSeeOther`, `respondTemporaryRedirect`, `respondPermanentRedirect`, `respondCreated`, and others.
 
 ## WebSocket
@@ -259,22 +281,25 @@ File paths can be tagged with a unique version identifier so clients can cache t
 
 ```typescript
 /* style.css becomes style.<id>.css — the id changes when the file changes */
-const versionedPath = server.cache.immutable('my-handler', '/static/style.css');
+const versionedPath = server.cache.immutable('my-module', '/static/style.css');
 ```
 
 When a request arrives for an immutable path, the cache strips the version tag, serves the underlying file, and redirects stale version tags to the current one. Set `CacheConfig.immutableStatePath` to persist version mappings across restarts.
 
 ### Direct Cache Access
 
+These methods are designed for modules to be used, and allows directly to write to the disk, and update the cache at the same time. May throw exceptions.
+
 ```typescript
 const buffer = await server.cache.read('/path/to/data.json');
 await server.cache.write('/path/to/output.json', JSON.stringify(data));
+await server.cache.remove('/path/to/old.json');
 server.cache.flush();
 ```
 
 ## HTML Building
 
-The `build` namespace provides programmatic HTML construction with automatic escaping:
+The `build` namespace provides programmatic HTML construction with automatic escaping. It allows parent modules to use the `patchHtmlPage` function, to build around the HTML, before serving it:
 
 ```typescript
 import { build } from "@bjoernboss/mws";

package/dist/base.d.ts

@@ -146,7 +146,7 @@ export declare const Media: {
     readonly Svg: {
         readonly fileEnding: ["svg"];
         readonly mediaType: "image/svg+xml";
-        readonly encoding: "";
+        readonly encoding: "charset=utf-8";
         readonly compressible: true;
     };
     readonly Unknown: {
@@ -167,32 +167,33 @@ export declare const Encoding: {
         readonly name: "br";
         readonly makeDecode: () => libZlib.BrotliDecompress;
         readonly makeEncode: () => libZlib.BrotliCompress;
-        readonly encodeBuffer: (buffer: Buffer) => NonSharedBuffer;
+        readonly encodeBuffer: (buffer: Buffer) => Buffer;
     };
     readonly Zstd: {
         readonly name: "zstd";
         readonly makeDecode: () => libZlib.ZstdDecompress;
         readonly makeEncode: () => libZlib.ZstdCompress;
-        readonly encodeBuffer: (buffer: Buffer) => NonSharedBuffer;
+        readonly encodeBuffer: (buffer: Buffer) => Buffer;
     };
     readonly Gzip: {
         readonly name: "gzip";
         readonly makeDecode: () => libZlib.Gunzip;
         readonly makeEncode: () => libZlib.Gzip;
-        readonly encodeBuffer: (buffer: Buffer) => NonSharedBuffer;
+        readonly encodeBuffer: (buffer: Buffer) => Buffer;
     };
     readonly Deflate: {
         readonly name: "deflate";
         readonly makeDecode: () => libZlib.Inflate;
         readonly makeEncode: () => libZlib.Deflate;
-        readonly encodeBuffer: (buffer: Buffer) => NonSharedBuffer;
+        readonly encodeBuffer: (buffer: Buffer) => Buffer;
     };
     readonly Identity: {
         readonly name: "identity";
         readonly makeDecode: () => libStream.PassThrough;
         readonly makeEncode: () => libStream.PassThrough;
-        readonly encodeBuffer: (buffer: Buffer) => Buffer<ArrayBufferLike>;
+        readonly encodeBuffer: (buffer: Buffer) => Buffer;
     };
 };
+/** minimum size for content is considered encodable */
 export declare const MIN_ENCODING_SIZE: number;
 //# sourceMappingURL=base.d.ts.map

package/dist/base.js

@@ -33,7 +33,7 @@ export const Media = {
     Png: { fileEnding: ['png'], mediaType: 'image/png', encoding: '', compressible: false },
     Gif: { fileEnding: ['gif'], mediaType: 'image/gif', encoding: '', compressible: false },
     Jpg: { fileEnding: ['jpg', 'jpeg'], mediaType: 'image/jpeg', encoding: '', compressible: false },
-    Svg: { fileEnding: ['svg'], mediaType: 'image/svg+xml', encoding: '', compressible: true },
+    Svg: { fileEnding: ['svg'], mediaType: 'image/svg+xml', encoding: 'charset=utf-8', compressible: true },
     Unknown: { fileEnding: [], mediaType: 'application/octet-stream', encoding: '', compressible: false }
 };
 export const Encoding = {
@@ -68,6 +68,6 @@ export const Encoding = {
         encodeBuffer: (buffer) => buffer
     }
 };
-/* minimum size for content is considered encodable */
+/** minimum size for content is considered encodable */
 export const MIN_ENCODING_SIZE = 1_000;
 //# sourceMappingURL=base.js.map

package/dist/builder.d.ts

@@ -1,27 +1,36 @@
+/** wrapper around a string that has been verified as safe for direct html insertion;
+*	plain strings are treated as untrusted and will be html-escaped before wrapping */
 export type HtmlString = HtmlGuard | string;
 export declare class HtmlGuard {
     content: string;
     private constructor();
+    /** ensure the value is safe for html insertion; escapes plain strings, passes through HtmlGuard as-is */
     static get(str: HtmlString): HtmlGuard;
+    /** wrap a string for html insertion; if safe is false, it will be html-escaped first */
     static make(str: string, safe: boolean): HtmlGuard;
 }
+/** create a secure string [if safe is true, content is taken as-is; otherwise it is html escaped] */
 export declare function Safe(content: string, safe?: boolean): HtmlGuard;
+/** html component building interface (simple should return true for small one liners) */
 export interface HtmlComponent {
     finalize(indent: string): string;
     simple(): boolean;
 }
+/** raw text content to be embedded into an html tree */
 export declare class EmbeddedContent implements HtmlComponent {
     private content;
     constructor(content: string, safe: boolean);
     simple(): boolean;
     finalize(_: string): string;
 }
+/** self-closing html tag (e.g. <meta/>, <link/>, <br/>) */
 export declare class SingleTag implements HtmlComponent {
     private content;
     constructor(name: string, properties: Record<string, HtmlString>);
     simple(): boolean;
     finalize(indent: string): string;
 }
+/** html tag with children (e.g. <div>...</div>, <p>text</p>) */
 export declare class DualTag implements HtmlComponent {
     private openTag;
     private closeTag;
@@ -30,6 +39,7 @@ export declare class DualTag implements HtmlComponent {
     simple(): boolean;
     finalize(indent: string): string;
 }
+/** full html page; automatically adds utf-8 charset and defaults language to 'en' */
 export declare class HtmlPage {
     private _head;
     private _body;
@@ -45,12 +55,16 @@ export declare class HtmlPage {
     set body(value: HtmlComponent | HtmlComponent[]);
     finalize(): string;
 }
+/** embed raw content; if safe is true, the content is trusted and
+*	inserted verbatim; otherwise it is html-escaped before insertion */
 export declare function Embed(content: string, safe: boolean): HtmlComponent;
 export declare function Meta(name: HtmlString, content: HtmlString): HtmlComponent;
 export declare function Title(name: HtmlString): HtmlComponent;
 export declare function LoadStyle(path: HtmlString): HtmlComponent;
 export declare function LoadScript(path: HtmlString, properties?: Record<string, HtmlString>): HtmlComponent;
+/** inline css; content is inserted verbatim as <style> is a raw text element */
 export declare function AddStyle(content: string, properties?: Record<string, HtmlString>): HtmlComponent;
+/** inline javascript; content is inserted verbatim as <script> is a raw text element */
 export declare function AddScript(content: string, properties?: Record<string, HtmlString>): HtmlComponent;
 export declare function Text(text: HtmlString, properties?: Record<string, HtmlString>): HtmlComponent;
 export declare function Div(properties?: Record<string, HtmlString>, children?: HtmlComponent[] | HtmlComponent): HtmlComponent;

package/dist/builder.js

@@ -6,20 +6,20 @@ export class HtmlGuard {
     constructor(content) {
         this.content = content;
     }
-    /* ensure the value is safe for html insertion; escapes plain strings, passes through HtmlGuard as-is */
+    /** ensure the value is safe for html insertion; escapes plain strings, passes through HtmlGuard as-is */
     static get(str) {
         return (str instanceof HtmlGuard ? str : new HtmlGuard(libHelper.escapeHtml(str)));
     }
-    /* wrap a string for html insertion; if safe is false, it will be html-escaped first */
+    /** wrap a string for html insertion; if safe is false, it will be html-escaped first */
     static make(str, safe) {
         return new HtmlGuard(safe ? str : libHelper.escapeHtml(str));
     }
 }
-/* create a secure string [if safe is true, content is taken as-is; otherwise it is html escaped] */
+/** create a secure string [if safe is true, content is taken as-is; otherwise it is html escaped] */
 export function Safe(content, safe = true) {
     return HtmlGuard.make(content, safe);
 }
-/* raw text content to be embedded into an html tree */
+/** raw text content to be embedded into an html tree */
 export class EmbeddedContent {
     content;
     constructor(content, safe) {
@@ -32,7 +32,7 @@ export class EmbeddedContent {
         return this.content;
     }
 }
-/* self-closing html tag (e.g. <meta/>, <link/>, <br/>) */
+/** self-closing html tag (e.g. <meta/>, <link/>, <br/>) */
 export class SingleTag {
     content;
     constructor(name, properties) {
@@ -46,7 +46,7 @@ export class SingleTag {
         return `${indent}${this.content}`;
     }
 }
-/* html tag with children (e.g. <div>...</div>, <p>text</p>) */
+/** html tag with children (e.g. <div>...</div>, <p>text</p>) */
 export class DualTag {
     openTag;
     closeTag;
@@ -73,7 +73,7 @@ export class DualTag {
         return `${indent}${this.openTag}${body}\n${indent}${this.closeTag}`;
     }
 }
-/* full html page; automatically adds utf-8 charset and defaults language to 'en' */
+/** full html page; automatically adds utf-8 charset and defaults language to 'en' */
 export class HtmlPage {
     _head;
     _body;
@@ -109,7 +109,7 @@ export class HtmlPage {
         return `<!DOCTYPE html>\n${page.finalize('')}`;
     }
 }
-/* embed raw content; if safe is true, the content is trusted and
+/** embed raw content; if safe is true, the content is trusted and
 *	inserted verbatim; otherwise it is html-escaped before insertion */
 export function Embed(content, safe) {
     return new EmbeddedContent(content, safe);
@@ -126,11 +126,11 @@ export function LoadStyle(path) {
 export function LoadScript(path, properties = {}) {
     return new DualTag('script', { ...properties, src: path }, []);
 }
-/* inline css; content is inserted verbatim as <style> is a raw text element */
+/** inline css; content is inserted verbatim as <style> is a raw text element */
 export function AddStyle(content, properties = {}) {
     return new DualTag('style', properties, [new EmbeddedContent(content, true)]);
 }
-/* inline javascript; content is inserted verbatim as <script> is a raw text element */
+/** inline javascript; content is inserted verbatim as <script> is a raw text element */
 export function AddScript(content, properties = {}) {
     return new DualTag('script', properties, new EmbeddedContent(content, true));
 }

package/dist/cache.d.ts

@@ -2,56 +2,96 @@ import * as libLog from "./log.js";
 import * as libBase from "./base.js";
 import * as libStream from "stream";
 export interface Cached {
+    /** check if this is an immutable file entry */
     isImmutable(): boolean;
+    /** path of the file */
     filePath(): string;
+    /** size in bytes of the file */
     fileSize(): number;
+    /** fetch the last modified time formatted for the network */
     lastModified(): string;
+    /** fetch the unique-id to identify this version of the cached file (constructed,
+     *	just like the cache identifies them as equivalent: size+last-modified) */
     uniqueId(): string;
+    /** [no-throw but errors] object or encoded entry must not be used anymore after reading or streaming from it */
     stream(options?: {
         start?: number;
         end?: number;
     }): libStream.Readable;
+    /** [throws] object or encoded entry must not be used anymore after reading or streaming from it */
     read(): Promise<Buffer>;
+    /** [throws] object or encoded entry must not be used anymore after reading or streaming from it */
     readSync(): Buffer;
+    /** create an encoded version of this cached entry (no encoding is equivalent to identity) */
     encoded(encoding?: libBase.EncodingType): EncodedCache;
 }
 export interface EncodedCache {
+    /** size in bytes of the encoding (null if not yet determined) */
     contentSize(): number | null;
+    /** [no-throw but errors] object or encoded entry must not be used anymore after reading or streaming from it */
     stream(): libStream.Readable;
+    /** [throws] object or encoded entry must not be used anymore after reading or streaming from it */
     read(): Promise<Buffer>;
+    /** [throws] object or encoded entry must not be used anymore after reading or streaming from it */
     readSync(): Buffer;
 }
+/** all cache host operations which may throw errors and will not log them, and dont guarantee to contain the failing file path */
 export declare class CacheHost extends libLog.Logger {
     private _cacheManager;
     private _immutableManager;
     private _config;
     constructor(config?: CacheConfig | BurntCacheConfig);
     private resolveCache;
+    /** configuration used by this cache host */
     get config(): BurntCacheConfig;
+    /** [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: string, options?: {
         checkFreshness?: boolean;
     }): Cached | string | null;
+    /** [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: string, options?: {
         checkFreshness?: boolean;
     }): Cached | null;
-    immutable(handler: string, path: string, options?: {
+    /** 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(module: string, path: string, options?: {
         checkFreshness?: boolean;
     }): string;
+    /** flush all cached data and invalidate immutable stats so they are re-checked on next access */
     flush(): void;
+    /** [throws] read the data directly into a buffer (designed for modules to interact with) */
     read(path: string, options?: {
         checkFreshness?: boolean;
     }): Promise<Buffer | null>;
+    /** [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; for create,
+     *	must not replace an existing file; returns false if the file already existed and could not be created) */
     write(path: string, data: Buffer | string, options?: {
         what?: string;
         temporary?: string;
-    }): Promise<void>;
+        create?: boolean;
+    }): Promise<boolean>;
+    /** [throws] remove the data from the physical disk and from the cache (returns false if it did not exist) */
+    remove(path: string): Promise<boolean>;
 }
+/** simple wrapper function to create a cache */
 export declare function createCache(config?: CacheConfig | BurntCacheConfig): CacheHost;
 export interface CacheConfig {
+    /** immutable state path is used to ensure the immutable state uses persistent ids across
+     *	restarts (will be read upon loading; if not set, ids will be lost after a server restart) [Default: ''] */
     immutableStatePath?: string;
+    /** total cachable size [Default: 50_000_000] */
     cacheSize?: number;
+    /** upper limit for files considered cachable, others will just be streamed through [Default: 10_000_000] */
     fileSizeLimit?: number;
+    /** always validate file freshness before providing them [Default: false] */
     alwaysValidate?: boolean;
+    /** tag served content with immutable ids to encode freshness into the path [Default: true] */
     immutableTagging?: boolean;
 }
 export declare class BurntCacheConfig {

package/dist/cache.js

@@ -7,7 +7,7 @@ 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 UNIQUE_ID_LENGTH = 10;
 const ID_EXTENSION_REGEX = RegExp(`^\\.[${UNIQUE_ID_CHARS}]{${UNIQUE_ID_LENGTH}}$`, 'i');
 function readStats(path) {
     try {
@@ -18,26 +18,31 @@ function readStats(path) {
     catch (err) {
         if (err.code == 'ENOENT')
             return null;
-        throw new Error(`Filesystem error while checking [${path}]: ${err.message}`);
+        throw err;
     }
     return null;
 }
 async function atomicWrite(path, content, logger, options) {
     const tempPath = (options?.temporary ?? `${path}.temp`);
+    logger.trace(`Writing ${options?.what ?? 'data'} to [${path}]`);
+    if (options?.create === true) {
+        try {
+            await libFsPromises.writeFile(path, content, { flag: 'wx' });
+        }
+        catch (err) {
+            if (err.code == 'EEXIST')
+                return false;
+            throw new Error(`Failed to create file: ${err.message}`);
+        }
+        return true;
+    }
     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);
         }
@@ -45,8 +50,11 @@ async function atomicWrite(path, content, logger, options) {
             if (err.code != 'ENOENT')
                 logger.warning(`Failed to remove temporary file [${tempPath}]: ${err.message}`);
         }
+        if (written)
+            throw new Error(`Failed to replace the original file: ${err.message}`);
+        throw new Error(`Failed to write to temporary file [${tempPath}]: ${err.message}`);
     }
-    return false;
+    return true;
 }
 class CacheManager {
     logger;
@@ -83,9 +91,9 @@ class CacheManager {
         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 };
+        this.logger.log(`Added [${path}] to the cache (Size: ${data.byteLength} / Allocated: ${this.allocated})`);
     }
     addEncoding(path, data, age, name) {
         if (!this.cacheable(data.byteLength))
@@ -102,20 +110,20 @@ class CacheManager {
         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;
+        this.logger.log(`Added encoding [${name}] of [${path}] to the cache (Size: ${data.byteLength} / Allocated: ${this.allocated})`);
     }
     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];
+        this.logger.log(`Dropped [${path}] and encodings from the cache (Allocated: ${this.allocated})`);
     }
     cacheable(size) {
         return (size <= this.largestSize && size <= this.totalCapacity);
@@ -195,7 +203,12 @@ class ImmutableManager {
             }
             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' });
+            try {
+                await atomicWrite(this.writeBack.path, Buffer.from(content, 'utf-8'), this.logger, { what: 'immutable state' });
+            }
+            catch (err) {
+                this.logger.error(`Failed to write immutable state to [${this.writeBack.path}]: ${err.message}`);
+            }
         }
         this.writeBack.writing = null;
         resolver();
@@ -286,8 +299,8 @@ class ImmutableManager {
         if (performInitialWriteBack)
             this.storeState();
     }
-    make(handler, path, checkFreshness) {
-        const identifier = `${handler}:${path}`;
+    make(module, path, checkFreshness) {
+        const identifier = `${module}:${path}`;
         if (!this.immutableTagging)
             return path;
         while (true) {
@@ -593,6 +606,7 @@ function EncodedCache(cache, reader, entry, age, encoding) {
         }
     };
 }
+/** all cache host operations which may throw errors and will not log them, and dont guarantee to contain the failing file path */
 export class CacheHost extends libLog.Logger {
     _cacheManager;
     _immutableManager;
@@ -630,51 +644,60 @@ export class CacheHost extends libLog.Logger {
             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 */
+    /** 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) */
+    /** [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) */
+    /** [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);
+    /** 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(module, path, options) {
+        return this._immutableManager.make(module, path, options?.checkFreshness ?? false);
     }
-    /* flush all cached data and invalidate immutable stats so they are re-checked on next access */
+    /** 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) */
+    /** [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();
+        try {
+            const entry = this.resolveCache(path, options?.checkFreshness ?? false, false);
+            if (entry == null)
+                return null;
+            return entry.read();
+        }
+        /* special abstraction to ensure check-before-use does not result in not-found */
+        catch (err) {
+            if (err.code == 'ENOENT')
+                return null;
+            throw err;
+        }
     }
-    /* [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) */
+    /** [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; for create,
+     *	must not replace an existing file; returns false if the file already existed and could not be created) */
     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');
+        /* write the data atomically to the destination (let errors propagate out) */
+        if (!await atomicWrite(path, data, this, { what: (options?.what ?? 'via cache'), temporary: options?.temporary, create: options?.create }))
+            return false;
         if (!this._cacheManager.cacheable(data.byteLength))
-            return;
+            return true;
         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);
@@ -682,9 +705,26 @@ export class CacheHost extends libLog.Logger {
             this._cacheManager.drop(path);
         else if (stats[0] == data.byteLength)
             this._cacheManager.add(path, data, stats[1], age);
+        return true;
+    }
+    /** [throws] remove the data from the physical disk and from the cache (returns false if it did not exist) */
+    async remove(path) {
+        let existed = true;
+        /* try to remove the physical file */
+        try {
+            await libFsPromises.unlink(path);
+        }
+        catch (err) {
+            if (err.code != 'ENOENT')
+                throw err;
+            existed = false;
+        }
+        /* remove the data from the cache */
+        this._cacheManager.drop(path);
+        return existed;
     }
 }
-/* simple wrapper function to create a cache */
+/** simple wrapper function to create a cache */
 export function createCache(config) {
     return new CacheHost(config);
 }