stabilize-orm 1.1.3 → 1.1.5

package/index.ts

@@ -1,3 +1,9 @@
+/**
+ * @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";
 import { type Logger, ConsoleLogger } from "./logger";
@@ -25,6 +31,7 @@ import {
   type CacheConfig,
   type LoggerConfig,
   DBType,
+  DataTypes, // --- FIX: Import DataTypes here ---
   StabilizeError,
   type PoolMetrics,
   type QueryHint,
@@ -33,79 +40,120 @@ import {
   LogLevel,
 } from "./types";
 
+
 export class Stabilize {
-  private client: DBClient;
+  public client: DBClient;
   private cache: Cache | null;
   private logger: Logger;
 
+  /**
+   * Creates an instance of the Stabilize ORM.
+   * @param config The database configuration object.
+   * @param cacheConfig Optional configuration for the cache. Caching is disabled if not provided.
+   * @param loggerConfig Optional configuration for the logger.
+   */
   constructor(
     config: DBConfig,
     cacheConfig: CacheConfig = { enabled: false, ttl: 60 },
     loggerConfig: LoggerConfig = {},
+    existingClient?: DBClient,
   ) {
     this.logger = new ConsoleLogger(loggerConfig);
-    this.client = new DBClient(config, this.logger);
-    this.cache = cacheConfig.enabled
+    this.client = existingClient || new DBClient(config, this.logger);
+    this.cache = existingClient ? null : (cacheConfig.enabled
       ? new Cache(cacheConfig, this.logger)
-      : null;
+      : null);
   }
 
+  /**
+   * Gets a repository for a given model, used to perform CRUD operations.
+   * @param model The model class, which must be decorated with `@Model`.
+   * @returns A new `Repository` instance for the specified model.
+   * @example
+   * ```
+   * const stabilize = new Stabilize(dbConfig);
+   * const userRepository = stabilize.getRepository(User);
+   * 
+   * const user = await userRepository.findOne(1);
+   * console.log(user);
+   * ```
+   */
   getRepository<T>(model: new (...args: any[]) => T): Repository<T> {
-    if (this.cache) {
-      const cacheInstance = this.cache as any;
-      const repoCacheConfig: CacheConfig = {
-        enabled: true,
-        ttl: 60,
-        redisUrl: cacheInstance.redisUrl,
-        cachePrefix: cacheInstance.prefix,
-        strategy: this.cache.getStrategy(),
-      };
-      return new Repository(this.client, model, repoCacheConfig, this.logger);
-    }
-
-    return new Repository(
-      this.client,
-      model,
-      { enabled: false, ttl: 60 },
-      this.logger,
-    );
-  }
-
-  async transaction<T>(callback: () => Promise<T>): Promise<T> {
-    return await this.client.transaction(callback);
+    const cacheConfig = this.cache ? this.cache.config : undefined;
+    return new Repository(this.client, model, cacheConfig, this.logger);
   }
 
-  async savepoint<T>(name: string, callback: () => Promise<T>): Promise<T> {
-    return await this.client.savepoint(name, callback);
-  }
-
-  async switchConnection(config: DBConfig) {
-    await this.client.switchConnection(config);
+  /**
+   * Executes a callback within a database transaction, ensuring all operations are atomic.
+   * The callback receives a transactional `DBClient` instance that must be passed to
+   * repository methods to ensure they are part of the same transaction.
+   * 
+   * @param callback The async function to execute. It receives a `txClient` as its only argument.
+   * @returns The result of the callback function.
+   * @example
+   * ```
+   * const userRepo = stabilize.getRepository(User);
+   * const profileRepo = stabilize.getRepository(Profile);
+   * 
+   * 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.');
+   * } catch (error) {
+   *   console.error('Transaction failed, everything was rolled back.', error);
+   * }
+   * ```
+   */
+  async transaction<T>(callback: (txClient: DBClient) => Promise<T>): Promise<T> {
+    return this.client.transaction(callback);
   }
 
+  /**
+   * Retrieves statistics from the cache, if it is enabled.
+   * @returns A promise that resolves to an object containing cache hits, misses, and total keys.
+   * @example
+   * ```
+   * const stats = await stabilize.getCacheStats();
+   * console.log(`Cache Hits: ${stats.hits}, Misses: ${stats.misses}`);
+   * ```
+   */
   async getCacheStats(): Promise<CacheStats> {
-    return this.cache
-      ? await this.cache.getStats()
-      : { hits: 0, misses: 0, keys: 0 };
-  }
-
-  getPoolMetrics(): PoolMetrics {
-    return this.client.getPoolMetrics();
+    if (!this.cache) {
+      return { hits: 0, misses: 0, keys: 0 };
+    }
+    return this.cache.getStats();
   }
 
+  /**
+   * Closes the database connection and disconnects the cache client for a graceful shutdown.
+   * @example
+   * ```
+   * await stabilize.close();
+   * console.log('Connections closed.');
+   * ```
+   */
   async close() {
     await this.client.close();
-    if (this.cache) await this.cache.disconnect();
+    if (this.cache) {
+      await this.cache.disconnect();
+    }
   }
 }
 
 export {
-  // Types
+  Repository,
+  DBClient,
+  QueryBuilder,
+  Cache,
+  ConsoleLogger,
   DBType,
+  DataTypes, 
   LogLevel,
   RelationType,
   StabilizeError,
-  // Decorators
   Model,
   Column,
   Required,
@@ -120,19 +168,12 @@ export {
   ValidatorKey,
   RelationKey,
   SoftDeleteKey,
-  // Classes
-  Cache,
-  DBClient,
-  QueryBuilder,
-  Repository,
-  ConsoleLogger,
-  // Migrations
   runMigrations,
   generateMigration,
 };
 
-export type { Migration };
 export type {
+  Migration,
   DBConfig,
   CacheConfig,
   LoggerConfig,
@@ -140,4 +181,4 @@ export type {
   PoolMetrics,
   CacheStats,
   Logger,
-};
+};

package/logger.ts

@@ -1,6 +1,10 @@
-// src/logger.ts
+/**
+ * @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 * as path from "path";
 import {
   LogLevel,
   type LoggerConfig,
@@ -8,119 +12,116 @@ import {
   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 ConsoleLogger implements Logger {
-  private level: LogLevel;
-  private filePath: string | null;
-  private maxFileSize: number;
-  private maxFiles: number;
-  private currentFileSize: number = 0;
+  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.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 {
-    const levels = [
-      LogLevel.ERROR,
-      LogLevel.WARN,
-      LogLevel.INFO,
-      LogLevel.DEBUG,
-    ];
-    return levels.indexOf(messageLevel) <= levels.indexOf(this.level);
+    return messageLevel <= this.level;
   }
 
-  private async rotateLogFile() {
+  /** @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) {
-        for (let i = this.maxFiles - 1; i > 0; i--) {
-          const oldPath = i === 1 ? this.filePath : `${this.filePath}.${i - 1}`;
-          const newPath = `${this.filePath}.${i}`;
-          if (await fs.stat(oldPath).catch(() => null)) {
-            await fs.rename(oldPath, newPath).catch(() => {});
-          }
+      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.writeFile(this.filePath, "");
-        this.currentFileSize = 0;
       }
+      await fs.rename(this.filePath, `${this.filePath}.1`);
     } catch (error) {
-      console.error("Log rotation failed:", 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}`);
     }
   }
 
-  private async writeToFile(message: string) {
-    if (!this.filePath) return;
+  /** @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;
 
-    try {
-      await this.rotateLogFile();
-      const logEntry = `${new Date().toISOString()} ${message}\n`;
-      await fs.appendFile(this.filePath, logEntry);
-      this.currentFileSize += Buffer.byteLength(logEntry);
-    } catch (error) {
-      console.error("Failed to write to log file:", error);
+    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;
     }
-  }
 
-  logQuery(query: string, params: any[], executionTime?: number) {
-    if (this.shouldLog(LogLevel.DEBUG)) {
-      const message = `[DEBUG] Query: ${query} | Params: ${JSON.stringify(params)} | Time: ${executionTime ? `${executionTime.toFixed(2)}ms` : "N/A"}`;
-      console.log(message);
-      if (this.filePath) {
-        this.writeToFile(message);
+    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}`);
       }
     }
   }
 
-  logError(error: Error) {
-    if (this.shouldLog(LogLevel.ERROR)) {
-      const message = `[ERROR] ${error.message}${error.stack ? `\n${error.stack}` : ""}`;
-      console.error(message);
-      if (this.filePath) {
-        this.writeToFile(message);
-      }
-    }
+  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}`);
   }
 
-  logMetrics(metrics: PoolMetrics) {
-    if (this.shouldLog(LogLevel.INFO)) {
-      const message = `[INFO] Pool Metrics: Active=${metrics.activeConnections}, Idle=${metrics.idleConnections}, Total=${metrics.totalConnections}`;
-      console.log(message);
-      if (this.filePath) {
-        this.writeToFile(message);
-      }
-    }
+  public logError(error: Error): void {
+    const message = `${error.message}${error.stack ? `\n${error.stack}` : ""}`;
+    this.log(LogLevel.Error, message);
   }
 
-  logInfo(message: string) {
-    if (this.shouldLog(LogLevel.INFO)) {
-      const formatted = `[INFO] ${message}`;
-      console.log(formatted);
-      if (this.filePath) {
-        this.writeToFile(formatted);
-      }
-    }
+  public logMetrics(metrics: PoolMetrics): void {
+    const message = `Pool Metrics: Active=${metrics.activeConnections}, Idle=${metrics.idleConnections}, Total=${metrics.totalConnections}`;
+    this.log(LogLevel.Info, message);
   }
 
-  logDebug(message: string) {
-    if (this.shouldLog(LogLevel.DEBUG)) {
-      const formatted = `[DEBUG] ${message}`;
-      console.log(formatted);
-      if (this.filePath) {
-        this.writeToFile(formatted);
-      }
-    }
+  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);
+  }
+}