stabilize-orm 1.1.7 → 1.2.0

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

@@ -2,7 +2,6 @@
  * @file stabilize.ts
  * @description The main entry point for the Stabilize ORM, tying together the client, cache, and repositories.
  * @author ElectronSz
- * @date 2025-10-15 20:35:34
  */
 import { Cache } from "./cache";
 import { DBClient } from "./client";
@@ -10,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,
@@ -23,6 +23,7 @@ import {
   ModelKey,
   ColumnKey,
   ValidatorKey,
+  Versioned,
   RelationKey,
   SoftDeleteKey,
 } from "./decorators";
@@ -31,7 +32,7 @@ import {
   type CacheConfig,
   type LoggerConfig,
   DBType,
-  DataTypes, // --- FIX: Import DataTypes here ---
+  DataTypes,
   StabilizeError,
   type PoolMetrics,
   type QueryHint,
@@ -159,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 { type DBConfig, type Migration, StabilizeError, DBType } from "./types";
+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.
@@ -31,56 +30,99 @@ function formatQuery(query: string, dbType: DBType): string {
 }
 
 /**
- * @internal
- * Gets the database-specific SQL for an auto-incrementing primary key.
- * @param dbType The target database dialect.
- * @returns The SQL string for the primary key column definition.
+ * 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).
+ *
+ * This function enables model definitions to be portable across different databases by
+ * converting each logical type to its proper SQL type in CREATE TABLE migrations.
+ *
+ * @param dt - The data type to map. Accepts either a value from the DataTypes enum, or a string
+ *             (e.g., "string", "integer", "boolean", etc.).
+ * @param dbType - The target database dialect (DBType.Postgres, DBType.MySQL, or DBType.SQLite).
+ * @returns The SQL column type string appropriate for the database and logical type.
+ *
  */
-function getAutoIncrementPK(dbType: DBType): string {
-  switch (dbType) {
-    case DBType.Postgres:
-      return "SERIAL PRIMARY KEY";
-    case DBType.MySQL:
-      return "INT AUTO_INCREMENT PRIMARY KEY";
-    case DBType.SQLite:
-    default:
-      return "INTEGER PRIMARY KEY AUTOINCREMENT";
+function mapDataTypeToSql(dt: DataTypes | string, dbType: DBType): string {
+  let type: string;
+  if (typeof dt === "string") {
+    type = dt.toLowerCase();
+  } else {
+    type = DataTypes[dt].toLowerCase();
   }
-}
 
-/**
- * @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"; 
+  if (dbType === DBType.Postgres) {
+    switch (type) {
+      case "string": return "TEXT";
+      case "text": return "TEXT";
+      case "integer": return "INTEGER";
+      case "bigint": return "BIGINT";
+      case "float": return "REAL";
+      case "double": return "DOUBLE PRECISION";
+      case "decimal": return "DECIMAL";
+      case "boolean": return "BOOLEAN";
+      case "date": return "DATE";
+      case "datetime": return "TIMESTAMP";
+      case "json": return "JSONB";
+      case "uuid": return "UUID";
+      case "blob": return "BYTEA";
+      default: return "TEXT";
+    }
   }
+  if (dbType === DBType.MySQL) {
+    switch (type) {
+      case "string": return "VARCHAR(255)";
+      case "text": return "TEXT";
+      case "integer": return "INT";
+      case "bigint": return "BIGINT";
+      case "float": return "FLOAT";
+      case "double": return "DOUBLE";
+      case "decimal": return "DECIMAL(10,2)";
+      case "boolean": return "TINYINT(1)";
+      case "date": return "DATE";
+      case "datetime": return "DATETIME";
+      case "json": return "JSON";
+      case "uuid": return "CHAR(36)";
+      case "blob": return "BLOB";
+      default: return "TEXT";
+    }
+  }
+  // SQLite
+  if (dbType === DBType.SQLite) {
+    switch (type) {
+      case "string": return "TEXT";
+      case "text": return "TEXT";
+      case "integer": return "INTEGER";
+      case "bigint": return "INTEGER";
+      case "float": return "REAL";
+      case "double": return "REAL";
+      case "decimal": return "NUMERIC";
+      case "boolean": return "INTEGER";
+      case "date": return "TEXT";
+      case "datetime": return "TEXT";
+      case "json": return "TEXT";
+      case "uuid": return "TEXT";
+      case "blob": return "BLOB";
+      default: return "TEXT";
+    }
+  }
+  return "TEXT";
 }
 
 /**
  * @internal
- * Gets the database-specific SQL for a default `CURRENT_TIMESTAMP` value.
+ * Gets the database-specific SQL for an auto-incrementing primary key.
  * @param dbType The target database dialect.
- * @returns The SQL string for the default value.
+ * @returns The SQL string for the primary key column definition.
  */
-function getTimestampDefault(dbType: DBType): string {
+function getAutoIncrementPK(dbType: DBType): string {
   switch (dbType) {
     case DBType.Postgres:
-    case DBType.SQLite:
-      return "DEFAULT CURRENT_TIMESTAMP";
+      return "SERIAL PRIMARY KEY";
     case DBType.MySQL:
-      return "DEFAULT CURRENT_TIMESTAMP";
+      return "INT AUTO_INCREMENT PRIMARY KEY";
+    case DBType.SQLite:
     default:
-      return "DEFAULT CURRENT_TIMESTAMP";
+      return "INTEGER PRIMARY KEY AUTOINCREMENT";
   }
 }
 
@@ -88,6 +130,8 @@ function getTimestampDefault(dbType: DBType): string {
  * 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.
@@ -95,8 +139,8 @@ function getTimestampDefault(dbType: DBType): string {
  */
 export async function generateMigration(
   model: new (...args: any[]) => any,
-  name: string, 
-  dbType: DBType = DBType.Postgres,
+  name: string,
+  dbType: DBType,
 ): Promise<Migration> {
   const tableName = Reflect.getMetadata(ModelKey, model);
   if (!tableName) {
@@ -105,19 +149,19 @@ export async function generateMigration(
 
   const columns: ColumnMetadata = Reflect.getMetadata(ColumnKey, model.prototype) || {};
   const validators: ValidatorMetadata = Reflect.getMetadata(ValidatorKey, model.prototype) || {};
-  const softDeleteField = Reflect.getMetadata(SoftDeleteKey, model.prototype);
+  const versioned: boolean = !!Reflect.getMetadata(VersionedKey, model);
 
-  const columnDefs = Object.entries(columns).map(([key, col]) => {
-    if (col.name === "id") {
-      return `id ${getAutoIncrementPK(dbType)}`;
-    }
+  const columnDefs: string[] = [];
+
+  for (const [key, col] of Object.entries(columns)) {
+    const defParts: string[] = [];
 
-    const defParts: string[] = [col.name];
-    
-    if (["createdAt", "updatedAt"].includes(key) || (softDeleteField && key === softDeleteField)) {
-      defParts.push(getTimestampType(dbType));
+    if (col.name === "id") {
+      defParts.push("id");
+      defParts.push(getAutoIncrementPK(dbType));
     } else {
-      defParts.push(col.type);
+      defParts.push(col.name);
+      defParts.push(mapDataTypeToSql(col.type, dbType));
     }
 
     if (validators[key]?.includes("required")) {
@@ -127,21 +171,54 @@ export async function generateMigration(
       defParts.push("UNIQUE");
     }
 
-    if (key === "createdAt") {
-      defParts.push(getTimestampDefault(dbType));
-    }
+    columnDefs.push(defParts.join(" "));
+  }
 
-    return defParts.join(" ");
-  });
+  const up: string[] = [`CREATE TABLE IF NOT EXISTS ${tableName} (${columnDefs.join(", ")})`];
+  const down: string[] = [`DROP TABLE IF EXISTS ${tableName}`];
 
-  if (softDeleteField && !columns[softDeleteField]) {
-    columnDefs.push(`${softDeleteField} ${getTimestampType(dbType)}`);
+  // If model is versioned, add history table migration
+  if (versioned) {
+    const [historyUp, historyDown] = generateHistoryMigration(tableName, columnDefs, dbType);
+    up.push(historyUp);
+    down.push(historyDown);
   }
 
-  const up = [`CREATE TABLE IF NOT EXISTS ${tableName} (${columnDefs.join(", ")})`];
-  const down = [`DROP TABLE IF EXISTS ${tableName}`];
+  return { up, down, name };
+}
 
-  return { up, down, name: tableName }; 
+/**
+ * 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}`
+  ];
 }
 
 /**
@@ -153,20 +230,20 @@ export async function generateMigration(
 function getMigrationsTableSQL(dbType: DBType): string {
   switch (dbType) {
     case DBType.Postgres:
-      return `CREATE TABLE IF NOT EXISTS migrations (
+      return `CREATE TABLE IF NOT EXISTS stabilize_migrations (
         id SERIAL PRIMARY KEY,
         name VARCHAR(255) UNIQUE NOT NULL,
         applied_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
       )`;
     case DBType.MySQL:
-      return `CREATE TABLE IF NOT EXISTS migrations (
+      return `CREATE TABLE IF NOT EXISTS stabilize_migrations (
         id INT AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(255) UNIQUE NOT NULL,
         applied_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
       )`;
     case DBType.SQLite:
     default:
-      return `CREATE TABLE IF NOT EXISTS migrations (
+      return `CREATE TABLE IF NOT EXISTS stabilize_migrations (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         name TEXT UNIQUE NOT NULL,
         applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
@@ -190,8 +267,8 @@ export async function runMigrations(config: DBConfig, migrations: Migration[]) {
 
     for (const [index, migration] of migrations.entries()) {
       const name = migration.name || `migration_${index}_${new Date().getTime()}`;
-      
-      const selectQuery = formatQuery(`SELECT id FROM migrations WHERE name = ?`, dbType);
+
+      const selectQuery = formatQuery(`SELECT id FROM stabilize_migrations WHERE name = ?`, dbType);
       const applied = await client.query<{ id: number }>(selectQuery, [name]);
 
       if (applied.length === 0) {
@@ -200,17 +277,17 @@ export async function runMigrations(config: DBConfig, migrations: Migration[]) {
           for (const query of migration.up) {
             await txClient.query(query);
           }
-          
-          const insertQuery = formatQuery(`INSERT INTO migrations (name, applied_at) VALUES (?, ?)`, dbType);
+
+          const insertQuery = formatQuery(`INSERT INTO stabilize_migrations (name, applied_at) VALUES (?, ?)`, dbType);
           await txClient.query(insertQuery, [name, new Date().toISOString()]);
-          
+
           console.log(`Migration ${name} applied successfully.`);
         });
       }
     }
   } catch (error) {
     console.error("Migration failed:", error);
-    throw error; 
+    throw error;
   } finally {
     await client.close();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stabilize-orm",
-  "version": "1.1.7",
+  "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",