TypeScript API Reference

TypeScript API Reference v0.15.6-rc.22¶

Functions¶

schemaQueryOnly()¶

Create a simple schema configuration with only Query type.

This is a convenience function for schemas that only have queries.

Returns:

A QueryOnlyConfig with default settings

Signature:

function schemaQueryOnly(): QueryOnlyConfig

Returns: QueryOnlyConfig

schemaQueryMutation()¶

Create a schema configuration with Query and Mutation types.

This is a convenience function for schemas with queries and mutations but no subscriptions.

Returns:

A QueryMutationConfig with default settings

Signature:

function schemaQueryMutation(): QueryMutationConfig

Returns: QueryMutationConfig

schemaFull()¶

Create a schema configuration with all three root types.

This is a convenience function for fully-featured schemas.

Returns:

A FullSchemaConfig with default settings

Signature:

function schemaFull(): FullSchemaConfig

Returns: FullSchemaConfig

Types¶

ApiKeyConfig¶

API Key authentication configuration

App¶

Spikard application builder.

Methods¶

new()¶

Create a new application with the default server configuration.

Signature:

static new(): App

mergeAxumRouter()¶

Attach an existing Axum router to this application, returning ownership.

Signature:

mergeAxumRouter(router: string): App

attachAxumRouter()¶

Attach an Axum router using a mutable reference for incremental configuration.

Signature:

attachAxumRouter(router: string): App

intoRouter()¶

Build the underlying Axum router.

Errors:

Returns an error if server or router construction fails.

Signature:

intoRouter(): string

intoRouterAndConfig()¶

Decompose the application into its Axum router and server configuration.

This is the low-level escape hatch used by the C FFI layer to start the server on a background thread while retaining the bind address from the caller-supplied ServerConfig. Prefer App.run for normal use.

Errors:

Returns an error if router construction fails.

Signature:

intoRouterAndConfig(): string

default()¶

Signature:

static default(): App

AsyncApiConfig¶

AsyncAPI HTTP endpoint configuration

BackgroundJobMetadata¶

Methods¶

default()¶

Signature:

static default(): BackgroundJobMetadata

BackgroundTaskConfig¶

Configuration for in-process background task execution.

Methods¶

default()¶

Signature:

static default(): BackgroundTaskConfig

CompressionConfig¶

Compression configuration shared across runtimes

Methods¶

default()¶

Signature:

static default(): CompressionConfig

ContactInfo¶

Contact information

CorsConfig¶

CORS configuration for a route

Methods¶

allowedMethodsJoined()¶

Get the cached joined methods string for preflight responses

Signature:

allowedMethodsJoined(): string

allowedHeadersJoined()¶

Get the cached joined headers string for preflight responses

Signature:

allowedHeadersJoined(): string

isOriginAllowed()¶

Check if an origin is allowed (O(1) with wildcard, O(n) for exact match)

Signature:

isOriginAllowed(origin: string): boolean

isMethodAllowed()¶

Check if a method is allowed (O(1) with wildcard, O(n) for exact match)

Signature:

isMethodAllowed(method: string): boolean

default()¶

Signature:

static default(): CorsConfig

FullSchemaConfig¶

Configuration for fully-featured schemas with Query, Mutation, and Subscription types

Methods¶

default()¶

Signature:

static default(): FullSchemaConfig

GraphQlRouteConfig¶

Configuration for GraphQL routes

Provides a builder pattern for configuring GraphQL route parameters for the Spikard HTTP server's routing system.

Methods¶

new()¶

Create a new GraphQL route configuration with defaults

Default values:

• path: "/graphql"
• method: "POST"
• enable_playground: false

Signature:

static new(): GraphQlRouteConfig

path()¶

Set the HTTP path for the GraphQL endpoint

Signature:

path(path: string): GraphQlRouteConfig

method()¶

Set the HTTP method for the GraphQL endpoint

Signature:

method(method: string): GraphQlRouteConfig

enablePlayground()¶

Enable or disable the GraphQL Playground UI

Signature:

enablePlayground(enable: boolean): GraphQlRouteConfig

description()¶

Set a custom description for documentation

Signature:

description(description: string): GraphQlRouteConfig

getPath()¶

Get the configured path

Signature:

getPath(): string

getMethod()¶

Get the configured method

Signature:

getMethod(): string

isPlaygroundEnabled()¶

Check if playground is enabled

Signature:

isPlaygroundEnabled(): boolean

getDescription()¶

Get the description if set

Signature:

getDescription(): string | null

default()¶

Signature:

static default(): GraphQlRouteConfig

GraphQlSubscriptionSnapshot¶

Snapshot of a GraphQL subscription exchange over WebSocket.

GrpcConfig¶

Configuration for gRPC support

Controls how the server handles gRPC requests, including compression, timeouts, and protocol settings.

Stream Limits¶

This configuration enforces message-level size limits but delegates concurrent stream limiting to the HTTP/2 transport layer:

• Message Size Limits: The max_message_size field is enforced per individual message (request or response) in both unary and streaming RPCs. When a single message exceeds this limit, the request is rejected with PAYLOAD_TOO_LARGE (HTTP 413).

• Concurrent Stream Limits: The max_concurrent_streams is an advisory configuration passed to the HTTP/2 layer for connection-level stream negotiation. The HTTP/2 transport automatically enforces this limit and returns GOAWAY frames when exceeded. Applications should not rely on custom enforcement of this limit.

• Stream Response Size Limits: The max_stream_response_bytes field caps the total encoded bytes emitted across a server-streaming or bidi-streaming response. When the cumulative size exceeds the limit, the stream is terminated with tonic.Status.resource_exhausted. Defaults to null (unbounded).

Methods¶

default()¶

Signature:

static default(): GrpcConfig

Handler¶

Handler trait that all language bindings must implement

This trait is completely language-agnostic. Each binding (Python, Node, WASM) implements this trait to bridge their runtime to our HTTP server.

Methods¶

call()¶

Handle an HTTP request

Takes the extracted request data and returns a future that resolves to either:

• Ok(Response): A successful HTTP response
• Err((StatusCode, String)): An error with status code and message

Signature:

call(request: Request, requestData: RequestData): HandlerResult

prefersRawJsonBody()¶

Whether this handler prefers consuming RequestData.raw_body over the parsed RequestData.body for JSON requests.

When true, the server may skip eager JSON parsing when there is no request-body schema validator attached to the route.

Signature:

prefersRawJsonBody(): boolean

prefersParameterExtraction()¶

Whether this handler wants to perform its own parameter validation/extraction (path/query/header/cookie).

When true, the server will skip ParameterValidator.validate_and_extract in ValidatingHandler. This is useful for language bindings which need to transform validated parameters into language-specific values (e.g., Python kwargs) without duplicating work. When false, the server stores validated output in RequestData.validated_params.

Signature:

prefersParameterExtraction(): boolean

wantsHeaders()¶

Whether this handler needs the parsed headers map in RequestData.

When false, the server may skip building RequestData.headers for requests without a body. (Requests with bodies still typically need Content-Type decisions.)

Signature:

wantsHeaders(): boolean

wantsCookies()¶

Whether this handler needs the parsed cookies map in RequestData.

When false, the server may skip parsing cookies for requests without a body.

Signature:

wantsCookies(): boolean

wantsRequestExtensions()¶

Whether this handler needs RequestData stored in request extensions.

When false, the server avoids inserting RequestData into extensions to skip cloning in hot paths.

Signature:

wantsRequestExtensions(): boolean

staticResponse()¶

Return a pre-built static response if this handler always produces the same output. When Some, the server bypasses the full middleware pipeline and serves the pre-built response directly.

Signature:

staticResponse(): StaticResponse | null

IntoHandler¶

Convert user-facing handler functions into the low-level Handler trait.

Methods¶

intoHandler()¶

Convert this value into a shared request handler.

Signature:

intoHandler(): Handler

JsonRpcConfig¶

JSON-RPC server configuration

Methods¶

default()¶

Signature:

static default(): JsonRpcConfig

JsonRpcMethodInfo¶

JSON-RPC method metadata for routes that support JSON-RPC

This struct captures the metadata needed to expose HTTP routes as JSON-RPC methods, enabling discovery and documentation of RPC-compatible endpoints.

JwtConfig¶

JWT authentication configuration

LicenseInfo¶

License information

OpenApiConfig¶

OpenAPI configuration

Methods¶

default()¶

Signature:

static default(): OpenApiConfig

ParseRequest¶

Request body for POST /asyncapi/parse

ParseResult¶

Full parse result returned by POST /asyncapi/parse

ParsedChannel¶

A single channel extracted from an AsyncAPI spec

ParsedMessage¶

A resolved message (name + JSON Schema)

ParsedOperation¶

A single operation extracted from an AsyncAPI spec

ProblemDetails¶

RFC 9457 Problem Details for HTTP APIs

A machine-readable format for specifying errors in HTTP API responses. Per RFC 9457, all fields are optional. The type field defaults to "about:blank" if not specified.

Content-Type¶

Responses using this struct should set:

Content-Type: application/problem+json

{
  "type": "<https://spikard.dev/errors/validation-error",>
  "title": "Request Validation Failed",
  "status": 422,
  "detail": "2 validation errors in request body",
  "errors": [...]
}

Methods¶

withDetail()¶

Set the detail field

Signature:

withDetail(detail: string): ProblemDetails

withInstance()¶

Set the instance field

Signature:

withInstance(instance: string): ProblemDetails

notFound()¶

Create a not found error

Signature:

static notFound(detail: string): ProblemDetails

methodNotAllowed()¶

Create a method not allowed error

Signature:

static methodNotAllowed(detail: string): ProblemDetails

internalServerError()¶

Create an internal server error

Signature:

static internalServerError(detail: string): ProblemDetails

badRequest()¶

Create a bad request error

Signature:

static badRequest(detail: string): ProblemDetails

toJson()¶

Serialize to JSON string

Errors: Returns an error if the serialization fails.

Signature:

toJson(): string

toJsonPretty()¶

Serialize to pretty JSON string

Errors: Returns an error if the serialization fails.

Signature:

toJsonPretty(): string

QueryMutationConfig¶

Configuration for schemas with Query and Mutation types

Methods¶

default()¶

Signature:

static default(): QueryMutationConfig

QueryOnlyConfig¶

Configuration for schemas with only Query type

Methods¶

default()¶

Signature:

static default(): QueryOnlyConfig

RateLimitConfig¶

Rate limiting configuration shared across runtimes

Methods¶

default()¶

Signature:

static default(): RateLimitConfig

Request¶

Response¶

HTTP Response with custom status code, headers, and content

Methods¶

setHeader()¶

Set a header

Signature:

setHeader(key: string, value: string): void

setCookie()¶

Set a cookie in the response

Signature:

setCookie(key: string, value: string, secure: boolean, httpOnly: boolean, maxAge: number, domain: string, path: string, sameSite: string): void

default()¶

Signature:

static default(): Response

ResponseSnapshot¶

Snapshot of an Axum response used by higher-level language bindings.

Methods¶

text()¶

Return response body as UTF-8 string.

Signature:

text(): string

header()¶

Lookup header by case-insensitive name.

Signature:

header(name: string): string | null

RouteBuilder¶

Builder for defining a route.

Methods¶

new()¶

Create a new builder for the provided HTTP method and path.

Signature:

static new(method: Method, path: string): RouteBuilder

handlerName()¶

Assign an explicit handler name.

Signature:

handlerName(name: string): RouteBuilder

requestSchemaJson()¶

Provide a raw JSON schema for the request body.

Signature:

requestSchemaJson(schema: unknown): RouteBuilder

responseSchemaJson()¶

Provide a raw JSON schema for the response body.

Signature:

responseSchemaJson(schema: unknown): RouteBuilder

paramsSchemaJson()¶

Provide a raw JSON schema for request parameters.

Signature:

paramsSchemaJson(schema: unknown): RouteBuilder

fileParamsJson()¶

Provide multipart file parameter configuration.

Signature:

fileParamsJson(schema: unknown): RouteBuilder

cors()¶

Attach a CORS configuration for this route.

Signature:

cors(cors: CorsConfig): RouteBuilder

compression()¶

Attach a compression configuration for this route.

Signature:

compression(compression: CompressionConfig): RouteBuilder

sync()¶

Mark the route as synchronous.

Signature:

sync(): RouteBuilder

handlerDependencies()¶

Declare the dependency keys that must be resolved before this handler runs.

Signature:

handlerDependencies(dependencies: Array<string>): RouteBuilder

SchemaConfig¶

Configuration for GraphQL schema building.

Encapsulates all schema-level configuration options including introspection control, complexity limits, and depth limits.

Methods¶

default()¶

Signature:

static default(): SchemaConfig

ServerConfig¶

Server configuration

Methods¶

default()¶

Signature:

static default(): ServerConfig

ServerInfo¶

Server information

SseEvent¶

An individual SSE event

Represents a single Server-Sent Event to be sent to a connected client. Events can have an optional type, ID, and retry timeout for advanced scenarios.

SSE Format¶

Events are serialized to the following text format:

event: event_type
data: {"json":"value"}
id: event-123
retry: 3000

Methods¶

withId()¶

Set the event ID for client-side reconnection support

Sets an ID that clients can use to resume from this point if they disconnect. The client sends this ID back in the Last-Event-ID header when reconnecting.

Signature:

withId(id: string): SseEvent

withRetry()¶

Set the retry timeout for client reconnection

Sets the time in milliseconds clients should wait before attempting to reconnect if the connection is lost. The client browser will automatically handle reconnection.

Signature:

withRetry(retryMs: number): SseEvent

StaticFilesConfig¶

Static file serving configuration

TestClient¶

Core test client for making HTTP requests to a Spikard application.

This struct wraps axum-test's TestServer and provides a language-agnostic interface for making HTTP requests, sending WebSocket connections, and handling Server-Sent Events. Language bindings wrap this to provide native API surfaces.

Methods¶

graphqlAt()¶

Send a GraphQL query/mutation to a custom endpoint

Signature:

graphqlAt(endpoint: string, query: string, variables: unknown, operationName: string): ResponseSnapshot

graphql()¶

Send a GraphQL query/mutation

Signature:

graphql(query: string, variables: unknown, operationName: string): ResponseSnapshot

graphqlSubscriptionAt()¶

Send a GraphQL subscription (WebSocket) to a custom endpoint.

Uses the graphql-transport-ws protocol and captures the first next payload. After the first payload is received, this client sends complete to unsubscribe.

Signature:

graphqlSubscriptionAt(endpoint: string, query: string, variables: unknown, operationName: string): GraphQlSubscriptionSnapshot

graphqlSubscription()¶

Send a GraphQL subscription (WebSocket).

Uses /graphql as the default subscription endpoint.

Signature:

graphqlSubscription(query: string, variables: unknown, operationName: string): GraphQlSubscriptionSnapshot

TestingSseEvent¶

A single Server-Sent Event.

UploadFile¶

Represents an uploaded file from multipart/form-data requests.

This struct provides efficient access to file content with automatic base64 decoding and implements standard I/O traits for compatibility.

Methods¶

asBytes()¶

Get the raw file content as bytes.

This provides zero-copy access to the underlying buffer.

Signature:

asBytes(): Buffer

readToString()¶

Read the file content as a UTF-8 string.

Errors:

Returns an error if the content is not valid UTF-8.

Signature:

readToString(): string

contentTypeOrDefault()¶

Get the content type, defaulting to "application/octet-stream".

Signature:

contentTypeOrDefault(): string

ValidateRequest¶

Request body for POST /asyncapi/validate

ValidationResponse¶

Response body for POST /asyncapi/validate

Enums¶

Method¶

HTTP method

SecuritySchemeInfo¶

Security scheme types

SnapshotError¶

Possible errors while converting an Axum response into a snapshot.

WebSocketMessage¶

A WebSocket message that can be text or binary.

Errors¶

AppError¶

Error type for application builder operations.

Errors are thrown as plain Error objects with descriptive messages.

GraphQlError¶

Errors that can occur during GraphQL operations

These errors are compatible with async-graphql error handling and can be converted to structured HTTP responses matching the project's error fixtures.

Errors are thrown as plain Error objects with descriptive messages.

SchemaError¶

Error type for schema building operations

Errors are thrown as plain Error objects with descriptive messages.

Edit this page on GitHub