stabilize-orm 1.0.5

package/examples/models/Role.ts

@@ -0,0 +1,11 @@
+import { Model, Column, Required } from "../../src";
+
+@Model("roles")
+export class Role {
+  @Column("id", "INTEGER")
+  id?: number;
+
+  @Column("name", "TEXT")
+  @Required()
+  name?: string;
+}

package/examples/models/User.ts

@@ -0,0 +1,22 @@
+import { Model, Column, Required, SoftDelete } from "../../src";
+
+@Model("users")
+export class User {
+  @Column("id", "INTEGER")
+  id?: number;
+
+  @Column("name", "TEXT")
+  @Required()
+  name?: string;
+
+  @Column("email", "TEXT")
+  @Required()
+  email?: string;
+
+  @Column("active", "BOOLEAN")
+  active?: boolean;
+
+  @Column("deletedAt", "TEXT")
+  @SoftDelete()
+  deletedAt?: string;
+}

package/examples/seeds/20251013_additional_seed.ts

@@ -0,0 +1,29 @@
+import { Stabilize } from "../../src";
+import { Role } from "../models/Role";
+
+export const dependencies = ["20251013_initial_seed"];
+
+export async function seed(orm: Stabilize) {
+  const repo = orm.getRepository(Role);
+  await repo.bulkCreate([{ name: "Admin" }, { name: "User" }], {
+    batchSize: 100,
+  });
+
+  await orm["client"].query(
+    `INSERT INTO seed_history (name, applied_at) VALUES (?, ?)`,
+    ["20251013_additional_seed", new Date().toISOString()],
+  );
+}
+
+export async function rollback(orm: Stabilize) {
+  const repo = orm.getRepository(Role);
+  const entities = await repo.find().execute(orm["client"]);
+  await repo.bulkDelete(
+    entities.map((e) => e.id!),
+    { batchSize: 100 },
+  );
+
+  await orm["client"].query(`DELETE FROM seed_history WHERE name = ?`, [
+    "20251013_additional_seed",
+  ]);
+}

package/examples/seeds/20251013_initial_seed.ts

@@ -0,0 +1,33 @@
+import { Stabilize } from "../../src";
+import { User } from "../models/User";
+
+export const dependencies = [];
+
+export async function seed(orm: Stabilize) {
+  const repo = orm.getRepository(User);
+  await repo.bulkCreate(
+    [
+      { name: "Alice", email: "alice@example.com", active: true },
+      { name: "Bob", email: "bob@example.com", active: true },
+    ],
+    { batchSize: 100 },
+  );
+
+  await orm["client"].query(
+    `INSERT INTO seed_history (name, applied_at) VALUES (?, ?)`,
+    ["20251013_initial_seed", new Date().toISOString()],
+  );
+}
+
+export async function rollback(orm: Stabilize) {
+  const repo = orm.getRepository(User);
+  const entities = await repo.find().execute(orm["client"]);
+  await repo.bulkDelete(
+    entities.map((e) => e.id!),
+    { batchSize: 100 },
+  );
+
+  await orm["client"].query(`DELETE FROM seed_history WHERE name = ?`, [
+    "20251013_initial_seed",
+  ]);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "stabilize-orm",
+  "version": "1.0.5",
+  "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"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun --minify && bun build cli/stabilize-cli.ts --outdir dist/cli --target bun --minify",
+    
+    "prepublishOnly": "bun run build && bun run test",
+    "format": "bunx prettier --write .",
+    "lint": "eslint src tests cli examples",
+    "cli": "bun run cli/stabilize-cli.ts"
+  },
+  "keywords": [
+    "orm",
+    "bun",
+    "sqlite",
+    "mysql",
+    "postgresql",
+    "redis",
+    "typescript",
+    "database"
+  ],
+  "author": "th3b0tk1ill3r <lwazicd@icloud.com>",
+  "license": "MIT",
+  "dependencies": {
+    "ioredis": "^5.4.1",
+    "reflect-metadata": "^0.2.2",
+    "commander": "^12.1.0",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.3",
+    "@vitest/coverage-v8": "^2.1.3",
+    "typescript": "^5.6.3",
+    "prettier": "^3.3.3",
+    "eslint": "^9.12.0",
+    "@typescript-eslint/parser": "^8.7.0",
+    "@typescript-eslint/eslint-plugin": "^8.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ElectronSz/stabilize-orm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ElectronSz/stabilize-orm/issues"
+  },
+  "homepage": "https://github.com/ElectronSz/stabilize-orm#readme",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ElectronSz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/cache.ts

@@ -0,0 +1,110 @@
+import Redis from "ioredis";
+import { type CacheConfig, type CacheStats } from "./types";
+import { ConsoleLogger, type Logger } from "./logger";
+
+export class Cache {
+  private redis: Redis | null = null;
+  private ttl: number;
+  private prefix: string;
+  private strategy: "cache-aside" | "write-through";
+  private logger: Logger;
+  private hits: number = 0;
+  private misses: number = 0;
+
+  constructor(config: CacheConfig, logger: Logger = new ConsoleLogger()) {
+    this.ttl = config.ttl;
+    this.prefix = config.cachePrefix || "cache:";
+    this.strategy = config.strategy || "cache-aside";
+    this.logger = logger;
+
+    if (config.enabled && config.redisUrl) {
+      this.redis = new Redis(config.redisUrl, { lazyConnect: true });
+      this.redis.on("error", (error) => this.logger.logError(error));
+    }
+  }
+
+  getStrategy() {
+    return this.strategy;
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    if (!this.redis) return null;
+
+    try {
+      const data = await this.redis.get(this.prefix + 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;
+    }
+  }
+
+  async set<T>(key: string, value: T, ttl: number = this.ttl): Promise<void> {
+    if (!this.redis) return;
+
+    try {
+      await this.redis.set(this.prefix + key, JSON.stringify(value), "EX", ttl);
+      this.logger.logDebug(`Cache set for key: ${key}`);
+    } catch (error) {
+      this.logger.logError(error as Error);
+    }
+  }
+
+  async invalidate(keys: string[]): Promise<void> {
+    if (!this.redis) return;
+
+    try {
+      const pipeline = this.redis.pipeline();
+      for (const key of keys) {
+        pipeline.del(this.prefix + key);
+        this.logger.logDebug(`Cache invalidated for key: ${key}`);
+      }
+      await pipeline.exec();
+    } catch (error) {
+      this.logger.logError(error as Error);
+    }
+  }
+
+  async invalidatePattern(pattern: string): Promise<void> {
+    if (!this.redis) return;
+
+    try {
+      const keys = await this.redis.keys(this.prefix + pattern);
+      if (keys.length > 0) {
+        const pipeline = this.redis.pipeline();
+        for (const key of keys) {
+          pipeline.del(key);
+          this.logger.logDebug(`Cache invalidated for pattern: ${pattern}`);
+        }
+        await pipeline.exec();
+      }
+    } catch (error) {
+      this.logger.logError(error as Error);
+    }
+  }
+
+  async getStats(): Promise<CacheStats> {
+    if (!this.redis) return { hits: 0, misses: 0, keys: 0 };
+    try {
+      const keys = await this.redis.keys(this.prefix + "*");
+      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 };
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.redis) {
+      await this.redis.quit();
+      this.logger.logInfo("Redis connection closed");
+    }
+  }
+}

package/src/client.ts

@@ -0,0 +1,258 @@
+import { sql, SQL } from "bun";
+import { Database, Statement } from "bun:sqlite";
+import {
+  type DBConfig,
+  StabilizeError,
+  type PoolMetrics,
+  DBType, // Added DBType for type checking
+  type LoggerConfig, // Kept, but not used in logic
+} from "./types";
+import { type Logger, ConsoleLogger } from "./logger";
+
+// Helper to determine if we are in Bun SQLite mode based on config
+function isSQLiteConfig(config: DBConfig): boolean {
+  return (
+    config.type === DBType.SQLite || config.connectionString.includes("sqlite")
+  );
+}
+
+export class DBClient {
+  // Renamed to 'client' for clarity; stores the actual connection (Bun.Database or external driver)
+  // We use 'any' for the SQL client instance since Bun's SQL client is complex (callable function with methods)
+  private client: Database | any | null = null;
+  private logger: Logger;
+  private retryAttempts: number;
+  private retryDelay: number;
+  private maxJitter: number;
+  // Map stores Bun SQLite Statement objects when in SQLite mode
+  private preparedStatements: Map<string, Statement> = new Map();
+  private config: DBConfig;
+
+  constructor(config: DBConfig, logger: Logger = new ConsoleLogger()) {
+    this.config = config;
+    this.logger = logger;
+    this.retryAttempts = config.retryAttempts || 3;
+    this.retryDelay = config.retryDelay || 1000;
+    this.maxJitter = config.maxJitter || 100;
+
+    this.initializeClient(config);
+  }
+
+  // Initializes the connection based on config
+  private initializeClient(config: DBConfig) {
+    if (isSQLiteConfig(config)) {
+      // Use Bun's native SQLite client, which is synchronous to construct
+      try {
+        // new Database(path, { create: true }) is the standard Bun method
+        this.client = new Database(config.connectionString, { create: true });
+        this.logger.logDebug(
+          `Initialized Bun SQLite client for: ${config.connectionString}`,
+        );
+      } catch (e) {
+        this.logger.logError(e as Error);
+        throw new StabilizeError(
+          `Failed to initialize SQLite database: ${(e as Error).message}`,
+          "INIT_ERROR",
+        );
+      }
+    } else {
+      // For other DB types (Postgres/MySQL), initialize a Bun SQL client instance.
+      // This is necessary because the bare `sql` tag is for the default connection,
+      // and we need an instance with specific connection settings, using `SQL` as the constructor.
+      this.client = new SQL(config.connectionString);
+      this.logger.logDebug(
+        `Initialized Bun SQL client for: ${config.connectionString}`,
+      );
+    }
+  }
+
+  private getJitter() {
+    return Math.random() * this.maxJitter;
+  }
+
+  // Pool metrics are largely irrelevant for single-connection Bun SQLite
+  getPoolMetrics(): PoolMetrics {
+    return {
+      activeConnections: 0,
+      idleConnections: 0,
+      totalConnections: this.client instanceof Database ? 1 : 0,
+    };
+  }
+
+  async switchConnection(config: DBConfig) {
+    await this.close();
+    this.config = config;
+    this.preparedStatements.clear();
+    this.retryAttempts = config.retryAttempts || 3;
+    this.retryDelay = config.retryDelay || 1000;
+    this.maxJitter = config.maxJitter || 100;
+    this.initializeClient(config);
+  }
+
+  async query<T>(query: string, params: any[] = []): Promise<T[]> {
+    const start = Date.now();
+    this.logger.logQuery(query, params);
+    this.logger.logMetrics(this.getPoolMetrics());
+
+    let stmt: Statement | undefined;
+
+    // Check for Bun SQLite client
+    if (this.client instanceof Database) {
+      const stmtKey = query;
+      // Use prepared statement caching for SQLite
+      if (!this.preparedStatements.has(stmtKey)) {
+        // Use this.client (the Database instance) to prepare the statement
+        this.preparedStatements.set(stmtKey, this.client.prepare(query));
+      }
+      stmt = this.preparedStatements.get(stmtKey);
+    }
+
+    for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
+      try {
+        let result: T[];
+
+        if (stmt) {
+          // Bun SQLite Statement objects use .all() for fetching results
+          result = stmt.all(...params) as T[];
+        } else if (this.client) {
+          // Path for non-SQLite Bun SQL clients (Postgres/MySQL)
+          // Bun SQL clients do not expose a standard .query() method.
+          // We must use the 'unsafe' helper to execute a raw string query with positional parameters.
+          result = (await (this.client as any).unsafe(query, params)) as T[];
+        } else {
+          throw new StabilizeError(
+            "Database client is not initialized or does not support query execution.",
+            "INIT_ERROR",
+          );
+        }
+
+        const executionTime = Date.now() - start;
+        this.logger.logQuery(query, params, executionTime);
+        return result;
+      } 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",
+          );
+        }
+        // Exponential backoff with jitter
+        await new Promise((resolve) =>
+          setTimeout(
+            resolve,
+            this.retryDelay * Math.pow(2, attempt - 1) + this.getJitter(),
+          ),
+        );
+      }
+    }
+    throw new StabilizeError("Query failed: no attempts made", "QUERY_ERROR");
+  }
+
+  async transaction<T>(callback: () => Promise<T>): Promise<T> {
+    // Use native Bun SQLite transaction wrapper for safer, faster transactions
+    if (this.client instanceof Database) {
+      const start = Date.now();
+      this.logger.logDebug("Starting native SQLite transaction");
+
+      // Bun's .transaction() automatically handles BEGIN/COMMIT/ROLLBACK
+      const tx = this.client.transaction(async () => {
+        return callback();
+      });
+
+      try {
+        const result = await tx();
+        this.logger.logDebug(
+          `Native transaction committed in ${Date.now() - start}ms`,
+        );
+        return result;
+      } catch (error) {
+        this.logger.logError(error as Error);
+        // The transaction automatically rolls back on error
+        throw new StabilizeError(
+          `Native transaction failed: ${(error as Error).message}`,
+          "TX_ERROR",
+        );
+      }
+    }
+
+    // Fallback to manual transaction with retry logic for non-SQLite
+    const start = Date.now();
+    this.logger.logDebug("Starting manual transaction (non-SQLite)");
+    for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
+      try {
+        // Use this.query, which now correctly handles execution via .unsafe() for non-SQLite
+        await this.query("BEGIN", []);
+        const result = await callback();
+        await this.query("COMMIT", []);
+        this.logger.logDebug(
+          `Manual transaction committed in ${Date.now() - start}ms`,
+        );
+        return result;
+      } catch (error) {
+        // Attempt rollback, but ignore errors if rollback fails
+        await this.query("ROLLBACK", []).catch(() => {
+          this.logger.logDebug("Rollback failed. Connection may be invalid.");
+        });
+        this.logger.logError(error as Error);
+        if (attempt === this.retryAttempts) {
+          throw new StabilizeError(
+            `Manual transaction failed after ${this.retryAttempts} attempts: ${(error as Error).message}`,
+            "TX_ERROR",
+          );
+        }
+        // Exponential backoff with jitter
+        await new Promise((resolve) =>
+          setTimeout(
+            resolve,
+            this.retryDelay * Math.pow(2, attempt - 1) + this.getJitter(),
+          ),
+        );
+      }
+    }
+    throw new StabilizeError(
+      "Transaction failed: no attempts made",
+      "TX_ERROR",
+    );
+  }
+
+  async savepoint<T>(name: string, callback: () => Promise<T>): Promise<T> {
+    const start = Date.now();
+    this.logger.logDebug(`Starting savepoint ${name}`);
+    await this.query(`SAVEPOINT ${name}`, []);
+    try {
+      const result = await callback();
+      await this.query(`RELEASE SAVEPOINT ${name}`, []);
+      this.logger.logDebug(
+        `Savepoint ${name} released in ${Date.now() - start}ms`,
+      );
+      return result;
+    } catch (error) {
+      // Attempt rollback, but ignore errors if rollback fails
+      await this.query(`ROLLBACK TO SAVEPOINT ${name}`, []).catch(() => {
+        this.logger.logDebug(
+          `Rollback to savepoint ${name} failed. Connection may be invalid.`,
+        );
+      });
+      this.logger.logError(error as Error);
+      throw error;
+    }
+  }
+
+  async close() {
+    this.preparedStatements.clear();
+    // Check if the client is a Bun Database instance before closing (Bun SQLite close is sync)
+    if (this.client instanceof Database) {
+      this.client.close();
+      this.client = null;
+    } else if (
+      this.client &&
+      typeof (this.client as any).close === "function"
+    ) {
+      // Assume external/Bun SQL driver has an async close method
+      await (this.client as any).close();
+      this.client = null;
+    }
+    this.logger.logInfo("Database connection closed");
+  }
+}

package/src/decorators.ts

@@ -0,0 +1,99 @@
+import "reflect-metadata";
+import { RelationType } from "./types";
+
+export const ModelKey = Symbol("model");
+export const ColumnKey = Symbol("column");
+export const ValidatorKey = Symbol("validator");
+export const RelationKey = Symbol("relation");
+export const SoftDeleteKey = Symbol("softDelete");
+
+export function Model(tableName: string) {
+  return function (constructor: Function) {
+    Reflect.defineMetadata(ModelKey, tableName, constructor);
+  };
+}
+
+export function Column(name: string, type: string) {
+  return function (target: any, propertyKey: string) {
+    const columns = Reflect.getMetadata(ColumnKey, target) || {};
+    columns[propertyKey] = { name, type };
+    Reflect.defineMetadata(ColumnKey, columns, target);
+  };
+}
+
+export function Required() {
+  return function (target: any, propertyKey: string) {
+    const validators = Reflect.getMetadata(ValidatorKey, target) || {};
+    validators[propertyKey] = [...(validators[propertyKey] || []), "required"];
+    Reflect.defineMetadata(ValidatorKey, validators, target);
+  };
+}
+
+export function Unique() {
+  return function (target: any, propertyKey: string) {
+    const validators = Reflect.getMetadata(ValidatorKey, target) || {};
+    validators[propertyKey] = [...(validators[propertyKey] || []), "unique"];
+    Reflect.defineMetadata(ValidatorKey, validators, target);
+  };
+}
+
+export function SoftDelete() {
+  return function (target: any, propertyKey: string) {
+    Reflect.defineMetadata(SoftDeleteKey, propertyKey, target);
+  };
+}
+
+export function OneToOne(model: () => any, foreignKey: string) {
+  return function (target: any, propertyKey: string) {
+    const relations = Reflect.getMetadata(RelationKey, target) || {};
+    relations[propertyKey] = {
+      type: RelationType.OneToOne,
+      targetModel: model,
+      foreignKey,
+    };
+    Reflect.defineMetadata(RelationKey, relations, target);
+  };
+}
+
+export function ManyToOne(model: () => any, foreignKey: string) {
+  return function (target: any, propertyKey: string) {
+    const relations = Reflect.getMetadata(RelationKey, target) || {};
+    relations[propertyKey] = {
+      type: RelationType.ManyToOne,
+      targetModel: model,
+      foreignKey,
+    };
+    Reflect.defineMetadata(RelationKey, relations, target);
+  };
+}
+
+export function OneToMany(model: () => any, inverseKey: string) {
+  return function (target: any, propertyKey: string) {
+    const relations = Reflect.getMetadata(RelationKey, target) || {};
+    relations[propertyKey] = {
+      type: RelationType.OneToMany,
+      targetModel: model,
+      inverseKey,
+    };
+    Reflect.defineMetadata(RelationKey, relations, target);
+  };
+}
+
+export function ManyToMany(
+  model: () => any,
+  joinTable: string,
+  foreignKey: string,
+  inverseKey: string,
+) {
+  return function (target: any, propertyKey: string) {
+    const relations = Reflect.getMetadata(RelationKey, target) || {};
+    relations[propertyKey] = {
+      type: RelationType.ManyToMany,
+      targetModel: model,
+      joinTable,
+      foreignKey,
+      inverseKey,
+    };
+    Reflect.defineMetadata(RelationKey, relations, target);
+  };
+}