Registry / web-framework / effect-http

effect-http

JSON →
library0.87.0jsnpmunverified

effect-http is a high-level, declarative, and type-safe HTTP API layer built specifically for the `effect-ts` ecosystem. It leverages `Effect`'s powerful functional programming primitives, including Effects, Layers, and Schemas, to provide a robust framework for defining both HTTP servers and clients. Currently at version 0.87.0, the library maintains a rapid release cadence, often issuing minor version updates to align with ongoing developments and breaking changes within its core peer dependency, `effect`. This close coupling ensures full compatibility and leverages the latest features of `effect-ts`, but also means users should expect frequent dependency updates. Its primary differentiation lies in its deep integration with the `Effect` paradigm, offering end-to-end type safety from API definition to implementation and client consumption, while remaining platform-agnostic at its core (`effect-http` package) with specific adapters like `effect-http-node` for server execution. It promotes a functional and declarative style for building robust, concurrent, and error-handled web services.

npm install effect-http
INSTALL
IMPORT
SIG · EFFECT-HTTP
E
effect-http
web-frameworkjavascriptv0.87.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Api
import * as Api from 'effect-http/Api';
import { Api } from 'effect-http';
Most effect-ts related modules prefer a namespace import (e.g., `* as Api`) due to numerous exports and potential naming conflicts.
Router
import * as Router from 'effect-http/Router';
import { Router } from 'effect-http';
Similar to `Api`, `Router` is typically imported as a namespace to access its various functions for building HTTP handlers and services.
Client
import * as Client from 'effect-http/Client';
import { Client } from 'effect-http';
The `Client` module provides functions for generating type-safe clients from an `Api` definition. Use `Client.make` or similar.

This quickstart defines a simple REST API with GET and POST endpoints, implements them using `effect-http/Router`, starts a Node.js server with `effect-http-node`, and then uses `effect-http/Client` to interact with the running API programmatically.

import * as Effect from 'effect'; import * as Schema from '@effect/schema/Schema'; import * as Http from '@effect/platform/Http'; import * as NodeHttpServer from '@effect/platform-node/HttpServer'; import * as NodeHttpClient from '@effect/platform-node/HttpClient'; import * as Api from 'effect-http/Api'; import * as Router from 'effect-http/Router'; import * as Client from 'effect-http/Client'; // 1. Define your API schema const MyApi = Api.api().pipe( Api.get('getUser', '/users/:id', { request: { params: Schema.struct({ id: Schema.NumberFromString }) }, response: Schema.struct({ id: Schema.number, name: Schema.string }), }), Api.post('createUser', '/users', { request: { body: Schema.struct({ name: Schema.string }) }, response: Schema.struct({ id: Schema.number, name: Schema.string }), }), ); // 2. Implement the handlers const app = Router.make(MyApi).pipe( Router.handle('getUser', ({ params }) => Effect.succeed({ id: params.id, name: `User ${params.id}`, }), ), Router.handle('createUser', ({ body }) => Effect.succeed({ id: Math.floor(Math.random() * 1000) + 1, name: body.name, }), ), ); // 3. Set up the Node.js server const server = NodeHttpServer.server.pipe( Effect.tap((s) => Http.server.serve(app, s)), Effect.scoped, Effect.provide(NodeHttpServer.layer(() => Http.listeningOn({ port: 3000 }))), ); // 4. Create a client for the API const myClient = Client.make(MyApi); const httpClient = Http.client.fetch.pipe(NodeHttpClient.layer); // Use Node's fetch // 5. Run the server and make a client request const program = Effect.gen(function* () { yield* Effect.fork(server); yield* Effect.sleep('100ms'); // Give server time to start const getUserResult = yield* myClient.getUser({ params: { id: 1 } }); console.log('GET /users/1 result:', getUserResult); const createUserResult = yield* myClient.createUser({ body: { name: 'Alice' } }); console.log('POST /users result:', createUserResult); yield* Effect.log('Server and client interaction complete. Stopping server.'); }).pipe(Effect.provide(httpClient)); Effect.runPromise(program);
Debug
Known issues
breakingeffect-http frequently updates its peer dependencies on `effect` and `@effect/platform`. Minor version bumps in effect-http often correspond to minor or patch updates in `effect` itself, which can include breaking changes in the underlying `effect-ts` library. Always review the `effect-ts` changelog when updating `effect-http`.
fix
Pin `effect-http` and `effect` dependencies to specific versions, or review release notes for both `effect-http` and `effect` when upgrading to manage breaking changes. Use `npm install effect-http@latest effect@latest` cautiously.
affects: >=0.1.0
gotchaThe `effect-http` package itself is platform-agnostic, primarily providing the API definition and routing logic. To run an HTTP server, you must install and use a platform-specific adapter like `effect-http-node` for Node.js environments or `effect-http-express` for Express.js integration.
fix
For Node.js server environments, install `effect-http-node` (`npm install effect-http-node`) and use its server utilities (e.g., `NodeHttpServer.server`).
affects: >=0.1.0
breakingThe `effect` library, upon which `effect-http` is built, underwent significant breaking changes in its transition to version 3. If you are migrating from an `effect` v2 (or earlier) project, expect extensive code refactoring, especially around `Layer` composition, `Effect` constructors, and `Schema` usage.
fix
Consult the `effect-ts` migration guides for upgrading to `effect` v3. Ensure all `effect` ecosystem libraries, including `effect-http`, are compatible with your target `effect` version. `effect-http` versions >=0.80.0 are generally aligned with `effect` v3.
affects: <3.0.0
Errors
Common errors & fixes
Error: Operation 'myOperation' not found or has no handler attached.
You have defined an operation in your `Api` but have not provided an implementation for it using `Router.handle('myOperation', ...)`.
fix
Ensure every operation defined in `Api.api()` has a corresponding handler attached to the `Router.make(api)` instance using `Router.handle('operationName', handlerFunction)`.
TypeError: Cannot read properties of undefined (reading 'pipe')
This often indicates that you're trying to call a method like `pipe` on `undefined` because a dependency was not provided or an `Effect` did not resolve as expected, commonly seen when `Layer` composition is incorrect.
fix
Verify that all necessary dependencies (Layers) are provided to your `Effect` program. Use `Effect.provide()` or `Layer.merge()`/`Layer.provide()` correctly to ensure services are available in the desired scope. Inspect the specific line number for the `undefined` value.
Error: Decoding error: (Schema validation details)
This error occurs when an incoming request (e.g., body, params, query) or an outgoing response does not conform to the `Schema` defined in your `Api` for that specific operation.
fix
Review the `Schema` definition for the affected operation in your `Api`. Ensure that the data being sent or received by the client/server matches the structure and types specified by the `Schema`.
Upgrade
Version history
0.87.0latest on npm
Audit
Dependencies
@effect/platformrequiredProvides platform-agnostic HTTP server/client primitives and utilities, foundational for network operations in the Effect ecosystem.
effectrequiredThe core functional programming library providing the Effect data type, Layers for dependency management, and Schemas for data validation, which effect-http is built upon.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources
effect-http — npm install effect-http · libregistry