Data & Database Decorators
Define database operations, transactions, isolation, consistency, read-only and tenant constraints, and ORM entity mappings with AxilJS decorators.
On this page14
AxilJS data decorators describe how application code interacts with persistent storage. They express database operations, transaction boundaries, consistency requirements, entity mappings, and tenant isolation as semantic metadata.
The decorators describe intent; database and ORM consumers interpret that metadata to implement the required behavior without coupling application code to a specific database driver.
@tDatabase
Declares the database operation semantics for a method.
1import { tDatabase } from '@axiljs/decorator'
2
3@tDatabase({ operation: 'read' })
4async getUser(id: string) {}
5
6@tDatabase({ operation: 'write', replica: 'primary' })
7async updateUser(id: string, data: UpdateDto) {}Options
| Option | Type | Description |
|---|---|---|
operation | 'read' | 'write' | 'readwrite' | Operation type |
replica | 'primary' | 'replica' | 'auto' | Connection pool routing |
timeout | number | Query timeout in milliseconds |
@tDatabase makes the intended database access pattern explicit. A runtime or ORM consumer can use this metadata to select an appropriate connection pool and enforce operation constraints.
@tTransaction
Defines a database transaction boundary around a method.
1import { tTransaction } from '@axiljs/decorator'
2
3@tTransaction()
4async transferFunds(from: string, to: string, amount: number) {}Transaction configuration can include isolation, timeout, and propagation behavior:
1@tTransaction({
2 isolation: 'serializable',
3 timeout: 5000,
4})
5async processPayment(orderId: string) {}Options
| Option | Type | Description |
|---|---|---|
isolation | 'read-uncommitted' | 'read-committed' | 'repeatable-read' | 'serializable' | Transaction isolation level |
timeout | number | Transaction timeout in milliseconds |
propagation | 'required' | 'requires-new' | 'nested' | 'never' | Transaction propagation behavior |
The transaction decorator expresses the boundary and requirements. The underlying transaction manager is responsible for implementing the actual database transaction.
@tIsolation
Declares a minimum transaction isolation requirement.
Use @tIsolation when the isolation requirement needs to be expressed independently from the transaction boundary.
1import { tIsolation } from '@axiljs/decorator'
2
3@tIsolation('serializable')
4async getBalance(accountId: string) {}This allows infrastructure consumers to reason about isolation requirements separately from transaction configuration.
@tConsistent
Declares the consistency guarantee required by an operation.
This is particularly useful in distributed systems where data may be replicated across multiple database nodes or read replicas.
1import { tConsistent } from '@axiljs/decorator'
2
3@tConsistent('strong')
4async getBalance() {}
5
6@tConsistent('eventual')
7async getRecommendations() {}Consistency Values
| Value | Description |
|---|---|
'strong' | Requires strong, read-your-writes consistency |
'eventual' | Allows stale reads in exchange for lower latency |
'snapshot' | Uses a point-in-time snapshot |
'bounded' | Allows bounded staleness |
The semantic requirement can be consumed by database routing or distributed data infrastructure to determine an appropriate read source.
@tReadOnly
Declares that a method must not perform write operations.
1import { tReadOnly } from '@axiljs/decorator'
2
3@tReadOnly()
4async generateReport() {}An ORM or database consumer can use this metadata to reject write queries executed within the operation.
This is useful for reporting, analytics, query services, and other operations where mutation should be explicitly prohibited.
@tTenantIsolated
Declares that database access must be scoped to the current tenant.
1import { tTenantIsolated } from '@axiljs/decorator'
2
3@tTenantIsolated()
4async findAll() {
5 return this.orderRepo.findAll()
6}A tenant-aware database consumer can apply the current tenant boundary to generated queries:
WHERE tenant_id = currentTenantThis makes tenant isolation an explicit data-access requirement rather than relying entirely on individual repository implementations.
@tTenantIsolateddescribes the isolation requirement. The database, ORM, or infrastructure consumer is responsible for enforcing it.
Entity Decorators
AxilJS also provides semantic decorators for describing database entities and their mappings.
@tEntity
Declares a class as a database entity.
1import {
2 tEntity,
3 tPrimaryKey,
4 tColumn,
5} from '@axiljs/decorator'
6
7@tEntity({ table: 'users' })
8class User {
9 @tPrimaryKey()
10 id: number
11
12 @tColumn({ type: 'varchar', length: 255 })
13 name: string
14
15 @tColumn({ unique: true })
16 email: string
17}The entity metadata describes how the application model maps to persistent storage.
@tColumn
Maps a class property to a database column.
1import { tColumn } from '@axiljs/decorator'
2
3@tColumn({ type: 'decimal(10,2)' })
4price: number
5
6@tColumn({ type: 'jsonb' })
7metadata: Record<string, any>
8
9@tColumn({ select: false })
10password: stringColumn metadata can describe storage types and constraints required by the database consumer.
| Option | Type | Description |
|---|---|---|
name | string | Column name, when it differs from the property |
type | string | Column type |
length | number | Column length |
nullable | boolean | Whether NULL is allowed |
unique | boolean | Unique constraint |
default | unknown | Default value |
primary | boolean | Part of the primary key |
select | boolean | Include the column in default selects |
tPrimaryKey accepts the same options.
@tPrimaryKey
Marks a property as the entity's primary key.
1import { tPrimaryKey } from '@axiljs/decorator'
2
3@tPrimaryKey()
4id: numberThe resulting metadata can be used by an ORM or schema-management consumer when generating queries and persistence mappings.
@tRelation
Declares a relationship between entities.
1import { tRelation } from '@axiljs/decorator'
2
3@tRelation({
4 type: 'many-to-one',
5 target: () => User,
6})
7author: User
8
9@tRelation({
10 type: 'one-to-many',
11 target: () => Post,
12 cascade: true,
13})
14posts: Post[]Relation Types
| Type | Description |
|---|---|
'one-to-one' | A single related entity |
'one-to-many' | A collection of related entities |
'many-to-one' | Multiple entities reference one entity |
'many-to-many' | A collection with a many-to-many relationship |
tRelation also accepts inverse (the inverse property name), cascade (boolean or an array of 'insert' | 'update' | 'remove'), eager and onDelete ('CASCADE' | 'SET NULL' | 'RESTRICT').
Relations remain semantic metadata, allowing the persistence layer to determine how relationships are represented and queried.
Full Entity Example
1import {
2 tEntity,
3 tPrimaryKey,
4 tColumn,
5 tRelation,
6} from '@axiljs/decorator'
7
8@tEntity({ table: 'orders' })
9class Order {
10 @tPrimaryKey()
11 id: number
12
13 @tColumn({ type: 'decimal(10,2)' })
14 total: number
15
16 @tColumn({
17 type: 'enum',
18 default: 'pending',
19 })
20 status: string
21
22 @tRelation({
23 type: 'many-to-one',
24 target: () => User,
25 })
26 customer: User
27
28 @tRelation({
29 type: 'one-to-many',
30 target: () => OrderItem,
31 cascade: true,
32 })
33 items: OrderItem[]
34}Entity decorators produce metadata that a persistence consumer can use for queries, migrations, and type-safe repositories. The same metadata can also be consumed by tooling such as database browsers, schema generators, and compliance systems.
Composing Data Semantics
Data decorators can be combined when an operation has multiple storage requirements.
1import {
2 tDatabase,
3 tTransaction,
4 tIsolation,
5 tConsistent,
6 tTenantIsolated,
7} from '@axiljs/decorator'
8
9@tDatabase({
10 operation: 'write',
11 replica: 'primary',
12})
13@tTransaction({
14 isolation: 'serializable',
15 timeout: 5000,
16})
17@tIsolation('serializable')
18@tConsistent('strong')
19@tTenantIsolated()
20async transferFunds(
21 fromAccount: string,
22 toAccount: string,
23 amount: number,
24) {
25 // Business logic
26}This separates the business operation from infrastructure implementation while making its data requirements explicit:
- The operation performs a write.
- The write is routed to the primary database.
- A transaction boundary is required.
- Serializable isolation is required.
- Strong consistency is required.
- Data access must remain tenant-isolated.
The consumer layer can interpret these semantics and translate them into the appropriate database, ORM, transaction, and routing behavior.
Data Decorator Reference
| Decorator | Purpose |
|---|---|
@tDatabase | Declares database operation and routing semantics |
@tTransaction | Defines a transaction boundary |
@tIsolation | Declares a minimum transaction isolation level |
@tConsistent | Declares a required consistency guarantee |
@tReadOnly | Prevents write operations within a method |
@tTenantIsolated | Enforces tenant-scoped data access |
@tEntity | Declares a database entity |
@tColumn | Maps a property to a database column |
@tPrimaryKey | Declares an entity primary key |
@tRelation | Declares an entity relationship |
Was this page helpful?