Skip to content

feat: Strongly-typed route path parameters using template literals - #19

Merged
insanerx merged 2 commits into
mainfrom
refactor/before-release
Aug 14, 2026
Merged

feat: Strongly-typed route path parameters using template literals#19
insanerx merged 2 commits into
mainfrom
refactor/before-release

Conversation

@insanerx

Copy link
Copy Markdown
Contributor

PR Description: Strongly-Typed Path Parameters via TS Template Literal Type Inference

This PR introduces compile-time path parameter type extraction to Volten's routing methods. Developers will now enjoy auto-completion and type safety when accessing ctx.params variables directly based on the route string pattern.


High-Level Overview

Previously, ctx.params was typed as Record<string, string>, meaning accessing a route parameter did not guarantee the parameter existed on the path, requiring unsafe casts or unchecked property lookups.

This PR adds advanced type level helpers to Volten. When defining a route, such as app.get("/users/:userId/posts/:postId", (ctx) => { ... }), the keys "userId" and "postId" are parsed directly from the path string literal type. ctx.params is then dynamically typed as { userId: string; postId: string }.


Key Technical Changes

1. Compile-Time Path Parsing Type Helpers (src/core/types.ts)

  • Added ExtractParamKeys<T> type helper mapping path segments recursively:
    • Extracts named params (e.g. :id -> "id").
    • Extracts wildcards (e.g. * -> "*").
  • Added ExtractParams<T> type helper converting path literals to key-value objects.
  • Updated VoltenHandler, PreflightHandler, and ErrorHandler signatures to propagate the generic path string literal parameter P.

2. Router API Generic Integrations (src/core/router.ts)

  • Updated all HTTP verb router methods (get, post, patch, put, delete) to define <P extends string> generics.
  • Handlers passed to routes now bind to VoltenHandler<P>[].

3. Context Params Mapping (src/utils/requestCtx.ts)

  • Updated RequestContext to accept generic parameter <P extends string = string>.
  • Changed ctx.params property typing to match ExtractParams<P> instead of general Params.

4. Tests Added (tests/unit/core/types.test.ts [NEW])

  • Added compile-time types evaluation checks verifying single parameters, nested parameters, and wildcards.
  • Added compiler checks for router handlers.

Breaking Changes

  • Type Parameter Requirements: Custom wrappers around VoltenHandler might require updating signatures to accept or default a type parameter P extends string.
  • Type Casts: Code attempting to assign ctx.params to a generic dictionary might require casting or widening if the route path is statically typed.

@insanerx
insanerx merged commit 40f2e53 into main Aug 14, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant