Decorators

Data & Database Decorators

Define database operations, transactions, isolation, consistency, read-only and tenant constraints, and ORM entity mappings with AxilJS decorators.

7 min readUpdated DocumentationEdit this page
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.

TypeScript
TS
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

OptionTypeDescription
operation'read' | 'write' | 'readwrite'Operation type
replica'primary' | 'replica' | 'auto'Connection pool routing
timeoutnumberQuery 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.

TypeScript
TS
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:

TypeScript
TS
1@tTransaction({
2  isolation: 'serializable',
3  timeout: 5000,
4})
5async processPayment(orderId: string) {}

Options

OptionTypeDescription
isolation'read-uncommitted' | 'read-committed' | 'repeatable-read' | 'serializable'Transaction isolation level
timeoutnumberTransaction 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.

TypeScript
TS
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.

TypeScript
TS
1import { tConsistent } from '@axiljs/decorator'
2
3@tConsistent('strong')
4async getBalance() {}
5
6@tConsistent('eventual')
7async getRecommendations() {}

Consistency Values

ValueDescription
'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.

TypeScript
TS
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.

TypeScript
TS
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:

SQL
SQL
WHERE tenant_id = currentTenant

This makes tenant isolation an explicit data-access requirement rather than relying entirely on individual repository implementations.

@tTenantIsolated describes 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.

TypeScript
TS
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.

TypeScript
TS
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: string

Column metadata can describe storage types and constraints required by the database consumer.

OptionTypeDescription
namestringColumn name, when it differs from the property
typestringColumn type
lengthnumberColumn length
nullablebooleanWhether NULL is allowed
uniquebooleanUnique constraint
defaultunknownDefault value
primarybooleanPart of the primary key
selectbooleanInclude the column in default selects

tPrimaryKey accepts the same options.

@tPrimaryKey

Marks a property as the entity's primary key.

TypeScript
TS
1import { tPrimaryKey } from '@axiljs/decorator'
2
3@tPrimaryKey()
4id: number

The resulting metadata can be used by an ORM or schema-management consumer when generating queries and persistence mappings.

@tRelation

Declares a relationship between entities.

TypeScript
TS
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

TypeDescription
'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

TypeScript
TS
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.

TypeScript
TS
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

DecoratorPurpose
@tDatabaseDeclares database operation and routing semantics
@tTransactionDefines a transaction boundary
@tIsolationDeclares a minimum transaction isolation level
@tConsistentDeclares a required consistency guarantee
@tReadOnlyPrevents write operations within a method
@tTenantIsolatedEnforces tenant-scoped data access
@tEntityDeclares a database entity
@tColumnMaps a property to a database column
@tPrimaryKeyDeclares an entity primary key
@tRelationDeclares an entity relationship

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY