asljs-server 0.2.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Alexandrite Software Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# asljs-server
+
+A lightweight development-time static files server with live-reload (SSE) and
+a filesystem read/write API.
+
+## CLI
+
+After installing:
+
+- `asljs-server`
+
+Or without installing:
+
+- `npx asljs-server`
+
+### Examples
+
+- Serve current folder on port 3000:
+  - `asljs-server`
+
+- Serve a specific folder:
+  - `asljs-server ./public`
+  - `asljs-server --root ./public`
+
+- Change port/host:
+  - `asljs-server --port 8080`
+  - `asljs-server --host 0.0.0.0 --port 8080`
+
+## JSON API
+
+- `GET /api/json?file=name[.json]` returns the JSON file
+- `PUT|POST /api/json?file=name[.json]` writes JSON (pretty-printed)
+
+## Live reload
+
+HTML pages get a small client injected that listens on:
+
+- `GET /__events`

package/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import './dist/cli.js';

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,102 @@
+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
+`);
+}
+function readVersion() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const packageJsonPath = path.join(here, '..', 'package.json');
+    const raw = readFileSync(packageJsonPath, 'utf8');
+    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;
+        }
+        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;
+    }
+    return { kind: 'run', options };
+}
+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;
+    }
+}
+catch (error) {
+    const message = (error
+        && typeof error === 'object'
+        && 'message' in error)
+        ? String(error.message)
+        : String(error);
+    process.stderr.write(`${message}\n\n`);
+    printHelp();
+    process.exitCode = 1;
+}

package/dist/send.d.ts

@@ -0,0 +1,13 @@
+import type { OutgoingHttpHeaders } from 'node:http';
+import type { ServerResponse } from 'node:http';
+export declare function options(response: ServerResponse, headers: OutgoingHttpHeaders): void;
+export declare function api(response: ServerResponse, payload: unknown): void;
+export declare function apiError(response: ServerResponse, error: unknown): void;
+export declare function json(response: ServerResponse, status: number, jsonString: unknown): void;
+export declare function html(response: ServerResponse, htmlString: string): void;
+export declare function badRequest(response: ServerResponse, message?: string): void;
+export declare function forbidden(response: ServerResponse, message?: string): void;
+export declare function notFound(response: ServerResponse, message?: string): void;
+export declare function methodNotAllowed(response: ServerResponse, allowed?: string): void;
+export declare function error(response: ServerResponse, err: unknown): void;
+export declare function file(response: ServerResponse, filePath: string): Promise<void>;

package/dist/send.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+const CONTENT_TYPES = new Map([['.html', 'text/html; charset=utf-8'],
+    ['.htm', 'text/html; charset=utf-8'],
+    ['.js', 'text/javascript; charset=utf-8'],
+    ['.mjs', 'text/javascript; charset=utf-8'],
+    ['.css', 'text/css; charset=utf-8'],
+    ['.json', 'application/json; charset=utf-8'],
+    ['.txt', 'text/plain; charset=utf-8'],
+    ['.svg', 'image/svg+xml'],
+    ['.png', 'image/png'],
+    ['.jpg', 'image/jpeg'],
+    ['.jpeg', 'image/jpeg'],
+    ['.gif', 'image/gif'],
+    ['.webp', 'image/webp'],
+    ['.ico', 'image/x-icon'],
+    ['.woff', 'font/woff'],
+    ['.woff2', 'font/woff2']]);
+function contentTypeFor(filePath) {
+    const ext = path.extname(filePath)
+        .toLowerCase();
+    return CONTENT_TYPES.get(ext)
+        || 'application/octet-stream';
+}
+export function options(response, headers) {
+    response.writeHead(204, headers);
+    response.end();
+}
+export function api(response, payload) {
+    response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+    response.end(JSON.stringify(payload));
+}
+export function apiError(response, error) {
+    response.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
+    const message = (error && typeof error === 'object' && 'message' in error)
+        ? String(error.message)
+        : String(error);
+    response.end(JSON.stringify({ error: message }));
+}
+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));
+}
+export function html(response, htmlString) {
+    response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+    response.end(htmlString);
+}
+export function badRequest(response, message = 'Bad request') {
+    response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
+    response.end(message);
+}
+export function forbidden(response, message = 'Forbidden') {
+    response.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+    response.end(message);
+}
+export function notFound(response, message = 'Not found') {
+    response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    response.end(message);
+}
+export function methodNotAllowed(response, allowed = 'GET') {
+    response.writeHead(405, { 'content-type': 'text/plain; charset=utf-8',
+        'allow': allowed });
+    response.end('Method not allowed');
+}
+export function error(response, err) {
+    response.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+    const message = (err && typeof err === 'object' && 'stack' in err)
+        ? String(err.stack)
+        : (err && typeof err === 'object' && 'message' in err)
+            ? String(err.message)
+            : String(err);
+    response.end(message);
+}
+export async function file(response, filePath) {
+    try {
+        const stat = await fsp.stat(filePath);
+        response.writeHead(200, { 'content-type': contentTypeFor(filePath),
+            'content-length': stat.size });
+        fs.createReadStream(filePath)
+            .on('error', err => error(response, err))
+            .pipe(response);
+    }
+    catch (err) {
+        if (err
+            && typeof err === 'object'
+            && 'code' in err
+            && err.code === 'ENOENT') {
+            return notFound(response);
+        }
+        return error(response, err);
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+import type { Server } from 'node:http';
+export type ServerLogger = {
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+export type StartServerOptions = {
+    root?: string;
+    port?: number;
+    host?: string;
+    logger?: ServerLogger;
+};
+export declare function startServer({ root, port, host, logger }?: StartServerOptions): Server;

package/dist/server.js

@@ -0,0 +1,199 @@
+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;
+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());
+    // ---------- JSON API helpers
+    const jsonFilePath = (name) => {
+        const base = safeJsonName(name);
+        if (!base)
+            return null;
+        const file = base.endsWith('.json')
+            ? base
+            : (base + '.json');
+        const full = path.join(FILES_DIR, file);
+        return isPathInside(full, FILES_DIR)
+            ? full
+            : null;
+    };
+    async function handleJsonApi(request, response, url) {
+        await fsp.mkdir(FILES_DIR, { recursive: true });
+        const name = url.searchParams.get('file');
+        const file = jsonFilePath(name);
+        if (!file) {
+            return send.badRequest(response, 'Invalid "file" name. Allowed: [a-zA-Z0-9._-] and optional .json');
+        }
+        if (request.method === 'GET') {
+            try {
+                return send.json(response, 200, await fsp.readFile(file, 'utf8'));
+            }
+            catch (e) {
+                if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT')
+                    return send.notFound(response, 'JSON file not found');
+                throw e;
+            }
+        }
+        if (request.method === 'PUT'
+            || request.method === 'POST') {
+            try {
+                // 1MB limit
+                const body = await readBody(request, 1000000);
+                let parsed;
+                try {
+                    parsed = JSON.parse(body);
+                }
+                catch {
+                    return send.badRequest(response, 'Invalid JSON');
+                }
+                await fsp.writeFile(file, JSON.stringify(parsed, null, 2) + '\n', 'utf8');
+                return send.api(response, { file: path.basename(file) });
+            }
+            catch (error) {
+                return send.apiError(response, error);
+            }
+        }
+        return send.methodNotAllowed(response, 'GET, PUT, POST');
+    }
+    async function serveStatic(request, response, url) {
+        const pathname = decodeURIComponent(url.pathname);
+        // SSE endpoint
+        if (pathname === '/__events') {
+            return serveSSE(request, response);
+        }
+        // JSON API: /api/json?file=name[.json]
+        if (pathname === '/api/json') {
+            return handleJsonApi(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') {
+            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);
+            }
+            catch (error) {
+                return send.error(response, error);
+            }
+        }
+        return send.file(response, filePath);
+    }
+    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;
+}
+const entryFile = process.argv[1];
+if (entryFile
+    && import.meta.url === pathToFileURL(entryFile).href) {
+    startServer();
+}

package/dist/watch.d.ts

@@ -0,0 +1 @@
+export declare function watchStaticTree(rootDir: string, onChange: () => void): () => void;

package/dist/watch.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+export 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/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "asljs-server",
+  "version": "0.2.0",
+  "description": "A lightweight development-time static files server. Supports live-reload. Provides filesystem read-write API.",
+  "type": "module",
+  "main": "server.js",
+  "types": "server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./server.d.ts",
+      "default": "./server.js"
+    }
+  },
+  "bin": {
+    "asljs-server": "./cli.js"
+  },
+  "files": [
+    "dist/**",
+    "server.js",
+    "server.d.ts",
+    "cli.js",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "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)')\""
+  },
+  "keywords": [
+    "server",
+    "development",
+    "live-reload"
+  ],
+  "author": "Alex Netkachov <alex.netkachov@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/AlexandriteSoftware/asljs#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandriteSoftware/asljs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
+  }
+}

package/server.d.ts

@@ -0,0 +1,8 @@
+export {
+  startServer
+} from './dist/server.js';
+
+export type {
+  ServerLogger,
+  StartServerOptions
+} from './dist/server.js';

package/server.js

@@ -0,0 +1,3 @@
+export {
+  startServer
+} from './dist/server.js';