stabilize-orm 1.1.3 → 1.1.4

package/migrations.ts

@@ -1,3 +1,9 @@
+/**
+ * @file migrations.ts
+ * @description Contains functions for generating and running database migrations based on model metadata.
+ * @author ElectronSz
+ */
+
 import { DBClient } from "./client";
 import { ModelKey, ColumnKey, ValidatorKey, SoftDeleteKey } from "./decorators";
 import { type DBConfig, type Migration, StabilizeError, DBType } from "./types";
@@ -6,138 +12,224 @@ type ColumnData = { name: string; type: string };
 type ColumnMetadata = Record<string, ColumnData>;
 type ValidatorMetadata = Record<string, string[]>;
 
-// Helper to get SQL type for auto-increment PK
-function getAutoIncrementPK(dbType: DBType) {
+/**
+ * @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";
-    default: // Default to Postgres
-      return "SERIAL PRIMARY KEY";
   }
 }
 
-// Helper to get SQL type for timestamps
-function getTimestampType(dbType: DBType) {
+/**
+ * @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:
-      return "TEXT";
-    default: // Default to Postgres
-      return "TIMESTAMP";
+    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.
+ * @example
+ * ```
+ * // In a script like 'scripts/generate_user_migration.ts'
+ * import { generateMigration, DBType } from 'stabilize-orm';
+ * import { User } from './models/user';
+ * import fs from 'fs';
+ *
+ * async function createMigration() {
+ *   const migration = await generateMigration(User, 'create_users_table', DBType.Postgres);
+ *   fs.writeFileSync(
+ *     `migrations/${new Date().getTime()}_create_users.json`,
+ *     JSON.stringify(migration, null, 2)
+ *   );
+ * }
+ *
+ * createMigration();
+ * ```
+ */
 export async function generateMigration(
   model: new (...args: any[]) => any,
-  name: string,
-  dbType: DBType = DBType.Postgres, // default to Postgres
+  name: string, 
+  dbType: DBType = DBType.Postgres,
 ): Promise<Migration> {
   const tableName = Reflect.getMetadata(ModelKey, model);
-  if (!tableName)
-    throw new StabilizeError(
-      "Model not decorated with @Model",
-      "MIGRATION_ERROR",
-    );
-
-  const columns: ColumnMetadata =
-    Reflect.getMetadata(ColumnKey, model.prototype) || {};
-  const validators: ValidatorMetadata =
-    Reflect.getMetadata(ValidatorKey, model.prototype) || {};
+  if (!tableName) {
+    throw new StabilizeError("Model not decorated with @Model", "MIGRATION_ERROR");
+  }
+
+  const columns: ColumnMetadata = Reflect.getMetadata(ColumnKey, model.prototype) || {};
+  const validators: ValidatorMetadata = Reflect.getMetadata(ValidatorKey, model.prototype) || {};
   const softDeleteField = Reflect.getMetadata(SoftDeleteKey, model.prototype);
 
   const columnDefs = Object.entries(columns).map(([key, col]) => {
-    let def: string;
     if (col.name === "id") {
-      // Use correct PK syntax for each DB
-      def = getAutoIncrementPK(dbType);
-      return def;
+      return `id ${getAutoIncrementPK(dbType)}`;
     }
-    def = `${col.name} ${col.type}`;
-    if (validators[key]?.includes("required")) def += " NOT NULL";
-    if (validators[key]?.includes("unique")) def += " UNIQUE";
-    // Handle timestamps
-    if (["createdAt", "updatedAt"].includes(col.name)) {
-      def = `${col.name} ${getTimestampType(dbType)}`;
+
+    const defParts: string[] = [col.name];
+    
+    if (["createdAt", "updatedAt"].includes(key) || (softDeleteField && key === softDeleteField)) {
+      defParts.push(getTimestampType(dbType));
+    } else {
+      defParts.push(col.type);
+    }
+
+    if (validators[key]?.includes("required")) {
+      defParts.push("NOT NULL");
+    }
+    if (validators[key]?.includes("unique")) {
+      defParts.push("UNIQUE");
+    }
+
+    if (key === "createdAt") {
+      defParts.push(getTimestampDefault(dbType));
     }
-    return def;
+
+    return defParts.join(" ");
   });
 
-  if (softDeleteField && columns[softDeleteField]) {
-    columnDefs.push(
-      `${columns[softDeleteField].name} ${columns[softDeleteField].type}`,
-    );
+  if (softDeleteField && !columns[softDeleteField]) {
+    columnDefs.push(`${softDeleteField} ${getTimestampType(dbType)}`);
   }
 
-  const up = [
-    `CREATE TABLE IF NOT EXISTS ${tableName} (${columnDefs.join(", ")})`,
-  ];
+  const up = [`CREATE TABLE IF NOT EXISTS ${tableName} (${columnDefs.join(", ")})`];
   const down = [`DROP TABLE IF EXISTS ${tableName}`];
 
-  return { up, down };
+  return { up, down, name: tableName }; 
 }
 
-// Create migrations table with correct types for each DB
-function getMigrationsTableSQL(dbType: DBType) {
+/**
+ * @internal
+ * Gets the database-specific SQL for creating the `migrations` table, which tracks applied migrations.
+ * @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 migrations (
         id SERIAL PRIMARY KEY,
-        name TEXT NOT NULL,
-        applied_at TIMESTAMP NOT NULL
+        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 (
         id INT AUTO_INCREMENT PRIMARY KEY,
-        name VARCHAR(255) NOT NULL,
-        applied_at DATETIME NOT NULL
+        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 (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
-        name TEXT NOT NULL,
-        applied_at TEXT NOT NULL
-      )`;
-    default: // Default to Postgres
-      return `CREATE TABLE IF NOT EXISTS migrations (
-        id SERIAL PRIMARY KEY,
-        name TEXT NOT NULL,
-        applied_at TIMESTAMP NOT NULL
+        name TEXT UNIQUE NOT NULL,
+        applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
       )`;
   }
 }
 
+/**
+ * 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.
+ * @example
+ * ```
+ * // In a script like 'scripts/run_all_migrations.ts'
+ * import { runMigrations } from 'stabilize-orm';
+ * import { dbConfig } from './config';
+ * import migration1 from '../migrations/1_create_users.json';
+ * import migration2 from '../migrations.ts/2_create_profiles.json';
+ *
+ * const allMigrations = [migration1, migration2];
+ *
+ * async function applyMigrations() {
+ *   console.log('Starting migration process...');
+ *   await runMigrations(dbConfig, allMigrations);
+ *   console.log('All pending migrations applied successfully.');
+ * }
+ *
+ * applyMigrations();
+ * ```
+ */
 export async function runMigrations(config: DBConfig, migrations: Migration[]) {
   const client = new DBClient(config);
   try {
-    // Detect DB type from config
-    const dbType = config.type ?? DBType.Postgres;
-
+    const dbType = config.type;
     await client.query(getMigrationsTableSQL(dbType));
 
     for (const [index, migration] of migrations.entries()) {
-      const name = `migration_${index}_${new Date().toISOString().replace(/[-:T.]/g, "")}`;
+      const name = migration.name || `migration_${index}_${new Date().getTime()}`;
+      
       const applied = await client.query<{ id: number }>(
         `SELECT id FROM migrations WHERE name = ?`,
         [name],
       );
 
       if (applied.length === 0) {
-        for (const query of migration.up) {
-          await client.query(query, []);
-        }
-        await client.query(
-          `INSERT INTO migrations (name, applied_at) VALUES (?, ?)`,
-          [name, new Date().toISOString()],
-        );
+        await client.transaction(async (txClient) => {
+          console.log(`Applying migration: ${name}...`);
+          for (const query of migration.up) {
+            await txClient.query(query);
+          }
+          await txClient.query(
+            `INSERT INTO migrations (name, applied_at) VALUES (?, ?)`,
+            [name, new Date().toISOString()],
+          );
+          console.log(`Migration ${name} applied successfully.`);
+        });
       }
     }
+  } catch (error) {
+    console.error("Migration failed:", error);
+    throw error; 
   } finally {
     await client.close();
   }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "stabilize-orm",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "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",
   "bin": {
-    "stabilize": "./dist/cli/stabilize-cli.js"
+    "stabilize": "dist/cli/stabilize-cli.js"
   },
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target bun --minify && bun build cli/stabilize-cli.ts --outdir dist/cli --target bun --minify",
@@ -28,11 +28,14 @@
   "author": "ElectronSz <lwazicd@icloud.com>",
   "license": "MIT",
   "dependencies": {
+    "@types/pg": "^8.15.5",
     "@types/uuid": "^11.0.0",
     "commander": "^12.1.0",
     "figlet": "^1.9.3",
     "glob": "^11.0.0",
     "ioredis": "^5.4.1",
+    "mysql2": "^3.15.2",
+    "pg": "^8.16.3",
     "reflect-metadata": "^0.2.2",
     "uuid": "^13.0.0"
   },

package/query-builder.ts

@@ -1,7 +1,18 @@
+/**
+ * @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 { type QueryHint } 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[] = ["*"];
@@ -11,54 +22,110 @@ export class QueryBuilder<T> {
   private orderByClause: string | null = null;
   private limitValue: number | null = null;
   private offsetValue: number | null = null;
-  private hints: QueryHint[] = [];
 
+  /**
+   * 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;
   }
 
-  hint(hint: QueryHint): QueryBuilder<T> {
-    this.hints.push(hint);
-    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.hints.length > 0) {
-      const hintStr = this.hints.map((h) => `${h.type}(${h.value})`).join(" ");
-      query = `SELECT ${hintStr} ${this.selectFields.join(", ")} FROM ${this.table}`;
-    }
+    
     if (this.joins.length > 0) {
       query += " " + this.joins.join(" ");
     }
@@ -77,20 +144,43 @@ export class QueryBuilder<T> {
     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);
+      await cache.set(cacheKey, results, 60); 
     }
+    
     return results;
   }
-}
+}