#Primitives
If services are the "classes" of your application, Primitives are the "superpowers" you attach to them.
In other frameworks, you might use Decorators (like @Get() in NestJS) or File-System naming conventions (like +page.server.ts in SvelteKit) to define special behavior.
In Alepha, we use Primitives. These are factory functions, always prefixed with $, that you assign to class properties. They tell the framework: "This isn't just a variable. This is an API endpoint, a database table, or a background job."
#How they work
You don't need to register routes in a separate file. You don't need to configure a queue worker in a different folder. You declare the behavior right next to the logic.
1import { $logger } from "alepha/logger"; 2import { $action } from "alepha/server"; 3import { $scheduler } from "alepha/scheduler"; 4 5class UserController { 6 // 1. Inject a utility 7 log = $logger(); 8 9 // 2. Define an HTTP Endpoint10 list = $action({11 path: "/users",12 handler: async () => {13 return ["Alice", "Bob"];14 }15 });16 17 // 3. Define a Cron Job18 cleanup = $scheduler({19 cron: "0 0 * * *", // Every midnight20 handler: async () => {21 this.log.info("Cleaning up old users...");22 }23 });24}When you run your app, Alepha scans your classes. It sees $action, so it creates a route. It sees $scheduler, so it starts a cron job. It handles the wiring so you can handle the code.
#The Standard Library
Alepha comes with over 30 Primitives out of the box. Here are the ones you will use every day.
#Core & Dependency Injection
The glue that holds your app together.
$inject: The Dependency Injection mechanism. Access other services instantly.$env: Type-safe access to environment variables. Validates.envfiles at startup.$logger: Context-aware logging (knows which module/service called it).
#HTTP & Server
Building APIs and managing requests.
$action: The star of the show. Defines a type-safe REST endpoint with input/output validation (via TypeBox) and automatic Swagger generation.$cookie: Secure, encrypted, and signed cookie management.
#Data & Persistence
Working with Postgres or SQLite.
$entity: Defines a database table schema.$repository: Creates a fully typed repository for an entity with built-in CRUD (create, find, update, delete).
#Infrastructure
Powerful backend features without the setup pain.
$queue: A background job queue (backed by memory or Redis).$scheduler: Cron jobs and recurring tasks.$cache: Caches the result of a function (in memory or Redis).$bucket: File storage abstraction (upload to local disk, S3, or Azure).
#Frontend (React)
Full-stack integration.
$page: Defines a React route (SSR/CSR) with server-side data fetching.$head: Manages document<head>(title, meta tags).
#Creating your own
Primitives aren't magic. They are just functions.
As you get advanced with Alepha, you can write your own Primitives to encapsulate complex logic (like $index for ElasticSearch) and share them across your projects.