expediate 0.0.2 → 1.0.0

package/dist/router.js

@@ -0,0 +1,502 @@
+/* Copyright 2021 Fabien Bavent
+ *
+ * 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.
+ */
+'use strict';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+// ---------------------------------------------------------------------------
+// Pattern compilation
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether a path string contains glob characters (`*` or `?`).
+ *
+ * A pattern is considered a glob when it contains at least one unescaped
+ * `*` or `?` character, following the same convention as `.gitignore`.
+ *
+ * @param pattern - The path string to inspect.
+ * @returns `true` if the pattern should be treated as a glob.
+ */
+function isGlobPattern(pattern) {
+    return /(?<!\\)[*?]/.test(pattern);
+}
+/**
+ * Compile a `.gitignore`-style glob string into a prefix-anchored `RegExp`.
+ *
+ * Supported wildcard syntax:
+ * - `?`  — matches exactly one character that is not `/`.
+ * - `*`  — matches zero or more characters that are not `/`.
+ * - `**` — matches zero or more path segments (any characters including `/`).
+ *
+ * The returned expression is anchored at the start (`^`) so it always matches
+ * a prefix of the current path; the matched portion is stripped by
+ * `matchRouteLayer` when `layer.stripPath` is `true`.
+ *
+ * @param glob - The glob pattern to compile.
+ * @returns A prefix-anchored `RegExp`.
+ *
+ * @example
+ * ```ts
+ * compileGlob('/**\/*.php').test('/admin/index.php'); // true
+ * compileGlob('/api/*')    .test('/api/users');       // true
+ * compileGlob('/api/*')    .test('/api/users/123');   // false
+ * ```
+ */
+function compileGlob(glob) {
+    // Escape all regex special characters, leaving our wildcard characters intact.
+    let src = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    // Replace in order: `**` must be handled before `*`.
+    src = src
+        .replace(/\*\*/g, '\x00GLOBSTAR\x00') // temporary placeholder
+        .replace(/\*/g, '[^/]*') // single-segment wildcard
+        .replace(/\?/g, '[^/]') // single-character wildcard
+        .replace(/\x00GLOBSTAR\x00/g, '.*'); // cross-segment wildcard
+    return new RegExp('^' + src);
+}
+/**
+ * Compile a plain path string with optional `:name` parameter segments into a
+ * prefix-anchored `RegExp` that uses named capture groups.
+ *
+ * Each `:name` segment is converted to `(?<name>[^/]+)`, making named
+ * captures available directly on the `RegExp` match result.
+ * Literal segments are escaped and matched exactly.
+ *
+ * The expression matches up to a segment boundary (`/` or end-of-string) so
+ * that `/users` never inadvertently matches `/users-admin`.
+ *
+ * @param path - A plain path string such as `'/users/:id/posts'`.
+ * @returns A prefix-anchored `RegExp` with named groups for each parameter.
+ *
+ * @example
+ * ```ts
+ * const re = compilePlainPath('/users/:id');
+ * re.exec('/users/42/comments')?.groups; // { id: '42' }
+ * ```
+ */
+function compilePlainPath(path) {
+    const segments = path.split('/').filter((s) => s.length > 0);
+    const src = segments
+        .map((seg) => seg.startsWith(':')
+        ? `(?<${seg.slice(1)}>[^/]+)` // named parameter segment
+        : seg.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+        .join('/');
+    // Allow a trailing slash or an additional path segment after the prefix.
+    return new RegExp('^/?' + src + '(?=/|$)');
+}
+/**
+ * Convert any supported path pattern into the single canonical `RegExp`
+ * used by `matchRouteLayer`.
+ *
+ * | Input type   | Strategy                                              |
+ * |--------------|-------------------------------------------------------|
+ * | Glob string  | {@link compileGlob} — `.gitignore`-style wildcards    |
+ * | Plain string | {@link compilePlainPath} — `:name` → named groups     |
+ * | `RegExp`     | Used as-is; named groups are surfaced as params       |
+ *
+ * @param path - The raw path pattern supplied by the caller.
+ * @returns A `RegExp` suitable for use in `matchRouteLayer`.
+ */
+function compilePattern(path) {
+    if (path instanceof RegExp)
+        return path;
+    if (isGlobPattern(path))
+        return compileGlob(path);
+    return compilePlainPath(path);
+}
+// ---------------------------------------------------------------------------
+// Layer construction
+// ---------------------------------------------------------------------------
+/**
+ * Build a `Layer` that represents a single registered route entry.
+ *
+ * The `path` argument may be a plain string with `:name` parameters, a glob
+ * string, or a `RegExp`. In all three cases the pattern is pre-compiled into
+ * a single `RegExp` stored as `layer.regex`.
+ *
+ * @param method     - HTTP method to restrict this layer to (uppercased), or
+ *                     `null` to match any method.
+ * @param path       - URL path pattern (plain string, glob, or `RegExp`).
+ * @param middleware - The middleware function to invoke on a match.
+ * @param stripPath  - When `true`, the matched prefix is stripped from
+ *                     `req.path` before the middleware runs. Pass `true` for
+ *                     prefix/`use` registrations and `false` for exact-method
+ *                     routes so that chained middlewares sharing the same path
+ *                     can each match in turn.
+ * @returns A fully initialised `Layer` ready to be pushed into the route table.
+ * @throws {TypeError} When `middleware` is not a callable function.
+ */
+function buildRouteLayer(method, path, middleware, stripPath) {
+    if (typeof middleware !== 'function')
+        throw new TypeError('Incorrect middleware type: expected a function');
+    return { method, path, regex: compilePattern(path), stripPath, middleware };
+}
+// ---------------------------------------------------------------------------
+// Layer matching
+// ---------------------------------------------------------------------------
+/**
+ * Test whether an incoming request matches the given layer and, on success,
+ * mutate `req` to reflect the match.
+ *
+ * All pattern types (plain string, glob, `RegExp`) are handled identically
+ * through `layer.regex`. Named capture groups in the match result are merged
+ * into `req.params` and `req.queries.route`.
+ *
+ * Path stripping is conditional on `layer.stripPath`:
+ * - `true`  (prefix routes) — the matched prefix is removed from `req.path`
+ *   so nested routers only see the remaining suffix.
+ * - `false` (exact-method routes) — `req.path` is left unchanged so that
+ *   subsequent chained middlewares sharing the same pattern can still match.
+ *
+ * @param layer - The layer to test.
+ * @param req   - The incoming request (mutated in-place on a successful match).
+ * @param path  - The current value of `req.path` to test against.
+ * @returns `true` if the layer matches and `req` has been updated;
+ *          `false` otherwise.
+ */
+function matchRouteLayer(layer, req, path) {
+    if (layer.method && layer.method !== req.method)
+        return false;
+    const m = layer.regex.exec(path);
+    if (m === null)
+        return false;
+    const captured = m.groups ?? {};
+    // Only rewrite req.path for prefix-style (use) registrations.
+    // Exact-method routes leave req.path intact so chained middlewares
+    // sharing the same path each see the full, unmodified path.
+    if (layer.stripPath) {
+        req.path = path.slice(m[0].length) || '/';
+    }
+    req.queries.route = captured;
+    Object.assign(req.params, captured);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// HTTP object augmentation
+// ---------------------------------------------------------------------------
+/**
+ * Augment a raw `http.IncomingMessage` / `http.ServerResponse` pair with the
+ * additional fields and helpers expected by router middleware.
+ *
+ * This function is idempotent — it exits immediately when `req.queries` is
+ * already defined, so it is safe to call multiple times on the same pair.
+ *
+ * **Fields added to `req`:**
+ * - `originalUrl` — the unmodified URL string.
+ * - `path`        — the pathname portion of the URL.
+ * - `params`      — merged map initialised from URL query parameters.
+ * - `queries`     — structured query buckets (`url`, `route`).
+ * - `cookies`     — parsed `Cookie` header values.
+ *
+ * **Helpers added to `res`:**
+ * - `send(data?)`             — write `data` and end the response.
+ * - `status(code, headers?)`  — set the status code and optional headers.
+ * - `redirect(url)`           — issue a 302 redirect.
+ * - `cookie(name, val, opts)` — append a `Set-Cookie` header.
+ *
+ * @param req - The raw incoming message to augment.
+ * @param res - The raw server response to augment.
+ */
+function updateHttpObjects(req, res) {
+    const rReq = req;
+    const rRes = res;
+    if (rReq.queries)
+        return; // Already augmented.
+    rReq.queries = {};
+    const qry = new URL(`http://${req.headers.host}${req.url}`);
+    rReq.originalUrl = req.url;
+    rReq.path = qry.pathname;
+    // Parse URL query parameters.
+    const urlParams = {};
+    for (const [key, value] of qry.searchParams.entries())
+        urlParams[key] = value;
+    rReq.queries.url = urlParams;
+    rReq.params = { ...urlParams };
+    // Parse cookies.
+    if (rReq.cookies == null) {
+        rReq.cookies = {};
+        if (req.headers.cookie) {
+            for (const raw of req.headers.cookie.split(';')) {
+                const eqIdx = raw.indexOf('=');
+                if (eqIdx === -1)
+                    continue;
+                rReq.cookies[raw.slice(0, eqIdx).trim()] = raw.slice(eqIdx + 1).trim();
+                // TODO: 's:' prefix → signed cookie, 'j:' prefix → JSON cookie
+            }
+        }
+    }
+    rRes.setHeader('X-Powered-By', 'Expediate');
+    rRes.send = (data) => {
+        if (data)
+            res.write(data);
+        res.end();
+    };
+    rRes.status = (code, headers) => {
+        res.statusCode = code;
+        if (headers)
+            for (const [k, v] of Object.entries(headers))
+                res.setHeader(k, v);
+        return rRes;
+    };
+    rRes.redirect = (url) => {
+        res.setHeader('location', url);
+        res.writeHead(302);
+        res.write(`Found. Redirecting to ${url}`);
+        res.end();
+    };
+    rRes.cookie = (name, value, options) => {
+        const opts = options ?? {};
+        if (opts.signed && !req.secret)
+            throw new Error('cookieParser("secret") required for signed cookies');
+        let val = typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value);
+        if (opts.signed)
+            val = 's:' + val; // sign() integration point
+        let txt = `${name}=${val}`;
+        if (opts.maxAge != null) {
+            opts.expires = new Date(Date.now() + opts.maxAge);
+            opts.maxAge = Math.floor(opts.maxAge / 1000);
+            txt += `; Max-Age=${opts.maxAge}`;
+        }
+        if (opts.expires)
+            txt += `; Expires=${opts.expires.toUTCString()}`;
+        txt += `; Path=${opts.path ?? '/'}`;
+        res.setHeader('Set-Cookie', txt);
+        return rRes;
+    };
+}
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+/**
+ * Recursively resolve a `MiddlewareArg` value down to individual `Middleware`
+ * functions and push one `Layer` per function into the route table.
+ *
+ * Accepted input shapes (processed recursively):
+ * - A `Middleware` function → pushed directly as a layer.
+ * - A `Router` instance    → its `listener` is unwrapped and pushed.
+ * - An array of either     → each element is processed recursively.
+ *
+ * @param routes    - The mutable route table to push into.
+ * @param method    - HTTP method string or `null` for method-agnostic layers.
+ * @param path      - URL pattern (plain string, glob, or `RegExp`).
+ * @param arg       - The middleware value(s) to register.
+ * @param stripPath - Forwarded to `buildRouteLayer`. Pass `true` for prefix-
+ *                    style registrations (`use`) so the matched prefix
+ *                    is stripped from `req.path`, and `false` for exact-method
+ *                    routes so that chained middlewares sharing the same path
+ *                    each see the unmodified path.
+ * @throws {TypeError} When `arg` contains a value that cannot be resolved to
+ *                     a `Middleware` function.
+ */
+function registerRoute(routes, method, path, arg, stripPath) {
+    if (Array.isArray(arg)) {
+        for (const item of arg)
+            registerRoute(routes, method, path, item, stripPath);
+    }
+    else if (typeof arg === 'function') {
+        routes.push(buildRouteLayer(method, path, arg, stripPath));
+    }
+    else if (arg && typeof arg.listener === 'function') {
+        // Router instance — unwrap its listener.
+        routes.push(buildRouteLayer(method, path, arg.listener, stripPath));
+    }
+    else {
+        throw new TypeError('Unexpected value registered as middleware: expected a Middleware ' +
+            'function, a Router instance, or an array of either');
+    }
+}
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create and return a new `Router` instance.
+ *
+ * The returned object exposes an Express-compatible routing API and doubles
+ * as a middleware function itself (via `router.listener`), so it can be
+ * mounted inside another router:
+ * ```ts
+ * parent.use('/api', child);
+ * ```
+ *
+ * **Path patterns** accepted by all route-registration methods:
+ * - Plain strings with optional `:name` segments — e.g. `'/users/:id'`.
+ *   Each `:name` is compiled to a named capture group and exposed in
+ *   `req.params` on a match.
+ * - Glob strings following `.gitignore` rules — e.g. `'/**\/*.php'`.
+ *   Supported wildcards: `?` (one non-slash char), `*` (any non-slash chars),
+ *   `**` (any chars, including slashes).
+ * - `RegExp` objects — used directly; named groups become route parameters.
+ *
+ * **Middleware arguments** accept any number of variadic `MiddlewareArg`
+ * values, each of which may be:
+ * - A `Middleware` function.
+ * - A `Router` instance (its `listener` is registered automatically).
+ * - An array of either of the above.
+ *
+ * **Path stripping behaviour:**
+ * - `use` — strip the matched path prefix from `req.path` before
+ *   invoking middleware. Nested routers therefore only see the remaining suffix.
+ * - `all` / `get` / `post` / `put` / `delete` / `patch` — leave `req.path` intact
+ *   so that multiple middlewares registered for the same exact path can each
+ *   match and be invoked in sequence via `next()`.
+ *
+ * @returns A fully initialised `Router` ready to register routes and
+ *          optionally start an HTTP or HTTPS server.
+ *
+ * @example
+ * ```ts
+ * const auth = createRouter();
+ * auth.post('/login',  handleLogin);
+ * auth.post('/logout', handleLogout);
+ *
+ * const app = createRouter();
+ * app.use('/auth', auth);                              // mount a sub-router
+ * app.get('/users/:id', requireAuth, getUser);         // multiple middleware
+ * app.get('/**\/*.php', (req, res) =>                 // glob pattern
+ *   res.status(403).send('Forbidden'));
+ *
+ * app.listen(3000, () => console.log('Listening on :3000'));
+ * ```
+ */
+function createRouter() {
+    const routes = [];
+    /**
+     * Core dispatch function. Walks the route table in registration order and
+     * invokes the first layer that matches the current request. Falls back to a
+     * 404 response when no layer matches and no upstream `done` callback is set.
+     */
+    const listener = (req, res, done) => {
+        const method = req.method;
+        const url = req.url;
+        let idx = 0;
+        updateHttpObjects(req, res);
+        const next = () => {
+            while (idx < routes.length) {
+                const layer = routes[idx++];
+                const pathBefore = req.path;
+                if (matchRouteLayer(layer, req, req.path)) {
+                    if (layer.stripPath) {
+                        // For prefix layers (use), save the pre-strip path so we can
+                        // restore it if the sub-router calls done() and control returns here.
+                        // Without restoration, subsequent layers in this router would see
+                        // the truncated path and fail to match their own patterns.
+                        const strippedPath = req.path;
+                        return layer.middleware(req, res, () => {
+                            req.path = pathBefore; // restore for the next sibling layer
+                            next();
+                        });
+                    }
+                    return layer.middleware(req, res, next);
+                }
+            }
+            if (done)
+                return done();
+            res.status(404).end(`Cannot ${method} ${url}`);
+        };
+        try {
+            next();
+        }
+        catch (e) {
+            console.warn(e);
+            res.status(500).end(`Error ${method} ${url}`);
+        }
+    };
+    // -------------------------------------------------------------------------
+    // Internal helper — produce the uniform registration function for a method.
+    // -------------------------------------------------------------------------
+    /**
+     * Return the route-registration function used by all HTTP-method helpers.
+     *
+     * The produced function accepts a mandatory `path` followed by any number
+     * of `MiddlewareArg` values (functions, `Router` instances, or arrays
+     * thereof), and delegates each to `registerRoute`.
+     *
+     * @param method    - HTTP method to restrict layers to, or `null` for any.
+     * @param stripPath - Whether the matched path prefix should be stripped from
+     *                    `req.path` before middleware is invoked. `true` for
+     *                    prefix-style registrations, `false` for exact-method ones.
+     * @returns A variadic route-registration function.
+     */
+    function makeRegister(method, stripPath) {
+        return (path, ...args) => {
+            for (const arg of args)
+                registerRoute(routes, method, path, arg, stripPath);
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Public router API
+    // -------------------------------------------------------------------------
+    const router = {
+        listener,
+        use: makeRegister(null, true), // prefix — strip path
+        all: makeRegister(null, false), // exact  — keep path
+        get: makeRegister('GET', false),
+        put: makeRegister('PUT', false),
+        post: makeRegister('POST', false),
+        delete: makeRegister('DELETE', false),
+        patch: makeRegister('PATCH', false),
+        listen(port, opts, cb) {
+            if (typeof opts === 'function') {
+                cb = opts;
+                opts = undefined;
+            }
+            const rawListener = listener;
+            if (opts && opts.key && opts.cert)
+                https.createServer(opts, rawListener).listen(port, cb);
+            else
+                http.createServer(rawListener).listen(port, cb);
+        },
+    };
+    return router;
+}
+exports.default = createRouter;
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

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

package/dist/static.d.ts

@@ -0,0 +1,164 @@
+import type { RouterRequest, RouterResponse, Middleware } from './router';
+export type Mime = {
+    lookup: (path: string, fallback: string | null) => string;
+    charsets: (mimeType: string) => string | null;
+};
+export declare const mime: Mime;
+/** HTTP header map used both in options and as argument to res.status(). */
+type HeaderMap = Record<string, string>;
+/**
+ * Options accepted by {@link serveStatic}, {@link serveFile}, and
+ * {@link sendFile}.
+ */
+export interface StaticOptions {
+    /**
+     * Extra HTTP headers added to every response (merged with the built-in
+     * security headers `Content-Security-Policy` and `X-Content-Type-Options`).
+     */
+    headers?: HeaderMap;
+    /**
+     * When `true`, unhandled requests (wrong method, missing file) are passed
+     * to the next middleware via `next()` instead of sending an error response.
+     * Defaults to `false`.
+     */
+    fallthrough?: boolean;
+    /**
+     * Browser cache lifetime for served files, in **milliseconds**.
+     * Translated to a `Cache-Control: public, max-age=<seconds>` header.
+     * Defaults to `0` (no caching).
+     */
+    maxage?: number;
+    /** Alias for {@link maxage}. */
+    maxAge?: number;
+    /**
+     * When `true`, appends `, immutable` to the `Cache-Control` header,
+     * signalling that the response will never change during its `max-age`
+     * window. Only meaningful when {@link maxage} is non-zero.
+     */
+    immutable?: boolean;
+    /**
+     * When `true` (default), the server generates and sends a weak `ETag`
+     * header based on the file's size and last-modification time.
+     */
+    etag?: boolean;
+    /**
+     * When `true` (default), the server sends a `Last-Modified` header
+     * derived from the file's `mtime`.
+     */
+    lastModified?: boolean;
+    /**
+     * Override the auto-detected `Content-Type`.  When set, MIME detection via
+     * the `mime` package is skipped entirely.
+     */
+    contentType?: string | null;
+    /**
+     * Controls how dot-files (files or directories whose name starts with `.`)
+     * are handled:
+     * - `'allow'`  — serve them like any other file.
+     * - `'deny'`   — respond with 403 Forbidden.
+     * - `'hide'`   — respond with 404 Not Found (default).
+     */
+    dotfiles?: 'allow' | 'deny' | 'hide';
+    /**
+     * When `true` (default), a request for a directory path is transparently
+     * redirected to `index.html` inside that directory.
+     * When `false`, directory requests receive a 404 response.
+     */
+    redirect?: boolean;
+    /**
+     * When `true`, a request for a directory path that has no `index.html`
+     * renders an Apache-style directory listing.
+     * Defaults to `false`.
+     */
+    indexOf?: boolean;
+}
+/**
+ * Fully resolved options used internally after merging caller-supplied values
+ * with {@link DEFAULT_OPTIONS}. All optional fields from {@link StaticOptions}
+ * are guaranteed to be present.
+ */
+interface ResolvedOptions extends Required<Omit<StaticOptions, 'maxAge'>> {
+    /** Absolute, normalised path to the root directory or file. */
+    root: string;
+}
+/**
+ * Send a single file from the filesystem as an HTTP response.
+ *
+ * Unlike the {@link serveStatic} middleware, this function resolves the
+ * response for a **specific** `pathname` that has already been determined by
+ * the caller. It is useful for custom routing logic where the file path is
+ * computed dynamically.
+ *
+ * Behaviour:
+ * - When `pathname` refers to a **regular file**, it is served via
+ *   {@link sendIt} (including ETag, Last-Modified, conditional GET, and
+ *   MIME-type detection).
+ * - When `pathname` refers to a **directory** and `opts.indexOf` is `true`,
+ *   an Apache-style directory listing is rendered.
+ * - Otherwise, a 404 Not Found response is sent.
+ *
+ * @param req      - The incoming router request.
+ * @param res      - The outgoing router response.
+ * @param pathname - Absolute filesystem path of the file to send.
+ * @param opts     - Fully resolved static-serving options.
+ */
+export declare function sendFile(req: RouterRequest, res: RouterResponse, pathname: string, opts: ResolvedOptions): void;
+/**
+ * Middleware factory that serves files from a directory on the filesystem.
+ *
+ * Mount this middleware with a path prefix to expose a public directory:
+ * ```ts
+ * app.use('/public', serveStatic('./dist'));
+ * ```
+ *
+ * Features:
+ * - **Method filtering** — only `GET` and `HEAD` are served; other methods
+ *   receive 405 Method Not Allowed (or are forwarded to `next()` when
+ *   `fallthrough` is `true`).
+ * - **Directory traversal protection** — any path containing `..` is
+ *   rejected with 403 Forbidden.
+ * - **Dot-file handling** — configurable via the `dotfiles` option
+ *   (`'allow'`, `'deny'`, or `'hide'`).
+ * - **Directory redirect** — a path resolving to a directory is automatically
+ *   redirected to its `index.html` when `redirect` is `true`.
+ * - **Conditional GET** — ETag and Last-Modified headers enable browser and
+ *   proxy caching with proper revalidation.
+ * - **Cache-Control** — configurable via `maxage` / `immutable` options.
+ * - **MIME-type detection** — via the `mime` npm package.
+ *
+ * @param root    - Path to the directory containing the files to serve.
+ *                  Resolved to an absolute path internally.
+ * @param options - Optional configuration (see {@link StaticOptions}).
+ * @returns An Express-compatible middleware function.
+ * @throws {TypeError} When `root` is missing or not a string.
+ */
+export declare function serveStatic(root: string, options?: StaticOptions): Middleware;
+/**
+ * Middleware factory that serves a **single, fixed file** as the response to
+ * every request, regardless of the request path.
+ *
+ * Use this when you want every route to return the same file — for example,
+ * serving a compiled single-page application's `index.html` as a catch-all:
+ * ```ts
+ * app.get('/**', serveFile('./dist/index.html'));
+ * ```
+ *
+ * Features:
+ * - **Method filtering** — only `GET` and `HEAD` are served.
+ * - **Conditional GET** — ETag and Last-Modified are generated from the file
+ *   metadata on every request.
+ * - **MIME-type detection** — via the `mime` npm package.
+ *
+ * @param filePath - Path to the file to serve. Resolved to an absolute path.
+ * @param options  - Optional configuration (see {@link StaticOptions}).
+ * @returns An Express-compatible middleware function.
+ * @throws {TypeError} When `filePath` is missing or not a string.
+ */
+export declare function serveFile(filePath: string, options?: StaticOptions): Middleware;
+declare const _default: {
+    serveStatic: typeof serveStatic;
+    serveFile: typeof serveFile;
+    sendFile: typeof sendFile;
+};
+export default _default;
+//# sourceMappingURL=static.d.ts.map