@mantiq/database 0.0.1

package/src/drivers/MySQLConnection.ts

@@ -0,0 +1,120 @@
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+import { QueryBuilder } from '../query/Builder.ts'
+import { MySQLGrammar } from './MySQLGrammar.ts'
+import { SchemaBuilderImpl } from '../schema/SchemaBuilder.ts'
+import { ConnectionError } from '../errors/ConnectionError.ts'
+import { QueryError } from '../errors/QueryError.ts'
+
+export interface MySQLConfig {
+  host?: string
+  port?: number
+  database: string
+  user?: string
+  password?: string
+  pool?: { min?: number; max?: number }
+}
+
+export class MySQLConnection implements DatabaseConnection {
+  readonly _grammar = new MySQLGrammar()
+  private pool: any = null
+  private config: MySQLConfig
+
+  constructor(config: MySQLConfig) {
+    this.config = config
+  }
+
+  private async getPool(): Promise<any> {
+    if (!this.pool) {
+      try {
+        const mysql = await import('mysql2/promise')
+        this.pool = await mysql.createPool({
+          host: this.config.host ?? 'localhost',
+          port: this.config.port ?? 3306,
+          database: this.config.database,
+          user: this.config.user,
+          password: this.config.password,
+          connectionLimit: this.config.pool?.max ?? 10,
+          waitForConnections: true,
+        })
+      } catch (e: any) {
+        throw new ConnectionError(`MySQL connection failed: ${e.message}`, 'mysql', e)
+      }
+    }
+    return this.pool
+  }
+
+  async select(sql: string, bindings: any[] = []): Promise<Record<string, any>[]> {
+    const pool = await this.getPool()
+    try {
+      const [rows] = await pool.query(sql, bindings)
+      return rows as Record<string, any>[]
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async statement(sql: string, bindings: any[] = []): Promise<number> {
+    const pool = await this.getPool()
+    try {
+      const [result] = await pool.query(sql, bindings)
+      return (result as any).affectedRows ?? 0
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async insertGetId(sql: string, bindings: any[] = []): Promise<number | bigint> {
+    const pool = await this.getPool()
+    try {
+      const [result] = await pool.query(sql, bindings)
+      return (result as any).insertId ?? 0
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async transaction<T>(callback: (connection: DatabaseConnection) => Promise<T>): Promise<T> {
+    const pool = await this.getPool()
+    const conn = await pool.getConnection()
+    try {
+      await conn.beginTransaction()
+      const txConn: DatabaseConnection = {
+        select: async (sql, b) => { const [rows] = await conn.query(sql, b); return rows as Record<string, any>[] },
+        statement: async (sql, b) => { const [r] = await conn.query(sql, b); return (r as any).affectedRows ?? 0 },
+        insertGetId: async (sql, b) => { const [r] = await conn.query(sql, b); return (r as any).insertId ?? 0 },
+        transaction: (cb) => cb(txConn),
+        table: (name) => new QueryBuilder(txConn, name),
+        schema: () => new SchemaBuilderImpl(txConn),
+        getDriverName: () => 'mysql',
+        getTablePrefix: () => '',
+      }
+      // @ts-ignore — attach grammar
+      txConn._grammar = this._grammar
+      const result = await callback(txConn)
+      await conn.commit()
+      return result
+    } catch (e) {
+      await conn.rollback()
+      throw e
+    } finally {
+      conn.release()
+    }
+  }
+
+  table(name: string): QueryBuilder {
+    return new QueryBuilder(this, name)
+  }
+
+  schema(): SchemaBuilder {
+    return new SchemaBuilderImpl(this)
+  }
+
+  getDriverName(): string {
+    return 'mysql'
+  }
+
+  getTablePrefix(): string {
+    return ''
+  }
+}

package/src/drivers/MySQLGrammar.ts

@@ -0,0 +1,19 @@
+import { BaseGrammar } from './BaseGrammar.ts'
+import type { QueryState } from '../query/Builder.ts'
+
+export class MySQLGrammar extends BaseGrammar {
+  quoteIdentifier(name: string): string {
+    if (name.includes('.')) {
+      return name.split('.').map((p) => `\`${p}\``).join('.')
+    }
+    return `\`${name}\``
+  }
+
+  placeholder(_index: number): string {
+    return '?'
+  }
+
+  override compileTruncate(table: string): string {
+    return `TRUNCATE TABLE ${this.quoteIdentifier(table)}`
+  }
+}

package/src/drivers/PostgresConnection.ts

@@ -0,0 +1,125 @@
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+import { QueryBuilder } from '../query/Builder.ts'
+import { PostgresGrammar } from './PostgresGrammar.ts'
+import { SchemaBuilderImpl } from '../schema/SchemaBuilder.ts'
+import { ConnectionError } from '../errors/ConnectionError.ts'
+import { QueryError } from '../errors/QueryError.ts'
+
+export interface PostgresConfig {
+  host?: string
+  port?: number
+  database: string
+  user?: string
+  password?: string
+  ssl?: boolean
+  pool?: { min?: number; max?: number }
+}
+
+export class PostgresConnection implements DatabaseConnection {
+  readonly _grammar = new PostgresGrammar()
+  private client: any = null
+  private config: PostgresConfig
+
+  constructor(config: PostgresConfig) {
+    this.config = config
+  }
+
+  private async getClient(): Promise<any> {
+    if (!this.client) {
+      try {
+        // Uses pg (node-postgres) compatible driver
+        const { default: pg } = await import('pg')
+        const pool = new pg.Pool({
+          host: this.config.host ?? 'localhost',
+          port: this.config.port ?? 5432,
+          database: this.config.database,
+          user: this.config.user,
+          password: this.config.password,
+          ssl: this.config.ssl ? { rejectUnauthorized: false } : false,
+          min: this.config.pool?.min ?? 2,
+          max: this.config.pool?.max ?? 10,
+        })
+        this.client = pool
+      } catch (e: any) {
+        throw new ConnectionError(`Postgres connection failed: ${e.message}`, 'postgres', e)
+      }
+    }
+    return this.client
+  }
+
+  async select(sql: string, bindings: any[] = []): Promise<Record<string, any>[]> {
+    const pool = await this.getClient()
+    try {
+      const result = await pool.query(sql, bindings)
+      return result.rows
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async statement(sql: string, bindings: any[] = []): Promise<number> {
+    const pool = await this.getClient()
+    try {
+      const result = await pool.query(sql, bindings)
+      return result.rowCount ?? 0
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async insertGetId(sql: string, bindings: any[] = []): Promise<number | bigint> {
+    const pool = await this.getClient()
+    try {
+      const result = await pool.query(sql, bindings)
+      return result.rows[0]?.id ?? 0
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async transaction<T>(callback: (connection: DatabaseConnection) => Promise<T>): Promise<T> {
+    const pool = await this.getClient()
+    const client = await pool.connect()
+    try {
+      await client.query('BEGIN')
+      // Create a transactional connection wrapper
+      const txConn: DatabaseConnection = {
+        select: async (sql, b) => { const r = await client.query(sql, b); return r.rows },
+        statement: async (sql, b) => { const r = await client.query(sql, b); return r.rowCount ?? 0 },
+        insertGetId: async (sql, b) => { const r = await client.query(sql, b); return r.rows[0]?.id ?? 0 },
+        transaction: (cb) => cb(txConn),
+        table: (name) => new QueryBuilder(txConn, name),
+        schema: () => new SchemaBuilderImpl(txConn),
+        getDriverName: () => 'postgres',
+        getTablePrefix: () => '',
+      }
+      // @ts-ignore — attach grammar for the builder
+      txConn._grammar = this._grammar
+      const result = await callback(txConn)
+      await client.query('COMMIT')
+      return result
+    } catch (e) {
+      await client.query('ROLLBACK')
+      throw e
+    } finally {
+      client.release()
+    }
+  }
+
+  table(name: string): QueryBuilder {
+    return new QueryBuilder(this, name)
+  }
+
+  schema(): SchemaBuilder {
+    return new SchemaBuilderImpl(this)
+  }
+
+  getDriverName(): string {
+    return 'postgres'
+  }
+
+  getTablePrefix(): string {
+    return ''
+  }
+}

package/src/drivers/PostgresGrammar.ts

@@ -0,0 +1,24 @@
+import { BaseGrammar } from './BaseGrammar.ts'
+import type { QueryState } from '../query/Builder.ts'
+
+export class PostgresGrammar extends BaseGrammar {
+  quoteIdentifier(name: string): string {
+    if (name.includes('.')) {
+      return name.split('.').map((p) => `"${p}"`).join('.')
+    }
+    return `"${name}"`
+  }
+
+  placeholder(index: number): string {
+    return `$${index}`
+  }
+
+  override compileInsertGetId(table: string, data: Record<string, any>): { sql: string; bindings: any[] } {
+    const { sql, bindings } = this.compileInsert(table, data)
+    return { sql: `${sql} RETURNING id`, bindings }
+  }
+
+  override compileTruncate(table: string): string {
+    return `TRUNCATE TABLE ${this.quoteIdentifier(table)} RESTART IDENTITY CASCADE`
+  }
+}

package/src/drivers/SQLiteConnection.ts

@@ -0,0 +1,125 @@
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+import type { EventDispatcher } from '@mantiq/core'
+import { QueryBuilder } from '../query/Builder.ts'
+import { SQLiteGrammar } from './SQLiteGrammar.ts'
+import { SchemaBuilderImpl } from '../schema/SchemaBuilder.ts'
+import { ConnectionError } from '../errors/ConnectionError.ts'
+import { QueryError } from '../errors/QueryError.ts'
+import { QueryExecuted, TransactionBeginning, TransactionCommitted, TransactionRolledBack } from '../events/DatabaseEvents.ts'
+
+export interface SQLiteConfig {
+  database: string  // ':memory:' or file path
+}
+
+export class SQLiteConnection implements DatabaseConnection {
+  readonly _grammar = new SQLiteGrammar()
+  private db: import('bun:sqlite').Database | null = null
+  private config: SQLiteConfig
+
+  /** Optional event dispatcher. Set by @mantiq/events when installed. */
+  static _dispatcher: EventDispatcher | null = null
+
+  constructor(config: SQLiteConfig) {
+    this.config = config
+  }
+
+  private getDb(): import('bun:sqlite').Database {
+    if (!this.db) {
+      try {
+        const { Database } = require('bun:sqlite') as typeof import('bun:sqlite')
+        this.db = new Database(this.config.database, { create: true })
+        this.db.run('PRAGMA journal_mode = WAL')
+        this.db.run('PRAGMA foreign_keys = ON')
+      } catch (e: any) {
+        throw new ConnectionError(`SQLite connection failed: ${e.message}`, 'sqlite', e)
+      }
+    }
+    return this.db
+  }
+
+  /** bun:sqlite only accepts string | number | bigint | boolean | Uint8Array | null */
+  private sanitizeBindings(bindings: any[]): any[] {
+    return bindings.map((v) => {
+      if (v instanceof Date) return v.toISOString()
+      return v
+    })
+  }
+
+  async select(sql: string, bindings: any[] = []): Promise<Record<string, any>[]> {
+    try {
+      const start = performance.now()
+      const stmt = this.getDb().prepare(sql)
+      const result = stmt.all(...this.sanitizeBindings(bindings)) as Record<string, any>[]
+      await this.fireQueryEvent(sql, bindings, performance.now() - start)
+      return result
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async statement(sql: string, bindings: any[] = []): Promise<number> {
+    try {
+      const start = performance.now()
+      const stmt = this.getDb().prepare(sql)
+      const result = stmt.run(...this.sanitizeBindings(bindings))
+      await this.fireQueryEvent(sql, bindings, performance.now() - start)
+      return result.changes
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async insertGetId(sql: string, bindings: any[] = []): Promise<number | bigint> {
+    try {
+      const start = performance.now()
+      const stmt = this.getDb().prepare(sql)
+      const result = stmt.run(...this.sanitizeBindings(bindings))
+      await this.fireQueryEvent(sql, bindings, performance.now() - start)
+      return result.lastInsertRowid
+    } catch (e: any) {
+      throw new QueryError(sql, bindings, e)
+    }
+  }
+
+  async transaction<T>(callback: (connection: DatabaseConnection) => Promise<T>): Promise<T> {
+    const db = this.getDb()
+    db.run('BEGIN')
+    await SQLiteConnection._dispatcher?.emit(new TransactionBeginning('sqlite'))
+    try {
+      const result = await callback(this)
+      db.run('COMMIT')
+      await SQLiteConnection._dispatcher?.emit(new TransactionCommitted('sqlite'))
+      return result
+    } catch (e) {
+      db.run('ROLLBACK')
+      await SQLiteConnection._dispatcher?.emit(new TransactionRolledBack('sqlite'))
+      throw e
+    }
+  }
+
+  private async fireQueryEvent(sql: string, bindings: any[], time: number): Promise<void> {
+    await SQLiteConnection._dispatcher?.emit(new QueryExecuted(sql, bindings, time, 'sqlite'))
+  }
+
+  table(name: string): QueryBuilder {
+    return new QueryBuilder(this, name)
+  }
+
+  schema(): SchemaBuilder {
+    return new SchemaBuilderImpl(this)
+  }
+
+  getDriverName(): string {
+    return 'sqlite'
+  }
+
+  getTablePrefix(): string {
+    return ''
+  }
+
+  close(): void {
+    this.db?.close()
+    this.db = null
+  }
+}

package/src/drivers/SQLiteGrammar.ts

@@ -0,0 +1,19 @@
+import { BaseGrammar } from './BaseGrammar.ts'
+
+export class SQLiteGrammar extends BaseGrammar {
+  quoteIdentifier(name: string): string {
+    // Handle table.column notation
+    if (name.includes('.')) {
+      return name.split('.').map((p) => `"${p}"`).join('.')
+    }
+    return `"${name}"`
+  }
+
+  placeholder(_index: number): string {
+    return '?'
+  }
+
+  override compileTruncate(table: string): string {
+    return `DELETE FROM ${this.quoteIdentifier(table)}`
+  }
+}

package/src/errors/ConnectionError.ts

@@ -0,0 +1,10 @@
+import { MantiqError } from '@mantiq/core'
+
+export class ConnectionError extends MantiqError {
+  constructor(
+    public readonly driver: string,
+    originalError: Error,
+  ) {
+    super(`Failed to connect to ${driver} database: ${originalError.message}`)
+  }
+}

package/src/errors/ModelNotFoundError.ts

@@ -0,0 +1,14 @@
+import { MantiqError } from '@mantiq/core'
+
+export class ModelNotFoundError extends MantiqError {
+  constructor(
+    public readonly modelName: string,
+    public readonly id?: any,
+  ) {
+    super(
+      id !== undefined
+        ? `No ${modelName} found with ID ${id}.`
+        : `No ${modelName} matching the given conditions.`,
+    )
+  }
+}

package/src/errors/QueryError.ts

@@ -0,0 +1,11 @@
+import { MantiqError } from '@mantiq/core'
+
+export class QueryError extends MantiqError {
+  constructor(
+    public readonly sql: string,
+    public readonly bindings: any[],
+    public readonly originalError: Error,
+  ) {
+    super(`Database query failed: ${originalError.message}`, { sql, bindings })
+  }
+}

package/src/events/DatabaseEvents.ts

@@ -0,0 +1,101 @@
+import { Event } from '@mantiq/core'
+
+/**
+ * Fired after a database query is executed.
+ * Useful for query logging, debugging, and performance monitoring.
+ */
+export class QueryExecuted extends Event {
+  constructor(
+    /** The SQL query string. */
+    public readonly sql: string,
+    /** The query bindings. */
+    public readonly bindings: any[],
+    /** Time in milliseconds the query took to execute. */
+    public readonly time: number,
+    /** The connection name (e.g. 'sqlite'). */
+    public readonly connectionName: string,
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired when a database transaction begins.
+ */
+export class TransactionBeginning extends Event {
+  constructor(public readonly connectionName: string) {
+    super()
+  }
+}
+
+/**
+ * Fired when a database transaction is committed.
+ */
+export class TransactionCommitted extends Event {
+  constructor(public readonly connectionName: string) {
+    super()
+  }
+}
+
+/**
+ * Fired when a database transaction is rolled back.
+ */
+export class TransactionRolledBack extends Event {
+  constructor(public readonly connectionName: string) {
+    super()
+  }
+}
+
+// ── Migration Events ─────────────────────────────────────────────────────────
+
+/**
+ * Fired before a single migration is executed (up or down).
+ */
+export class MigrationStarted extends Event {
+  constructor(
+    /** The migration name (e.g. '2024_01_01_create_users_table'). */
+    public readonly migration: string,
+    /** 'up' for running, 'down' for rolling back. */
+    public readonly method: 'up' | 'down',
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired after a single migration has been executed (up or down).
+ */
+export class MigrationEnded extends Event {
+  constructor(
+    /** The migration name. */
+    public readonly migration: string,
+    /** 'up' for running, 'down' for rolling back. */
+    public readonly method: 'up' | 'down',
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired before a batch of migrations starts (run/rollback/reset).
+ */
+export class MigrationsStarted extends Event {
+  constructor(
+    /** 'up' for running, 'down' for rolling back. */
+    public readonly method: 'up' | 'down',
+  ) {
+    super()
+  }
+}
+
+/**
+ * Fired after a batch of migrations finishes (run/rollback/reset).
+ */
+export class MigrationsEnded extends Event {
+  constructor(
+    /** 'up' for running, 'down' for rolling back. */
+    public readonly method: 'up' | 'down',
+  ) {
+    super()
+  }
+}