Effect HTTP Node.js Server

Common errors

• Error: EADDRINUSE: address already in use :::3000

  cause The specified port (e.g., 3000) is already occupied by another process.
  fix Change the `port` in `NodeServer.make` to an available port, or terminate the process currently using the port.

• TypeError: (0 , effect_http_node_1.NodeServer.make) is not a function

  cause This error typically indicates an ESM/CJS module incompatibility. You might be trying to `require` an ESM-only module or using incorrect named/default import syntax.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import { NodeServer } from 'effect-http-node';` syntax. Avoid `require()` for Effect-TS modules.

• TS2345: Argument of type 'Api<...>' is not assignable to parameter of type 'HttpApp<...>'

  cause The `NodeServer.make` function expects an `HttpApp` (an implemented router), not just an `Api` definition. The `Api` needs to be transformed into a `Router` (application) with handlers.
  fix Ensure you've created an `EffectHttp.Router` instance by calling `Router.make(api).pipe(Router.handle(...))` before passing it to `NodeServer.make`.

Warnings

• breaking The `effect-http` library, and by extension `effect-http-node`, is considered 'deprecated in favour of the @effect/platform' as of August 30, 2024. Users are advised to migrate to `@effect/platform` for future-proof HTTP server development within the Effect ecosystem.
  Fix: Begin migrating your HTTP API definitions and server implementations to use the `@effect/platform` and `@effect/platform-node` modules directly for server creation and routing. `effect-http` will only receive Effect updates and critical patches.
• gotcha Due to the rapid development and interconnectedness of the Effect-TS ecosystem, frequent minor version updates across `effect`, `@effect/platform`, `@effect/platform-node`, and `effect-http` are common. Mismatched peer dependencies can lead to runtime errors or subtle type-system inconsistencies.
  Fix: Always keep `effect`, `@effect/platform`, `@effect/platform-node`, and `effect-http` (and `effect-http-node`) at compatible versions, ideally by updating them simultaneously or frequently checking the `effect-http` changelog for specific dependency requirements. Use a lockfile (pnpm-lock.yaml, yarn.lock, package-lock.json) to ensure consistent dependency resolution.
• gotcha The Effect ecosystem is designed for TypeScript and leverages advanced type features. Incorrect type inference or usage can lead to complex type errors. While powerful, this can be a learning curve for developers new to Effect.
  Fix: Refer to the official Effect documentation, especially sections on error handling, schema, and basic Effect patterns. Ensure your TypeScript configuration is strict, and gradually introduce Effect concepts.

Install

• npm install effect-http-node npm
• yarn add effect-http-node yarn
• pnpm add effect-http-node pnpm

Imports

• NodeServer
  wrong:

  const NodeServer = require('effect-http-node').NodeServer;

  correct:

  import { NodeServer } from 'effect-http-node';

  Used for creating a Node.js HTTP server instance from an `effect-http` application. The Effect ecosystem is primarily ESM-first.
• NodeRuntime
  wrong:

  import { NodeRuntime } from '@effect/platform-node';

  correct:

  import * as NodePlatform from '@effect/platform-node';
  // ...
  NodePlatform.NodeRuntime.runMain(program);

  While `NodeRuntime` is from `@effect/platform-node`, it is essential for running `Effect` programs, including the server, in a Node.js environment. It's often imported as a namespace.
• Api

  import { Api } from 'effect-http';

  Although `Api` is from `effect-http`, it's fundamental for defining the API contract that `effect-http-node` then serves.

Quickstart

This quickstart demonstrates defining a simple `effect-http` API, implementing its handlers, and serving it using `effect-http-node` within a Node.js runtime. It includes a GET and a POST endpoint.

import { pipe, Effect } from 'effect';
import { Api, Router } from 'effect-http';
import { NodeServer } from 'effect-http-node';
import * as NodePlatform from '@effect/platform-node';
import * as Logger from '@effect/data/Logger';

// 1. Define your API using effect-http
const api = Api.make().pipe(
  Api.get('hello', '/hello', {
    response: Api.string(),
  }),
  Api.post('echo', '/echo', {
    request: {
      body: Api.string(),
    },
    response: Api.string(),
  }),
);

// 2. Implement the API handlers
const app = Router.make(api).pipe(
  Router.handle('hello', () => Effect.succeed('Hello from Effect-HTTP!')), 
  Router.handle('echo', ({ body }) => Effect.succeed(`You said: ${body}`)),
);

// 3. Create a Node.js server from the API and application
const server = NodeServer.make(app, { port: 3000 });

// 4. Run the server using NodePlatform.NodeRuntime
pipe(
  server.pipe(
    Effect.tap(() =>
      Effect.logInfo('Server started on http://localhost:3000'),
    ),
  ),
  NodePlatform.NodeRuntime.runMain,
);