#The Alepha Instance

The Alepha class is the brain of your application. It acts as the central container that holds your configuration, manages the state, and controls the lifecycle of all your services.

Unlike frameworks that rely on global nasty side-effects, Alepha keeps everything contained within this instance. This makes your application portable, testable, and predictable.

#Creating the Instance

While you can use new Alepha(), we strongly recommend using the static factory method.

1import { Alepha } from "alepha";2 3// The standard way to initialize your app4const alepha = Alepha.create();

Why create()?

1. Environment Merging: It automatically merges process.env (on the server) with any custom configuration you provide.
2. Test Integration: If it detects a testing environment (like Vitest with globals: true), it automatically hooks into beforeAll and afterAll to manage the app lifecycle during tests.

#Configuration & Environment

You can pass a configuration object to create. The most important property is env.

 1const alepha = Alepha.create({ 2  env: { 3    // 1. Set defaults or overrides 4    APP_NAME: "My SaaS", 5  6    // 2. Secrets are automatically loaded from process.env 7    // You don't need to manually pass them here if they exist in the environment 8  } 9});10 11// Access anywhere via the instance (read-only)12console.log(alepha.env.APP_NAME);

Tip: While alepha.env gives you raw access, we recommend using the $env primitive inside your services for type-safe, validated environment variables.

#The Container (Dependency Injection)

Alepha is built on a powerful Dependency Injection (DI) container. You don't manually instantiate your classes; you register them, and Alepha wires them together.

#Registering Services (.with)

Use .with() to add services, modules, or providers to your application.

 1import { Alepha, run } from "alepha"; 2import { AlephaServer } from "alepha/server"; 3import { MyDatabaseService } from "./services/db"; 4  5const alepha = Alepha.create(); 6  7// Register the HTTP Server module 8alepha.with(AlephaServer); 9 10// Register your own service11alepha.with(MyDatabaseService);

Auto-Registration Magic: You rarely need to manually register core modules. If you use a primitive like $route or $repository in your class, Alepha automatically detects the dependency and registers the necessary modules (like AlephaServer or AlephaPostgres) for you.

#Using Services (.inject)

If you need to access a service from the outside (e.g., in a script or test), use .inject().

1const myService = alepha.inject(MyService);2myService.doSomething();

Technically, .inject(MyService) is nearly like new MyService() but with all dependencies automatically resolved and injected.

#Lifecycle Management

Alepha has a strict lifecycle to ensure resources (databases, ports, queues) are opened and closed correctly.

#The Phases

1. Configure: All services register their configurations. Primitives like $action read their schemas.
2. Start: Providers connect to IO (Database connections open, HTTP server listens).
3. Ready: The app is live. Background jobs and schedulers start running.
4. Stop: Graceful shutdown. HTTP server stops accepting requests, DB connections close.

CONFIGURE --> START --> READY --> (LIVE) --> STOP

#Running the App

You don't need to call the lifecycle methods manually. Use the run helper.

1import { run } from "alepha";2 3// 1. Configures4// 2. Starts5// 3. Handles SIGTERM/SIGINT for graceful shutdown6run(alepha);

#Manual Control (For Tests)

In tests, you often want manual control over the lifecycle to mock services or test specific states.

 1// In a test file 2test("MyService", async () => { 3  const app = Alepha.create().with(MyService); 4  5  await app.start(); // Connects to DB, etc. 6  7  const service = app.inject(MyService); 8  expect(service.isReady).toBe(true); 9 10  // await app.stop(); <- automatically called by Vitest hooks11});