Skip to content

Decorators

Every decorator NestRS ships, grouped by concern, with a one-line summary and a link to the page where it lives.

This page is the index of every decorator the framework ships, grouped by concern. Skim the table for the one you need, click through to the page that explains it in context. Each row says where the decorator goes (struct, impl block, method, field) so you can confirm the position without leaving the page.

What counts as a decorator here: everything you write. That is the whole inclusion rule, and it is wider than “an attribute macro”. Roughly half the rows below — #[get], #[query], #[public], #[on_module_init] — are inert tokens an orchestrator reads (#[routes], #[operations], #[hooks]), not macros of their own, and they need no import. What decides a row is whether you type it, not how the compiler resolves it. A decorator of your own reads its keys and words its refusals as these do, on the kit Writing a decorator walks through.

DecoratorGoes onSummaryRead more
#[module]structComposes a binary: lists providers it owns and imports it depends onModules
#[nest_rs::main]main functionInstalls the panic hook, publishes the .env cascade and captures the binary’s name, version and description (AppIdentity, which OpenAPI’s info, MCP’s serverInfo and OpenTelemetry’s service.name default to) before main, builds the runtime, and ends the process within the shutdown budget; written in full, never a bare #[main], which use tokio::main; would make tokio’sShutdown
#[injectable]structMarks a provider built from the container, with optional scope = request | transientProviders, Provider scopes
#[inject]fieldResolves the field from the container by its type, at construction; takes no argumentProviders
#[instance]unit structDeclares a marker naming one instance of a resource the app opens more than once; its name is the ident in snake caseInstances
#[hooks]impl blockOrchestrates lifecycle methods on a providerLifecycle
#[on_module_init]methodRuns once after wiring, before servingLifecycle
#[on_application_bootstrap]methodRuns once after every module init, before servingLifecycle
#[on_module_destroy]methodRuns on shutdown after transports stopLifecycle
#[before_application_shutdown]methodRuns on shutdown once every module-destroy hook has runLifecycle
#[on_application_shutdown]methodRuns last during shutdown, best-effortLifecycle
DecoratorGoes onSummaryRead more
#[controller]structMounts the struct as a controller with a base path and optional versionControllers
#[routes]impl blockWires methods to HTTP routes and emits the route tableControllers
#[get] #[post] #[put] #[patch] #[delete]methodBinds the method to an HTTP verb at the given pathControllers
#[sse]methodBinds a GET that answers a text/event-stream, with the keep-alive and the connection ceilingStreaming
#[http_code]methodOverrides the default response status codeResponses
#[response_header]methodSets a response header, set-cookie appended (repeatable)Responses
#[redirect]methodIssues a redirect and discards the handler payloadResponses
#[no_pipes]methodRuns no global pipe over the route’s body, the app’s pool includedGlobal pipes
#[version]methodNarrows a route to one of the controller’s declared versionsVersioning

One set for every edge: a host is a controller, a resolver, a gateway, an MCP host or a worker’s impl block, and a method one of its handlers.

DecoratorGoes onSummaryRead more
#[use_guards]host or methodBinds container-resolved guards, first listed outermostGuards
#[force_guards]methodBinds a guard and re-runs it though a broader scope already ran it — the opt-out from dedupGuards
#[use_pipes]host or methodBinds global pipes to an HTTP or WebSocket site, beside the app’s poolGlobal pipes
#[use_interceptors]host or methodBinds interceptors at the handler stage, after the guardsInterceptors
#[use_exception_filters]host or methodBinds exception filters — a typed catch, or every error with dyn Error + Send + Sync; the method’s tried firstError handling
#[interceptor(stage = unit)]structMakes a struct an interceptor its module’s import brings around the guards of every unit; at the handler stage, an app-wide one is the root’s GlobalInterceptors<(…)>Interceptors
#[meta]host or methodDeclares typed metadata, the method’s over its host’s (repeatable); read back by a layer through cx.reflector()Execution context
#[public]methodAccess posture: the unit admits a caller with no credential — guards relax; bare it reads nothing a grant guards, and #[public(Action, Subject)] gates and reads on that caller’s ability, as #[authorize] does; refused at boot where the request’s guards would turn one awayPublic reads
#[authorize]methodAccess posture: gates the unit by ability (Action, Subject) and, on an entity, opens its reads under the caller’s ability, each wire row judged for that caller; bind = Service also loads the row an id names into an Authorized<Action, E> parameter, on a route, a GraphQL operation or an MCP #[resource]Authorization, Route model binding
#[subject]unit structDeclares a capability no table holds as an authorization subject: a rule grants it whole, a posture naming it gates on every edge and opens the unit’s reads to the caller’s abilityPolicies
DecoratorGoes onSummaryRead more
#[derive(PrincipalIdentity)]structMakes a claims type a principal: implements PrincipalIdentity and AmbientValue off the fields #[principal] marksJWT
#[principal]fieldMarks the role its field plays — actor (required), tenant or scopes — each played by one fieldJWT

One grammar holds every decorator pair: each layer attribute is taken where its edge runs that family, and anywhere else it is a compile error that says why — never a layer that silently never runs. The WebSocket #[on_connect] / #[on_disconnect] hooks run outside any site: they refuse a #[meta] (no layer runs around a hook to read it), a guard (the upgrade’s guards admitted the socket), a pipe (a hook has no payload) and a posture (no gate stands before a hook, so it reads nothing a grant guards), and run no interceptor or exception filter yet.

AttributeHTTPGraphQLWebSocketsMCPQueue, schedule, eventsHooks, indicators
#[use_guards]struct, methodstruct, methodstruct (the upgrade), method; — on a connection hookstruct, method— no caller to gate—
#[force_guards]methodmethodmethodmethod——
#[use_pipes]struct, method— bind a per-argument pipestruct, method; — on a connection hook— bind it inside Parameters<…>— bind a per-argument pipe—
#[use_interceptors]struct, methodstruct, methodstruct, method; not yet on a connection hookstruct, methodimpl block, method—
#[use_exception_filters]struct, methodstruct, methodstruct, method; not yet on a connection hookstruct, methodimpl block, method—
#[meta]struct, methodstruct, methodstruct, method; — on a connection hookstruct, methodimpl block, method—

Not yet marks a family the edge does not run yet: the compiler refuses it today, as a silent no-op would be worse, and the edge takes it once it runs it. #[use_filters] is refused at every pair, naming #[use_exception_filters], whose catch-all replaced it.

DecoratorGoes onSummaryRead more
#[input]structShorthand for a DTO an edge decodes: Serialize + Deserialize + Validate + JsonSchema + deny_unknown_fieldsExtractors
#[output]struct, enumShorthand for a DTO an edge only sends: Serialize + JsonSchemaControllers
#[wire_enum]enumCarries the wire derives for an enum both decoded and sent, a column’s or a claims role, and under graphql its EnumEntities

One decorator per shape, one definition — an HTTP body, a GraphQL input, a queue payload, a WS message and a tool’s arguments all take them, from one path: nest_rs::core, which nest_rs::prelude carries too.

DecoratorGoes onSummaryRead more
#[resolver]structMarks a resolver provider and declares its resolver-scope guards, interceptors and exception filtersGraphQL
#[operations]impl blockOrchestrates the block’s #[query] / #[mutation] / #[subscription] / #[entity] / #[field_resolver] methodsGraphQL
#[query]methodRoot query operation; requires an access posture (#[authorize(…)], #[public(…)] or #[public])Queries and mutations
#[mutation]methodRoot mutation operation; requires an access posture (#[authorize(…)], #[public(…)] or #[public])Queries and mutations
#[subscription]methodRoot subscription over graphql-ws; same posture, gated at subscribe, each item judged for its subscriberSubscriptions
#[entity]methodFederation entity resolver — the router resolves it by reference through _entities; same mandatory posture, and its arguments are the @keyFederation
#[field_resolver]methodCustom field resolver on a wire type; takes no posture attributeField resolvers
#[dataloader]impl block on serviceBatches a method into a request-scoped DataLoaderDataloader
DecoratorGoes onSummaryRead more
#[gateway]structMounts a WebSocket gateway at a path on the HTTP transportWebSockets
#[messages]impl blockBinds gateway message handlers and lifecycle hooksMessages
#[subscribe_message]methodHandles one event in the { event, data } envelopeMessages
#[on_connect]methodRuns after the socket upgradesRooms
#[on_disconnect]methodRuns after the socket closesRooms
DecoratorGoes onSummaryRead more
#[queue]unit structDeclares a queue’s wire name and payload type in one artifact both producer and consumer importQueue
#[processor]impl blockOrchestrates queue consumers on a providerQueue
#[process]methodBinds the method to a queue with a retries budget, a per-replica concurrency, a deployment-wide throttle, an attempt’s timeout and transactional settling; the method may take an Attempt and a Checkpoint<_> beside its jobQueue
DecoratorGoes onSummaryRead more
#[scheduled]impl blockOrchestrates scheduled methods on a providerSchedule
#[every]methodFires the method on a fixed interval, optional timeout, transactional, replicas and keySchedule
#[cron]methodFires the method on a cron expression, optional timeout, tz, transactional, replicas and keySchedule
#[after]methodFires the method once after a delay from boot, optional timeout and transactionalSchedule
DecoratorGoes onSummaryRead more
#[listeners]impl blockOrchestrates event listeners on a providerEvents
#[on_event]methodSubscribes the method to its second-parameter event type, each call a unit of work of its own, optional timeout and transactionalEvents
DecoratorGoes onSummaryRead more
#[mcp]structMounts an MCP endpoint over HTTP, at /mcp or a declared pathMCP
#[tools]impl blockServes the block’s #[tool], #[prompt], #[resource] and #[resources] methods, deriving the advertised capabilitiesMCP
#[tool]methodExposes the method as an MCP tool; description = "…", or the doc comment as a fallbackMCP
#[prompt]methodExposes the method as an MCP prompt; description = "…", or the doc comment as a fallbackResources and prompts
#[resource]methodReads the URIs an RFC 6570 template = "…" writes, each variable a typed argument, or under bind = Service the row it names; description = "…", or the doc comment as a fallbackResources and prompts
#[resources]methodAnswers resources/list, one per hostResources and prompts
DecoratorGoes onSummaryRead more
#[indicators]impl blockOrchestrates health checks on a providerIndicators
#[liveness]methodBinds the method to the liveness probeIndicators
#[readiness]methodBinds the method to the readiness probeIndicators
#[startup]methodBinds the method to the startup probeIndicators
DecoratorGoes onSummaryRead more
#[config]structMarks a struct as a namespaced configuration loaded from env and filesConfiguration
DecoratorGoes onSummaryRead more
#[expose]struct + fieldExposes a SeaORM entity to GraphQL and OpenAPI from one declarationDatabase
#[crud]impl blockGenerates standard CRUD operations on a controller or resolverCRUD
DecoratorGoes onSummaryRead more
#[api]methodEnriches the OpenAPI operation with summary, description, and tagsOpenAPI