Decorators

Custom & CLI

Extend AxilJS semantic metadata with custom consumers, inspect decorator contracts from the CLI, and build framework-independent tooling.

6 min readUpdated DocumentationEdit this page
On this page11

AxilJS decorators are designed as metadata declarations rather than framework-bound runtime components. This makes the decorator system extensible: applications and tooling can inspect the same metadata without coupling business code to a specific framework.

This page covers the decorator contract, metadata registry, custom consumers, and CLI introspection.

The Decorator Contract

Every AxilJS decorator exposes a TDecoratorInfo contract. The contract describes what the decorator means, where it can be applied, what metadata it produces, and how it composes with other decorators.

TypeScript
TS
1interface TDecoratorInfo {
2  name: string
3  description: string
4  purpose: string
5  why: string
6  whenToUse: string
7  whenNotToUse?: string
8  category: string
9  targets: Array<'class' | 'method' | 'property' | 'parameter'>
10  options?: Record<string, unknown>
11  runtimeBehavior?: string
12  metadataProduced?: string[]
13  consumedBy?: string[]
14  composesWith?: string[]
15  conflictsWith?: string[]
16  securityImpact?: string
17  performanceImpact?: string
18  examples: string[]
19}

The contract is checked when the decorator is defined: registerDecoratorInfo() throws if name, description, purpose, why, whenToUse or category is missing, or if targets or examples is empty. This gives tooling a structured representation of every semantic decorator.

The contract enables:

  • CLI introspection
  • IDE contextual tooltips
  • composition validation with validateComposition()
  • static analysis

For example:

Terminal
❯axil decorator info tDatabase

This command can explain a decorator without requiring the application to be running.

Metadata Registry

The metadata registry is the shared boundary between decorators and their consumers.

Decorators write semantic metadata to the registry. Consumers read that metadata and implement the corresponding behavior.

TypeScript
TS
1import {
2  registerMetadata,
3  getMetadata,
4  getAllMetadata,
5  hasMetadata
6} from '@axiljs/decorator'
7
8registerMetadata(
9  'tDatabase',
10  target,
11  'findUser',
12  { operation: 'read' }
13)
14
15const meta = getMetadata(
16  'tDatabase',
17  target,
18  'findUser'
19)
20
21const all = getAllMetadata(
22  target,
23  'findUser'
24)

A method can therefore expose multiple independent semantic declarations:

TypeScript
TS
1{
2  tHttp: { ... },
3  tDatabase: { ... },
4  tCache: { ... }
5}

Metadata is stored on the class prototype (or the class, for class decorators) under non-enumerable symbol keys, so it does not depend on reflect-metadata or any framework. getAllMetadata() returns a shallow copy. Parameter decorators such as tParam are read with getParamMetadata(), and getDecoratedMethods(target) lists the decorated method names.

Writing a Custom Consumer

A consumer is any component that reads AxilJS metadata and acts on it.

The built-in consumer is @axiljs/runtime, which executes tAudit, tRetry, tTimeout and tRedact / tSensitive (see Runtime). For everything else, you implement your own consumer for application-specific behavior.

A custom consumer can inspect all metadata attached to a method:

TypeScript
TS
1import { getAllMetadata } from '@axiljs/decorator'
2
3class MyConsumer {
4  scan(target: object, method: string) {
5    const meta = getAllMetadata(target, method)
6
7    if (meta.tDatabase?.operation === 'write') {
8      this.instrumentWrite(target, method)
9    }
10  }
11}

The important boundary is that the decorator does not need to know what the consumer does with its metadata. The consumer decides how that semantic declaration is interpreted.

This allows application-specific tooling such as:

  • internal policy engines
  • custom telemetry integrations
  • deployment analysis
  • architecture validation
  • code-generation tools
  • organization-specific compliance checks

Defining a Custom Decorator

defineDecorator(info, handler) registers the contract and returns a decorator; makeMetadataDecorator(info) builds one that simply stores its options:

TypeScript
TS
1import { makeMetadataDecorator, getMetadata } from '@axiljs/decorator'
2
3export const tTenantPlan = makeMetadataDecorator<{ plan: 'free' | 'pro' }>({
4  name: 'tTenantPlan',
5  description: 'Requires a tenant plan',
6  purpose: 'Records the minimum plan needed to call the method',
7  why: 'Plan gating is a business rule, not handler code',
8  whenToUse: 'On paid features',
9  category: 'Custom',
10  targets: ['method'],
11  examples: ["@tTenantPlan({ plan: 'pro' })"]
12})
13
14class Reports {
15  @tTenantPlan({ plan: 'pro' })
16  async export() {}
17}
18
19getMetadata('tTenantPlan', Reports.prototype, 'export') // { plan: 'pro' }

Composition Validation

TypeScript
TS
1import { validateComposition } from '@axiljs/decorator'
2
3const result = validateComposition(Reports.prototype, 'export')
4result.valid     // false when two applied decorators conflict
5result.errors    // conflicts from each decorator's conflictsWith
6result.warnings  // e.g. metadata with no registered TDecoratorInfo

CLI Introspection

Because decorators expose structured metadata, AxilJS tooling can inspect them without executing application logic.

Terminal
❯axil decorator info tDatabase

The full command set is axil decorator list, info, search, check, graph (pure JSON) and categories; see Decorator commands. The same catalog is available in code through listDecorators({ category }), getDecoratorInfo(name), searchDecorators(query) and listCategories().

CLI introspection is useful when you need to understand a decorator's purpose, supported targets, options, composition rules, and other contract information directly from the command line.

The same metadata model can also support IDE tooling and static analysis, allowing documentation and developer tooling to consume the decorator contract rather than relying on duplicated descriptions.

Framework-Independent Tooling

AxilJS separates declarations from consumers.

Output
TXT
Application Code
       |
       v
Semantic Decorators
       |
       v
Metadata Registry
       |
       +--------+--------+--------+--------+
       |        |        |        |        |
       v        v        v        v        v
      HTTP     ORM    Security    AI   Observability

Application code declares intent. The registry stores that intent. Independent consumers interpret the metadata.

This means a consumer can be added, removed, or replaced without changing the semantic declarations in application code.

Composing Custom Tooling with Existing Metadata

A custom consumer does not need to introduce a new decorator for every requirement. It can inspect existing semantic metadata and derive additional behavior.

For example:

TypeScript
TS
1const metadata = getAllMetadata(target, 'createOrder')
2
3if (metadata.tHttp && metadata.tAudit) {
4  this.registerAuditedEndpoint(target, 'createOrder')
5}

This preserves the separation between declarations and implementation while allowing tooling to reason about combinations of existing semantics.

Installation

Install the AxilJS decorator package:

❯npm install @axiljs/decorator
❯pnpm add @axiljs/decorator
❯yarn add @axiljs/decorator
❯bun add @axiljs/decorator

Design Principle

The AxilJS decorator system follows a simple boundary:

Decorators describe intent. The metadata registry stores intent. Consumers implement behavior.

This makes semantic metadata reusable across runtimes, tooling, and infrastructure without requiring application code to depend on a single framework implementation.

Reference

The core APIs relevant to custom tooling are:

APIPurpose
TDecoratorInfoDescribes a decorator's contract
registerMetadata()Registers semantic metadata
getMetadata()Reads metadata for a specific decorator
getAllMetadata()Reads all metadata attached to a target
hasMetadata()Checks whether metadata exists
getParamMetadata()Reads parameter-decorator metadata
getDecoratedMethods()Lists decorated method names
defineDecorator() / makeMetadataDecorator()Define a custom decorator
validateComposition()Checks conflictsWith rules
listDecorators() / getDecoratorInfo() / searchDecorators() / listCategories()Query the decorator catalog

The same registry is read by @axiljs/runtime and the axil decorator CLI, making it the integration boundary between semantic declarations and runtime behavior.

With the complete decorator documentation set, AxilJS provides semantic declarations across HTTP, security, data, reliability, concurrency, distributed systems, messaging, caching, observability, compliance, runtime behavior, AI, validation, and custom tooling.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY