ArctonArcton
Architecture

Runtime Abstraction

Why the runtime types live in their own package, and what that buys the core, the adapters and your application.

@arcton/contracts contains types and nothing else. No functions, no classes, no runtime code at all. Every other package depends on it, and it depends on nothing.

@arcton/core ──┐
               ├──→ @arcton/contracts
@arcton/adapter-bun ──┤
@arcton/adapter-node ─┤
@arcton/cors ─────────┘

Why a separate package

The core needs to describe what it expects from a runtime. An adapter needs to implement exactly that. If either side owned the description, the other would have to depend on it — and an adapter depending on the core, or the core depending on every adapter, is a cycle waiting to happen.

Putting the vocabulary in a package that depends on nothing breaks the cycle. The core is written against RuntimeAdapter, each adapter implements RuntimeAdapter, and neither knows the other exists. That is what makes the default adapter swappable by passing one option.

It has a second effect: because the package holds only types, it disappears at build time. Depending on the shared vocabulary costs nothing at runtime.

What lives there

Two groups of types.

The runtime contract — RuntimeAdapter, RuntimeServer, RuntimeServeOptions, RuntimeHandler, RuntimeCapabilities, RuntimeRequestContext, and the WebSocket types. These describe a server, and they are what an adapter implements.

The application vocabulary — Context, Middleware, RouteHandler, NextFunction, ProvideFn, BodyParser, Body, HttpMethod, StandardSchemaV1 and friends. These describe the things your code writes.

Both groups sit in the same package because both are shared: @arcton/cors needs Middleware and Context without needing the core, and so does any middleware you publish yourself.

Why the web platform is the interface

The contract is built on Request, Response, Headers and ReadableStream rather than on an Arcton-specific request object.

Those types already exist in every target runtime, they are specified independently, and developers already know them. A framework-specific wrapper would add a layer to learn, a layer to keep in sync with the platform, and a conversion at every boundary — in exchange for very little. So ctx.request is a real Request, and everything you know about the Fetch API applies.

The one place Arcton adds its own shape is the response, where ctx.response holds a status and headers that are still mutable. A real Response is immutable in the ways middleware needs to change, so the pipeline keeps a mutable staging object and materializes it — see Pipeline.

Standard Schema, for the same reason

Validation follows the same principle. Rather than shipping a validator or depending on one, Arcton accepts any schema implementing Standard Schema — the interface Zod, Valibot and ArkType all implement.

The framework never imports a validation library, users are not forced onto the maintainer's favorite, and a project already using one keeps using it. The interface is small enough that StandardSchemaV1 is declared in contracts alongside everything else, so even that is not a dependency.

What this means for your code

Typing a standalone middleware or handler means importing from contracts:

import type { Middleware } from '@arcton/contracts'

export const requestId: Middleware = async (ctx, next) => {
  ctx.response.headers.set('X-Request-Id', crypto.randomUUID())
  await next()
}

Since the package is types-only, that import vanishes from the build output.

On this page