flowingts 0.0.0 → 0.19.0

package/dist/core/app.js

@@ -0,0 +1,283 @@
+import { uploadSettings } from './uploads/receive.js';
+import '../shims/symbol-metadata.js';
+import { childScope, joinPrefix, compileAutoRoutes, compileManualRoute, createGroup, ROOT_SCOPE, } from './compiler.js';
+import { MountedGroup, RouteGroupScope } from './mounted-group.js';
+import { staticHandler } from '../server/static.js';
+import { canonicalPath, joinPaths } from '../utils/path.js';
+import { generateOpenAPI } from '../openapi/generate.js';
+import { compileHealth } from './health.js';
+import { mediaType } from '../utils/content-type.js';
+import { compileHostMatcher } from '../utils/origin-match.js';
+import { inject } from './inject.js';
+import { guardsMiddleware } from './guard.js';
+import { consoleLogger, silentLogger } from './logger.js';
+import { createTelemetry } from './telemetry.js';
+import { buildSecurityHeaders } from '../middlewares/security-headers.js';
+import { FrameworkRoutes } from './registry/framework-routes.js';
+import { RouteRegistry } from './registry/registry.js';
+import { RequestHandler } from './runtime/request-handler.js';
+import { RequestObserver } from './runtime/observer.js';
+import { ServerLifecycle } from './runtime/server.js';
+import { routeHooks } from './hooks.js';
+import { NATIVE_CONTRACTS } from './contracts.js';
+function assertOpen(scope) {
+    if (scope.token && !scope.token.open) {
+        throw new Error('[flowing] app.group(): this group has already finished; register its routes inside the callback, synchronously.');
+    }
+}
+const isThenable = (v) => (typeof v === 'object' || typeof v === 'function') && v !== null && typeof v.then === 'function';
+/**
+ * O app. É uma fachada (Facade) sobre o registro de rotas, as rotas do próprio framework (health, OpenAPI),
+ * o servidor e o pipeline da requisição: a API pública fica aqui, e o trabalho fica nesses componentes.
+ */
+export class FlowingApp {
+    log;
+    core;
+    registry;
+    framework;
+    runtime;
+    requests;
+    constructor(opts = {}) {
+        this.log = opts.logger === false ? silentLogger : (opts.logger ?? consoleLogger());
+        this.core = {
+            opts,
+            log: this.log,
+            middlewares: [],
+            errorHandlers: [],
+            onSendHooks: [],
+            onRequestHooks: [],
+            contracts: opts.contracts ?? NATIVE_CONTRACTS,
+            telemetry: opts.telemetry ? createTelemetry(opts.telemetry) : undefined,
+            onResponseHooks: [],
+            scopedOnResponse: 0,
+            onCloseHooks: [],
+            // Compilados na criação: uma regra inválida falha aqui, e não na primeira requisição.
+            allowedHosts: opts.allowedHosts ? compileHostMatcher(opts.allowedHosts) : undefined,
+            serializers: new Map(Object.entries(opts.serializers ?? {}).map(([type, fn]) => [mediaType(type), fn])),
+            uploads: uploadSettings(opts.uploads),
+            applySecurityHeaders: opts.securityHeaders !== false ? buildSecurityHeaders(opts.securityHeaders) : undefined,
+        };
+        this.registry = new RouteRegistry(this.core, () => this.framework.reservedPaths(), () => this.framework.openapi?.cache.clear());
+        this.framework = new FrameworkRoutes(this.core, this.registry);
+        const observer = new RequestObserver(this.core);
+        this.runtime = new ServerLifecycle(this.core, () => this.callback(), observer);
+        this.requests = new RequestHandler(this.core, this.registry, this.framework, this.runtime, observer);
+    }
+    use(mw) {
+        this.core.middlewares.push(mw);
+        return this;
+    }
+    onError(h) {
+        this.core.errorHandlers.push(h);
+        return this;
+    }
+    /**
+     * Roda imediatamente antes de escrever uma resposta com corpo (exceto streams), inclusive em erros
+     * e 404. É síncrono: pode alterar headers (ETag, assinatura) ou devolver `{ body, contentType }`
+     * novos. Se lançar, o erro é logado e a resposta original é enviada (F-04).
+     */
+    onSend(hook) {
+        this.core.onSendHooks.push(hook);
+        return this;
+    }
+    /**
+     * Roda no início de cada requisição, antes da validação do `Host` e dos middlewares: abrir um span, contar
+     * requisições ativas. Toda requisição que passa por aqui também passa pelo `onResponse`. É síncrono; erros
+     * são só logados (F-38).
+     */
+    onRequest(hook) {
+        this.core.onRequestHooks.push(hook);
+        return this;
+    }
+    /**
+     * Roda exatamente uma vez quando a requisição termina, com status, duração, `outcome` (`completed`,
+     * `aborted`, `error`), motivo do cancelamento, tempo até os headers, rota e se foi stream: métricas,
+     * tracing, auditoria. Pode ser assíncrono; erros são só logados (F-04, F-38).
+     */
+    onResponse(hook) {
+        this.core.onResponseHooks.push(hook);
+        return this;
+    }
+    /**
+     * Roda no `close()`, depois que o servidor fecha, qualquer que seja a origem (sinal, teste, código),
+     * e antes do `shutdown.onShutdown`. Erros são logados e fazem o `close()` rejeitar ao final (F-04).
+     */
+    onClose(hook) {
+        this.core.onCloseHooks.push(hook);
+        return this;
+    }
+    mount(ref, options = {}) {
+        return this.mountIn(ROOT_SCOPE, ref, options);
+    }
+    /**
+     * Agrupa `mount()`s sob um prefixo, middlewares e guards comuns. Não é um container: é só composição,
+     * com a mesma semântica do `mount()`. Grupos podem ser aninhados.
+     *
+     * ```ts
+     * app.group({ prefix: '/v2', middlewares: [authenticate], guards: [isAdmin] }, (g) =>
+     *   g.mount(UserRoutes).mount(new OrderRoutes(db)),
+     * );
+     * ```
+     * Ordem de execução: middlewares dos grupos (de fora para dentro) → do `mount()` → da classe → do método.
+     */
+    group(options, define) {
+        this.groupIn(ROOT_SCOPE, options, define);
+        return this;
+    }
+    /** @internal */
+    groupIn(parent, options, define) {
+        assertOpen(parent);
+        const scope = childScope(parent, options);
+        // Registro em duas fases: o que o callback registrar fica pendente e só é efetivado se ele terminar
+        // de forma síncrona e sem erro. Grupos aninhados entram no lote do grupo mais externo; se um aninhado
+        // falhar (mesmo com o erro capturado pelo externo), só a parte dele é descartada.
+        const outermost = this.registry.pending === undefined;
+        if (outermost)
+            this.registry.pending = [];
+        const mark = this.registry.pending.length;
+        try {
+            const result = define(new RouteGroupScope(this, scope));
+            if (isThenable(result)) {
+                // O callback continua rodando depois do `await`; o escopo fechado abaixo rejeita registros
+                // tardios, e este handler evita um unhandledRejection.
+                result.then(undefined, (err) => this.log.error({ err }, 'async app.group() callback failed after the group was rejected'));
+                throw new Error('[flowing] app.group(): the callback must be synchronous; do async work before registering routes.');
+            }
+            if (outermost)
+                this.registry.commit(this.registry.pending);
+        }
+        catch (err) {
+            this.registry.pending.length = mark;
+            throw err;
+        }
+        finally {
+            scope.token.open = false;
+            if (outermost)
+                this.registry.pending = undefined;
+        }
+    }
+    /**
+     * Serve os arquivos de `root` em `GET prefix/*` (F-13). É uma rota como as outras: vale `group()`
+     * (host, guards, middlewares), 404/405 e a checagem de conflitos. Não entra no OpenAPI.
+     *
+     * ```ts
+     * app.static('/assets', './public', { maxAge: '7d', immutable: true });
+     * app.static('/', './dist', { fallback: 'index.html' }); // SPA
+     * ```
+     * Caminhos que saem da raiz (`..`, symlinks), arquivos ocultos e diretórios sem índice respondem 404.
+     */
+    static(prefix, root, opts = {}) {
+        this.staticIn(ROOT_SCOPE, prefix, root, opts);
+        return this;
+    }
+    /** @internal */
+    staticIn(scope, prefix, root, opts) {
+        assertOpen(scope);
+        const handler = staticHandler(root, opts);
+        const base = joinPrefix(scope.prefix, prefix) || '/';
+        const route = (path) => ({
+            method: 'GET',
+            path,
+            handler: (ctx) => handler(ctx),
+            schemas: {},
+            middlewares: [...scope.middlewares],
+            guards: [...scope.guards],
+            hooks: routeHooks(scope.hooks),
+            owner: 'static',
+            handlerName: `static('${prefix}')`,
+            hosts: scope.hosts,
+            internal: true,
+        });
+        // `prefix/*` cobre os arquivos; o próprio prefixo (`/assets`, `/assets/`) serve o índice.
+        const routes = [route(joinPaths(base, '*'))];
+        if (base !== '/')
+            routes.push(route(base));
+        this.registry.stage(`static('${prefix}')`, routes);
+    }
+    /** @internal */
+    mountIn(scope, ref, options = {}) {
+        assertOpen(scope);
+        const group = createGroup(ref, options, scope);
+        this.registry.stage(group.name, compileAutoRoutes(group));
+        return new MountedGroup(this, group, (g, method, path, select, opts) => {
+            assertOpen(scope);
+            this.registry.stage(g.name, [compileManualRoute(g, method, path, select, opts)]);
+        }, scope);
+    }
+    /**
+     * Serve o documento OpenAPI 3.1 gerado das rotas (`/openapi.json`) e, com `docs`, o Swagger UI (F-16).
+     * As duas rotas passam pelos middlewares globais e pelos `middlewares`/`guards` informados aqui:
+     * `app.openapi({ guards: [isAdmin] })`. O documento é gerado na primeira requisição, depois dos `mount()`.
+     */
+    openapi(opts = {}) {
+        const path = opts.path ?? '/openapi.json';
+        const docs = opts.docs === true ? '/docs' : opts.docs || false;
+        if (docs && canonicalPath(docs) === canonicalPath(path))
+            throw new Error(`[flowing] openapi(): "docs" and "path" cannot both be "${path}".`);
+        this.framework.assertFreePaths('app.openapi()', docs ? [canonicalPath(path), canonicalPath(docs)] : [canonicalPath(path)], 'openapi');
+        const pipeline = [...(opts.middlewares ?? [])];
+        if (opts.guards?.length)
+            pipeline.push(guardsMiddleware(opts.guards));
+        this.framework.openapi = { opts, path, docs, pipeline, cache: new Map() };
+        return this;
+    }
+    /**
+     * Healthchecks para load balancers e orquestradores (Kubernetes, ECS…).
+     * - `GET /livez`: o processo está de pé (200 sempre).
+     * - `GET /readyz`: pronto para receber tráfego. Roda os `checks` (banco, fila…) e responde 503 se algum
+     *   falhar ou estourar o tempo, e também durante o encerramento.
+     *
+     * As rotas são servidas **antes** dos middlewares globais (sondas não têm credenciais nem devem
+     * consumir rate limit); use `guards`/`middlewares` aqui para restringir.
+     */
+    health(opts = {}) {
+        const config = compileHealth(opts, this.log);
+        this.framework.assertFreePaths('app.health()', config.paths, 'health');
+        this.framework.health = config;
+        return this;
+    }
+    /**
+     * Documento OpenAPI 3.1 das rotas registradas até agora, para gravar em arquivo ou testar (F-16).
+     * Com virtual hosts, é por host (F-35): `{ host: 'api.exemplo.com' }` traz as rotas desse host e as sem
+     * host; sem `host`, só as sem host. Domínios diferentes nunca se misturam num mesmo documento.
+     */
+    openapiDocument(opts = this.framework.openapi?.opts ?? {}) {
+        return generateOpenAPI(this.registry.routesFor(opts.host?.toLowerCase()), opts, !this.core.opts.formatError, (s) => this.core.contracts.toJsonSchema(s));
+    }
+    /** Executa o pipeline completo para um contexto já criado. */
+    handle(ctx) {
+        return this.requests.handle(ctx);
+    }
+    /**
+     * Listener `(req, res)` do app, para usar com qualquer servidor do Node:
+     * `https.createServer(opts, app.callback())`, `http2` em modo compat, testes etc. (F-09).
+     */
+    callback() {
+        return this.requests.callback();
+    }
+    listen(options = {}) {
+        return this.runtime.listen(options);
+    }
+    /**
+     * Troca os certificados sem reiniciar nem derrubar conexões (renovação, ACME externo). Conexões novas
+     * usam os novos; as abertas seguem com os antigos. Um certificado inválido lança erro e mantém os atuais.
+     */
+    reloadTLS(tls) {
+        this.runtime.reloadTLS(tls);
+    }
+    /**
+     * Para de aceitar conexões, encerra as ociosas e espera as requisições em andamento terminarem.
+     * Depois de `graceMs`, força o fechamento das restantes.
+     */
+    close(graceMs = 10_000) {
+        return this.runtime.close(graceMs);
+    }
+    /** Executa uma requisição em memória, sem rede. Ideal para testes (F-09). */
+    inject(opts) {
+        return inject(this.callback(), typeof opts === 'string' ? { url: opts } : opts);
+    }
+}
+export function createApp(opts) {
+    return new FlowingApp(opts);
+}
+//# sourceMappingURL=app.js.map

package/dist/core/app.js.map

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

package/dist/core/body-parser.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from './context.ts';
+import { type ProtoPoisoning } from '../utils/safe-json.ts';
+/**
+ * Parser de body para um tipo de mídia (F-12): recebe o corpo cru, já limitado pelo `bodyLimit`, e devolve o valor
+ * de `ctx.body`. Pode ser assíncrono. O resultado passa pela proteção contra prototype pollution (S-08) e é validado
+ * pelo contrato da rota, como o JSON.
+ */
+export type BodyParser = (raw: Buffer, ctx: Context) => unknown;
+/**
+ * Lê e parseia o body: JSON nativo e os `parsers` do app (F-12), respeitando `limit` em bytes. O app chama antes dos
+ * middlewares globais, que recebem o body já lido; é uma etapa direta, sem camada de middleware (F-39).
+ */
+export declare function bodyReader(limit: number, protoPoisoning?: ProtoPoisoning, parsers?: ReadonlyMap<string, BodyParser>): (ctx: Context) => Promise<void> | undefined;
+//# sourceMappingURL=body-parser.d.ts.map

package/dist/core/body-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-parser.d.ts","sourceRoot":"","sources":["../../src/core/body-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAkC,KAAK,cAAc,EAAe,MAAM,uBAAuB,CAAC;AAEzG;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;AAEhE;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,cAAwB,EACxC,OAAO,GAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAa,GACnD,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CA8D7C"}

package/dist/core/body-parser.js

@@ -0,0 +1,76 @@
+import { isJsonContentType, mediaType } from '../utils/content-type.js';
+import { parseJson, ProtoPoisoningError, scrubParsed } from '../utils/safe-json.js';
+/**
+ * Lê e parseia o body: JSON nativo e os `parsers` do app (F-12), respeitando `limit` em bytes. O app chama antes dos
+ * middlewares globais, que recebem o body já lido; é uma etapa direta, sem camada de middleware (F-39).
+ */
+export function bodyReader(limit, protoPoisoning = 'error', parsers = new Map()) {
+    // Síncrono quando não há body a ler (GET, HEAD, outro Content-Type): sem Promise por requisição (F-41).
+    return (ctx) => {
+        if (ctx.method === 'GET' || ctx.method === 'HEAD')
+            return undefined;
+        const contentType = ctx.req.headers['content-type'];
+        if (isJsonContentType(contentType))
+            return readJson(ctx);
+        // Sem parsers configurados, nem o tipo de mídia é calculado.
+        if (parsers.size === 0)
+            return undefined;
+        const parser = parsers.get(mediaType(contentType));
+        return parser ? readWith(ctx, parser) : undefined;
+    };
+    async function readRaw(ctx) {
+        // B-12: rejeita cedo pelo Content-Length e fecha a conexão ao exceder,
+        // para o cliente não continuar enviando um corpo que será descartado.
+        const tooLarge = () => {
+            ctx.res.setHeader('Connection', 'close');
+            return ctx.throw(413, 'Payload too large', 'PAYLOAD_TOO_LARGE');
+        };
+        const declared = Number(ctx.req.headers['content-length']);
+        if (Number.isFinite(declared) && declared > limit)
+            tooLarge();
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of ctx.req) {
+            size += chunk.length;
+            if (size > limit)
+                tooLarge();
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks);
+    }
+    async function readJson(ctx) {
+        const raw = (await readRaw(ctx)).toString('utf8');
+        if (raw) {
+            try {
+                ctx.body = parseJson(raw, protoPoisoning);
+            }
+            catch (err) {
+                // S-08: `__proto__` e `constructor.prototype` no body são recusados (ou removidos, se configurado).
+                if (err instanceof ProtoPoisoningError)
+                    ctx.throw(400, err.message, 'PROTO_POISONING');
+                ctx.throw(400, 'Invalid JSON', 'INVALID_JSON');
+            }
+        }
+    }
+    async function readWith(ctx, parser) {
+        const raw = await readRaw(ctx);
+        if (raw.length === 0)
+            return;
+        let value;
+        try {
+            value = await parser(raw, ctx);
+        }
+        catch {
+            // A mensagem do parser pode expor detalhes internos: o cliente recebe só o motivo genérico.
+            ctx.throw(400, 'Invalid body', 'INVALID_BODY');
+        }
+        try {
+            scrubParsed(value, protoPoisoning);
+        }
+        catch (err) {
+            ctx.throw(400, err.message, 'PROTO_POISONING');
+        }
+        ctx.body = value;
+    }
+}
+//# sourceMappingURL=body-parser.js.map

package/dist/core/body-parser.js.map

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

package/dist/core/compiler.d.ts

@@ -0,0 +1,104 @@
+import type { Guard } from './guard.ts';
+import type { Middleware } from './compose.ts';
+import { type RouterMetadata } from './metadata.ts';
+import type { RouteDefinition } from './route-table.ts';
+import { type MatchRule, type RouteHostRule } from '../utils/origin-match.ts';
+import { type HookOptions, type RouteHooks, type ScopedHooks } from './hooks.ts';
+export interface CompiledRoute extends RouteDefinition {
+    method: string;
+    path: string;
+    /** Classe e método de origem, para mensagens e para o OpenAPI (F-16). */
+    owner: string;
+    handlerName: string;
+    /** Virtual hosts da rota (F-35); vazio = qualquer host. */
+    hosts: readonly RouteHostRule[];
+    /** Rota criada pelo framework (`static()`): fica fora do OpenAPI. */
+    internal?: boolean;
+    /** Hooks com escopo da rota (F-43), já em ordem de execução; ausente se não há nenhum. */
+    hooks?: RouteHooks | undefined;
+}
+/** Um host, ou uma lista: `'api.exemplo.com'`, `'*.exemplo.dev'`, `/^tenant-\d+\.exemplo\.com$/`. */
+export type HostOption = MatchRule | readonly MatchRule[];
+export declare function compileHostOption(host: HostOption | undefined): RouteHostRule[];
+/** Classe com construtor sem argumentos **ou** instância já construída (B-10). */
+export type RouterRef = (new () => object) | object;
+type AnyMethod = (...args: never[]) => unknown;
+/** Seleciona um método da instância montada: `(r) => r.getUser` (F-30). */
+export type MethodSelector<T> = (routes: T) => AnyMethod;
+/** Seleciona vários métodos: `(r) => [r.list, r.getUser]` (F-30). */
+export type MethodsSelector<T> = (routes: T) => readonly AnyMethod[];
+/** Opções de `app.mount()`, aplicadas no ponto de composição (F-28, F-30). */
+export interface MountOptions<T = object> {
+    /** Substitui o prefixo definido no `@Router`. */
+    prefix?: string;
+    /** Registra só estes métodos de rota. Não pode ser usado junto com `except`. */
+    only?: MethodsSelector<T>;
+    /** Registra todos os métodos de rota, exceto estes. */
+    except?: MethodsSelector<T>;
+    /** Registra as rotas declaradas na classe. Padrão: `true`. Use `false` para só mapear manualmente. */
+    auto?: boolean;
+    /** Middlewares para todas as rotas do grupo; rodam antes dos `@Middlewares` da classe. */
+    middlewares?: readonly Middleware[];
+    /** Guards para todas as rotas do grupo; rodam antes dos `@Guards` da classe. */
+    guards?: readonly Guard[];
+    /** Hooks `onSend`, `onResponse` e `onError` só para estas rotas (F-43); rodam antes dos hooks da classe. */
+    hooks?: HookOptions;
+    /** Virtual host (F-35): as rotas só respondem nesses hosts. Sem `host`, valem para qualquer um. */
+    host?: HostOption;
+}
+/** Opções de uma rota mapeada manualmente: `.get(path, sel, { middlewares, guards })` (F-30). */
+export interface ManualRouteOptions {
+    /** Rodam depois dos `@Middlewares` do método (são as mais específicas). */
+    middlewares?: readonly Middleware[];
+    /** Rodam depois dos `@Guards` do método. */
+    guards?: readonly Guard[];
+    /** Hooks só desta rota (F-43): os mais específicos. */
+    hooks?: HookOptions;
+}
+/** Opções de `app.group()`: valem para todos os `mount()` do grupo, inclusive de grupos aninhados. */
+export interface GroupOptions {
+    /** Somado antes do prefixo de cada classe: `group({ prefix: '/v2' })` + `@Router('/users')` → `/v2/users`. */
+    prefix?: string;
+    /** Rodam antes dos middlewares do `mount()`. */
+    middlewares?: readonly Middleware[];
+    /** Rodam antes dos guards do `mount()`. */
+    guards?: readonly Guard[];
+    /** Hooks para todas as rotas do grupo (F-43); rodam antes dos hooks do `mount()`. */
+    hooks?: HookOptions;
+    /** Virtual host (F-35) para todos os `mount()` do grupo, inclusive os aninhados. */
+    host?: HostOption;
+}
+/** Escopo acumulado dos grupos em volta de um `mount()`. */
+export interface RouteScope {
+    /** Validade do grupo: depois que o callback do `group()` termina, registrar nele é erro. */
+    readonly token?: {
+        open: boolean;
+    };
+    prefix: string;
+    middlewares: readonly Middleware[];
+    guards: readonly Guard[];
+    hooks: ScopedHooks;
+    hosts: readonly RouteHostRule[];
+}
+export declare const ROOT_SCOPE: RouteScope;
+/** Prefixo de um grupo dentro de outro, sem barras duplicadas; vazio não altera nada. */
+export declare function joinPrefix(outer: string, inner: string): string;
+/** Escopo de um grupo aninhado em `parent`. */
+export declare function childScope(parent: RouteScope, opts: GroupOptions): RouteScope;
+/** Um grupo montado: a instância, sua metadata e as opções do `mount`. */
+export interface RouteGroup {
+    name: string;
+    instance: object;
+    meta: RouterMetadata;
+    prefix: string;
+    options: MountOptions;
+    scope: RouteScope;
+    hosts: readonly RouteHostRule[];
+}
+export declare function createGroup(ref: RouterRef, options?: MountOptions, scope?: RouteScope): RouteGroup;
+/** Rotas declaradas na classe (`@Get`, `@Post`…), filtradas por `only`/`except` e `auto`. */
+export declare function compileAutoRoutes(group: RouteGroup): CompiledRoute[];
+/** Rota mapeada no app: `.get('/legacy/:id', (r) => r.getUser, opts)` (F-30). */
+export declare function compileManualRoute(group: RouteGroup, httpMethod: string, path: string, selector: MethodSelector<object>, options?: ManualRouteOptions): CompiledRoute;
+export {};
+//# sourceMappingURL=compiler.d.ts.map

package/dist/core/compiler.d.ts.map

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