xTaskjs Documentation

Catalog

Decorator groups by use case

Decorator Group

HTTP Routing And Pipelines

Route declaration and request-pipeline decorators exported by @xtaskjs/common. These are the core HTTP building blocks used by controllers in every sample.

13 decorators

Decorator Group

Lifecycle Runners And Events

Lifecycle decorators from @xtaskjs/common used to run startup logic, CLI tasks, and event handlers inside the application lifecycle.

3 decorators

Decorator Group

Core DI And Components

Dependency-injection and component decorators from @xtaskjs/core. These mark providers for container discovery and select named bindings for injection.

8 decorators

Decorator Group

Security And Authorization

Authentication, authorization, strategy, and injector decorators exported by @xtaskjs/security. These layer on top of @xtaskjs/common route metadata.

10 decorators

Decorator Group

Persistence And Repositories

TypeORM registration and injection decorators exported by @xtaskjs/typeorm. These bind datasources and repositories into the same DI container.

5 decorators

Decorator Group

CQRS Buses, Handlers, And Projections

CQRS configuration, handler, projection, idempotency, and injector decorators exported by @xtaskjs/cqrs. These connect command, query, and event flows to the xtaskjs container and read or write datasource aliases.

16 decorators

Decorator Group

Event Sourcing And Stored Events

Configuration, aggregate, subscriber, and injector decorators exported by @xtaskjs/event-source. These wire aggregate metadata, event appliers, repositories, and stored-event subscribers into the xtaskjs lifecycle.

9 decorators

Decorator Group

Mailer Templates And Delivery

Mailer decorators exported by @xtaskjs/mailer. These register transports and templates and inject delivery services into DI-managed classes.

5 decorators

Decorator Group

Internationalization And Locale Resolution

Configuration and injector decorators exported by @xtaskjs/internationalization. These register locale behavior and expose translation services inside DI-managed classes.

7 decorators

Decorator Group

Value Objects And DTO Transformation

DTO-oriented decorators from @xtaskjs/value-objects that turn raw request fields into normalized domain wrappers before controllers and services consume them.

1 decorators

Decorator Group

Cache Models And Runtime Control

Configuration, model, injector, and method decorators from @xtaskjs/cache used to register cache models, inject repositories or services, and control read/write cache behavior in DI-managed services.

9 decorators

Decorator Group

HTTP And Browser Cache Policies

HTTP response decorators from @xtaskjs/cache used to apply Cache-Control directives, validators, and Vary behavior to routes, plus injector access to HttpCacheService.

7 decorators

Decorator Group

Scheduler Jobs And Lifecycle

Scheduling decorators from @xtaskjs/scheduler used to declare cron, interval, and timeout jobs and to inject runtime scheduler services.

5 decorators

Decorator Group

Throttling And Rate Limits

Rate-limiting decorators from @xtaskjs/throttler used to protect routes and inject runtime throttling services.

3 decorators

Decorator Group

Socket.IO Realtime Gateways

Gateway, event, and injector decorators exported by @xtaskjs/socket-io. These keep realtime handlers inside regular xtaskjs services and wire Socket.IO namespaces into the DI container.

8 decorators

Decorator Group

Queues And Messaging

Queue consumer, publish, and injector decorators exported by @xtaskjs/queues. These wire broker transports and in-memory queues into DI-managed services.

7 decorators

Decorator Group

HTTP Routing And Pipelines

Route declaration and request-pipeline decorators exported by @xtaskjs/common. These are the core HTTP building blocks used by controllers in every sample.

@xtaskjs/common Class decorator class

Controller

Defines the base route path for an HTTP controller and can attach shared middlewares, guards, and pipes.

Route prefix on a controller

import { Controller, Get } from "@xtaskjs/common";

@Controller("/users")
export class UsersController {
  @Get("/")
  list() {
    return [];
  }
}

@xtaskjs/common Method decorator method

Get

Registers a GET route handler and optionally adds route-specific middleware, guards, or pipes.

GET route

import { Controller, Get } from "@xtaskjs/common";

@Controller("/health")
export class HealthController {
  @Get("/")
  status() {
    return { ok: true };
  }
}

@xtaskjs/common Method decorator method

Post

Registers a POST route handler for commands, form submissions, or resource creation.

POST route

import { Controller, Post } from "@xtaskjs/common";

@Controller("/users")
export class UsersController {
  @Post("/")
  create(req: any) {
    return { email: req.body.email, created: true };
  }
}

@xtaskjs/common Method decorator method

Patch

Registers a PATCH route handler for partial updates.

PATCH route

import { Controller, Patch } from "@xtaskjs/common";

@Controller("/users")
export class UsersController {
  @Patch("/:id")
  update(req: any) {
    return { id: req.params.id, updated: true };
  }
}

@xtaskjs/common Method decorator method

Delete

Registers a DELETE route handler for removals and destructive operations.

DELETE route

import { Controller, Delete } from "@xtaskjs/common";

@Controller("/users")
export class UsersController {
  @Delete("/:id")
  remove(req: any) {
    return { id: req.params.id, removed: true };
  }
}

@xtaskjs/common Parameter decorator method parameter

Body

Binds request body data to a controller parameter and supports DTO transformation when validation pipes are enabled.

Read body payload

import { Body, Controller, Post } from "@xtaskjs/common";

class CreateUserDto {
  email!: string;
}

@Controller("/users")
export class UsersController {
  @Post("/")
  create(@Body() body: CreateUserDto) {
    return body;
  }
}

@xtaskjs/common Parameter decorator method parameter

Param

Extracts route parameters by name or as a full params object for typed handler input.

Read route params

import { Controller, Get, Param } from "@xtaskjs/common";

@Controller("/users")
export class UsersController {
  @Get("/:id")
  detail(@Param("id") id: string) {
    return { id };
  }
}

@xtaskjs/common Parameter decorator method parameter

Query

Maps query-string values to a method parameter, optionally by property name.

Read query-string filters

import { Controller, Get, Query } from "@xtaskjs/common";

@Controller("/users")
export class UsersController {
  @Get("/")
  list(@Query("role") role?: string) {
    return { role };
  }
}

@xtaskjs/common Parameter decorator method parameter

Req

Injects the adapter request object into a controller handler parameter.

Access request object

import { Controller, Get, Req } from "@xtaskjs/common";

@Controller("/auth")
export class AuthController {
  @Get("/me")
  me(@Req() req: any) {
    return { auth: req.auth };
  }
}

@xtaskjs/common Parameter decorator method parameter

Res

Injects the adapter response object into a controller handler parameter.

Access response object

import { Controller, Get, Res } from "@xtaskjs/common";

@Controller("/health")
export class HealthController {
  @Get("/")
  status(@Res() res: any) {
    return { statusCode: res.statusCode || 200 };
  }
}

@xtaskjs/common Class and method decorator class or method

UseMiddlewares

Adds one or more middlewares to a controller or route so cross-cutting logic runs before the handler.

Class-level middleware

import { Controller, Get, UseMiddlewares } from "@xtaskjs/common";

const requestLogger = async (_context: any, next: () => Promise<void>) => {
  await next();
};

@Controller("/audit")
@UseMiddlewares(requestLogger)
export class AuditController {
  @Get("/")
  list() {
    return { ok: true };
  }
}

@xtaskjs/common Class and method decorator class or method

UseGuards

Attaches guard functions to a controller or route to allow, deny, or enrich request context before execution.

Route-level guard

import { Controller, Get, UseGuards } from "@xtaskjs/common";

const adminGuard = (context: any) => context.request?.headers?.["x-role"] === "admin";

@Controller("/admin")
export class AdminController {
  @Get("/")
  @UseGuards(adminGuard)
  dashboard() {
    return { secure: true };
  }
}

@xtaskjs/common Class and method decorator class or method

UsePipes

Applies argument transformation or validation functions before a route handler consumes input.

Pipe-based payload cleanup

import { Controller, Post, UsePipes } from "@xtaskjs/common";

const trimEmailPipe = (value: any) => ({ ...value, email: String(value.email || "").trim() });

@Controller("/accounts")
export class AccountController {
  @Post("/")
  @UsePipes(trimEmailPipe)
  create(req: any) {
    return req.body;
  }
}

Decorator Group

Lifecycle Runners And Events

Lifecycle decorators from @xtaskjs/common used to run startup logic, CLI tasks, and event handlers inside the application lifecycle.

@xtaskjs/common Method decorator method

OnEvent

Registers a lifecycle event handler for a given phase and execution priority.

Lifecycle phase listener

import { OnEvent } from "@xtaskjs/common";

export class AuditListener {
  @OnEvent("AFTER_CONTROLLER_HANDLER", 10)
  afterHandler() {
    console.log("controller completed");
  }
}

@xtaskjs/common Method decorator method

ApplicationRunner

Runs a method during application startup with optional priority ordering.

Startup seed

import { ApplicationRunner } from "@xtaskjs/common";
import { Service } from "@xtaskjs/core";

@Service()
export class SeedRunner {
  @ApplicationRunner(100)
  async seed() {
    console.log("seeding application data");
  }
}

@xtaskjs/common Method decorator method

CommandLineRunner

Marks a method as a command-line lifecycle runner so it can execute in CLI-oriented flows.

CLI task

import { CommandLineRunner } from "@xtaskjs/common";
import { Service } from "@xtaskjs/core";

@Service()
export class ReportsRunner {
  @CommandLineRunner(0)
  async generate() {
    console.log("generating reports");
  }
}

Decorator Group

Core DI And Components

Dependency-injection and component decorators from @xtaskjs/core. These mark providers for container discovery and select named bindings for injection.

@xtaskjs/core Class decorator class

Component

Low-level component decorator that stores DI metadata such as scope, condition, name, and primary selection.

Custom component metadata

import { Component } from "@xtaskjs/core";

@Component({ scope: "singleton", name: "clock" })
export class ClockService {}

@xtaskjs/core Class decorator class

Service

Convenience stereotype for registering a class as a DI-managed service component.

Service stereotype

import { Service } from "@xtaskjs/core";

@Service()
export class BillingService {}

@xtaskjs/core Class decorator class

Controller

Registers a class as a controller component in the DI container. This is separate from the HTTP route decorator exported by @xtaskjs/common.

DI controller stereotype

import { Controller } from "@xtaskjs/core";

@Controller({ name: "admin-controller" })
export class AdminComponent {}

@xtaskjs/core Class decorator class

Repository

Convenience stereotype for repository-like providers managed by the DI container.

Repository stereotype

import { Repository } from "@xtaskjs/core";

@Repository()
export class UserLookupRepository {}

@xtaskjs/core Property decorator property

AutoWired / Autowired

Injects a dependency into a property. The package also exports Autowired as an alias of AutoWired.

Property injection

import { AutoWired } from "@xtaskjs/core";
import { UserService } from "./user.service";

export class AccountController {
  @AutoWired({ qualifier: UserService.name })
  private readonly users!: UserService;
}

@xtaskjs/core Parameter decorator constructor parameter

Qualifier

Selects a named binding for constructor-parameter injection when multiple implementations share the same type.

Named constructor injection

import { Qualifier, Service } from "@xtaskjs/core";

@Service()
export class NotificationService {
  constructor(@Qualifier("mailer:notifications") private readonly transport: any) {}
}

@xtaskjs/core Method decorator method

PostConstruct

Marks a method to run after dependency injection completes for the instance.

Run setup after injection

import { PostConstruct, Service } from "@xtaskjs/core";

@Service()
export class BootstrapService {
  @PostConstruct()
  init() {
    console.log("initialized");
  }
}

@xtaskjs/core Method decorator method

PreDestroy

Marks a method to run when the container destroys managed instances during shutdown.

Release resources on shutdown

import { PreDestroy, Service } from "@xtaskjs/core";

@Service()
export class WorkerService {
  @PreDestroy()
  stop() {
    console.log("stopping");
  }
}

Decorator Group

Security And Authorization

Authentication, authorization, strategy, and injector decorators exported by @xtaskjs/security. These layer on top of @xtaskjs/common route metadata.

@xtaskjs/security Class and method decorator class or method

Authenticated

Requires a successful authentication result before a controller or route executes. It can target a specific strategy or strategy list.

Protect a controller

import { Controller, Get } from "@xtaskjs/common";
import { Authenticated } from "@xtaskjs/security";

@Controller("/me")
@Authenticated()
export class ProfileController {
  @Get("/")
  profile(req: any) {
    return req.user;
  }
}

@xtaskjs/security Class and method decorator class or method

Auth

Alias of Authenticated for projects that prefer a shorter decorator name.

Alias for Authenticated

import { Auth } from "@xtaskjs/security";

@Auth(["default", "encrypted"])
export class SecureAreaController {}

@xtaskjs/security Class and method decorator class or method

Roles

Applies role-based authorization requirements to an already authenticated route.

Role-gated endpoint

import { Controller, Get } from "@xtaskjs/common";
import { Authenticated, Roles } from "@xtaskjs/security";

@Controller("/admin")
@Authenticated()
export class AdminController {
  @Get("/")
  @Roles("admin")
  dashboard() {
    return { secure: true };
  }
}

@xtaskjs/security Class and method decorator class or method

AllowAnonymous

Marks a route as publicly accessible even when the surrounding controller is authenticated by default.

Public health check

import { Controller, Get } from "@xtaskjs/common";
import { AllowAnonymous, Authenticated } from "@xtaskjs/security";

@Controller("/admin")
@Authenticated()
export class AdminController {
  @Get("/health")
  @AllowAnonymous()
  health() {
    return { ok: true };
  }
}

@xtaskjs/security Class decorator class

JwtSecurityStrategy

Decorator form of registerJwtStrategy() for registering a JWT strategy definition during module loading.

Decorator-based JWT strategy

import { JwtSecurityStrategy } from "@xtaskjs/security";

@JwtSecurityStrategy({
  name: "default",
  default: true,
  secretOrKey: process.env.JWT_SECRET,
})
export class DefaultJwtStrategy {}

@xtaskjs/security Class decorator class

JweSecurityStrategy

Decorator form of registerJweStrategy() for encrypted token flows.

Decorator-based JWE strategy

import { JweSecurityStrategy } from "@xtaskjs/security";

@JweSecurityStrategy({
  name: "encrypted",
  decryptionKey: process.env.JWE_SECRET || "secret",
})
export class EncryptedStrategy {}

@xtaskjs/security Parameter and property decorator constructor parameter or property

InjectAuthenticationService

Injects the SecurityAuthenticationService registered by the security lifecycle manager.

Inject auth service

import { Service } from "@xtaskjs/core";
import { InjectAuthenticationService, SecurityAuthenticationService } from "@xtaskjs/security";

@Service()
export class SessionAuditService {
  constructor(
    @InjectAuthenticationService()
    private readonly authentication: SecurityAuthenticationService
  ) {}
}

@xtaskjs/security Parameter and property decorator constructor parameter or property

InjectAuthorizationService

Injects the SecurityAuthorizationService used for role and permission decisions.

Inject authorization service

import { Service } from "@xtaskjs/core";
import { InjectAuthorizationService, SecurityAuthorizationService } from "@xtaskjs/security";

@Service()
export class PolicyService {
  constructor(
    @InjectAuthorizationService()
    private readonly authorization: SecurityAuthorizationService
  ) {}
}

@xtaskjs/security Parameter and property decorator constructor parameter or property

InjectPassport

Injects the configured Passport instance managed by xtaskjs security.

Inject Passport

import { Service } from "@xtaskjs/core";
import { InjectPassport } from "@xtaskjs/security";

@Service()
export class PassportInspector {
  constructor(@InjectPassport() private readonly passport: any) {}
}

@xtaskjs/security Parameter and property decorator constructor parameter or property

InjectSecurityLifecycleManager

Injects the SecurityLifecycleManager so advanced services can inspect strategies or authentication state wiring.

Inject lifecycle manager

import { Service } from "@xtaskjs/core";
import { InjectSecurityLifecycleManager } from "@xtaskjs/security";

@Service()
export class SecurityDiagnosticsService {
  constructor(@InjectSecurityLifecycleManager() private readonly lifecycle: any) {}
}

Decorator Group

Persistence And Repositories

TypeORM registration and injection decorators exported by @xtaskjs/typeorm. These bind datasources and repositories into the same DI container.

@xtaskjs/typeorm Class decorator class

TypeOrmDataSource

Registers a TypeORM datasource definition for xtask startup and shutdown management.

Register a datasource

import { TypeOrmDataSource } from "@xtaskjs/typeorm";
import { UserEntity } from "./user.entity";

@TypeOrmDataSource({
  name: "default",
  type: "sqlite",
  database: "app.sqlite",
  entities: [UserEntity],
  synchronize: true,
})
export class DatabaseConfig {}

@xtaskjs/typeorm Parameter and property decorator constructor parameter or property

InjectDataSource

Injects a named datasource instance managed by xtaskjs TypeORM integration.

Inject the default datasource

import { Service } from "@xtaskjs/core";
import { DataSource, InjectDataSource } from "@xtaskjs/typeorm";

@Service()
export class HealthQueryService {
  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
}

@xtaskjs/typeorm Parameter and property decorator constructor parameter or property

InjectRepository

Injects a TypeORM repository for a given entity and datasource name.

Inject entity repository

import { Service } from "@xtaskjs/core";
import { InjectRepository, Repository } from "@xtaskjs/typeorm";
import { UserEntity } from "./user.entity";

@Service()
export class UsersService {
  constructor(
    @InjectRepository(UserEntity)
    private readonly users: Repository<UserEntity>
  ) {}
}

@xtaskjs/typeorm Class decorator class

TypeOrmMigration

Registers a migration class in the TypeORM migration registry for a named datasource.

Register a migration

import { MigrationInterface, QueryRunner, TypeOrmMigration } from "@xtaskjs/typeorm";

@TypeOrmMigration({ dataSourceName: "default" })
export class CreateAuditEntries1700000000000 implements MigrationInterface {
  async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query("CREATE TABLE audit_entries (id integer primary key autoincrement, message varchar(120) not null)");
  }

  async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query("DROP TABLE audit_entries");
  }
}

@xtaskjs/typeorm Class decorator class

TypeOrmSeeder

Registers an ordered seeder class that runs after datasource initialization when seeders are enabled.

Register a startup seeder

import { DataSource, TypeOrmSeeder } from "@xtaskjs/typeorm";

@TypeOrmSeeder({ dataSourceName: "default", order: 1 })
export class AuditEntriesSeeder {
  async run(dataSource: DataSource): Promise<void> {
    await dataSource.query("INSERT INTO audit_entries (message) VALUES ('seeded')");
  }
}

Decorator Group

CQRS Buses, Handlers, And Projections

CQRS configuration, handler, projection, idempotency, and injector decorators exported by @xtaskjs/cqrs. These connect command, query, and event flows to the xtaskjs container and read or write datasource aliases.

@xtaskjs/cqrs Class decorator class

Cqrs

Decorator form of configureCqrs() for binding the read and write datasource aliases and optional idempotency store during module loading.

Bind read and write datasource aliases

import { Cqrs } from "@xtaskjs/cqrs";

@Cqrs({ writeDataSourceName: "write-db", readDataSourceName: "read-db" })
export class CqrsConfiguration {}

@xtaskjs/cqrs Class decorator class

CommandHandler

Registers a DI-managed class as the single handler for a command message type.

Command handler

import { Service } from "@xtaskjs/core";
import { CommandHandler, ICommandHandler } from "@xtaskjs/cqrs";

class CreateUserCommand {
  constructor(public readonly name: string) {}
}

@Service()
@CommandHandler(CreateUserCommand)
export class CreateUserHandler implements ICommandHandler<CreateUserCommand, string> {
  execute(command: CreateUserCommand) {
    return command.name;
  }
}

@xtaskjs/cqrs Class decorator class

QueryHandler

Registers a DI-managed class as the handler for a query message type.

Query handler

import { Service } from "@xtaskjs/core";
import { IQueryHandler, QueryHandler } from "@xtaskjs/cqrs";

class ListUsersQuery {}

@Service()
@QueryHandler(ListUsersQuery)
export class ListUsersHandler implements IQueryHandler<ListUsersQuery, string[]> {
  execute() {
    return ["Ada"];
  }
}

@xtaskjs/cqrs Class decorator class

EventHandler

Registers one or more event handlers that react after a message publishes an event on the CQRS event bus.

Event handler

import { Service } from "@xtaskjs/core";
import { EventHandler, IEventHandler } from "@xtaskjs/cqrs";

class UserCreatedEvent {
  constructor(public readonly id: string) {}
}

@Service()
@EventHandler(UserCreatedEvent)
export class UserProjectionHandler implements IEventHandler<UserCreatedEvent> {
  async handle(event: UserCreatedEvent) {
    console.log(event.id);
  }
}

@xtaskjs/cqrs Class decorator class

ProcessManager / Saga

Registers an orchestration component that reacts to events with access to command, query, and event buses. Saga is an alias of ProcessManager.

Event-driven orchestration

import { Service } from "@xtaskjs/core";
import { IProcessManager, ProcessManager, ProcessManagerContext } from "@xtaskjs/cqrs";

class UserCreatedEvent {
  constructor(public readonly id: string) {}
}

@Service()
@ProcessManager(UserCreatedEvent)
export class WelcomeProcessManager implements IProcessManager<UserCreatedEvent> {
  async handle(event: UserCreatedEvent, context: ProcessManagerContext) {
    await context.commandBus.execute({ userId: event.id });
  }
}

@xtaskjs/cqrs Class decorator class

ProjectionRebuilder

Registers a named projection rebuilder so operators or diagnostics flows can rebuild a read model from write-side state.

Named projection rebuilder

import { Service } from "@xtaskjs/core";
import { IProjectionRebuilder, ProjectionRebuilder } from "@xtaskjs/cqrs";

@Service()
@ProjectionRebuilder("users")
export class UserProjectionRebuilder implements IProjectionRebuilder {
  async rebuild() {
    console.log("rebuild read model");
  }
}

@xtaskjs/cqrs Class decorator class

IdempotentCommand

Adds idempotency metadata to a command handler so repeated executions can reuse a cached result instead of running the write-side action again.

Idempotent command handler

import { CommandHandler, IdempotentCommand } from "@xtaskjs/cqrs";

class CreateUserCommand {
  constructor(public readonly name: string, public readonly idempotencyKey: string) {}
}

@IdempotentCommand<CreateUserCommand>({ key: (command) => command.idempotencyKey })
@CommandHandler(CreateUserCommand)
export class CreateUserHandler {
  execute(command: CreateUserCommand) {
    return `${command.name}:${command.idempotencyKey}`;
  }
}