#Alepha - Server

#Installation

Part of the alepha package. Import from alepha/server.

npm install alepha

#Overview

Provides high-performance HTTP server capabilities with declarative routing and action primitives.

The server module enables building REST APIs and web applications using $route and $action primitives on class properties. It provides automatic request/response handling, schema validation, middleware support, and seamless integration with other Alepha modules for a complete backend solution.

#API Reference

#Primitives

Primitives are functions that define and configure various aspects of your application. They follow the convention of starting with $ and return configured primitive instances.

For more details, see the Primitives documentation.

#$action()

Creates a server action primitive for defining type-safe HTTP endpoints.

Server actions are the core building blocks for REST APIs in Alepha, providing declarative HTTP endpoints with full type safety, automatic validation, and OpenAPI documentation.

Key Features

• Full TypeScript inference for request/response types
• Automatic schema validation using TypeBox
• Convention-based URL generation with customizable paths
• Direct invocation (run()) or HTTP requests (fetch())
• Built-in authentication and authorization support
• Automatic content-type handling (JSON, form-data, plain text)

URL Generation

Important: All $action paths are automatically prefixed with /api.

1$action({ path: "/users" })     // → GET /api/users2$action({ path: "/users/:id" }) // → GET /api/users/:id3$action({ path: "/hello" })     // → GET /api/hello

This prefix is configurable via the SERVER_API_PREFIX environment variable. HTTP method defaults to GET, or POST if body schema is provided.

Common Use Cases

• CRUD operations with type safety
• File upload and download endpoints
• Microservice communication

 1class UserController { 2  getUsers = $action({ 3    path: "/users", 4    schema: { 5      query: t.object({ 6        page: t.optional(t.number({ default: 1 })), 7        limit: t.optional(t.number({ default: 10 })) 8      }), 9      response: t.object({10        users: t.array(t.object({11          id: t.text(),12          name: t.text(),13          email: t.text()14        })),15        total: t.number()16      })17    },18    handler: async ({ query }) => {19      const users = await this.userService.findUsers(query);20      return { users: users.items, total: users.total };21    }22  });23 24  createUser = $action({25    method: "POST",26    path: "/users",27    schema: {28      body: t.object({29        name: t.text(),30        email: t.text({ format: "email" })31      }),32      response: t.object({ id: t.text(), name: t.text() })33    },34    handler: async ({ body }) => {35      return await this.userService.create(body);36    }37  });38}

#$route()

Create a basic endpoint.

It's a low level primitive. You probably want to use $action instead.

#Providers

Providers are classes that encapsulate specific functionality and can be injected into your application. They handle initialization, configuration, and lifecycle management.

For more details, see the Providers documentation.

#ServerNotReadyProvider

On every request, this provider checks if the server is ready.

If the server is not ready, it responds with a 503 status code and a message indicating that the server is not ready yet.

The response also includes a Retry-After header indicating that the client should retry after 5 seconds.

#ServerProvider

Base server provider to handle incoming requests and route them.

This is the default implementation for serverless environments.

ServerProvider supports both Node.js HTTP requests and Web (Fetch API) requests.

#ServerRouterProvider

Main router for all routes on the server side.

• $route => generic route
• $action => action route (for API calls)
• $page => React route (for SSR)