Warning: VibeLang is v0. The language will change in major, breaking ways. It is not suitable for production use.

Building an HTTP API

Build routes with Effect's HTTP modules and write each handler as a VibeLang function. This example creates users, validates JSON bodies, and maps expected failures to HTTP status codes.

Define the body and the service

VibeLang

// users.vibe
// run: provide UsersLive { Console.log(JSON.stringify(Users.create("Ada"))); const repeated = Effect.result(Users.create("Ada")); if (repeated.isFailure()) Console.log(repeated.failure.name) }
export schema CreateUserconst CreateUser: Struct<{
    readonly name: String;
}> { name(property) name: String: string }
export errorclass NameTaken NameTakenclass NameTaken { name(property) name: string: string }

export serviceabstract class Users Usersabstract class Users {
  create(method) Users.create(name: string): {
    readonly id: string;
    readonly name: string;
}!NameTaken!(name(parameter) name: string: string): { id(property) id: string: string; name(property) name: string: string }!NameTakenclass NameTaken
}

export const UsersLiveconst UsersLive: Layer<Users, never, never>Layer: provides Users; needs nothing. = Layer(alias) module "effect/Layer".effectconst effect: <Users, {
    create(name: string): {
        id: string;
        name: string;
    }!NameTaken!;
}, never, never>(service: Key<Users, {
    create(name: string): {
        id: string;
        name: string;
    }!NameTaken!;
}>, effect: {
    create(name: string): {
        id: string;
        name: string;
    }!NameTaken!;
}!!) => Layer<Users, never, never>Constructs a layer from an effect that produces a single service.(Usersabstract class Users) {
  const namesconst names: Set<string> = new Setvar Set: new <string>(iterable?: Iterable<string> | null | undefined) => Set<string><string>()
  let nextIdlet nextId: number = 0
  return {
    create(method) create(name: string): {
    id: string;
    name: string;
}!NameTaken!(name(parameter) name: string) {
      if (namesconst names: Set<string>.has(method) Set<string>.has(value: string): boolean(name(parameter) name: string)) throw new NameTakenconstructor NameTaken<{
    readonly name: string;
}>(args: {
    readonly name: string;
}): NameTaken({ name(property) name: string })
      namesconst names: Set<string>.add(method) Set<string>.add(value: string): Set<string>Appends a new element with a specified value to the end of the Set.(name(parameter) name: string)
      nextIdlet nextId: number++
      return { id(property) id: string: Stringvar String: (value?: any) => stringAllows manipulation and formatting of text strings and determination and location of substrings within strings.(nextIdlet nextId: number), name(property) name: string }
    }
  }
}
// Output: {"id":"1","name":"Ada"}
// Output: Ada

Types in this example

CreateUser: const CreateUser: Struct<{ readonly name: String; }>
name: (property) name: String
error: class NameTaken
NameTaken: class NameTaken
name: (property) name: string
service: abstract class Users
Users: abstract class Users
create: (method) Users.create(name: string): { readonly id: string; readonly name: string; }!NameTaken!
name: (parameter) name: string
id: (property) id: string
UsersLive: const UsersLive: Layer<Users, never, never>Layer: provides Users; needs nothing.
Layer: (alias) module "effect/Layer"
effect: const effect: <Users, { create(name: string): { id: string; name: string; }!NameTaken!; }, never, never>(service: Key<Users, { create(name: string): { id: string; name: string; }!NameTaken!; }>, effect: { create(name: string): { id: string; name: string; }!NameTaken!; }!!) => Layer<Users, never, never>Constructs a layer from an effect that produces a single service.
names: const names: Set<string>
Set: var Set: new <string>(iterable?: Iterable<string> | null | undefined) => Set<string>
nextId: let nextId: number
create: (method) create(name: string): { id: string; name: string; }!NameTaken!
has: (method) Set<string>.has(value: string): boolean
NameTaken: constructor NameTaken<{ readonly name: string; }>(args: { readonly name: string; }): NameTaken
add: (method) Set<string>.add(value: string): Set<string>Appends a new element with a specified value to the end of the Set.
String: var String: (value?: any) => stringAllows manipulation and formatting of text strings and determination and location of substrings within strings.

schema CreateUser { name: string } declares a struct schema and its type: it accepts a JSON object with a string name. Users.create declares NameTaken as an expected failure. The layer owns the set of names and the ID counter, so each layer build starts with isolated state.

Decode the request and map failures

VibeLang

// routes.vibe
// run: Effect.scoped { const app = HttpRouter.toHttpEffect(App); const statuses: number[] = []; for (const body of [{ name: "Ada" }, { name: "Ada" }, { name: 123 }]) { const request = HttpServerRequest.fromClientRequest(HttpClientRequest.bodyJson(HttpClientRequest.post("http://local/users"), body)); statuses.push(Effect.provideService(app, HttpServerRequest.HttpServerRequest, request).status) }; Console.log(JSON.stringify(statuses)) }
import { HttpClientRequest(alias) module "effect/http/HttpClientRequest", HttpRouter(alias) module "effect/http/HttpRouter", HttpServerRequest(alias) module "effect/http/HttpServerRequest", HttpServerResponse(alias) module "effect/http/HttpServerResponse" } from "effect/http"
import { CreateUser(alias) const CreateUser: Struct<{
    readonly name: String;
}>
(alias) interface CreateUser, NameTaken(alias) class NameTaken, Users(alias) abstract class Users, UsersLive(alias) const UsersLive: Layer<Users, never, never>Layer: provides Users; needs nothing. } from "./users.vibe"

export function createUserfunction createUser(): HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Users() {
  try {
    const inputconst input: {
    readonly name: string;
} = HttpServerRequest(alias) module "effect/http/HttpServerRequest".schemaBodyJsonconst schemaBodyJson: <{
    readonly name: string;
}, never>(schema: ConstraintDecoder<{
    readonly name: string;
}, never>, options?: (ParseOptions & JsonOptions) | undefined) => {
    readonly name: string;
}!HttpServerError | SchemaError!HttpServerRequest.HttpServerRequestRuns here and returns { readonly name: string; }.Reads the current request body as JSON and decodes it with the supplied schema.(CreateUser(alias) const CreateUser: Struct<{
    readonly name: String;
}>)
    const userconst user: {
    readonly id: string;
    readonly name: string;
} = Users(alias) abstract class Users.create(method) Users.create(name: string): {
    readonly id: string;
    readonly name: string;
}!NameTaken!Runs here and returns { readonly id: string; readonly name: string; }.(inputconst input: {
    readonly name: string;
}.name(property) name: string)
    return HttpServerResponse(alias) module "effect/http/HttpServerResponse".jsonconst json: (body: unknown, options?: HttpServerResponse.Options.WithContentType | undefined) => HttpServerResponse.HttpServerResponse!HttpBodyError!Runs here and returns HttpServerResponse.HttpServerResponse.Creates a JSON HTTP response.(userconst user: {
    readonly id: string;
    readonly name: string;
}, { status(property) status?: number | undefined: 201 })
  } catch (errorvar error: HttpBodyError | HttpServerError | NameTaken | SchemaError) {
    return match (error) {
      when NameTaken(alias) class NameTaken: HttpServerResponse(alias) module "effect/http/HttpServerResponse".textconst text: (body: string, options?: HttpServerResponse.Options.WithContentType) => HttpServerResponse.HttpServerResponseCreates an HTTP response whose body is a string.(`Name already registered: ${errorvar error: NameTaken.name(property) Error.name: string}`, { status(property) status?: number | undefined: 409 });
      when Schema(alias) module "effect/Schema".SchemaError: HttpServerResponse(alias) module "effect/http/HttpServerResponse".textconst text: (body: string, options?: HttpServerResponse.Options.WithContentType) => HttpServerResponse.HttpServerResponseCreates an HTTP response whose body is a string.("Expected a JSON object with a string name", { status(property) status?: number | undefined: 400 });
      default: throw errorvar error: HttpBodyError | HttpServerError;
    }
  }
}

export const Routesconst Routes: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError> | HttpRouter.Request<"Requires", Users>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError> and Request<"Requires", Users>. = HttpRouter(alias) module "effect/http/HttpRouter".addconst add: <HttpBodyError | HttpServerError, HttpServerRequest.HttpServerRequest | Users>(method: "*" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY", path: HttpRouter.PathInput, handler: (HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Users) | HttpServerResponse.HttpServerResponse | ..., options?: {
    readonly uninterruptible?: boolean | undefined;
}) => Layer<...>Create a layer that adds a single route to the HTTP router.("POST", "/users", createUserfunction createUser(): HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Users())
export const Appconst App: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError>. = HttpRouter(alias) module "effect/http/HttpRouter".provideRequestconst provideRequest: <Users, never, never>(layer: Layer<Users, never, never>) => <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, Exclude<R, HttpRouter.Request<"Requires", Users>>>Provides request-level dependencies to some routes.(UsersLive(alias) const UsersLive: Layer<Users, never, never>Layer: provides Users; needs nothing.)(Routesconst Routes: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError> | HttpRouter.Request<"Requires", Users>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError> and Request<"Requires", Users>.)
// Output: [201,409,400]

Types in this example

HttpClientRequest: (alias) module "effect/http/HttpClientRequest"
HttpRouter: (alias) module "effect/http/HttpRouter"
HttpServerRequest: (alias) module "effect/http/HttpServerRequest"
HttpServerResponse: (alias) module "effect/http/HttpServerResponse"
CreateUser: (alias) const CreateUser: Struct<{ readonly name: String; }> (alias) interface CreateUser
NameTaken: (alias) class NameTaken
Users: (alias) abstract class Users
UsersLive: (alias) const UsersLive: Layer<Users, never, never>Layer: provides Users; needs nothing.
createUser: function createUser(): HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Users
input: const input: { readonly name: string; }
schemaBodyJson: const schemaBodyJson: <{ readonly name: string; }, never>(schema: ConstraintDecoder<{ readonly name: string; }, never>, options?: (ParseOptions & JsonOptions) | undefined) => { readonly name: string; }!HttpServerError | SchemaError!HttpServerRequest.HttpServerRequestRuns here and returns { readonly name: string; }.Reads the current request body as JSON and decodes it with the supplied schema.
CreateUser: (alias) const CreateUser: Struct<{ readonly name: String; }>
user: const user: { readonly id: string; readonly name: string; }
create: (method) Users.create(name: string): { readonly id: string; readonly name: string; }!NameTaken!Runs here and returns { readonly id: string; readonly name: string; }.
name: (property) name: string
json: const json: (body: unknown, options?: HttpServerResponse.Options.WithContentType | undefined) => HttpServerResponse.HttpServerResponse!HttpBodyError!Runs here and returns HttpServerResponse.HttpServerResponse.Creates a JSON HTTP response.
status: (property) status?: number | undefined
error: var error: HttpBodyError | HttpServerError | NameTaken | SchemaError
text: const text: (body: string, options?: HttpServerResponse.Options.WithContentType) => HttpServerResponse.HttpServerResponseCreates an HTTP response whose body is a string.
error: var error: NameTaken
name: (property) Error.name: string
Schema: (alias) module "effect/Schema"
error: var error: HttpBodyError | HttpServerError
Routes: const Routes: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError> | HttpRouter.Request<"Requires", Users>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError> and Request<"Requires", Users>.
add: const add: <HttpBodyError | HttpServerError, HttpServerRequest.HttpServerRequest | Users>(method: "*" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY", path: HttpRouter.PathInput, handler: (HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Users) | HttpServerResponse.HttpServerResponse | ..., options?: { readonly uninterruptible?: boolean | undefined; }) => Layer<...>Create a layer that adds a single route to the HTTP router.
App: const App: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError>.
provideRequest: const provideRequest: <Users, never, never>(layer: Layer<Users, never, never>) => <A, E, R>(self: Layer<A, E, R>) => Layer<A, E, Exclude<R, HttpRouter.Request<"Requires", Users>>>Provides request-level dependencies to some routes.

The JSON decoder runs at the call and returns the validated body. Users.create runs next, and the response is JSON with status 201. A repeated name becomes 409; a body that fails the schema becomes 400. The match handles each error class it names, and default: throw error passes any other failure on to the HTTP boundary.

catch sees expected failures only. It does not catch defects or interruption. Keep error-to-status mapping explicit so a programming defect cannot become a successful response.

HttpRouter.add receives createUser() by name, as a program that runs on each request. HttpRouter.provideRequest supplies Users to route execution. Calling HttpRouter.toHttpEffect in a test will therefore use the same service implementation as the server.

Start the Node server

VibeLang

// server.vibe
// run: provide Logger.layer([]) { Effect.scoped { Layer.build(server(0)); Console.log("server acquired") }; Console.log("server released") }
import { HttpRouter(alias) module "effect/http/HttpRouter" } from "effect/http"
import { NodeHttpServer(alias) module "@effect/platform-node/NodeHttpServer" } from "@effect/platform-node"
import { createServer(alias) function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(requestListener?: RequestListener<Request, Response>): Server<Request, Response>
(alias) function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(options: ServerOptions<Request, Response>, requestListener?: RequestListener<Request, Response>): Server<Request, Response>Returns a new instance of Server. } from "node:http"
import { App(alias) const App: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError>. } from "./routes.vibe"

functionfunction server(port: number): Layer<never, ServeError, never>!! serverfunction server(port: number): Layer<never, ServeError, never>Plain JavaScript: VibeLang code calls it directly. TypeScript callers see Effect<Layer<never, ServeError, never>, never, never>.(port(parameter) port: number: number) {
  const Serverconst Server: Layer<Generator | HttpPlatform | HttpServer | NodeServices, ServeError, never>Layer: provides ChildProcessSpawner and Crypto and FileSystem and Generator and HttpPlatform and HttpServer and Path and Stdio and Terminal; needs nothing; fails with ServeError. = NodeHttpServer(alias) module "@effect/platform-node/NodeHttpServer".layerconst layer: (evaluate: LazyArg<Server>, options: NodeHttpServer.Options) => Layer.Layer<HttpServer | NodeServices | HttpPlatform | Generator, ServeError>Provides a Node HttpServer together with the Node HTTP platform, ETag, and
core platform services required to serve requests.(createServer(alias) function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(requestListener?: RequestListener<Request, Response>): Server<Request, Response>
(alias) function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(options: ServerOptions<Request, Response>, requestListener?: RequestListener<Request, Response>): Server<Request, Response>Returns a new instance of Server., { port(property) ListenOptions.port?: number | undefined })
  return Layer(alias) module "effect/Layer".provideconst provide: <HttpServer, never, never, never, ServeError, Generator | HttpPlatform | HttpServer | NodeServices>(self: Layer<never, never, HttpServer>, that: Layer<Generator | HttpPlatform | HttpServer | NodeServices, ServeError, never>) => Layer<never, ServeError, never>Feeds the output services of the dependency layer into the requirements of
this layer, returning a layer that only provides the services from this layer.(HttpRouter(alias) module "effect/http/HttpRouter".serveconst serve: <never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>, unknown, never>(appLayer: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>, options?: {
    readonly routerConfig?: Partial<RouterConfig> | undefined;
    readonly disableLogger?: boolean | undefined;
    readonly disableListenLog?: boolean;
    readonly middleware?: ... | undefined;
} | undefined) => Layer<...>Runs the provided application layer as an HTTP server.(App(alias) const App: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError>.), Serverconst Server: Layer<Generator | HttpPlatform | HttpServer | NodeServices, ServeError, never>Layer: provides ChildProcessSpawner and Crypto and FileSystem and Generator and HttpPlatform and HttpServer and Path and Stdio and Terminal; needs nothing; fails with ServeError.)
}
const Liveconst Live: Layer<never, ServeError, never>Layer: provides nothing; needs nothing; fails with ServeError. = serverfunction server(port: number): Layer<never, ServeError, never>Plain JavaScript: VibeLang code calls it directly. TypeScript callers see Effect<Layer<never, ServeError, never>, never, never>.(3000)

export function mainfunction main(): void!ServeError!() {
  Layer(alias) module "effect/Layer".launchconst launch: <never, ServeError, never>(self: Layer<never, ServeError, never>) => !ServeError!Runs here and returns never.Builds this layer and keeps it alive until the returned effect is interrupted.(Liveconst Live: Layer<never, ServeError, never>Layer: provides nothing; needs nothing; fails with ServeError.)
}
// Output: server acquired
// Output: server released

Types in this example

HttpRouter: (alias) module "effect/http/HttpRouter"
NodeHttpServer: (alias) module "@effect/platform-node/NodeHttpServer"
createServer: (alias) function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(requestListener?: RequestListener<Request, Response>): Server<Request, Response> (alias) function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(options: ServerOptions<Request, Response>, requestListener?: RequestListener<Request, Response>): Server<Request, Response>Returns a new instance of Server.
App: (alias) const App: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError>.
function: function server(port: number): Layer<never, ServeError, never>!!
server: function server(port: number): Layer<never, ServeError, never>Plain JavaScript: VibeLang code calls it directly. TypeScript callers see Effect<Layer<never, ServeError, never>, never, never>.
port: (parameter) port: number
Server: const Server: Layer<Generator | HttpPlatform | HttpServer | NodeServices, ServeError, never>Layer: provides ChildProcessSpawner and Crypto and FileSystem and Generator and HttpPlatform and HttpServer and Path and Stdio and Terminal; needs nothing; fails with ServeError.
layer: const layer: (evaluate: LazyArg<Server>, options: NodeHttpServer.Options) => Layer.Layer<HttpServer | NodeServices | HttpPlatform | Generator, ServeError>Provides a Node HttpServer together with the Node HTTP platform, ETag, and core platform services required to serve requests.
port: (property) ListenOptions.port?: number | undefined
Layer: (alias) module "effect/Layer"
provide: const provide: <HttpServer, never, never, never, ServeError, Generator | HttpPlatform | HttpServer | NodeServices>(self: Layer<never, never, HttpServer>, that: Layer<Generator | HttpPlatform | HttpServer | NodeServices, ServeError, never>) => Layer<never, ServeError, never>Feeds the output services of the dependency layer into the requirements of this layer, returning a layer that only provides the services from this layer.
serve: const serve: <never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>, unknown, never>(appLayer: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>, options?: { readonly routerConfig?: Partial<RouterConfig> | undefined; readonly disableLogger?: boolean | undefined; readonly disableListenLog?: boolean; readonly middleware?: ... | undefined; } | undefined) => Layer<...>Runs the provided application layer as an HTTP server.
Live: const Live: Layer<never, ServeError, never>Layer: provides nothing; needs nothing; fails with ServeError.
main: function main(): void!ServeError!
launch: const launch: <never, ServeError, never>(self: Layer<never, ServeError, never>) => !ServeError!Runs here and returns never.Builds this layer and keeps it alive until the returned effect is interrupted.

Pass createServer as a value. NodeHttpServer.layer runs the Node API and owns its lifetime; calling createServer() directly in .vibe is a platform API error. HttpRouter.serve builds the serving layer, and Layer.launch keeps it alive until shutdown.

The module top level constructs schemas, routes, and layers. node server.js starts the application: a module that exports a main without parameters ends with if (import.meta.main) NodeRuntime.runMain(main()), so importing it, from a test or another module, starts nothing.

Test a route without a socket

VibeLang

// routes.test.vibe
import { assert(alias) const assert: Chai.Assert, it(alias) const it: Vitest.Methods<never, {}>Vitest test API extended with Effect test helpers. } from "@effect/vitest"
import { HttpClientRequest(alias) module "effect/http/HttpClientRequest", HttpRouter(alias) module "effect/http/HttpRouter", HttpServerRequest(alias) module "effect/http/HttpServerRequest" } from "effect/http"
import { App(alias) const App: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError>. } from "./routes.vibe"

function requestfunction request(body: unknown): HttpServerRequest.HttpServerRequest!HttpBodyError!(body(parameter) body: unknown: unknown) {
  const clientconst client: HttpClientRequest.HttpClientRequest = HttpClientRequest(alias) module "effect/http/HttpClientRequest".bodyJsonconst bodyJson: (self: HttpClientRequest.HttpClientRequest, body: unknown) => HttpClientRequest.HttpClientRequest!HttpBodyError!Runs here and returns HttpClientRequest.HttpClientRequest.Encodes a value as a JSON request body and sets it on the request, failing with HttpBodyError if encoding fails.(HttpClientRequest(alias) module "effect/http/HttpClientRequest".postconst post: (url: string | URL, options?: HttpClientRequest.Options.NoUrl) => HttpClientRequest.HttpClientRequestCreates a POST request for the specified URL.("http://local/users"), body(parameter) body: unknown)
  return HttpServerRequest(alias) module "effect/http/HttpServerRequest".fromClientRequestconst fromClientRequest: (request: HttpClientRequest.HttpClientRequest) => HttpServerRequest.HttpServerRequestCreates an HttpServerRequest view of an HttpClientRequest.(clientconst client: HttpClientRequest.HttpClientRequest)
}

it(alias) const it: Vitest.Methods<never, {}>Vitest test API extended with Effect test helpers..effect(property) Vitest.MethodsNonLive<never, {}>.effect: <void, HttpBodyError | HttpServerError>(name: string, self: Vitest.TestFunction<void, HttpBodyError | HttpServerError, Scope, [TestContext]>, timeout?: number | TestOptions) => void("validates bodies and rejects duplicate names") {
  Effect(alias) module "effect/Effect".scopedconst scoped: <void, HttpBodyError | HttpServerError, Scope>(self: void!HttpBodyError | HttpServerError!Scope) => void!HttpBodyError | HttpServerError!Runs here and returns void.Runs an effect with a scope that closes when the effect completes. {
    const appconst app: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope = HttpRouter(alias) module "effect/http/HttpRouter".toHttpEffectconst toHttpEffect: <never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>(appLayer: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>) => (HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope)!!ScopeRuns here and returns Effect<HttpServerResponse.HttpServerResponse, HttpBodyError | HttpServerError, HttpServerRequest.HttpServerRequest | Scope>.Builds an application layer with a router and returns the router as an HTTP
handler effect.(App(alias) const App: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError>.)
    const createdconst created: HttpServerResponse.HttpServerResponse = Effect(alias) module "effect/Effect".provideServiceconst provideService: <HttpServerResponse.HttpServerResponse, HttpBodyError | HttpServerError, HttpServerRequest.HttpServerRequest | Scope, HttpServerRequest.HttpServerRequest, HttpServerRequest.HttpServerRequest>(self: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope, service: Key<...>, implementation: HttpServerRequest.HttpServerRequest) => ...!!Runs here and returns HttpServerResponse.HttpServerResponse.Provides one concrete service implementation to an effect.(appconst app: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope, HttpServerRequest(alias) module "effect/http/HttpServerRequest".HttpServerRequestconst HttpServerRequest: Service<HttpServerRequest.HttpServerRequest, HttpServerRequest.HttpServerRequest>Service tag for the active server-side HTTP request., requestfunction request(body: unknown): HttpServerRequest.HttpServerRequest!HttpBodyError!Runs here and returns HttpServerRequest.HttpServerRequest.({ name(property) name: string: "Ada" }))
    const conflictconst conflict: HttpServerResponse.HttpServerResponse = Effect(alias) module "effect/Effect".provideServiceconst provideService: <HttpServerResponse.HttpServerResponse, HttpBodyError | HttpServerError, HttpServerRequest.HttpServerRequest | Scope, HttpServerRequest.HttpServerRequest, HttpServerRequest.HttpServerRequest>(self: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope, service: Key<...>, implementation: HttpServerRequest.HttpServerRequest) => ...!!Runs here and returns HttpServerResponse.HttpServerResponse.Provides one concrete service implementation to an effect.(appconst app: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope, HttpServerRequest(alias) module "effect/http/HttpServerRequest".HttpServerRequestconst HttpServerRequest: Service<HttpServerRequest.HttpServerRequest, HttpServerRequest.HttpServerRequest>Service tag for the active server-side HTTP request., requestfunction request(body: unknown): HttpServerRequest.HttpServerRequest!HttpBodyError!Runs here and returns HttpServerRequest.HttpServerRequest.({ name(property) name: string: "Ada" }))
    const badconst bad: HttpServerResponse.HttpServerResponse = Effect(alias) module "effect/Effect".provideServiceconst provideService: <HttpServerResponse.HttpServerResponse, HttpBodyError | HttpServerError, HttpServerRequest.HttpServerRequest | Scope, HttpServerRequest.HttpServerRequest, HttpServerRequest.HttpServerRequest>(self: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope, service: Key<...>, implementation: HttpServerRequest.HttpServerRequest) => ...!!Runs here and returns HttpServerResponse.HttpServerResponse.Provides one concrete service implementation to an effect.(appconst app: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope, HttpServerRequest(alias) module "effect/http/HttpServerRequest".HttpServerRequestconst HttpServerRequest: Service<HttpServerRequest.HttpServerRequest, HttpServerRequest.HttpServerRequest>Service tag for the active server-side HTTP request., requestfunction request(body: unknown): HttpServerRequest.HttpServerRequest!HttpBodyError!Runs here and returns HttpServerRequest.HttpServerRequest.({ name(property) name: number: 123 }))
    assert(alias) const assert: Chai.Assert.deepStrictEqual(method) Chai.Assert.deepStrictEqual<number[]>(actual: number[], expected: number[], message?: string): voidAlias to deepEqual([createdconst created: HttpServerResponse.HttpServerResponse.status(property) HttpServerResponse.status: number, conflictconst conflict: HttpServerResponse.HttpServerResponse.status(property) HttpServerResponse.status: number, badconst bad: HttpServerResponse.HttpServerResponse.status(property) HttpServerResponse.status: number], [201, 409, 400])
  }
}
// Output:

Types in this example

assert: (alias) const assert: Chai.Assert
it: (alias) const it: Vitest.Methods<never, {}>Vitest test API extended with Effect test helpers.
HttpClientRequest: (alias) module "effect/http/HttpClientRequest"
HttpRouter: (alias) module "effect/http/HttpRouter"
HttpServerRequest: (alias) module "effect/http/HttpServerRequest"
App: (alias) const App: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>Layer: provides nothing; needs HttpRouter and Request<"Error", HttpBodyError> and Request<"Error", HttpServerError>.
request: function request(body: unknown): HttpServerRequest.HttpServerRequest!HttpBodyError!
body: (parameter) body: unknown
client: const client: HttpClientRequest.HttpClientRequest
bodyJson: const bodyJson: (self: HttpClientRequest.HttpClientRequest, body: unknown) => HttpClientRequest.HttpClientRequest!HttpBodyError!Runs here and returns HttpClientRequest.HttpClientRequest.Encodes a value as a JSON request body and sets it on the request, failing with HttpBodyError if encoding fails.
post: const post: (url: string | URL, options?: HttpClientRequest.Options.NoUrl) => HttpClientRequest.HttpClientRequestCreates a POST request for the specified URL.
fromClientRequest: const fromClientRequest: (request: HttpClientRequest.HttpClientRequest) => HttpServerRequest.HttpServerRequestCreates an HttpServerRequest view of an HttpClientRequest.
effect: (property) Vitest.MethodsNonLive<never, {}>.effect: <void, HttpBodyError | HttpServerError>(name: string, self: Vitest.TestFunction<void, HttpBodyError | HttpServerError, Scope, [TestContext]>, timeout?: number | TestOptions) => void
Effect: (alias) module "effect/Effect"
scoped: const scoped: <void, HttpBodyError | HttpServerError, Scope>(self: void!HttpBodyError | HttpServerError!Scope) => void!HttpBodyError | HttpServerError!Runs here and returns void.Runs an effect with a scope that closes when the effect completes.
app: const app: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope
toHttpEffect: const toHttpEffect: <never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>(appLayer: Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Error", HttpBodyError> | HttpRouter.Request<"Error", HttpServerError>>) => (HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope)!!ScopeRuns here and returns Effect<HttpServerResponse.HttpServerResponse, HttpBodyError | HttpServerError, HttpServerRequest.HttpServerRequest | Scope>.Builds an application layer with a router and returns the router as an HTTP handler effect.
created: const created: HttpServerResponse.HttpServerResponse
provideService: const provideService: <HttpServerResponse.HttpServerResponse, HttpBodyError | HttpServerError, HttpServerRequest.HttpServerRequest | Scope, HttpServerRequest.HttpServerRequest, HttpServerRequest.HttpServerRequest>(self: HttpServerResponse.HttpServerResponse!HttpBodyError | HttpServerError!HttpServerRequest.HttpServerRequest | Scope, service: Key<...>, implementation: HttpServerRequest.HttpServerRequest) => ...!!Runs here and returns HttpServerResponse.HttpServerResponse.Provides one concrete service implementation to an effect.
HttpServerRequest: const HttpServerRequest: Service<HttpServerRequest.HttpServerRequest, HttpServerRequest.HttpServerRequest>Service tag for the active server-side HTTP request.
request: function request(body: unknown): HttpServerRequest.HttpServerRequest!HttpBodyError!Runs here and returns HttpServerRequest.HttpServerRequest.
name: (property) name: string
conflict: const conflict: HttpServerResponse.HttpServerResponse
bad: const bad: HttpServerResponse.HttpServerResponse
name: (property) name: number
deepStrictEqual: (method) Chai.Assert.deepStrictEqual<number[]>(actual: number[], expected: number[], message?: string): voidAlias to deepEqual
status: (property) HttpServerResponse.status: number

HttpRouter.toHttpEffect builds a request program without starting a server. Hold that program as app, then provide a request for each execution. The scope shares the service layer across these requests and releases it after the test. A new test scope builds a fresh user registry.

Import assertions from @effect/vitest; the compiler trusts its re-exports. Use the installation guide to set up the compiler and test plugin. The complete project, including its Vite configuration, is in examples/http-api.