stabilize-orm 1.3.8 → 2.1.0

package/cache.ts

@@ -1,181 +0,0 @@
-/**
- * @file cache.ts
- * @description Provides a Redis-backed caching layer for the ORM.
- * @author ElectronSz
- */
-
-import Redis from "ioredis";
-import { type CacheConfig, type CacheStats } from "./types";
-import { StabilizeLogger, type Logger } from "./logger";
-
-/**
- * A caching client that uses Redis to store and retrieve query results.
- * It supports cache-aside and write-through strategies and keeps track of basic stats.
- */
-export class Cache {
-  private redis: Redis | null = null;
-  private logger: Logger;
-  private hits: number = 0;
-  private misses: number = 0;
-
-  /** The configuration object the cache was initialized with. */
-  public readonly config: CacheConfig;
-
-  /**
-   * Creates an instance of the Cache client.
-   * @param config The configuration for the cache, including Redis URL and TTL.
-   * @param logger A logger instance for logging messages.
-   */
-  constructor(config: CacheConfig, logger: Logger = new StabilizeLogger()) {
-    this.config = config;
-    this.logger = logger;
-
-    if (this.config.enabled && this.config.redisUrl) {
-      this.redis = new Redis(this.config.redisUrl, { lazyConnect: true });
-      this.redis.on("error", (error) => this.logger.logError(error));
-    }
-  }
-
-  /**
-   * Gets the caching strategy being used.
-   * @returns The caching strategy, either 'cache-aside' or 'write-through'.
-   */
-  getStrategy() {
-    return this.config.strategy || "cache-aside";
-  }
-
-  /**
-   * Retrieves an item from the cache.
-   * @template T The expected type of the cached item.
-   * @param key The key of the item to retrieve.
-   * @returns A promise that resolves to the cached item or `null` if not found.
-   * @example
-   * ```
-   * const user = await cache.get<User>('user:1');
-   * ```
-   */
-  async get<T>(key: string): Promise<T | null> {
-    if (!this.redis) return null;
-
-    try {
-      const data = await this.redis.get(this.config.cachePrefix + key);
-      if (data) {
-        this.hits++;
-        this.logger.logDebug(`Cache hit for key: ${key}`);
-        return JSON.parse(data) as T;
-      }
-      this.misses++;
-      this.logger.logDebug(`Cache miss for key: ${key}`);
-      return null;
-    } catch (error) {
-      this.logger.logError(error as Error);
-      return null;
-    }
-  }
-
-  /**
-   * Stores an item in the cache.
-   * @template T The type of the item being stored.
-   * @param key The key to store the item under.
-   * @param value The value to store.
-   * @param ttl Optional: The time-to-live for this specific item in seconds. Defaults to the global TTL.
-   * @returns A promise that resolves when the item is set.
-   * @example
-   * ```
-   * await cache.set('user:1', user, 3600); // Cache for 1 hour
-   * ```
-   */
-  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
-    if (!this.redis) return;
-
-    try {
-      const effectiveTtl = ttl ?? this.config.ttl;
-      await this.redis.set(this.config.cachePrefix + key, JSON.stringify(value), "EX", effectiveTtl);
-      this.logger.logDebug(`Cache set for key: ${key}`);
-    } catch (error) {
-      this.logger.logError(error as Error);
-    }
-  }
-
-  /**
-   * Removes one or more items from the cache by their exact keys.
-   * @param keys An array of keys to invalidate.
-   * @returns A promise that resolves when the keys are invalidated.
-   * @example
-   * ```
-   * await cache.invalidate(['user:1', 'all_users']);
-   * ```
-   */
-  async invalidate(keys: string[]): Promise<void> {
-    if (!this.redis) return;
-
-    try {
-      const pipeline = this.redis.pipeline();
-      for (const key of keys) {
-        pipeline.del(this.config.cachePrefix + key);
-        this.logger.logDebug(`Cache invalidated for key: ${key}`);
-      }
-      await pipeline.exec();
-    } catch (error) {
-      this.logger.logError(error as Error);
-    }
-  }
-
-  /**
-   * Invalidates all keys matching a given pattern.
-   * @param pattern The pattern to match against (e.g., 'user:*').
-   * @returns A promise that resolves when the operation is complete.
-   * @example
-   * ```
-   * await cache.invalidatePattern('user:*'); // Invalidates all user-related cache
-   * ```
-   */
-  async invalidatePattern(pattern: string): Promise<void> {
-    if (!this.redis) return;
-
-    try {
-      const keys = await this.redis.keys(this.config.cachePrefix + pattern);
-      if (keys.length > 0) {
-        const pipeline = this.redis.pipeline();
-        for (const key of keys) {
-          pipeline.del(key);
-        }
-        await pipeline.exec();
-        this.logger.logDebug(`Cache invalidated for pattern: ${pattern} (${keys.length} keys)`);
-      }
-    } catch (error) {
-      this.logger.logError(error as Error);
-    }
-  }
-
-  /**
-   * Retrieves statistics about the cache, including hits, misses, and total key count.
-   * @returns A promise that resolves to a `CacheStats` object.
-   * @example
-   * ```
-   * const stats = await cache.getStats();
-   * console.log(`Cache Hits: ${stats.hits}, Misses: ${stats.misses}`);
-   * ```
-   */
-  async getStats(): Promise<CacheStats> {
-    if (!this.redis) return { hits: 0, misses: 0, keys: 0 };
-    try {
-      const keys = await this.redis.keys(this.config.cachePrefix + "*");
-      return { hits: this.hits, misses: this.misses, keys: keys.length };
-    } catch (error) {
-      this.logger.logError(error as Error);
-      return { hits: this.hits, misses: this.misses, keys: 0 };
-    }
-  }
-
-  /**
-   * Disconnects the Redis client gracefully.
-   * @returns A promise that resolves when the client has disconnected.
-   */
-  async disconnect(): Promise<void> {
-    if (this.redis) {
-      await this.redis.quit();
-      this.logger.logInfo("Redis connection closed");
-    }
-  }
-}

package/client.ts

@@ -1,249 +0,0 @@
-/**
- * @file client.ts
- * @description Provides a unified database client for interacting with PostgreSQL, MySQL, and SQLite.
- * @author ElectronSz
- */
-
-import { Database, Statement } from "bun:sqlite";
-import { Pool, type PoolClient } from "pg";
-import mysql from "mysql2/promise";
-import {
-  type DBConfig,
-  StabilizeError,
-  DBType,
-} from "./types";
-import { type Logger, StabilizeLogger } from "./logger";
-
-/**
- * Checks if the DB configuration is for SQLite.
- * @param config The database configuration object.
- * @returns True if the configuration is for SQLite, false otherwise.
- */
-function isSQLiteConfig(config: DBConfig): boolean {
-  return config.type === DBType.SQLite;
-}
-
-/**
- * Checks if the DB configuration is for MySQL.
- * @param config The database configuration object.
- * @returns True if the configuration is for MySQL, false otherwise.
- */
-function isMySQLConfig(config: DBConfig): boolean {
-  return config.type === DBType.MySQL;
-}
-
-/**
- * Checks if the given client is a MySQL pool.
- * @param client The database client.
- * @returns True if the client is a MySQL pool, false otherwise.
- */
-function isMySQLPool(client: any): client is mysql.Pool {
-  return typeof client.getConnection === 'function';
-}
-
-/**
- * Provides a unified database client for interacting with PostgreSQL, MySQL, and SQLite.
- */
-export class DBClient {
-  private client!: Database | Pool | mysql.Pool | PoolClient | mysql.PoolConnection;
-  private logger: Logger;
-  public readonly config: DBConfig;
-  private retryAttempts: number;
-  private retryDelay: number;
-  private maxJitter: number;
-
-  private preparedStatements: Map<string, Statement> = new Map();
-  public readonly isTransactionClient: boolean = false;
-
-  /**
-   * Constructs a new DBClient instance.
-   * @param config The database configuration object.
-   * @param logger Optional logger instance. Uses StabilizeLogger if not provided.
-   * @param existingClient Optional existing transaction client.
-   */
-  constructor(
-    config: DBConfig,
-    logger: Logger = new StabilizeLogger(),
-    existingClient: PoolClient | mysql.PoolConnection | null = null,
-  ) {
-    this.config = config;
-    this.logger = logger;
-    this.retryAttempts = config.retryAttempts || 3;
-    this.retryDelay = config.retryDelay || 1000;
-    this.maxJitter = config.maxJitter || 100;
-
-    if (existingClient) {
-      this.client = existingClient;
-      this.isTransactionClient = true;
-    } else {
-      this.initializeClient(config);
-    }
-  }
-
-  /**
-   * Initializes the database client based on the configuration.
-   * @param config The database configuration object.
-   */
-  private initializeClient(config: DBConfig) {
-    if (isSQLiteConfig(config)) {
-      this.client = new Database(config.connectionString, { create: true });
-      this.logger.logDebug(`Initialized Bun SQLite client.`);
-    } else if (isMySQLConfig(config)) {
-      this.client = mysql.createPool(config.connectionString);
-      this.logger.logDebug(`Initialized MySQL Pool client.`);
-    } else if (config.type = DBType.Postgres) { // NOTE: single '=' should be '===', this is likely a bug
-      this.client = new Pool({ connectionString: config.connectionString! });
-      this.logger.logDebug(`Initialized Postgres Pool client.`);
-    }
-  }
-
-  /**
-   * Returns a random jitter value for retry logic.
-   * @returns A random number up to maxJitter.
-   */
-  private getJitter = () => Math.random() * this.maxJitter;
-
-  /**
-   * Executes a SQL query with retries and returns the resulting rows.
-   * @param query The SQL query string.
-   * @param params Query parameters.
-   * @returns Array of resulting rows.
-   * @throws StabilizeError if all retry attempts fail.
-   */
-  async query<T>(query: string, params: any[] = []): Promise<T[]> {
-    const start = Date.now();
-
-    for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
-      try {
-        let result: any;
-
-        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) {
-          const [rows] = await (this.client as mysql.Pool).query(query, params);
-          result = rows;
-        } 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);
-          result = Array.isArray(pgResult.rows) ? pgResult.rows : [];
-        } else {
-          throw new StabilizeError("Unknown database client type", "QUERY_ERROR");
-        }
-
-        const executionTime = Date.now() - start;
-        this.logger.logQuery(query, params, executionTime);
-        return Array.isArray(result) ? result as T[] : [];
-      } catch (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");
-        }
-        await new Promise(res => setTimeout(res, this.retryDelay * Math.pow(2, attempt - 1) + this.getJitter()));
-      }
-    }
-    throw new StabilizeError("Query failed: maximum retries reached without success", "QUERY_ERROR");
-  }
-
-  /**
-   * Runs a callback within a database transaction.
-   * Handles commit/rollback and connection release.
-   * @param callback The callback to execute within the transaction context.
-   * @returns The result of the callback.
-   * @throws StabilizeError if transactions are not supported or rollback is triggered.
-   */
-  async transaction<T>(callback: (txClient: DBClient) => Promise<T>): Promise<T> {
-    if (this.isTransactionClient) return callback(this);
-
-    if (this.client instanceof Database) {
-      const tx = this.client.transaction(() => callback(this));
-      return tx();
-    }
-
-    if (isMySQLPool(this.client)) {
-      const connection = await this.client.getConnection();
-      const txClient = new DBClient(this.config, this.logger, connection);
-      this.logger.logDebug("Starting MySQL transaction.");
-      try {
-        await txClient.query("START TRANSACTION");
-        const result = await callback(txClient);
-        await txClient.query("COMMIT");
-        return result;
-      } catch (error) {
-        await txClient.query("ROLLBACK");
-        throw error;
-      } finally {
-        connection.release();
-        this.logger.logDebug("MySQL transaction connection released.");
-      }
-    }
-
-    if (this.client instanceof Pool) {
-      const connection = await this.client.connect();
-      const txClient = new DBClient(this.config, this.logger, connection);
-      this.logger.logDebug("Starting Postgres transaction.");
-      try {
-        await txClient.migrationQuery("BEGIN");
-        const result = await callback(txClient);
-        await txClient.migrationQuery("COMMIT");
-        return result;
-      } catch (error) {
-        await txClient.migrationQuery("ROLLBACK");
-        throw error;
-      } finally {
-        connection.release();
-        this.logger.logDebug("Postgres transaction connection released.");
-      }
-    }
-
-    throw new StabilizeError("Transaction not supported by this client configuration.", "TX_ERROR");
-  }
-
-  /**
-   * Closes the database connection.
-   * For pooled connections, ends the pool.
-   * @returns Promise that resolves once the connection is closed.
-   */
-  async close() {
-    if (this.client instanceof Database) {
-      this.client.close();
-    } else if (this.client && 'end' in this.client) {
-      await (this.client as any).end();
-    }
-    this.client = null!;
-    this.logger.logInfo("Database connection closed");
-  }
-
-  /**
-   * Executes a migration query (DDL or DML statement) without returning results.
-   * Handles parameterized queries and statement preparation.
-   * @param query The SQL query string.
-   * @param params Query parameters.
-   * @returns Promise that resolves once the query is complete.
-   */
-  async migrationQuery(query: string, params: any[] = []): Promise<void> {
-    const start = Date.now();
-    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))) {
-      await (this.client as mysql.Pool).query(query, params);
-    } else if (this.config.type = DBType.Postgres) { // NOTE: single '=' should be '===', this is likely a bug
-      let paramIndex = 0;
-      const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
-      await (this.client as Pool).query(pgQuery, params);
-    }
-
-    const executionTime = Date.now() - start;
-    this.logger.logQuery(query, params, executionTime);
-  }
-}

package/docker-compose.yml

@@ -1,22 +0,0 @@
-
-services:
-  db:
-    image: mariadb:latest
-    container_name: mariadb-container
-    restart: always
-    environment:
-      # Required: set a secure root password
-      MARIADB_ROOT_PASSWORD: P@ssw0rd
-      # Optional: set up a default database and user
-      MARIADB_DATABASE: db
-      MARIADB_USER: admin
-      MARIADB_PASSWORD: P@ssw0rd
-    ports:
-      # Map host port 3306 to container port 3306
-      - '3306:3306'
-    volumes:
-      # Create a named volume for persistent data storage
-      - mariadb_data:/var/lib/mysql
-
-volumes:
-  mariadb_data:

package/hooks.ts

@@ -1,76 +0,0 @@
-/**
- * @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?:  Partial<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

@@ -1,158 +0,0 @@
-/**
- * @file stabilize.ts
- * @description The main entry point for the Stabilize ORM, tying together the client, cache, and repositories.
- * @author ElectronSz
- */
-import { Cache } from "./cache";
-import { DBClient } from "./client";
-import { type Logger, StabilizeLogger } from "./logger";
-import { QueryBuilder } from "./query-builder";
-import { Repository } from "./repository";
-import { runMigrations, generateMigration, type Migration, mapDataTypeToSql} from "./migrations";
-import {
-  type DBConfig,
-  type CacheConfig,
-  type LoggerConfig,
-  DBType,
-  DataTypes,
-  StabilizeError,
-  type PoolMetrics,
-  type QueryHint,
-  RelationType,
-  type CacheStats,
-  LogLevel,
-} from "./types";
-import { defineModel, MetadataStorage } from "./model";
-import type { Hook } from "./hooks";
-
-export class Stabilize {
-  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 StabilizeLogger(loggerConfig);
-    this.client = existingClient || new DBClient(config, this.logger);
-    this.cache = existingClient ? null : (cacheConfig.enabled
-      ? new Cache(cacheConfig, this.logger)
-      : null);
-  }
-
-  /**
-   * Gets a repository for a given model, used to perform CRUD operations.
-   * @param model The model class, defined using `defineModel`.
-   * @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> {
-    const cacheConfig = this.cache ? this.cache.config : undefined;
-    return new Repository(this.client, model, cacheConfig, this.logger);
-  }
-
-  /**
-   * 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);
-   *     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> {
-    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();
-    }
-  }
-}
-
-export {
-  Repository,
-  DBClient,
-  QueryBuilder,
-  Cache,
-  StabilizeLogger,
-  DBType,
-  DataTypes,
-  LogLevel,
-  RelationType,
-  MetadataStorage,
-  mapDataTypeToSql,
-  StabilizeError,
-  runMigrations,
-  generateMigration,
-  defineModel,
-  
-};
-
-export type {
-  Migration,
-  DBConfig,
-  CacheConfig,
-  LoggerConfig,
-  QueryHint,
-  PoolMetrics,
-  CacheStats,
-  Logger,
-  Hook
-};