@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/adapter/express/ExpressHTTPEntrypoint.js

@@ -0,0 +1,301 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressHTTPEntrypoint = expressHTTPEntrypoint;
+const express_1 = __importDefault(require("express"));
+const node_http_1 = require("node:http");
+const node_path_1 = __importDefault(require("node:path"));
+const HTTPContext_js_1 = require("../../context/HTTPContext.js");
+const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
+const Result_js_1 = require("../../lib/Result.js");
+const RouteNotFoundException_js_1 = require("../../exceptions/RouteNotFoundException.js");
+const Responders_js_1 = require("./Responders.js");
+/**
+ * The first segments of the routes
+ * @param routes
+ */
+function actionPrefixesOf(routes) {
+    const prefixes = new Set();
+    for (const route of routes) {
+        const segment = route.split('/').find((part) => !!part);
+        //A route starting with a parameter matches every path
+        if (segment && !/^[:*]/.test(segment))
+            prefixes.add(`/${segment}`);
+    }
+    return [...prefixes];
+}
+/**
+ * The data of an event of a stream
+ * @param data
+ * @param event
+ * @param id
+ */
+function eventFrame(data, event, id) {
+    let frame = '';
+    if (id !== undefined)
+        frame += `id: ${id}\n`;
+    if (event !== undefined)
+        frame += `event: ${event}\n`;
+    const text = typeof data === 'string' ? data : JSON.stringify(data);
+    for (const line of text.split(/\r?\n/))
+        frame += `data: ${line}\n`;
+    return `${frame}\n`;
+}
+/**
+ * Create the HTTP adapter of an entrypoint served by an express application: each HTTP action (`@GET`, `@POST`,
+ * `@HTTPAction`…) becomes an express route. It needs the optional peer dependency `express`.
+ *
+ * An action's input is the request's query and body (see the `input` option) with the route parameters merged over
+ * them. Its result is written by the responder (JSON by default, 204 for no result); a `StatusResult` sets the status
+ * and the headers, a `FileResult` sends a file, a buffer or a stream (304 when its ETag matches `If-None-Match`), and an
+ * `EventsResult` streams Server-Sent Events. An action that writes the response itself (through
+ * `HTTPContext.response`) is left alone. The errors are written by the responder with their status (400 for the
+ * validation failures, 500 by default).
+ *
+ * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
+ * entrypoint stops, the server stops accepting connections, the event streams end, and the requests in progress are
+ * given up to one second after they settle to send their responses before the remaining connections are closed.
+ * @param options The adapter options; by default it listens on port 80 of all the interfaces with a new express
+ * application.
+ * @returns The adapter, to give to the `http` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET, POST} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, staticUI} from 'lakutata/adapter/express'
+ *
+ * class UserController extends Controller {
+ *     //GET /users/1?verbose=true: the route parameter id merged over the query
+ *     @GET('/users/:id')
+ *     public async get(input: {id: string, verbose?: string}): Promise<{id: string}> {
+ *         return {id: input.id}
+ *     }
+ *
+ *     //POST /users with the JSON body {"name": "Ada"}
+ *     @POST('/users')
+ *     public async create(input: {name: string}): Promise<{name: string}> {
+ *         return {name: input.name}
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [UserController],
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 body: {limit: '5mb'},
+ *                 //The application's own routes, before the actions
+ *                 before: (app): void => {
+ *                     app.get('/health', (request, response): void => void response.send('ok'))
+ *                 },
+ *                 //The pages of the UI built in ./ui/dist, for the paths outside /users
+ *                 fallback: staticUI('./ui/dist')
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+function expressHTTPEntrypoint(options = {}) {
+    const respond = options.respond ?? Responders_js_1.JSONResponder;
+    const input = options.input ?? ((request) => ({ ...request.query, ...(request.body && typeof request.body === 'object' ? request.body : {}) }));
+    const streams = new Set();
+    let server;
+    let closed;
+    let stopping = false;
+    //The responses of the actions not sent yet
+    const responding = new Set();
+    /**
+     * Stream the events of a result
+     * @param result
+     * @param request
+     * @param response
+     */
+    const streamEvents = async (result, request, response) => {
+        const abortController = new AbortController();
+        streams.add(abortController);
+        response.status(200).set({
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache, no-transform',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no'
+        }).flushHeaders();
+        const heartbeat = setInterval(() => response.write(': ping\n\n'), options.heartbeat ?? 15000);
+        const close = () => abortController.abort();
+        response.on('close', close);
+        try {
+            await result.producer((data, event, id) => {
+                if (!abortController.signal.aborted)
+                    response.write(eventFrame(data, event, id));
+            }, abortController.signal);
+        }
+        catch {
+            //The stream is already started, its error ends it
+        }
+        finally {
+            clearInterval(heartbeat);
+            response.off('close', close);
+            streams.delete(abortController);
+            if (!response.writableEnded)
+                response.end();
+        }
+    };
+    /**
+     * Send a file
+     * @param result
+     * @param request
+     * @param response
+     */
+    const sendFile = async (result, request, response) => {
+        const { contentType, filename, etag, headers } = result.options;
+        if (headers)
+            response.set(headers);
+        if (etag) {
+            response.set('ETag', `"${etag}"`);
+            if (request.headers['if-none-match'] === `"${etag}"`) {
+                response.status(304).end();
+                return;
+            }
+        }
+        if (filename)
+            response.attachment(filename);
+        if (contentType)
+            response.type(contentType);
+        const source = result.source;
+        if (typeof source === 'string') {
+            await new Promise((resolve, reject) => response.sendFile(node_path_1.default.resolve(source), (error) => error ? reject(error) : resolve()));
+        }
+        else if (Buffer.isBuffer(source)) {
+            response.send(source);
+        }
+        else {
+            await new Promise((resolve, reject) => {
+                source.once('error', reject).pipe(response).once('finish', resolve);
+            });
+        }
+    };
+    /**
+     * Write the result of an action
+     * @param result
+     * @param request
+     * @param response
+     */
+    const output = async (result, request, response) => {
+        //The action wrote the response itself
+        if (response.headersSent)
+            return;
+        if (result instanceof Result_js_1.EventsResult)
+            return await streamEvents(result, request, response);
+        if (result instanceof Result_js_1.FileResult)
+            return await sendFile(result, request, response);
+        if (result instanceof Result_js_1.StatusResult) {
+            response.status(result.status).set(result.headers);
+            return respond.success(response, result.data, request);
+        }
+        respond.success(response, result, request);
+    };
+    /**
+     * The handler of the requests of an action
+     * @param runtime
+     * @param action
+     */
+    const actionHandler = (runtime, action) => (request, response) => {
+        const abortController = new AbortController();
+        const responded = new Promise((resolve) => void response.once('close', resolve));
+        responding.add(responded);
+        //The client left before the response was sent
+        response.on('close', () => {
+            responding.delete(responded);
+            if (!response.writableFinished)
+                abortController.abort();
+        });
+        //While the adapter stops, the connections are closed once their response is sent
+        response.on('finish', () => {
+            if (stopping)
+                setImmediate(() => server?.closeIdleConnections());
+        });
+        const dispatch = async () => {
+            const context = new HTTPContext_js_1.HTTPContext({
+                route: action.address.route,
+                method: action.address.method,
+                request: request,
+                response: response,
+                data: input(request)
+            });
+            const result = await runtime.dispatchTo(action, context, { signal: abortController.signal, params: { ...request.params } });
+            if (!abortController.signal.aborted)
+                await output(result, request, response);
+        };
+        dispatch().catch((error) => {
+            if (!response.headersSent && !abortController.signal.aborted)
+                respond.error(response, error, request, 'action');
+        });
+    };
+    return {
+        channel: 'http',
+        definition: BuiltinChannels_js_1.HTTPChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            const app = options.app ?? (0, express_1.default)();
+            server = (0, node_http_1.createServer)(options.server ?? {}, app);
+            const routes = new Map();
+            for (const action of runtime.actions)
+                routes.set(action.address.route, (routes.get(action.address.route) ?? new Set()).add(action.address.method));
+            const actionPrefixes = actionPrefixesOf(routes.keys());
+            const isActionPath = (requestPath) => actionPrefixes.some((prefix) => requestPath === prefix || requestPath.startsWith(`${prefix}/`));
+            await options.before?.(app, { module: runtime.module, server: server, routes: routes, actionPrefixes: actionPrefixes, isActionPath: isActionPath });
+            if (options.body !== false)
+                app.use(express_1.default.json({ limit: options.body?.limit ?? '1mb' }), express_1.default.urlencoded({ extended: true, limit: options.body?.limit ?? '1mb' }));
+            for (const action of runtime.actions) {
+                const method = String(action.address.method).toLowerCase();
+                const register = app[method];
+                if (typeof register !== 'function')
+                    throw new TypeError(`Unsupported HTTP method "${action.address.method}" of the route "${action.address.route}"`);
+                register.call(app, action.address.route, actionHandler(runtime, action));
+            }
+            const fallback = options.fallback;
+            if (fallback)
+                app.use((request, response, next) => isActionPath(request.path) ? next() : fallback(request, response, next));
+            app.use((request, response) => respond.error(response, new RouteNotFoundException_js_1.RouteNotFoundException('Route {route} not found', { route: request.path }), request, 'request'));
+            app.use((error, request, response, next) => {
+                if (response.headersSent)
+                    return next(error);
+                respond.error(response, error, request, 'request');
+            });
+            //The adapter starts once the server listens (an occupied port fails the start)
+            await new Promise((resolve, reject) => {
+                server.once('error', reject).listen(options.port ?? 80, options.host, () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+        },
+        stop: () => {
+            //The event streams end, the server stops accepting connections and closes the idle ones
+            stopping = true;
+            streams.forEach((stream) => stream.abort());
+            if (!server?.listening)
+                return;
+            closed = new Promise((resolve) => void server.close(() => resolve()));
+            server.closeIdleConnections();
+        },
+        close: async () => {
+            //The requests in progress ended or were aborted: their responses are written, then the remaining connections are closed
+            let timer;
+            await Promise.race([Promise.all(responding), new Promise((resolve) => {
+                    timer = setTimeout(resolve, 1000);
+                })]);
+            clearTimeout(timer);
+            server?.closeAllConnections();
+            await closed;
+            await options.stop?.();
+        }
+    };
+}

package/dist/cjs/adapter/express/Responders.d.ts

@@ -0,0 +1,89 @@
+import type { Request, Response } from 'express';
+import { describeError, type HTTPErrorOrigin, statusOfError } from '../../lib/HTTPErrors.js';
+export { describeError, statusOfError, type HTTPErrorOrigin };
+/**
+ * How {@link expressHTTPEntrypoint} writes the results and the errors of the actions (its `respond` option). Implement
+ * it to give the responses another shape; {@link JSONResponder} is the default, {@link jsonEnvelope} wraps them in an
+ * envelope. The file results and the event streams are not written by the responder.
+ */
+export interface ExpressResponder {
+    /**
+     * Write the result of an action. For a `StatusResult`, its status and headers are already set on the response and
+     * `data` is its payload.
+     * @param response The express response to write.
+     * @param data The action's result, `undefined` when it returned nothing.
+     * @param request The express request being answered.
+     */
+    success(response: Response, data: unknown, request: Request): void;
+    /**
+     * Write an error: a failed action (validation, access control, its own exception), an error passed by an express
+     * middleware (`next(error)`: an authenticator), or a request matching no route (`RouteNotFoundException`). Not
+     * called once the response headers are sent, nor after the client left.
+     * @param response The express response to write.
+     * @param error The thrown error.
+     * @param request The express request being answered.
+     * @param origin Where the error comes from: `'action'` (the dispatch of an action failed) or `'request'` (an
+     * express middleware, a route not found); see {@link HTTPErrorOrigin}.
+     */
+    error(response: Response, error: unknown, request: Request, origin?: HTTPErrorOrigin): void;
+}
+/**
+ * The default responder of {@link expressHTTPEntrypoint}: a result is sent as JSON, no result as an empty 204 (or the
+ * status set by a `StatusResult`); an error is sent as `{errno, errMsg}` (see `describeError`) with its HTTP status
+ * (see `statusOfError`: the first 4xx status in its cause chain, its own status, or 500).
+ */
+export declare const JSONResponder: ExpressResponder;
+/**
+ * The options of {@link jsonEnvelope}.
+ */
+export type JSONEnvelopeOptions = {
+    /**
+     * The HTTP status of every error response, such as 200 for the clients that read the errors from the envelope.
+     * @default the error's own status (see `statusOfError`)
+     */
+    errorStatus?: number;
+    /**
+     * The HTTP status of the errors of the actions only (their dispatch failed: validation, access control, their own
+     * exceptions), over `errorStatus`; the errors of the express middlewares (an authenticator's 401) and the routes
+     * not found keep theirs. 200 answers as the applications of lakutata 2.x usually did.
+     * @default `errorStatus`
+     */
+    actionErrorStatus?: number;
+};
+/**
+ * Create a responder for {@link expressHTTPEntrypoint} that wraps every response in the envelope
+ * `{errno, errMsg, data}`: a result as `{errno: null, errMsg: null, data}` (`data` is `null` when the action returned
+ * nothing, and its status is not turned into 204), an error as `{errno, errMsg, data: null}` with the error's status,
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option.
+ * @param options The envelope options.
+ * @returns The responder, to give to the `respond` option of `expressHTTPEntrypoint`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, jsonEnvelope} from 'lakutata/adapter/express'
+ *
+ * class PingController extends Controller {
+ *     //GET /ping answers {"errno": null, "errMsg": null, "data": "pong"}
+ *     @GET('/ping')
+ *     public async ping(): Promise<string> {
+ *         return 'pong'
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [PingController],
+ *             //The errors of the actions answered with 200 too (as the applications of lakutata 2.x), the routes not
+ *             //found and the errors of the express middlewares with their status (404, 401…)
+ *             http: expressHTTPEntrypoint({port: 8080, respond: jsonEnvelope({actionErrorStatus: 200})})
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export declare function jsonEnvelope(options?: JSONEnvelopeOptions): ExpressResponder;

package/dist/cjs/adapter/express/Responders.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSONResponder = exports.statusOfError = exports.describeError = void 0;
+exports.jsonEnvelope = jsonEnvelope;
+const HTTPErrors_js_1 = require("../../lib/HTTPErrors.js");
+Object.defineProperty(exports, "describeError", { enumerable: true, get: function () { return HTTPErrors_js_1.describeError; } });
+Object.defineProperty(exports, "statusOfError", { enumerable: true, get: function () { return HTTPErrors_js_1.statusOfError; } });
+/**
+ * The default responder of {@link expressHTTPEntrypoint}: a result is sent as JSON, no result as an empty 204 (or the
+ * status set by a `StatusResult`); an error is sent as `{errno, errMsg}` (see `describeError`) with its HTTP status
+ * (see `statusOfError`: the first 4xx status in its cause chain, its own status, or 500).
+ */
+exports.JSONResponder = {
+    success: (response, data) => {
+        if (data === undefined) {
+            response.status(response.statusCode === 200 ? 204 : response.statusCode).end();
+            return;
+        }
+        response.json(data);
+    },
+    error: (response, error) => {
+        response.status((0, HTTPErrors_js_1.statusOfError)(error)).json((0, HTTPErrors_js_1.describeError)(error));
+    }
+};
+/**
+ * Create a responder for {@link expressHTTPEntrypoint} that wraps every response in the envelope
+ * `{errno, errMsg, data}`: a result as `{errno: null, errMsg: null, data}` (`data` is `null` when the action returned
+ * nothing, and its status is not turned into 204), an error as `{errno, errMsg, data: null}` with the error's status,
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option.
+ * @param options The envelope options.
+ * @returns The responder, to give to the `respond` option of `expressHTTPEntrypoint`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, jsonEnvelope} from 'lakutata/adapter/express'
+ *
+ * class PingController extends Controller {
+ *     //GET /ping answers {"errno": null, "errMsg": null, "data": "pong"}
+ *     @GET('/ping')
+ *     public async ping(): Promise<string> {
+ *         return 'pong'
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [PingController],
+ *             //The errors of the actions answered with 200 too (as the applications of lakutata 2.x), the routes not
+ *             //found and the errors of the express middlewares with their status (404, 401…)
+ *             http: expressHTTPEntrypoint({port: 8080, respond: jsonEnvelope({actionErrorStatus: 200})})
+ *         })
+ *     }
+ * })
+ * ```
+ */
+function jsonEnvelope(options = {}) {
+    return {
+        success: (response, data) => {
+            response.json({ errno: null, errMsg: null, data: data === undefined ? null : data });
+        },
+        error: (response, error, _request, origin) => {
+            const status = origin === 'action' ? options.actionErrorStatus ?? options.errorStatus : options.errorStatus;
+            response.status(status ?? (0, HTTPErrors_js_1.statusOfError)(error)).json({ ...(0, HTTPErrors_js_1.describeError)(error), data: null });
+        }
+    };
+}

package/dist/cjs/adapter/express/StaticUI.d.ts

@@ -0,0 +1,83 @@
+import { type RequestHandler } from 'express';
+/**
+ * The options of {@link staticUI}.
+ */
+export type StaticUIOptions = {
+    /**
+     * Serve a single-page application: a GET or HEAD request accepting HTML, whose path has no file extension and
+     * matches no file, is answered with the index (the client-side router handles the path). With `false`, such a
+     * request is passed on (a 404 behind `expressHTTPEntrypoint`).
+     * @default true
+     */
+    spa?: boolean;
+    /**
+     * The index file of the application, relative to the directory.
+     * @default 'index.html'
+     */
+    index?: string;
+    /**
+     * How long the browsers may cache the files with a content hash in their name (the assets of a Vite build:
+     * `index-B2x9fQ1a.js`): a number of seconds, or a duration (`'30d'`, `'12h'`; a string of digits is seconds). A file
+     * counts as hashed when it is a script, a style, a font or an image whose name ends with a dot or a dash followed by
+     * at least 8 letters, digits, `_` or `-`, among them a digit or an uppercase letter, before its extension
+     * (`index-B2x9fQ1a.js`, `main.3f2a1b9c.css`, not `my-component.js`). The other files and the index are sent with
+     * `Cache-Control: no-cache`.
+     * @default 31536000 (one year)
+     */
+    assetsMaxAge?: string | number;
+};
+/**
+ * Whether a file of a built UI has a content hash in its name: a script, a style, a font or an image whose name ends
+ * with a dot or a dash followed by at least 8 letters, digits, `_` or `-`, among them a digit or an uppercase letter
+ * @param file
+ * @internal
+ */
+export declare function isHashedAsset(file: string): boolean;
+/**
+ * The seconds the hashed assets are cached: a number of seconds, or a duration
+ * @param value
+ * @internal
+ */
+export declare function assetsMaxAge(value: string | number | undefined): number;
+/**
+ * Create an express handler serving a built web UI (the `dist` directory of a Vite application): its files, and its
+ * index for the paths of its client-side routes. Given as the `fallback` of {@link expressHTTPEntrypoint}, it never
+ * receives the paths of the actions. It needs the optional peer dependency `express`.
+ *
+ * The files with a content hash in their name are cached for a long time (`assetsMaxAge`), the other files and the
+ * index are revalidated on each request. A request matching no file that is not a page request (an asset, a non-GET
+ * request, a client not accepting HTML) is passed on to the next handler.
+ * @param directory The directory of the built UI, resolved from the current working directory.
+ * @param options How the index is served and the assets cached.
+ * @returns The express request handler.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, staticUI} from 'lakutata/adapter/express'
+ *
+ * class DeviceController extends Controller {
+ *     //GET /api/devices answers the action; GET /settings answers the index of the UI
+ *     @GET('/api/devices')
+ *     public async list(): Promise<string[]> {
+ *         return ['sensor-1']
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'console.app',
+ *     name: 'Console',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [DeviceController],
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 fallback: staticUI('./ui/dist', {assetsMaxAge: 86400})
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export declare function staticUI(directory: string, options?: StaticUIOptions): RequestHandler;

package/dist/cjs/adapter/express/StaticUI.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHashedAsset = isHashedAsset;
+exports.assetsMaxAge = assetsMaxAge;
+exports.staticUI = staticUI;
+const express_1 = __importDefault(require("express"));
+const node_path_1 = __importDefault(require("node:path"));
+const Cron_js_1 = require("../../lib/schedule/Cron.js");
+/**
+ * Whether a file of a built UI has a content hash in its name: a script, a style, a font or an image whose name ends
+ * with a dot or a dash followed by at least 8 letters, digits, `_` or `-`, among them a digit or an uppercase letter
+ * @param file
+ * @internal
+ */
+function isHashedAsset(file) {
+    const matched = /[.-]([0-9A-Za-z_-]{8,})\.(?:js|mjs|css|woff2?|png|jpe?g|svg|gif|webp|avif)$/.exec(file);
+    return !!matched && /[0-9A-Z]/.test(matched[1]);
+}
+/**
+ * The seconds the hashed assets are cached: a number of seconds, or a duration
+ * @param value
+ * @internal
+ */
+function assetsMaxAge(value) {
+    if (value === undefined)
+        return 31536000;
+    const seconds = typeof value === 'number' || /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : (0, Cron_js_1.parseDuration)(value) / 1000;
+    if (!Number.isFinite(seconds) || seconds < 0)
+        throw new RangeError(`Invalid assetsMaxAge "${value}": a number of seconds or a duration ("30d")`);
+    return Math.floor(seconds);
+}
+/**
+ * Create an express handler serving a built web UI (the `dist` directory of a Vite application): its files, and its
+ * index for the paths of its client-side routes. Given as the `fallback` of {@link expressHTTPEntrypoint}, it never
+ * receives the paths of the actions. It needs the optional peer dependency `express`.
+ *
+ * The files with a content hash in their name are cached for a long time (`assetsMaxAge`), the other files and the
+ * index are revalidated on each request. A request matching no file that is not a page request (an asset, a non-GET
+ * request, a client not accepting HTML) is passed on to the next handler.
+ * @param directory The directory of the built UI, resolved from the current working directory.
+ * @param options How the index is served and the assets cached.
+ * @returns The express request handler.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ * import {expressHTTPEntrypoint, staticUI} from 'lakutata/adapter/express'
+ *
+ * class DeviceController extends Controller {
+ *     //GET /api/devices answers the action; GET /settings answers the index of the UI
+ *     @GET('/api/devices')
+ *     public async list(): Promise<string[]> {
+ *         return ['sensor-1']
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'console.app',
+ *     name: 'Console',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [DeviceController],
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 fallback: staticUI('./ui/dist', {assetsMaxAge: 86400})
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+function staticUI(directory, options = {}) {
+    const root = node_path_1.default.resolve(directory);
+    const index = options.index ?? 'index.html';
+    const maxAge = assetsMaxAge(options.assetsMaxAge);
+    const files = express_1.default.static(root, {
+        index: false,
+        setHeaders: (response, file) => {
+            if (isHashedAsset(file))
+                response.setHeader('Cache-Control', `public, max-age=${maxAge}, immutable`);
+            else
+                response.setHeader('Cache-Control', 'no-cache');
+        }
+    });
+    return (request, response, next) => {
+        files(request, response, (error) => {
+            if (error)
+                return next(error);
+            //The routes of the application are its index; the missing files are not
+            const wantsPage = (request.method === 'GET' || request.method === 'HEAD') && !node_path_1.default.extname(request.path) && request.accepts('html') === 'html';
+            if (options.spa === false || !wantsPage)
+                return next();
+            response.setHeader('Cache-Control', 'no-cache');
+            response.sendFile(node_path_1.default.join(root, index), (sendError) => {
+                if (sendError)
+                    next(sendError);
+            });
+        });
+    };
+}