stabilize-orm 1.1.8 → 1.3.0

package/client.ts

@@ -14,26 +14,18 @@ import {
 } from "./types";
 import { type Logger, ConsoleLogger } from "./logger";
 
-/** @internal Checks if the config is for SQLite. */
 function isSQLiteConfig(config: DBConfig): boolean {
   return config.type === DBType.SQLite;
 }
 
-/** @internal Checks if the config is for MySQL. */
 function isMySQLConfig(config: DBConfig): boolean {
   return config.type === DBType.MySQL;
 }
 
-/** @internal A type guard to reliably identify a mysql2 Pool object. */
 function isMySQLPool(client: any): client is mysql.Pool {
   return typeof client.getConnection === 'function';
 }
 
-/**
- * A unified database client that provides a consistent interface for
- * PostgreSQL, MySQL, and SQLite databases. It handles connection pooling,
- * query execution with retries, and transactions.
- */
 export class DBClient {
   private client!: Database | Pool | mysql.Pool | PoolClient | mysql.PoolConnection;
   private logger: Logger;
@@ -45,12 +37,6 @@ export class DBClient {
   private preparedStatements: Map<string, Statement> = new Map();
   public readonly isTransactionClient: boolean = false;
 
-  /**
-   * Creates an instance of DBClient.
-   * @param config The database configuration object.
-   * @param logger A logger instance for logging messages.
-   * @param existingClient An optional existing connection, used internally for transactions.
-   */
   constructor(
     config: DBConfig,
     logger: Logger = new ConsoleLogger(),
@@ -70,11 +56,6 @@ export class DBClient {
     }
   }
 
-  /**
-   * @internal
-   * Initializes the database client based on the provided configuration.
-   * @param config The database configuration.
-   */
   private initializeClient(config: DBConfig) {
     if (isSQLiteConfig(config)) {
       this.client = new Database(config.connectionString, { create: true });
@@ -88,22 +69,8 @@ export class DBClient {
     }
   }
 
-  /** @internal Gets a random jitter value to add to retry delays. */
   private getJitter = () => Math.random() * this.maxJitter;
 
-  /**
-   * Executes a SQL query with parameters and returns the result.
-   * Automatically handles placeholder conversion for different databases and includes retry logic.
-   * @template T The expected type of the result rows.
-   * @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 to an array of results.
-   * @example
-   * ```
-   * const users = await dbClient.query('SELECT * FROM users WHERE status = ?', ['active']);
-   * ```
-   */
-
   async query<T>(query: string, params: any[] = []): Promise<T[]> {
     const start = Date.now();
 
@@ -111,21 +78,19 @@ export class DBClient {
       try {
         let result: any;
 
-        // Log the query before execution
         this.logger.logQuery(query, params);
 
-        if (this.client instanceof Database) { // SQLite
+        if (this.client instanceof Database) {
           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
+        } else if (this.config.type === DBType.MySQL && isMySQLPool(this.client)) {
           const [rows] = await (this.client as mysql.Pool).query(query, params);
           result = rows;
-        } else if (this.config.type === DBType.Postgres ) { // Postgres
-
+        } else if (this.config.type === DBType.Postgres ) {
           let paramIndex = 0;
           const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
           const pgResult = await (this.client as Pool).query(pgQuery, params);
@@ -138,8 +103,6 @@ export class DBClient {
         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");
@@ -147,24 +110,9 @@ export class DBClient {
         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.
-   * If any operation in the callback fails, the entire transaction is rolled back.
-   * @template T The return type of the callback function.
-   * @param callback An async function that receives a transactional `DBClient` instance.
-   * @returns A promise that resolves with the result of the callback.
-   * @example
-   * ```
-   * await dbClient.transaction(async (txClient) => {
-   *   await txClient.query('UPDATE accounts SET balance = balance - 100 WHERE id = 1');
-   *   await txClient.query('UPDATE accounts SET balance = balance + 100 WHERE id = 2');
-   * });
-   * ```
-   */
   async transaction<T>(callback: (txClient: DBClient) => Promise<T>): Promise<T> {
     if (this.isTransactionClient) return callback(this);
 
@@ -212,10 +160,6 @@ export class DBClient {
     throw new StabilizeError("Transaction not supported by this client configuration.", "TX_ERROR");
   }
 
-  /**
-   * Closes the database connection pool gracefully.
-   * Should be called when the application is shutting down.
-   */
   async close() {
     if (this.client instanceof Database) {
       this.client.close();
@@ -226,38 +170,20 @@ export class DBClient {
     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
+    if (this.client instanceof Database) {
       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
+    } else if (isMySQLPool(this.client) || ('query' in this.client && 'release' in this.client && !(this.client instanceof Pool))) {
       await (this.client as mysql.Pool).query(query, params);
-    } else if (this.config.type = DBType.Postgres) { // Postgres Pool or Client
+    } else if (this.config.type = DBType.Postgres) {
       let paramIndex = 0;
       const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
       await (this.client as Pool).query(pgQuery, params);
@@ -266,5 +192,4 @@ export class DBClient {
     const executionTime = Date.now() - start;
     this.logger.logQuery(query, params, executionTime);
   }
-
-}
+}

package/hooks.ts

@@ -0,0 +1,76 @@
+/**
+ * @file hooks.ts
+ * @description Provides lifecycle hooks for Stabilize ORM models, integrated with the programmatic API.
+ * @author ElectronSz
+ */
+
+import { MetadataStorage } from "./model";
+
+export type HookType =
+  | "beforeCreate"
+  | "afterCreate"
+  | "beforeUpdate"
+  | "afterUpdate"
+  | "beforeSave"
+  | "afterSave"
+  | "beforeDelete"
+  | "afterDelete";
+
+export type HookCallback = (entity: any) => Promise<void> | void;
+
+export interface Hook {
+  type: HookType;
+  callback: HookCallback;
+}
+
+// Extend ModelConfig to include hooks
+declare module "./model" {
+  interface ModelConfig {
+    hooks?: Record<HookType, HookCallback | HookCallback[]>;
+  }
+}
+
+/**
+ * Registers hooks for a model in the MetadataStorage.
+ * @param model The model class.
+ * @param hooks A record of hook types to their callbacks.
+ */
+export function registerHooks(model: Function, hooks: Record<HookType, HookCallback | HookCallback[]>) {
+  const config = MetadataStorage.getModelMetadata(model) || { tableName: "", columns: {} };
+  config.hooks = { ...config.hooks, ...hooks };
+  MetadataStorage.setModelMetadata(model, config);
+}
+
+/**
+ * Retrieves hooks for a given entity and hook type.
+ * Combines hooks from MetadataStorage and class methods.
+ * @param entity The entity instance.
+ * @param type The hook type (e.g., 'beforeCreate').
+ * @returns An array of Hook objects to execute.
+ */
+export function getHooks(entity: any, type: HookType): Hook[] {
+  const hooks: Hook[] = [];
+  const model = Object.getPrototypeOf(entity).constructor;
+
+  // Get hooks from MetadataStorage
+  const config = MetadataStorage.getModelMetadata(model);
+  if (config?.hooks?.[type]) {
+    const callbacks = Array.isArray(config.hooks[type])
+      ? config.hooks[type]
+      : [config.hooks[type]];
+    hooks.push(...callbacks.map(callback => ({
+      type,
+      callback: () => callback(entity),
+    })));
+  }
+
+  // Get hooks from class methods
+  if (typeof entity[type] === "function") {
+    hooks.push({
+      type,
+      callback: () => entity[type](),
+    });
+  }
+
+  return hooks;
+}

package/index.ts

@@ -9,28 +9,12 @@ import { type Logger, ConsoleLogger } from "./logger";
 import { QueryBuilder } from "./query-builder";
 import { Repository } from "./repository";
 import { runMigrations, generateMigration, type Migration } from "./migrations";
-import {
-  Model,
-  Column,
-  Required,
-  Unique,
-  SoftDelete,
-  OneToOne,
-  ManyToOne,
-  OneToMany,
-  ManyToMany,
-  ModelKey,
-  ColumnKey,
-  ValidatorKey,
-  RelationKey,
-  SoftDeleteKey,
-} from "./decorators";
 import {
   type DBConfig,
   type CacheConfig,
   type LoggerConfig,
   DBType,
-  DataTypes, // --- FIX: Import DataTypes here ---
+  DataTypes,
   StabilizeError,
   type PoolMetrics,
   type QueryHint,
@@ -38,7 +22,8 @@ import {
   type CacheStats,
   LogLevel,
 } from "./types";
-
+import { defineModel } from "./model";
+import type { Hook } from "./hooks";
 
 export class Stabilize {
   public client: DBClient;
@@ -66,7 +51,7 @@ export class Stabilize {
 
   /**
    * Gets a repository for a given model, used to perform CRUD operations.
-   * @param model The model class, which must be decorated with `@Model`.
+   * @param model The model class, defined using `defineModel`.
    * @returns A new `Repository` instance for the specified model.
    * @example
    * ```
@@ -97,7 +82,6 @@ export class Stabilize {
    * try {
    *   await stabilize.transaction(async (txClient) => {
    *     const newUser = await userRepo.create({ name: 'Ciniso Dlamini' }, {}, txClient);
-   *     // The new user's ID is needed for the profile, linking the operations.
    *     await profileRepo.create({ userId: newUser.id, bio: 'A new bio' }, {}, txClient);
    *   });
    *   console.log('User and profile created successfully.');
@@ -149,26 +133,13 @@ export {
   Cache,
   ConsoleLogger,
   DBType,
-  DataTypes, 
+  DataTypes,
   LogLevel,
   RelationType,
   StabilizeError,
-  Model,
-  Column,
-  Required,
-  Unique,
-  SoftDelete,
-  OneToOne,
-  ManyToOne,
-  OneToMany,
-  ManyToMany,
-  ModelKey,
-  ColumnKey,
-  ValidatorKey,
-  RelationKey,
-  SoftDeleteKey,
   runMigrations,
   generateMigration,
+  defineModel,
 };
 
 export type {
@@ -180,4 +151,5 @@ export type {
   PoolMetrics,
   CacheStats,
   Logger,
-};
+  Hook
+};

package/migrations.ts

@@ -6,18 +6,12 @@
  */
 
 import { DBClient } from "./client";
-import { ModelKey, ColumnKey, ValidatorKey, SoftDeleteKey } from "./decorators";
+import { MetadataStorage } from "./model";
 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.
- * Replaces '?' with '$1', '$2', etc. for PostgreSQL.
  * @param query The SQL query string with '?' placeholders.
  * @param dbType The target database dialect.
  * @returns The formatted SQL query string.
@@ -30,19 +24,11 @@ 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).
- *
- * 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.
- *
+ * Maps an abstract data type to the correct SQL type string for the specified database dialect.
+ * @param dt The data type to map.
+ * @param dbType The target database dialect.
+ * @returns The SQL column type string.
  */
 function mapDataTypeToSql(dt: DataTypes | string, dbType: DBType): string {
   let type: string;
@@ -88,7 +74,6 @@ function mapDataTypeToSql(dt: DataTypes | string, dbType: DBType): string {
       default: return "TEXT";
     }
   }
-  // SQLite
   if (dbType === DBType.SQLite) {
     switch (type) {
       case "string": return "TEXT";
@@ -110,7 +95,6 @@ function mapDataTypeToSql(dt: DataTypes | string, dbType: DBType): string {
   return "TEXT";
 }
 
-
 /**
  * @internal
  * Gets the database-specific SQL for an auto-incrementing primary key.
@@ -130,48 +114,10 @@ function getAutoIncrementPK(dbType: DBType): string {
 }
 
 /**
- * @internal
- * Gets the database-specific SQL for a timestamp column.
+ * Generates SQL migration scripts (`up` and `down`) based on a model's configuration.
+ * @param model The model class defined with `defineModel`.
+ * @param name A descriptive name for the migration.
  * @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.
- *
- * @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.
  * @returns A promise that resolves to a `Migration` object containing the `up` and `down` SQL scripts.
  */
 export async function generateMigration(
@@ -179,13 +125,14 @@ export async function generateMigration(
   name: string,
   dbType: DBType,
 ): Promise<Migration> {
-  const tableName = Reflect.getMetadata(ModelKey, model);
+  const tableName = MetadataStorage.getTableName(model);
   if (!tableName) {
-    throw new StabilizeError("Model not decorated with @Model", "MIGRATION_ERROR");
+    throw new StabilizeError("Model not defined with tableName", "MIGRATION_ERROR");
   }
 
-  const columns: ColumnMetadata = Reflect.getMetadata(ColumnKey, model.prototype) || {};
-  const validators: ValidatorMetadata = Reflect.getMetadata(ValidatorKey, model.prototype) || {};
+  const columns = MetadataStorage.getColumns(model);
+  const validators = MetadataStorage.getValidators(model);
+  const versioned = MetadataStorage.isVersioned(model);
 
   const columnDefs: string[] = [];
 
@@ -196,7 +143,7 @@ export async function generateMigration(
       defParts.push("id");
       defParts.push(getAutoIncrementPK(dbType));
     } else {
-      defParts.push(col.name);
+      defParts.push(col.name || key);
       defParts.push(mapDataTypeToSql(col.type, dbType));
     }
 
@@ -206,19 +153,65 @@ export async function generateMigration(
     if (validators[key]?.includes("unique")) {
       defParts.push("UNIQUE");
     }
+    if (col.defaultValue !== undefined) {
+      defParts.push(`DEFAULT ${JSON.stringify(col.defaultValue)}`);
+    }
+    if (col.index) {
+      defParts.push(`INDEX ${col.index}`);
+    }
 
     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 (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.
+ * Gets the database-specific SQL for creating the `migrations` table.
  * @param dbType The target database dialect.
  * @returns The SQL string for the `CREATE TABLE` statement.
  */
@@ -248,9 +241,6 @@ function getMigrationsTableSQL(dbType: DBType): string {
 
 /**
  * Connects to the database and runs all pending migrations.
- * It tracks which migrations have been applied by using a `migrations` table in the database.
- * Each migration is run within a transaction to ensure atomicity.
- *
  * @param config The database configuration object.
  * @param migrations An array of `Migration` objects to be executed.
  */
@@ -288,4 +278,4 @@ export async function runMigrations(config: DBConfig, migrations: Migration[]) {
   }
 }
 
-export type { Migration };
+export type { Migration };

package/model.ts

@@ -0,0 +1,115 @@
+
+/**
+ * @file model.ts
+ * @description Provides a programmatic API for defining models and a metadata storage system.
+ * @author ElectronSz
+ */
+
+import { DataTypes, RelationType, DBType } from './types';
+
+// Interface for column configuration
+export interface ColumnConfig {
+    name?: string;
+    type: DataTypes;
+    length?: number;
+    precision?: number;
+    scale?: number;
+    required?: boolean;
+    unique?: boolean;
+    defaultValue?: any;
+    index?: string; // Optional index name
+    softDelete?: boolean; // Marks column as soft delete field
+}
+
+// Interface for relationship configuration
+export interface RelationConfig {
+    type: RelationType;
+    target: () => any; // Reference to another model
+    property: string; // Property name in the model
+    foreignKey?: string;
+    inverseKey?: string;
+    joinTable?: string;
+}
+
+// Interface for model configuration
+export interface ModelConfig {
+    tableName: string;
+    versioned?: boolean;
+    softDelete?: boolean;
+    columns: Record<string, ColumnConfig>;
+    relations?: RelationConfig[];
+}
+
+// Metadata storage for models
+export class MetadataStorage {
+    private static models: Map<Function, ModelConfig> = new Map();
+
+    static setModelMetadata(model: Function, config: ModelConfig) {
+        this.models.set(model, config);
+    }
+
+    static getModelMetadata(model: Function): ModelConfig | undefined {
+        return this.models.get(model);
+    }
+
+    static getTableName(model: Function): string {
+        return this.getModelMetadata(model)?.tableName || '';
+    }
+
+    static getColumns(model: Function): Record<string, ColumnConfig> {
+        return this.getModelMetadata(model)?.columns || {};
+    }
+
+    static getValidators(model: Function): Record<string, string[]> {
+        const columns = this.getModelMetadata(model)?.columns || {};
+        const validators: Record<string, string[]> = {};
+        for (const [key, col] of Object.entries(columns)) {
+            const rules: string[] = [];
+            if (col.required) rules.push('required');
+            if (col.unique) rules.push('unique');
+            validators[key] = rules;
+        }
+        return validators;
+    }
+
+    static getRelations(model: Function): Record<string, RelationConfig> {
+        const relations = this.getModelMetadata(model)?.relations || [];
+        const result: Record<string, RelationConfig> = {};
+        for (const rel of relations) {
+            result[rel.property] = rel;
+        }
+        return result;
+    }
+
+    static getSoftDeleteField(model: Function): string | null {
+        const columns = this.getModelMetadata(model)?.columns || {};
+        for (const [key, col] of Object.entries(columns)) {
+            if (col.softDelete) return key;
+        }
+        return null;
+    }
+
+    static isVersioned(model: Function): boolean {
+        return !!this.getModelMetadata(model)?.versioned;
+    }
+}
+
+// Programmatic model definition
+export function defineModel(config: ModelConfig) {
+    class Model {
+        constructor(data: any) {
+            Object.assign(this, data);
+        }
+    }
+
+    // Store metadata
+    MetadataStorage.setModelMetadata(Model, {
+        tableName: config.tableName,
+        versioned: config.versioned || false,
+        softDelete: config.softDelete || false,
+        columns: config.columns,
+        relations: config.relations || [],
+    });
+
+    return Model;
+}