@modularizer/plat 0.8.0 → 0.10.0

package/dist/static/file-response.js

@@ -0,0 +1,57 @@
+import { getMimeType } from './mime-types.js';
+export const FILE_RESPONSE_BRAND = Symbol.for('plat:FileResponse');
+/**
+ * A response that serves a file. Can be returned from any controller method.
+ * Methods returning FileResponse should use @GET({ hidden: true }) to exclude from OpenAPI.
+ */
+export class FileResponse {
+    kind;
+    source;
+    [FILE_RESPONSE_BRAND] = true;
+    filename;
+    contentType;
+    maxAge;
+    headers;
+    constructor(kind, source, filename, opts) {
+        this.kind = kind;
+        this.source = source;
+        this.filename = filename;
+        this.contentType = opts?.contentType ?? getMimeType(filename);
+        this.maxAge = opts?.maxAge;
+        this.headers = opts?.headers ?? {};
+    }
+    static from(pathOrContent, filenameOrOpts, opts) {
+        if (typeof pathOrContent === 'string' && (filenameOrOpts === undefined || typeof filenameOrOpts === 'object' && !(filenameOrOpts instanceof Buffer))) {
+            // from(path) or from(path, opts) — filesystem path
+            const path = pathOrContent;
+            const filename = path.split('/').pop() ?? path;
+            return new FileResponse('path', path, filename, filenameOrOpts);
+        }
+        // from(content, filename) or from(content, filename, opts) — in-memory content
+        return new FileResponse('content', pathOrContent, filenameOrOpts, opts);
+    }
+    /**
+     * Get the file content as a Buffer. For path-based responses, reads the file.
+     * For content-based responses, converts string to Buffer if needed.
+     */
+    async getContent() {
+        if (this.kind === 'path') {
+            const { readFile } = await import('node:fs/promises');
+            return readFile(this.source);
+        }
+        if (typeof this.source === 'string') {
+            return Buffer.from(this.source, 'utf-8');
+        }
+        if (this.source instanceof Uint8Array) {
+            return Buffer.from(this.source);
+        }
+        return this.source;
+    }
+}
+/**
+ * Check if a value is a FileResponse instance (works across module boundaries).
+ */
+export function isFileResponse(value) {
+    return value != null && typeof value === 'object' && FILE_RESPONSE_BRAND in value;
+}
+//# sourceMappingURL=file-response.js.map

package/dist/static/file-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-response.js","sourceRoot":"","sources":["../../src/static/file-response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AAQlE;;;GAGG;AACH,MAAM,OAAO,YAAY;IASZ;IACA;IATF,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAA;IAE5B,QAAQ,CAAQ;IAChB,WAAW,CAAQ;IACnB,MAAM,CAAS;IACf,OAAO,CAAwB;IAExC,YACW,IAAwB,EACxB,MAAoC,EAC7C,QAAgB,EAChB,IAAuB;QAHd,SAAI,GAAJ,IAAI,CAAoB;QACxB,WAAM,GAAN,MAAM,CAA8B;QAI7C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,WAAW,GAAG,IAAI,EAAE,WAAW,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAA;QAC7D,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAA;QAC1B,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,EAAE,CAAA;IACpC,CAAC;IAcD,MAAM,CAAC,IAAI,CACT,aAA2C,EAC3C,cAA0C,EAC1C,IAAuB;QAEvB,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,CAAC,CAAC,cAAc,YAAY,MAAM,CAAC,CAAC,EAAE,CAAC;YACrJ,mDAAmD;YACnD,MAAM,IAAI,GAAG,aAAa,CAAA;YAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI,CAAA;YAC9C,OAAO,IAAI,YAAY,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,cAA8C,CAAC,CAAA;QACjG,CAAC;QAED,+EAA+E;QAC/E,OAAO,IAAI,YAAY,CAAC,SAAS,EAAE,aAAa,EAAE,cAAwB,EAAE,IAAI,CAAC,CAAA;IACnF,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU;QACd,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACzB,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAA;YACrD,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAgB,CAAC,CAAA;QACxC,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC1C,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,YAAY,UAAU,EAAE,CAAC;YACtC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACjC,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,mBAAmB,IAAI,KAAK,CAAA;AACnF,CAAC"}

package/dist/static/glob-match.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Gitignore-style glob matching for exclude patterns.
+ *
+ * Supported patterns:
+ *   **\/*.map     — match extension in any subdirectory
+ *   .DS_Store     — exact filename anywhere
+ *   secrets/**    — entire directory tree
+ *   **\/.*        — all dotfiles in any subdirectory
+ *   *.txt         — match extension in current directory only
+ */
+/**
+ * Check if a file path matches any of the exclude patterns.
+ * Paths should be relative (no leading slash), using forward slashes.
+ */
+export declare function isExcluded(filePath: string, patterns: string[]): boolean;
+//# sourceMappingURL=glob-match.d.ts.map

package/dist/static/glob-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob-match.d.ts","sourceRoot":"","sources":["../../src/static/glob-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA8BH;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CASxE"}

package/dist/static/glob-match.js

@@ -0,0 +1,48 @@
+/**
+ * Gitignore-style glob matching for exclude patterns.
+ *
+ * Supported patterns:
+ *   **\/*.map     — match extension in any subdirectory
+ *   .DS_Store     — exact filename anywhere
+ *   secrets/**    — entire directory tree
+ *   **\/.*        — all dotfiles in any subdirectory
+ *   *.txt         — match extension in current directory only
+ */
+/**
+ * Convert a gitignore-style glob pattern to a RegExp.
+ */
+function globToRegExp(pattern) {
+    // Normalize: strip leading/trailing slashes
+    let p = pattern.replace(/^\/+|\/+$/g, '');
+    // Escape regex special chars except * and ?
+    p = p.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    // Handle ** patterns
+    // /**/  → match any number of path segments (including zero)
+    p = p.replace(/\\\*\\\*\//g, '(?:.+/)?');
+    // ** at end → match everything
+    p = p.replace(/\\\*\\\*/g, '.*');
+    // Single * → match anything except /
+    p = p.replace(/\\\*/g, '[^/]*');
+    // ? → match single char except /
+    p = p.replace(/\\\?/g, '[^/]');
+    // If pattern has no slash, match against basename anywhere in path
+    if (!pattern.includes('/')) {
+        return new RegExp(`(?:^|/)${p}$`);
+    }
+    return new RegExp(`^${p}$`);
+}
+/**
+ * Check if a file path matches any of the exclude patterns.
+ * Paths should be relative (no leading slash), using forward slashes.
+ */
+export function isExcluded(filePath, patterns) {
+    // Normalize the path
+    const normalized = filePath.replace(/^\/+/, '');
+    for (const pattern of patterns) {
+        if (globToRegExp(pattern).test(normalized)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=glob-match.js.map

package/dist/static/glob-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob-match.js","sourceRoot":"","sources":["../../src/static/glob-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,SAAS,YAAY,CAAC,OAAe;IACnC,4CAA4C;IAC5C,IAAI,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;IAEzC,4CAA4C;IAC5C,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAA;IAE1C,qBAAqB;IACrB,6DAA6D;IAC7D,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC,CAAA;IACxC,+BAA+B;IAC/B,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;IAChC,qCAAqC;IACrC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAC/B,iCAAiC;IACjC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IAE9B,mEAAmE;IACnE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;IACnC,CAAC;IAED,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,QAAkB;IAC7D,qBAAqB;IACrB,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC/C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3C,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/static/index.d.ts

@@ -0,0 +1,9 @@
+export { FileResponse, isFileResponse } from './file-response';
+export type { FileResponseOpts } from './file-response';
+export { StaticFolder, isStaticFolder } from './static-folder';
+export type { StaticFolderOpts } from './static-folder';
+export type { VirtualFileSystem, MemoryFileEntry } from './virtual-file-system';
+export { NodeFileSystem, MemoryFileSystem } from './virtual-file-system';
+export { getMimeType } from './mime-types';
+export { isExcluded } from './glob-match';
+//# sourceMappingURL=index.d.ts.map

package/dist/static/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/static/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC/E,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA"}

package/dist/static/index.js

@@ -0,0 +1,6 @@
+export { FileResponse, isFileResponse } from './file-response.js';
+export { StaticFolder, isStaticFolder } from './static-folder.js';
+export { NodeFileSystem, MemoryFileSystem } from './virtual-file-system.js';
+export { getMimeType } from './mime-types.js';
+export { isExcluded } from './glob-match.js';
+//# sourceMappingURL=index.js.map

package/dist/static/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/static/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAE9D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAG9D,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA"}

package/dist/static/mime-types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get MIME content-type from a filename or extension.
+ * Returns 'application/octet-stream' for unrecognized extensions.
+ */
+export declare function getMimeType(filename: string): string;
+//# sourceMappingURL=mime-types.d.ts.map

package/dist/static/mime-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime-types.d.ts","sourceRoot":"","sources":["../../src/static/mime-types.ts"],"names":[],"mappings":"AAsEA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpD"}

package/dist/static/mime-types.js

@@ -0,0 +1,74 @@
+const MIME_TYPES = {
+    // Text
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.css': 'text/css',
+    '.csv': 'text/csv',
+    '.txt': 'text/plain',
+    '.xml': 'text/xml',
+    '.md': 'text/markdown',
+    '.yaml': 'text/yaml',
+    '.yml': 'text/yaml',
+    // JavaScript / JSON
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.cjs': 'application/javascript',
+    '.json': 'application/json',
+    '.jsonld': 'application/ld+json',
+    '.map': 'application/json',
+    '.ts': 'text/typescript',
+    // Images
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.bmp': 'image/bmp',
+    '.tiff': 'image/tiff',
+    '.tif': 'image/tiff',
+    // Fonts
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.eot': 'application/vnd.ms-fontobject',
+    // Audio
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.flac': 'audio/flac',
+    '.aac': 'audio/aac',
+    '.m4a': 'audio/mp4',
+    // Video
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.avi': 'video/x-msvideo',
+    '.mov': 'video/quicktime',
+    '.mkv': 'video/x-matroska',
+    // Documents
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip',
+    '.gz': 'application/gzip',
+    '.tar': 'application/x-tar',
+    '.7z': 'application/x-7z-compressed',
+    '.rar': 'application/vnd.rar',
+    // Web
+    '.wasm': 'application/wasm',
+    '.manifest': 'text/cache-manifest',
+    '.webmanifest': 'application/manifest+json',
+};
+/**
+ * Get MIME content-type from a filename or extension.
+ * Returns 'application/octet-stream' for unrecognized extensions.
+ */
+export function getMimeType(filename) {
+    const dot = filename.lastIndexOf('.');
+    if (dot === -1)
+        return 'application/octet-stream';
+    const ext = filename.slice(dot).toLowerCase();
+    return MIME_TYPES[ext] ?? 'application/octet-stream';
+}
+//# sourceMappingURL=mime-types.js.map

package/dist/static/mime-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime-types.js","sourceRoot":"","sources":["../../src/static/mime-types.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAA2B;IACzC,OAAO;IACP,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,WAAW;IAEnB,oBAAoB;IACpB,KAAK,EAAE,wBAAwB;IAC/B,MAAM,EAAE,wBAAwB;IAChC,MAAM,EAAE,wBAAwB;IAChC,OAAO,EAAE,kBAAkB;IAC3B,SAAS,EAAE,qBAAqB;IAChC,MAAM,EAAE,kBAAkB;IAC1B,KAAK,EAAE,iBAAiB;IAExB,SAAS;IACT,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,eAAe;IACvB,MAAM,EAAE,cAAc;IACtB,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,YAAY;IAEpB,QAAQ;IACR,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,+BAA+B;IAEvC,QAAQ;IACR,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IAEnB,QAAQ;IACR,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,kBAAkB;IAE1B,YAAY;IACZ,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,iBAAiB;IACzB,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,mBAAmB;IAC3B,KAAK,EAAE,6BAA6B;IACpC,MAAM,EAAE,qBAAqB;IAE7B,MAAM;IACN,OAAO,EAAE,kBAAkB;IAC3B,WAAW,EAAE,qBAAqB;IAClC,cAAc,EAAE,2BAA2B;CAC5C,CAAA;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IACrC,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,0BAA0B,CAAA;IACjD,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAA;IAC7C,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,0BAA0B,CAAA;AACtD,CAAC"}

package/dist/static/static-folder.d.ts

@@ -0,0 +1,69 @@
+import { FileResponse } from './file-response';
+import { type MemoryFileEntry, type VirtualFileSystem } from './virtual-file-system';
+export declare const STATIC_FOLDER_BRAND: unique symbol;
+export interface StaticFolderOpts {
+    /** Gitignore-style exclude patterns */
+    exclude?: string[];
+    /** Cache-Control max-age in seconds */
+    maxAge?: number;
+    /** Extra response headers */
+    headers?: Record<string, string>;
+    /** How to handle dotfiles: 'ignore' (404), 'allow', or 'deny' (403). Default: 'ignore' */
+    dotfiles?: 'ignore' | 'allow' | 'deny';
+    /**
+     * What to return when someone requests a directory.
+     * - 'none'      : 404 (default when index is not set)
+     * - 'index'     : serve the index file if it exists (default when index is set)
+     * - 'list'      : return a JSON array of filenames
+     * - 'directory'  : return an HTML directory listing page
+     * - function    : custom handler — receives file list, returns a FileResponse
+     */
+    onDirectory?: 'none' | 'index' | 'list' | 'directory' | ((files: string[]) => FileResponse | Promise<FileResponse>);
+    /** Index file to serve for directory requests when onDirectory is 'index' (e.g. 'index.html') */
+    index?: string;
+}
+/**
+ * A static folder that serves files from a VirtualFileSystem.
+ * Used as a class variable on controllers:
+ *
+ *   @Controller()
+ *   class MyApp {
+ *     assets = new StaticFolder('./public', { exclude: ['**\/*.map'] })
+ *   }
+ */
+export declare class StaticFolder {
+    readonly [STATIC_FOLDER_BRAND] = true;
+    readonly vfs: VirtualFileSystem;
+    readonly opts: StaticFolderOpts;
+    constructor(directory: string, opts?: StaticFolderOpts);
+    constructor(files: Record<string, MemoryFileEntry>, opts?: StaticFolderOpts);
+    constructor(vfs: VirtualFileSystem, opts?: StaticFolderOpts);
+    /**
+     * Recursively enumerate all file paths available in this folder.
+     * Returns paths relative to the folder root (no leading slash).
+     * Respects exclude patterns and dotfile policy.
+     * Useful for building manifests so clients know what paths are serveable.
+     */
+    listAllFiles(maxDepth?: number): Promise<string[]>;
+    private walkDir;
+    /**
+     * Resolve a sub-path to a FileResponse, or null if not found.
+     * Handles: exclude globs, dotfile policy, stem matching, onDirectory behavior.
+     */
+    resolve(subPath: string): Promise<FileResponse | null>;
+    private isDotfile;
+    private hasExtension;
+    /**
+     * Stem matching: if request path has no extension and exactly one file matches the stem, serve it.
+     * e.g. /assets/readme → serves readme.md if it's the only readme.* in that directory
+     */
+    private stemMatch;
+    private handleDirectory;
+    private renderDirectoryPage;
+    private createFileResponse;
+}
+/**
+ * Check if a value is a StaticFolder instance (works across module boundaries).
+ */
+export declare function isStaticFolder(value: unknown): value is StaticFolder;
+//# sourceMappingURL=static-folder.d.ts.map

package/dist/static/static-folder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-folder.d.ts","sourceRoot":"","sources":["../../src/static/static-folder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAG9C,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAA;AAE9B,eAAO,MAAM,mBAAmB,eAAkC,CAAA;AAElE,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IACtC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAA;IACnH,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,CAAC,mBAAmB,CAAC,QAAO;IAErC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;gBAEnB,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB;gBAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB;gBAC/D,GAAG,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,gBAAgB;IAgB3D;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,SAAK,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAMtC,OAAO;IAwBrB;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAwC5D,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,YAAY;IAKpB;;;OAGG;YACW,SAAS;YA+BT,eAAe;IAgC7B,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,kBAAkB;CAW3B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE"}

package/dist/static/static-folder.js

@@ -0,0 +1,206 @@
+import { FileResponse } from './file-response.js';
+import { isExcluded } from './glob-match.js';
+import { getMimeType } from './mime-types.js';
+import { isVirtualFileSystem, MemoryFileSystem, NodeFileSystem, } from './virtual-file-system.js';
+export const STATIC_FOLDER_BRAND = Symbol.for('plat:StaticFolder');
+/**
+ * A static folder that serves files from a VirtualFileSystem.
+ * Used as a class variable on controllers:
+ *
+ *   @Controller()
+ *   class MyApp {
+ *     assets = new StaticFolder('./public', { exclude: ['**\/*.map'] })
+ *   }
+ */
+export class StaticFolder {
+    [STATIC_FOLDER_BRAND] = true;
+    vfs;
+    opts;
+    constructor(source, opts) {
+        this.opts = opts ?? {};
+        if (typeof source === 'string') {
+            this.vfs = new NodeFileSystem(source);
+        }
+        else if (isVirtualFileSystem(source)) {
+            this.vfs = source;
+        }
+        else {
+            this.vfs = new MemoryFileSystem(source);
+        }
+    }
+    /**
+     * Recursively enumerate all file paths available in this folder.
+     * Returns paths relative to the folder root (no leading slash).
+     * Respects exclude patterns and dotfile policy.
+     * Useful for building manifests so clients know what paths are serveable.
+     */
+    async listAllFiles(maxDepth = 20) {
+        const results = [];
+        await this.walkDir('', results, 0, maxDepth);
+        return results;
+    }
+    async walkDir(dirPath, results, depth, maxDepth) {
+        if (depth > maxDepth)
+            return;
+        const entries = await this.vfs.list(dirPath);
+        for (const entry of entries) {
+            if (entry.endsWith('/')) {
+                const dirName = entry.slice(0, -1);
+                const fullDirPath = dirPath ? `${dirPath}/${dirName}` : dirName;
+                if (this.isDotfile(fullDirPath)) {
+                    const policy = this.opts.dotfiles ?? 'ignore';
+                    if (policy === 'ignore' || policy === 'deny')
+                        continue;
+                }
+                await this.walkDir(fullDirPath, results, depth + 1, maxDepth);
+            }
+            else {
+                const filePath = dirPath ? `${dirPath}/${entry}` : entry;
+                if (this.isDotfile(filePath)) {
+                    const policy = this.opts.dotfiles ?? 'ignore';
+                    if (policy === 'ignore' || policy === 'deny')
+                        continue;
+                }
+                if (this.opts.exclude && isExcluded(filePath, this.opts.exclude))
+                    continue;
+                results.push(filePath);
+            }
+        }
+    }
+    /**
+     * Resolve a sub-path to a FileResponse, or null if not found.
+     * Handles: exclude globs, dotfile policy, stem matching, onDirectory behavior.
+     */
+    async resolve(subPath) {
+        // Normalize: strip leading/trailing slashes
+        const normalized = subPath.replace(/^\/+|\/+$/g, '');
+        // Check dotfile policy
+        if (this.isDotfile(normalized)) {
+            const policy = this.opts.dotfiles ?? 'ignore';
+            if (policy === 'ignore' || policy === 'deny')
+                return null;
+        }
+        // Check exclude patterns
+        if (this.opts.exclude && normalized && isExcluded(normalized, this.opts.exclude)) {
+            return null;
+        }
+        // Empty path = directory root request
+        if (!normalized) {
+            return this.handleDirectory('');
+        }
+        // Try exact file match
+        const content = await this.vfs.read(normalized);
+        if (content !== null) {
+            return this.createFileResponse(content, normalized);
+        }
+        // Check if it's a directory (by listing it)
+        const dirEntries = await this.vfs.list(normalized);
+        if (dirEntries.length > 0) {
+            return this.handleDirectory(normalized);
+        }
+        // Stem matching: if no extension, look for unique match
+        if (!this.hasExtension(normalized)) {
+            return this.stemMatch(normalized);
+        }
+        return null;
+    }
+    isDotfile(path) {
+        const parts = path.split('/');
+        return parts.some(p => p.startsWith('.') && p.length > 1);
+    }
+    hasExtension(path) {
+        const basename = path.split('/').pop() ?? '';
+        return basename.includes('.') && !basename.startsWith('.');
+    }
+    /**
+     * Stem matching: if request path has no extension and exactly one file matches the stem, serve it.
+     * e.g. /assets/readme → serves readme.md if it's the only readme.* in that directory
+     */
+    async stemMatch(normalizedPath) {
+        const parts = normalizedPath.split('/');
+        const stem = parts.pop();
+        const dir = parts.join('/');
+        const entries = await this.vfs.list(dir);
+        const matches = entries.filter(entry => {
+            if (entry.endsWith('/'))
+                return false;
+            const dot = entry.lastIndexOf('.');
+            const entryStem = dot > 0 ? entry.slice(0, dot) : entry;
+            return entryStem === stem;
+        });
+        if (matches.length === 1) {
+            const matched = matches[0];
+            const fullPath = dir ? `${dir}/${matched}` : matched;
+            // Check exclude on the resolved path
+            if (this.opts.exclude && isExcluded(fullPath, this.opts.exclude)) {
+                return null;
+            }
+            const content = await this.vfs.read(fullPath);
+            if (content !== null) {
+                return this.createFileResponse(content, fullPath);
+            }
+        }
+        return null;
+    }
+    async handleDirectory(dirPath) {
+        const onDir = this.opts.onDirectory ?? (this.opts.index ? 'index' : 'none');
+        if (onDir === 'none')
+            return null;
+        if (onDir === 'index') {
+            if (!this.opts.index)
+                return null;
+            const indexPath = dirPath ? `${dirPath}/${this.opts.index}` : this.opts.index;
+            const content = await this.vfs.read(indexPath);
+            if (content === null)
+                return null;
+            return this.createFileResponse(content, indexPath);
+        }
+        const entries = await this.vfs.list(dirPath);
+        if (onDir === 'list') {
+            const json = JSON.stringify(entries);
+            return FileResponse.from(json, 'listing.json');
+        }
+        if (onDir === 'directory') {
+            const html = this.renderDirectoryPage(dirPath, entries);
+            return FileResponse.from(html, 'index.html');
+        }
+        if (typeof onDir === 'function') {
+            return onDir(entries);
+        }
+        return null;
+    }
+    renderDirectoryPage(dirPath, entries) {
+        const title = dirPath || '/';
+        const links = entries
+            .map(entry => {
+            const href = entry;
+            return `    <li><a href="${href}">${entry}</a></li>`;
+        })
+            .join('\n');
+        return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Index of ${title}</title></head>
+<body>
+<h1>Index of /${title}</h1>
+<ul>
+${links}
+</ul>
+</body>
+</html>`;
+    }
+    createFileResponse(content, filePath) {
+        const filename = filePath.split('/').pop() ?? filePath;
+        return FileResponse.from(content, filename, {
+            contentType: getMimeType(filename),
+            maxAge: this.opts.maxAge,
+            headers: this.opts.headers,
+        });
+    }
+}
+/**
+ * Check if a value is a StaticFolder instance (works across module boundaries).
+ */
+export function isStaticFolder(value) {
+    return value != null && typeof value === 'object' && STATIC_FOLDER_BRAND in value;
+}
+//# sourceMappingURL=static-folder.js.map

package/dist/static/static-folder.js.map

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

package/dist/static/virtual-file-system.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Abstraction over file storage. StaticFolder resolves files through this interface.
+ * Implementations: NodeFileSystem (real fs), MemoryFileSystem (in-memory map), or any custom backend.
+ */
+export interface VirtualFileSystem {
+    /**
+     * List entries at a path. Return filenames only (not full paths).
+     * Directories should be suffixed with '/'.
+     * path is '' for root, 'subdir' for a subdirectory.
+     */
+    list(path: string): string[] | Promise<string[]>;
+    /**
+     * Read a file's content. Return null if not found.
+     */
+    read(path: string): string | Uint8Array | null | Promise<string | Uint8Array | null>;
+}
+/**
+ * Check if a value implements the VirtualFileSystem interface.
+ */
+export declare function isVirtualFileSystem(value: unknown): value is VirtualFileSystem;
+/**
+ * VFS backed by Node.js filesystem. Used when StaticFolder is given a directory path string.
+ */
+export declare class NodeFileSystem implements VirtualFileSystem {
+    private root;
+    constructor(directory: string);
+    private resolveSafe;
+    list(subPath: string): Promise<string[]>;
+    read(subPath: string): Promise<Uint8Array | null>;
+}
+export type MemoryFileEntry = string | Uint8Array | {
+    read(): string | Uint8Array | Promise<string | Uint8Array>;
+};
+/**
+ * VFS backed by an in-memory file map.
+ * Keys are paths like 'index.html' or 'css/style.css'.
+ * Values can be raw content or objects with a read() method for lazy evaluation.
+ */
+export declare class MemoryFileSystem implements VirtualFileSystem {
+    private files;
+    constructor(files: Record<string, MemoryFileEntry>);
+    list(subPath: string): string[];
+    read(subPath: string): Promise<string | Uint8Array | null>;
+}
+//# sourceMappingURL=virtual-file-system.d.ts.map

package/dist/static/virtual-file-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-file-system.d.ts","sourceRoot":"","sources":["../../src/static/virtual-file-system.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAEhD;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC,CAAA;CACrF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAO9E;AAED;;GAEG;AACH,qBAAa,cAAe,YAAW,iBAAiB;IACtD,OAAO,CAAC,IAAI,CAAQ;gBAER,SAAS,EAAE,MAAM;IAM7B,OAAO,CAAC,WAAW;IAeb,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAexC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CAUxD;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,GAAG;IAAE,IAAI,IAAI,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC,CAAA;CAAE,CAAA;AAElH;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IAC5C,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAE1D,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAkBzB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;CAOjE"}