stabilize-orm 1.3.8 → 2.1.0

package/logger.ts

@@ -1,127 +0,0 @@
-/**
- * @file logger.ts
- * @description Provides a flexible logger that can write to the console and/or rotating log files.
- * @author ElectronSz
- */
-
-import * as fs from "fs/promises";
-import {
-  LogLevel,
-  type LoggerConfig,
-  type PoolMetrics,
-  StabilizeError,
-} from "./types";
-
-/**
- * Defines the interface for a logger that can be used within the ORM.
- */
-export interface Logger {
-  logQuery(query: string, params: any[], executionTime?: number): void;
-  logError(error: Error): void;
-  logMetrics(metrics: PoolMetrics): void;
-  logInfo(message: string): void;
-  logWarn(message: string): void;
-  logDebug(message: string): void;
-}
-
-/**
- * A logger implementation that writes to the console and can optionally write to rotating files.
- */
-export class StabilizeLogger implements Logger {
-  private readonly level: LogLevel;
-  private readonly filePath: string | null;
-  private readonly maxFileSize: number;
-  private readonly maxFiles: number;
-
-  constructor(config: LoggerConfig = {}) {
-    this.level = config.level ?? LogLevel.Info;
-    this.filePath = config.filePath || null;
-    this.maxFileSize = config.maxFileSize || 1 * 1024 * 1024; // 1MB
-    this.maxFiles = config.maxFiles || 3;
-  }
-
-  /** @internal Checks if a message at a given level should be logged. */
-  private shouldLog(messageLevel: LogLevel): boolean {
-    return messageLevel <= this.level;
-  }
-
-  /** @internal Rotates log files if the current one exceeds the max size. */
-  private async rotateLogFile(): Promise<void> {
-    if (!this.filePath) return;
-
-    try {
-      const stats = await fs.stat(this.filePath).catch(() => null);
-      if (!stats || stats.size < this.maxFileSize) {
-        return; // No rotation needed
-      }
-
-      const oldestLog = `${this.filePath}.${this.maxFiles}`;
-      await fs.unlink(oldestLog).catch(() => {});
-
-      for (let i = this.maxFiles - 1; i >= 1; i--) {
-        const source = `${this.filePath}.${i}`;
-        const destination = `${this.filePath}.${i + 1}`;
-        if (await fs.stat(source).catch(() => null)) {
-          await fs.rename(source, destination);
-        }
-      }
-      await fs.rename(this.filePath, `${this.filePath}.1`);
-    } catch (error) {
-      // Use StabilizeError for internal logger failures
-      const logError = new StabilizeError("Log rotation failed", "LOG_ROTATION_ERROR", error as Error);
-      console.error(`[LOGGER_ERROR] ${logError.message}\n${logError.stack}`);
-    }
-  }
-
-  /** @internal Writes a formatted message to the console and/or a file. */
-  private async log(level: LogLevel, message: string): Promise<void> {
-    if (!this.shouldLog(level)) return;
-
-    const levelStr = LogLevel[level].toUpperCase();
-    const logEntry = `[${levelStr}] ${new Date().toISOString()} - ${message}`;
-
-    switch (level) {
-      case LogLevel.Error: console.error(logEntry); break;
-      case LogLevel.Warn: console.warn(logEntry); break;
-      default: console.log(logEntry); break;
-    }
-
-    if (this.filePath) {
-      try {
-        await this.rotateLogFile();
-        await fs.appendFile(this.filePath, logEntry + "\n");
-      } catch (error) {
-        // Use StabilizeError for internal logger failures
-        const logError = new StabilizeError("Failed to write to log file", "LOG_WRITE_ERROR", error as Error);
-        console.error(`[LOGGER_ERROR] ${logError.message}\n${logError.stack}`);
-      }
-    }
-  }
-
-  public logQuery(query: string, params: any[], executionTime?: number): void {
-    const time = executionTime ? `${executionTime.toFixed(2)}ms` : "N/A";
-    this.log(LogLevel.Debug, `Query: ${query} | Params: ${JSON.stringify(params)} | Time: ${time}`);
-  }
-
-  public logError(error: Error): void {
-    const message = `${error.message}${error.stack ? `\n${error.stack}` : ""}`;
-    this.log(LogLevel.Error, message);
-  }
-
-  public logMetrics(metrics: PoolMetrics): void {
-    const message = `Pool Metrics: Active=${metrics.activeConnections}, Idle=${metrics.idleConnections}, Total=${metrics.totalConnections}`;
-    this.log(LogLevel.Info, message);
-  }
-
-  public logInfo(message: string): void {
-    this.log(LogLevel.Info, message);
-  }
-  
-  public logWarn(message: string): void {
-    this.log(LogLevel.Warn, message);
-  }
-
-  public logDebug(message: string): void {
-    this.log(LogLevel.Debug, message);
-  }
-}

package/migrations.ts

@@ -1,318 +0,0 @@
-/**
- * @file migrations.ts
- * @description Contains functions for generating and running database migrations based on model metadata.
- * @author ElectronSz
- * @date 2025-10-15 20:55:49
- */
-
-import { DBClient } from "./client";
-import { MetadataStorage } from "./model";
-import { type DBConfig, type Migration, StabilizeError, DBType, DataTypes } from "./types";
-
-/**
- * @internal
- * Formats a SQL query with placeholders for the target database dialect.
- * @param query The SQL query string with '?' placeholders.
- * @param dbType The target database dialect.
- * @returns The formatted SQL query string.
- */
-function formatQuery(query: string, dbType: DBType): string {
-  if (dbType === DBType.Postgres) {
-    let paramIndex = 1;
-    return query.replace(/\?/g, () => `$${paramIndex++}`);
-  }
-  return query;
-}
-
-/**
- * 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;
-  if (typeof dt === "string") {
-    type = dt.toLowerCase();
-  } else {
-    type = DataTypes[dt].toLowerCase();
-  }
-
-  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";
-    }
-  }
-  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 an auto-incrementing primary key.
- * @param dbType The target database dialect.
- * @returns The SQL string for the primary key column definition.
- */
-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";
-  }
-}
-
-/**
- * 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 A promise that resolves to a `Migration` object containing the `up` and `down` SQL scripts.
- */
-export async function generateMigration(
-  model: new (...args: any[]) => any,
-  name: string,
-  dbType: DBType,
-): Promise<Migration> {
-  const tableName = MetadataStorage.getTableName(model);
-  if (!tableName) {
-    throw new StabilizeError("Model not defined with tableName", "MIGRATION_ERROR");
-  }
-
-  const columns = MetadataStorage.getColumns(model);
-  const validators = MetadataStorage.getValidators(model);
-  const versioned = MetadataStorage.isVersioned(model);
-  const timestamps = MetadataStorage.getTimestamps(model);
-
-  const columnDefs: string[] = [];
-
-  for (const [key, col] of Object.entries(columns)) {
-    const defParts: string[] = [];
-
-    if (col.name === "id") {
-      defParts.push("id");
-      defParts.push(getAutoIncrementPK(dbType));
-    } else {
-      defParts.push(col.name || key);
-      defParts.push(mapDataTypeToSql(col.type, dbType));
-    }
-
-    if (validators[key]?.includes("required")) {
-      defParts.push("NOT NULL");
-    }
-    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(" "));
-  }
-
-  // Add timestamp columns if enabled
-  if (timestamps) {
-    for (const [field, colName] of Object.entries(timestamps)) {
-      // Use the field name defined in the timestamps config
-      let sqlType = dbType === DBType.Postgres ? "TIMESTAMP" : "DATETIME";
-      let def = `${colName} ${sqlType} NOT NULL`;
-
-      // Set default value for createdAt, and optionally for updatedAt
-      if (field === "createdAt") {
-        def += " DEFAULT CURRENT_TIMESTAMP";
-      } else if (field === "updatedAt") {
-        def += " DEFAULT CURRENT_TIMESTAMP";
-        // For MySQL, add ON UPDATE CURRENT_TIMESTAMP
-        if (dbType === DBType.MySQL) {
-          def += " ON UPDATE CURRENT_TIMESTAMP";
-        }
-      }
-
-      columnDefs.push(def);
-    }
-  }
-
-  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" : "");
-
-  // Strip constraints for history columns
-  function cleanColumnDef(def: string): string {
-    return def
-      .replace(/\s+PRIMARY\s+KEY\b/gi, "")
-      .replace(/\s+UNIQUE\b/gi, "");
-  }
-
-  const historyColumns = [
-    ...columnDefs.map(cleanColumnDef),
-    `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.
- * @param dbType The target database dialect.
- * @returns The SQL string for the `CREATE TABLE` statement.
- */
-function getMigrationsTableSQL(dbType: DBType): string {
-  switch (dbType) {
-    case DBType.Postgres:
-      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 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 stabilize_migrations (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        name TEXT UNIQUE NOT NULL,
-        applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
-      )`;
-  }
-}
-
-/**
- * Connects to the database and runs all pending migrations.
- * @param config The database configuration object.
- * @param migrations An array of `Migration` objects to be executed.
- */
-export async function runMigrations(config: DBConfig, migrations: Migration[]) {
-  const client = new DBClient(config);
-  try {
-    const dbType = config.type;
-    await client.query(getMigrationsTableSQL(dbType));
-
-    for (const [index, migration] of migrations.entries()) {
-      const name = migration.name || `migration_${index}_${new Date().getTime()}`;
-
-      const selectQuery = formatQuery(`SELECT id FROM stabilize_migrations WHERE name = ?`, dbType);
-      const applied = await client.query<{ id: number }>(selectQuery, [name]);
-
-      if (applied.length === 0) {
-        await client.transaction(async (txClient) => {
-          console.log(`Applying migration: ${name}...`);
-          for (const query of migration.up) {
-            await txClient.query(query);
-          }
-
-          const insertQuery = formatQuery(`INSERT INTO stabilize_migrations (name, applied_at) VALUES (?, ?)`, dbType);
-          let appliedAt: string;
-          if (dbType === DBType.MySQL) {
-            appliedAt = new Date().toISOString().slice(0, 19).replace("T", " ");
-          } else {
-            appliedAt = new Date().toISOString();
-          }
-          await txClient.query(insertQuery, [name, appliedAt]);
-
-          console.log(`Migration ${name} applied successfully.`);
-        });
-      }
-    }
-  } catch (error) {
-    console.error("Migration failed:", error);
-    throw error;
-  } finally {
-    await client.close();
-  }
-}
-
-export type { Migration };
-export { mapDataTypeToSql };

package/query-builder.ts

@@ -1,209 +0,0 @@
-/**
- * @file query-builder.ts
- * @description Provides a fluent API for building and executing SQL queries in a database-agnostic way.
- * @author ElectronSz
- */
-
-import { DBClient } from "./client";
-import { Cache } from "./cache";
-import { MetadataStorage } from "./model";
-import { StabilizeError } from "./types";
-
-/**
- * A fluent interface for building SQL SELECT queries.
- * This class allows for the programmatic and readable construction of queries
- * that can be executed on different database systems via the DBClient.
- * @template T The type of the entity being queried.
- */
-export class QueryBuilder<T> {
-  private table: string;
-  private selectFields: string[] = ["*"];
-  private joins: string[] = [];
-  private whereConditions: string[] = [];
-  private whereParams: any[] = [];
-  private orderByClause: string | null = null;
-  private limitValue: number | null = null;
-  private offsetValue: number | null = null;
-
-  /**
-   * Creates an instance of QueryBuilder.
-   * @param table The name of the main table to query from.
-   */
-  constructor(table: string) {
-    this.table = table;
-  }
-
-  /**
-   * Specifies the columns to select. If not called, all columns (`*`) are selected by default.
-   * @param fields A list of column names to select.
-   * @returns The `QueryBuilder` instance for chaining.
-   * @example
-   * ```
-   * queryBuilder.select('id', 'name', 'email');
-   * ```
-   */
-  select(...fields: string[]): QueryBuilder<T> {
-    this.selectFields = fields.length > 0 ? fields : ["*"];
-    return this;
-  }
-
-  /**
-   * Adds a WHERE clause to the query. Multiple calls will be joined with AND.
-   * @param condition The SQL condition string with `?` as placeholders.
-   * @param params The values to substitute for the `?` placeholders.
-   * @returns The `QueryBuilder` instance for chaining.
-   * @example
-   * ```
-   * queryBuilder.where('status = ?', 'active').where('age > ?', 21);
-   * ```
-   */
-  where(condition: string, ...params: any[]): QueryBuilder<T> {
-    this.whereConditions.push(condition);
-    this.whereParams.push(...params);
-    return this;
-  }
-
-  /**
-   * Adds a LEFT JOIN clause to the query.
-   * @param table The name of the table to join with.
-   * @param condition The ON condition for the join.
-   * @returns The `QueryBuilder` instance for chaining.
-   * @example
-   * ```
-   * queryBuilder.join('profiles', 'profiles.userId = users.id');
-   * ```
-   */
-  join(table: string, condition: string): QueryBuilder<T> {
-    this.joins.push(`LEFT JOIN ${table} ON ${condition}`);
-    return this;
-  }
-
-  /**
-   * Adds an ORDER BY clause to the query.
-   * @param clause The column and direction for ordering (e.g., 'createdAt DESC').
-   * @returns The `QueryBuilder` instance for chaining.
-   * @example
-   * ```
-   * queryBuilder.orderBy('lastName ASC');
-   * ```
-   */
-  orderBy(clause: string): QueryBuilder<T> {
-    this.orderByClause = clause;
-    return this;
-  }
-
-  /**
-   * Adds a LIMIT clause to the query to restrict the number of rows returned.
-   * @param limit The maximum number of rows to return.
-   * @returns The `QueryBuilder` instance for chaining.
-   * @example
-   * ```
-   * queryBuilder.limit(10);
-   * ```
-   */
-  limit(limit: number): QueryBuilder<T> {
-    this.limitValue = limit;
-    return this;
-  }
-
-  /**
-   * Adds an OFFSET clause to the query for pagination.
-   * @param offset The number of rows to skip.
-   * @returns The `QueryBuilder` instance for chaining.
-   * @example
-   * ```
-   * queryBuilder.offset(20);
-   * ```
-   */
-  offset(offset: number): QueryBuilder<T> {
-    this.offsetValue = offset;
-    return this;
-  }
-
-  /**
-   * Constructs the final SQL query string and its corresponding parameters.
-   * This is an internal method, typically called by `execute`.
-   * @returns An object containing the final `query` string and `params` array.
-   */
-  build(): { query: string; params: any[] } {
-    let query = `SELECT ${this.selectFields.join(", ")} FROM ${this.table}`;
-
-    if (this.joins.length > 0) {
-      query += " " + this.joins.join(" ");
-    }
-    if (this.whereConditions.length > 0) {
-      query += " WHERE " + this.whereConditions.join(" AND ");
-    }
-    if (this.orderByClause) {
-      query += ` ORDER BY ${this.orderByClause}`;
-    }
-    if (this.limitValue !== null) {
-      query += ` LIMIT ${this.limitValue}`;
-    }
-    if (this.offsetValue !== null) {
-      query += ` OFFSET ${this.offsetValue}`;
-    }
-    return { query, params: this.whereParams };
-  }
-
-  /**
-   * Executes the constructed query against the database using the provided client.
-   * Handles cache-aside logic if a cache and cacheKey are provided.
-   * @param client The `DBClient` instance to use for executing the query.
-   * @param cache Optional: The `Cache` instance to use for caching.
-   * @param cacheKey Optional: The key to use for getting/setting the result in the cache.
-   * @returns A promise that resolves to an array of results of type `T`.
-   * @example
-   * ```
-   * const users = await stabilize.getRepository(User)
-   *   .find()
-   *   .where('status = ?', 'active')
-   *   .limit(10)
-   *   .execute(dbClient, cache, 'active_users_page_1');
-   * ```
-   */
-  async execute(
-    client: DBClient,
-    cache?: Cache,
-    cacheKey?: string,
-  ): Promise<T[]> {
-    const { query, params } = this.build();
-
-    // Attempt to retrieve from cache first (cache-aside read)
-    if (cache && cacheKey) {
-      const cached = await cache.get<T[]>(cacheKey);
-      if (cached) return cached;
-    }
-
-    // If not in cache, execute query against the database
-    const results = await client.query<T>(query, params);
-
-    // Store the database results in the cache for future requests
-    if (cache && cacheKey && results.length > 0) {
-      await cache.set(cacheKey, results, 60);
-    }
-
-    return results;
-  }
-
-  /**
-   * Applies a named scope to the current query builder.
-   *
-   * This method looks up a scope function by name for the current model (based on the table name),
-   * then invokes the scope function with the query builder and any additional arguments.
-   *
-   * @param {string} name - The name of the scope to apply.
-   * @param {...any} args - Additional arguments to pass to the scope function.
-   * @throws {StabilizeError} If no model is found for the current table, or if the specified scope does not exist.
-   * @returns {QueryBuilder<T>} The query builder instance after applying the scope.
-   */
-  scope(name: string, ...args: any[]): QueryBuilder<T> {
-    const model = Object.values(MetadataStorage['models']).find(m => m.tableName === this.table)?.constructor;
-    if (!model) throw new StabilizeError(`Model for table ${this.table} not found`, "SCOPE_ERROR");
-    const scopes = MetadataStorage.getScopes(model);
-    const scopeFn = scopes[name];
-    if (!scopeFn) throw new StabilizeError(`Scope ${name} not found`, "SCOPE_ERROR");
-    return scopeFn(this, ...args);
-  }
-  
-}