What runs differently
What a NestJS habit meets underneath NestRS — security by composition, a boot that refuses, no forwardRef, no reflection — and what you will not find.
Coming from NestJS maps the vocabulary. This page is where the machine underneath diverges: what the framework holds for you that a NestJS app holds by habit, and what you will reach for and not find, each for a reason Rust gives.
Security is structural, not per-decorator discipline
Section titled “Security is structural, not per-decorator discipline”In NestJS, authorization is a habit: you remember to add @UseGuards and a
policy check on each route, and a forgotten one is a silent hole. NestRS moves
the guarantee into composition. Once a feature imports the database and authz
modules, every read through the data layer is filtered and every mutating write
is gated, and each row a unit answers is judged for its caller where it is
built. A unit naming nothing reads nothing a grant guards, so the line you forget
fails closed.
You still bind guards explicitly with #[use_guards(...)], and every posture
stays greppable as one #[authorize] or #[public] site — but forgetting the
filter on a query is a category error the framework prevents, not a review catch.
A forgotten guard refuses the boot
Section titled “A forgotten guard refuses the boot”APP_GUARD binds a NestJS guard once, in a module, for the whole app — and a
controller has no way to say it depends on that binding, so the app that forgets
it serves the controller open. NestRS declares the app’s pool in the module
main boots, GlobalGuards<(...)> — never in a feature, which would choose
what covers every route — and an HTTP route no guard identifying a caller covers —
not the global pool, not a #[use_guards] on its controller or itself, a rate limit
counting for nothing — refuses the boot unless it says #[public]. The refusal names every such route, so the
omission is a failed start, never an open route.
Declaring the guard on the controller, resolver or gateway that needs it is still
the convention, because it lets a feature crate travel to a binary with no global
pool and boot there. Listing it at both scopes costs nothing: the Layer System
dedups every layer by TypeId, so a guard listed twice resolves once and runs
once per unit.
There is no forwardRef
Section titled “There is no forwardRef”forwardRef(() => OtherService) exists because JavaScript modules let two files
import each other and resolve the tie at runtime — NestJS then needs a way to
defer one side of a cycle it cannot see until it runs. Rust does not offer the
tie in the first place. Cargo refuses a dependency cycle between crates
outright, so the layering you drew is the layering you get.
Two modules of one crate may still import each other. That cycle is harmless
until a provider crosses it: one of the two modules registers before the other’s
providers exist, so a provider injecting across the cycle has nothing to be
built from. The boot refuses it by name (UnbuiltProviderError), with the edit
to make:
module `UsersModule`: `UsersService` was never built — it needs `PostsService`, which nothing had registered when `UsersModule`'s providers were built; `UsersModule` and `PostsModule` import each other, so one registers before the other's providers exist: move what both need into a module both importWhen the providers also wait on each other — PostsService injecting
UsersService back — no layout of modules can order them, and the boot names
the cycle instead (ProviderCycleError). It does so whichever modules list
them and whatever their scope, a request-scoped or transient cycle included,
before any request would resolve it, and the error carries the remedy:
module `PostsModule`: singleton provider cycle `PostsService` → `UsersService` → `PostsService` — break it by moving what both need into a third provider both inject, by passing the value as a method argument, or by publishing an event one side listens toThat remedy is the point. A cycle is a design signal — each side owns half of what the other needs. Moving that half into a provider both inject, passing the value at the call, or turning one direction into an event removes the cycle instead of deferring it. There is nothing to wrap in a thunk, and no runtime resolution order to reason about.
Other things you will reach for and not find
Section titled “Other things you will reach for and not find”Each is deliberate: the concept exists in NestJS to work around something Rust does not do.
| NestJS | Why NestRS has none |
|---|---|
configure(consumer) middleware, registerPreRequestHook | The word covers several shapes. Gating is a Guard, wrapping is an Interceptor, work around every request before the access decision is an interceptor declared #[interceptor(stage = unit)], body normalization is a Pipe, CORS and security headers are HttpConfig. Middleware maps every role to its home |
@Global() | What a seed or a factory makes is app-global — every config and connection, as TypeOrmModule.forRoot and ConfigModule.forRoot({ isGlobal: true }) are in NestJS. A provider a module lists is import-gated, and no flag opens it everywhere: the import list is its declaration, the one the boot-time access-graph check reads |
app.enableShutdownHooks() | Never opt-in. #[on_module_destroy] and #[on_application_shutdown] always run, best-effort, so one failing cleanup doesn’t skip the rest |
Terminus’s gracefulShutdownTimeoutMs, Fastify’s return503OnClosing | The transport stops accepting at the signal and answers what it already took, so no request arrives to be answered 503; taking the replica out of rotation first is the platform’s — a Kubernetes preStop sleep, an ECS deregistration (leaving the load balancer first) |
@Injectable() on everything | #[injectable] marks a provider the container builds; a controller, resolver or gateway is already one through its own decorator |
The execution context
Section titled “The execution context”A guard, an interceptor, a pipe and an exception filter all read one
UnitContext, as every NestJS enhancer reads one ExecutionContext, on every
edge. The calls map one for one:
| NestJS | NestRS |
|---|---|
ExecutionContext | UnitContext, handed to every layer |
context.getType() | cx.edge() — Edge::Http, Edge::Graphql, Edge::Ws, Edge::Mcp, Edge::Queue, … |
context.switchToHttp() | cx.switch_to::<HttpView>(); in a guard, HttpView::of(cx)? |
switchToWs(), GqlExecutionContext.create(context) | cx.switch_to::<WsView>(), cx.switch_to::<GraphqlView>() — a view per edge |
context.getHandler(), context.getClass() | cx.handler() — the method and its host in one value |
SetMetadata, Reflector.createDecorator | #[meta(value)], typed, on a host or a method |
reflector.get, reflector.getAllAndOverride | cx.reflector().get::<M>() — the method’s value over its host’s |
reflector.getAllAndMerge | cx.reflector().get_all::<M>() |
What differs is where it reaches. The context is typed, so a value read by type cannot collide with another’s key, and the container is not on it: a layer injects what it needs, and the boot checks it. Execution context is the reference.
The parameter type is the decorator
Section titled “The parameter type is the decorator”@Param('id'), @Query(), @Body(), @Req() have no counterpart, because the
job they do is already done by the parameter’s type. A handler declares
Path<Uuid>, Query<Filters> or Json<CreatePost>, and the extraction, the
parse, the rules CreatePost declares and the 400 on malformed input come
from that type — there is no ValidationPipe to register. The same applies to the request-scoped Scoped<T> and the
guard-attached Ambient<T> — Extractors is the full list. A
type never declares who may call: Authorized<Action, E> receives the row an
#[authorize(Action, bind = Service)] beside it loaded, and only the attribute
is the posture.
Interceptors follow the same move. There is no RxJS: intercept is an
async fn receiving Next<'_>, and “after the handler” is the code you write
after next.run(cx).await — no .pipe(map(...)), no stream to remember to
subscribe.
One declaration feeds every schema
Section titled “One declaration feeds every schema”A NestJS field is declared several times: on the entity, on the DTO, again with
@ApiProperty() for Swagger, again with @Field() for GraphQL. Each copy is a
chance to drift. NestRS declares it once — #[expose] on the SeaORM column —
and derives the wire type, the create/update inputs, the JSON Schema behind
GET /api-json, and the GraphQL object from that one site.
A column with no #[expose] reaches no transport at all, so the default is
closed: adding a column to a table never widens the API by accident.
No runtime reflection, because nothing was erased
Section titled “No runtime reflection, because nothing was erased”NestJS reads decorator metadata through reflect-metadata at runtime — the
crutch exists because TypeScript types vanish at compile time, so the framework
has to recover them from a side channel, and an interface can’t be injected
without a hand-written token. NestRS decorators are attribute macros: they
expand to plain Rust during compilation, and the types they read are the ones
the compiler checks. There is no metadata registry to query at runtime, and no
.env-driven reflection deciding what a decorator means — the environment
moves values, every one of them, and never shape. What the macro emitted is what
runs.
What ships is one executable. cargo build --release produces a binary you
copy into a distroless image — no node_modules to install, no runtime to
pin alongside it, no npm ci in the Dockerfile. The monorepo habits do carry
over: a Cargo workspace is the layout you already run, apps/* next to shared
crates, one lockfile at the root, local packages wired by path.
Going further
Section titled “Going further”- Coming from NestJS — the equivalence table, and what a module lists.
- Execution context — the
UnitContextevery layer reads. - Why NestRS — the thesis and the structural properties behind it.