0
# HibernateTS
1

2
HibernateTS is a comprehensive TypeScript ORM library for MySQL, MariaDB, and PostgreSQL databases. It provides a decorator-based approach to entity mapping, automatic change tracking, and powerful querying capabilities. The library offers seamless database operations with full type safety and relationship management.
3

4
## Package Information
5

6
- **Package Name**: hibernatets
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install hibernatets`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  table, column, primary, mapping, reference,
16
  load, save, remove,
17
  SqlCondition, Mappings,
18
  updateDatabase, intercept
19
} from "hibernatets";
20
```
21

22
For CommonJS:
23

24
```javascript
25
const {
26
  table, column, primary, mapping, reference,
27
  load, save, remove,
28
  SqlCondition, Mappings,
29
  updateDatabase, intercept
30
} = require("hibernatets");
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { table, column, primary, mapping, Mappings, load, save } from "hibernatets";
37

38
// Define entities with decorators
39
@table()
40
export class User {
41
    @primary()
42
    id: number;
43

44
    @column()
45
    name: string;
46

47
    @column({ type: "boolean" })
48
    active: boolean;
49

50
    @mapping(Mappings.OneToMany, Post, "userId")
51
    posts: Post[];
52
}
53

54
@table()
55
export class Post {
56
    @primary()
57
    id: number;
58

59
    @column()
60
    title: string;
61

62
    @column()
63
    userId: number;
64

65
    @mapping(Mappings.OneToOne, User, "id")
66
    user: User;
67
}
68

69
// Basic operations
70
async function example() {
71
    // Create and save new user
72
    const user = new User();
73
    user.name = "Alice";
74
    user.active = true;
75
    await save(user);
76

77
    // Load user with related posts
78
    const userWithPosts = await load(User, 1, [], { deep: true });
79

80
    // Query with SQL conditions
81
    const activeUsers = await load(User,
82
        new SqlCondition().column("active").equals(true)
83
    );
84

85
    // Update and save changes
86
    user.name = "Alice Smith";
87
    await save(user); // Automatically detects changes
88
}
89
```
90

91
## Architecture
92

93
HibernateTS is built around several key architectural components:
94

95
- **Decorator System**: Class and property decorators (`@table`, `@column`, `@primary`, `@mapping`) define database schema mapping
96
- **Entity Management**: Automatic change tracking and persistence with transparent lazy loading of relationships
97
- **Type Safety**: Full TypeScript integration preserving types throughout database operations
98
- **Query Builder**: Fluent `SqlCondition` API for building complex SQL queries with type safety
99
- **Multi-Database Support**: Unified API supporting MySQL, MariaDB, and PostgreSQL with adapter pattern
100
- **Relationship Mapping**: OneToOne and OneToMany relationships with deep loading capabilities
101

102
## Capabilities
103

104
### Entity Modeling
105

106
Database table and column mapping using TypeScript decorators. Define your data models with annotations that automatically generate the database schema.
107

108
```typescript { .api }
109
// Class decorators
110
function table(opts?: TableOptions): ClassDecorator;
111

112
// Property decorators
113
function column(opts?: ColumnOptions): PropertyDecorator;
114
function primary(options?: PrimaryOptions): PropertyDecorator;
115
function mapping(type: Mappings, model: any, key?: string, options?: MappingOptions): PropertyDecorator;
116
function reference(): PropertyDecorator;
117

118
interface TableOptions {
119
  name?: string;
120
  collation?: string;
121
  usePrototypeAssignInsteadOf0ArgsConstructor?: boolean;
122
  constraints?: Constraint<any>[];
123
}
124
```
125

126
[Entity Modeling](./entity-modeling.md)
127

128
### Data Operations
129

130
Core CRUD operations for loading, saving, and deleting entities with support for relationships and bulk operations.
131

132
```typescript { .api }
133
function load<T>(findClass: ConstructorClass<T>, primaryKeyOrFilter: any, parameters?: any[], options?: LoadOptions<T>): Promise<T | Array<T>>;
134

135
function save<T>(saveObjects: T | T[], options?: SaveOptions<T>): Promise<Array<number>>;
136

137
function remove<T>(object: any, opts?: DeleteOptions): Promise<number>;
138
function remove<T>(descriptor: ConstructorClass<T>, primaryId: number | Array<number>, opts?: DeleteOptions): Promise<number>;
139

140
interface LoadOptions<T> {
141
  deep?: boolean | string[] | { [key: string]: SqlCondition };
142
  skipFields?: string[];
143
  first?: boolean;
144
  idOnNonDeepOneToOne?: boolean;
145
  withShallowReferences?: boolean;
146
  db?: any;
147
  dontInterceptSetters?: boolean;
148
}
149
```
150

151
[Data Operations](./data-operations.md)
152

153
### SQL Conditions
154

155
Fluent SQL condition builder for complex queries and filtering with type-safe parameter binding.
156

157
```typescript { .api }
158
class SqlCondition {
159
  static ALL: SqlCondition;
160

161
  column(columnName: string): SqlCondition;
162
  smaller(): SqlCondition;
163
  greater(): SqlCondition;
164
  equals(value: SqlParameter): SqlCondition;
165
  and(cb: (condition: SqlCondition) => SqlCondition): SqlCondition;
166
  param(value: SqlParameter | Date): SqlCondition;
167
  now(): SqlCondition;
168
  build(params: Array<SqlParameter> | null): string;
169
  checkColumns(classRef: any): void;
170
}
171

172
type SqlParameter = string | number;
173
```
174

175
[SQL Conditions](./sql-conditions.md)
176

177
### Database Adapters
178

179
Database connectivity and adapter implementations for MySQL, MariaDB, and PostgreSQL with connection pooling.
180

181
```typescript { .api }
182
interface DataBaseBase {
183
  sqlquery<T>(cfg: any, queryString: string, params?: any[]): Promise<DatabaseResult>;
184
  selectQuery<T>(queryString: string, params?: any[]): Promise<Array<T>>;
185
  end(): Promise<void>;
186
}
187

188
interface DatabaseResult {
189
  insertId: BigInt;
190
  affectedRows: number;
191
  warningStatus: number;
192
}
193

194
// Database-specific adapters
195
class MariaDbBase extends DataBaseBase;
196
class MysqlBase extends DataBaseBase;
197
class PsqlBase extends DataBaseBase;
198
```
199

200
[Database Adapters](./database-adapters.md)
201

202
### Configuration
203

204
Database configuration, schema updates, and utility functions for entity management and persistence.
205

206
```typescript { .api }
207
function updateDatabase(modelRootPath: string, opts?: UpdateOpts): Promise<void>;
208

209
function intercept<T>(object: T, opts?: InterceptParams): void;
210

211
function getId(object: any): number;
212
function setId(object: any, id: number): void;
213
function isPersisted(object: any): boolean;
214
function getDBConfig<T>(obj: any): DataBaseConfig<T>;
215

216
interface UpdateOpts {
217
  dbPoolGenerator?: () => DataBaseBase;
218
  modelDb?: DataBaseBase;
219
}
220

221
interface InterceptParams {
222
  interceptArrayFunctions?: boolean;
223
  db?: DataBaseBase;
224
}
225
```
226

227
[Configuration](./configuration.md)
228

229
### Extended Map Utilities
230

231
Type-safe extended map implementations for managing key-value pairs with automatic JSON serialization and database persistence.
232

233
```typescript { .api }
234
class ExtendedMap<T extends ExtendedMapItem<string, any>, ValueMap> extends Map<T["key"], ExtendedMapItem<T["key"], ValueMap[T["key"]]>> {
235
  getValue<K extends T["key"]>(key: K, fallback?: ValueMap[K]): ValueMap[K];
236
  setValue<K extends T["key"]>(key: K, val: ValueMap[K]): void;
237
}
238

239
@table()
240
class ExtendedMapItem<K extends string = string, T = any> {
241
  @primary() id: number;
242
  @column() value: string;
243
  @column() key: K;
244
  parsed(): T;
245
  setStringified(value: T): void;
246
}
247
```
248

249
[Extended Map Utilities](./configuration.md#extended-map-utilities)