@sigitex/outlaw 1.0.1 → 1.2.0

package/README.md

@@ -8,7 +8,7 @@ bun add @sigitex/outlaw
 
 Attempts to mirror Sqlite syntax *very* closely. Currently works with Bun and Cloudflare Functions.
 
-Define your schema in code, and Outlaw's [cowboy migrations](#cowboy-migrations) automatically diff and converge your database on startup -- no migration files, no CLI steps. Just change your schema and go.
+Define your schema in code, and Outlaw's [cowboy migrations](#cowboy-migrations) automatically diff and converge your database on startup.
 
 > **Note:** This package exports TypeScript sources directly. A TypeScript-compatible runtime or bundler (Bun, etc.) is required.
 
@@ -155,6 +155,9 @@ Outlaw abstracts over any SQLite connection via the `Connection` interface:
 type Connection = {
   query<Row>(sql: string): Promise<Row[]>
   script(statements: string[]): Promise<void>
+  transaction?<Result>(
+    work: (connection: TransactionalConnection) => Promise<Result>,
+  ): Promise<Result>
 }
 ```
 
@@ -188,6 +191,25 @@ import { createDatabase } from "@sigitex/outlaw"
 const db = createDatabase(connection, schema)
 ```
 
+Every database API exposes `transaction`. Supported connections provide a fresh
+database API bound to the transaction-scoped connection:
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.users.insert({ name: "Wyatt" }).execute()
+
+  await tx.transaction(async (nested) => {
+    await nested.products.insert({ name: "Hat" }).execute()
+  })
+})
+```
+
+Use only the callback's scoped database API until that callback ends. Bun
+serializes root operations, uses `BEGIN IMMEDIATE`, and implements nested
+callbacks with savepoints. Cloudflare D1 does not support interactive callback
+transactions; `transaction` throws `UnsupportedTransactionError` before the
+callback runs, while `script()` remains available through D1 batch.
+
 ### Select
 
 ```ts

package/package.json

@@ -5,11 +5,11 @@
   "description": "A trigger-happy sqlite framework.",
   "author": {
     "name": "Sigitex",
-    "url": "http://github.com/sigitex"
+    "url": "https://sigitex.com"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/sigitex/outlaw.git"
+    "url": "git+https://github.com/sigitex/outlaw.git"
   },
   "exports": {
     ".": {
@@ -28,12 +28,12 @@
     "@semantic-release/exec": "^7.0.3",
     "@types/bun": "^1.3.13",
     "@types/fast-json-stable-stringify": "^2.1.2",
-    "@typescript/native-preview": "beta",
     "husky": "^9.1.7",
     "multi-semantic-release": "^3.1.0",
     "oxfmt": "^0.47.0",
     "oxlint": "^1.62.0",
-    "semantic-release": "^25.0.3"
+    "semantic-release": "^25.0.3",
+    "typescript": "^7.0.2"
   },
   "dependencies": {
     "@sigitex/print": "*",
@@ -43,11 +43,11 @@
   "scripts": {
     "prepare": "husky",
     "lint": "oxlint",
-    "check": "tsgo --build",
+    "check": "tsc --build",
     "test": "bun test --pass-with-no-tests --tsconfig-override tsconfig.test.json"
   },
   "files": [
     "src"
   ],
-  "version": "1.0.1"
+  "version": "1.2.0"
 }

package/src/api/DatabaseTable.ts

@@ -1,5 +1,12 @@
 // oxlint-disable typescript/no-explicit-any
-import type { Delete, Connection, Insert, Select, TableApi, Update } from "./api.types"
+import type {
+  Delete,
+  Connection,
+  Insert,
+  Select,
+  TableApi,
+  Update,
+} from "./api.types"
 import type { TableData } from "../schemaBuilder"
 import {
   DeleteBuilder,
@@ -18,27 +25,32 @@ export class DatabaseTable implements TableApi<any> {
   }
 
   select(all: "*"): Select<any, any>
-  select<Column extends string>(columns: Column[]): Select<Pick<any, any>, any>
-  select(
-    columns: "*" | string[],
-  ): Select<any, any> | Select<Pick<any, any>, any> {
-    return new SelectBuilder(this.connection, this.table, columns)
+  select<Column extends string>(
+    ...columns: Column[]
+  ): Select<Pick<any, any>, any>
+  select(...columns: ("*" | string)[]): Select<any, any> {
+    const selected = columns[0] === "*" || columns.length === 0 ? "*" : columns
+    return new SelectBuilder(this.connection, this.table, selected)
   }
 
-  insert(row: Partial<any>): Insert<any, any, number>
-  insert<Column extends string | number | symbol>(
-    columns: Column[],
-    rows: Pick<any, Column>[],
-  ): Insert<Column, any, number>
-  insert(
-    columnsOrRow: any,
-    rows?: any,
-  ): Insert<any, any, number> | Insert<any, any, number> {
-    if (rows) {
-      return new InsertBuilder(this.connection, this.table, columnsOrRow, rows)
+  insert(...rows: [Partial<any>, ...Partial<any>[]]): Insert<any, any, number>
+  insert(...rows: Record<string, unknown>[]): Insert<any, any, number> {
+    const first = rows[0]
+    if (!first) {
+      throw new Error("insert() requires at least one row")
     }
-    const row = columnsOrRow as Record<string, unknown>
-    return new InsertBuilder(this.connection, this.table, Object.keys(row), [row])
+    const columns = Object.keys(first)
+    const expected = new Set(columns)
+    for (const row of rows.slice(1)) {
+      const rowColumns = Object.keys(row)
+      if (
+        rowColumns.length !== columns.length ||
+        rowColumns.some((column) => !expected.has(column))
+      ) {
+        throw new Error("insert() rows must use the same columns")
+      }
+    }
+    return new InsertBuilder(this.connection, this.table, columns, rows)
   }
 
   update(row: Partial<any>): Update<any, number> {

package/src/api/DatabaseView.ts

@@ -13,10 +13,11 @@ export class DatabaseView implements ViewApi<any> {
   }
 
   select(all: "*"): Select<any, any>
-  select<Column extends string>(columns: Column[]): Select<Pick<any, any>, any>
-  select(
-    columns: "*" | string[],
-  ): Select<any, any> | Select<Pick<any, any>, any> {
-    return new SelectBuilder(this.connection, this.tableData, columns)
+  select<Column extends string>(
+    ...columns: Column[]
+  ): Select<Pick<any, any>, any>
+  select(...columns: ("*" | string)[]): Select<any, any> {
+    const selected = columns[0] === "*" || columns.length === 0 ? "*" : columns
+    return new SelectBuilder(this.connection, this.tableData, selected)
   }
 }

package/src/api/UnsupportedTransactionError.ts

@@ -0,0 +1,7 @@
+export class UnsupportedTransactionError extends Error {
+  override readonly name = "UnsupportedTransactionError"
+
+  constructor() {
+    super("This connection does not support transactions.")
+  }
+}

package/src/api/api.types.ts

@@ -1,11 +1,12 @@
-// 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,
@@ -29,36 +30,54 @@ export type InsertRecord<R> = Partial<R> &
 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 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>
+}
+
+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 Connection = ConnectionOperations & {
   readonly reset?: () => Promise<void>
+  readonly transaction?: Transaction
 }
 
-export type DatabaseApi<M extends SchemaMembers> = {
+export type DatabaseApi<
+  M extends SchemaMembers,
+  C extends Connection = Connection,
+> = {
   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
+  readonly connection: C
+  readonly transaction: <Result>(
+    work: (
+      database: DatabaseApi<M, TransactionalConnection>,
+    ) => Promise<Result>,
+  ) => Promise<Result>
 }
 
-export type ColumnsOfView<BV> = BV extends BuildView<infer Columns> ? Columns : never
+export type ColumnsOfView<BV> =
+  BV extends BuildView<infer Columns> ? Columns : never
 
 export type ViewApi<Columns> = {
   /** Issue a `SELECT *` query to the API. */
@@ -78,7 +97,7 @@ export type TableApi<Columns> = {
   ): Select<Pick<Columns, Column>, Columns>
   /** 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 +110,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,13 +121,15 @@ 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> {
+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.. */
@@ -177,11 +198,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 +210,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/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/UpdateBuilder.ts

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