valkyrjaio / valkyrja-ts / 30726327818

100%

push

github

[Routing] feat: Add routing decorators and runtime attribute route collectors (#85)

# Description

Brings the TypeScript port to parity with the PHP and Java
implementations by
adding **declarative routing decorators** for both HTTP and CLI, plus
the runtime
`AttributeRouteCollector` that turns them into routes — in addition to
the
existing imperative `getRoutes()` path, which is untouched.

Controllers and command controllers can now declare routes with
decorators
(`@Route`, `@DynamicRoute`, `@RouteHandler`, request-method decorators,
`@Middleware`, `@Name`, `@Path`, structs, and the CLI
`@ArgumentParameter` /
`@OptionParameter`), mirroring the PHP
`Valkyrja\Http\Routing\Attribute\*` /
`Valkyrja\Cli\Routing\Attribute\*` and Java
`io.valkyrja.*.routing.attribute`
shapes.

**How it works.** TC39 Stage-3 decorators write their metadata to the
standard
`context.metadata` object, which the runtime exposes as
`Controller[Symbol.metadata]`.
The new `AttributeRouteCollector` reads that metadata and builds the
route data —
no source parsing, so the framework keeps its zero-AST-dependency
guarantee (the
same relationship PHP's collector has via reflection). The service
providers wire
it exactly like PHP: in debug mode `publishData` walks each provider's
`getControllerClasses()`, runs the collector, and merges the result with
the
imperative `getRoutes()`; when not in debug mode the generated data
cache is used
unchanged. Sindri (build-time scanning) and the starter-app conversion
land in
follow-up PRs.

**Notes for reviewers.**
- Decorator metadata typing requires `Symbol.metadata`, so `tsconfig`
gains
`"lib": ["ES2023", "ESNext.Decorators"]` (verified the whole project
still
  type-checks; the framework is Node-only, no DOM usage).
- Parameter metadata is folded into `@DynamicRoute` options because
Stage-3 has
  no parameter decorators (mirrors PHP's `#[Parameter]`).
- Middleware is bucketed structurally (by the middleware class's
prototype
method) since TS i... (continued)

1735 of 1735 branches covered (100.0%)

Branch coverage included in aggregate %.

223 of 223 new or added lines in 34 files covered. (100.0%)

3765 of 3765 relevant lines covered (100.0%)

28.9 hits per line