@mantiq/database 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/database
+
+Query builder, Eloquent-style ORM, schema migrations, seeders, and factories for MantiqJS. Supports SQLite, Postgres, MySQL, and MongoDB.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/database
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@mantiq/database",
+  "version": "0.0.1",
+  "description": "Query builder, ORM, migrations, seeders, factories — with SQLite, Postgres, MySQL and MongoDB support",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/database",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/database"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "database"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/pg": "^8.18.0",
+    "bun-types": "latest",
+    "mssql": "^11.0.0",
+    "mysql2": "^3.14.1",
+    "pg": "^8.13.3",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "pg": "",
+    "mysql2": "",
+    "mssql": ">=10",
+    "mongodb": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "mssql": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    }
+  }
+}

package/src/DatabaseManager.ts

@@ -0,0 +1,115 @@
+import type { DatabaseConnection } from './contracts/Connection.ts'
+import type { MongoDatabaseConnection } from './contracts/MongoConnection.ts'
+import { SQLiteConnection } from './drivers/SQLiteConnection.ts'
+import { PostgresConnection } from './drivers/PostgresConnection.ts'
+import { MySQLConnection } from './drivers/MySQLConnection.ts'
+import { MongoConnection } from './drivers/MongoConnection.ts'
+import { ConnectionError } from './errors/ConnectionError.ts'
+
+export interface SQLConfig {
+  driver: 'sqlite' | 'postgres' | 'mysql'
+  database: string
+  host?: string
+  port?: number
+  user?: string
+  password?: string
+  ssl?: boolean
+  pool?: { min?: number; max?: number }
+}
+
+export interface MongoConfig {
+  driver: 'mongodb'
+  uri: string
+  database: string
+  options?: Record<string, any>
+}
+
+export type ConnectionConfig = SQLConfig | MongoConfig
+
+export interface DatabaseConfig {
+  default?: string
+  connections: Record<string, ConnectionConfig>
+}
+
+export class DatabaseManager {
+  private sqlConnections = new Map<string, DatabaseConnection>()
+  private mongoConnections = new Map<string, MongoDatabaseConnection>()
+
+  constructor(private readonly config: DatabaseConfig) {}
+
+  /** Get a SQL DatabaseConnection by name */
+  connection(name?: string): DatabaseConnection {
+    const connName = name ?? this.config.default ?? 'default'
+    if (this.sqlConnections.has(connName)) return this.sqlConnections.get(connName)!
+
+    const cfg = this.config.connections[connName]
+    if (!cfg) throw new ConnectionError(`Connection "${connName}" not configured`, connName)
+
+    const conn = this.makeConnection(cfg)
+    this.sqlConnections.set(connName, conn)
+    return conn
+  }
+
+  /** Get a MongoDB connection by name */
+  mongo(name?: string): MongoDatabaseConnection {
+    const connName = name ?? this.config.default ?? 'default'
+    if (this.mongoConnections.has(connName)) return this.mongoConnections.get(connName)!
+
+    const cfg = this.config.connections[connName]
+    if (!cfg) throw new ConnectionError(`Connection "${connName}" not configured`, connName)
+
+    if (cfg.driver !== 'mongodb') {
+      throw new ConnectionError(`Connection "${connName}" is not a MongoDB connection`, connName)
+    }
+
+    const conn = new MongoConnection({ uri: cfg.uri, database: cfg.database, options: cfg.options })
+    this.mongoConnections.set(connName, conn)
+    return conn
+  }
+
+  /** Shorthand for the default SQL connection's table() method */
+  table(name: string) {
+    return this.connection().table(name)
+  }
+
+  /** Shorthand for the default SQL connection's schema() method */
+  schema() {
+    return this.connection().schema()
+  }
+
+  /** Shorthand for MongoDB collection */
+  collection(name: string) {
+    return this.mongo().collection(name)
+  }
+
+  private makeConnection(cfg: ConnectionConfig): DatabaseConnection {
+    switch (cfg.driver) {
+      case 'sqlite':
+        return new SQLiteConnection({ database: cfg.database })
+      case 'postgres':
+        return new PostgresConnection({
+          database: cfg.database,
+          host: cfg.host,
+          port: cfg.port,
+          user: cfg.user,
+          password: cfg.password,
+          ssl: cfg.ssl,
+          pool: cfg.pool,
+        })
+      case 'mysql':
+        return new MySQLConnection({
+          database: cfg.database,
+          host: cfg.host,
+          port: cfg.port,
+          user: cfg.user,
+          password: cfg.password,
+          pool: cfg.pool,
+        })
+      case 'mongodb':
+        // MongoDB is handled separately via mongo()
+        throw new ConnectionError(`Use .mongo() to access MongoDB connections`, cfg.driver)
+      default:
+        throw new ConnectionError(`Unknown driver "${(cfg as any).driver}"`, (cfg as any).driver)
+    }
+  }
+}

package/src/DatabaseServiceProvider.ts

@@ -0,0 +1,39 @@
+import { DatabaseManager } from './DatabaseManager.ts'
+import { Model } from './orm/Model.ts'
+
+export const DATABASE_MANAGER = Symbol('DatabaseManager')
+
+/**
+ * Minimal service provider integration — provides a factory function
+ * so @mantiq/database can be used without @mantiq/core if needed.
+ *
+ * When using with @mantiq/core, extend ServiceProvider and register
+ * DatabaseManager as a singleton with your application's config.
+ *
+ * @example — with @mantiq/core:
+ * ```ts
+ * import { ServiceProvider } from '@mantiq/core'
+ * import { DatabaseManager, Model } from '@mantiq/database'
+ *
+ * export class DatabaseServiceProvider extends ServiceProvider {
+ *   register(): void {
+ *     this.app.singleton(DatabaseManager, () => {
+ *       const config = this.app.make('config').get('database')
+ *       const manager = new DatabaseManager(config)
+ *       Model.setConnection(manager.connection())
+ *       return manager
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export function createDatabaseManager(config: {
+  default?: string
+  connections: Record<string, any>
+}): DatabaseManager {
+  return new DatabaseManager(config)
+}
+
+export function setupModels(manager: DatabaseManager, connectionName?: string): void {
+  Model.setConnection(manager.connection(connectionName))
+}

package/src/contracts/Connection.ts

@@ -0,0 +1,13 @@
+import type { QueryBuilder } from '../query/Builder.ts'
+import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+
+export interface DatabaseConnection {
+  select(sql: string, bindings?: any[]): Promise<Record<string, any>[]>
+  statement(sql: string, bindings?: any[]): Promise<number>
+  insertGetId(sql: string, bindings?: any[]): Promise<number | bigint>
+  transaction<T>(callback: (connection: DatabaseConnection) => Promise<T>): Promise<T>
+  table(name: string): QueryBuilder
+  schema(): SchemaBuilder
+  getDriverName(): string
+  getTablePrefix(): string
+}

package/src/contracts/Grammar.ts

@@ -0,0 +1,16 @@
+import type { QueryState } from '../query/Builder.ts'
+
+export interface Grammar {
+  /** Quote a column or table identifier */
+  quoteIdentifier(name: string): string
+
+  compileSelect(state: QueryState): { sql: string; bindings: any[] }
+  compileInsert(table: string, data: Record<string, any>): { sql: string; bindings: any[] }
+  compileInsertGetId(table: string, data: Record<string, any>): { sql: string; bindings: any[] }
+  compileUpdate(table: string, state: QueryState, data: Record<string, any>): { sql: string; bindings: any[] }
+  compileDelete(table: string, state: QueryState): { sql: string; bindings: any[] }
+  compileTruncate(table: string): string
+
+  /** Placeholder token for parameterised queries: '?' for SQLite/MySQL, '$1' for Postgres */
+  placeholder(index: number): string
+}

package/src/contracts/MongoConnection.ts

@@ -0,0 +1,122 @@
+export interface MongoFilter {
+  [key: string]: any
+}
+
+export interface MongoProjection {
+  [key: string]: 0 | 1
+}
+
+export interface MongoUpdateDoc {
+  $set?: Record<string, any>
+  $unset?: Record<string, any>
+  $inc?: Record<string, any>
+  $push?: Record<string, any>
+  $pull?: Record<string, any>
+  $addToSet?: Record<string, any>
+  [key: string]: any
+}
+
+export interface MongoSortDoc {
+  [key: string]: 1 | -1
+}
+
+export interface MongoPipelineStage {
+  $match?: MongoFilter
+  $project?: MongoProjection
+  $sort?: MongoSortDoc
+  $limit?: number
+  $skip?: number
+  $group?: Record<string, any>
+  $lookup?: Record<string, any>
+  $unwind?: string | Record<string, any>
+  $addFields?: Record<string, any>
+  [key: string]: any
+}
+
+export interface MongoInsertResult {
+  insertedId: any
+  acknowledged: boolean
+}
+
+export interface MongoInsertManyResult {
+  insertedIds: any[]
+  acknowledged: boolean
+  insertedCount: number
+}
+
+export interface MongoUpdateResult {
+  matchedCount: number
+  modifiedCount: number
+  acknowledged: boolean
+}
+
+export interface MongoDeleteResult {
+  deletedCount: number
+  acknowledged: boolean
+}
+
+export interface MongoCollectionContract {
+  /** Find documents matching filter */
+  find(filter?: MongoFilter): MongoQueryBuilder
+  /** Find a single document */
+  findOne(filter?: MongoFilter): Promise<Record<string, any> | null>
+  /** Find by _id */
+  findById(id: any): Promise<Record<string, any> | null>
+  /** Insert a single document */
+  insertOne(doc: Record<string, any>): Promise<MongoInsertResult>
+  /** Insert multiple documents */
+  insertMany(docs: Record<string, any>[]): Promise<MongoInsertManyResult>
+  /** Update first matching document */
+  updateOne(filter: MongoFilter, update: MongoUpdateDoc): Promise<MongoUpdateResult>
+  /** Update all matching documents */
+  updateMany(filter: MongoFilter, update: MongoUpdateDoc): Promise<MongoUpdateResult>
+  /** Replace a document by _id */
+  replaceOne(filter: MongoFilter, replacement: Record<string, any>): Promise<MongoUpdateResult>
+  /** Upsert: update or insert */
+  upsert(filter: MongoFilter, update: MongoUpdateDoc): Promise<MongoUpdateResult>
+  /** Delete first matching document */
+  deleteOne(filter: MongoFilter): Promise<MongoDeleteResult>
+  /** Delete all matching documents */
+  deleteMany(filter: MongoFilter): Promise<MongoDeleteResult>
+  /** Run an aggregation pipeline */
+  aggregate(pipeline: MongoPipelineStage[]): Promise<Record<string, any>[]>
+  /** Count documents */
+  count(filter?: MongoFilter): Promise<number>
+  /** Create an index */
+  createIndex(spec: Record<string, any>, options?: Record<string, any>): Promise<string>
+  /** Drop the collection */
+  drop(): Promise<boolean>
+}
+
+export interface MongoQueryBuilder {
+  /** Filter documents */
+  where(filter: MongoFilter): MongoQueryBuilder
+  /** Projection — include/exclude fields */
+  select(projection: MongoProjection): MongoQueryBuilder
+  /** Sort results */
+  sort(sort: MongoSortDoc): MongoQueryBuilder
+  /** Limit results */
+  limit(n: number): MongoQueryBuilder
+  /** Skip results */
+  skip(n: number): MongoQueryBuilder
+  /** Execute and return all results */
+  get(): Promise<Record<string, any>[]>
+  /** Execute and return first result */
+  first(): Promise<Record<string, any> | null>
+  /** Execute and return first or throw */
+  firstOrFail(): Promise<Record<string, any>>
+  /** Count matching documents */
+  count(): Promise<number>
+}
+
+export interface MongoDatabaseConnection {
+  /** Get a collection query interface */
+  collection(name: string): MongoCollectionContract
+  /** Run a raw command */
+  command(command: Record<string, any>): Promise<any>
+  /** List all collection names */
+  listCollections(): Promise<string[]>
+  /** Start a transaction session */
+  transaction<T>(callback: (conn: MongoDatabaseConnection) => Promise<T>): Promise<T>
+  getDriverName(): string
+}

package/src/contracts/Paginator.ts

@@ -0,0 +1,10 @@
+export interface PaginationResult<T = Record<string, any>> {
+  data: T[]
+  total: number
+  perPage: number
+  currentPage: number
+  lastPage: number
+  from: number
+  to: number
+  hasMore: boolean
+}

package/src/drivers/BaseGrammar.ts

@@ -0,0 +1,220 @@
+import { Expression } from '../query/Expression.ts'
+import type { WhereClause, QueryState, JoinClause, OrderClause } from '../query/Builder.ts'
+import type { Grammar } from '../contracts/Grammar.ts'
+
+export abstract class BaseGrammar implements Grammar {
+  abstract quoteIdentifier(name: string): string
+  abstract placeholder(index: number): string
+
+  // ── SELECT ────────────────────────────────────────────────────────────────
+
+  compileSelect(state: QueryState): { sql: string; bindings: any[] } {
+    const bindings: any[] = []
+    const parts: string[] = []
+
+    // Collect raw expression bindings from columns first (they come first in the final bindings)
+    const colBindings: any[] = []
+    for (const c of state.columns) {
+      if (c instanceof Expression) colBindings.push(...c.bindings)
+    }
+
+    const cols = state.columns.map((c) => {
+      if (c instanceof Expression) return c.value
+      const s = c as string
+      // Don't quote wildcards or already-qualified expressions
+      if (s === '*' || s.endsWith('.*')) return s
+      return this.quoteIdentifier(s)
+    }).join(', ')
+
+    parts.push(`SELECT ${state.distinct ? 'DISTINCT ' : ''}${cols}`)
+    parts.push(`FROM ${this.quoteIdentifier(state.table)}`)
+
+    if (state.joins.length) {
+      for (const j of state.joins) {
+        parts.push(this.compileJoin(j))
+      }
+    }
+
+    if (state.wheres.length) {
+      const { sql: whereSql, bindings: wb } = this.compileWheres(state.wheres, colBindings.length + 1)
+      parts.push(`WHERE ${whereSql}`)
+      bindings.push(...wb)
+    }
+
+    if (state.groups.length) {
+      parts.push(`GROUP BY ${state.groups.map((g) => this.quoteIdentifier(g)).join(', ')}`)
+    }
+
+    if (state.havings.length) {
+      const havingStartIdx = colBindings.length + bindings.length + 1
+      const { sql: havingSql, bindings: hb } = this.compileWheres(state.havings, havingStartIdx)
+      parts.push(`HAVING ${havingSql}`)
+      bindings.push(...hb)
+    }
+
+    if (state.orders.length) {
+      const orderStr = state.orders.map((o) => {
+        const col = o.column instanceof Expression
+          ? o.column.value
+          : this.quoteIdentifier(o.column as string)
+        return `${col} ${o.direction.toUpperCase()}`
+      }).join(', ')
+      parts.push(`ORDER BY ${orderStr}`)
+    }
+
+    if (state.limitValue !== null) {
+      parts.push(`LIMIT ${state.limitValue}`)
+    }
+
+    if (state.offsetValue !== null) {
+      parts.push(`OFFSET ${state.offsetValue}`)
+    }
+
+    return { sql: parts.join(' '), bindings: [...colBindings, ...bindings] }
+  }
+
+  // ── INSERT ────────────────────────────────────────────────────────────────
+
+  compileInsert(table: string, data: Record<string, any>): { sql: string; bindings: any[] } {
+    const keys = Object.keys(data)
+    const cols = keys.map((k) => this.quoteIdentifier(k)).join(', ')
+    const placeholders = keys.map((_, i) => this.placeholder(i + 1)).join(', ')
+    return {
+      sql: `INSERT INTO ${this.quoteIdentifier(table)} (${cols}) VALUES (${placeholders})`,
+      bindings: Object.values(data),
+    }
+  }
+
+  compileInsertGetId(table: string, data: Record<string, any>): { sql: string; bindings: any[] } {
+    return this.compileInsert(table, data)
+  }
+
+  // ── UPDATE ────────────────────────────────────────────────────────────────
+
+  compileUpdate(
+    table: string,
+    state: QueryState,
+    data: Record<string, any>,
+  ): { sql: string; bindings: any[] } {
+    const bindings: any[] = []
+    const keys = Object.keys(data)
+    let setIndex = 1
+    const sets = keys.map((k) => {
+      const val = data[k]
+      if (val instanceof Expression) return `${this.quoteIdentifier(k)} = ${val.value}`
+      bindings.push(val)
+      return `${this.quoteIdentifier(k)} = ${this.placeholder(setIndex++)}`
+    }).join(', ')
+
+    let sql = `UPDATE ${this.quoteIdentifier(table)} SET ${sets}`
+
+    if (state.wheres.length) {
+      // Pass current binding count so WHERE $n continues from where SET left off
+      const { sql: whereSql, bindings: wb } = this.compileWheres(state.wheres, bindings.length + 1)
+      sql += ` WHERE ${whereSql}`
+      bindings.push(...wb)
+    }
+
+    return { sql, bindings }
+  }
+
+  // ── DELETE ────────────────────────────────────────────────────────────────
+
+  compileDelete(table: string, state: QueryState): { sql: string; bindings: any[] } {
+    const bindings: any[] = []
+    let sql = `DELETE FROM ${this.quoteIdentifier(table)}`
+
+    if (state.wheres.length) {
+      const { sql: whereSql, bindings: wb } = this.compileWheres(state.wheres)
+      sql += ` WHERE ${whereSql}`
+      bindings.push(...wb)
+    }
+
+    return { sql, bindings }
+  }
+
+  compileTruncate(table: string): string {
+    return `DELETE FROM ${this.quoteIdentifier(table)}`
+  }
+
+  // ── Private helpers ───────────────────────────────────────────────────────
+
+  private compileJoin(j: JoinClause): string {
+    const type = j.type.toUpperCase()
+    return `${type} JOIN ${this.quoteIdentifier(j.table)} ON ${j.first} ${j.operator} ${j.second}`
+  }
+
+  protected compileWheres(wheres: WhereClause[], startIndex = 1): { sql: string; bindings: any[] } {
+    const parts: string[] = []
+    const bindings: any[] = []
+    let bindingIndex = startIndex
+
+    for (let i = 0; i < wheres.length; i++) {
+      const w = wheres[i]!
+      const bool = i === 0 ? '' : w.boolean.toUpperCase() + ' '
+
+      if (w.type === 'raw') {
+        parts.push(`${bool}${w.sql}`)
+        const rawBindings = w.bindings ?? []
+        bindings.push(...rawBindings)
+        bindingIndex += rawBindings.length
+        continue
+      }
+
+      if (w.type === 'nested') {
+        const { sql: nestedSql, bindings: nb } = this.compileWheres(w.nested ?? [], bindingIndex)
+        parts.push(`${bool}(${nestedSql})`)
+        bindings.push(...nb)
+        bindingIndex += nb.length
+        continue
+      }
+
+      if (w.type === 'null') {
+        parts.push(`${bool}${this.quoteIdentifier(w.column!)} IS NULL`)
+        continue
+      }
+
+      if (w.type === 'notNull') {
+        parts.push(`${bool}${this.quoteIdentifier(w.column!)} IS NOT NULL`)
+        continue
+      }
+
+      if (w.type === 'in') {
+        const placeholders = (w.values ?? []).map((_, i) => this.placeholder(bindingIndex++)).join(', ')
+        parts.push(`${bool}${this.quoteIdentifier(w.column!)} IN (${placeholders})`)
+        bindings.push(...(w.values ?? []))
+        continue
+      }
+
+      if (w.type === 'notIn') {
+        const placeholders = (w.values ?? []).map((_, i) => this.placeholder(bindingIndex++)).join(', ')
+        parts.push(`${bool}${this.quoteIdentifier(w.column!)} NOT IN (${placeholders})`)
+        bindings.push(...(w.values ?? []))
+        continue
+      }
+
+      if (w.type === 'between') {
+        const p1 = this.placeholder(bindingIndex++)
+        const p2 = this.placeholder(bindingIndex++)
+        parts.push(`${bool}${this.quoteIdentifier(w.column!)} BETWEEN ${p1} AND ${p2}`)
+        bindings.push(...(w.range ?? []))
+        continue
+      }
+
+      if (w.type === 'column') {
+        parts.push(`${bool}${this.quoteIdentifier(w.column!)} ${w.operator} ${this.quoteIdentifier(w.secondColumn!)}`)
+        continue
+      }
+
+      // basic
+      if (w.value instanceof Expression) {
+        parts.push(`${bool}${this.quoteIdentifier(w.column!)} ${w.operator} ${w.value.value}`)
+      } else {
+        parts.push(`${bool}${this.quoteIdentifier(w.column!)} ${w.operator} ${this.placeholder(bindingIndex++)}`)
+        bindings.push(w.value)
+      }
+    }
+
+    return { sql: parts.join(' '), bindings }
+  }
+}