How axiac/maroco works
• Testing Entry Point: The exported $route() function (located in src/_route.ts and referenced in the README) is the primary entry point. It determines which controller action is handling a specified HTTP verb and URL.
• Jest Matchers (src/matchers): A whole suite of matcher functions such as toBeHandled, toReturnJSON, toUseQueryParameter, etc. These components encapsulate the testing logic and ensure that the response and request handling follow expected rules.
• Metadata System (src/metadata): Components like Action.ts, Controller.ts, Route.ts, and metadataArgs.ts collect and manage metadata regarding controllers and their actions. This information is essential for the $route() function to resolve requests.
• Utility Functions (src/util): Support functions (for example, getDecoratorForVerb and type-checking utilities) used internally by both the $route function and the matchers to validate and format input.
• Tests: The tests directory mirrors the main structure by having corresponding test files for matchers and utilities. This verifies the correctness and expected behavior of each component.
• The testing code (tests directory) calls the $route() function with a HTTP verb and route, which then uses the metadata (extracted from the Routing Controllers annotations) to resolve the target controller action.
• Once the route is resolved, the returned object (the “route” object) is evaluated by the various Jest matchers in order to assert the specifics of its implementation (e.g., response type, parameter usage, HTTP headers).
• Utility functions support both the $route resolution and the operation of matchers by enforcing type expectations and handling decorator-based metadata.
Architectural patterns and design choices
• Modular Architecture: Components are organized into distinct folders (matchers, metadata, util) which indicates clean separation of concerns.
• Dependency Injection via Metadata: The system leverages metadata (decorators) to automatically wire up the controller actions with the corresponding routes, a common pattern in MVC or decorator-based frameworks.
• Testing Companion Library: The overall design is focused on testing; it’s intentionally decoupled from production code, acting as a companion to the Routing Controllers package by providing semantic matchers.
• Clear demarcation between core functionality (resolving route actions) and testing assertions (Jest matchers).