stabilize-orm 1.1.8 → 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/bun.lock

@@ -7,7 +7,6 @@
         "@types/pg": "^8.15.5",
         "@types/uuid": "^11.0.0",
         "commander": "^12.1.0",
-        "dotenv": "^17.2.3",
         "figlet": "^1.9.3",
         "glob": "^11.0.0",
         "ioredis": "^5.4.1",
@@ -307,8 +306,6 @@
 
     "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
 
-    "dotenv": ["dotenv@17.2.3", "", {}, "sha512-JVUnt+DUIzu87TABbhPmNfVdBDt18BLOWjMUFJMSi/Qqg7NTYtabbvSNJGOJ7afbRuv9D/lngizHtP7QyLQ+9w=="],
-
     "eastasianwidth": ["eastasianwidth@0.2.0", "", {}, "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA=="],
 
     "emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],

package/decorators.ts

@@ -7,7 +7,6 @@
 import "reflect-metadata";
 import { RelationType, DataTypes } from "./types";
 
-
 export const ModelKey = Symbol("model");
 export const ColumnKey = Symbol("column");
 export const ValidatorKey = Symbol("validator");
@@ -15,7 +14,7 @@ export const RelationKey = Symbol("relation");
 export const SoftDeleteKey = Symbol("softDelete");
 export const DefaultKey = Symbol("default");
 export const IndexKey = Symbol("index");
-
+export const VersionedKey = Symbol("versioned");
 
 export interface ColumnOptions {
   name?: string;
@@ -42,11 +41,9 @@ export function Model(tableName: string) {
 export function Column(options: ColumnOptions | DataTypes) {
   return function (target: any, propertyKey: string) {
     const columns = Reflect.getMetadata(ColumnKey, target) || {};
- 
     const columnOptions: ColumnOptions = typeof options === 'object' ? options : { type: options };
-    
     columns[propertyKey] = {
-      name: columnOptions.name || propertyKey, 
+      name: columnOptions.name || propertyKey,
       ...columnOptions,
     };
     Reflect.defineMetadata(ColumnKey, columns, target);
@@ -80,9 +77,9 @@ export function Unique() {
  * @param value The default value.
  */
 export function Default(value: any) {
-    return function (target: any, propertyKey: string) {
-        Reflect.defineMetadata(DefaultKey, value, target, propertyKey);
-    };
+  return function (target: any, propertyKey: string) {
+    Reflect.defineMetadata(DefaultKey, value, target, propertyKey);
+  };
 }
 
 /**
@@ -90,14 +87,13 @@ export function Default(value: any) {
  * @param indexName Optional: A custom name for the index.
  */
 export function Index(indexName?: string) {
-    return function (target: any, propertyKey: string) {
-        const indexes = Reflect.getMetadata(IndexKey, target) || {};
-        indexes[propertyKey] = indexName || `idx_${propertyKey}`;
-        Reflect.defineMetadata(IndexKey, indexes, target);
-    };
+  return function (target: any, propertyKey: string) {
+    const indexes = Reflect.getMetadata(IndexKey, target) || {};
+    indexes[propertyKey] = indexName || `idx_${propertyKey}`;
+    Reflect.defineMetadata(IndexKey, indexes, target);
+  };
 }
 
-
 /**
  * Decorator to enable soft-delete functionality on a model.
  * The decorated property will store the deletion timestamp.
@@ -108,6 +104,15 @@ export function SoftDelete() {
   };
 }
 
+/**
+ * Decorator to enable versioning (history, snapshot & time-travel) on a model.
+ */
+export function Versioned() {
+  return function (target: any) {
+    Reflect.defineMetadata(VersionedKey, true, target);
+  };
+}
+
 
 export function OneToOne(model: () => any, foreignKey: string) {
   return function (target: any, propertyKey: string) {

package/hooks.ts

@@ -0,0 +1,33 @@
+import 'reflect-metadata';
+
+export type HookType =
+  | 'beforeCreate' | 'afterCreate'
+  | 'beforeUpdate' | 'afterUpdate'
+  | 'beforeDelete' | 'afterDelete'
+  | 'beforeSave' | 'afterSave';
+
+const HOOK_METADATA_KEY = Symbol('stabilize:hooks');
+
+/**
+ * Decorator to mark a method as a lifecycle hook.
+ * Usage: @Hook('beforeCreate')
+ */
+export function Hook(type: HookType) {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    const hooks: Record<HookType, string[]> =
+      Reflect.getMetadata(HOOK_METADATA_KEY, target) || {};
+    hooks[type] = hooks[type] || [];
+    hooks[type].push(propertyKey);
+    Reflect.defineMetadata(HOOK_METADATA_KEY, hooks, target);
+  };
+}
+
+/**
+ * Get hooks of a specific type for a model instance.
+ */
+export function getHooks(instance: any, type: HookType): Array<() => Promise<void> | void> {
+  const proto = Object.getPrototypeOf(instance);
+  const hooks: Record<HookType, string[]> =
+    Reflect.getMetadata(HOOK_METADATA_KEY, proto) || {};
+  return (hooks[type] || []).map((methodName) => instance[methodName].bind(instance));
+}

package/index.ts

@@ -9,6 +9,7 @@ import { type Logger, ConsoleLogger } from "./logger";
 import { QueryBuilder } from "./query-builder";
 import { Repository } from "./repository";
 import { runMigrations, generateMigration, type Migration } from "./migrations";
+import { Hook } from "./hooks";
 import {
   Model,
   Column,
@@ -22,6 +23,7 @@ import {
   ModelKey,
   ColumnKey,
   ValidatorKey,
+  Versioned,
   RelationKey,
   SoftDeleteKey,
 } from "./decorators";
@@ -30,7 +32,7 @@ import {
   type CacheConfig,
   type LoggerConfig,
   DBType,
-  DataTypes, // --- FIX: Import DataTypes here ---
+  DataTypes,
   StabilizeError,
   type PoolMetrics,
   type QueryHint,
@@ -158,6 +160,8 @@ export {
   Required,
   Unique,
   SoftDelete,
+  Versioned,
+  Hook,
   OneToOne,
   ManyToOne,
   OneToMany,

package/migrations.ts

@@ -6,14 +6,13 @@
  */
 
 import { DBClient } from "./client";
-import { ModelKey, ColumnKey, ValidatorKey, SoftDeleteKey } from "./decorators";
+import { ModelKey, ColumnKey, ValidatorKey, SoftDeleteKey, VersionedKey } from "./decorators";
 import { type DBConfig, type Migration, StabilizeError, DBType, DataTypes } from "./types";
 
 type ColumnData = { name: string; type: string };
 type ColumnMetadata = Record<string, ColumnData>;
 type ValidatorMetadata = Record<string, string[]>;
 
-// --- FIX: New Helper Function to format queries for different DBs ---
 /**
  * @internal
  * Formats a SQL query with placeholders for the target database dialect.
@@ -30,7 +29,6 @@ function formatQuery(query: string, dbType: DBType): string {
   return query;
 }
 
-
 /**
  * Maps an abstract data type (from DataTypes enum or a string) to the correct SQL type string
  * for the specified database dialect (Postgres, MySQL, or SQLite).
@@ -110,7 +108,6 @@ function mapDataTypeToSql(dt: DataTypes | string, dbType: DBType): string {
   return "TEXT";
 }
 
-
 /**
  * @internal
  * Gets the database-specific SQL for an auto-incrementing primary key.
@@ -129,46 +126,12 @@ function getAutoIncrementPK(dbType: DBType): string {
   }
 }
 
-/**
- * @internal
- * Gets the database-specific SQL for a timestamp column.
- * @param dbType The target database dialect.
- * @returns The SQL string for the timestamp column type.
- */
-function getTimestampType(dbType: DBType): string {
-  switch (dbType) {
-    case DBType.Postgres:
-      return "TIMESTAMP";
-    case DBType.MySQL:
-      return "DATETIME";
-    case DBType.SQLite:
-    default:
-      return "TEXT";
-  }
-}
-
-/**
- * @internal
- * Gets the database-specific SQL for a default `CURRENT_TIMESTAMP` value.
- * @param dbType The target database dialect.
- * @returns The SQL string for the default value.
- */
-function getTimestampDefault(dbType: DBType): string {
-  switch (dbType) {
-    case DBType.Postgres:
-    case DBType.SQLite:
-      return "DEFAULT CURRENT_TIMESTAMP";
-    case DBType.MySQL:
-      return "DEFAULT CURRENT_TIMESTAMP";
-    default:
-      return "DEFAULT CURRENT_TIMESTAMP";
-  }
-}
-
 /**
  * Generates SQL migration scripts (`up` and `down`) based on a model's decorators.
  * This function reads the metadata from a model class to create a `CREATE TABLE` statement.
  *
+ * If the model is versioned (has @Versioned), also generates a history table for time-travel queries.
+ *
  * @param model The model class decorated with `@Model` and `@Column`.
  * @param name A descriptive name for the migration (used for the migration object).
  * @param dbType The target database dialect to generate SQL for. Defaults to Postgres.
@@ -186,6 +149,7 @@ export async function generateMigration(
 
   const columns: ColumnMetadata = Reflect.getMetadata(ColumnKey, model.prototype) || {};
   const validators: ValidatorMetadata = Reflect.getMetadata(ValidatorKey, model.prototype) || {};
+  const versioned: boolean = !!Reflect.getMetadata(VersionedKey, model);
 
   const columnDefs: string[] = [];
 
@@ -210,12 +174,53 @@ export async function generateMigration(
     columnDefs.push(defParts.join(" "));
   }
 
-  const up = [`CREATE TABLE IF NOT EXISTS ${tableName} (${columnDefs.join(", ")})`];
-  const down = [`DROP TABLE IF EXISTS ${tableName}`];
+  const up: string[] = [`CREATE TABLE IF NOT EXISTS ${tableName} (${columnDefs.join(", ")})`];
+  const down: string[] = [`DROP TABLE IF EXISTS ${tableName}`];
+
+  // If model is versioned, add history table migration
+  if (versioned) {
+    const [historyUp, historyDown] = generateHistoryMigration(tableName, columnDefs, dbType);
+    up.push(historyUp);
+    down.push(historyDown);
+  }
 
   return { up, down, name };
 }
 
+/**
+ * Generates SQL for a version/audit history table for time-travel queries.
+ * @param tableName The name of the main table.
+ * @param columnDefs The column definitions (from the main table).
+ * @param dbType The target database dialect.
+ */
+function generateHistoryMigration(
+  tableName: string,
+  columnDefs: string[],
+  dbType: DBType,
+): [string, string] {
+  const historyTable = `${tableName}_history`;
+  let opType = "VARCHAR(10) NOT NULL";
+  let versionType = "INT NOT NULL";
+  let tsType = dbType === DBType.MySQL ? "DATETIME" :
+    dbType === DBType.SQLite ? "TEXT" : "TIMESTAMP";
+  let modByType = dbType === DBType.MySQL ? "VARCHAR(255)" : "TEXT";
+  let modAtType = tsType + (dbType === DBType.Postgres ? " DEFAULT CURRENT_TIMESTAMP" : "");
+
+  const historyColumns = [
+    ...columnDefs,
+    `operation ${opType}`,
+    `version ${versionType}`,
+    `valid_from ${tsType} NOT NULL`,
+    `valid_to ${tsType}`,
+    `modified_by ${modByType}`,
+    `modified_at ${modAtType}`
+  ];
+  return [
+    `CREATE TABLE IF NOT EXISTS ${historyTable} (${historyColumns.join(", ")})`,
+    `DROP TABLE IF EXISTS ${historyTable}`
+  ];
+}
+
 /**
  * @internal
  * Gets the database-specific SQL for creating the `migrations` table, which tracks applied migrations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stabilize-orm",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "A lightweight, type-safe ORM for Bun.js with support for SQLite, MySQL, PostgreSQL, and Redis caching",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/repository.ts

@@ -20,7 +20,12 @@ import {
   ValidatorKey,
   RelationKey,
   SoftDeleteKey,
+  VersionedKey,
 } from "./decorators";
+import { getHooks, type HookType } from "./hooks";
+
+type VersionOperation = "insert" | "update" | "delete";
+
 
 /**
  * Provides a generic repository for a model `T`.
@@ -46,6 +51,8 @@ export class Repository<T> {
   >;
   private softDeleteField: string | null;
   private logger: Logger;
+  private versioned: boolean;
+  private historyTable: string;
 
   /**
    * Creates an instance of Repository.
@@ -69,6 +76,8 @@ export class Repository<T> {
     this.softDeleteField =
       Reflect.getMetadata(SoftDeleteKey, model.prototype) || null;
     this.logger = logger;
+    this.versioned = !!Reflect.getMetadata(VersionedKey, model);
+    this.historyTable = `${this.table}_history`;
   }
 
   /**
@@ -102,6 +111,17 @@ export class Repository<T> {
     }
   }
 
+  /**
+  * Runs lifecycle hooks of a given type for the entity.
+  * @param entity The entity instance.
+  * @param type The hook type (e.g., 'beforeCreate').
+  */
+  private async runHooks(entity: any, type: HookType): Promise<void> {
+    for (const hook of getHooks(entity, type)) {
+      await hook();
+    }
+  }
+
   /**
    * Creates a new `QueryBuilder` instance for the repository's table.
    * Automatically adds a `WHERE` clause to exclude soft-deleted records if applicable.
@@ -152,6 +172,136 @@ export class Repository<T> {
     return results[0] || null;
   }
 
+  /**
+ * Snapshot query: get record as it was at a point in time.
+ */
+  async asOf(
+    id: number | string,
+    asOfDate: Date,
+    _client?: DBClient
+  ): Promise<T | null> {
+    if (!this.versioned) throw new StabilizeError("Model is not versioned", "VERSIONING_ERROR");
+    const client = _client || this.client;
+    const rows = await client.query<T>(
+      `SELECT * FROM ${this.historyTable} WHERE id = ? AND valid_from <= ? AND (valid_to IS NULL OR valid_to > ?) ORDER BY version DESC LIMIT 1`,
+      [id, asOfDate, asOfDate]
+    );
+    return rows[0] || null;
+  }
+
+  /**
+ * Get all history for a record.
+ */
+  async history(
+    id: number | string,
+    _client?: DBClient
+  ): Promise<T[]> {
+    if (!this.versioned) throw new StabilizeError("Model is not versioned", "VERSIONING_ERROR");
+    const client = _client || this.client;
+    return client.query<T>(
+      `SELECT * FROM ${this.historyTable} WHERE id = ? ORDER BY version ASC`,
+      [id]
+    );
+  }
+
+
+
+  /**
+   * Rollback a record to a previous version.
+   */
+  async rollback(
+    id: number | string,
+    version: number,
+    _client?: DBClient
+  ): Promise<T> {
+    if (!this.versioned) throw new StabilizeError("Model is not versioned", "VERSIONING_ERROR");
+    const client = _client || this.client;
+    return client.transaction(async (txClient) => {
+      const rows = await txClient.query<T>(
+        `SELECT * FROM ${this.historyTable} WHERE id = ? AND version = ? LIMIT 1`,
+        [id, version]
+      );
+      if (!rows.length) throw new StabilizeError("Version not found", "ROLLBACK_ERROR");
+
+      const entity = rows[0];
+      const columns = Object.keys(this.columns).filter((c) => c !== "id");
+      const setClause = columns.map((c) => `${this.columns[c]!.name} = ?`).join(", ");
+      const params = columns.map((c) => (entity as any)[c]);
+
+      await txClient.query(
+        `UPDATE ${this.table} SET ${setClause} WHERE id = ?`,
+        [...params, id]
+      );
+      await this.writeHistory({ ...entity, version: version + 1 }, "update", txClient);
+      return this.findOne(id, {}, txClient) as Promise<T>;
+    });
+  }
+
+
+  /**
+   * Writes a versioned history row for the entity to the history table.
+   *
+   * This method maps entity property keys to their corresponding SQL column names
+   * (as defined in metadata) to ensure that inserts match the schema for all supported
+   * databases (Postgres, MySQL, SQLite).
+   *
+   * This function works for Postgres, MySQL, and SQLite, and uses positional parameters
+   * (properly formatted for the target database) for safety and compatibility.
+   *
+   * @param entity - The entity object being versioned
+   * @param operation - The operation performed ("insert", "update", "delete")
+   * @param client - The database client to use for the insert
+   * @param user - The user/system responsible for the change (default: "system")
+   */
+  private async writeHistory(
+    entity: any,
+    operation: VersionOperation,
+    client: DBClient,
+    user?: string
+  ) {
+    if (!this.versioned) return;
+
+    // Get property keys and corresponding SQL column names
+    const propertyKeys = Object.keys(this.columns);
+    const sqlColumnNames = propertyKeys.map((k) => this.columns[k]!.name);
+
+    // Build historyColumns using SQL column names
+    const historyColumns = [
+      ...sqlColumnNames,
+      "operation",
+      "version",
+      "valid_from",
+      "valid_to",
+      "modified_by",
+      "modified_at"
+    ];
+
+    // Map values from entity using property keys
+    const values = propertyKeys.map((k) => entity[k]);
+
+    const params = [
+      ...values,
+      operation,
+      entity.version || 1,
+      new Date(),
+      null,
+      user || "system",
+      new Date()
+    ];
+    // Database-agnostic placeholder formatting
+    let placeholders: string;
+    if (client.config.type === DBType.Postgres) {
+      placeholders = params.map((_, i) => `$${i + 1}`).join(", ");
+    } else {
+      placeholders = params.map(() => "?").join(", ");
+    }
+
+    await client.query(
+      `INSERT INTO ${this.historyTable} (${historyColumns.join(", ")}) VALUES (${placeholders})`,
+      params
+    );
+  }
+
   /**
    * Creates a new record in the database within a transaction.
    * @param entity The data for the new record.
@@ -166,11 +316,22 @@ export class Repository<T> {
     entity: Partial<T>,
     options: { relations?: string[] } = {},
   ): Promise<T> {
-    return this.client.transaction((txClient) =>
-      this._create(entity, options, txClient),
-    );
-  }
+    return this.client.transaction(async (txClient) => {
+      const instance = new (Object.getPrototypeOf(entity).constructor || Object)();
+      Object.assign(instance, entity);
 
+      await this.runHooks(instance, "beforeCreate");
+      await this.runHooks(instance, "beforeSave");
+
+      const result = await this._create(entity, options, txClient);
+
+      await this.runHooks(result, "afterCreate");
+      await this.runHooks(result, "afterSave");
+
+      await this.writeHistory(result, "insert", txClient);
+      return result;
+    });
+  }
   /**
    * @internal
    * The private implementation for creating a record, executed within a transaction.
@@ -245,9 +406,30 @@ export class Repository<T> {
     entities: Partial<T>[],
     options: { relations?: string[]; batchSize?: number } = {},
   ): Promise<T[]> {
-    return this.client.transaction((txClient) =>
-      this._bulkCreate(entities, options, txClient),
-    );
+    return this.client.transaction(async (txClient) => {
+      // Prepare entity instances for hooks
+      const preparedEntities = entities.map(data => {
+        const instance = new (this as any).model();
+        Object.assign(instance, data);
+        return instance;
+      });
+
+      for (const entity of preparedEntities) {
+        await this.runHooks(entity, "beforeCreate");
+        await this.runHooks(entity, "beforeSave");
+      }
+
+      const results = await this._bulkCreate(entities, options, txClient);
+
+      for (const result of results) {
+        await this.runHooks(result, "afterCreate");
+        await this.runHooks(result, "afterSave");
+        if (this.versioned) {
+          await this.writeHistory(result, "insert", txClient);
+        }
+      }
+      return results;
+    });
   }
 
   /**
@@ -358,9 +540,27 @@ export class Repository<T> {
    * ```
    */
   async update(id: number | string, entity: Partial<T>): Promise<T> {
-    return this.client.transaction((txClient) =>
-      this._update(id, entity, txClient),
-    );
+    return this.client.transaction(async (txClient) => {
+      const before = await this.findOne(id, {}, txClient);
+      if (!before) throw new StabilizeError("Not found", "UPDATE_ERROR");
+      const instance = new (Object.getPrototypeOf(before).constructor || Object)();
+      Object.assign(instance, before, entity);
+
+      await this.runHooks(instance, "beforeUpdate");
+      await this.runHooks(instance, "beforeSave");
+
+      const result = await this._update(id, entity, txClient);
+
+      await this.runHooks(result, "afterUpdate");
+      await this.runHooks(result, "afterSave");
+
+      await this.writeHistory(
+        { ...before, ...entity, version: (before as any).version ? (before as any).version + 1 : 1 },
+        "update",
+        txClient
+      );
+      return result;
+    });
   }
 
   /**
@@ -442,14 +642,48 @@ export class Repository<T> {
     for (let i = 0; i < updates.length; i += batchSize) {
       const batch = updates.slice(i, i + batchSize);
       for (const update of batch) {
-        const keys = Object.keys(update.set).filter((k) => this.columns[k]);
-        const setClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(", ");
-        const query = `UPDATE ${this.table} SET ${setClause} WHERE ${update.where.condition}${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
-        const params = [
-          ...keys.map((k) => (update.set as any)[k]),
-          ...update.where.params,
-        ];
-        await client.query(query, params);
+        // Find all IDs matching the where clause
+        const rows = await client.query<{ id: number | string }>(
+          `SELECT id FROM ${this.table} WHERE ${update.where.condition}${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`,
+          update.where.params,
+        );
+        for (const { id } of rows) {
+          // Fetch record before update for versioning
+          const before = await this.findOne(id, {}, client);
+          if (!before) continue;
+
+          // Prepare instance for hooks
+          const instance = new ((this as any).model || Object)();
+          Object.assign(instance, before, update.set);
+
+          await this.runHooks(instance, "beforeUpdate");
+          await this.runHooks(instance, "beforeSave");
+
+          const keys = Object.keys(update.set).filter((k) => this.columns[k]);
+          const setClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(", ");
+          const query = `UPDATE ${this.table} SET ${setClause} WHERE id = ?${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
+          const params = [
+            ...keys.map((k) => (update.set as any)[k]),
+            id,
+          ];
+          await client.query(query, params);
+
+          const after = await this.findOne(id, {}, client);
+          if (after) {
+            await this.runHooks(after, "afterUpdate");
+            await this.runHooks(after, "afterSave");
+            if (this.versioned) {
+              await this.writeHistory(
+                {
+                  ...after,
+                  version: (before as any).version ? (before as any).version + 1 : 1
+                },
+                "update",
+                client
+              );
+            }
+          }
+        }
       }
     }
 
@@ -459,7 +693,6 @@ export class Repository<T> {
       `Bulk updated ${updates.length} ${this.table} entities in ${(performance.now() - start).toFixed(2)}ms`,
     );
   }
-
   /**
    * Performs an "update or insert" operation based on a set of unique keys.
    * @param entity The entity to upsert.
@@ -504,6 +737,32 @@ export class Repository<T> {
     const insertParams = columns.map((k) => (entity as any)[k]);
     let params = [...insertParams, ...updateParams];
 
+    // Try to find the record before upsert
+    let before: T | null = null;
+    let isUpdate = false;
+    if (this.versioned && keys.length > 0) {
+      const whereClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(" AND ");
+      const whereParams = keys.map((k) => (entity as any)[k]);
+      const found = await client.query<T>(
+        `SELECT * FROM ${this.table} WHERE ${whereClause} LIMIT 1`,
+        whereParams
+      );
+      before = found[0] || null;
+      isUpdate = !!before;
+    }
+
+    // Prepare instance for hooks
+    const instance = new ((this as any).model || Object)();
+    Object.assign(instance, before || {}, entity);
+
+    if (isUpdate) {
+      await this.runHooks(instance, "beforeUpdate");
+      await this.runHooks(instance, "beforeSave");
+    } else {
+      await this.runHooks(instance, "beforeCreate");
+      await this.runHooks(instance, "beforeSave");
+    }
+
     if (dbType === DBType.SQLite) {
       query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON CONFLICT(${keys.map((k) => this.columns[k]!.name).join(", ")}) DO UPDATE SET ${updateClause}`;
     } else if (dbType === DBType.MySQL) {
@@ -532,6 +791,14 @@ export class Repository<T> {
 
     const result = results[0] ?? ((await this.findOne(id, {}, client)) as T);
 
+    if (isUpdate) {
+      await this.runHooks(result, "afterUpdate");
+      await this.runHooks(result, "afterSave");
+    } else {
+      await this.runHooks(result, "afterCreate");
+      await this.runHooks(result, "afterSave");
+    }
+
     if (this.cache) {
       await this.cache.invalidatePattern(`find:${this.table}:*`);
       if (this.cache.getStrategy() === "write-through") {
@@ -539,12 +806,19 @@ export class Repository<T> {
       }
     }
 
+    if (this.versioned) {
+      await this.writeHistory(
+        { ...result, version: before ? ((before as any).version ? (before as any).version + 1 : 1) : 1 },
+        before ? "update" : "insert",
+        client
+      );
+    }
+
     this.logger.logDebug(
       `Upserted ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
     );
     return result;
   }
-
   /**
    * Deletes a record by its ID. Performs a soft delete if enabled on the model.
    * @param id The ID of the record to delete.
@@ -555,7 +829,16 @@ export class Repository<T> {
    * ```
    */
   async delete(id: number | string): Promise<void> {
-    return this.client.transaction((txClient) => this._delete(id, txClient));
+    return this.client.transaction(async (txClient) => {
+      const before = await this.findOne(id, {}, txClient);
+      if (!before) throw new StabilizeError("Not found", "DELETE_ERROR");
+      await this.runHooks(before, "beforeDelete");
+
+      await this._delete(id, txClient);
+
+      await this.runHooks(before, "afterDelete");
+      await this.writeHistory(before, "delete", txClient);
+    });
   }
 
   /**
@@ -619,14 +902,25 @@ export class Repository<T> {
     const batchSize = options.batchSize || 1000;
     for (let i = 0; i < ids.length; i += batchSize) {
       const batch = ids.slice(i, i + batchSize);
-      const placeholders = batch.map(() => "?").join(", ");
-      const query = this.softDeleteField
-        ? `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id IN (${placeholders})`
-        : `DELETE FROM ${this.table} WHERE id IN (${placeholders})`;
-      const params = this.softDeleteField
-        ? [new Date().toISOString(), ...batch]
-        : batch;
-      await client.query(query, params);
+      for (const id of batch) {
+        const before = await this.findOne(id, {}, client);
+        if (!before) continue;
+
+        await this.runHooks(before, "beforeDelete");
+
+        const query = this.softDeleteField
+          ? `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id = ?`
+          : `DELETE FROM ${this.table} WHERE id = ?`;
+        const params = this.softDeleteField ? [new Date().toISOString(), id] : [id];
+
+        await client.query(query, params);
+
+        await this.runHooks(before, "afterDelete");
+
+        if (this.versioned) {
+          await this.writeHistory(before, "delete", client);
+        }
+      }
     }
 
     if (this.cache) await this.cache.invalidatePattern(`find:${this.table}:*`);
@@ -635,7 +929,6 @@ export class Repository<T> {
       `Bulk deleted ${ids.length} ${this.table} entities in ${(performance.now() - start).toFixed(2)}ms`,
     );
   }
-
   /**
    * Recovers a soft-deleted record by its ID.
    * Throws an error if soft delete is not enabled on the model.