@mantiq/database 0.0.1

package/src/query/Builder.ts

@@ -0,0 +1,456 @@
+import { Expression } from './Expression.ts'
+import { ModelNotFoundError } from '../errors/ModelNotFoundError.ts'
+import { applyMacros } from '@mantiq/core'
+import type { PaginationResult } from '../contracts/Paginator.ts'
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+
+export type Operator = '=' | '!=' | '<>' | '<' | '>' | '<=' | '>=' | 'like' | 'not like' | 'in' | 'not in'
+
+export interface WhereClause {
+  type: 'basic' | 'in' | 'notIn' | 'null' | 'notNull' | 'between' | 'raw' | 'nested' | 'column'
+  boolean: 'and' | 'or'
+  column?: string
+  operator?: string
+  value?: any
+  values?: any[]
+  range?: [any, any]
+  sql?: string
+  bindings?: any[]
+  nested?: WhereClause[]
+  secondColumn?: string
+}
+
+export interface JoinClause {
+  type: 'inner' | 'left' | 'right'
+  table: string
+  first: string
+  operator: string
+  second: string
+}
+
+export interface OrderClause {
+  column: string | Expression
+  direction: 'asc' | 'desc'
+}
+
+export interface QueryState {
+  table: string
+  columns: (string | Expression)[]
+  distinct: boolean
+  wheres: WhereClause[]
+  joins: JoinClause[]
+  orders: OrderClause[]
+  groups: string[]
+  havings: WhereClause[]
+  limitValue: number | null
+  offsetValue: number | null
+}
+
+export class QueryBuilder {
+  protected state: QueryState
+  protected _connection: DatabaseConnection
+
+  constructor(connection: DatabaseConnection, table: string) {
+    this._connection = connection
+    this.state = {
+      table,
+      columns: ['*'],
+      distinct: false,
+      wheres: [],
+      joins: [],
+      orders: [],
+      groups: [],
+      havings: [],
+      limitValue: null,
+      offsetValue: null,
+    }
+  }
+
+  // ── Selection ─────────────────────────────────────────────────────────────
+
+  select(...columns: (string | Expression)[]): this {
+    this.state.columns = columns.length ? columns : ['*']
+    return this
+  }
+
+  selectRaw(expression: string, bindings?: any[]): this {
+    this.state.columns = [new Expression(expression, bindings)]
+    return this
+  }
+
+  addSelect(...columns: (string | Expression)[]): this {
+    if (this.state.columns.length === 1 && this.state.columns[0] === '*') {
+      this.state.columns = [...columns]
+    } else {
+      this.state.columns.push(...columns)
+    }
+    return this
+  }
+
+  distinct(): this {
+    this.state.distinct = true
+    return this
+  }
+
+  // ── Where conditions ─────────────────────────────────────────────────────
+
+  where(column: string | ((q: QueryBuilder) => void), operatorOrValue?: any, value?: any): this {
+    if (typeof column === 'function') {
+      const nested: WhereClause[] = []
+      const sub = new QueryBuilder(this._connection, this.state.table)
+      column(sub)
+      this.state.wheres.push({ type: 'nested', boolean: 'and', nested: sub.state.wheres })
+      return this
+    }
+
+    let operator: string
+    let val: any
+    if (value === undefined) {
+      operator = '='
+      val = operatorOrValue
+    } else {
+      operator = operatorOrValue
+      val = value
+    }
+
+    this.state.wheres.push({ type: 'basic', boolean: 'and', column, operator, value: val })
+    return this
+  }
+
+  orWhere(column: string | ((q: QueryBuilder) => void), operatorOrValue?: any, value?: any): this {
+    if (typeof column === 'function') {
+      const sub = new QueryBuilder(this._connection, this.state.table)
+      column(sub)
+      this.state.wheres.push({ type: 'nested', boolean: 'or', nested: sub.state.wheres })
+      return this
+    }
+    let operator: string
+    let val: any
+    if (value === undefined) {
+      operator = '='
+      val = operatorOrValue
+    } else {
+      operator = operatorOrValue
+      val = value
+    }
+    this.state.wheres.push({ type: 'basic', boolean: 'or', column, operator, value: val })
+    return this
+  }
+
+  whereIn(column: string, values: any[]): this {
+    this.state.wheres.push({ type: 'in', boolean: 'and', column, values })
+    return this
+  }
+
+  whereNotIn(column: string, values: any[]): this {
+    this.state.wheres.push({ type: 'notIn', boolean: 'and', column, values })
+    return this
+  }
+
+  whereNull(column: string): this {
+    this.state.wheres.push({ type: 'null', boolean: 'and', column })
+    return this
+  }
+
+  whereNotNull(column: string): this {
+    this.state.wheres.push({ type: 'notNull', boolean: 'and', column })
+    return this
+  }
+
+  whereBetween(column: string, range: [any, any]): this {
+    this.state.wheres.push({ type: 'between', boolean: 'and', column, range })
+    return this
+  }
+
+  whereRaw(sql: string, bindings?: any[]): this {
+    this.state.wheres.push({ type: 'raw', boolean: 'and', sql, bindings: bindings ?? [] })
+    return this
+  }
+
+  /**
+   * Add a where clause comparing two columns.
+   *
+   * @example
+   *   query.whereColumn('updated_at', '>', 'created_at')
+   *   query.whereColumn('first_name', 'last_name') // defaults to '='
+   */
+  whereColumn(first: string, operatorOrSecond: string, second?: string): this {
+    let operator: string
+    let secondCol: string
+    if (second === undefined) {
+      operator = '='
+      secondCol = operatorOrSecond
+    } else {
+      operator = operatorOrSecond
+      secondCol = second
+    }
+    this.state.wheres.push({ type: 'column', boolean: 'and', column: first, operator, secondColumn: secondCol })
+    return this
+  }
+
+  /**
+   * Filter by date part of a datetime column.
+   * @example query.whereDate('created_at', '2024-01-15')
+   */
+  whereDate(column: string, operatorOrValue: string, value?: string): this {
+    const [op, val] = value === undefined ? ['=', operatorOrValue] : [operatorOrValue, value]
+    return this.whereRaw(`DATE(${column}) ${op} ?`, [val])
+  }
+
+  /**
+   * Filter by month of a datetime column.
+   * @example query.whereMonth('created_at', '03')
+   */
+  whereMonth(column: string, operatorOrValue: string | number, value?: string | number): this {
+    const [op, val] = value === undefined ? ['=', operatorOrValue] : [operatorOrValue, value]
+    return this.whereRaw(`strftime('%m', ${column}) ${op} ?`, [String(val).padStart(2, '0')])
+  }
+
+  /**
+   * Filter by year of a datetime column.
+   * @example query.whereYear('created_at', 2024)
+   */
+  whereYear(column: string, operatorOrValue: string | number, value?: string | number): this {
+    const [op, val] = value === undefined ? ['=', operatorOrValue] : [operatorOrValue, value]
+    return this.whereRaw(`strftime('%Y', ${column}) ${op} ?`, [String(val)])
+  }
+
+  /**
+   * Filter by time part of a datetime column.
+   * @example query.whereTime('created_at', '>=', '10:00')
+   */
+  whereTime(column: string, operatorOrValue: string, value?: string): this {
+    const [op, val] = value === undefined ? ['=', operatorOrValue] : [operatorOrValue, value]
+    return this.whereRaw(`strftime('%H:%M:%S', ${column}) ${op} ?`, [val])
+  }
+
+  // ── Joins ─────────────────────────────────────────────────────────────────
+
+  join(table: string, first: string, operator: string, second: string): this {
+    this.state.joins.push({ type: 'inner', table, first, operator, second })
+    return this
+  }
+
+  leftJoin(table: string, first: string, operator: string, second: string): this {
+    this.state.joins.push({ type: 'left', table, first, operator, second })
+    return this
+  }
+
+  rightJoin(table: string, first: string, operator: string, second: string): this {
+    this.state.joins.push({ type: 'right', table, first, operator, second })
+    return this
+  }
+
+  // ── Ordering / Grouping ───────────────────────────────────────────────────
+
+  orderBy(column: string | Expression, direction: 'asc' | 'desc' = 'asc'): this {
+    this.state.orders.push({ column, direction })
+    return this
+  }
+
+  orderByDesc(column: string): this {
+    return this.orderBy(column, 'desc')
+  }
+
+  groupBy(...columns: string[]): this {
+    this.state.groups.push(...columns)
+    return this
+  }
+
+  having(column: string, operator: string, value: any): this {
+    this.state.havings.push({ type: 'basic', boolean: 'and', column, operator, value })
+    return this
+  }
+
+  havingRaw(sql: string, bindings?: any[]): this {
+    this.state.havings.push({ type: 'raw', boolean: 'and', sql, bindings: bindings ?? [] })
+    return this
+  }
+
+  // ── Pagination ────────────────────────────────────────────────────────────
+
+  limit(value: number): this {
+    this.state.limitValue = value
+    return this
+  }
+
+  offset(value: number): this {
+    this.state.offsetValue = value
+    return this
+  }
+
+  take = this.limit
+  skip = this.offset
+
+  // ── Execution ─────────────────────────────────────────────────────────────
+
+  async get(): Promise<Record<string, any>[]> {
+    const { sql, bindings } = this.grammar().compileSelect(this.state)
+    return this._connection.select(sql, bindings)
+  }
+
+  async first(): Promise<Record<string, any> | null> {
+    const rows = await this.limit(1).get()
+    return rows[0] ?? null
+  }
+
+  async firstOrFail(): Promise<Record<string, any>> {
+    const row = await this.first()
+    if (!row) throw new ModelNotFoundError(this.state.table)
+    return row
+  }
+
+  async find(id: number | string): Promise<Record<string, any> | null> {
+    return this.where('id', id).first()
+  }
+
+  async value(column: string): Promise<any> {
+    const row = await this.select(column).first()
+    return row ? row[column] : null
+  }
+
+  async pluck(column: string): Promise<any[]> {
+    const rows = await this.select(column).get()
+    return rows.map((r) => r[column])
+  }
+
+  async exists(): Promise<boolean> {
+    const row = await this.selectRaw('1 as exists_check').limit(1).first()
+    return row !== null
+  }
+
+  async doesntExist(): Promise<boolean> {
+    return !(await this.exists())
+  }
+
+  /**
+   * Get the only record matching the query. Throws if zero or more than one.
+   */
+  async sole(): Promise<Record<string, any>> {
+    const results = await this.limit(2).get()
+    if (results.length === 0) throw new ModelNotFoundError(this.state.table)
+    if (results.length > 1) throw new Error(`Expected one result for table [${this.state.table}], found multiple.`)
+    return results[0]!
+  }
+
+  // ── Aggregates ────────────────────────────────────────────────────────────
+
+  async count(column = '*'): Promise<number> {
+    const row = await this.selectRaw(`COUNT(${column}) as aggregate`).first()
+    return Number(row?.['aggregate'] ?? 0)
+  }
+
+  async sum(column: string): Promise<number> {
+    const row = await this.selectRaw(`SUM(${column}) as aggregate`).first()
+    return Number(row?.['aggregate'] ?? 0)
+  }
+
+  async avg(column: string): Promise<number> {
+    const row = await this.selectRaw(`AVG(${column}) as aggregate`).first()
+    return Number(row?.['aggregate'] ?? 0)
+  }
+
+  async min(column: string): Promise<any> {
+    const row = await this.selectRaw(`MIN(${column}) as aggregate`).first()
+    return row?.['aggregate']
+  }
+
+  async max(column: string): Promise<any> {
+    const row = await this.selectRaw(`MAX(${column}) as aggregate`).first()
+    return row?.['aggregate']
+  }
+
+  // ── Writes ────────────────────────────────────────────────────────────────
+
+  async insert(data: Record<string, any> | Record<string, any>[]): Promise<void> {
+    const rows = Array.isArray(data) ? data : [data]
+    for (const row of rows) {
+      const { sql, bindings } = this.grammar().compileInsert(this.state.table, row)
+      await this._connection.statement(sql, bindings)
+    }
+  }
+
+  async insertGetId(data: Record<string, any>): Promise<number> {
+    const { sql, bindings } = this.grammar().compileInsertGetId(this.state.table, data)
+    const id = await this._connection.insertGetId(sql, bindings)
+    return Number(id)
+  }
+
+  async update(data: Record<string, any>): Promise<number> {
+    const { sql, bindings } = this.grammar().compileUpdate(this.state.table, this.state, data)
+    return this._connection.statement(sql, bindings)
+  }
+
+  async updateOrInsert(
+    conditions: Record<string, any>,
+    data: Record<string, any>,
+  ): Promise<void> {
+    const clone = this.clone()
+    for (const [k, v] of Object.entries(conditions)) clone.where(k, v)
+    const exists = await clone.exists()
+    if (exists) {
+      await clone.update(data)
+    } else {
+      await this.insert({ ...conditions, ...data })
+    }
+  }
+
+  async delete(): Promise<number> {
+    const { sql, bindings } = this.grammar().compileDelete(this.state.table, this.state)
+    return this._connection.statement(sql, bindings)
+  }
+
+  async truncate(): Promise<void> {
+    const sql = this.grammar().compileTruncate(this.state.table)
+    await this._connection.statement(sql, [])
+  }
+
+  // ── Pagination ────────────────────────────────────────────────────────────
+
+  async paginate(page = 1, perPage = 15): Promise<PaginationResult> {
+    const total = await this.clone().count()
+    const lastPage = Math.max(1, Math.ceil(total / perPage))
+    const currentPage = Math.min(page, lastPage)
+    const data = await this.clone().limit(perPage).offset((currentPage - 1) * perPage).get()
+    const from = total === 0 ? 0 : (currentPage - 1) * perPage + 1
+    const to = Math.min(from + data.length - 1, total)
+    return { data, total, perPage, currentPage, lastPage, from, to, hasMore: currentPage < lastPage }
+  }
+
+  // ── Utilities ─────────────────────────────────────────────────────────────
+
+  toSql(): string {
+    return this.grammar().compileSelect(this.state).sql
+  }
+
+  getBindings(): any[] {
+    return this.grammar().compileSelect(this.state).bindings
+  }
+
+  clone(): QueryBuilder {
+    const copy = new QueryBuilder(this._connection, this.state.table)
+    copy.state = {
+      ...this.state,
+      columns: [...this.state.columns],
+      wheres: [...this.state.wheres],
+      joins: [...this.state.joins],
+      orders: [...this.state.orders],
+      groups: [...this.state.groups],
+      havings: [...this.state.havings],
+    }
+    return copy
+  }
+
+  getState(): QueryState {
+    return this.state
+  }
+
+  // ── Grammar (driver-specific SQL) ─────────────────────────────────────────
+
+  protected grammar() {
+    return (this._connection as any)._grammar as import('../contracts/Grammar.ts').Grammar
+  }
+}
+
+// Add macro support — QueryBuilder.macro('name', fn) / instance.__macro('name')
+applyMacros(QueryBuilder)

package/src/query/Expression.ts

@@ -0,0 +1,18 @@
+/**
+ * Wraps a raw SQL string so the query builder won't escape/quote it.
+ * @example db.raw('COUNT(*) as total')
+ */
+export class Expression {
+  constructor(
+    public readonly value: string,
+    public readonly bindings: any[] = [],
+  ) {}
+
+  toString(): string {
+    return this.value
+  }
+}
+
+export function raw(expression: string, bindings?: any[]): Expression {
+  return new Expression(expression, bindings ?? [])
+}

package/src/schema/Blueprint.ts

@@ -0,0 +1,196 @@
+import { ColumnDefinition } from './ColumnDefinition.ts'
+
+export interface IndexDefinition {
+  type: 'index' | 'unique' | 'primary'
+  columns: string[]
+  name?: string
+}
+
+export interface ForeignKeyDefinition {
+  column: string
+  references: string
+  on: string
+  onDelete?: string
+  onUpdate?: string
+}
+
+export class Blueprint {
+  readonly columns: ColumnDefinition[] = []
+  readonly indexes: IndexDefinition[] = []
+  readonly foreignKeys: ForeignKeyDefinition[] = []
+  readonly droppedColumns: string[] = []
+  readonly droppedIndexes: string[] = []
+
+  // ── Common column types ────────────────────────────────────────────────────
+
+  id(name = 'id'): ColumnDefinition {
+    const col = new ColumnDefinition(name, 'bigIncrements')
+    this.columns.push(col)
+    return col
+  }
+
+  bigIncrements(name: string): ColumnDefinition {
+    return this.addColumn(name, 'bigIncrements')
+  }
+
+  increments(name: string): ColumnDefinition {
+    return this.addColumn(name, 'increments')
+  }
+
+  string(name: string, length = 255): ColumnDefinition {
+    return this.addColumn(name, 'string', length)
+  }
+
+  text(name: string): ColumnDefinition {
+    return this.addColumn(name, 'text')
+  }
+
+  longText(name: string): ColumnDefinition {
+    return this.addColumn(name, 'longText')
+  }
+
+  mediumText(name: string): ColumnDefinition {
+    return this.addColumn(name, 'mediumText')
+  }
+
+  integer(name: string): ColumnDefinition {
+    return this.addColumn(name, 'integer')
+  }
+
+  bigInteger(name: string): ColumnDefinition {
+    return this.addColumn(name, 'bigInteger')
+  }
+
+  tinyInteger(name: string): ColumnDefinition {
+    return this.addColumn(name, 'tinyInteger')
+  }
+
+  smallInteger(name: string): ColumnDefinition {
+    return this.addColumn(name, 'smallInteger')
+  }
+
+  unsignedInteger(name: string): ColumnDefinition {
+    return this.addColumn(name, 'unsignedInteger')
+  }
+
+  unsignedBigInteger(name: string): ColumnDefinition {
+    return this.addColumn(name, 'unsignedBigInteger')
+  }
+
+  float(name: string, precision = 8, scale = 2): ColumnDefinition {
+    return this.addColumn(name, 'float', undefined, precision, scale)
+  }
+
+  double(name: string, precision = 15, scale = 8): ColumnDefinition {
+    return this.addColumn(name, 'double', undefined, precision, scale)
+  }
+
+  decimal(name: string, precision = 8, scale = 2): ColumnDefinition {
+    return this.addColumn(name, 'decimal', undefined, precision, scale)
+  }
+
+  boolean(name: string): ColumnDefinition {
+    return this.addColumn(name, 'boolean')
+  }
+
+  date(name: string): ColumnDefinition {
+    return this.addColumn(name, 'date')
+  }
+
+  dateTime(name: string): ColumnDefinition {
+    return this.addColumn(name, 'dateTime')
+  }
+
+  timestamp(name: string): ColumnDefinition {
+    return this.addColumn(name, 'timestamp')
+  }
+
+  timestamps(): void {
+    this.timestamp('created_at').nullable()
+    this.timestamp('updated_at').nullable()
+  }
+
+  softDeletes(column = 'deleted_at'): ColumnDefinition {
+    return this.timestamp(column).nullable()
+  }
+
+  json(name: string): ColumnDefinition {
+    return this.addColumn(name, 'json')
+  }
+
+  jsonb(name: string): ColumnDefinition {
+    return this.addColumn(name, 'jsonb')
+  }
+
+  uuid(name: string): ColumnDefinition {
+    return this.addColumn(name, 'uuid')
+  }
+
+  binary(name: string): ColumnDefinition {
+    return this.addColumn(name, 'binary')
+  }
+
+  enum(name: string, values: string[]): ColumnDefinition {
+    const col = new ColumnDefinition(name, `enum:${values.join(',')}`)
+    this.columns.push(col)
+    return col
+  }
+
+  // ── Foreign key shortcuts ─────────────────────────────────────────────────
+
+  foreignId(name: string): ColumnDefinition {
+    return this.unsignedBigInteger(name)
+  }
+
+  foreign(column: string): { references(col: string): { on(table: string): ForeignKeyDefinition } } {
+    return {
+      references: (col: string) => ({
+        on: (table: string): ForeignKeyDefinition => {
+          const fk: ForeignKeyDefinition = { column, references: col, on: table }
+          this.foreignKeys.push(fk)
+          return fk
+        },
+      }),
+    }
+  }
+
+  // ── Indexes ────────────────────────────────────────────────────────────────
+
+  index(columns: string | string[], name?: string): void {
+    this.indexes.push({ type: 'index', columns: Array.isArray(columns) ? columns : [columns], name })
+  }
+
+  unique(columns: string | string[], name?: string): void {
+    this.indexes.push({ type: 'unique', columns: Array.isArray(columns) ? columns : [columns], name })
+  }
+
+  primary(columns: string | string[]): void {
+    this.indexes.push({ type: 'primary', columns: Array.isArray(columns) ? columns : [columns] })
+  }
+
+  // ── Modify / drop ─────────────────────────────────────────────────────────
+
+  dropColumn(name: string): void {
+    this.droppedColumns.push(name)
+  }
+
+  dropTimestamps(): void {
+    this.droppedColumns.push('created_at', 'updated_at')
+  }
+
+  dropSoftDeletes(column = 'deleted_at'): void {
+    this.droppedColumns.push(column)
+  }
+
+  dropIndex(name: string): void {
+    this.droppedIndexes.push(name)
+  }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+
+  private addColumn(name: string, type: string, length?: number, precision?: number, scale?: number): ColumnDefinition {
+    const col = new ColumnDefinition(name, type, length, precision, scale)
+    this.columns.push(col)
+    return col
+  }
+}