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 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 @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).

Documentation available here

Minimal size: 9 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 @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.

Creating a Repository

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

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

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 @onCreate, @onUpdate, @onDelete, and @onRead allow you to attach custom logic to specific repository operations.

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.

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

@id

Marks a property as the primary key.

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

@generated

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

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

@hash

Automatically hashes a property's value.

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

@composed

Composes a property's value from other properties.

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

  firstName: string;
  lastName: string;
}

@version

Automatically manages a version number for optimistic locking.

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

Related

Social

Languages

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 Mozilla Public License 2.0.

By developers, for developers...