Module

Yoga.HTTP.API.Route

Package
purescript-yoga-http-api
Repository
rowtype-yoga/purescript-yoga-http-api

Re-exports from Yoga.HTTP.API.Path

#Root Source

data Root

Root path representing "/"

Example: Path Root -- /

Instances

#Required Source

data Required a

Marker for required query parameters (default is optional → Maybe)

Example: Path ("users") :? (limit :: Int, offset :: Required Int) -- limit parses as Maybe Int, offset parses as Int (fails if missing)

#QueryParams Source

data QueryParams :: forall k. k -> Type -> Typedata QueryParams path params

Attach query parameters to a path

Example: Path ("users" / "id" : Int) :? { limit :: Int, offset :: Required Int }

Instances

#PathCons Source

data PathCons :: forall k1 k2. k1 -> k2 -> Typedata PathCons left right

Instances

#Path Source

data Path :: forall k. k -> Typedata Path segments

Type-level path representation

Examples: Path Root -- / Path (Lit "users") -- /users Path (Lit "users" / Capture "id" Int) -- /users/:id Path (Lit "users" / Capture "id" Int / Lit "posts") -- /users/:id/posts

Instances

#Param Source

data Param :: Symbol -> Type -> Typedata Param (name :: Symbol) (ty :: Type)

Sugar for Capture — use with bare Symbols in the path DSL

Example: Path ("users" / "id" : Int / "posts") -- equivalent to: Path (Lit "users" / Capture "id" Int / Lit "posts")

Instances

#Lit Source

data Lit :: Symbol -> Typedata Lit (segment :: Symbol)

Literal path segment (wrapper for Symbol to work around PureScript 0.15 limitations)

In PureScript 0.15, we can't use bare Symbols like Path "users" due to kind inference. Instead, use: Path (Lit "users")

Example: Path (Lit "users") -- /users Path (Lit "users" / Capture "id" Int) -- /users/:id

Instances

#Capture Source

data Capture :: Symbol -> Type -> Typedata Capture (name :: Symbol) (ty :: Type)

Capture a path parameter with a name and type

Example: Capture "id" Int -- captures :id as an Int Capture "name" String -- captures :name as a String

Instances

#ParseParam Source

class ParseParam (ty :: Type)  where

Parse a value from a String (used for path captures)

Members

Instances

#ParsePath Source

class ParsePath :: Type -> Row Type -> Constraintclass ParsePath (path :: Type) (params :: Row Type) | path -> params where

Parse a URL string into a record of typed path parameters

Examples: parsePath @(Path Root) "/" = Just {} parsePath @(Path (Lit "users")) "/users" = Just {} parsePath @(Path (Lit "users" / Capture "id" Int)) "/users/123" = Just { id: 123 }

Members

Instances

#PathPattern Source

class PathPattern :: forall k. k -> Constraintclass PathPattern path  where

Generate a Fastify-compatible URL pattern from a path type

Examples: pathPattern (Proxy :: _ (Path Root)) = "/" pathPattern (Proxy :: _ (Path (Lit "users"))) = "/users" pathPattern (Proxy :: _ (Path (Lit "users" / Capture "id" Int))) = "/users/:id" pathPattern (Proxy :: _ ("users" / "id" : Int)) = "/users/:id"

Members

Instances

#type (:?) Source

Operator alias for Yoga.HTTP.API.Path.QueryParams (left-associative / precedence 1)

#type (:) Source

Operator alias for Yoga.HTTP.API.Path.Param (right-associative / precedence 8)

#type (/) Source

Operator alias for Yoga.HTTP.API.Path.PathCons (right-associative / precedence 6)

Infix operator for building paths

Example: Lit "users" / Capture "id" Int / Lit "posts"

Re-exports from Yoga.HTTP.API.Route.Auth

#DigestAuth Source

newtype DigestAuth

Digest authentication header value

Example: parseHeader "Digest username="user", realm="api", ..." :: Either String DigestAuth = Right (DigestAuth "Digest username="user", realm="api", ...")

Constructors

Instances

#BasicAuth Source

newtype BasicAuth

Basic authentication header value (Base64-encoded credentials)

Example: parseHeader "Basic dXNlcjpwYXNz" :: Either String BasicAuth = Right (BasicAuth "dXNlcjpwYXNz")

The raw Base64-encoded credentials are preserved for server-side verification

Constructors

Instances

#ApiKeyHeader Source

newtype ApiKeyHeader

API Key passed in a custom header

Example: parseHeader "abc123" :: Either String ApiKeyHeader = Right (ApiKeyHeader "abc123")

Constructors

Instances

#ApiKeyCookie Source

newtype ApiKeyCookie

API Key passed in a cookie (for authentication purposes) This is a marker type that indicates the cookie should be treated as an authentication mechanism in OpenAPI (securitySchemes) rather than a regular cookie parameter.

Example: Request { cookies :: { sessionId :: ApiKeyCookie } }

Constructors

Instances

Re-exports from Yoga.HTTP.API.Route.BearerToken

#BearerToken Source

newtype BearerToken

Bearer token newtype that validates the "Bearer " prefix

Example: parseHeader "Bearer abc123" :: Either String BearerToken = Right (BearerToken "abc123") parseHeader "abc123" :: Either String BearerToken = Left "missing 'Bearer ' prefix"

Constructors

Instances

Re-exports from Yoga.HTTP.API.Route.Encoding

#XML Source

data XML a

XML encoded request/response body (application/xml)

Example: Request { body :: XML XmlDocument }

#Streaming Source

data Streaming a

Streaming response body (returns a Strom of decoded chunks)

Example: { body :: Streaming Uint8Array } -- raw binary { body :: Streaming String } -- text

#PlainText Source

data PlainText

Plain text request/response body (text/plain)

Example: { body :: PlainText }

#NoBody Source

data NoBody

No request body (for GET, DELETE, etc.)

Example: Request {} -- NoBody is the default when body is omitted

#MultipartFormData Source

data MultipartFormData a

Multipart form data encoded request body (multipart/form-data)

Example: Request { body :: MultipartFormData { file :: FileUpload } }

#JSON Source

data JSON a

JSON-encoded request body (application/json)

Example: Request { body :: JSON User }

#FormData Source

data FormData a

Form data encoded request body (application/x-www-form-urlencoded)

Example: Request { body :: FormData { username :: String, password :: String } }

#CustomContentType Source

data CustomContentType :: Symbol -> Type -> Typedata CustomContentType mime a

Custom content type with explicit MIME type

Example: Request { body :: CustomContentType "application/vnd.api+json" User }

Re-exports from Yoga.HTTP.API.Route.Handler

#NoRequest Source

type NoRequest = Record ()

Type alias for routes with no request data (no headers, cookies, or body).

Usage: Route GET "health" NoRequest (ok :: { body :: String })

Equivalent to: Route GET "health" {} (ok :: { body :: String })

#HandlerFn Source

type HandlerFn :: Row Type -> Row Type -> Row Type -> Type -> Row Type -> Typetype HandlerFn pathParams queryParams reqHeaders body respVariant = { body :: body, headers :: Record reqHeaders, path :: Record pathParams, query :: Record queryParams } -> Aff (Variant respVariant)

Type-safe handler tied to a route's computed types.

Usage: myHandler :: Handler (id :: Int) (limit :: Maybe Int) (authorization :: BearerToken) User (ok :: ResponseData () (Array Post), notFound :: ResponseData () ErrorMessage) myHandler { path, query, headers, body } = do -- path :: { id :: Int } -- query :: { limit :: Maybe Int } -- headers :: { authorization :: BearerToken } -- body :: User pure $ respondNoHeaders (Proxy :: _ "ok") []

Re-exports from Yoga.HTTP.API.Route.HeaderError

#HeaderError Source

data HeaderError

Typed errors for header parsing

Constructors

Instances

Re-exports from Yoga.HTTP.API.Route.HeaderValue

#HeaderValue Source

class HeaderValue a  where

Typeclass for values that can be parsed from and printed to HTTP header strings

This mirrors the ParseParam pattern from path parsing and allows headers to be typed beyond just strings.

Returns Either String for detailed error messages (the string is the reason, not the header name).

Examples: parseHeader "42" :: Either String Int = Right 42 parseHeader "bad" :: Either String Int = Left "not a valid integer" printHeader 42 = "42" parseHeader "hello" :: Either String String = Right "hello"

Members

Instances

  • HeaderValue String

    String headers are pass-through (identity)

  • HeaderValue Int

    Integer headers are parsed from strings

  • (HeaderValue a) => HeaderValue (Maybe a)

    Optional headers (Maybe a) where a has HeaderValue This instance allows headers to be optional Note: parseHeader always succeeds for Maybe types (returns Just or Nothing)

#HeaderValueType Source

class HeaderValueType (ty :: Type)  where

Get OpenAPI type string for a HeaderValue type

Members

Instances

Re-exports from Yoga.HTTP.API.Route.Method

#PUT Source

data PUT

HTTP PUT method

#POST Source

data POST

HTTP POST method

#PATCH Source

data PATCH

HTTP PATCH method

#GET Source

data GET

HTTP GET method

#DELETE Source

data DELETE

HTTP DELETE method

Re-exports from Yoga.HTTP.API.Route.OpenAPI

#ServerObject Source

type ServerObject = { description :: Maybe String, url :: String }

Type for OpenAPI server object

#OpenAPISpec Source

data OpenAPISpec

Opaque type representing a complete OpenAPI specification document.

Instances

#CollectOperations Source

class CollectOperations (routes :: Type)  where

Collect OpenAPI operations from a type-level structure of routes. Use a Record to combine multiple named routes: CollectOperations { getUser :: RouteA, createUser :: RouteB }

Members

Instances

#ToOpenAPI Source

class ToOpenAPI (route :: Type)

Generate complete OpenAPI operation object for a route Note: The instance for this typeclass is defined in Route.purs since it depends on the Route type defined there

#toOpenAPI Source

toOpenAPI :: forall @a. ToOpenAPI a => String

#buildOpenAPISpec' Source

buildOpenAPISpec' :: forall @routes. CollectOperations routes => CollectRouteSchemas routes => ValidateSchemaNames routes => OpenAPIInfoUor -> { servers :: Opt (Array ServerObject) } -> OpenAPISpec

Build a complete OpenAPI 3.0 spec with optional servers configuration.

#buildOpenAPISpec Source

buildOpenAPISpec :: forall @routes r. CollectOperations routes => CollectRouteSchemas routes => ValidateSchemaNames routes => Options r (OpenAPIInfoR UndefinedOr) => Record r -> OpenAPISpec

Re-exports from Yoga.HTTP.API.Route.OpenAPIMetadata

#Title Source

data Title :: Symbol -> Type -> Typedata Title t a

Attach a title to a type. Example: String # Title "UserName"

Instances

#Schema Source

data Schema :: Symbol -> Type -> Typedata Schema name a

Mark a type to be extracted as an OpenAPI component schema with $ref. When used in request/response bodies, generates a reference instead of inline schema.

Example: type User = { id :: Int, name :: String } Route POST path (Request { body :: JSON (Schema "User" User) }) (ok :: { body :: Schema "User" User })

Instances

#Pattern Source

data Pattern :: Symbol -> Type -> Typedata Pattern pat a

Set a regex pattern constraint. Example: String # Pattern "^[a-z]+$"

Instances

#OperationMetadata Source

type OperationMetadata = { deprecated :: Boolean, description :: Maybe String, operationId :: Maybe String, summary :: Maybe String, tags :: Array String }

#Format Source

data Format :: Symbol -> Type -> Typedata Format formatStr a

Attach a format annotation to a type. Example: String # Format "email"

Instances

#Examples Source

data Examples :: Row Type -> Type -> Typedata Examples examplesRow a

Attach multiple named examples to a type for OpenAPI documentation. This allows you to provide several example values that will appear in the generated OpenAPI spec.

Example: Int # Examples (basic :: ExampleValue "42", advanced :: ExampleValue "100")

Instances

#ExampleWithSummary Source

data ExampleWithSummary :: Symbol -> Symbol -> Typedata ExampleWithSummary value summary

An example with a summary (used in Examples row).

Example: premium :: ExampleWithSummary "456" "Premium user"

#ExampleValue Source

data ExampleValue :: Symbol -> Typedata ExampleValue value

A simple example with just a value (used in Examples row).

Example: basic :: ExampleValue "42"

#ExampleObject Source

data ExampleObject :: Symbol -> Symbol -> Symbol -> Symbol -> Typedata ExampleObject value summary description externalValue

A complete example object with value, summary, description, and optional externalValue.

Example: external :: ExampleObject "" "External example" "An example from URL" "https://example.com/data.json"

#Example Source

data Example :: Symbol -> Type -> Typedata Example exampleValue a

Attach an example value to a type. Example: Int # Example "123"

Instances

#Enum Source

data Enum a

Wrapper to use an enum type (sum type with no-argument constructors) in routes. The type parameter should be a Generic sum type, and enum values will be automatically extracted from its constructor names.

Example: data Status = Pending | Active | Completed derive instance Generic Status _

type StatusParam = Enum Status

Instances

#Description Source

data Description :: Symbol -> Type -> Typedata Description desc a

Attach a description to a type. Example: Int # Description "The unique identifier for a user"

Instances

#Default Source

data Default :: Symbol -> Type -> Typedata Default val a

Set a default value. Example: Int # Default "10"

Instances

#Callback Source

data Callback :: Type -> Symbol -> Symbol -> Type -> Type -> Row Type -> Typedata Callback inner name expression method requestBody responseRow

Define an OpenAPI callback for webhook/asynchronous API patterns. Callbacks allow you to define outgoing requests that your API will make to the client.

Parameters: inner - The wrapped type (transparent wrapper) name - The callback identifier (e.g., "onPaymentComplete") expression - The URL with runtime expressions (e.g., "{$request.body#/callbackUrl}") method - The HTTP method type for the callback (GET, POST, etc.) requestBody - The request body type for the callback responseRow - The response variants row for the callback

Example: type PaymentRoute = Route POST (Path (Lit "payment")) (Request { body :: JSON PaymentRequest }) ( ok :: { body :: PaymentResponse } ) # Callback "onPaymentComplete" "{$request.body#/callbackUrl}" POST (JSON { status :: String, transactionId :: String }) ( ok :: { body :: { received :: Boolean } } )

#GenericEnumValues Source

class GenericEnumValues rep  where

Extract enum values from a Generic sum type representation. Walks through GR.Sum constructors and collects constructor names.

Members

Instances

#HasEnum Source

class HasEnum ty  where

Members

Instances

#HasFormat Source

class HasFormat ty  where

Members

Instances

#HasOperationMetadata Source

class HasOperationMetadata route  where

Members

Instances

#HasTitle Source

class HasTitle ty  where

Members

Instances

Re-exports from Yoga.HTTP.API.Route.Response

#ResponseData Source

type ResponseData :: Row Type -> Type -> Typetype ResponseData headers body = Response headers body

Deprecated alias for backwards compatibility

#Response Source

data Response :: Row Type -> Type -> Typedata Response headers body

Response data combining headers and body This is a data type (not type alias) to work with type class instances

Constructors

Instances

#respondWith Source

respondWith :: forall label headers body r1 r2. IsSymbol label => Cons label (Response headers body) r1 r2 => Proxy label -> Record headers -> body -> Variant r2

Construct a variant response with separate headers and body arguments

Example: respondWith (Proxy :: _ "created") { "Location": "/users/123" } user

#respondNoHeaders Source

respondNoHeaders :: forall @label body r1 r2. IsSymbol label => Cons label (Response () body) r1 r2 => body -> Variant r2

Construct a variant response with no custom headers (most common case)

Example: respondNoHeaders (Proxy :: _ "ok") user respondNoHeaders (Proxy :: _ "notFound") { error: "Not found" }

Re-exports from Yoga.HTTP.API.Route.Route

#Route Source

data Route :: forall k. Type -> k -> Type -> Row Type -> Typedata Route method segments request respVariant

Constructors

Instances

#ConvertResponseVariant Source

class ConvertResponseVariant :: Row Type -> Row Type -> Constraintclass ConvertResponseVariant (userRow :: Row Type) (internalRow :: Row Type) | userRow -> internalRow

Convert a variant row with record syntax to Response types. Input: ( ok :: { body :: User }, notFound :: { body :: ErrorMsg } ) Output: ( ok :: Response () User, notFound :: Response () ErrorMsg )

Instances

#ConvertResponseVariantRL Source

class ConvertResponseVariantRL :: RowList Type -> Row Type -> Row Type -> Constraintclass ConvertResponseVariantRL (rl :: RowList Type) (acc :: Row Type) (out :: Row Type) | rl acc -> out

Instances

Re-exports from Yoga.HTTP.API.Route.RouteHandler

#Handler Source

data Handler t0

A handler tied to a specific route type.

Usage: userHandler :: Handler UserRoute userHandler = mkHandler { path } -> ...

#APIHandlers Source

class APIHandlers :: RowList Type -> Row Type -> Constraintclass APIHandlers (rl :: RowList Type) (handlerRow :: Row Type) | rl -> handlerRow

Instances

#ApiRecord Source

class ApiRecord :: Type -> Row Type -> Constraintclass ApiRecord (api :: Type) (row :: Row Type) | api -> row

Instances

#RouteHandler Source

class RouteHandler :: Type -> Row Type -> Row Type -> Row Type -> Type -> Row Type -> Constraintclass RouteHandler (route :: Type) (pathParams :: Row Type) (queryParams :: Row Type) (reqHeaders :: Row Type) (body :: Type) (respVariant :: Row Type) | route -> pathParams queryParams reqHeaders body respVariant

Type class that computes the handler function type from a Route type.

Instances

#runHandler Source

runHandler :: forall route pathParams queryParams reqHeaders body respVariant. RouteHandler route pathParams queryParams reqHeaders body respVariant => Handler route -> HandlerFn pathParams queryParams reqHeaders body respVariant

Extract the handler function from a Handler.

#mkHandler Source

mkHandler :: forall route pathParams queryParams reqHeaders body respVariant. RouteHandler route pathParams queryParams reqHeaders body respVariant => HandlerFn pathParams queryParams reqHeaders body respVariant -> Handler route

Create a Handler from a function matching the route's type.

#apiHandlers Source

apiHandlers :: forall @api apiRow rl handlerRow. ApiRecord api apiRow => RowToList apiRow rl => APIHandlers rl handlerRow => Record handlerRow -> Record handlerRow

Re-exports from Yoga.HTTP.API.Route.StatusCode

#StatusCodeMap Source

class StatusCodeMap :: Symbol -> Constraintclass StatusCodeMap (sym :: Symbol)  where

Map variant constructor names (Symbols) to HTTP status codes

Members

Instances

#statusCodeToString Source

statusCodeToString :: StatusCode -> String

Convert StatusCode to String for OpenAPI generation

Re-exports from Yoga.Options

#UndefinedOr Source

type UndefinedOr a = OneOf Undefined a

#Options Source

class Options :: Row Type -> Row Type -> Constraintclass Options given full

Instances

#withUor Source

withUor :: forall a b. (a -> b) -> UndefinedOr a -> UndefinedOr b

#uorToMaybe Source

uorToMaybe :: forall a. UndefinedOr a -> Maybe a

#options Source

options :: forall @full given. Options given full => Record given -> Record full

#nullishCoalesce Source

nullishCoalesce :: forall a. UndefinedOr a -> a -> a

#fromUndefinedOr Source

fromUndefinedOr :: forall a. a -> UndefinedOr a -> a

#defined Source

defined :: forall a. a -> UndefinedOr a

#(??) Source

Operator alias for Yoga.Options.nullishCoalesce (left-associative / precedence 9)

Modules
Yoga.HTTP.API.Path
Yoga.HTTP.API.Route
Yoga.HTTP.API.Route.Auth
Yoga.HTTP.API.Route.BearerToken
Yoga.HTTP.API.Route.Encoding
Yoga.HTTP.API.Route.Handler
Yoga.HTTP.API.Route.HeaderError
Yoga.HTTP.API.Route.HeaderValue
Yoga.HTTP.API.Route.Method
Yoga.HTTP.API.Route.OpenAPI
Yoga.HTTP.API.Route.OpenAPIMetadata
Yoga.HTTP.API.Route.RenderMethod
Yoga.HTTP.API.Route.Response
Yoga.HTTP.API.Route.Route
Yoga.HTTP.API.Route.RouteHandler
Yoga.HTTP.API.Route.StatusCode