Website ·
npm
# @xemahq/xema-decorators
> Declarative NestJS decorators for routes and capabilities.
## Overview
The annotation layer that lets a service declare its routes, resources, and
capabilities directly on its controllers. Decorators like `@XemaResource`,
`@XemaRoute`, `@XemaPublicRoute`, and `@XemaCapability` mark intent; a
convention-inference engine derives actions, operation ids, and
the resolved space from naming conventions. At boot, `XemaRuntimeModule` scans
the application and emits the route, capability, and service manifests — so
those manifests are generated from the code rather than hand-maintained.
## When to use it
- Use it to declare a NestJS service's route and capability surface as
annotations instead of separate hand-written manifests.
- Reach for the inference engine standalone in tests or codemods that need to
derive actions or permissions from route metadata.
- Declare a browser-facing composition (BFF) surface with `@BffController`,
which carries the whole contract in one decorator: a public API surface, a
user-token-only fence, a stated org-role floor with both guards mounted, and
an enforced `bff/` mount prefix.
## Installation
```bash
pnpm add @xemahq/xema-decorators
```
## Usage
```ts
import { XemaResource, XemaRoute, XemaPublicRoute } from '@xemahq/xema-decorators';
@XemaResource('invoice')
@Controller('invoices')
export class InvoiceController {
@XemaPublicRoute()
@Get()
list() { /* ... */ }
@XemaRoute()
@Post()
create() { /* ... */ }
}
```
A browser-facing composition surface declares its whole contract at once. The
org-role floor is required rather than defaulted — an omitted tier on an
administrative surface is a failure, not a default — and the mount path must
begin with `bff/`, which is checked when the class is declared.
```ts
import { OrgRole } from '@xemahq/platform-common';
import { BffController } from '@xemahq/xema-decorators';
@BffController({ resource: 'invoice', path: 'bff/invoices', orgRole: OrgRole.Member })
export class InvoiceBffController {
@Get()
summary() { /* ... */ }
}
```
## Peer requirements
- `@nestjs/common`, `@nestjs/core` — host framework.
- `@xemahq/platform-common` — request context, token classes and org roles;
`@BffController` composes its guards.
- `reflect-metadata` — decorator metadata runtime.
## License
Apache-2.0 © Xema — [xema.dev](https://xema.dev)