/ 
PAGI-FastAPI-v1.2.5
/ PAGI::FastAPI::TypedPath

NAME

PAGI::FastAPI::TypedPath - Path Parameter Validation for PAGI::FastAPI

VERSION

Version v1.2.5

SYNOPSIS

use PAGI::FastAPI::Depends qw(Depends);
use PAGI::FastAPI::TypedPath qw(TypedPath);
use Types::Standard qw(Int);

$app->get('/items/{item_id}',
    dependencies => [
        Depends(TypedPath('item_id', Int), key => 'item_id'),
    ],
    handler => async sub ($c) {
        my $item_id = $c->stash->{item_id};   # validated
        return { item_id => $item_id };
    }
);

# Invalid input (e.g. GET /items/abc) never reaches the handler --
# the dependency short-circuits with 422 automatically, the same way
# core's own query/body validation does.

DESCRIPTION

Python FastAPI infers a path parameter's type from your function signature (e.g. item_id: int) and rejects non-matching requests with a 422 automatically. PAGI::FastAPI doesn't have an equivalent at the routing layer, path parameters always arrive as plain strings. TypedPath() reproduces the validate-and-422-automatically behaviour by building a coderef compatible with Depends(), so it plugs into the exact same dependency short-circuit mechanism core already uses for query/body validation failures (confirmed against the real dependency-execution loop in PAGI::FastAPI's source).

Validation vs. coercion: $type->validate($raw) (what Type::Tiny does by default) checks that the string looks right but doesn't transform it, a plain Types::Standard::Int will accept "42" but still hand back the string "42", not the Perl integer 42. If you need an actual coerced value, pass a type with coercion enabled (e.g. via Type::Tiny's plus_coercions), and TypedPath() will use ->coerce automatically when ->has_coercion is true.

FUNCTIONS

TypedPath($param_name, $type)

Returns a coderef of async sub ($c) {...} suitable for passing directly to Depends(). $type must be a Type::Tiny object.

On validation failure: sets $c->status(422) and returns { detail => "Path parameter '$param_name' invalid: $err" }, which (via core's own dependency-execution loop) short-circuits before your handler runs.

On success: returns the (optionally coerced) value. Pass key => ... to Depends() to have it land in $c->stash->{...}.

CAVEATS

This validates AFTER routing has already matched the request to a route using the raw, untyped {param} capture, it cannot be used to distinguish between two routes based on a path segment's type (e.g. /items/{id} where id must be numeric vs. a separate literal route). That level of route-matching-time type dispatch would require a change to the router itself, not just a dependency.

SEE ALSO

PAGI::FastAPI::Depends, Type::Tiny, Types::Standard

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/PAGI-FastAPI

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PAGI::FastAPI::TypedPath

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0).