Custom & CLI
Extend AxilJS semantic metadata with custom consumers, inspect decorator contracts from the CLI, and build framework-independent tooling.
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.
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:
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.
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:
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:
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:
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
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 TDecoratorInfoCLI Introspection
Because decorators expose structured metadata, AxilJS tooling can inspect them without executing application logic.
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.
Application Code
|
v
Semantic Decorators
|
v
Metadata Registry
|
+--------+--------+--------+--------+
| | | | |
v v v v v
HTTP ORM Security AI ObservabilityApplication 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:
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:
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:
| API | Purpose |
|---|---|
TDecoratorInfo | Describes 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?