@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

pnpm add @xemahq/xema-decorators

Usage

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.

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