HanORM - TypeScript MySQL ORM

HanORM is a TypeScript library that provides a simple yet powerful Object-Relational Mapping (ORM) framework for MySQL databases. With HanORM, you can define and manage database entities using TypeScript classes and benefit from features such as transactions, table indexing, and query logging.

Table of Contents

1. Installation
2. Getting Started
3. Connection
4. Transactions
5. Entity Models
6. Table Operations
7. Querying

1. Installation

To use HanORM, you need to install it as a dependency in your TypeScript project:

npm install mysql2 hanorm

2. Getting Started

Start by importing HanORM and creating an instance of the HanORM class:

import { HanORM, ConnectionOptions, MySQLType } from 'hanorm';

const connectionOptions: ConnectionOptions = {
  host: 'your-database-host',
  user: 'your-database-user',
  password: 'your-database-password',
  database: 'your-database-name',
  logging: false, // default false
  sync: false // default false, Note that: Please do not set this to true for production database
};

const hanORM = new HanORM(connectionOptions);

3. Connection

3.1 Connect to the Database

To establish a connection to the database:

await hanORM.connect();

3.2 Disconnect from the Database

To disconnect from the database:

await hanORM.disconnect();

4. Transactions

4.1 Start a Transaction

const transactionConnection = await hanORM.startTransaction();

4.2 Commit a Transaction

await hanORM.commitTransaction();

4.3 Rollback a Transaction

await hanORM.rollbackTransaction();

Example: Using Transactions

try {
  // Start a transaction
  const transactionConnection = await hanORM.startTransaction();

  // Perform multiple operations within the transaction
  await userModel.create({ username: 'john_doe', email: '[email protected]' });

  const updatedUser = await userModel.update(1, { username: 'new_username' });

  // Commit the transaction if all operations are successful
  await hanORM.commitTransaction();

  console.log('Transaction committed successfully');
} catch (error) {
  // Rollback the transaction if an error occurs
  await hanORM.rollbackTransaction();
  console.error('Transaction failed. Rolling back changes:', error);
}

5. Entity Models

5.1 Create a Single Entity

const user = await userModel.create({
  username: 'john_doe',
  email: '[email protected]',
});

5.2 Create Multiple Entities

const usersData = [
  { username: 'john_doe', email: '[email protected]' },
  { username: 'jane_doe', email: '[email protected]' },
];

const createdUsers = await userModel.createMany(usersData);

5.3 Update a Single Entity by ID

const updatedUser = await userModel.update(1, { username: 'new_username' });

5.4 Update Multiple Entities by IDs

const updatedUsers = await userModel.updateMany([1, 2], { email: '[email protected]' });

5.5 Delete a Single Entity by ID

await userModel.delete(1);

5.6 Delete Multiple Entities by IDs

const userIdsToDelete = [1, 2, 3];
await userModel.deleteMany(userIdsToDelete);

5.7 Find by ID

const user = await userModel.findById(1);

5.8 Find with Conditions

const users = await userModel.find({ username: 'john_doe' });

5.9 Join Tables

5.9.1 INNER Join

const innerJoinResult = await userModel.join('INNER', 'users', 'posts', ['users.id = posts.user_id'], ['users.id', 'posts.title']);

5.9.2 LEFT Join

const leftJoinResult = await userModel.join('LEFT', 'users', 'comments', ['users.id = comments.user_id'], ['users.id', 'comments.text']);

5.9.3 RIGHT Join

const rightJoinResult = await userModel.join('RIGHT', 'users', 'orders', ['users.id = orders.user_id'], ['users.id', 'orders.total']);

5.10 Count Records

const count = await userModel.count({ username: 'john_doe' });

6. Table Operations

6.1 Indexing

6.1.1 Create Index

This example creates a unique index on the 'username' column of the 'users' table.

await hanORM.index('users', ['username'], true);

6.1.2 Drop Index

This example drops the previously created index on the 'username' column of the 'users' table.

await hanORM.dropIndex('users', 'idx_users_username');

6.2 Create Table

interface User {
  id: number;
  username: string;
  email: string;
}

const userFields: Record<keyof User, FieldDefinition> = {
  id: { type: 'INT', primary: true, autoIncrement: true },
  username: { type: 'VARCHAR', size: 255, unique: true, nullable: false },
  email: { type: 'VARCHAR', size: 255, nullable: false },
};

await hanORM.createTable<User>('users', userFields);

This example creates a 'users' table with specified fields and constraints.

6.3 Drop Table

This example drops the 'users' table.

await hanORM.dropTable('users');

7. Querying

7.1 Basic Query

This example retrieves users with the username 'john_doe'.

const users = await userModel.find({ username: 'john_doe' });

7.2 Advanced Query

This example retrieves users with the username 'john_doe', selects specific fields, paginates results, and sorts them by the 'created_at' column in descending order.

const users = await userModel.find(
  { username: 'john_doe' },
  'id, username, email',
  1,
  10,
  'created_at',
  'desc'
);

7.3 Count Records

This example counts the number of records in the 'users' table where the username is 'john_doe'.

const count = await userModel.count({ username: 'john_doe' });

People

The original author of hanorm is Ferhat Yalçın

License

MIT