@decaf-ts/db-decorators
Version:
Agnostic database decorators and repository
293 lines (201 loc) • 11 kB
Markdown
### DB-Decorators: Database Operations Made Simple
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](./workdocs/reports/RELEASE_NOTES.md) for ticket summaries.
### Core Concepts
* **`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 ``, ``, ``, and `` 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 (``), generating values (``), hashing values (``), composing values from other properties (``), and managing version numbers (``).
[](https://github.com/decaf-ts/db-decorators/actions/workflows/nodejs-build-prod.yaml)
[](https://github.com/decaf-ts/db-decorators/actions/workflows/codeql-analysis.yml)[](https://github.com/decaf-ts/db-decorators/actions/workflows/snyk-analysis.yaml)
[](https://github.com/decaf-ts/db-decorators/actions/workflows/pages.yaml)
[](https://github.com/decaf-ts/db-decorators/actions/workflows/release-on-tag.yaml)
Documentation available [here](https://decaf-ts.github.io/db-decorators/)
Minimal size: 8.1 KB kb gzipped
### DB-Decorators
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 `()` decorator
- Property composition with `()` and `()` decorators
- Versioning support with the `()` decorator
- Transient properties with the `()` decorator
3. **Operation Hooks**
- Pre-operation hooks with `()`, `()`, `()`, etc.
- Post-operation hooks with `()`, `()`, `()`, 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 `-ts/db-decorators` library.
## Repository
The `Repository` class is an abstract base class that implements the repository pattern.
### Creating a Repository
To create a repository, you need to extend the `Repository` class and implement the abstract CRUD methods.
```typescript
import { Repository, Model } from '-ts/db-decorators';
import { model, id, required } from '-ts/decorator-validation';
()
class User extends Model {
()
id: string;
()
name: string;
}
class UserRepository extends Repository<User, any> {
constructor() {
super(User);
}
async create(model: User): Promise<User> {
// Implementation for creating a user
return model;
}
async read(key: string): Promise<User> {
// Implementation for reading a user
return new User({ id: key, name: 'User' });
}
async update(model: User): Promise<User> {
// Implementation for updating a user
return model;
}
async delete(key: string): Promise<User> {
// Implementation for deleting a user
const model = await this.read(key);
return model;
}
}
```
### 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.
```typescript
class UserRepository extends Repository<User, any> {
// ...
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<User> {
console.log('After creating user...');
return model;
}
}
```
## Operation Decorators
Decorators like ``, ``, ``, and `` allow you to attach custom logic to specific repository operations.
```typescript
import { onCreate, onUpdate } from '-ts/db-decorators';
const logOnCreate = onCreate((context, data, key, model) => {
console.log(`Creating model: ${model.constructor.name}`);
});
()
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 '-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
### ``
Marks a property as the primary key.
```typescript
()
class Product extends Model {
()
productId: string;
}
```
### ``
Indicates that a property's value is generated by the database.
```typescript
()
class Order extends Model {
()
()
orderId: number;
}
```
### ``
Automatically hashes a property's value.
```typescript
()
class User extends Model {
()
password!: string;
}
```
### ``
Composes a property's value from other properties.
```typescript
()
class Person extends Model {
(['firstName', 'lastName'], ' ')
fullName: string;
firstName: string;
lastName: string;
}
```
### ``
Automatically manages a version number for optimistic locking.
```typescript
()
class Account extends Model {
()
version: number;
}
```
### Related
[](https://github.com/decaf-ts/decaf-ts)
[](https://github.com/decaf-ts/decorator-validation)
[](https://github.com/decaf-ts/Reflection)
### Social
[](https://www.linkedin.com/in/decaf-ts/)
#### Languages
## Getting help
If you have bug reports, questions or suggestions please [create a new issue](https://github.com/decaf-ts/ts-workspace/issues/new/choose).
## Contributing
I am grateful for any contributions made to this project. Please read [this](./workdocs/98-Contributing.md) to get started.
## Supporting
The first and easiest way you can support it is by [Contributing](./workdocs/98-Contributing.md). 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](./LICENSE.md).
By developers, for developers...