asljs-server 0.2.1 → 0.2.3

package/README.md

@@ -26,12 +26,20 @@ Or without installing:
   - `asljs-server --port 8080`
   - `asljs-server --host 0.0.0.0 --port 8080`
 
+- Map a folder under a virtual path:
+  - `asljs-server --mount assets=../Assets`
+  - Serves `../Assets/logo.png` as `/assets/logo.png`
+
 ## File API
 
 - `GET /api/file?path=path` returns the file contents
 - `PUT|POST /api/file?path=path` writes the file
 - `GET /api/files?path=path` lists all files in the directory
 
+Folder mappings apply to the File API too. For example, with `--mount assets=../Assets`:
+
+- `GET /api/file?path=assets/logo.png`
+
 ## Live reload
 
 HTML pages get a small client injected that listens on:

package/dist/cli.js

@@ -2,20 +2,10 @@ import { startServer } from './server.js';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-function printHelp() {
-    process.stdout.write(`asljs-server
-
-Usage:
-  asljs-server [--root <dir>] [--port <number>] [--host <name>]
-
-Options:
-  --root <dir>     Root directory to serve (default: .)
-  --port <number>  Port to listen on (default: 3000)
-  --host <name>    Host/interface to bind (default: localhost)
-  --help           Show this help
-  --version        Print version
-`);
-}
+import yargs from 'yargs';
+/**
+ * Reads the asljs-server version from package.json.
+ */
 function readVersion() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const packageJsonPath = path.join(here, '..', 'package.json');
@@ -23,80 +13,84 @@ function readVersion() {
     return JSON.parse(raw)
         .version;
 }
-function parseArgs(argv) {
-    const options = { root: '.',
-        port: 3000,
-        host: 'localhost' };
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === '--help'
-            || arg === '-h') {
-            return { kind: 'help' };
-        }
-        if (arg === '--version'
-            || arg === '-v') {
-            return { kind: 'version' };
-        }
-        if (arg === '--root') {
-            const value = argv[++i];
-            if (!value) {
-                throw new TypeError('Missing value for --root');
-            }
-            options.root = value;
-            continue;
-        }
-        if (arg === '--port') {
-            const value = argv[++i];
-            if (!value) {
-                throw new TypeError('Missing value for --port');
-            }
-            const parsed = Number(value);
-            if (!Number.isFinite(parsed)
-                || parsed <= 0) {
-                throw new TypeError('Invalid --port');
-            }
-            options.port = parsed;
-            continue;
+/**
+ * Converts array of strings `[ "<virtual>=<dir>", ... ]` into a map.
+ */
+function parseMounts(mounts) {
+    const map = {};
+    if (!mounts)
+        return map;
+    for (const spec of mounts) {
+        const separatorIndex = spec.indexOf('=');
+        if (separatorIndex === -1) {
+            throw new Error('Incorrect format, expect "<virtual>=<dir>".');
         }
-        if (arg === '--host') {
-            const value = argv[++i];
-            if (!value) {
-                throw new TypeError('Missing value for --host');
-            }
-            options.host = value;
-            continue;
-        }
-        if (arg.startsWith('-')) {
-            throw new TypeError(`Unknown option: ${arg}`);
-        }
-        // Positional = root directory
-        options.root = arg;
+        const virtual = spec.slice(0, separatorIndex);
+        const dir = spec.slice(separatorIndex + 1);
+        map[virtual] = dir;
     }
-    return { kind: 'run', options };
+    return map;
 }
-try {
-    const parsed = parseArgs(process.argv.slice(2));
-    switch (parsed.kind) {
-        case 'help':
-            printHelp();
-            process.exitCode = 0;
-            break;
-        case 'version':
-            process.stdout.write(`${readVersion() ?? ''}\n`);
-            process.exitCode = 0;
-            break;
-        default:
-            startServer(parsed.options);
-            break;
+const version = readVersion() ?? '';
+yargs(process.argv.slice(2))
+    .scriptName('asljs-server')
+    .usage('$0 [root] [options]')
+    .command('$0 [dir]', 'Start the server', (y) => y
+    .positional('dir', { type: 'string',
+    describe: 'Root directory to serve (default: .)' })
+    .option('root', { type: 'string',
+    describe: 'Root directory to serve (default: .)',
+    default: '.' })
+    .option('port', { type: 'number',
+    describe: 'Port to listen on (default: 3000)',
+    default: 3000 })
+    .option('host', { type: 'string',
+    describe: 'Host/interface to bind (default: localhost)',
+    default: 'localhost' })
+    .option('mount', { type: 'string',
+    alias: 'm',
+    array: true,
+    describe: 'Mount a folder under a virtual path (repeatable). Spec: <virtual>=<dir> (example: assets=../Assets)' }), (argv) => {
+    if (!Number.isFinite(argv.port)
+        || argv.port <= 0) {
+        throw new Error('Invalid --port');
     }
-}
-catch (error) {
-    const message = (error
-        && typeof error === 'object'
-        && 'message' in error)
-        ? String(error.message)
-        : String(error);
-    process.stderr.write(`${message}\n\n`);
-    printHelp();
+    if (typeof argv.host !== 'string'
+        || !argv.host) {
+        throw new Error('Missing value for --host');
+    }
+    if (typeof argv.root !== 'string'
+        || !argv.root) {
+        throw new Error('Missing value for --root');
+    }
+    let mounts;
+    try {
+        mounts =
+            parseMounts(argv.mount);
+    }
+    catch (err) {
+        throw new Error(`Invalid --mount. ${err.message}`);
+    }
+    const options = { root: argv.dir ?? argv.root,
+        port: argv.port,
+        host: argv.host,
+        mounts };
+    startServer(options);
+})
+    .strict()
+    .help('help')
+    .alias('help', 'h')
+    .version('version', 'Print version', version)
+    .alias('version', 'v')
+    .exitProcess(false)
+    .fail((msg, err, y) => {
+    const message = err?.message
+        ? String(err.message)
+        : msg;
+    if (message) {
+        process.stderr.write(`${message}\n\n`);
+    }
+    y.showHelp();
     process.exitCode = 1;
-}
+})
+    .parse();

package/dist/module.d.ts

@@ -0,0 +1,5 @@
+import { URL } from 'node:url';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface IRequestHandler {
+    tryHandleRequest(request: IncomingMessage, response: ServerResponse, url: URL): Promise<boolean>;
+}

package/dist/module.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/filesystem-api.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { VirtualFolders } from '../virtual-folders.js';
+import type { IRequestHandler } from '../module.js';
+export declare class FilesystemApi implements IRequestHandler {
+    readonly filesDir: string;
+    readonly virtualFolders: VirtualFolders;
+    constructor(filesDir: string, virtualFolders: VirtualFolders);
+    tryHandleRequest(request: IncomingMessage, response: ServerResponse, url: URL): Promise<boolean>;
+    private fileApiPath;
+    private handleFileApi;
+    private handleFilesApi;
+}

package/dist/modules/filesystem-api.js

@@ -0,0 +1,98 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import * as send from '../send.js';
+import { safePath, readBody } from '../receive.js';
+export class FilesystemApi {
+    constructor(filesDir, virtualFolders) {
+        this.filesDir = filesDir;
+        this.virtualFolders = virtualFolders;
+    }
+    async tryHandleRequest(request, response, url) {
+        const pathname = decodeURIComponent(url.pathname);
+        // File API: /api/file?path=relative/path.ext
+        if (pathname === '/api/file') {
+            await this.handleFileApi(request, response, url);
+            return true;
+        }
+        // Directory listing API: /api/files?path=relative/dir
+        if (pathname === '/api/files') {
+            await this.handleFilesApi(request, response, url);
+            return true;
+        }
+        return false;
+    }
+    fileApiPath(relativePath) {
+        return this.virtualFolders
+            .resolve(relativePath)
+            .path;
+    }
+    async handleFileApi(request, response, url) {
+        const relativePath = safePath(url.searchParams.get('path')
+            || '');
+        if (!relativePath) {
+            return send.badRequest(response, 'Invalid "path". Use a relative path with URL-style separators.');
+        }
+        const filePath = this.fileApiPath(relativePath);
+        if (!filePath) {
+            return send.forbidden(response);
+        }
+        if (request.method === 'GET') {
+            return send.file(response, filePath);
+        }
+        if (request.method === 'PUT'
+            || request.method === 'POST') {
+            await fsp.mkdir(this.filesDir, { recursive: true });
+            try {
+                const body = await readBody(request, 1000000);
+                await fsp.mkdir(path.dirname(filePath), { recursive: true });
+                await fsp.writeFile(filePath, body, 'utf8');
+                return send.api(response, { path: relativePath });
+            }
+            catch (error) {
+                return send.apiError(response, error);
+            }
+        }
+        return send.methodNotAllowed(response, 'GET, PUT, POST');
+    }
+    async handleFilesApi(request, response, url) {
+        if (request.method !== 'GET') {
+            return send.methodNotAllowed(response, 'GET');
+        }
+        const relativePath = safePath(url.searchParams.get('path')
+            || '');
+        if (relativePath === null) {
+            return send.badRequest(response, 'Invalid "path". Use a relative directory path.');
+        }
+        const directoryPath = this.fileApiPath(relativePath);
+        if (!directoryPath) {
+            return send.forbidden(response);
+        }
+        try {
+            const stat = await fsp.stat(directoryPath);
+            if (!stat.isDirectory()) {
+                return send.badRequest(response, '"path" must point to a directory');
+            }
+        }
+        catch (error) {
+            if (error
+                && typeof error === 'object'
+                && 'code' in error
+                && error.code === 'ENOENT') {
+                return send.notFound(response, 'Directory not found');
+            }
+            return send.error(response, error);
+        }
+        try {
+            const entries = await fsp.readdir(directoryPath, { withFileTypes: true });
+            const files = entries
+                .filter(e => e.isFile())
+                .map(e => e.name)
+                .sort((a, b) => a.localeCompare(b));
+            return send.api(response, { path: relativePath,
+                files });
+        }
+        catch (error) {
+            return send.apiError(response, error);
+        }
+    }
+}

package/dist/modules/live-reload.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { IRequestHandler } from '../module.js';
+import { VirtualFolders } from '../virtual-folders.js';
+export declare class LiveReloadSupport implements IRequestHandler {
+    private readonly clients;
+    private readonly headers;
+    private readonly RELOAD_SNIPPET;
+    private readonly stopWatchers;
+    private readonly virtualFolders;
+    private reloadPending;
+    constructor(virtualFolders: VirtualFolders);
+    start(): void;
+    stop(): void;
+    tryHandleRequest(request: IncomingMessage, response: ServerResponse, url: URL): Promise<boolean>;
+    connectClient(request: IncomingMessage, response: ServerResponse): void;
+    broadcastReload(): void;
+    injectReloadScript(html: string): string;
+}

package/dist/modules/live-reload.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+export class LiveReloadSupport {
+    constructor(virtualFolders) {
+        this.clients = new Set();
+        this.headers = { 'content-type': 'text/event-stream',
+            'cache-control': 'no-cache',
+            'connection': 'keep-alive',
+            'x-accel-buffering': 'no' };
+        this.RELOAD_SNIPPET = `
+      <script>
+      try {
+        const es = new EventSource('/__events');
+        es.addEventListener('reload', () => location.reload());
+      } catch (_) {}
+      </script>
+    `;
+        this.stopWatchers = [];
+        this.reloadPending = false;
+        this.virtualFolders = virtualFolders;
+    }
+    start() {
+        for (const mount of this.virtualFolders.mounts) {
+            try {
+                this.stopWatchers.push(watchStaticTree(mount.rootDir, () => this.broadcastReload()));
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    stop() {
+        for (const stop of this.stopWatchers) {
+            try {
+                stop();
+            }
+            catch { }
+        }
+    }
+    async tryHandleRequest(request, response, url) {
+        const pathname = decodeURIComponent(url.pathname);
+        if (pathname === '/__events') {
+            this.connectClient(request, response);
+            return true;
+        }
+        return false;
+    }
+    connectClient(request, response) {
+        response.writeHead(200, this.headers);
+        response.write(': connected\n\n');
+        this.clients.add(response);
+        const ping = setInterval(() => response.write(': ping\n\n'), 30000);
+        request.on('close', () => {
+            clearInterval(ping);
+            this.clients.delete(response);
+        });
+    }
+    broadcastReload() {
+        if (this.reloadPending)
+            return;
+        this.reloadPending = true;
+        setTimeout(() => {
+            this.reloadPending = false;
+            for (const res of this.clients) {
+                res.write('event: reload\n');
+                res.write('data: now\n\n');
+            }
+        }, 50);
+    }
+    injectReloadScript(html) {
+        const htmlWithReload = html.includes('/__events')
+            ? html
+            : html.replace(/<\/body\s*>/i, m => `${this.RELOAD_SNIPPET}\n${m}`)
+                + (!html.match(/<\/body\s*>/i)
+                    ? `\n${this.RELOAD_SNIPPET}`
+                    : '');
+        return htmlWithReload;
+    }
+}
+function watchStaticTree(rootDir, onChange) {
+    // Best-effort cross-platform watcher.
+    // On Windows/macOS, recursive fs.watch works.
+    // On Linux, recursive is not supported, but this package is intended for dev-time usage.
+    let watcher;
+    try {
+        watcher =
+            fs.watch(rootDir, { recursive: true }, () => onChange());
+    }
+    catch {
+        watcher =
+            fs.watch(rootDir, () => onChange());
+    }
+    return () => {
+        try {
+            watcher.close();
+        }
+        catch { }
+    };
+}

package/dist/modules/static-files.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { LiveReloadSupport } from './live-reload.js';
+import { VirtualFolders } from '../virtual-folders.js';
+import type { IRequestHandler } from '../module.js';
+export declare class StaticFilesRequestHandler implements IRequestHandler {
+    private readonly virtualFolders;
+    private readonly liveReloadSupport;
+    constructor(virtualFolders: VirtualFolders, liveReloadSupport: LiveReloadSupport);
+    tryHandleRequest(request: IncomingMessage, response: ServerResponse, url: URL): Promise<boolean>;
+}

package/dist/modules/static-files.js

@@ -0,0 +1,58 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import * as send from '../send.js';
+import { safePath } from '../receive.js';
+export class StaticFilesRequestHandler {
+    constructor(virtualFolders, liveReloadSupport) {
+        this.virtualFolders = virtualFolders;
+        this.liveReloadSupport = liveReloadSupport;
+    }
+    async tryHandleRequest(request, response, url) {
+        const pathname = decodeURIComponent(url.pathname);
+        const safeUrlPath = safePath(pathname.startsWith('/')
+            ? pathname.slice(1)
+            : pathname);
+        if (safeUrlPath === null) {
+            send.forbidden(response);
+            return true;
+        }
+        // Resolve file path
+        let filePath = this.virtualFolders
+            .resolve(safeUrlPath)
+            .path;
+        if (!filePath) {
+            send.forbidden(response);
+            return true;
+        }
+        // If path is dir, try index.html
+        try {
+            const stat = await fsp.stat(filePath);
+            if (stat.isDirectory()) {
+                filePath =
+                    path.join(filePath, 'index.html');
+                await fsp.stat(filePath);
+            }
+        }
+        catch {
+            send.notFound(response);
+            return true;
+        }
+        const ext = path.extname(filePath)
+            .toLowerCase();
+        // HTML: inject hot-reload snippet
+        if (ext === '.html'
+            && request.method === 'GET') {
+            try {
+                const html = await fsp.readFile(filePath, 'utf8');
+                const htmlWithReload = this.liveReloadSupport.injectReloadScript(html);
+                send.html(response, htmlWithReload);
+            }
+            catch (error) {
+                send.error(response, error);
+            }
+            return true;
+        }
+        send.file(response, filePath);
+        return true;
+    }
+}

package/dist/receive.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage } from 'node:http';
+export declare function safePath(value: string): string;
+/**
+ * Reads the body of the given request up to the given size limit.
+ */
+export declare function readBody(request: IncomingMessage, limit: number): Promise<string>;

package/dist/receive.js

@@ -0,0 +1,48 @@
+export function safePath(value) {
+    if (typeof value !== 'string') {
+        throw new TypeError('Value must be a string');
+    }
+    if (value === '') {
+        return '';
+    }
+    const incorrectCharacterMatch = /[^a-zA-Z0-9._/-]/.exec(value);
+    if (incorrectCharacterMatch !== null) {
+        throw new Error(`Incorrect characters in path at position ${incorrectCharacterMatch.index}.`);
+    }
+    if (value.startsWith('/')) {
+        throw new Error('Path must be relative.');
+    }
+    const segments = value.split('/');
+    for (const segment of segments) {
+        if (!segment
+            || segment === '.'
+            || segment === '..') {
+            throw new Error('Path must not contain empty, "." or ".." segments.');
+        }
+    }
+    return value;
+}
+/**
+ * Reads the body of the given request up to the given size limit.
+ */
+export function readBody(request, limit) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        request.on('data', chunk => {
+            const buffer = Buffer.isBuffer(chunk)
+                ? chunk
+                : Buffer.from(chunk);
+            size += buffer.length;
+            if (size > limit) {
+                reject(new Error('Payload is too large'));
+                request.destroy();
+                return;
+            }
+            chunks.push(buffer);
+        });
+        request.on('end', () => resolve(Buffer.concat(chunks)
+            .toString('utf8')));
+        request.on('error', reject);
+    });
+}

package/dist/send.d.ts

@@ -1,13 +1,65 @@
+/**
+ * Functions for sending HTTP responses.
+ *
+ * Exported helpers:
+ *
+ * - `options(ServerResponse, OutgoingHttpHeaders): void`
+ * - `api(ServerResponse, unknown): void`
+ * - `apiError(ServerResponse, unknown): void`
+ * - `json(ServerResponse, number, unknown): void`
+ * - `html(ServerResponse, string): void`
+ * - `badRequest(ServerResponse, string?): void`
+ * - `forbidden(ServerResponse, string?): void`
+ * - `notFound(ServerResponse, string?): void`
+ * - `methodNotAllowed(ServerResponse, string?): void`
+ * - `error(ServerResponse, unknown): void`
+ * - `file(ServerResponse, string): Promise<void>`
+ */
 import type { OutgoingHttpHeaders } from 'node:http';
 import type { ServerResponse } from 'node:http';
+/**
+ * Sends an empty response to the client for an OPTIONS request.
+ * Typically used for CORS preflight requests.
+ */
 export declare function options(response: ServerResponse, headers: OutgoingHttpHeaders): void;
+/**
+ * Sends a JSON API response with status 200.
+ */
 export declare function api(response: ServerResponse, payload: unknown): void;
+/**
+ * Sends an API error message to the response with status 500.
+ */
 export declare function apiError(response: ServerResponse, error: unknown): void;
+/**
+ * Sends a JSON string to the response with the specified status.
+ */
 export declare function json(response: ServerResponse, status: number, jsonString: unknown): void;
+/**
+ * Sends an HTML string to the response with status 200.
+ */
 export declare function html(response: ServerResponse, htmlString: string): void;
+/**
+ * Sends a "Bad request" error message to the response with status 400.
+ */
 export declare function badRequest(response: ServerResponse, message?: string): void;
+/**
+ * Sends a "Forbidden" error message to the response with status 403.
+ */
 export declare function forbidden(response: ServerResponse, message?: string): void;
+/**
+ * Sends a "Not found" error message to the response with status 404.
+ */
 export declare function notFound(response: ServerResponse, message?: string): void;
+/**
+ * Sends a "Method not allowed" error message to the response with status 405.
+ */
 export declare function methodNotAllowed(response: ServerResponse, allowed?: string): void;
+/**
+ * Sends an error message to the response with status 500.
+ */
 export declare function error(response: ServerResponse, err: unknown): void;
+/**
+ * Sends a static file, specified by `filePath`, to the response,
+ * asynchronously.
+ */
 export declare function file(response: ServerResponse, filePath: string): Promise<void>;

package/dist/send.js

@@ -1,6 +1,25 @@
+/**
+ * Functions for sending HTTP responses.
+ *
+ * Exported helpers:
+ *
+ * - `options(ServerResponse, OutgoingHttpHeaders): void`
+ * - `api(ServerResponse, unknown): void`
+ * - `apiError(ServerResponse, unknown): void`
+ * - `json(ServerResponse, number, unknown): void`
+ * - `html(ServerResponse, string): void`
+ * - `badRequest(ServerResponse, string?): void`
+ * - `forbidden(ServerResponse, string?): void`
+ * - `notFound(ServerResponse, string?): void`
+ * - `methodNotAllowed(ServerResponse, string?): void`
+ * - `error(ServerResponse, unknown): void`
+ * - `file(ServerResponse, string): Promise<void>`
+ */
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+// Map of file extensions to content types.
+// Used by `file()` to set the Content-Type header.
 const CONTENT_TYPES = new Map([['.html', 'text/html; charset=utf-8'],
     ['.htm', 'text/html; charset=utf-8'],
     ['.js', 'text/javascript; charset=utf-8'],
@@ -17,20 +36,33 @@ const CONTENT_TYPES = new Map([['.html', 'text/html; charset=utf-8'],
     ['.ico', 'image/x-icon'],
     ['.woff', 'font/woff'],
     ['.woff2', 'font/woff2']]);
+/**
+ * Returns the content type for the specified file path, based on its extension.
+ */
 function contentTypeFor(filePath) {
     const ext = path.extname(filePath)
         .toLowerCase();
     return CONTENT_TYPES.get(ext)
         || 'application/octet-stream';
 }
+/**
+ * Sends an empty response to the client for an OPTIONS request.
+ * Typically used for CORS preflight requests.
+ */
 export function options(response, headers) {
     response.writeHead(204, headers);
     response.end();
 }
+/**
+ * Sends a JSON API response with status 200.
+ */
 export function api(response, payload) {
     response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
     response.end(JSON.stringify(payload));
 }
+/**
+ * Sends an API error message to the response with status 500.
+ */
 export function apiError(response, error) {
     response.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
     const message = (error && typeof error === 'object' && 'message' in error)
@@ -38,33 +70,54 @@ export function apiError(response, error) {
         : String(error);
     response.end(JSON.stringify({ error: message }));
 }
+/**
+ * Sends a JSON string to the response with the specified status.
+ */
 export function json(response, status, jsonString) {
     response.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     response.end(typeof jsonString === 'string'
         ? jsonString
         : JSON.stringify(jsonString));
 }
+/**
+ * Sends an HTML string to the response with status 200.
+ */
 export function html(response, htmlString) {
     response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
     response.end(htmlString);
 }
+/**
+ * Sends a "Bad request" error message to the response with status 400.
+ */
 export function badRequest(response, message = 'Bad request') {
     response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
     response.end(message);
 }
+/**
+ * Sends a "Forbidden" error message to the response with status 403.
+ */
 export function forbidden(response, message = 'Forbidden') {
     response.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
     response.end(message);
 }
+/**
+ * Sends a "Not found" error message to the response with status 404.
+ */
 export function notFound(response, message = 'Not found') {
     response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
     response.end(message);
 }
+/**
+ * Sends a "Method not allowed" error message to the response with status 405.
+ */
 export function methodNotAllowed(response, allowed = 'GET') {
     response.writeHead(405, { 'content-type': 'text/plain; charset=utf-8',
         'allow': allowed });
     response.end('Method not allowed');
 }
+/**
+ * Sends an error message to the response with status 500.
+ */
 export function error(response, err) {
     response.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
     const message = (err && typeof err === 'object' && 'stack' in err)
@@ -74,6 +127,10 @@ export function error(response, err) {
             : String(err);
     response.end(message);
 }
+/**
+ * Sends a static file, specified by `filePath`, to the response,
+ * asynchronously.
+ */
 export async function file(response, filePath) {
     try {
         const stat = await fsp.stat(filePath);

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import type { Server } from 'node:http';
+import type { Server as HttpServer } from 'node:http';
 export type ServerLogger = {
     log: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
@@ -7,6 +7,21 @@ export type StartServerOptions = {
     root?: string;
     port?: number;
     host?: string;
+    fsapi?: boolean;
     logger?: ServerLogger;
+    mounts?: Record<string, string>;
 };
-export declare function startServer({ root, port, host, logger }?: StartServerOptions): Server;
+export declare class Server {
+    private readonly root;
+    private readonly port;
+    private readonly host;
+    private readonly logger;
+    private readonly filesDir;
+    private readonly virtualFolders;
+    private readonly requestHandlers;
+    private readonly server;
+    constructor({ root, port, host, logger, mounts }?: StartServerOptions);
+    listen(): HttpServer;
+    private serve;
+}
+export declare function startServer(options?: StartServerOptions): HttpServer;

package/dist/server.js

@@ -1,268 +1,76 @@
 import http from 'node:http';
-import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { URL, pathToFileURL } from 'node:url';
 import * as send from './send.js';
-import { watchStaticTree } from './watch.js';
-function isPathInside(child, parent) {
-    const resolved = path.resolve(child);
-    return resolved === parent
-        || resolved.startsWith(parent + path.sep);
-}
-// inject minimal client into served HTML
-const RELOAD_SNIPPET = `<script>
-try {
-  const es = new EventSource('/__events');
-  es.addEventListener('reload', () => location.reload());
-} catch (_) {}
-</script>`;
-const safeJsonName = (name) => typeof name === 'string'
-    && /^[a-zA-Z0-9._/-]+$/.test(name)
-    ? name
-    : null;
-const safeRelativeApiPath = (value, { allowEmpty = false } = {}) => {
-    if (value === null
-        || value === undefined) {
-        return allowEmpty
-            ? ''
-            : null;
-    }
-    if (typeof value !== 'string')
-        return null;
-    if (value === '')
-        return allowEmpty
-            ? ''
-            : null;
-    if (!/^[a-zA-Z0-9._/-]+$/.test(value))
-        return null;
-    // Force URL-style separators.
-    if (value.includes('\\'))
-        return null;
-    if (value.startsWith('/'))
-        return null;
-    const parts = value.split('/');
-    for (const part of parts) {
-        if (!part
-            || part === '.'
-            || part === '..') {
-            return null;
-        }
-    }
-    return value;
-};
-function readBody(request, limit) {
-    return new Promise((resolve, reject) => {
-        let size = 0;
-        const chunks = [];
-        request.on('data', chunk => {
-            const buffer = Buffer.isBuffer(chunk)
-                ? chunk
-                : Buffer.from(chunk);
-            size += buffer.length;
-            if (size > limit) {
-                reject(new Error('Payload too large'));
-                request.destroy();
-                return;
-            }
-            chunks.push(buffer);
-        });
-        request.on('end', () => resolve(Buffer.concat(chunks)
-            .toString('utf8')));
-        request.on('error', reject);
-    });
-}
-const options = { 'access-control-allow-origin': '*',
-    'access-control-allow-methods': 'GET,POST,PUT,OPTIONS',
-    'access-control-allow-headers': 'content-type' };
-export function startServer({ root = '.', port = 3000, host = 'localhost', logger = console } = {}) {
-    const FILES_DIR = path.resolve(root);
-    // ---------- hot reload (SSE)
-    const sseClients = new Set();
-    const sseHeaders = { 'content-type': 'text/event-stream',
-        'cache-control': 'no-cache',
-        'connection': 'keep-alive',
-        'x-accel-buffering': 'no' };
-    const serveSSE = (req, res) => {
-        res.writeHead(200, sseHeaders);
-        res.write(': connected\n\n'); // comment = keep-alive
-        sseClients.add(res);
-        const ping = setInterval(() => res.write(': ping\n\n'), 30000);
-        req.on('close', () => {
-            clearInterval(ping);
-            sseClients.delete(res);
-        });
-    };
-    let reloadPending = false;
-    const broadcastReload = () => {
-        if (reloadPending)
-            return;
-        reloadPending = true;
-        setTimeout(() => {
-            reloadPending = false;
-            for (const res of sseClients) {
-                res.write('event: reload\n');
-                res.write('data: now\n\n');
-            }
-        }, 50);
-    };
-    watchStaticTree(FILES_DIR, () => broadcastReload());
-    // ---------- File API helpers
-    const fileApiPath = (relativePath) => {
-        const full = path.join(FILES_DIR, relativePath);
-        return isPathInside(full, FILES_DIR)
-            ? full
-            : null;
-    };
-    async function handleFileApi(request, response, url) {
-        await fsp.mkdir(FILES_DIR, { recursive: true });
-        const relativePath = safeRelativeApiPath(url.searchParams.get('path'));
-        if (!relativePath) {
-            return send.badRequest(response, 'Invalid "path". Use a relative path with URL-style separators.');
-        }
-        const filePath = fileApiPath(relativePath);
-        if (!filePath) {
-            return send.forbidden(response);
-        }
-        if (request.method === 'GET') {
-            return send.file(response, filePath);
-        }
-        if (request.method === 'PUT'
-            || request.method === 'POST') {
-            try {
-                // 1MB limit
-                const body = await readBody(request, 1000000);
-                await fsp.mkdir(path.dirname(filePath), { recursive: true });
-                // Preserve the old behavior for JSON files.
-                if (path.extname(filePath).toLowerCase() === '.json') {
-                    let parsed;
-                    try {
-                        parsed = JSON.parse(body);
-                    }
-                    catch {
-                        return send.badRequest(response, 'Invalid JSON');
-                    }
-                    await fsp.writeFile(filePath, JSON.stringify(parsed, null, 2) + '\n', 'utf8');
+import { VirtualFolders } from './virtual-folders.js';
+import { LiveReloadSupport } from './modules/live-reload.js';
+import { FilesystemApi } from './modules/filesystem-api.js';
+import { StaticFilesRequestHandler } from './modules/static-files.js';
+export class Server {
+    constructor({ root = '.', port = 3000, host = 'localhost', logger = console, mounts = {} } = {}) {
+        this.root = root;
+        this.port = port;
+        this.host = host;
+        this.logger = logger;
+        this.filesDir =
+            path.resolve(this.root);
+        this.virtualFolders =
+            new VirtualFolders(this.filesDir, mounts);
+        const liveReloadSupport = new LiveReloadSupport(this.virtualFolders);
+        const filesystemApi = new FilesystemApi(this.filesDir, this.virtualFolders);
+        const staticFilesHandler = new StaticFilesRequestHandler(this.virtualFolders, liveReloadSupport);
+        this.requestHandlers =
+            [liveReloadSupport,
+                filesystemApi,
+                staticFilesHandler];
+        liveReloadSupport.start();
+        this.server =
+            http.createServer((request, response) => {
+                if (request.method === 'OPTIONS') {
+                    return send.options(response, { 'access-control-allow-origin': '*',
+                        'access-control-allow-methods': 'GET,POST,PUT,OPTIONS',
+                        'access-control-allow-headers': 'content-type' });
                 }
-                else {
-                    await fsp.writeFile(filePath, body, 'utf8');
-                }
-                return send.api(response, { path: relativePath });
-            }
-            catch (error) {
-                return send.apiError(response, error);
-            }
-        }
-        return send.methodNotAllowed(response, 'GET, PUT, POST');
+                this.logger.log(`${request.method} ${request.url}`);
+                this.serve(request, response, new URL(request.url || '/', `http://${request.headers.host || `${this.host}:${this.port}`}`))
+                    .catch(error => {
+                    this.logger.error(error);
+                    send.error(response, error);
+                });
+            });
+        this.server.on('close', () => {
+            liveReloadSupport.stop();
+        });
     }
-    async function handleFilesApi(request, response, url) {
-        if (request.method !== 'GET') {
-            return send.methodNotAllowed(response, 'GET');
-        }
-        await fsp.mkdir(FILES_DIR, { recursive: true });
-        const relativePath = safeRelativeApiPath(url.searchParams.get('path'), { allowEmpty: true });
-        if (relativePath === null) {
-            return send.badRequest(response, 'Invalid "path". Use a relative directory path.');
-        }
-        const directoryPath = fileApiPath(relativePath);
-        if (!directoryPath) {
-            return send.forbidden(response);
-        }
-        try {
-            const stat = await fsp.stat(directoryPath);
-            if (!stat.isDirectory()) {
-                return send.badRequest(response, '"path" must point to a directory');
+    listen() {
+        this.server.listen(this.port, this.host, () => {
+            this.logger.log(`FILES: ${this.filesDir}`);
+            for (const mount of this.virtualFolders.mounts) {
+                this.logger.log(`VIRTUAL FOLDER:   /${mount.virtual} -> ${mount.rootDir}`);
             }
-        }
-        catch (error) {
-            if (error
-                && typeof error === 'object'
-                && 'code' in error
-                && error.code === 'ENOENT') {
-                return send.notFound(response, 'Directory not found');
-            }
-            return send.error(response, error);
-        }
-        try {
-            const entries = await fsp.readdir(directoryPath, { withFileTypes: true });
-            const files = entries
-                .filter(e => e.isFile())
-                .map(e => e.name)
-                .sort((a, b) => a.localeCompare(b));
-            return send.api(response, { path: relativePath,
-                files });
-        }
-        catch (error) {
-            return send.apiError(response, error);
-        }
+            this.logger.log(`URL:   http://${this.host}:${this.port}`);
+        });
+        return this.server;
     }
-    async function serveStatic(request, response, url) {
-        const pathname = decodeURIComponent(url.pathname);
-        // SSE endpoint
-        if (pathname === '/__events') {
-            return serveSSE(request, response);
-        }
-        // File API: /api/file?path=relative/path.ext
-        if (pathname === '/api/file') {
-            return handleFileApi(request, response, url);
-        }
-        // Directory listing API: /api/files?path=relative/dir
-        if (pathname === '/api/files') {
-            return handleFilesApi(request, response, url);
-        }
-        // Resolve file path
-        let filePath = path.normalize(path.join(FILES_DIR, pathname));
-        if (!isPathInside(filePath, FILES_DIR)) {
-            return send.forbidden(response);
-        }
-        // If path is dir, try index.html
-        try {
-            const stat = await fsp.stat(filePath);
-            if (stat.isDirectory()) {
-                filePath =
-                    path.join(filePath, 'index.html');
-                await fsp.stat(filePath);
-            }
-        }
-        catch {
-            return send.notFound(response);
-        }
-        const ext = path.extname(filePath)
-            .toLowerCase();
-        // HTML: inject hot-reload snippet
-        if (ext === '.html'
-            && request.method === 'GET') {
+    async serve(request, response, url) {
+        for (const handler of this.requestHandlers) {
             try {
-                const html = await fsp.readFile(filePath, 'utf8');
-                const htmlWithReload = html.includes('/__events')
-                    ? html
-                    : html.replace(/<\/body\s*>/i, m => `${RELOAD_SNIPPET}\n${m}`) +
-                        (!html.match(/<\/body\s*>/i)
-                            ? `\n${RELOAD_SNIPPET}`
-                            : '');
-                return send.html(response, htmlWithReload);
+                if (await handler.tryHandleRequest(request, response, url)) {
+                    return;
+                }
             }
             catch (error) {
-                return send.error(response, error);
+                this.logger.error(error);
+                send.error(response, error);
+                return;
             }
         }
-        return send.file(response, filePath);
+        send.notFound(response);
     }
-    const server = http.createServer((request, response) => {
-        if (request.method === 'OPTIONS') {
-            return send.options(response, options);
-        }
-        logger.log(`${request.method} ${request.url}`);
-        serveStatic(request, response, new URL(request.url || '/', `http://${request.headers.host || `${host}:${port}`}`))
-            .catch(error => {
-            logger.error(error);
-            send.error(response, error);
-        });
-    });
-    server.listen(port, host, () => {
-        logger.log(`FILES: ${FILES_DIR}`);
-        logger.log(`URL:   http://${host}:${port}`);
-    });
-    return server;
+}
+export function startServer(options = {}) {
+    return new Server(options)
+        .listen();
 }
 const entryFile = process.argv[1];
 if (entryFile

package/dist/virtual-folders.d.ts

@@ -0,0 +1,17 @@
+export type VerifySafeRelativePathOptions = {
+    allowEmpty?: boolean;
+};
+export type VirtualFolderMount = {
+    virtual: string;
+    rootDir: string;
+};
+export declare class VirtualFolders {
+    readonly baseDir: string;
+    readonly mounts: ReadonlyArray<VirtualFolderMount>;
+    constructor(baseDir: string, mounts?: Record<string, string>);
+    resolve(value: string): {
+        rootDir: string;
+        relativePath: string;
+        path: string;
+    };
+}

package/dist/virtual-folders.js

@@ -0,0 +1,74 @@
+import path from 'node:path';
+import { safePath } from './receive.js';
+function isPathInside(child, parent) {
+    const childPath = path.resolve(path.normalize(child));
+    const parentPath = path.resolve(path.normalize(parent));
+    return childPath === parentPath
+        || childPath.startsWith(parentPath + path.sep);
+}
+export class VirtualFolders {
+    constructor(baseDir, mounts = {}) {
+        if (!baseDir
+            || typeof baseDir !== 'string') {
+            throw new TypeError('VirtualFolders: baseDir must be a string');
+        }
+        this.baseDir =
+            path.resolve(path.normalize(baseDir));
+        this.mounts =
+            Object.entries(mounts)
+                .map(([virtual, dir]) => {
+                const safeVirtualPath = safePath(virtual);
+                if (safeVirtualPath === null
+                    || safeVirtualPath === '') {
+                    throw new TypeError('Invalid mount virtual path');
+                }
+                if (typeof dir !== 'string') {
+                    throw new TypeError('Invalid mount dir');
+                }
+                return {
+                    virtual: safeVirtualPath,
+                    rootDir: path.resolve(path.normalize(dir))
+                };
+            })
+                // Prefer longer (more specific) virtual paths.
+                .sort((a, b) => b.virtual.length
+                - a.virtual.length);
+    }
+    resolve(value) {
+        const safeRelativePath = safePath(value);
+        if (safeRelativePath === null) {
+            throw new TypeError('Value must be a safe relative path.');
+        }
+        if (safeRelativePath === '') {
+            return { rootDir: this.baseDir,
+                relativePath: '',
+                path: this.baseDir };
+        }
+        for (const mount of this.mounts) {
+            if (safeRelativePath === mount.virtual) {
+                return { rootDir: mount.rootDir,
+                    relativePath: '',
+                    path: mount.rootDir };
+            }
+            const prefix = mount.virtual + '/';
+            if (safeRelativePath.startsWith(prefix)) {
+                const resolvedRelativePath = safeRelativePath.slice(prefix.length);
+                const fullPath = path.join(mount.rootDir, resolvedRelativePath);
+                if (!isPathInside(fullPath, mount.rootDir)) {
+                    throw new Error('Resolved path is outside of virtual folder root.');
+                }
+                return resolveResult(mount.rootDir, resolvedRelativePath);
+            }
+        }
+        return resolveResult(this.baseDir, safeRelativePath);
+        function resolveResult(baseDir, relativePath) {
+            const fullPath = path.join(baseDir, relativePath);
+            if (!isPathInside(fullPath, baseDir)) {
+                throw new Error('Resolved path is outside of virtual folder root.');
+            }
+            return { rootDir: baseDir,
+                relativePath: relativePath,
+                path: fullPath };
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asljs-server",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "A lightweight development-time static files server. Supports live-reload. Provides filesystem read-write API.",
   "type": "module",
   "main": "server.js",
@@ -24,12 +24,13 @@
   ],
   "scripts": {
     "build": "tsc -p .",
+    "build:tests": "tsc -p tsconfig.tests.json",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "prepack": "npm run build",
-    "test": "npm run build && node --test",
-    "test:watch": "npm run build && node --watch --test",
-    "coverage": "npm run build && NODE_V8_COVERAGE=.coverage node --test && node -e \"console.log('Coverage in .coverage (use c8/istanbul if you want reports)')\""
+    "test": "npm run build && npm run build:tests && node --test .tests/*.test.js",
+    "test:watch": "npm run build && npm run build:tests && node --watch --test .tests/*.test.js",
+    "coverage": "npm run build && npm run build:tests && NODE_V8_COVERAGE=.coverage node --test .tests/*.test.js && node -e \"console.log('Coverage in .coverage (use c8/istanbul if you want reports)')\""
   },
   "keywords": [
     "server",
@@ -45,5 +46,8 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
+  },
+  "dependencies": {
+    "yargs": "^17.7.2"
   }
 }