@sigitex/outlaw 1.0.1 → 2.0.0

package/src/api/api.types.ts

@@ -1,15 +1,14 @@
-// oxlint-disable typescript/consistent-type-definitions
 // oxlint-disable typescript/no-explicit-any
+// oxlint-disable typescript/method-signature-style
+// oxlint-disable typescript/consistent-type-definitions
 import type { BINARY_OPERATORS, UNARY_OPERATORS } from "../queryBuilder"
 import type {
-  BuildColumn,
-  BuildTable,
-  BuildView,
-  ColumnRef,
+  InferColumn,
   SchemaMembers,
   TablesOf,
   ViewsOf,
 } from "../schemaBuilder"
+import type { QueryScope } from "../queryBuilder/QueryScope"
 
 // Utilities
 
@@ -26,59 +25,82 @@ export type InsertRecord<R> = Partial<R> &
 
 // Deconstruction
 
-export type ColumnsOf<BT> =
-  BT extends BuildTable<infer Columns> ? Columns : never
-
-export type ColumnTypeOf<BC> =
-  BC extends BuildColumn<infer Type, infer Constraints>
-    ? Constraints extends "notNull" | "primaryKey"
-      ? Type
-      : Type | null
-    : never
+export type ColumnsOf<BT> = BT extends { readonly $columns: infer Columns }
+  ? Columns
+  : never
 
 export type ColumnTypesOf<BCS> = {
-  readonly [BCK in keyof BCS]: ColumnTypeOf<BCS[BCK]>
+  readonly [BCK in keyof BCS]: InferColumn<BCS[BCK]>
 }
 
 // API
 
 export type DefaultRow = Record<string, unknown>
 
-export type Connection = {
+export type ConnectionOperations = {
   readonly query: <Row = DefaultRow>(sql: string) => Promise<Row[]>
   readonly script: (statements: string[]) => Promise<void>
-  readonly reset?: () => Promise<void>
 }
 
-export type DatabaseApi<M extends SchemaMembers> = {
-  readonly [K in keyof TablesOf<M>]: TableApi<ColumnsOf<TablesOf<M>[K]>>
-} & {
-  readonly [K in keyof ViewsOf<M>]: ViewApi<ColumnsOfView<ViewsOf<M>[K]>>
-} & {
-  readonly connection: Connection
+export type TransactionWork<Result> = (
+  connection: TransactionalConnection,
+) => Promise<Result>
+
+export type Transaction = <Result>(
+  work: TransactionWork<Result>,
+) => Promise<Result>
+
+export type TransactionalConnection = ConnectionOperations & {
+  readonly transaction: Transaction
 }
 
-export type ColumnsOfView<BV> = BV extends BuildView<infer Columns> ? Columns : never
+export type Connection = ConnectionOperations & {
+  readonly reset?: () => Promise<void>
+  readonly transaction?: Transaction
+}
 
-export type ViewApi<Columns> = {
-  /** Issue a `SELECT *` query to the API. */
-  select(all: "*"): Select<Columns, Columns>
-  /** Issue a `SELECT` query to the API with the chosen columns. */
-  select<Column extends keyof Columns>(
-    ...columns: Column[]
-  ): Select<Pick<Columns, Column>, Columns>
+export type DatabaseApi<
+  M extends SchemaMembers,
+  C extends Connection = Connection,
+> = {
+  readonly [K in keyof TablesOf<M>]: TableApi<
+    ColumnsOf<TablesOf<M>[K]>,
+    QueryScope.Of<TablesOf<M>[K]>["name"]
+  >
+} & {
+  readonly [K in keyof ViewsOf<M>]: ViewApi<
+    QueryScope.Of<ViewsOf<M>[K]>["columns"],
+    QueryScope.Of<ViewsOf<M>[K]>["name"]
+  >
+} & {
+  readonly connection: C
+  readonly transaction: <Result>(
+    work: (
+      database: DatabaseApi<M, TransactionalConnection>,
+    ) => Promise<Result>,
+  ) => Promise<Result>
 }
 
-export type TableApi<Columns> = {
-  /** Issue a `SELECT *` query to the API. */
-  select(all: "*"): Select<Columns, Columns>
-  /** Issue a `SELECT` query to the API with the chosen columns. */
-  select<Column extends keyof Columns>(
-    ...columns: Column[]
-  ): Select<Pick<Columns, Column>, Columns>
+export type ColumnsOfView<BV> = QueryScope.Of<BV>["columns"]
+
+export type ViewApi<
+  Columns extends QueryScope.Columns,
+  Name extends string = string,
+> = QueryScope.Composition<
+  QueryScope.Initial<QueryScope.State<Name, Columns>>,
+  true
+>
+
+export type TableApi<
+  Columns,
+  Name extends string = string,
+> = QueryScope.Composition<
+  QueryScope.Initial<QueryScope.State<Name, QueryScope.SchemaColumns<Columns>>>,
+  true
+> & {
   /** Issue an `INSERT` statement. */
   insert<InsertColumns extends Partial<ColumnTypesOf<Columns>>>(
-    ...rows: InsertColumns[]
+    ...rows: [InsertColumns, ...InsertColumns[]]
   ): Insert<InsertColumns, Columns, number>
   /** Issue an `UPDATE` statement. */
   update(row: Partial<ColumnTypesOf<Columns>>): Update<Columns, number>
@@ -91,7 +113,7 @@ export interface HasWhereClause<Columns> {
   /** Add a condition where the given column equals the given value. */
   where<Column extends keyof Columns>(
     column: Column,
-    value: Columns[Column],
+    value: InferColumn<Columns[Column]>,
   ): this
   /** Add a unary `WHERE` condition. */
   where<Column extends keyof Columns>(
@@ -102,63 +124,14 @@ export interface HasWhereClause<Columns> {
   where<Column extends keyof Columns>(
     column: Column,
     operator: BinaryOperator,
-    value: ColumnTypeOf<Columns[Column]>,
+    value: InferColumn<Columns[Column]>,
   ): this
 }
 
-/** Select query API. */
-export interface Select<SelectColumns, Columns>
-  extends HasWhereClause<Columns> {
-  /** Issue the query, expecting an array of results. */
-  fetch(): Promise<ColumnTypesOf<SelectColumns>[]>
-  /** Issue the query, returning a single result, or throwing.. */
-  first(): Promise<ColumnTypesOf<SelectColumns>>
-  /** Add a `LIMIT` clause. */
-  limit(n: number): this
-  /** Add an `OFFSET` clause. */
-  offset(n: number): this
-  /** Add an `ORDER BY` sort expression. */
-  orderBy(sorts: [keyof Columns, "asc" | "desc"][]): this
-
-  /** Inner join on a table. */
-  join<JC>(
-    table: BuildTable<JC>,
-  ): Select<SelectColumns & ColumnTypesOf<JC>, Columns & JC>
-  /** Inner join on a subquery. */
-  join<SC>(
-    query: Select<SC, any>,
-  ): Select<SelectColumns & ColumnTypesOf<SC>, Columns & SC>
-
-  /** Left join on a table — joined columns become nullable. */
-  leftJoin<JC>(
-    table: BuildTable<JC>,
-  ): Select<SelectColumns & Partial<ColumnTypesOf<JC>>, Columns & JC>
-  /** Left join on a subquery — joined columns become nullable. */
-  leftJoin<SC>(
-    query: Select<SC, any>,
-  ): Select<SelectColumns & Partial<ColumnTypesOf<SC>>, Columns & SC>
-
-  /** Right join on a table. */
-  rightJoin<JC>(
-    table: BuildTable<JC>,
-  ): Select<SelectColumns & ColumnTypesOf<JC>, Columns & JC>
-  /** Right join on a subquery. */
-  rightJoin<SC>(
-    query: Select<SC, any>,
-  ): Select<SelectColumns & ColumnTypesOf<SC>, Columns & SC>
-
-  /** Cross join on a table. */
-  crossJoin<JC>(
-    table: BuildTable<JC>,
-  ): Select<SelectColumns & ColumnTypesOf<JC>, Columns & JC>
-  /** Cross join on a subquery. */
-  crossJoin<SC>(
-    query: Select<SC, any>,
-  ): Select<SelectColumns & ColumnTypesOf<SC>, Columns & SC>
-
-  /** Add an ON condition to the most recent join. */
-  on(left: ColumnRef, operator: BinaryOperator, right: ColumnRef): this
-}
+export type Select<
+  SelectColumns extends QueryScope.Columns,
+  Scope extends QueryScope,
+> = QueryScope.Selection<SelectColumns, Scope, true>
 
 /** Insert statement API. */
 export interface Insert<InsertColumns, Columns, Returning> {
@@ -177,11 +150,11 @@ export interface Update<Columns, Returning> extends HasWhereClause<Columns> {
   /** Execute the statement. */
   execute(): Promise<Returning>
   /** Specify a `RETURNING *` clause. */
-  returning(all: "*"): Update<Columns, Columns[]>
+  returning(all: "*"): Update<Columns, ColumnTypesOf<Columns>[]>
   /** Specify a `RETURNING` clause with the chosen columns. */
   returning<Column extends keyof Columns>(
-    columns: Column[],
-  ): Update<Columns, Pick<Columns, Column>[]>
+    ...columns: Column[]
+  ): Update<Columns, ColumnTypesOf<Pick<Columns, Column>>[]>
 }
 
 /** Delete statement API. */
@@ -189,11 +162,11 @@ export interface Delete<Columns, Returning> extends HasWhereClause<Columns> {
   /** Execute the statement. */
   execute(): Promise<Returning>
   /** Specify a `RETURNING *` clause. */
-  returning(all: "*"): Delete<Columns, Columns[]>
+  returning(all: "*"): Delete<Columns, ColumnTypesOf<Columns>[]>
   /** Specify a `RETURNING` clause with the chosen columns. */
   returning<Column extends keyof Columns>(
-    columns: Column[],
-  ): Delete<Columns, Pick<Columns, Column>[]>
+    ...columns: Column[]
+  ): Delete<Columns, ColumnTypesOf<Pick<Columns, Column>>[]>
 }
 
 export type UnaryOperator = ElementOf<typeof UNARY_OPERATORS>

package/src/api/createDatabase.ts

@@ -1,13 +1,38 @@
-import type { BuildTable, BuildView, SchemaMembers, Schema } from "../schemaBuilder"
-import type { Connection, DatabaseApi } from "./api.types"
+import type {
+  BuildTable,
+  BuildView,
+  SchemaMembers,
+  Schema,
+} from "../schemaBuilder"
+import type {
+  Connection,
+  DatabaseApi,
+  TransactionalConnection,
+} from "./api.types"
 import { DatabaseTable } from "./DatabaseTable"
 import { DatabaseView } from "./DatabaseView"
+import { UnsupportedTransactionError } from "./UnsupportedTransactionError"
 
-export function createDatabase<M extends SchemaMembers>(
-  connection: Connection,
+export function createDatabase<M extends SchemaMembers, C extends Connection>(
+  connection: C,
   schema: Schema<M>,
 ) {
-  const api = { connection }
+  const api = {
+    connection,
+    transaction: async <Result>(
+      work: (
+        database: DatabaseApi<M, TransactionalConnection>,
+      ) => Promise<Result>,
+    ) => {
+      const transaction = connection.transaction
+      if (!transaction) {
+        throw new UnsupportedTransactionError()
+      }
+      return transaction((scopedConnection) =>
+        work(createDatabase(scopedConnection, schema)),
+      )
+    },
+  }
   for (const [property, member] of Object.entries(schema.tables)) {
     const table = member as BuildTable<unknown>
     Object.defineProperty(api, property, {
@@ -20,5 +45,5 @@ export function createDatabase<M extends SchemaMembers>(
       value: new DatabaseView(connection, view.$tableData),
     })
   }
-  return api as DatabaseApi<M>
+  return api as DatabaseApi<M, C>
 }

package/src/api/index.ts

@@ -2,3 +2,4 @@ export * from "./api.types"
 export * from "./DatabaseTable"
 export * from "./DatabaseView"
 export * from "./createDatabase"
+export * from "./UnsupportedTransactionError"

package/src/bun/bun.ts

@@ -1,27 +1,140 @@
 import type { Database } from "bun:sqlite"
-import type { DefaultRow, Connection } from "../api/api.types"
+import type {
+  Connection,
+  DefaultRow,
+  TransactionalConnection,
+  TransactionWork,
+} from "../api/api.types"
+
+type TransactionState = {
+  active: boolean
+  nextSavepoint: number
+}
 
 export class BunConnection implements Connection {
   private readonly db: Database
+  private pending = Promise.resolve()
 
   constructor(db: Database) {
     this.db = db
   }
 
   async query<Row = DefaultRow>(sql: string) {
-    return this.db.query(sql).all() as Row[]
+    return this.exclusive(() => query<Row>(this.db, sql))
   }
 
   async script(statements: string[]) {
-    this.db.run("BEGIN")
+    await this.exclusive(() => script(this.db, statements, "BEGIN"))
+  }
+
+  async transaction<Result>(work: TransactionWork<Result>) {
+    return this.exclusive(async () => {
+      await run(this.db, "BEGIN IMMEDIATE")
+      const state: TransactionState = { active: true, nextSavepoint: 0 }
+      const connection = new BunTransactionConnection(this.db, state)
+
+      try {
+        const result = await work(connection)
+        connection.close()
+        await run(this.db, "COMMIT")
+        return result
+      } catch (error) {
+        connection.close()
+        await run(this.db, "ROLLBACK")
+        throw error
+      } finally {
+        state.active = false
+      }
+    })
+  }
+
+  private async exclusive<Result>(work: () => Promise<Result>) {
+    const previous = this.pending
+    let release!: () => void
+    this.pending = new Promise<void>((resolve) => {
+      release = resolve
+    })
+
+    await previous
     try {
-      for (const s of statements) {
-        this.db.run(s)
+      return await work()
+    } finally {
+      release()
+    }
+  }
+}
+
+class BunTransactionConnection implements TransactionalConnection {
+  private readonly db: Database
+  private readonly state: TransactionState
+  private active = true
+
+  constructor(db: Database, state: TransactionState) {
+    this.db = db
+    this.state = state
+  }
+
+  async query<Row = DefaultRow>(sql: string) {
+    this.assertActive()
+    return query<Row>(this.db, sql)
+  }
+
+  async script(statements: string[]) {
+    this.assertActive()
+    await this.transaction(async (connection) => {
+      for (const statement of statements) {
+        await connection.query(statement)
       }
-      this.db.run("COMMIT")
+    })
+  }
+
+  async transaction<Result>(work: TransactionWork<Result>) {
+    this.assertActive()
+    const name = `outlaw_transaction_${++this.state.nextSavepoint}`
+    await run(this.db, `SAVEPOINT ${name}`)
+    const connection = new BunTransactionConnection(this.db, this.state)
+
+    try {
+      const result = await work(connection)
+      connection.close()
+      await run(this.db, `RELEASE SAVEPOINT ${name}`)
+      return result
     } catch (error) {
-      this.db.run("ROLLBACK")
+      connection.close()
+      await run(this.db, `ROLLBACK TO SAVEPOINT ${name}`)
+      await run(this.db, `RELEASE SAVEPOINT ${name}`)
       throw error
     }
   }
+
+  close() {
+    this.active = false
+  }
+
+  private assertActive() {
+    if (!this.active || !this.state.active) {
+      throw new Error("Transaction connection is no longer active.")
+    }
+  }
+}
+
+async function query<Row>(db: Database, sql: string) {
+  return db.query(sql).all() as Row[]
+}
+
+async function run(db: Database, sql: string) {
+  db.run(sql)
+}
+
+async function script(db: Database, statements: string[], begin: "BEGIN") {
+  await run(db, begin)
+  try {
+    for (const statement of statements) {
+      await run(db, statement)
+    }
+    await run(db, "COMMIT")
+  } catch (error) {
+    await run(db, "ROLLBACK")
+    throw error
+  }
 }

package/src/cowboyMigration/CowboyConnection.ts

@@ -1,5 +1,5 @@
 import type { Fixtures, Schema, SchemaMembers, Seeds } from "../schemaBuilder"
-import type { Connection, DefaultRow } from "../api"
+import type { Connection, DefaultRow, Transaction } from "../api"
 import type { SchemaHack } from "./cowboyMigration.types"
 import { CowboyMigrator } from "./CowboyMigrator"
 import { CowboySeeder } from "./CowboySeeder"
@@ -15,36 +15,68 @@ export class CowboyConnection implements Connection {
   private readonly raw: Connection
   private readonly schema: Schema<SchemaMembers>
   private readonly options: CowboyOptions
-  private shotFirst = false
+  private readiness?: Promise<void>
+  readonly transaction?: Transaction
 
-  constructor(raw: Connection, schema: Schema<SchemaMembers>, options?: CowboyOptions) {
+  constructor(
+    raw: Connection,
+    schema: Schema<SchemaMembers>,
+    options?: CowboyOptions,
+  ) {
     this.raw = raw
     this.schema = schema
     this.options = options ?? {}
+    const transaction = raw.transaction?.bind(raw)
+    if (transaction) {
+      this.transaction = async (work) => {
+        await this.ready()
+        return transaction(work)
+      }
+    }
   }
 
   async query<Row = DefaultRow>(sql: string) {
-    if (!this.shotFirst) {
-      await this.shotgun()
-    }
+    await this.ready()
     return this.raw.query(sql) as Promise<Row[]>
   }
 
   async script(statements: string[]) {
-    if (!this.shotFirst) {
-      await this.shotgun()
-    }
+    await this.ready()
     await this.raw.script(statements)
   }
 
   async reset() {
-    this.shotFirst = false
+    try {
+      await this.readiness
+    } catch {
+      // A failed initialization is already reset by ready().
+    }
+    this.readiness = undefined
+  }
+
+  private ready() {
+    if (this.readiness) {
+      return this.readiness
+    }
+
+    const readiness = this.shotgun().catch((error: unknown) => {
+      if (this.readiness === readiness) {
+        this.readiness = undefined
+      }
+      throw error
+    })
+    this.readiness = readiness
+    return readiness
   }
 
   private async shotgun() {
-    this.shotFirst = true
-    await new CowboyMigrator(this.raw, this.schema, this.options.hacks ?? []).migrate()
-    const hasSeeds = this.options.seeds || (this.options.runFixtures && this.options.fixtures)
+    await new CowboyMigrator(
+      this.raw,
+      this.schema,
+      this.options.hacks ?? [],
+    ).migrate()
+    const hasSeeds =
+      this.options.seeds || (this.options.runFixtures && this.options.fixtures)
     if (hasSeeds) {
       await new CowboySeeder(
         this.raw,

package/src/framework/Format.ts

@@ -11,6 +11,10 @@ export namespace Format {
     return SqlString.escapeId(name)
   }
 
+  export function identifier(name: string) {
+    return SqlString.escapeId(name, true)
+  }
+
   export function number(number: number) {
     if (typeof number !== "number" && typeof number !== "bigint") {
       throw new Error("Not a number.")

package/src/framework/definitions.d.ts

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

package/src/queryBuilder/DeleteBuilder.ts

@@ -20,13 +20,15 @@ export class DeleteBuilder implements Delete<any, any> {
 
   async execute(): Promise<any> {
     const result = await this.connection.query(generateDelete(this.command))
-    return this.command.returning ? Mappings.results(this.table, result) : result
+    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
+  returning(...columns: string[]): Delete<any, Pick<any, any>[]>
+  returning(...columns: ("*" | string)[]): Delete<any, any[]> {
+    this.command.returning = columns[0] === "*" ? ["*"] : columns
     return this
   }
 

package/src/queryBuilder/Mappings.ts

@@ -41,7 +41,7 @@ export namespace Mappings {
     return rows.map((row) => {
       const mapped: Record<string, unknown> = { ...row }
       for (const [name, mapping] of mappings) {
-        if (name in mapped) {
+        if (name in mapped && mapped[name] !== null) {
           mapped[name] = mapping.from(mapped[name])
         }
       }

package/src/queryBuilder/Projection.ts

@@ -0,0 +1,83 @@
+import type { ColumnRef } from "../schemaBuilder/ColumnRef"
+import type { ColumnData } from "../schemaBuilder/metadata"
+import type { ColumnIdentifier, SelectQuery } from "./queryBuilders.types"
+import { QuerySource } from "./QuerySource"
+
+export type Projection =
+  | "*"
+  | { column: ColumnIdentifier; alias?: string }
+  | ColumnRef.Wildcard
+
+export namespace Projection {
+  export type Input =
+    | "*"
+    | string
+    | ColumnRef
+    | ColumnRef.Aliased<string, string, string>
+    | ColumnRef.Wildcard
+
+  export function create(scope: QuerySource.Scope, input: Input): Projection {
+    if (input === "*") {
+      return input
+    }
+    if (typeof input === "object" && "wildcard" in input) {
+      return { ...input }
+    }
+    const column = QuerySource.identifier(scope, input)
+    const alias =
+      typeof input === "object" && "alias" in input
+        ? input.alias
+        : column.table === undefined && scope.coalesced.has(column.column)
+          ? column.column
+          : undefined
+    return {
+      column,
+      ...(alias !== undefined ? { alias } : {}),
+    }
+  }
+
+  export function columns(query: SelectQuery): ColumnData[] {
+    const scope = QuerySource.scope(query)
+    const selected = query.selected.flatMap((projection) => {
+      if (projection === "*") {
+        return scope.output
+      }
+      if ("wildcard" in projection) {
+        return scope.sources
+          .filter(
+            (source) => QuerySource.qualifier(source) === projection.table,
+          )
+          .flatMap((source) => source.tableData.columns)
+      }
+      return QuerySource.resolve(scope, projection.column).map((column) =>
+        renameColumn(column, projection.alias ?? column.name),
+      )
+    })
+    const outputs = new Map<string, ColumnData[]>()
+    for (const column of selected) {
+      const existing = outputs.get(column.name)
+      if (existing) {
+        existing.push(column)
+      } else {
+        outputs.set(column.name, [column])
+      }
+    }
+    return Array.from(outputs.values(), merge)
+  }
+
+  export function merge(columns: ColumnData[]): ColumnData {
+    const first = columns[0]
+    return {
+      ...first,
+      notNull: columns.every((column) => column.notNull || !!column.primaryKey),
+      primaryKey: undefined,
+      mapping: columns.every((column) => column.mapping === first.mapping)
+        ? first.mapping
+        : undefined,
+    }
+  }
+
+  function renameColumn(column: ColumnData, name: string): ColumnData {
+    return { ...column, name }
+  }
+}