@teliagen/persistence

The universal data mappers and ORM abstraction layer for Teliagen.

@teliagen/persistence provides a powerful Active Record implementation that decouples your entities from the underlying database driver. Whether you use Postgres, MySQL, or Mongo, your business logic remains robust and unchanged.

Features

• Universal Entities: Define models once using decorators (@Entity, @Column).
• Active Record: Intuitive API (User.findById, user.save()).
• Adapter System: Pluggable backends (Sequelize, TypeORM, Prisma, In-Memory).
• Rich Relationships: Built-in support for OneToOne, OneToMany, and ManyToMany.
• Microservices Ready: Define @RemoteEntity to reference data across services.

Installation

npm install @teliagen/persistence

You will also need a database adapter (e.g., @teliagen/adapter-sequelize).

Quick Start

1. Define an Entity (src/modules/users/entities/user.entity.ts)

Entities are standard TypeScript classes decorated with metadata.

import { Entity, Column, Model } from '@teliagen/persistence/entities';
import { DataType } from '@teliagen/persistence/database';

@Entity({ tableName: 'users' })
export class User extends Model {
  
  @Column({ primary: true, type: DataType.UUID, defaultValue: DataType.UUIDV4 })
  id!: string;

  @Column({ type: DataType.STRING, required: true })
  name!: string;

  @Column({ type: DataType.STRING, unique: true })
  email!: string;
}

2. Configure Adapter (src/bootstrap.ts)

Connect your application to the database.

import { TeliagenApp } from '@teliagen/server/app';
import { SequelizeAdapter } from '@teliagen/adapter-sequelize';
import { User } from './modules/users/entities/user.entity.js';

const app = new TeliagenApp();

const adapter = new SequelizeAdapter({
  dialect: 'postgres',
  host: process.env.DB_HOST,
  password: process.env.DB_PASSWORD,
  database: 'my_app'
});

// 1. Bind adapter to the Framework
app.useDataAdapter(adapter);

// 2. Register Entities
app.registerModule({
  entities: [User]
});

// 3. Sync Schema (Dev only) & Start
await app.initialize();
await adapter.connect();
await adapter.syncSchema({ alter: true });

await app.start();

3. Use Data (src/modules/users/actions/user.actions.ts)

Perform CRUD operations effortlessly.

import { ActionProvider, Action, Input } from '@teliagen/commons/actions/decorators';
import { User } from '../entities/user.entity.js';
import { CreateUserInput } from '../schemas/create-user.schema.js';

@ActionProvider({ module: 'users', name: 'UserActions' })
export class UserActions {

  @Action('create')
  async create(@Input() input: CreateUserInput) {
    // Active Record pattern
    const user = await User.create({
      name: input.name,
      email: input.email
    });
    
    return user;
  }
}

Core Concepts

Model API

Every entity extends Model, inheriting powerful static and instance methods:

• Finders: findById, findOne, findAll, count
• Mutations: create, update, destroy
• Instance: save, reload, toJSON

Associations

Define relationships clearly using decorators:

@Entity()
class Post extends Model {
  @ManyToOne(() => User)
  author!: User;
}

@Entity()
class User extends Model {
  @OneToMany(() => Post)
  posts!: Post[];
}

Documentation

For query builders, transactions, and advanced usage, visit:

docs.teliagen.org

License

Apache-2.0