baracota-node-db

TypeScript ORM Package

A modern, type-safe ORM for Node.js with support for MySQL and SQLite databases, featuring:

• TypeScript-first design - Full type safety throughout your data layer
• Multi-database support - Works with MySQL and SQLite (easily extensible)
• Active Record pattern - Simple model definitions with relationships
• Declarative syntax - Decorator-based model configuration
• Transactions - Easy transaction management
• Soft deletes - Non-destructive deletion with recovery
• Hooks/validation - Lifecycle hooks and data validation

Installation

npm install baracota-node-db mysql2  # For MySQL
# or
npm install baracota-node-db sqlite3 # For SQLite

Quick Start

1. Initialize the ORM

import { initORM } from 'baracota-node-db';

// Initialize with MySQL
await initORM({
  client: 'mysql',
  connection: {
    host: 'localhost',
    user: 'root',
    password: '',
    database: 'test'
  }
});

// Or with SQLite
await initORM({
  client: 'sqlite',
  connection: {
    filename: './database.sqlite'
  }
});

2. Define a Model

Using Decorators (Recommended)

import { Model, PrimaryKey, Fields, HasMany } from 'baracota-node-db';

@Model('users')
@Fields(['id', 'name', 'email'])
class User extends BaseModel {
  @PrimaryKey('user_id')
  id: number;

  @HasMany()
  posts: Post[];
}

@Model('posts')
@Fields(['id', 'title', 'content', 'user_id'])
class Post extends BaseModel {
  // Model methods...
}

Using Traditional Syntax

class User extends BaseModel {
  protected table = 'users';
  protected primaryKey = 'id';
  protected allowedFields = ['id', 'name', 'email'];
  
  // Define relationships
  static {
    this.hasMany(Post, 'user_id');
  }
}

3. Use Your Models

// Create a user
const userId = await User.insert({
  name: 'John Doe',
  email: '[e-mail]'
});

// Find with relationships
const user = await User.with('posts').find(userId);
console.log(user.posts);

// Complex query
const activeUsers = await User
  .where('status', 'active')
  .where('created_at', '>', new Date('2023-01-01'))
  .orderBy('name', 'ASC')
  .limit(10)
  .get();

// Transaction
await transaction(async (trx) => {
  const user = new User(trx);
  const post = new Post(trx);
  
  const userId = await user.insert({ name: 'Alice' });
  await post.insert({ title: 'First Post', user_id: userId });
});

Key Features

Database Support

Feature	MySQL	SQLite
CRUD	✅	✅
Transactions	✅	✅
Relations	✅	✅
Soft Deletes	✅	✅

Decorator Reference

Decorator	Description	Example
@Model()	Defines table name	@Model('users')
@Fields()	Whitelists allowed fields	@Fields(['id', 'name'])
@PrimaryKey()	Specifies primary key	@PrimaryKey('user_id')
@HasMany()	Defines 1-to-many relationship	@HasMany()
@BelongsTo()	Defines many-to-1 relationship	@BelongsTo()
@BeforeCreate	Lifecycle hook before creation	@BeforeCreate()

Query Methods

// Basic queries
Model.find(id)
Model.findAll()
Model.insert(data)
Model.update(id, data)
Model.delete(id)

// Query builder
Model.where(field, value)
Model.whereIn(field, values)
Model.orderBy(field, direction)
Model.limit(count)
Model.offset(count)

// Advanced
Model.with(relations) // Eager load
Model.transaction(callback) // Run in transaction
Model.softDelete() // Mark as deleted
Model.restore() // Unmark as deleted

Configuration Options

Initialize with these options:

await initORM({
  client: 'mysql' | 'sqlite',
  connection: {
    // MySQL
    host?: string,
    user?: string,
    password?: string,
    database?: string,
    port?: number,
    
    // SQLite
    filename?: string
  },
  pool?: {
    min?: number,
    max?: number
  },
  modelDefaults?: {
    timestamps?: boolean,
    createdAt?: string,
    updatedAt?: string,
    softDeletes?: boolean,
    deletedAt?: string
  }
});

Testing

// Test setup
beforeAll(async () => {
  await initORM({
    client: 'sqlite',
    connection: { filename: ':memory:' } // In-memory database
  });
});

// Example test
test('create user', async () => {
  const id = await User.insert({ name: 'Test' });
  const user = await User.find(id);
  expect(user.name).toBe('Test');
});

Migration Guide

From v1 to v2

• Replace direct BaseModel.initialize() with initORM()
• Update config format to new structure
• Decorators are now optional but recommended

Contributing

• Fork the repository
• Create feature branch (git checkout -b feature/fooBar)
• Commit changes (git commit -am 'Add some fooBar')
• Push to branch (git push origin feature/fooBar)
• Create new Pull Request

License

MIT © M.S.B