!Banner

$3

The db-decorators library provides a comprehensive set of TypeScript decorators and utilities for database operations. It implements the repository pattern with support for model definition, validation, identity management, and operation hooks. The library enables developers to define database models with decorators, perform CRUD operations with validation, and customize behavior during database operations through operation hooks.

> Release docs refreshed on 2025-11-26. See workdocs/reports/RELEASE_NOTES.md for ticket summaries.

$3

* Repository: An abstract base class that implements the repository pattern, providing a consistent interface for CRUD operations.
* Operation Hooks: The Repository class provides Prefix and Suffix methods for each CRUD operation, allowing you to execute custom logic before and after the main operation.
* Operation Decorators: Decorators like @onCreate, @onUpdate, @onDelete, and @onRead allow you to attach custom logic to specific repository operations.
* Context: A class for passing contextual information through the different layers of your application.
* Database-related Decorators: A set of decorators for handling common database tasks, such as defining primary keys (@id), generating values (@generated), hashing values (@hash), composing values from other properties (@composed), and managing version numbers (@version).

!Licence
!GitHub language count
!GitHub top language


!Open Issues
!Closed Issues
!Pull Requests
!Maintained

!Forks
!Stars
!Watchers

!Node Version
!NPM Version

Documentation available here

Minimal size: 8.2 KB kb gzipped

$3

The db-decorators library is a powerful TypeScript framework for database operations that leverages decorators to simplify database interactions. It provides a comprehensive solution for implementing the repository pattern with built-in support for model definition, validation, identity management, and operation hooks.

#### Key Features

1. Repository Pattern Implementation
- Abstract BaseRepository class providing the foundation for CRUD operations
- Concrete Repository class with validation support
- Support for bulk operations through the BulkCrudOperator interface

2. Model Management
- Model definition with TypeScript decorators
- Identity management with the @id() decorator
- Property composition with @composed() and @composedFromKeys() decorators
- Versioning support with the @version() decorator
- Transient properties with the @transient() decorator

3. Operation Hooks
- Pre-operation hooks with @on(), @onCreate(), @onUpdate(), etc.
- Post-operation hooks with @after(), @afterCreate(), @afterUpdate(), etc.
- Custom operation handlers through the Operations registry

4. Context Management
- Hierarchical context chains with parent-child relationships
- Context accumulation for state management
- Operation-specific context creation

5. Validation
- Integration with decorator-validation library
- Automatic validation during CRUD operations
- Custom validation rules through decorators

The library is designed to be extensible and adaptable to different database backends, providing a consistent API regardless of the underlying storage mechanism.

How to Use

This guide provides examples of how to use the main features of the @decaf-ts/db-decorators library.

Repository

The Repository class is an abstract base class that implements the repository pattern.

$3

To create a repository, you need to extend the Repository class and implement the abstract CRUD methods.

``typescript
import { Repository, Model } from '@decaf-ts/db-decorators';
import { model, id, required } from '@decaf-ts/decorator-validation';

@model()
class User extends Model {
@id()
id: string;

@required()
name: string;
}

class UserRepository extends Repository {
constructor() {
super(User);
}

async create(model: User): Promise {
// Implementation for creating a user
return model;
}

async read(key: string): Promise {
// Implementation for reading a user
return new User({ id: key, name: 'User' });
}

async update(model: User): Promise {
// Implementation for updating a user
return model;
}

async delete(key: string): Promise {
// Implementation for deleting a user
const model = await this.read(key);
return model;
}
}
`

$3

The Repository class provides Prefix and Suffix methods for each CRUD operation, allowing you to execute custom logic before and after the main operation.

`typescript
class UserRepository extends Repository {
// ...

protected async createPrefix(model: User, ...args: any[]): Promise<[User, ...any[], any]> {
console.log('Before creating user...');
return [model, ...args];
}

protected async createSuffix(model: User, context: any): Promise {
console.log('After creating user...');
return model;
}
}
`

Operation Decorators

Decorators like @onCreate, @onUpdate, @onDelete, and @onRead allow you to attach custom logic to specific repository operations.

`typescript
import { onCreate, onUpdate } from '@decaf-ts/db-decorators';

const logOnCreate = onCreate((context, data, key, model) => {
console.log(Creating model: ${model.constructor.name});
});

@model()
@logOnCreate
class Product extends Model {
// ...
}
`

Context

The Context class is used for passing contextual information through the different layers of your application.

`typescript
import { Context } from '@decaf-ts/db-decorators';

const context = new Context();
context.set('user', 'admin');

// You can then pass the context to repository methods
// userRepository.create(user, context);
`

Additional Decorators

$3

Marks a property as the primary key.

`typescript
@model()
class Product extends Model {
@id()
productId: string;
}
`

$3

Indicates that a property's value is generated by the database.

`typescript
@model()
class Order extends Model {
@id()
@generated()
orderId: number;
}
`

$3

Automatically hashes a property's value.

`typescript
@model()
class User extends Model {
@hash()
password!: string;
}
`

$3

Composes a property's value from other properties.

`typescript
@model()
class Person extends Model {
@composed(['firstName', 'lastName'], ' ')
fullName: string;

firstName: string;
lastName: string;
}
`

$3

Automatically manages a version number for optimistic locking.

`typescript
@model()
class Account extends Model {
@version()
version: number;
}
``

$3


$3


#### Languages

!TypeScript
!JavaScript
!NodeJS
!ShellScript

Getting help

If you have bug reports, questions or suggestions please create a new issue.

Contributing

I am grateful for any contributions made to this project. Please read this to get started.

Supporting

The first and easiest way you can support it is by Contributing. Even just finding a typo in the documentation is important.

Financial support is always welcome and helps keep both me and the project alive and healthy.

So if you can, if this project in any way. either by learning something or simply by helping you save precious time, please consider donating.

License

This project is released under the MIT License.

By developers, for developers...