stabilize-orm 1.1.7 → 1.2.0

package/README.md

@@ -4,24 +4,27 @@ _A Modern, Type-Safe, and Expressive ORM for Bun, Node.js, and Deno_
 
 ---
 
-**Stabilize** is a lightweight, feature-rich ORM designed for performance and developer experience. It provides a unified, database-agnostic API for **PostgreSQL**, **MySQL**, and **SQLite**, powered by a robust query builder, an elegant decorator-based model system, and a full-featured command-line interface.
+**Stabilize** is a lightweight, feature-rich ORM designed for performance and developer experience. It provides a unified, database-agnostic API for **PostgreSQL**, **MySQL**, and **SQLite**. Powered by a robust query builder, elegant decorator-based models, automatic versioning, and a full-featured command-line interface, Stabilize is built to scale with your app.
 
 ---
 
 ## 🚀 Features
 
--   **Unified API**: Write once, run against PostgreSQL, MySQL, or SQLite.
--   **Type-Safe Decorators**: Define models and columns with the powerful `DataTypes` enum for true database-agnostic schemas.
--   **Full-Featured CLI**: Generate models, manage migrations, seed data, and reset your database from the command line.
--   **Automatic Migrations**: Generate database-specific SQL schemas directly from your model definitions.
--   **Retry Logic**: Automatic exponential backoff for database queries to handle transient connection issues.
--   **Connection Pooling**: Efficient connection management for PostgreSQL and MySQL out of the box.
--   **Transactional Integrity**: Built-in support for atomic transactions with automatic rollback on failure.
--   **Advanced Query Builder**: A fluent, chainable API for building complex queries with joins, where clauses, ordering, and pagination.
--   **Model Relationships**: Define `OneToOne`, `ManyToOne`, `OneToMany`, and `ManyToMany` relationships with simple decorators.
--   **Pluggable Logging**: Includes a robust `ConsoleLogger` with support for file-based, rotating logs.
--   **Custom Errors**: `StabilizeError` provides clear, consistent error handling.
--   **Caching Layer**: Optional Redis-backed caching with `cache-aside` and `write-through` strategies.
+- **Unified API**: Write once, run on PostgreSQL, MySQL, or SQLite.
+- **Type-Safe Decorators**: Define models and columns with the powerful `DataTypes` enum for true database-agnostic schemas.
+- **Full-Featured CLI**: Generate models, manage migrations, seed data, and reset your database from the command line.
+- **Automatic Migrations**: Generate database-specific SQL schemas directly from your model definitions.
+- **Versioned Models & Time-Travel**: Add `@Versioned()` to your models for automatic history tables and snapshot queries.
+- **Retry Logic**: Automatic exponential backoff for database queries to handle transient connection issues.
+- **Connection Pooling**: Efficient connection management for PostgreSQL and MySQL.
+- **Transactional Integrity**: Built-in support for atomic transactions with automatic rollback on failure.
+- **Advanced Query Builder**: Fluent, chainable API for building complex queries, including joins, filters, ordering, and pagination.
+- **Model Relationships**: Use `OneToOne`, `ManyToOne`, `OneToMany`, and `ManyToMany` decorators for relationships.
+- **Soft Deletes**: Add `@SoftDelete()` to your model for transparent "deleted" flags and safe row removal.
+- **Lifecycle Hooks**: Use the `@Hook()` decorator for model lifecycle events like `beforeCreate`, `afterUpdate`, etc.
+- **Pluggable Logging**: Includes a robust `ConsoleLogger` with support for file-based, rotating logs.
+- **Custom Errors**: `StabilizeError` provides clear, consistent error handling.
+- **Caching Layer**: Optional Redis-backed caching with `cache-aside` and `write-through` strategies.
 
 ---
 
@@ -41,13 +44,13 @@ npm install stabilize-orm reflect-metadata
 
 ## 📃 Documentation & Community
 
--   [Changelog](./CHANGELOG.md)
--   [License](./LICENSE.md)
--   [Code of Conduct](./CODE_OF_CONDUCT.md)
--   [Contributing Guide](./CONTRIBUTING.md)
--   [Security Policy](./SECURITY.md)
--   [Support](./SUPPORT.md)
--   [Funding](./FUNDING.md)
+- [Changelog](./CHANGELOG.md)
+- [License](./LICENSE.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Contributing Guide](./CONTRIBUTING.md)
+- [Security Policy](./SECURITY.md)
+- [Support](./SUPPORT.md)
+- [Funding](./FUNDING.md)
 
 ---
 
@@ -60,13 +63,8 @@ First, create a database configuration file.
 import { DBType, type DBConfig } from "stabilize-orm";
 
 const dbConfig: DBConfig = {
-  // Choose your database type
   type: DBType.Postgres, 
-  
-  // Connection string for your database
   connectionString: process.env.DATABASE_URL || "postgres://user:password@localhost:5432/mydb",
-
-  // Optional: Connection retry settings
   retryAttempts: 3,
   retryDelay: 1000,
 };
@@ -74,29 +72,27 @@ const dbConfig: DBConfig = {
 export default dbConfig;
 ```
 
-Next, create a central ORM instance that your application can use. Remember to import `reflect-metadata` once at your application's entry point.
+Next, create a central ORM instance that your application can use. Import `reflect-metadata` once at your application's entry point.
 
 ```typescript
 // db.ts
-import 'reflect-metadata'; // declared first
+import 'reflect-metadata';
 import { Stabilize, type CacheConfig, type LoggerConfig, LogLevel } from "stabilize-orm";
 import dbConfig from "./database";
 
 const cacheConfig: CacheConfig = {
   enabled: process.env.CACHE_ENABLED === "true",
   redisUrl: process.env.REDIS_URL,
-  ttl: 60, // Default TTL in seconds
+  ttl: 60,
 };
 
 const loggerConfig: LoggerConfig = {
-    level: LogLevel.Info,
-    // Optional: Configure file logging
-    filePath: 'logs/stabilize.log',
-    maxFileSize: 5 * 1024 * 1024, // 5MB
-    maxFiles: 3,
-}
+  level: LogLevel.Info,
+  filePath: 'logs/stabilize.log',
+  maxFileSize: 5 * 1024 * 1024, // 5MB
+  maxFiles: 3,
+};
 
-// Create and export the ORM instance
 export const orm = new Stabilize(dbConfig, cacheConfig, loggerConfig);
 ```
 
@@ -104,19 +100,18 @@ export const orm = new Stabilize(dbConfig, cacheConfig, loggerConfig);
 
 ## 🏗️ Models & Relationships
 
-Define your database tables as classes using decorators. The new `@Column` decorator uses the `DataTypes` enum for a truly database-agnostic schema definition.
-
-### Example: Users and Roles (Many-to-Many)
+Define your tables as classes using decorators. The `@Column` decorator uses the `DataTypes` enum for a truly database-agnostic schema.
 
-Here's how to model a many-to-many relationship between `User` and `Role` through a `UserRole` join table.
+### Example: Users and Roles (Many-to-Many) with Versioning
 
 ```typescript
 // models/User.ts
 import 'reflect-metadata';
-import { Model, Column, DataTypes, Required, Unique, OneToMany } from 'stabilize-orm';
+import { Model, Column, DataTypes, Required, Unique, OneToMany, Versioned } from 'stabilize-orm';
 import { UserRole } from './UserRole';
 
 @Model('users')
+@Versioned() // Enables history table for time-travel/audit
 export class User {
   @Column({ type: DataTypes.INTEGER, name: 'id' })
   id!: number;
@@ -124,8 +119,7 @@ export class User {
   @Column({ type: DataTypes.STRING, length: 100 })
   @Required() @Unique()
   email!: string;
-  
-  // This side of the relationship is for querying convenience
+
   @OneToMany(() => UserRole, 'user')
   roles?: UserRole[];
 }
@@ -154,7 +148,7 @@ import { Model, Column, DataTypes, Required, ManyToOne, Index } from 'stabilize-
 import { User } from './User';
 import { Role } from './Role';
 
-@Model('user_roles') // The join table
+@Model('user_roles')
 export class UserRole {
   @Column({ type: DataTypes.INTEGER, name: 'id' })
   id!: number;
@@ -167,7 +161,6 @@ export class UserRole {
   @Required() @Index()
   roleId!: number;
 
-  // Define the "many" sides of the relationship
   @ManyToOne(() => User, 'userId')
   user?: User;
 
@@ -178,51 +171,133 @@ export class UserRole {
 
 ---
 
+## ⏳ Versioning & Auditing
+
+Enable automatic history tracking and time-travel queries by adding `@Versioned()` to your model.
+
+- Each change is recorded in a `<table>_history` table with version, operation, and audit columns.
+- Supports snapshot queries, rollbacks, audits, and time-travel.
+
+### **Versioning Example**
+
+```typescript
+@Model('users')
+@Versioned()
+export class User {
+  @Column({ type: DataTypes.INTEGER, name: 'id' })
+  id!: number;
+
+  @Column({ type: DataTypes.STRING, length: 100 })
+  name!: string;
+}
+
+// --- Using versioning features:
+
+const userRepository = orm.getRepository(User);
+
+// Rollback to a previous version
+await userRepository.rollback(1, 3); // roll back user with id=1 to version 3
+
+// Get a snapshot as of a specific date
+const userAsOf = await userRepository.asOf(1, new Date('2025-01-01T00:00:00Z'));
+console.log(userAsOf);
+
+// View full version history
+const history = await userRepository.history(1);
+console.log(history);
+```
+
+---
+
+## 🔄 Model Lifecycle Hooks
+
+Stabilize ORM supports lifecycle hooks via the `@Hook()` decorator.  
+You can run logic before/after create, update, delete, or save.
+
+### **Hooks Example**
+
+```typescript
+import { Model, Column, DataTypes, Hook } from 'stabilize-orm';
+
+@Model('users')
+export class User {
+  @Column({ type: DataTypes.INTEGER, name: 'id' })
+  id!: number;
+
+  @Column({ type: DataTypes.STRING, length: 100 })
+  name!: string;
+
+  @Column({ type: DataTypes.DATETIME, name: 'created_at' })
+  createdAt!: Date;
+
+  @Column({ type: DataTypes.DATETIME, name: 'updated_at' })
+  updatedAt!: Date;
+
+  @Hook('beforeCreate')
+  setCreatedAt() {
+    this.createdAt = new Date();
+  }
+
+  @Hook('beforeUpdate')
+  setUpdatedAt() {
+    this.updatedAt = new Date();
+  }
+
+  @Hook('afterCreate')
+  logCreate() {
+    console.log(`User created: ${this.name}`);
+  }
+}
+```
+
+You can use `@Hook` with: `'beforeCreate'`, `'afterCreate'`, `'beforeUpdate'`, `'afterUpdate'`, `'beforeDelete'`, `'afterDelete'`, `'beforeSave'`, `'afterSave'`.
+
+---
+
 ## 💻 Command-Line Interface (CLI)
 
-Stabilize includes a powerful CLI for managing your development workflow.
+Stabilize includes a powerful CLI for managing your workflow.
 
 ### Generating Files
 
--   **Generate a model**:
+- **Generate a model**:
     ```bash
     bun run stabilize-cli generate model Product
     ```
 
--   **Generate a migration from a model**:
+- **Generate a migration from a model**:
     ```bash
-    # Reads models/User.ts and creates a new migration file
     bun run stabilize-cli generate migration User
     ```
 
--   **Generate a seed file**:
+- **Generate a seed file**:
     ```bash
     bun run stabilize-cli generate seed InitialRoles
     ```
 
 ### Database & Migration Management
 
--   **Run all pending migrations**:
+- **Run all pending migrations**:
     ```bash
     bun run stabilize-cli migrate
     ```
 
--   **Roll back the last migration**:
+- **Roll back the last migration**:
     ```bash
     bun run stabilize-cli migrate:rollback
     ```
 
--   **Run all pending seeds** (in dependency order):
+- **Run all pending seeds (in dependency order)**:
     ```bash
     bun run stabilize-cli seed
     ```
 
--   **Check the status of all migrations and seeds**:
+- **Check the status of migrations and seeds**:
     ```bash
     bun run stabilize-cli status
     ```
 
--   **Reset the database (drop, migrate, seed)**:
+- **Reset the database (drop, migrate, seed)**:
     ```bash
     bun run stabilize-cli db:reset
     ```
@@ -233,34 +308,23 @@ Stabilize includes a powerful CLI for managing your development workflow.
 
 ### Basic CRUD with Repositories
 
-Interact with your data using the `Repository` pattern.
-
 ```typescript
 import { orm } from './db';
 import { User } from 'models/User';
 
 const userRepository = orm.getRepository(User);
 
-// Create a new user
 const newUser = await userRepository.create({ email: 'lwazicd@icloud.com' });
-
-// Find a user by ID
 const foundUser = await userRepository.findOne(newUser.id);
-
-// Update a user
 const updatedUser = await userRepository.update(newUser.id, { email: 'admin@offbytesecure.com' });
-
-// Delete a user
 await userRepository.delete(newUser.id);
 ```
 
 ### Advanced Queries with the Query Builder
 
-For complex queries, use the fluent `find()` method, which returns a chainable `QueryBuilder`.
-
 ```typescript
 const activeAdmins = await orm.getRepository(UserRole)
-  .find() // Start a query on the user_roles table
+  .find()
   .join("users", "user_roles.user_id = users.id")
   .join("roles", "user_roles.role_id = roles.id")
   .select("users.id", "users.email", "roles.name as role_name")
@@ -269,13 +333,9 @@ const activeAdmins = await orm.getRepository(UserRole)
   .execute();
 
 console.log(activeAdmins);
-// [ { id: 1, email: 'lwazicd@icloud.com', role_name: 'Admin' } ]
 ```
 
-The `execute()` method on a repository query does not require a client to be passed; it uses the repository's default client automatically.
-
----
-**API:**
+#### Query Builder API
 
 ```typescript
 {
@@ -286,16 +346,25 @@ The `execute()` method on a repository query does not require a client to be pas
   limit(limit: number): QueryBuilder<User>;
   offset(offset: number): QueryBuilder<User>;
   build(): { query: string; params: any[] };
-  execute(client: DBClient, cache?: Cache, cacheKey?: string): Promise<User[]>;
+  execute(client?: DBClient, cache?: Cache, cacheKey?: string): Promise<User[]>;
 }
 ```
 
+---
+
+## 🗑️ Soft Deletes
+
+Add `@SoftDelete()` to a model property to enable transparent soft deletes (e.g., `deleted_at` timestamp).
+- Use `repository.softDelete(id)` to mark an entity as deleted.
+- Use `find({ includeDeleted: true })` to include soft-deleted rows.
+
+---
+
 ## 🌐 Express.js Integration
 
 Stabilize ORM works seamlessly with web frameworks like Express.
 
 ```typescript
-// src/server.ts
 import express from "express";
 import { orm } from "./db";
 import { User } from "./models/User";
@@ -305,7 +374,6 @@ app.use(express.json());
 
 const userRepository = orm.getRepository(User);
 
-// Get all users
 app.get("/users", async (req, res) => {
   try {
     const users = await userRepository.find().execute();
@@ -315,7 +383,6 @@ app.get("/users", async (req, res) => {
   }
 });
 
-// Create a new user
 app.post("/users", async (req, res) => {
   try {
     const user = await userRepository.create(req.body);
@@ -332,6 +399,13 @@ app.listen(3000, () => {
 
 ---
 
+## 🧑‍🔬 Testing & Time-Travel
+
+- Use time-travel queries to inspect historical entity states.
+- Assert audit trails and rollback operations in your tests.
+
+---
+
 ## 📑 License
 
 Licensed under the MIT License. See [LICENSE.md](./LICENSE.md) for details.
@@ -342,6 +416,6 @@ Licensed under the MIT License. See [LICENSE.md](./LICENSE.md) for details.
 
 Created with ❤️ by **ElectronSz**
 <br/>
-*File last updated: 2025-10-15 19:32:00 UTC*
+<em>File last updated: 2025-10-16 19:41:00 UTC</em>
 
 </div>

package/client.ts

@@ -37,7 +37,7 @@ function isMySQLPool(client: any): client is mysql.Pool {
 export class DBClient {
   private client!: Database | Pool | mysql.Pool | PoolClient | mysql.PoolConnection;
   private logger: Logger;
-  public readonly config: DBConfig; 
+  public readonly config: DBConfig;
   private retryAttempts: number;
   private retryDelay: number;
   private maxJitter: number;
@@ -82,12 +82,12 @@ export class DBClient {
     } else if (isMySQLConfig(config)) {
       this.client = mysql.createPool(config.connectionString);
       this.logger.logDebug(`Initialized MySQL Pool client.`);
-    } else { 
-      this.client = new Pool({ connectionString: config.connectionString });
+    } else if (config.type = DBType.Postgres) {
+      this.client = new Pool({ connectionString: config.connectionString! });
       this.logger.logDebug(`Initialized Postgres Pool client.`);
     }
   }
-  
+
   /** @internal Gets a random jitter value to add to retry delays. */
   private getJitter = () => Math.random() * this.maxJitter;
 
@@ -103,50 +103,53 @@ export class DBClient {
    * const users = await dbClient.query('SELECT * FROM users WHERE status = ?', ['active']);
    * ```
    */
-  
-    async query<T>(query: string, params: any[] = []): Promise<T[]> {
-        const start = Date.now();
-        
-        for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
-            try {
-                let result: any;
-                
-                // Log the query before execution
-                this.logger.logQuery(query, params);
-
-                if (this.client instanceof Database) { // SQLite
-                    let stmt = this.preparedStatements.get(query);
-                    if (!stmt) {
-                        stmt = this.client.prepare(query);
-                        this.preparedStatements.set(query, stmt);
-                    }
-                    result = stmt.all(...params);
-                } else if (isMySQLPool(this.client) || ('query' in this.client && 'release' in this.client && !(this.client instanceof Pool))) { // mysql2 Pool or Connection
-                    const [rows] = await (this.client as mysql.Pool).query(query, params);
-                    result = rows;
-                } else { // Postgres Pool or Client
-                    
-                    // Correctly replace '?' with '$1', '$2', etc.
-                    let paramIndex = 0;
-                    const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
-                    const pgResult = await (this.client as Pool).query(pgQuery, params);
-                    result = pgResult.rows;
-                }
-
-                const executionTime = Date.now() - start;
-                this.logger.logQuery(query, params, executionTime);
-                return result as T[];
-            } catch (error) {
-                this.logger.logError(error as Error);
-                if (attempt === this.retryAttempts) {
-                    throw new StabilizeError(`Query failed after ${this.retryAttempts} attempts: ${(error as Error).message}`, "QUERY_ERROR");
-                }
-                await new Promise(res => setTimeout(res, this.retryDelay * Math.pow(2, attempt - 1) + this.getJitter()));
-            }
+
+  async query<T>(query: string, params: any[] = []): Promise<T[]> {
+    const start = Date.now();
+
+    for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
+      try {
+        let result: any;
+
+        // Log the query before execution
+        this.logger.logQuery(query, params);
+
+        if (this.client instanceof Database) { // SQLite
+          let stmt = this.preparedStatements.get(query);
+          if (!stmt) {
+            stmt = this.client.prepare(query);
+            this.preparedStatements.set(query, stmt);
+          }
+          result = stmt.all(...params);
+        } else if (this.config.type === DBType.MySQL && isMySQLPool(this.client)) { // MySQL
+          const [rows] = await (this.client as mysql.Pool).query(query, params);
+          result = rows;
+        } else if (this.config.type === DBType.Postgres ) { // Postgres
+
+          let paramIndex = 0;
+          const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
+          const pgResult = await (this.client as Pool).query(pgQuery, params);
+          result = Array.isArray(pgResult.rows) ? pgResult.rows : [];
+        } else {
+          throw new StabilizeError("Unknown database client type", "QUERY_ERROR");
+        }
+
+        const executionTime = Date.now() - start;
+        this.logger.logQuery(query, params, executionTime);
+        return Array.isArray(result) ? result as T[] : [];
+      } catch (error) {
+        console.log("error: ", error);
+
+        this.logger.logError(error as Error);
+        if (attempt === this.retryAttempts) {
+          throw new StabilizeError(`Query failed after ${this.retryAttempts} attempts: ${(error as Error).message}`, "QUERY_ERROR");
         }
-        // This line should theoretically be unreachable if retryAttempts >= 1
-        throw new StabilizeError("Query failed: maximum retries reached without success", "QUERY_ERROR");
+        await new Promise(res => setTimeout(res, this.retryDelay * Math.pow(2, attempt - 1) + this.getJitter()));
+      }
     }
+    // This line should theoretically be unreachable if retryAttempts >= 1
+    throw new StabilizeError("Query failed: maximum retries reached without success", "QUERY_ERROR");
+  }
 
   /**
    * Executes a series of database operations within a single atomic transaction.
@@ -169,23 +172,23 @@ export class DBClient {
       const tx = this.client.transaction(() => callback(this));
       return tx();
     }
-    
+
     if (isMySQLPool(this.client)) {
-        const connection = await this.client.getConnection();
-        const txClient = new DBClient(this.config, this.logger, connection);
-        this.logger.logDebug("Starting MySQL transaction.");
-        try {
-            await txClient.query("START TRANSACTION");
-            const result = await callback(txClient);
-            await txClient.query("COMMIT");
-            return result;
-        } catch (error) {
-            await txClient.query("ROLLBACK");
-            throw error;
-        } finally {
-            connection.release();
-            this.logger.logDebug("MySQL transaction connection released.");
-        }
+      const connection = await this.client.getConnection();
+      const txClient = new DBClient(this.config, this.logger, connection);
+      this.logger.logDebug("Starting MySQL transaction.");
+      try {
+        await txClient.query("START TRANSACTION");
+        const result = await callback(txClient);
+        await txClient.query("COMMIT");
+        return result;
+      } catch (error) {
+        await txClient.query("ROLLBACK");
+        throw error;
+      } finally {
+        connection.release();
+        this.logger.logDebug("MySQL transaction connection released.");
+      }
     }
 
     if (this.client instanceof Pool) {
@@ -193,12 +196,12 @@ export class DBClient {
       const txClient = new DBClient(this.config, this.logger, connection);
       this.logger.logDebug("Starting Postgres transaction.");
       try {
-        await txClient.query("BEGIN");
+        await txClient.migrationQuery("BEGIN");
         const result = await callback(txClient);
-        await txClient.query("COMMIT");
+        await txClient.migrationQuery("COMMIT");
         return result;
       } catch (error) {
-        await txClient.query("ROLLBACK");
+        await txClient.migrationQuery("ROLLBACK");
         throw error;
       } finally {
         connection.release();
@@ -222,4 +225,46 @@ export class DBClient {
     this.client = null!;
     this.logger.logInfo("Database connection closed");
   }
+
+  /**
+  * Executes a SQL query for migrations/transactions that
+  * does NOT expect any result rows and returns void.
+  * This is used for DDL and transaction statements (e.g. CREATE TABLE, BEGIN, COMMIT)
+  * that should never be iterated over.
+  *
+  * Logs the execution time for each query.
+  *
+  * @param query The SQL query string with `?` as placeholders.
+  * @param params An array of parameters to bind to the query.
+  * @returns A promise that resolves when the query has executed.
+  * @example
+  * ```
+  * await dbClient.migrationQuery('CREATE TABLE ...');
+  * await dbClient.migrationQuery('BEGIN');
+  * await dbClient.migrationQuery('COMMIT');
+  * ```
+  */
+  async migrationQuery(query: string, params: any[] = []): Promise<void> {
+    const start = Date.now();
+    this.logger.logQuery(query, params);
+
+    if (this.client instanceof Database) { // SQLite
+      let stmt = this.preparedStatements.get(query);
+      if (!stmt) {
+        stmt = this.client.prepare(query);
+        this.preparedStatements.set(query, stmt);
+      }
+      stmt.run(...params);
+    } else if (isMySQLPool(this.client) || ('query' in this.client && 'release' in this.client && !(this.client instanceof Pool))) { // mysql2 Pool or Connection
+      await (this.client as mysql.Pool).query(query, params);
+    } else if (this.config.type = DBType.Postgres) { // Postgres Pool or Client
+      let paramIndex = 0;
+      const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
+      await (this.client as Pool).query(pgQuery, params);
+    }
+
+    const executionTime = Date.now() - start;
+    this.logger.logQuery(query, params, executionTime);
+  }
+
 }