fist

Types

PathError

Errors encountered during reverse path generation via fist.path or fist.path_from.

pub type PathError {
  RouteNotFound(name: String)
  MissingParameter(route: String, missing: String)
  InvalidParameter(route: String, param: String, value: String)
}

Constructors

```
RouteNotFound(name: String)
```
The route name is not registered in the router.
```
MissingParameter(route: String, missing: String)
```
A required dynamic or wildcard parameter was not provided in the parameters list.
```
InvalidParameter(route: String, param: String, value: String)
```
A parameter was provided, but its value failed the route guard predicate.

PathRegistry

</>

A lightweight, self-contained registry of named route templates. Safe to store in application context without circular type dependencies.

pub type PathRegistry =
  @internal PathRegistry

RouteInfo

</>

Metadata about a registered route, introspectable via fist.inspect.

pub type RouteInfo =
  @internal RouteInfo

Router

opaque </>

Represents the router instance. Holds the Radix Trie structure for efficient route matching.

pub opaque type Router(req_body, ctx, output)

Values

allowed_methods

</>

pub fn allowed_methods(
  router: Router(req_body, ctx, output),
  path: String,
) -> List(http.Method)

Returns a list of all HTTP methods supported for the given path. Useful for handling CORS preflight OPTIONS requests and 405 Method Not Allowed responses.

describe

</>

pub fn describe(
  router: Router(req_body, ctx, output),
  description: String,
) -> Router(req_body, ctx, output)

Attaches a human-readable description to the last added route.

group

</>

pub fn group(
  router: Router(req, ctx, out),
  at prefix: String,
  with middlewares: List(
    fn(
      fn(request.Request(req), ctx, dict.Dict(String, String)) -> out,
    ) -> fn(request.Request(req), ctx, dict.Dict(String, String)) -> out,
  ),
  defining build_sub_router: fn(Router(req, ctx, out)) -> Router(
    req,
    ctx,
    out,
  ),
) -> Router(req, ctx, out)

Creates an isolated route group with a prefix and group-specific middlewares.

guard

</>

pub fn guard(
  router: Router(req_body, ctx, output),
  param param: String,
  when predicate: fn(String) -> Bool,
) -> Router(req_body, ctx, output)

Attaches a functional predicate (guard) to a dynamic parameter in the last added route.

When an incoming request matches this path segment, predicate is evaluated. If predicate returns True, routing continues down this branch. If predicate returns False, the router seamlessly falls through to subsequent sibling branches (e.g. matching numeric :id before generic :username) before returning 404.

Panics if called without an immediately preceding route or if param is not in the route.

handle

</>

pub fn handle(
  router: Router(req_body, ctx, output),
  request: request.Request(req_body),
  context: ctx,
  not_found: fn() -> output,
) -> output

Dispatches an incoming request through the router. If no route matches, the not_found fallback function is invoked.

has_path

</>

pub fn has_path(registry: PathRegistry, name: String) -> Bool

Checks if a route name is registered in the PathRegistry.

head

</>

pub fn head(
  router: Router(req_body, ctx, output),
  path path: String,
  to handler: fn(
    request.Request(req_body),
    ctx,
    dict.Dict(String, String),
  ) -> output,
) -> Router(req_body, ctx, output)

Adds a HEAD route to the router.

inspect

</>

pub fn inspect(
  router: Router(req_body, ctx, output),
) -> List(RouteInfo)

Returns a list of all registered routes and their metadata.

map

</>

pub fn map(
  router: Router(req_body, ctx, a),
  fun: fn(a) -> b,
) -> Router(req_body, ctx, b)

Transforms the output value of all route handlers using a mapping function.

map_context

</>

pub fn map_context(
  router: Router(req_body, ctx_b, output),
  mapper: fn(ctx_a) -> ctx_b,
) -> Router(req_body, ctx_a, output)

Transforms the context required by the router handlers from ctx_b to ctx_a.

merge

</>

pub fn merge(
  a: Router(req, ctx, out),
  b: Router(req, ctx, out),
) -> Router(req, ctx, out)

Combines two routers into a single unified router.

mount

</>

pub fn mount(
  parent: Router(req, ctx_a, out),
  at prefix: String,
  sub sub_router: Router(req, ctx_b, out),
  transform mapper: fn(ctx_a) -> ctx_b,
) -> Router(req, ctx_a, out)

Mounts a sub-router under a specified URL prefix, mapping parent context to child context.

name

</>

pub fn name(
  router: Router(req_body, ctx, output),
  name name: String,
) -> Router(req_body, ctx, output)

Assigns a unique identifier name to the last added route for reverse routing.

Panics if called without an immediately preceding route definition, if name is empty, or if name collides with an existing registered route name.

new

</>

pub fn new() -> Router(req_body, ctx, output)

Creates a new, empty router.

options

</>

pub fn options(
  router: Router(req_body, ctx, output),
  path path: String,
  to handler: fn(
    request.Request(req_body),
    ctx,
    dict.Dict(String, String),
  ) -> output,
) -> Router(req_body, ctx, output)

Adds an OPTIONS route to the router.

patch

</>

pub fn patch(
  router: Router(req_body, ctx, output),
  path path: String,
  to handler: fn(
    request.Request(req_body),
    ctx,
    dict.Dict(String, String),
  ) -> output,
) -> Router(req_body, ctx, output)

Adds a PATCH route to the router.

path

</>

pub fn path(
  router: Router(req_body, ctx, output),
  for name: String,
  with params: List(#(String, String)),
) -> Result(String, PathError)

Generates a canonical URL path from a Router given a route name and parameter list.

Returns Error(RouteNotFound(name)) if the route was not registered with fist.name. Returns Error(MissingParameter(route, missing)) if a required path segment parameter is omitted. Returns Error(InvalidParameter(route, param, value)) if a parameter fails its route guard predicate. Unused parameters in with are automatically formatted and appended as URL query parameters.

path_from

</>

pub fn path_from(
  registry: PathRegistry,
  for name: String,
  with params: List(#(String, String)),
) -> Result(String, PathError)

Generates a canonical URL path from a PathRegistry given a route name and parameter list.

path_names

</>

pub fn path_names(registry: PathRegistry) -> List(String)

Returns a list of all registered route names in the PathRegistry.

path_registry

</>

pub fn path_registry(
  router: Router(req_body, ctx, output),
) -> PathRegistry

Extracts a lightweight, self-contained PathRegistry from a Router.

The registry contains all named route templates and their guards, but has no generic dependencies on request body, context, or output types. It can be safely stored in the application context (e.g. AppContext) to allow handlers to generate reverse paths.

path_template

</>

pub fn path_template(
  registry: PathRegistry,
  name: String,
) -> Result(String, Nil)

Returns the canonical path template string for a registered route name (e.g. “/users/:id”).

post

</>

pub fn post(
  router: Router(req_body, ctx, output),
  path path: String,
  to handler: fn(
    request.Request(req_body),
    ctx,
    dict.Dict(String, String),
  ) -> output,
) -> Router(req_body, ctx, output)

Adds a POST route to the router.

put

</>

pub fn put(
  router: Router(req_body, ctx, output),
  path path: String,
  to handler: fn(
    request.Request(req_body),
    ctx,
    dict.Dict(String, String),
  ) -> output,
) -> Router(req_body, ctx, output)

Adds a PUT route to the router.

route

</>

pub fn route(
  router: Router(req_body, ctx, output),
  method method: http.Method,
  path path: String,
  handler handler: fn(
    request.Request(req_body),
    ctx,
    dict.Dict(String, String),
  ) -> output,
) -> Router(req_body, ctx, output)

Adds a route for an arbitrary HTTP method and path to the router.

wrap

</>

pub fn wrap(
  router: Router(req, ctx, out),
  middleware: fn(
    fn(request.Request(req), ctx, dict.Dict(String, String)) -> out,
  ) -> fn(request.Request(req), ctx, dict.Dict(String, String)) -> out,
) -> Router(req, ctx, out)

Wraps all route handlers in the router with a middleware function.

fist - v1.9.0