@sigitex/outlaw 1.0.0

package/src/cowboyMigration/createSchemaHacker.ts

@@ -0,0 +1,28 @@
+import type { SchemaHack } from "./cowboyMigration.types"
+
+export type SchemaHacker = ReturnType<typeof createSchemaHacker>
+
+export function createSchemaHacker() {
+  const hacks: SchemaHack[] = []
+  return {
+    get hacks() {
+      return hacks
+    },
+    renamed: {
+      table(fromTable: string, toTable: string) {
+        hacks.push({ type: "renamedTable", fromTable, toTable })
+      },
+      column(fromTable: string, fromColumn: string, toColumn: string) {
+        hacks.push({ type: "renamedColumn", fromTable, fromColumn, toColumn })
+      },
+    },
+    dropped: {
+      table(tableName: string) {
+        hacks.push({ type: "droppedTable", tableName })
+      },
+      column(tableName: string, columnName: string) {
+        hacks.push({ type: "droppedColumn", tableName, columnName })
+      },
+    },
+  }
+}

package/src/cowboyMigration/index.ts

@@ -0,0 +1,3 @@
+export * from "./cowboyMigration.types"
+export * from "./CowboyConnection"
+export * from "./createSchemaHacker"

package/src/crypto.d.ts

@@ -0,0 +1,9 @@
+type Hash = {
+  update(data: string): Hash
+  digest(encoding: "hex"): string
+}
+
+declare module "node:crypto" {
+  export function createHash(algorithm: string): Hash
+  export function randomUUID(): `${string}-${string}-${string}-${string}-${string}`
+}

package/src/framework/Format.ts

@@ -0,0 +1,31 @@
+import * as SqlString from "sqlstring-sqlite"
+
+export namespace Format {
+  export const NOW = "strftime('%Y-%m-%dT%H:%M:%S.%fZ', 'now')"
+
+  export function text(text: string) {
+    return SqlString.escape(text)
+  }
+
+  export function name(name: string | null | undefined) {
+    return SqlString.escapeId(name)
+  }
+
+  export function number(number: number) {
+    if (typeof number !== "number" && typeof number !== "bigint") {
+      throw new Error("Not a number.")
+    }
+    const s = number.toString()
+    return number < 0 ? `(${s})` : s
+  }
+
+  export function value(value: unknown): string {
+    if (value === null || value === undefined) {
+      return "null"
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+      return Format.number(Number(value))
+    }
+    return Format.text(String(value))
+  }
+}

package/src/framework/definitions.d.ts

@@ -0,0 +1,4 @@
+declare module "sqlstring-sqlite" {
+  export function escape(text: string | null | undefined): string
+  export function escapeId(text: string | null | undefined): string
+}

package/src/framework/index.ts

@@ -0,0 +1 @@
+export * from "./Format"

package/src/index.ts

@@ -0,0 +1,10 @@
+import "./console"
+
+export * from "./api"
+export * from "./cowboyMigration"
+export * from "./framework"
+export * from "./queryBuilder"
+export * from "./queryGenerator"
+export * from "./reflection"
+export * from "./schemaBuilder"
+export * from "./schemaGenerator"

package/src/queryBuilder/DeleteBuilder.ts

@@ -0,0 +1,40 @@
+// oxlint-disable typescript/no-explicit-any
+import type { BinaryOperator, UnaryOperator, Delete, Connection } from "../api"
+import type { TableData } from "../schemaBuilder"
+import type { DeleteCommand } from "./queryBuilders.types"
+import { generateDelete } from "../queryGenerator"
+import { addWhereClause } from "./addWhereClause"
+import { Mappings } from "./Mappings"
+
+/** Constructs declarative `DELETE` statements. */
+export class DeleteBuilder implements Delete<any, any> {
+  connection: Connection
+  table: TableData
+  command: DeleteCommand
+
+  constructor(connection: Connection, table: TableData) {
+    this.connection = connection
+    this.table = table
+    this.command = { table: table.name }
+  }
+
+  async execute(): Promise<any> {
+    const result = await this.connection.query(generateDelete(this.command))
+    return this.command.returning ? Mappings.results(this.table, result) : result
+  }
+
+  returning(all: "*"): Delete<any, any[]>
+  returning(columns: string[]): Delete<any, Pick<any, any>[]>
+  returning(columns: any): Delete<any, any[]> | Delete<any, Pick<any, any>[]> {
+    this.command.returning = columns === "*" ? ["*"] : columns
+    return this
+  }
+
+  where(column: string, value: any): this
+  where(column: string, operator: UnaryOperator): this
+  where(column: string, operator: BinaryOperator, value: any): this
+  where(column: any, operator: any, value?: any): this {
+    addWhereClause(column, this.table, this.command, operator, value)
+    return this
+  }
+}

package/src/queryBuilder/InsertBuilder.ts

@@ -0,0 +1,31 @@
+// oxlint-disable typescript/no-explicit-any
+import type { Connection, Insert } from "../api"
+import type { TableData } from "../schemaBuilder"
+import type { InsertCommand } from "./queryBuilders.types"
+import { generateInsert } from "../queryGenerator"
+import { Mappings } from "./Mappings"
+
+/** Constructs declarative `INSERT` statements. */
+export class InsertBuilder implements Insert<any, any, any> {
+  readonly connection: Connection
+  readonly table: TableData
+  readonly command: InsertCommand
+
+  constructor(connection: Connection, table: TableData, columns: string[], rows: Record<string, unknown>[]) {
+    this.connection = connection
+    this.table = table
+    this.command = { table: table.name, columns, rows: rows.map((r) => Mappings.row(table, r)) }
+  }
+
+  async execute(): Promise<any> {
+    const result = await this.connection.query(generateInsert(this.command))
+    return this.command.returning ? Mappings.results(this.table, result) : result
+  }
+
+  returning(all: "*"): Insert<any, any, any[]>
+  returning(...columns: string[]): Insert<any, any, any[]>
+  returning(...columns: ("*" | string)[]) {
+    this.command.returning = columns[0] === "*" ? ["*"] : columns
+    return this
+  }
+}

package/src/queryBuilder/Mappings.ts

@@ -0,0 +1,55 @@
+import type { MappingData, TableData } from "../schemaBuilder"
+
+export namespace Mappings {
+  export function row(
+    table: TableData,
+    row: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const mapped: Record<string, unknown> = {}
+    for (const key in row) {
+      const column = findColumn(table, key)
+      mapped[key] = column?.mapping ? column.mapping.to(row[key]) : row[key]
+    }
+    return mapped
+  }
+
+  export function conditionValue(
+    table: TableData,
+    column: string,
+    value: unknown,
+  ): unknown {
+    const col = findColumn(table, column)
+    return col?.mapping ? col.mapping.to(value) : value
+  }
+
+  export function results(
+    tables: TableData | TableData[],
+    rows: Record<string, unknown>[],
+  ): Record<string, unknown>[] {
+    const tableList = Array.isArray(tables) ? tables : [tables]
+    const mappings = new Map<string, MappingData>()
+    for (const table of tableList) {
+      for (const col of table.columns) {
+        if (col.mapping && !mappings.has(col.name)) {
+          mappings.set(col.name, col.mapping)
+        }
+      }
+    }
+    if (mappings.size === 0) {
+      return rows
+    }
+    return rows.map((row) => {
+      const mapped: Record<string, unknown> = { ...row }
+      for (const [name, mapping] of mappings) {
+        if (name in mapped) {
+          mapped[name] = mapping.from(mapped[name])
+        }
+      }
+      return mapped
+    })
+  }
+}
+
+function findColumn(table: TableData, name: string) {
+  return table.columns.find((c) => c.name === name)
+}

package/src/queryBuilder/SelectBuilder.ts

@@ -0,0 +1,39 @@
+// oxlint-disable typescript/no-explicit-any
+import type { Connection, Select } from "../api"
+import type { TableData } from "../schemaBuilder"
+import { generateSelect } from "../queryGenerator"
+import { Mappings } from "./Mappings"
+import { SelectQueryBuilder } from "./SelectQueryBuilder"
+
+/** Constructs declarative `SELECT` statements with connection-based execution. */
+export class SelectBuilder extends SelectQueryBuilder implements Select<any, any> {
+  readonly connection: Connection
+
+  constructor(
+    connection: Connection,
+    table: TableData,
+    columns: "*" | string[],
+  ) {
+    super(table, columns)
+    this.connection = connection
+  }
+
+  async fetch(): Promise<any[]> {
+    const rows = await this.connection.query(generateSelect(this.query))
+    const tables = [
+      this.table,
+      ...(this.query.joins?.map((j) => j.target.tableData) ?? []),
+    ]
+    return Mappings.results(tables, rows)
+  }
+
+  async first(): Promise<any> {
+    const results = await this.fetch()
+    if (results[0] === undefined) {
+      throw new Error(
+        `Query did not return a result (table: "${this.table.name}").`,
+      )
+    }
+    return results[0]
+  }
+}

package/src/queryBuilder/SelectQueryBuilder.ts

@@ -0,0 +1,93 @@
+// oxlint-disable typescript/no-explicit-any
+import type { BinaryOperator, Select, UnaryOperator } from "../api"
+import type { BuildTable, ColumnRef, TableData } from "../schemaBuilder"
+import { addWhereClause } from "./addWhereClause"
+import type { JoinTarget, JoinType, SelectQuery } from "./queryBuilders.types"
+
+/** Base query builder for constructing declarative `SELECT` statements without a connection. */
+export class SelectQueryBuilder {
+  readonly table: TableData
+  readonly query: SelectQuery
+
+  constructor(table: TableData, columns: "*" | string[]) {
+    this.table = table
+    this.query = { table: table.name }
+    if (Array.isArray(columns)) {
+      this.query.selected = columns
+    }
+  }
+
+  limit(n: number) {
+    this.query.limit = n
+    return this
+  }
+
+  offset(n: number) {
+    this.query.offset = n
+    return this
+  }
+
+  where(column: string, value: any): this
+  where(column: string, operator: UnaryOperator): this
+  where(column: string, operator: BinaryOperator, value: any): this
+  where(column: string, operator: any, value?: any) {
+    addWhereClause(column, this.table, this.query, operator, value)
+    return this
+  }
+
+  orderBy(sorts: [string, "asc" | "desc"][]): this {
+    this.query.orderBy = sorts.map(([column, direction]) => ({
+      column,
+      direction,
+    }))
+    return this
+  }
+
+  private addJoin(type: JoinType, target: JoinTarget): this {
+    if (!this.query.joins) {
+      this.query.joins = []
+    }
+    this.query.joins.push({ type, target, on: [] })
+    return this
+  }
+
+  join(target: BuildTable<any> | Select<any, any>): this {
+    return this.addJoin("join", resolveTarget(target))
+  }
+
+  leftJoin(target: BuildTable<any> | Select<any, any>): this {
+    return this.addJoin("left join", resolveTarget(target))
+  }
+
+  rightJoin(target: BuildTable<any> | Select<any, any>): this {
+    return this.addJoin("right join", resolveTarget(target))
+  }
+
+  crossJoin(target: BuildTable<any> | Select<any, any>): this {
+    return this.addJoin("cross join", resolveTarget(target))
+  }
+
+  on(left: ColumnRef, operator: BinaryOperator, right: ColumnRef): this {
+    const joins = this.query.joins
+    if (!joins?.length) {
+      throw new Error("on() called without a preceding join")
+    }
+    joins[joins.length - 1].on.push({ left, operator, right })
+    return this
+  }
+}
+
+export function resolveTarget(
+  target: BuildTable<any> | Select<any, any>,
+): JoinTarget {
+  if ("$meta" in target) {
+    return { kind: "table", name: target.$meta.name, tableData: target.$meta }
+  }
+  const builder = target as unknown as SelectQueryBuilder
+  return {
+    kind: "subquery",
+    table: builder.query.table,
+    query: { ...builder.query },
+    tableData: builder.table,
+  }
+}

package/src/queryBuilder/UpdateBuilder.ts

@@ -0,0 +1,44 @@
+// oxlint-disable typescript/no-explicit-any
+import type { BinaryOperator, Connection, UnaryOperator, Update } from "../api"
+import { generateUpdate } from "../queryGenerator"
+import type { TableData } from "../schemaBuilder"
+import { addWhereClause } from "./addWhereClause"
+import { Mappings } from "./Mappings"
+import type { UpdateCommand } from "./queryBuilders.types"
+
+/** Constructs declarative `UPDATE` statements. */
+export class UpdateBuilder implements Update<any, any> {
+  readonly connection: Connection
+  readonly table: TableData
+  readonly command: UpdateCommand
+
+  constructor(
+    connection: Connection,
+    table: TableData,
+    row: Record<string, unknown>,
+  ) {
+    this.connection = connection
+    this.table = table
+    this.command = { table: table.name, assignments: Mappings.row(table, row) }
+  }
+
+  async execute(): Promise<any> {
+    const result = await this.connection.query(generateUpdate(this.command))
+    return this.command.returning ? Mappings.results(this.table, result) : result
+  }
+
+  returning(all: "*"): Update<any, any[]>
+  returning(columns: string[]): Update<any, Pick<any, any>[]>
+  returning(columns: any): Update<any, any[]> | Update<any, Pick<any, any>[]> {
+    this.command.returning = columns === "*" ? ["*"] : columns
+    return this
+  }
+
+  where(column: string, value: any): this
+  where(column: string, operator: UnaryOperator): this
+  where(column: string, operator: BinaryOperator, value: any): this
+  where(column: any, operator: any, value?: any): this {
+    addWhereClause(column, this.table, this.command, operator, value)
+    return this
+  }
+}

package/src/queryBuilder/addWhereClause.ts

@@ -0,0 +1,35 @@
+// oxlint-disable typescript/no-explicit-any
+import type { TableData } from "../schemaBuilder"
+import type { Condition } from "./queryBuilders.types"
+import { Mappings } from "./Mappings"
+import { isBinaryOperator, isUnaryOperator } from "./operators"
+
+/** Constructs `WHERE` clauses. */
+export function addWhereClause(
+  column: string,
+  table: TableData,
+  query: { conditions?: Condition[] },
+  operator: any,
+  value?: any,
+) {
+  if (query.conditions === undefined) {
+    query.conditions = []
+  }
+  if (value !== undefined && isBinaryOperator(operator)) {
+    query.conditions.push({
+      column,
+      arity: 2,
+      operator,
+      value: Mappings.conditionValue(table, column, value),
+    })
+  } else if (isUnaryOperator(operator)) {
+    query.conditions.push({ column, arity: 1, operator })
+  } else {
+    query.conditions.push({
+      column,
+      arity: 2,
+      operator: "=",
+      value: Mappings.conditionValue(table, column, operator),
+    })
+  }
+}

package/src/queryBuilder/index.ts

@@ -0,0 +1,7 @@
+export * from "./queryBuilders.types"
+export * from "./operators"
+export * from "./SelectQueryBuilder"
+export * from "./SelectBuilder"
+export * from "./InsertBuilder"
+export * from "./UpdateBuilder"
+export * from "./DeleteBuilder"

package/src/queryBuilder/operators.ts

@@ -0,0 +1,35 @@
+// oxlint-disable typescript/no-explicit-any
+
+export const UNARY_OPERATORS = [
+  "is null",
+  "is not null",
+] as const
+
+export const BINARY_OPERATORS = [
+  "=",
+  "!=",
+  ">",
+  "<",
+  ">=",
+  "<=",
+  "like",
+  "not like",
+  "glob",
+  "not glob",
+  "match",
+  "not match",
+  "regexp",
+  "not regexp",
+  "in",
+  "not in",
+  "is",
+  "is not",
+] as const
+
+export function isUnaryOperator(o: string) {
+  return UNARY_OPERATORS.includes(o as any)
+}
+
+export function isBinaryOperator(o: string) {
+  return BINARY_OPERATORS.includes(o as any)
+}

package/src/queryBuilder/queryBuilders.types.ts

@@ -0,0 +1,105 @@
+// oxlint-disable typescript/consistent-type-definitions -- review
+import type { BinaryOperator, UnaryOperator } from "../api/api.types"
+import type { ColumnRef, TableData } from "../schemaBuilder"
+
+/** Represents a select query. */
+export interface SelectQuery {
+  /** Table this query is performed on. */
+  table: string
+  /** Limit clause. */
+  limit?: number
+  /** Offset clause. */
+  offset?: number
+  /** Conditions of the SELECT. */
+  conditions?: Condition[]
+  /** Which columns are being selected in this query. */
+  selected?: string[]
+  /** Order By clause */
+  orderBy?: OrderBySort[]
+  /** Join clauses. */
+  joins?: JoinClause[]
+}
+
+export type JoinType = "join" | "left join" | "right join" | "cross join"
+
+export type JoinTarget =
+  | { kind: "table"; name: string; tableData: TableData }
+  | {
+      kind: "subquery"
+      table: string
+      query: SelectQuery
+      tableData: TableData
+    }
+
+export interface JoinClause {
+  /** The type of join. */
+  type: JoinType
+  /** The target being joined — a table or a subquery. */
+  target: JoinTarget
+  /** Join conditions (ON clause). */
+  on: JoinOn[]
+}
+
+export interface JoinOn {
+  /** Left side of the ON condition. */
+  left: ColumnRef
+  /** The comparison operator. */
+  operator: BinaryOperator
+  /** Right side of the ON condition. */
+  right: ColumnRef
+}
+
+/** Represents an update command. */
+export interface UpdateCommand {
+  /** Table being UPDATEd. */
+  table: string
+  /** Column-value assignments. */
+  assignments: Record<string, unknown>
+  /** Conditions of the UPDATE. */
+  conditions?: Condition[]
+  /** Returning clause. */
+  returning?: string[]
+}
+
+/** Represents an insert command. */
+export interface InsertCommand {
+  /** Table being INSERTed to. */
+  table: string
+  /** Column names. */
+  columns: string[]
+  /** Row values to insert. */
+  rows: Record<string, unknown>[]
+  /** Returning clause. */
+  returning?: string[]
+}
+
+/** Represents a delete command. */
+export interface DeleteCommand {
+  table: string
+  conditions?: Condition[]
+  returning?: string[]
+}
+
+export interface OrderBySort {
+  column: string
+  direction: "asc" | "desc"
+}
+
+/* Represents a condition. */
+export type Condition = UnaryCondition | BinaryCondition
+
+/** A unary condition. */
+export interface UnaryCondition {
+  column: string
+  arity: 1
+  operator: UnaryOperator
+}
+
+/** A binary condition. */
+export interface BinaryCondition {
+  column: string
+  arity: 2
+  operator: BinaryOperator
+  // oxlint-disable-next-line typescript/no-explicit-any
+  value: any
+}

package/src/queryGenerator/Clause.ts

@@ -0,0 +1,79 @@
+import { indent, join, newline, type Node } from "@sigitex/print"
+import { Format } from "../framework"
+import type { Condition, JoinClause, JoinTarget } from "../queryBuilder"
+import type { ColumnRef } from "../schemaBuilder"
+import { generateSelectNode } from "./generateSelect"
+
+export namespace Clause {
+  export function where(conditions: Condition[], baseTable?: string): Node[] {
+    return [
+      "where ",
+      indent(
+        conditions.map((condition, index) => [
+          index > 0 && " and ",
+          baseTable
+            ? qualifyColumn(baseTable, condition.column)
+            : Format.name(condition.column),
+          " ",
+          condition.operator,
+          condition.arity === 2 && [" ", Format.value(condition.value)],
+          newline,
+        ]),
+      ),
+    ]
+  }
+
+  export function returning(columns: string[]): Node {
+    if (columns.length === 1 && columns[0] === "*") {
+      return ["returning *", newline]
+    }
+    return ["returning ", join(", ", columns, Format.name), newline]
+  }
+
+  export function joins(
+    clauses: JoinClause[],
+    aliasMap: Map<JoinClause, string>,
+  ): Node {
+    return clauses.map((clause) => {
+      const { type, on } = clause
+      const alias = aliasMap.get(clause)!
+      return [
+        type,
+        " ",
+        formatTarget(clause.target, alias),
+        newline,
+        on.length > 0 &&
+          indent(
+            on.map(({ left, operator, right }, index) => [
+              index === 0 ? "on " : "and ",
+              formatRef(left),
+              ` ${operator} `,
+              formatRef(right),
+              newline,
+            ]),
+          ),
+      ]
+    })
+  }
+}
+
+function formatTarget(target: JoinTarget, alias: string): Node {
+  if (target.kind === "table") {
+    return Format.name(target.name)
+  }
+  return [
+    "(",
+    newline,
+    indent([generateSelectNode(target.query)]),
+    ") as ",
+    Format.name(alias),
+  ]
+}
+
+function formatRef(ref: ColumnRef): string {
+  return `${Format.name(ref.table)}.${Format.name(ref.column)}`
+}
+
+function qualifyColumn(baseTable: string, column: string): string {
+  return `${Format.name(baseTable)}.${Format.name(column)}`
+}

package/src/queryGenerator/generateDelete.ts

@@ -0,0 +1,18 @@
+import { newline, print } from "@sigitex/print"
+import { Format } from "../framework"
+import type { DeleteCommand } from "../queryBuilder"
+import { Clause } from "./Clause"
+
+export function generateDelete({
+  table,
+  conditions,
+  returning,
+}: DeleteCommand) {
+  return print([
+    "delete from ",
+    Format.name(table),
+    newline,
+    conditions?.length && Clause.where(conditions),
+    returning && Clause.returning(returning),
+  ])
+}