@mantiq/database 0.0.1

package/src/index.ts

@@ -0,0 +1,100 @@
+// ── Contracts ────────────────────────────────────────────────────────────────
+export type { DatabaseConnection } from './contracts/Connection.ts'
+export type { Grammar } from './contracts/Grammar.ts'
+export type { PaginationResult } from './contracts/Paginator.ts'
+export type {
+  MongoDatabaseConnection,
+  MongoCollectionContract,
+  MongoQueryBuilder,
+  MongoFilter,
+  MongoUpdateDoc,
+  MongoPipelineStage,
+  MongoSortDoc,
+  MongoProjection,
+  MongoInsertResult,
+  MongoInsertManyResult,
+  MongoUpdateResult,
+  MongoDeleteResult,
+} from './contracts/MongoConnection.ts'
+
+// ── Errors ────────────────────────────────────────────────────────────────────
+export { QueryError } from './errors/QueryError.ts'
+export { ModelNotFoundError } from './errors/ModelNotFoundError.ts'
+export { ConnectionError } from './errors/ConnectionError.ts'
+
+// ── Query Builder ─────────────────────────────────────────────────────────────
+export { QueryBuilder } from './query/Builder.ts'
+export { Expression, raw } from './query/Expression.ts'
+export type { QueryState, WhereClause, JoinClause, OrderClause, Operator } from './query/Builder.ts'
+
+// ── Grammar ───────────────────────────────────────────────────────────────────
+export { BaseGrammar } from './drivers/BaseGrammar.ts'
+export { SQLiteGrammar } from './drivers/SQLiteGrammar.ts'
+export { PostgresGrammar } from './drivers/PostgresGrammar.ts'
+export { MySQLGrammar } from './drivers/MySQLGrammar.ts'
+export { MSSQLGrammar } from './drivers/MSSQLGrammar.ts'
+
+// ── SQL Connections ───────────────────────────────────────────────────────────
+export { SQLiteConnection } from './drivers/SQLiteConnection.ts'
+export type { SQLiteConfig } from './drivers/SQLiteConnection.ts'
+export { PostgresConnection } from './drivers/PostgresConnection.ts'
+export type { PostgresConfig } from './drivers/PostgresConnection.ts'
+export { MySQLConnection } from './drivers/MySQLConnection.ts'
+export type { MySQLConfig } from './drivers/MySQLConnection.ts'
+export { MSSQLConnection } from './drivers/MSSQLConnection.ts'
+export type { MSSQLConfig } from './drivers/MSSQLConnection.ts'
+
+// ── MongoDB ───────────────────────────────────────────────────────────────────
+export { MongoConnection } from './drivers/MongoConnection.ts'
+export type { MongoConfig } from './drivers/MongoConnection.ts'
+
+// ── Schema Builder ────────────────────────────────────────────────────────────
+export type { SchemaBuilder } from './schema/SchemaBuilder.ts'
+export { SchemaBuilderImpl } from './schema/SchemaBuilder.ts'
+export { Blueprint } from './schema/Blueprint.ts'
+export { ColumnDefinition } from './schema/ColumnDefinition.ts'
+export type { IndexDefinition, ForeignKeyDefinition } from './schema/Blueprint.ts'
+
+// ── Migrations ────────────────────────────────────────────────────────────────
+export { Migration } from './migrations/Migration.ts'
+export type { MigrationContract } from './migrations/Migration.ts'
+export { Migrator } from './migrations/Migrator.ts'
+export type { MigrationFile } from './migrations/Migrator.ts'
+export { MigrationRepository } from './migrations/MigrationRepository.ts'
+
+// ── ORM ───────────────────────────────────────────────────────────────────────
+export { Model } from './orm/Model.ts'
+export type { Scope } from './orm/Scope.ts'
+export { ClosureScope } from './orm/Scope.ts'
+export {
+  HasOneRelation,
+  HasManyRelation,
+  BelongsToRelation,
+  BelongsToManyRelation,
+} from './orm/Model.ts'
+export type { ModelStatic } from './orm/Model.ts'
+export { ModelQueryBuilder } from './orm/ModelQueryBuilder.ts'
+export { Collection } from './orm/Collection.ts'
+
+// ── MongoDB Document ORM ──────────────────────────────────────────────────────
+export { Document } from './orm/Document.ts'
+
+// ── Seeders & Factories ───────────────────────────────────────────────────────
+export { Seeder } from './seeders/Seeder.ts'
+export { Factory } from './factories/Factory.ts'
+export { Faker } from './factories/Faker.ts'
+
+// ── Database Manager ──────────────────────────────────────────────────────────
+export { DatabaseManager } from './DatabaseManager.ts'
+export type { DatabaseConfig, ConnectionConfig, SQLConfig } from './DatabaseManager.ts'
+export type { MongoConfig as MongoConnectionConfig } from './DatabaseManager.ts'
+
+// ── Bootstrap helpers ─────────────────────────────────────────────────────────
+export { createDatabaseManager, setupModels } from './DatabaseServiceProvider.ts'
+
+// ── Events ───────────────────────────────────────────────────────────────────
+export { QueryExecuted, TransactionBeginning, TransactionCommitted, TransactionRolledBack } from './events/DatabaseEvents.ts'
+export { MigrationStarted, MigrationEnded, MigrationsStarted, MigrationsEnded } from './events/DatabaseEvents.ts'
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+export { db, table, schema, mongo, collection, setManager, getManager } from './helpers/db.ts'

package/src/migrations/Migration.ts

@@ -0,0 +1,12 @@
+import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+
+export interface MigrationContract {
+  up(schema: SchemaBuilder, db: DatabaseConnection): Promise<void>
+  down(schema: SchemaBuilder, db: DatabaseConnection): Promise<void>
+}
+
+export abstract class Migration implements MigrationContract {
+  abstract up(schema: SchemaBuilder, db: DatabaseConnection): Promise<void>
+  abstract down(schema: SchemaBuilder, db: DatabaseConnection): Promise<void>
+}

package/src/migrations/MigrationRepository.ts

@@ -0,0 +1,50 @@
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+
+export class MigrationRepository {
+  private readonly table = 'migrations'
+
+  constructor(private readonly connection: DatabaseConnection) {}
+
+  async createTable(): Promise<void> {
+    const exists = await this.connection.schema().hasTable(this.table)
+    if (!exists) {
+      await this.connection.schema().create(this.table, (t) => {
+        t.id()
+        t.string('migration', 255)
+        t.integer('batch')
+        t.timestamp('run_at').nullable()
+      })
+    }
+  }
+
+  async getRan(): Promise<string[]> {
+    const rows = await this.connection.table(this.table).pluck('migration')
+    return rows as string[]
+  }
+
+  async getLastBatch(): Promise<number> {
+    const result = await this.connection.table(this.table).max('batch')
+    return Number(result ?? 0)
+  }
+
+  async log(migration: string, batch: number): Promise<void> {
+    await this.connection.table(this.table).insert({
+      migration,
+      batch,
+      run_at: new Date(),
+    })
+  }
+
+  async delete(migration: string): Promise<void> {
+    await this.connection.table(this.table).where('migration', migration).delete()
+  }
+
+  async getLastBatchMigrations(): Promise<string[]> {
+    const batch = await this.getLastBatch()
+    if (batch === 0) return []
+    return this.connection.table(this.table)
+      .where('batch', batch)
+      .orderBy('id', 'desc')
+      .pluck('migration') as Promise<string[]>
+  }
+}

package/src/migrations/Migrator.ts

@@ -0,0 +1,201 @@
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+import type { MigrationContract } from './Migration.ts'
+import type { EventDispatcher } from '@mantiq/core'
+import { MigrationRepository } from './MigrationRepository.ts'
+import { MigrationStarted, MigrationEnded, MigrationsStarted, MigrationsEnded } from '../events/DatabaseEvents.ts'
+import { join } from 'node:path'
+
+export interface MigrationFile {
+  name: string
+  migration: MigrationContract
+}
+
+export interface MigratorOptions {
+  /** Directory containing migration files. Each file must default-export a Migration class. */
+  migrationsPath?: string
+}
+
+export class Migrator {
+  private repo: MigrationRepository
+
+  /** Optional event dispatcher. Set by @mantiq/events when installed. */
+  static _dispatcher: EventDispatcher | null = null
+
+  constructor(
+    private readonly connection: DatabaseConnection,
+    private readonly options: MigratorOptions = {},
+  ) {
+    this.repo = new MigrationRepository(connection)
+  }
+
+  async run(migrations?: MigrationFile[]): Promise<string[]> {
+    await this.repo.createTable()
+
+    const files = migrations ?? (await this.loadFromDirectory())
+    const ran = await this.repo.getRan()
+    const pending = files.filter((f) => !ran.includes(f.name))
+
+    if (!pending.length) return []
+
+    const batch = (await this.repo.getLastBatch()) + 1
+    const ran_: string[] = []
+
+    await Migrator._dispatcher?.emit(new MigrationsStarted('up'))
+
+    for (const file of pending) {
+      await Migrator._dispatcher?.emit(new MigrationStarted(file.name, 'up'))
+      const schema = this.connection.schema()
+      await file.migration.up(schema, this.connection)
+      await this.repo.log(file.name, batch)
+      ran_.push(file.name)
+      await Migrator._dispatcher?.emit(new MigrationEnded(file.name, 'up'))
+    }
+
+    await Migrator._dispatcher?.emit(new MigrationsEnded('up'))
+
+    return ran_
+  }
+
+  async rollback(migrations?: MigrationFile[]): Promise<string[]> {
+    await this.repo.createTable()
+
+    const lastBatch = await this.repo.getLastBatchMigrations()
+    if (!lastBatch.length) return []
+
+    // Build lookup map
+    const files = migrations ?? (await this.loadFromDirectory())
+    const lookup = new Map(files.map((f) => [f.name, f]))
+
+    const rolled: string[] = []
+
+    await Migrator._dispatcher?.emit(new MigrationsStarted('down'))
+
+    for (const name of lastBatch) {
+      const file = lookup.get(name)
+      if (!file) continue
+      await Migrator._dispatcher?.emit(new MigrationStarted(name, 'down'))
+      const schema = this.connection.schema()
+      await file.migration.down(schema, this.connection)
+      await this.repo.delete(name)
+      rolled.push(name)
+      await Migrator._dispatcher?.emit(new MigrationEnded(name, 'down'))
+    }
+
+    await Migrator._dispatcher?.emit(new MigrationsEnded('down'))
+
+    return rolled
+  }
+
+  async reset(migrations?: MigrationFile[]): Promise<string[]> {
+    await this.repo.createTable()
+
+    const ran = await this.repo.getRan()
+    const files = migrations ?? (await this.loadFromDirectory())
+    const lookup = new Map(files.map((f) => [f.name, f]))
+
+    // Run in reverse order
+    const reversed = [...ran].reverse()
+    const rolled: string[] = []
+
+    await Migrator._dispatcher?.emit(new MigrationsStarted('down'))
+
+    for (const name of reversed) {
+      const file = lookup.get(name)
+      if (!file) continue
+      await Migrator._dispatcher?.emit(new MigrationStarted(name, 'down'))
+      const schema = this.connection.schema()
+      await file.migration.down(schema, this.connection)
+      await this.repo.delete(name)
+      rolled.push(name)
+      await Migrator._dispatcher?.emit(new MigrationEnded(name, 'down'))
+    }
+
+    await Migrator._dispatcher?.emit(new MigrationsEnded('down'))
+
+    return rolled
+  }
+
+  /**
+   * Drop all tables and re-run all migrations from scratch.
+   */
+  async fresh(migrations?: MigrationFile[]): Promise<string[]> {
+    const schema = this.connection.schema()
+
+    // Disable FK constraints so tables can be dropped in any order
+    await schema.disableForeignKeyConstraints()
+
+    try {
+      const tables = await this.getAllTables()
+      for (const table of tables) {
+        await schema.dropIfExists(table)
+      }
+    } finally {
+      await schema.enableForeignKeyConstraints()
+    }
+
+    // Re-run all migrations
+    return this.run(migrations)
+  }
+
+  private async getAllTables(): Promise<string[]> {
+    const driver = this.connection.getDriverName()
+    let rows: Record<string, any>[]
+
+    if (driver === 'sqlite') {
+      rows = await this.connection.select(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'",
+      )
+      return rows.map((r) => r['name'] as string)
+    } else if (driver === 'postgres') {
+      rows = await this.connection.select(
+        "SELECT tablename FROM pg_tables WHERE schemaname = 'public'",
+      )
+      return rows.map((r) => r['tablename'] as string)
+    } else if (driver === 'mssql') {
+      rows = await this.connection.select(
+        "SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE='BASE TABLE'",
+      )
+      return rows.map((r) => r['TABLE_NAME'] as string)
+    } else {
+      // MySQL
+      rows = await this.connection.select('SHOW TABLES')
+      return rows.map((r) => Object.values(r)[0] as string)
+    }
+  }
+
+  async status(): Promise<Array<{ name: string; ran: boolean; batch: number | null }>> {
+    await this.repo.createTable()
+
+    const files = await this.loadFromDirectory()
+    const ran = await this.repo.getRan()
+    const rows = await this.connection.table('migrations').get()
+    const batchMap = new Map(rows.map((r) => [r['migration'] as string, r['batch'] as number]))
+
+    return files.map((f) => ({
+      name: f.name,
+      ran: ran.includes(f.name),
+      batch: batchMap.get(f.name) ?? null,
+    }))
+  }
+
+  private async loadFromDirectory(): Promise<MigrationFile[]> {
+    if (!this.options.migrationsPath) return []
+
+    const glob = new Bun.Glob('*.ts')
+    const files: MigrationFile[] = []
+
+    for await (const file of glob.scan(this.options.migrationsPath)) {
+      const name = file.replace(/\.ts$/, '')
+      const path = join(this.options.migrationsPath, file)
+      const mod = await import(path)
+      const MigrationClass = mod.default
+      if (MigrationClass) {
+        files.push({ name, migration: new MigrationClass() })
+      }
+    }
+
+    // Sort by filename (timestamp prefix ensures correct order)
+    files.sort((a, b) => a.name.localeCompare(b.name))
+    return files
+  }
+}

package/src/orm/Collection.ts

@@ -0,0 +1,236 @@
+import type { Model } from './Model.ts'
+import { applyMacros } from '@mantiq/core'
+
+/**
+ * Typed array wrapper for model query results.
+ * Provides convenience methods for working with sets of models.
+ */
+export class Collection<T extends Model> {
+  private items: T[]
+
+  constructor(items: T[] = []) {
+    this.items = [...items]
+  }
+
+  // ── Array-like access ────────────────────────────────────────────────────
+
+  get length(): number {
+    return this.items.length
+  }
+
+  [Symbol.iterator](): Iterator<T> {
+    return this.items[Symbol.iterator]()
+  }
+
+  toArray(): T[] {
+    return [...this.items]
+  }
+
+  all(): T[] {
+    return this.toArray()
+  }
+
+  // ── Element access ──────────────────────────────────────────────────────
+
+  first(): T | undefined {
+    return this.items[0]
+  }
+
+  last(): T | undefined {
+    return this.items[this.items.length - 1]
+  }
+
+  get(index: number): T | undefined {
+    return this.items[index]
+  }
+
+  // ── Searching ────────────────────────────────────────────────────────────
+
+  find(callback: (item: T) => boolean): T | undefined {
+    return this.items.find(callback)
+  }
+
+  findByKey(id: any): T | undefined {
+    return this.items.find((item) => item.getKey() === id)
+  }
+
+  contains(callback: ((item: T) => boolean) | any): boolean {
+    if (typeof callback === 'function') {
+      return this.items.some(callback as (item: T) => boolean)
+    }
+    return this.items.some((item) => item.getKey() === callback)
+  }
+
+  // ── Filtering ────────────────────────────────────────────────────────────
+
+  filter(callback: (item: T) => boolean): Collection<T> {
+    return new Collection(this.items.filter(callback))
+  }
+
+  where(key: string, value: any): Collection<T> {
+    return this.filter((item) => item.getAttribute(key) === value)
+  }
+
+  whereIn(key: string, values: any[]): Collection<T> {
+    return this.filter((item) => values.includes(item.getAttribute(key)))
+  }
+
+  reject(callback: (item: T) => boolean): Collection<T> {
+    return this.filter((item) => !callback(item))
+  }
+
+  // ── Transformation ──────────────────────────────────────────────────────
+
+  map<U>(callback: (item: T, index: number) => U): U[] {
+    return this.items.map(callback)
+  }
+
+  flatMap<U>(callback: (item: T) => U[]): U[] {
+    return this.items.flatMap(callback)
+  }
+
+  pluck(key: string): any[] {
+    return this.items.map((item) => item.getAttribute(key))
+  }
+
+  modelKeys(): any[] {
+    return this.items.map((item) => item.getKey())
+  }
+
+  unique(key?: string): Collection<T> {
+    const seen = new Set()
+    return this.filter((item) => {
+      const val = key ? item.getAttribute(key) : item.getKey()
+      if (seen.has(val)) return false
+      seen.add(val)
+      return true
+    })
+  }
+
+  // ── Ordering ─────────────────────────────────────────────────────────────
+
+  sortBy(key: string, direction: 'asc' | 'desc' = 'asc'): Collection<T> {
+    const sorted = [...this.items].sort((a, b) => {
+      const aVal = a.getAttribute(key)
+      const bVal = b.getAttribute(key)
+      if (aVal < bVal) return direction === 'asc' ? -1 : 1
+      if (aVal > bVal) return direction === 'asc' ? 1 : -1
+      return 0
+    })
+    return new Collection(sorted)
+  }
+
+  reverse(): Collection<T> {
+    return new Collection([...this.items].reverse())
+  }
+
+  // ── Aggregates ──────────────────────────────────────────────────────────
+
+  count(): number {
+    return this.items.length
+  }
+
+  sum(key: string): number {
+    return this.items.reduce((acc, item) => acc + Number(item.getAttribute(key) ?? 0), 0)
+  }
+
+  avg(key: string): number {
+    if (this.items.length === 0) return 0
+    return this.sum(key) / this.items.length
+  }
+
+  min(key: string): any {
+    if (this.items.length === 0) return undefined
+    return this.items.reduce((min, item) => {
+      const val = item.getAttribute(key)
+      return val < min ? val : min
+    }, this.items[0]!.getAttribute(key))
+  }
+
+  max(key: string): any {
+    if (this.items.length === 0) return undefined
+    return this.items.reduce((max, item) => {
+      const val = item.getAttribute(key)
+      return val > max ? val : max
+    }, this.items[0]!.getAttribute(key))
+  }
+
+  // ── Chunking ─────────────────────────────────────────────────────────────
+
+  chunk(size: number): Collection<T>[] {
+    const chunks: Collection<T>[] = []
+    for (let i = 0; i < this.items.length; i += size) {
+      chunks.push(new Collection(this.items.slice(i, i + size)))
+    }
+    return chunks
+  }
+
+  // ── Side effects ────────────────────────────────────────────────────────
+
+  each(callback: (item: T, index: number) => void): this {
+    this.items.forEach(callback)
+    return this
+  }
+
+  // ── Grouping ─────────────────────────────────────────────────────────────
+
+  groupBy(key: string): Map<any, Collection<T>> {
+    const groups = new Map<any, T[]>()
+    for (const item of this.items) {
+      const val = item.getAttribute(key)
+      if (!groups.has(val)) groups.set(val, [])
+      groups.get(val)!.push(item)
+    }
+    const result = new Map<any, Collection<T>>()
+    for (const [k, v] of groups) result.set(k, new Collection(v))
+    return result
+  }
+
+  keyBy(key: string): Map<any, T> {
+    const map = new Map<any, T>()
+    for (const item of this.items) {
+      map.set(item.getAttribute(key), item)
+    }
+    return map
+  }
+
+  // ── Set operations ──────────────────────────────────────────────────────
+
+  push(...items: T[]): this {
+    this.items.push(...items)
+    return this
+  }
+
+  concat(other: Collection<T> | T[]): Collection<T> {
+    const otherItems = other instanceof Collection ? other.toArray() : other
+    return new Collection([...this.items, ...otherItems])
+  }
+
+  // ── Serialization ───────────────────────────────────────────────────────
+
+  toJSON(): Record<string, any>[] {
+    return this.items.map((item) => item.toJSON())
+  }
+
+  isEmpty(): boolean {
+    return this.items.length === 0
+  }
+
+  isNotEmpty(): boolean {
+    return this.items.length > 0
+  }
+
+  // ── Batch operations ────────────────────────────────────────────────────
+
+  async load(...relations: string[]): Promise<this> {
+    // Lazy eager-load relations on an existing collection
+    // This delegates to the eager loading infrastructure
+    if (this.items.length === 0 || relations.length === 0) return this
+    const { eagerLoadRelations } = await import('./eagerLoad.ts')
+    await eagerLoadRelations(this.items, relations)
+    return this
+  }
+}
+
+// Add macro support — Collection.macro('name', fn) / instance.__macro('name')
+applyMacros(Collection)