tina4-nodejs 3.13.92 → 3.13.95

package/types/core/src/queueBackends/mongoBackend.d.ts

@@ -0,0 +1,119 @@
+import type { QueueJob } from "../queue.js";
+export interface MongoConfig {
+    host?: string;
+    port?: number;
+    uri?: string;
+    username?: string;
+    password?: string;
+    database?: string;
+    collection?: string;
+    /**
+     * Reservation/visibility timeout (seconds). A dequeued message is held
+     * reserved with availableAt = now + timeout; reclaim returns it once that
+     * passes (consumer died mid-flight, before complete()/fail()). <= 0 disables
+     * the reclaim. Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300.
+     */
+    visibilityTimeout?: number;
+    /** Max attempts before the reclaim dead-letters a job instead of re-delivering. */
+    maxRetries?: number;
+}
+export interface QueueBackend {
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+    /** Release whatever connection the backend holds. Must be idempotent. */
+    close(): void;
+}
+/**
+ * MongoDB queue backend using the `mongodb` npm package.
+ *
+ * Uses synchronous-style communication by spawning a child process
+ * for each operation, similar to the RabbitMQ and Redis patterns.
+ * This keeps the interface synchronous as required by the Queue class.
+ */
+export declare class MongoBackend implements QueueBackend {
+    private host;
+    private port;
+    private uri;
+    private username;
+    private password;
+    private database;
+    private collection;
+    private visibilityTimeout;
+    private maxRetries;
+    constructor(config?: MongoConfig);
+    /**
+     * Resolved connection config — exposed for testing/introspection.
+     */
+    getConfig(): {
+        uri: string;
+        database: string;
+        collection: string;
+        visibilityTimeout: number;
+    };
+    /**
+     * Resolved reservation/visibility timeout (seconds). <= 0 disables the
+     * reclaim. Exposed for testing/introspection.
+     */
+    getVisibilityTimeout(): number;
+    /**
+     * Build the Node script that performs one MongoDB queue operation in a child
+     * process. Exposed (not private) so tests can assert the visibility-timeout
+     * behaviour without a live MongoDB — the script's pop branch advances
+     * availableAt = now + visibilityTimeout and stamps reservedAt (the core fix),
+     * and the reclaim branch flips an expired { status: reserved } back to
+     * pending with attempts incremented (dead-lettering past maxRetries),
+     * disabled when visibilityTimeout <= 0.
+     */
+    buildScript(operation: string, queue: string, data?: string): string;
+    /**
+     * Execute a MongoDB operation synchronously via a child process.
+     */
+    private execSync;
+    popById(queue: string, id: string): QueueJob | null;
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+    /**
+     * Acknowledge a completed job — drop its reservation so the reclaim never
+     * re-delivers it. Without this a Mongo-popped job stayed reserved and was
+     * re-delivered after the visibility window (the redelivery bug).
+     */
+    complete(queue: string, id: string): void;
+    /**
+     * Record a failed attempt: requeue (reset availableAt, ++attempts) while
+     * retries remain, else dead-letter. Mirrors the file/lite backend.
+     */
+    fail(queue: string, id: string, error: string, maxRetries: number, retryBackoff?: number): void;
+    /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
+    retry(queue: string, id: string, delaySeconds?: number): void;
+    /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
+    deadLetters(queue: string, maxRetries?: number): QueueJob[];
+    /** Jobs that failed but are still eligible for retry (status=failed, attempts < max). */
+    failed(queue: string, maxRetries?: number): QueueJob[];
+    /** Revive dead-lettered jobs under the (possibly raised) limit. Returns count revived. */
+    retryFailed(queue: string, maxRetries?: number): number;
+    /** Remove jobs by status (default: every doc for the topic). Returns count removed. */
+    purge(queue: string, status?: string): number;
+    /**
+     * Release the MongoDB connection. Idempotent — a second call is a no-op.
+     *
+     * HONEST CAVEAT, and it is the whole reason ADR-0022 exists: THIS backend
+     * holds no connection between calls to release. Every operation runs in its
+     * own child process (see execSync/buildScript), and that child's `finally`
+     * already does `await client.close()` before it exits — so the pool it opened
+     * is gone by the time the method returns. Unlike tina4-python, tina4-php and
+     * tina4-ruby, whose Mongo/broker backends hold a long-lived client that this
+     * method genuinely hands back, Node has nothing to give back.
+     *
+     * It is implemented anyway, and required by the QueueBackend interface,
+     * because the CONTRACT is what matters: `Queue.close()` must be callable on
+     * every backend in every framework, and the day the persistent-connection
+     * rewrite lands (ADR-0022's tracked fix) the client goes here with no change
+     * at any call site. A method that is a no-op today and correct forever beats
+     * a missing method the caller has to feature-detect.
+     */
+    close(): void;
+}

package/types/core/src/queueBackends/rabbitmqBackend.d.ts

@@ -0,0 +1,55 @@
+import type { QueueJob } from "../queue.js";
+export interface RabbitMQConfig {
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    vhost?: string;
+    /**
+     * Accepted for API parity with the file/MongoDB backends and IGNORED — the
+     * broker owns redelivery (unacked messages requeue on channel close), so the
+     * framework-level visibility timeout does not apply here.
+     */
+    visibilityTimeout?: number;
+}
+/**
+ * Parse an AMQP URL (amqp://[user:pass@]host[:port][/vhost]) into a partial
+ * RabbitMQConfig. Mirrors the Python/PHP/Ruby `parse_amqp_url` semantics:
+ * strips a leading amqp:// or amqps:// scheme, splits optional credentials,
+ * and reads the path segment as the URL-decoded vhost name. Only fields
+ * present in the URL are populated.
+ */
+export declare function parseAmqpUrl(url: string): RabbitMQConfig;
+export interface QueueBackend {
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+}
+/**
+ * RabbitMQ queue backend using raw AMQP 0-9-1 protocol.
+ *
+ * Uses synchronous-style communication by spawning a child process
+ * for each operation, similar to the Redis session handler pattern.
+ * This keeps the interface synchronous as required by the Queue class.
+ */
+export declare class RabbitMQBackend implements QueueBackend {
+    private host;
+    private port;
+    private username;
+    private password;
+    private vhost;
+    constructor(config?: RabbitMQConfig);
+    /**
+     * Resolved connection config — exposed for testing/introspection.
+     */
+    getConfig(): Required<Omit<RabbitMQConfig, "visibilityTimeout">>;
+    /**
+     * Execute an AMQP operation synchronously via a child process.
+     */
+    private execSync;
+    push(queue: string, payload: unknown, _delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+}

package/types/core/src/rateLimiter.d.ts

@@ -0,0 +1,49 @@
+import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
+/** Configuration for the rate limiter */
+export interface RateLimiterConfig {
+    /** Maximum number of requests per window. Default: 100 (or TINA4_RATE_LIMIT env) */
+    limit?: number;
+    /** Window duration in seconds. Default: 60 (or TINA4_RATE_WINDOW env) */
+    windowSeconds?: number;
+    /** Cleanup interval in milliseconds. Default: 60000 (1 minute) */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Create a rate limiter middleware using a sliding window algorithm.
+ * Tracks requests per IP in an in-memory Map.
+ *
+ * Response headers:
+ *   X-RateLimit-Limit     — Maximum requests per window
+ *   X-RateLimit-Remaining — Requests remaining in the current window
+ *   X-RateLimit-Reset     — Unix timestamp (seconds) when the window resets
+ *   Retry-After           — Seconds to wait (only when rate limited)
+ *
+ * Returns 429 Too Many Requests when the limit is exceeded.
+ */
+export declare function rateLimiter(config?: RateLimiterConfig): Middleware;
+/** Rate limit check result */
+export interface RateLimitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    reset: number;
+    retryAfter?: number;
+}
+/**
+ * Class-based rate limiter with check/reset/apply methods.
+ * Matches the Python/PHP/Ruby API surface.
+ */
+export declare class RateLimiter {
+    readonly limit: number;
+    readonly window: number;
+    private store;
+    constructor(config?: RateLimiterConfig);
+    /** Check if a request from the given IP is allowed. */
+    check(ip: string): RateLimitResult;
+    /** Clear all tracked request data. */
+    reset(): void;
+    /** Apply rate limiting to a request/response pair. Sets headers and 429 if exceeded. */
+    apply(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response];
+    /** Middleware hook — enforces rate limiting before the route handler. */
+    beforeRateLimit(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response];
+}

package/types/core/src/request.d.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage, IncomingHttpHeaders } from "node:http";
+import type { Tina4Request, UploadedFile } from "./types.js";
+/**
+ * Wrap Node's `IncomingHttpHeaders` in a Proxy so mixed-case lookups
+ * (`req.headers["Content-Type"]`) work alongside the canonical lowercase
+ * form Node already provides. Parity with PY-10-03 (Python ships a
+ * `CaseInsensitiveDict` for the same reason).
+ *
+ * The raw object is returned as-is by `Object.keys` / iteration — only
+ * string property reads/`in` checks are normalised.
+ */
+export declare function makeCaseInsensitiveHeaders(raw: IncomingHttpHeaders): IncomingHttpHeaders;
+export declare function createRequest(req: IncomingMessage): Tina4Request;
+export declare class PayloadTooLargeError extends Error {
+    statusCode: number;
+    constructor(actual: number, limit: number);
+}
+/**
+ * Parse multipart/form-data body into fields and files.
+ * Zero-dependency implementation.
+ */
+export declare function parseMultipart(body: Buffer, boundary: string): {
+    fields: Record<string, string>;
+    files: Record<string, UploadedFile | UploadedFile[]>;
+};

package/types/core/src/response.d.ts

@@ -0,0 +1,28 @@
+import type { ServerResponse } from "node:http";
+import type { Tina4Response } from "./types.js";
+/**
+ * Set the default templates directory for render().
+ * Called by server.ts during startup.
+ */
+export declare function setDefaultTemplatesDir(dir: string): void;
+/**
+ * Return the global Frond engine, creating a default if needed.
+ */
+export declare function getFrond(): Promise<InstanceType<any>>;
+/**
+ * Return the singleton Frond engine for built-in framework templates.
+ * Syncs custom filters/globals from the user engine.
+ */
+export declare function getFrameworkFrond(): Promise<InstanceType<any> | null>;
+/**
+ * Register a pre-configured Frond engine for response.render().
+ */
+export declare function setFrond(engine: InstanceType<any>): void;
+export declare function createResponse(res: ServerResponse): Tina4Response;
+/**
+ * Build a standard error response envelope (standalone helper).
+ *
+ * Usage:
+ *   return response(errorResponse("VALIDATION_FAILED", "Email is required", 400), 400);
+ */
+export declare function errorResponse(code: string, message: string, status?: number): Record<string, unknown>;

package/types/core/src/routeDiscovery.d.ts

@@ -0,0 +1,12 @@
+import type { RouteDefinition } from "./types.js";
+export declare function discoverRoutes(routesDir: string): Promise<RouteDefinition[]>;
+/**
+ * Re-run the most recent route scan — called by POST /__dev/api/reload so a
+ * newly-added OR edited file in src/routes/ registers without a server restart.
+ * A file is re-imported when it's new or its mtime increased; unchanged files
+ * are skipped. The router replaces routes by pattern, so a re-imported route
+ * overwrites the stale handler. No-op if discoverRoutes() has never been called.
+ */
+export declare function rediscoverRoutes(): Promise<RouteDefinition[]>;
+/** Test-only: reset the seen-files state so tests can replay the same dir. */
+export declare function _resetRouteDiscovery(): void;

package/types/core/src/router.d.ts

@@ -0,0 +1,366 @@
+import type { RouteHandler, RouteDefinition, RouteMeta, Middleware, MiddlewareSpec, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
+/**
+ * Whether `TINA4_TRAILING_SLASH_REDIRECT` is enabled.
+ *
+ * Default: false. When true, a request to `/foo/` that has no exact match
+ * but matches `/foo` will be treated as a hit on `/foo` — callers can use
+ * the returned pattern to issue a 308 redirect (Python parity).
+ */
+export declare function isTrailingSlashRedirectEnabled(): boolean;
+interface MatchResult {
+    handler: RouteHandler;
+    params: Record<string, string | number>;
+    pattern: string;
+    meta?: RouteMeta;
+    middlewares?: MiddlewareSpec[];
+    template?: string;
+    secure?: boolean;
+    cached?: boolean;
+    noAuth?: boolean;
+}
+interface CompiledRoute {
+    pattern: string;
+    regex: RegExp;
+    paramNames: string[];
+    paramTypes: string[];
+    handler: RouteHandler;
+    meta?: RouteMeta;
+    filePath?: string;
+    middlewares?: MiddlewareSpec[];
+    secure?: boolean;
+    cached?: boolean;
+    noAuth?: boolean;
+    cacheStore?: Map<string, {
+        data: unknown;
+        expires: number;
+    }>;
+    cacheTtl?: number;
+    template?: string;
+}
+/**
+ * Thin reference to a registered WebSocket route, enabling chained modifiers
+ * — the WS analogue of {@link RouteRef}.
+ *
+ * Usage:
+ *   router.websocket("/ws/secure", handler).secure();
+ */
+export declare class WsRouteRef {
+    private route;
+    constructor(route: WebSocketRouteDefinition);
+    /** Mark this WS route as requiring a valid JWT on the upgrade handshake. */
+    secure(): this;
+}
+/**
+ * Thin reference to a registered route, enabling chained modifiers.
+ *
+ * Usage:
+ *   router.get("/api/data", handler).secure().cache();
+ */
+export declare class RouteRef {
+    private route;
+    constructor(route: CompiledRoute);
+    /** Mark this route as requiring bearer-token authentication. */
+    secure(): this;
+    /** Opt out of secure-by-default auth (for public write routes). */
+    noAuth(): this;
+    /** Mark this route's response as cacheable. */
+    cache(): this;
+    /**
+     * Append middleware to this route. Accepts middleware functions and/or
+     * string specs (e.g. `"ResponseCache:300"`), resolved when the route runs.
+     */
+    middleware(...middlewareClasses: MiddlewareSpec[]): this;
+}
+export interface RouteInfo {
+    method: string;
+    path: string;
+    handler: string;
+    middlewareCount: number;
+    cached: boolean;
+    secure: boolean;
+}
+export declare class Router {
+    private routes;
+    private wsRoutes;
+    /** Class-based middleware registered via `use()` / `Router.use()`. */
+    private static _classMiddlewares;
+    /**
+     * Register a class-based middleware (beforeX / afterX convention).
+     * Classes are stored globally and executed by MiddlewareRunner.
+     */
+    static use(middlewareClass: any): void;
+    /**
+     * Get all registered class-based middleware classes.
+     */
+    static getClassMiddlewares(): any[];
+    /**
+     * Clear all registered class-based middleware (useful for testing).
+     */
+    static clearClassMiddlewares(): void;
+    /**
+     * Add a raw route definition (used internally and by file-based routing).
+     */
+    addRoute(definition: RouteDefinition): RouteRef;
+    /**
+     * Register a GET route programmatically.
+     */
+    get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a POST route programmatically.
+     */
+    post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a PUT route programmatically.
+     */
+    put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a PATCH route programmatically.
+     */
+    patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a DELETE route programmatically.
+     */
+    delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register an explicit HEAD route. By default the framework auto-handles
+     * HEAD by falling back to the GET route and stripping the body
+     * (RFC 9110 §9.3.2). Use this only when you need a HEAD handler that
+     * does something different from GET — e.g. cheaper existence-check
+     * logic, custom validator headers without the cost of building the body.
+     * The framework still strips the response body for you on the way out.
+     */
+    head(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register an explicit OPTIONS route. By default the framework auto-
+     * handles OPTIONS by building an Allow header from every method
+     * registered for the path and returning 204 (RFC 9110 §9.3.7). Use
+     * this to take over that behaviour.
+     */
+    options(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Register a route that matches ANY HTTP method.
+     */
+    any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Create a route group with a shared prefix and optional middlewares.
+     */
+    group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void;
+    /**
+     * Match a request method + pathname to a registered route.
+     *
+     * When `TINA4_TRAILING_SLASH_REDIRECT=true` and the request path ends in
+     * a trailing slash that doesn't match a registered route, retry without
+     * the trailing slash. Returning the de-slashed pattern lets callers issue
+     * a 308 redirect instead of a hard 404 — Python parity.
+     */
+    match(method: string, path: string): MatchResult | null;
+    /**
+     * Return the list of HTTP methods registered for ``path``, in canonical
+     * order GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS. Used by the
+     * dispatcher to build the ``Allow:`` header on 405 / OPTIONS responses
+     * (RFC 9110 §10.2.1, §9.3.7).
+     *
+     * If GET is registered, HEAD is appended implicitly (HEAD auto-fallback).
+     * OPTIONS is appended whenever any method exists for the path (the
+     * framework auto-handles OPTIONS).
+     */
+    methodsAllowedForPath(path: string): string[];
+    /** Inner match against a list of compiled routes, no trailing-slash logic. */
+    private matchRoute;
+    /**
+     * Get all registered route definitions.
+     */
+    getRoutes(): RouteDefinition[];
+    /** Alias for getRoutes(). */
+    allRoutes(): RouteDefinition[];
+    /**
+     * List all routes in a debug-friendly format for CLI output.
+     */
+    listRoutes(): RouteInfo[];
+    /**
+     * Register a WebSocket route.
+     *
+     * A WS route is PUBLIC by default (mirrors GET). It can be marked secured in
+     * EITHER way the HTTP routes support:
+     *   • imperatively — `websocket(path, fn, { secured: true })`, or chain the
+     *     returned ref: `websocket(path, fn).secure()`;
+     *   • decorator-style — a `_secured` flag on the handler function, set in
+     *     either order relative to registration (the ref keeps a back-reference
+     *     to the route so a later `.secure()` / `_secured` still flips it).
+     *
+     * When secured, the upgrade handshake requires a valid JWT (Authorization
+     * header / `bearer` subprotocol / `?token=`) or the upgrade is rejected.
+     */
+    websocket(path: string, handler: WebSocketRouteHandler, options?: {
+        secured?: boolean;
+    }): WsRouteRef;
+    /**
+     * Get all registered WebSocket route definitions.
+     */
+    getWebSocketRoutes(): WebSocketRouteDefinition[];
+    /**
+     * Match a WebSocket upgrade request path to a registered ws route.
+     * Returns the route only; use {@link matchWebSocketWithParams} when the
+     * upgrade handler needs the extracted `{param}` values.
+     */
+    matchWebSocket(pathname: string): WebSocketRouteDefinition | null;
+    /**
+     * Match a WebSocket upgrade path AND extract its `{param}` values, using the
+     * same pattern compiler as HTTP routes. A literal pattern (`/ws/chat`) still
+     * matches exactly with empty params; a parameterised pattern
+     * (`/ws/rtc/{room}`) matches `/ws/rtc/abc` and yields `{ room: "abc" }`.
+     * (Previously WS matching was exact-string only, so `{param}` routes never
+     * matched and `connection.params` was always empty.)
+     */
+    matchWebSocketWithParams(pathname: string): {
+        route: WebSocketRouteDefinition;
+        params: Record<string, string>;
+    } | null;
+    clear(): void;
+    /**
+     * Register a route for a specific HTTP method.
+     * Core registration method — all convenience methods delegate here.
+     */
+    static add(method: string, path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a GET route on the default global router.
+     */
+    static get(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a POST route on the default global router.
+     */
+    static post(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a PUT route on the default global router.
+     */
+    static put(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a PATCH route on the default global router.
+     */
+    static patch(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a DELETE route on the default global router.
+     */
+    static delete(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a route that matches ANY HTTP method on the default global router.
+     */
+    static any(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef;
+    /**
+     * Register a WebSocket route on the default global router.
+     */
+    static websocket(path: string, handler: WebSocketRouteHandler, options?: {
+        secured?: boolean;
+    }): WsRouteRef;
+    /**
+     * Match a WebSocket upgrade path against routes on the default global router.
+     * Returns the matched route definition (with its `authRequired` flag) or null.
+     */
+    static matchWebSocket(pathname: string): WebSocketRouteDefinition | null;
+    static matchWebSocketWithParams(pathname: string): {
+        route: WebSocketRouteDefinition;
+        params: Record<string, string>;
+    } | null;
+    /** All WebSocket route definitions on the default global router. */
+    static getWebSocketRoutes(): WebSocketRouteDefinition[];
+    /**
+     * Create a route group on the default global router.
+     */
+    static group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void;
+    /**
+     * Supported typed-parameter constraints. Mirrored verbatim in
+     * tina4-python / tina4-php / tina4-ruby for cross-framework parity.
+     *
+     * Any type name not in this table throws at route registration time —
+     * we never silently fall through to the default matcher, because a
+     * typo like `{id:inetger}` would otherwise match anything and create
+     * a security footgun (see tina4-book#125).
+     */
+    private static readonly PARAM_TYPE_PATTERNS;
+    private compilePattern;
+}
+/**
+ * Route group for grouping routes under a shared prefix with optional middlewares.
+ */
+export declare class RouteGroup {
+    private router;
+    private prefix;
+    private groupMiddlewares?;
+    constructor(router: Router, prefix: string, groupMiddlewares?: MiddlewareSpec[] | undefined);
+    private mergeMiddlewares;
+    get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+    /**
+     * Nested groups.
+     */
+    group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void;
+}
+/**
+ * Resolve a string-form middleware spec to a middleware function.
+ *
+ * Forms (parity with Python/PHP/Ruby):
+ *   "ResponseCache"      → responseCache() with the default/env TTL
+ *   "ResponseCache:300"  → responseCache({ ttl: 300 })
+ *
+ * The head before the first ":" names the middleware; any trailing
+ * colon-separated parts are its arguments (numeric parts are parsed as
+ * integers). Unknown names throw so a typo surfaces instead of silently
+ * dropping the middleware. `responseCache` is loaded via a dynamic import so
+ * the router carries no import-time dependency on the cache module.
+ *
+ * Exported so route dispatch (and tests) can turn a spec into a runnable
+ * middleware.
+ */
+export declare function resolveStringMiddleware(spec: string): Promise<Middleware>;
+/**
+ * Run the per-route middleware chain. Returns false when it short-circuited
+ * and the handler must be skipped.
+ *
+ * Accepts middleware functions, middleware CLASSES, and string specs
+ * (e.g. "ResponseCache:300"). A function or string spec is resolved and
+ * invoked as `mw(req, res, next)` exactly as before.
+ *
+ * A CLASS runs its beforeX hooks through the SAME `MiddlewareRunner.runBefore`
+ * and the SAME return-value table as global middleware — no parallel runner.
+ * Its afterX hooks run with the global after pass once the handler is done
+ * (server.ts / testClient.ts append the route's classes to that list), because
+ * "after" means after the handler, not after this function. Every spec used to
+ * be invoked as `mw(req, res, next)`, which for a class throws "Class
+ * constructor cannot be invoked without 'new'", so a class attached per-route
+ * was inert. Python and PHP both ran per-route class hooks already.
+ */
+export declare function runRouteMiddlewares(middlewares: MiddlewareSpec[], req: Tina4Request, res: Tina4Response): Promise<boolean>;
+/**
+ * Default global router instance.
+ * Top-level get(), post(), etc. register routes here.
+ * The server merges these routes on startup.
+ */
+export declare const defaultRouter: Router;
+/**
+ * Top-level route registration functions — mirrors Python's decorator pattern.
+ *
+ * Usage:
+ *   import { get, post } from "@tina4/core";
+ *
+ *   get("/hello", async (req, res) => {
+ *     res.json({ message: "Hello" });
+ *   });
+ *
+ *   post("/users/{id}", async (req, res) => {
+ *     res.json({ id: req.params.id }, 201);
+ *   });
+ */
+export declare function get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function del(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef;
+export declare function websocket(path: string, handler: WebSocketRouteHandler, options?: {
+    secured?: boolean;
+}): WsRouteRef;
+export { del as delete };

package/types/core/src/scss.d.ts

@@ -0,0 +1,19 @@
+export interface ScssConfig {
+    importPaths?: string[];
+    variables?: Record<string, string>;
+}
+export declare class ScssCompiler {
+    private _importPaths;
+    private _variables;
+    constructor(config?: ScssConfig);
+    /** Compile an SCSS string to CSS. */
+    compile(source: string): string;
+    /** Compile an SCSS file to CSS. */
+    compileFile(filePath: string): string;
+    /** Add a directory to the import resolution path. */
+    addImportPath(path: string): void;
+    /** Set or override an SCSS variable. */
+    setVariable(name: string, value: string): void;
+    /** Compile all .scss files in a directory into a single CSS output file. */
+    compileScss(scssDir?: string, output?: string, minify?: boolean): string;
+}