@cheetah.js/orm 0.1.113 → 0.1.118

package/README.md

@@ -1,435 +1,435 @@
-# Cheetah.js ORM
-Cheetah.js ORM is a simple and powerful ORM for Cheetah.js and Bun.
-<br>We don't use any query builder like knex, we have our own query builder making us faster.
-**In development.**
-
-### Menu
-- [Installation](#install)
-- [Entities](#entities)
-  - [Value Objects](#value-objects)
-  - [Hooks](#hooks)
-- [Usage](#usage)
-- [Migrations](#migrations)
-
-### [Installation](#install)
-For install Cheetah.js ORM, run the command below:
-
-```bash
-bun install @cheetah.js/orm
-```
-Create a configuration file for the ORM in the root of the project called "cheetah.config.ts" and configure the database connection, providers and entities:
-
-```javascript
-import { PgDriver } from '@cheetah.js/orm';
-import { ConnectionSettings } from '@cheetah.js/orm/driver/driver.interface';
-
-const config: ConnectionSettings<any> = {
-  host: 'localhost',
-  port: 5432,
-  database: 'postgres',
-  username: 'postgres',
-  password: 'postgres',
-  driver: PgDriver,
-  migrationPath: 'path_migrations', 
-  entities: 'entity/*.ts' // or [User, Post, ...]
-};
-
-export default config;
-```
-Actually, the ORM only supports PostgreSQL, but in the future it will support other databases.
-- Entities: Path to entities. Accepts glob patterns or an array of Entity classes.
-- MigrationPath: Path to migrations. Accepts glob patterns. Is optional.
-<br/>
-<br/>
-After that, you need to import the ORM into the project and add it to the Cheetah.js instance:
-    
-```javascript
-import { Cheetah } from '@cheetah.js/core';
-import { CheetahOrm } from '@cheetah.js/orm';
-
-new Cheetah().use(CheetahOrm).listen();
-```
-
-### [Entities](#entities)
-Entities are classes that map to database tables. Each entity must have a primary key.
-
-#### Example:
-```javascript
-import { Entity, PrimaryKey, Property } from '@cheetah.js/orm';
-
-@Entity()
-export class User {
-  @PrimaryKey()
-  id: number;
-
-  @Property()
-  name: string;
-}
-```
-
-#### PrimaryKey
-The @PrimaryKey decorator is used to define the primary key of the entity.
-
-#### Nullable property
-For define a nullable property, add a parameter to the @Property decorator:
-
-```javascript
-@Entity()
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property({ nullable: true })
-    name: string;
-}
-```
-Cheetah ORM can also distinguish nullable properties automatically by adding the question mark to the end of the property name:
-
-```javascript
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property()
-    name?:string;
-}
-```
-
-#### Unique property
-For define a unique property, add a parameter to the @Property decorator:
-
-```javascript
-@Entity()
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property({ unique: true })
-    name: string;
-}
-```
-
-#### Index property
-For define a index for a unique property, add a parameter to the @Property decorator:
-
-```javascript
-@Entity()
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property({ index: true })
-    name: string;
-}
-```
-
-For define a index for a multiple properties, add the @Index decorator. You can use it on a property or on the class. It accepts either an array of property names (legacy) or an object with a properties field (recommended):
-
-```javascript
-@Entity()
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property()
-    name: string;
-
-    // Property-level (compound index)
-    @Index({ properties: ['name', 'email'] })
-    @Property()
-    email: string;
-}
-
-// Or, at the class level
-
-@Entity()
-@Index<{ User }>({ properties: ['name', 'email'] })
-export class User {
-  @PrimaryKey()
-  id: number;
-
-  @Property()
-  name: string;
-
-  @Property()
-  email: string;
-}
-
-// Backward compatible usage (array):
-// @Index(['name', 'email'])
-```
-
-#### Property options
-| Option | Type | Description                                                                                |
-| ------ | ---- |--------------------------------------------------------------------------------------------|
-| nullable | boolean | Defines if the property is nullable.                                                       |
-| unique | boolean | Defines if the property is unique.                                                         |
-| index | boolean | Defines if the property is index.                                                          |
-| default | any | Defines the default value of the property.                                                 |
-| length | number | Defines the length of the property.                                                        |
-| onUpdate | string | Define the action to be taken for this property when updating the entity in the database   |
-| onInsert | string | Defines the action to be taken for this property when inserting the entity in the database |
-
-#### Computed Properties
-The `@Computed` decorator allows you to define properties that are included in serialization but NOT persisted to the database. This is useful for derived values, formatted data, or any computation based on existing properties.
-
-Computed properties are evaluated when the entity is serialized (e.g., `JSON.stringify()`) and are perfect for transforming or combining existing data.
-
-##### Example:
-```javascript
-import { Entity, PrimaryKey, Property, Computed } from '@cheetah.js/orm';
-
-@Entity()
-export class Article {
-  @PrimaryKey()
-  id: number;
-
-  @Property()
-  title: string;
-
-  @Property()
-  body: string;
-
-  @Computed()
-  get excerpt() {
-    return this.body?.substring(0, 50) || '';
-  }
-
-  @Computed()
-  get titleUppercase() {
-    return this.title?.toUpperCase() || '';
-  }
-}
-```
-
-When you serialize an article:
-```javascript
-const article = await Article.create({
-  title: 'My Article',
-  body: 'This is the full body text of the article...'
-});
-
-console.log(JSON.stringify(article));
-// Output: {"id":1,"title":"My Article","body":"This is the full body text of the article...","excerpt":"This is the full body text of the article...","titleUppercase":"MY ARTICLE"}
-```
-
-**Important Notes:**
-- Computed properties are **NOT** stored in the database
-- They are evaluated during serialization (toJSON)
-- Best used with getter functions
-- Can access other properties and even other computed properties
-- Can return any JSON-serializable type (string, number, object, array, etc.)
-
-### [Hooks](#hooks)
-Cheetah ORM supports hooks for entities. The available hooks are: BeforeCreate, AfterCreate, BeforeUpdate, AfterUpdate, BeforeDelete, AfterDelete.
-Hooks is only for modify the entity, not for create, update or delete another entities statements in database.
-
-### Example:
-```javascript
-import { Entity, PrimaryKey, Property, BeforeCreate } from '@cheetah.js/orm';
-
-@Entity()
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property()
-    name: string;
-
-    @BeforeCreate()
-    static beforeCreate() {
-        this.name = 'John Doe';
-    }
-}
-```
-
-#### Value Objects
-A Value Object is an immutable type that is distinguishable only by the state of its properties. That is, unlike an Entity, which has a unique identifier and remains distinct even if its properties are otherwise identical, two Value Objects with the exact same properties can be considered equal.
-Cheetah ORM Entities support Value Objects. To define a Value Object, extends the ValueObject class:
-
-```javascript
-import { ValueObject } from '@cheetah.js/orm';
-
-export class Name extends ValueObject<string, Name> { // First type is a value scalar type, 
-    // and second is a ValueObject
-
- validate(value): boolean {
-   return value.length > 0; // Any validation
- }
-}
-
-const name = new Name('John Doe');
-const name2 = Name.from('John Doe'); // Same as above
-
-console.log(name.equals(name2)); // true
-
-```
-
-### Caching
-You can cache SELECT queries by providing the `cache` option in find methods or QueryBuilder:
-
-- `cache: true` keeps the result cached using the driver default policy
-- `cache: number` sets a TTL in milliseconds
-- `cache: Date` sets an absolute expiration date
-
-Examples:
-
-```ts
-// Cache with TTL (5 seconds)
-await repo.find({ where: { name: 'John' }, cache: 5000 });
-
-// Cache until a specific date
-await repo.find({ where: { name: 'John' }, cache: new Date(Date.now() + 60_000) });
-
-// Infinite/driver-default cache
-await repo.find({ where: { name: 'John' }, cache: true });
-```
-Is Required to implement the validate method, that returns a boolean value.
-To use the Value Object in the Entity, just add the ValueObject type to the property:
-
-```javascript
-import { Entity, PrimaryKey, Property } from '@cheetah.js/orm';
-
-@Entity()
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property()
-    name: Name;
-}
-```
-Cheetah ORM will automatically convert the Value Object to the database type and vice versa.<br>
-Important: If you value object is different from string type, you need to define the database type in the @Property decorator, because the Cheetah ORM would not know the correct type of your value object:
-
-```javascript
-import { Entity, PrimaryKey, Property } from '@cheetah.js/orm';
-
-@Entity()
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property({ type: 'json' })
-    name: Name;
-}
-```
-
-#### Relations
-Cheetah ORM supports relations between entities. The available relations are: OneToMany, ManyToOne.
-
-##### OneToMany
-The OneToMany relation is used to define a one-to-many relationship between two entities. For example, a user can have multiple posts, but a post can only have one user.
-
-```javascript
-@Entity()
-export class User {
-    @PrimaryKey()
-    id: number;
-
-    @Property()
-    name: string;
-
-    @OneToMany(() => Post, (post) => post.user)
-    posts: Post[];
-}
-```
-
-#### ManyToOne
-The owner side of the relation is the side that has the @ManyToOne decorator. The inverse side is the side that has the @OneToMany decorator. The owner side is always the side that has the foreign key.
-
-```javascript
-@Entity()
-export class Post {
-    @PrimaryKey()
-    id: number;
-
-    @Property()
-    title: string;
-
-    @ManyToOne(() => User)
-    user: User;
-}
-```
-
-### [Usage](#usage)
-#### Create a new entity
-```javascript
-import { User } from './entity/user';
-
-const user = User.create({ name: 'John Doe' });
-
-// OR
-const user = new User();
-user.name = 'John Doe';
-await user.save();
-```
-
-#### Find a entity
-```javascript
-import { User } from './entity/user';
-
-const user = await User.findOne({ 
-    name: 'John Doe',
-    old: { $gte: 16, $lte: 30 }
-});
-```
-
-#### Transactions
-```typescript
-import { Orm } from '@cheetah.js/orm';
-
-const orm = Orm.getInstance();
-
-await orm.transaction(async (tx) => {
-  await tx`INSERT INTO users (name) VALUES (${ 'Jane Doe' })`;
-  await tx`UPDATE accounts SET balance = balance - 100 WHERE user_id = ${ 1 }`;
-});
-```
-The `transaction` method leverages the active driver implementation, ensuring consistent transactional semantics across supported databases.
-
-#### List of supported operators
-| Operator |Name | Description |
-| ------ | ---- |--------------------------------------------------------------------------------------------|
-| $eq | Equal | Matches values that are equal to a specified value. |
-| $gt | Greater Than | Matches values that are greater than a specified value. |
-| $gte | Greater Than or Equal | Matches values that are greater than or equal to a specified value. |
-| $in | In | Matches any of the values specified in an array. |
-| $lt | Less Than | Matches values that are less than a specified value. |
-| $lte | Less Than or Equal | Matches values that are less than or equal to a specified value. |
-| $ne | Not Equal | Matches all values that are not equal to a specified value. |
-| $nin | Not In | Matches none of the values specified in an array. |
-| $and | And | Joins query clauses with a logical AND returns all documents that match the conditions of both clauses. |
- | $or | Or | Joins query clauses with a logical OR returns all documents that match the conditions of either clause. |
-| $not | Not | Inverts the effect of a query expression and returns documents that do not match the query expression. |
-
-#### Filter by Date columns
-You can filter using JavaScript `Date` instances and the ORM translates them into precise SQL comparisons:
-
-```typescript
-const reinforcement = await User.findOne({
-  updatedAt: new Date('2024-06-01T00:00:00.000Z'),
-});
-```
-
-### [Migrations](#migrations)
-Cheetah ORM is capable of creating and running migrations.
-To do this, you need to install our cli package:
-
-```bash
-bun install @cheetah.js/cli
-```
-
-You must have the connection configuration file in the project root "cheetah.config.ts".
-To create a migration, run the command below:
-
-```bash
-bunx cli migration:generate
-```
-This command will create a migration file in the path defined in the configuration file, differentiating your entities created with the database.
-
-#### Example:
-```bash
-bunx cli cheetah-orm migration:run
-```
-This command will run all migrations that have not yet been run.
+# Cheetah.js ORM
+Cheetah.js ORM is a simple and powerful ORM for Cheetah.js and Bun.
+<br>We don't use any query builder like knex, we have our own query builder making us faster.
+**In development.**
+
+### Menu
+- [Installation](#install)
+- [Entities](#entities)
+  - [Value Objects](#value-objects)
+  - [Hooks](#hooks)
+- [Usage](#usage)
+- [Migrations](#migrations)
+
+### [Installation](#install)
+For install Cheetah.js ORM, run the command below:
+
+```bash
+bun install @cheetah.js/orm
+```
+Create a configuration file for the ORM in the root of the project called "cheetah.config.ts" and configure the database connection, providers and entities:
+
+```javascript
+import { PgDriver } from '@cheetah.js/orm';
+import { ConnectionSettings } from '@cheetah.js/orm/driver/driver.interface';
+
+const config: ConnectionSettings<any> = {
+  host: 'localhost',
+  port: 5432,
+  database: 'postgres',
+  username: 'postgres',
+  password: 'postgres',
+  driver: PgDriver,
+  migrationPath: 'path_migrations', 
+  entities: 'entity/*.ts' // or [User, Post, ...]
+};
+
+export default config;
+```
+Actually, the ORM only supports PostgreSQL, but in the future it will support other databases.
+- Entities: Path to entities. Accepts glob patterns or an array of Entity classes.
+- MigrationPath: Path to migrations. Accepts glob patterns. Is optional.
+<br/>
+<br/>
+After that, you need to import the ORM into the project and add it to the Cheetah.js instance:
+    
+```javascript
+import { Cheetah } from '@cheetah.js/core';
+import { CheetahOrm } from '@cheetah.js/orm';
+
+new Cheetah().use(CheetahOrm).listen();
+```
+
+### [Entities](#entities)
+Entities are classes that map to database tables. Each entity must have a primary key.
+
+#### Example:
+```javascript
+import { Entity, PrimaryKey, Property } from '@cheetah.js/orm';
+
+@Entity()
+export class User {
+  @PrimaryKey()
+  id: number;
+
+  @Property()
+  name: string;
+}
+```
+
+#### PrimaryKey
+The @PrimaryKey decorator is used to define the primary key of the entity.
+
+#### Nullable property
+For define a nullable property, add a parameter to the @Property decorator:
+
+```javascript
+@Entity()
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property({ nullable: true })
+    name: string;
+}
+```
+Cheetah ORM can also distinguish nullable properties automatically by adding the question mark to the end of the property name:
+
+```javascript
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property()
+    name?:string;
+}
+```
+
+#### Unique property
+For define a unique property, add a parameter to the @Property decorator:
+
+```javascript
+@Entity()
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property({ unique: true })
+    name: string;
+}
+```
+
+#### Index property
+For define a index for a unique property, add a parameter to the @Property decorator:
+
+```javascript
+@Entity()
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property({ index: true })
+    name: string;
+}
+```
+
+For define a index for a multiple properties, add the @Index decorator. You can use it on a property or on the class. It accepts either an array of property names (legacy) or an object with a properties field (recommended):
+
+```javascript
+@Entity()
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property()
+    name: string;
+
+    // Property-level (compound index)
+    @Index({ properties: ['name', 'email'] })
+    @Property()
+    email: string;
+}
+
+// Or, at the class level
+
+@Entity()
+@Index<{ User }>({ properties: ['name', 'email'] })
+export class User {
+  @PrimaryKey()
+  id: number;
+
+  @Property()
+  name: string;
+
+  @Property()
+  email: string;
+}
+
+// Backward compatible usage (array):
+// @Index(['name', 'email'])
+```
+
+#### Property options
+| Option | Type | Description                                                                                |
+| ------ | ---- |--------------------------------------------------------------------------------------------|
+| nullable | boolean | Defines if the property is nullable.                                                       |
+| unique | boolean | Defines if the property is unique.                                                         |
+| index | boolean | Defines if the property is index.                                                          |
+| default | any | Defines the default value of the property.                                                 |
+| length | number | Defines the length of the property.                                                        |
+| onUpdate | string | Define the action to be taken for this property when updating the entity in the database   |
+| onInsert | string | Defines the action to be taken for this property when inserting the entity in the database |
+
+#### Computed Properties
+The `@Computed` decorator allows you to define properties that are included in serialization but NOT persisted to the database. This is useful for derived values, formatted data, or any computation based on existing properties.
+
+Computed properties are evaluated when the entity is serialized (e.g., `JSON.stringify()`) and are perfect for transforming or combining existing data.
+
+##### Example:
+```javascript
+import { Entity, PrimaryKey, Property, Computed } from '@cheetah.js/orm';
+
+@Entity()
+export class Article {
+  @PrimaryKey()
+  id: number;
+
+  @Property()
+  title: string;
+
+  @Property()
+  body: string;
+
+  @Computed()
+  get excerpt() {
+    return this.body?.substring(0, 50) || '';
+  }
+
+  @Computed()
+  get titleUppercase() {
+    return this.title?.toUpperCase() || '';
+  }
+}
+```
+
+When you serialize an article:
+```javascript
+const article = await Article.create({
+  title: 'My Article',
+  body: 'This is the full body text of the article...'
+});
+
+console.log(JSON.stringify(article));
+// Output: {"id":1,"title":"My Article","body":"This is the full body text of the article...","excerpt":"This is the full body text of the article...","titleUppercase":"MY ARTICLE"}
+```
+
+**Important Notes:**
+- Computed properties are **NOT** stored in the database
+- They are evaluated during serialization (toJSON)
+- Best used with getter functions
+- Can access other properties and even other computed properties
+- Can return any JSON-serializable type (string, number, object, array, etc.)
+
+### [Hooks](#hooks)
+Cheetah ORM supports hooks for entities. The available hooks are: BeforeCreate, AfterCreate, BeforeUpdate, AfterUpdate, BeforeDelete, AfterDelete.
+Hooks is only for modify the entity, not for create, update or delete another entities statements in database.
+
+### Example:
+```javascript
+import { Entity, PrimaryKey, Property, BeforeCreate } from '@cheetah.js/orm';
+
+@Entity()
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property()
+    name: string;
+
+    @BeforeCreate()
+    static beforeCreate() {
+        this.name = 'John Doe';
+    }
+}
+```
+
+#### Value Objects
+A Value Object is an immutable type that is distinguishable only by the state of its properties. That is, unlike an Entity, which has a unique identifier and remains distinct even if its properties are otherwise identical, two Value Objects with the exact same properties can be considered equal.
+Cheetah ORM Entities support Value Objects. To define a Value Object, extends the ValueObject class:
+
+```javascript
+import { ValueObject } from '@cheetah.js/orm';
+
+export class Name extends ValueObject<string, Name> { // First type is a value scalar type, 
+    // and second is a ValueObject
+
+ validate(value): boolean {
+   return value.length > 0; // Any validation
+ }
+}
+
+const name = new Name('John Doe');
+const name2 = Name.from('John Doe'); // Same as above
+
+console.log(name.equals(name2)); // true
+
+```
+
+### Caching
+You can cache SELECT queries by providing the `cache` option in find methods or QueryBuilder:
+
+- `cache: true` keeps the result cached using the driver default policy
+- `cache: number` sets a TTL in milliseconds
+- `cache: Date` sets an absolute expiration date
+
+Examples:
+
+```ts
+// Cache with TTL (5 seconds)
+await repo.find({ where: { name: 'John' }, cache: 5000 });
+
+// Cache until a specific date
+await repo.find({ where: { name: 'John' }, cache: new Date(Date.now() + 60_000) });
+
+// Infinite/driver-default cache
+await repo.find({ where: { name: 'John' }, cache: true });
+```
+Is Required to implement the validate method, that returns a boolean value.
+To use the Value Object in the Entity, just add the ValueObject type to the property:
+
+```javascript
+import { Entity, PrimaryKey, Property } from '@cheetah.js/orm';
+
+@Entity()
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property()
+    name: Name;
+}
+```
+Cheetah ORM will automatically convert the Value Object to the database type and vice versa.<br>
+Important: If you value object is different from string type, you need to define the database type in the @Property decorator, because the Cheetah ORM would not know the correct type of your value object:
+
+```javascript
+import { Entity, PrimaryKey, Property } from '@cheetah.js/orm';
+
+@Entity()
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property({ type: 'json' })
+    name: Name;
+}
+```
+
+#### Relations
+Cheetah ORM supports relations between entities. The available relations are: OneToMany, ManyToOne.
+
+##### OneToMany
+The OneToMany relation is used to define a one-to-many relationship between two entities. For example, a user can have multiple posts, but a post can only have one user.
+
+```javascript
+@Entity()
+export class User {
+    @PrimaryKey()
+    id: number;
+
+    @Property()
+    name: string;
+
+    @OneToMany(() => Post, (post) => post.user)
+    posts: Post[];
+}
+```
+
+#### ManyToOne
+The owner side of the relation is the side that has the @ManyToOne decorator. The inverse side is the side that has the @OneToMany decorator. The owner side is always the side that has the foreign key.
+
+```javascript
+@Entity()
+export class Post {
+    @PrimaryKey()
+    id: number;
+
+    @Property()
+    title: string;
+
+    @ManyToOne(() => User)
+    user: User;
+}
+```
+
+### [Usage](#usage)
+#### Create a new entity
+```javascript
+import { User } from './entity/user';
+
+const user = User.create({ name: 'John Doe' });
+
+// OR
+const user = new User();
+user.name = 'John Doe';
+await user.save();
+```
+
+#### Find a entity
+```javascript
+import { User } from './entity/user';
+
+const user = await User.findOne({ 
+    name: 'John Doe',
+    old: { $gte: 16, $lte: 30 }
+});
+```
+
+#### Transactions
+```typescript
+import { Orm } from '@cheetah.js/orm';
+
+const orm = Orm.getInstance();
+
+await orm.transaction(async (tx) => {
+  await tx`INSERT INTO users (name) VALUES (${ 'Jane Doe' })`;
+  await tx`UPDATE accounts SET balance = balance - 100 WHERE user_id = ${ 1 }`;
+});
+```
+The `transaction` method leverages the active driver implementation, ensuring consistent transactional semantics across supported databases.
+
+#### List of supported operators
+| Operator |Name | Description |
+| ------ | ---- |--------------------------------------------------------------------------------------------|
+| $eq | Equal | Matches values that are equal to a specified value. |
+| $gt | Greater Than | Matches values that are greater than a specified value. |
+| $gte | Greater Than or Equal | Matches values that are greater than or equal to a specified value. |
+| $in | In | Matches any of the values specified in an array. |
+| $lt | Less Than | Matches values that are less than a specified value. |
+| $lte | Less Than or Equal | Matches values that are less than or equal to a specified value. |
+| $ne | Not Equal | Matches all values that are not equal to a specified value. |
+| $nin | Not In | Matches none of the values specified in an array. |
+| $and | And | Joins query clauses with a logical AND returns all documents that match the conditions of both clauses. |
+ | $or | Or | Joins query clauses with a logical OR returns all documents that match the conditions of either clause. |
+| $not | Not | Inverts the effect of a query expression and returns documents that do not match the query expression. |
+
+#### Filter by Date columns
+You can filter using JavaScript `Date` instances and the ORM translates them into precise SQL comparisons:
+
+```typescript
+const reinforcement = await User.findOne({
+  updatedAt: new Date('2024-06-01T00:00:00.000Z'),
+});
+```
+
+### [Migrations](#migrations)
+Cheetah ORM is capable of creating and running migrations.
+To do this, you need to install our cli package:
+
+```bash
+bun install @cheetah.js/cli
+```
+
+You must have the connection configuration file in the project root "cheetah.config.ts".
+To create a migration, run the command below:
+
+```bash
+bunx cli migration:generate
+```
+This command will create a migration file in the path defined in the configuration file, differentiating your entities created with the database.
+
+#### Example:
+```bash
+bunx cli cheetah-orm migration:run
+```
+This command will run all migrations that have not yet been run.

package/dist/driver/bun-driver.base.d.ts

@@ -12,6 +12,7 @@ export declare abstract class BunDriverBase implements Partial<DriverInterface>
     protected validateConnection(): Promise<void>;
     disconnect(): Promise<void>;
     executeSql(sqlString: string): Promise<any>;
+    private getExecutionContext;
     transaction<T>(callback: (tx: SQL) => Promise<T>): Promise<T>;
     protected toDatabaseValue(value: unknown): string | number | boolean;
     protected escapeString(value: string): string;

package/dist/driver/bun-driver.base.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BunDriverBase = void 0;
 const bun_1 = require("bun");
+const transaction_context_1 = require("../transaction/transaction-context");
 class BunDriverBase {
     constructor(options) {
         this.connectionString = this.buildConnectionString(options);
@@ -31,10 +32,18 @@ class BunDriverBase {
         await this.sql.close();
     }
     async executeSql(sqlString) {
+        const context = this.getExecutionContext();
+        return await context.unsafe(sqlString);
+    }
+    getExecutionContext() {
+        const txContext = transaction_context_1.transactionContext.getContext();
+        if (txContext) {
+            return txContext;
+        }
         if (!this.sql) {
             throw new Error('Database not connected');
         }
-        return await this.sql.unsafe(sqlString);
+        return this.sql;
     }
     async transaction(callback) {
         if (!this.sql) {
@@ -119,13 +128,14 @@ class BunDriverBase {
     }
     async executeStatement(statement) {
         const startTime = Date.now();
+        const context = this.getExecutionContext();
         if (statement.statement === 'insert') {
             const sql = this.buildInsertSqlWithReturn(statement);
-            const result = await this.sql.unsafe(sql);
+            const result = await context.unsafe(sql);
             return this.handleInsertReturn(statement, result, sql, startTime);
         }
         const sql = this.buildStatementSql(statement);
-        const result = await this.sql.unsafe(sql);
+        const result = await context.unsafe(sql);
         return {
             query: { rows: Array.isArray(result) ? result : [] },
             startTime,

package/dist/index.d.ts

@@ -22,3 +22,4 @@ export * from './common/value-object';
 export * from './common/email.vo';
 export * from './common/uuid';
 export * from './repository/Repository';
+export { transactionContext } from './transaction/transaction-context';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EntityStorage = void 0;
+exports.transactionContext = exports.EntityStorage = void 0;
 __exportStar(require("./decorators/entity.decorator"), exports);
 __exportStar(require("./decorators/property.decorator"), exports);
 __exportStar(require("./decorators/primary-key.decorator"), exports);
@@ -39,3 +39,5 @@ __exportStar(require("./common/value-object"), exports);
 __exportStar(require("./common/email.vo"), exports);
 __exportStar(require("./common/uuid"), exports);
 __exportStar(require("./repository/Repository"), exports);
+var transaction_context_1 = require("./transaction/transaction-context");
+Object.defineProperty(exports, "transactionContext", { enumerable: true, get: function () { return transaction_context_1.transactionContext; } });

package/dist/orm.js

@@ -14,6 +14,7 @@ exports.Orm = void 0;
 const core_1 = require("@cheetah.js/core");
 const SqlBuilder_1 = require("./SqlBuilder");
 const query_cache_manager_1 = require("./cache/query-cache-manager");
+const transaction_context_1 = require("./transaction/transaction-context");
 let Orm = Orm_1 = class Orm {
     constructor(logger, cacheService) {
         this.logger = logger;
@@ -47,7 +48,9 @@ let Orm = Orm_1 = class Orm {
         if (!this.driverInstance) {
             throw new Error('Driver instance not initialized');
         }
-        return this.driverInstance.transaction(operation);
+        return this.driverInstance.transaction(async (tx) => {
+            return transaction_context_1.transactionContext.run(tx, () => operation(tx));
+        });
     }
 };
 exports.Orm = Orm;

package/dist/orm.service.js

@@ -285,7 +285,7 @@ let OrmService = class OrmService {
         for (const entity of entities) {
             const nullableDefaultEntity = this.allEntities.get(entity.target.name);
             const propertiesFromMetadata = core_1.Metadata.get(constants_1.PROPERTIES_METADATA, entity.target);
-            const relationship = core_1.Metadata.get(constants_1.PROPERTIES_RELATIONS, entity.target);
+            const relationshipsFromMetadata = core_1.Metadata.get(constants_1.PROPERTIES_RELATIONS, entity.target) || [];
             const hooks = core_1.Metadata.get(constants_1.EVENTS_METADATA, entity.target);
             // Cria uma cópia profunda das propriedades para evitar mutação compartilhada
             const properties = {};
@@ -305,7 +305,14 @@ let OrmService = class OrmService {
                     properties[property].options.default = nullableDefaultEntity?.defaults[property];
                 }
             }
-            this.storage.add(entity, properties, relationship, hooks);
+            const relationships = relationshipsFromMetadata.map((relation) => ({ ...relation }));
+            for (const relation of relationships) {
+                const relationKey = String(relation.propertyKey);
+                if (nullableDefaultEntity?.nullables.includes(relationKey)) {
+                    relation.nullable = true;
+                }
+            }
+            this.storage.add(entity, properties, relationships, hooks);
         }
     }
     getSourceFilePaths() {

package/dist/transaction/transaction-context.d.ts

@@ -0,0 +1,10 @@
+import { SQL } from 'bun';
+declare class TransactionContextManager {
+    private storage;
+    constructor();
+    run<T>(tx: SQL, callback: () => Promise<T>): Promise<T>;
+    getContext(): SQL | undefined;
+    hasContext(): boolean;
+}
+export declare const transactionContext: TransactionContextManager;
+export {};

package/dist/transaction/transaction-context.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transactionContext = void 0;
+const async_hooks_1 = require("async_hooks");
+class TransactionContextManager {
+    constructor() {
+        this.storage = new async_hooks_1.AsyncLocalStorage();
+    }
+    run(tx, callback) {
+        return this.storage.run({ tx }, callback);
+    }
+    getContext() {
+        return this.storage.getStore()?.tx;
+    }
+    hasContext() {
+        return this.storage.getStore() !== undefined;
+    }
+}
+exports.transactionContext = new TransactionContextManager();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cheetah.js/orm",
-  "version": "0.1.113",
+  "version": "0.1.118",
   "description": "A simple ORM for Cheetah.js",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -55,5 +55,5 @@
     "bun",
     "value-object"
   ],
-  "gitHead": "439b0bb37b4f7b81d2aebf4171ba27792062d762"
+  "gitHead": "d5b23c4d1d3d720a93e3e157e658b8e57c828251"
 }

package/build.d.ts

@@ -1 +0,0 @@
-export {};

package/cheetah.config.d.ts

@@ -1,3 +0,0 @@
-import { ConnectionSettings } from '@cheetah.js/orm/driver/driver.interface';
-declare const config: ConnectionSettings<any>;
-export default config;