@sigitex/outlaw 1.0.1 → 2.0.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
@@ -216,17 +238,182 @@ db.users.select("*")
 
 ### Joins
 
+Compose sources **before** selecting results. Examples in this section use a
+`Connection` named `connection` and these schema definitions:
+
 ```ts
-db.users.select("*")
-  .join(posts).on(users.id, "=", posts.userId)
+const users = createTable("users", {
+  id: integer.primaryKey,
+  name: text.notNull,
+  managerId: integer,
+})
+const posts = createTable("posts", {
+  id: integer.primaryKey,
+  userId: integer.notNull,
+  tenantId: integer.notNull,
+  title: text.notNull,
+  published: integer.map.boolean.notNull,
+  createdAt: integer.map.timestamp.notNull,
+})
+const profiles = createTable("profiles", {
+  userId: integer.notNull,
+  tenantId: integer.notNull,
+  bio: text,
+})
+const db = createDatabase(connection, createSchema({ users, posts, profiles }))
+```
+
+Strings work throughout joined queries. Bare names retain SQLite name resolution;
+qualified strings identify a specific source. Only selected columns appear in the
+result:
+
+```ts
+await db.users
+  .join(posts)
+  .on("users.id", "=", "posts.userId")
+  .select("name", "title")
+  .where("title", "Hello")
+  .orderBy([["name", "asc"]])
+  .limit(20)
+  .offset(40)
   .fetch()
+```
 
-db.users.select("*")
-  .leftJoin(posts).on(users.id, "=", posts.userId)
+Refs and strings can be mixed. Projection aliases are optional; use them when
+distinct output names are useful. `users.all` selects `users.*`, not every joined
+column:
+
+```ts
+await db.users
+  .leftJoin(posts)
+  .on(users.id, "=", posts.userId)
+  .select(users.id.as("userId"), posts.id.as("postId"), posts.title)
+  .fetch()
+
+await db.users
+  .join(posts)
+  .on("users.id", "=", posts.userId)
+  .select(users.all, posts.title)
+  .where(posts.published, true)
+  .orderBy([[posts.createdAt, "desc"]])
+  .fetch()
+```
+
+#### Join forms and constraints
+
+`join`, `leftJoin`, `rightJoin`, `fullJoin`, and `crossJoin` each accept tables,
+views, or SELECT subqueries. Constraints are optional for every form. Repeated
+`on()` calls combine with `AND` on the latest join. `using()` accepts one or more
+common column names and cannot be combined with `on()` on that same join.
+
+```ts
+await db.users.rightJoin(posts).on(users.id, "=", posts.userId)
+  .select("name", "title").fetch()
+await db.users.fullJoin(posts).on(users.id, "=", posts.userId)
+  .select("name", "title").fetch()
+await db.users.crossJoin(posts).select("name", "title").fetch()
+await db.users.join(posts).select("name", "title").fetch()
+
+await db.users.crossJoin(posts)
+  .on(users.id, "=", posts.userId)
+  .on(users.name, "!=", posts.title)
+  .select("name", "title").fetch()
+
+await db.posts.join(profiles).using("userId", "tenantId").select("*").fetch()
+await db.posts.crossJoin(profiles).using("userId").select("userId").fetch()
+await db.posts.fullJoin(profiles).using("userId").select("userId").fetch()
+```
+
+Both operands of `on(left, operator, right)` are **column identifiers**, including
+strings. By contrast, the right-hand value of `where(column, value)` or
+`where(column, operator, value)` is always a **literal value**, even if it happens
+to equal a column name. Literal-value ON expressions are not supported.
+
+`select("*")` emits an actual `*`, preserving SQLite's common-column suppression
+with `USING`. Qualified refs and wildcards retain each source's own columns.
+Unqualified common keys from right/full joins include surviving right-side values.
+For explicitly projected common columns coalesced by `FULL JOIN ... USING`, Outlaw
+emits a same-name `AS` solely to prevent SQLite from retaining identifier quotes in
+the output key. No source names or distinct output names are invented.
+
+`RIGHT JOIN` and `FULL JOIN` require **SQLite 3.39.0 or newer**. Outlaw does not probe
+capabilities, emulate unsupported joins, validate rows, or preflight SQL structure.
+SQLite errors, including ambiguous bare identifiers, propagate from the connection.
+`NATURAL` joins and comma-separated sources are deferred. Join verification uses
+local Bun SQLite; no live D1 verification is claimed.
+
+#### Self-joins, subqueries, and views
+
+Source aliases are explicit and non-mutating:
+
+```ts
+const managers = users.as("managers")
+await db.users.leftJoin(managers)
+  .on(users.managerId, "=", managers.id)
+  .select(users.name.as("employeeName"), managers.name.as("managerName"))
+  .orderBy([["employeeName", "asc"]])
+  .fetch()
+```
+
+Subqueries expose only their projected outputs. Aliases remain optional; both
+forms execute inline as part of one SELECT. Aliasing or embedding snapshots the
+query, so later changes to the original builder do not alter an embedded query:
+
+```ts
+const publishedPosts = db.posts
+  .select("id", "userId", "title", "createdAt")
+  .where("published", true)
+  .as("publishedPosts")
+
+await db.users.join(publishedPosts)
+  .on(users.id, "=", publishedPosts.userId)
+  .select("name", publishedPosts.title, publishedPosts.createdAt)
+  .fetch()
+
+await db.users.join(db.posts.select("userId", "title"))
+  .on("users.id", "=", "userId")
+  .select("name", "title")
   .fetch()
+
+const userPosts = createView("user_posts",
+  users.leftJoin(posts).on(users.id, "=", posts.userId)
+    .select(users.name.as("userName"), posts.title),
+)
+```
+
+Schema-level queries need no connection. Add `userPosts` to `createSchema` to query
+the view through the database API; it exposes only `userName` and nullable `title`.
+
+#### Result types and duplicate names
+
+Results stay flat. Left joins add `null` to incoming columns; right joins add
+`null` to all accumulated left sources; full joins add it to both sides. Selected
+properties remain required, never optional. For example, selecting `users.name`
+and `posts.title` after a left join yields `{ name: string; title: string | null }`.
+
+Mappings follow the selected source and output alias, including through subqueries
+and views. Outer-join SQL nulls stay null; mapped values decode once at execution.
+Filters use the referenced source's storage mapping.
+
+Duplicate output names are allowed without aliases, nesting, or automatic
+renaming. The connection's object-row behavior determines which duplicate value
+survives; ordinary collisions have conservative union types. Incompatible mapping
+collisions stay undecoded and are typed as `unknown`. Explicit distinct aliases
+preserve precise field types when both values are needed.
+
+#### Migrating the old join chain
+
+`db.users.select(...).join(posts).on(...)` is removed, including schema-level
+join-after-select calls. Move `select(...)` after source composition:
+
+```ts
+await db.users.join(posts).on(users.id, "=", posts.userId)
+  .select(users.name, posts.title).fetch()
 ```
 
-Join types: `join`, `leftJoin`, `rightJoin`, `crossJoin`. Each accepts a table or a subquery.
+Joined columns are no longer implicitly appended to the projection. Select the
+outputs needed explicitly, or use `*`/qualified wildcards. Existing single-table
+SELECT and unrelated INSERT/UPDATE/DELETE chains retain their interfaces.
 
 ### Insert
 

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": "2.0.0"
 }

package/src/api/DatabaseTable.ts

@@ -1,44 +1,70 @@
 // oxlint-disable typescript/no-explicit-any
-import type { Delete, Connection, Insert, Select, TableApi, Update } from "./api.types"
+import type { Delete, Connection, Insert, Update } from "./api.types"
 import type { TableData } from "../schemaBuilder"
-import {
-  DeleteBuilder,
-  InsertBuilder,
-  SelectBuilder,
-  UpdateBuilder,
-} from "../queryBuilder"
-
-export class DatabaseTable implements TableApi<any> {
-  private connection: Connection
+import { DeleteBuilder, InsertBuilder, UpdateBuilder } from "../queryBuilder"
+import { QuerySourceBuilder } from "../queryBuilder/QuerySourceBuilder"
+import type { QuerySource } from "../queryBuilder/QuerySource"
+import type { Projection } from "../queryBuilder/Projection"
+
+export class DatabaseTable {
+  private readonly connection: Connection
   private table: TableData
+  private readonly source: QuerySource.Data
 
   constructor(connection: Connection, table: TableData) {
     this.connection = connection
     this.table = table
+    this.source = { kind: "table", name: table.name, tableData: table }
+  }
+
+  select(...columns: Projection.Input[]) {
+    return new QuerySourceBuilder(this.source, this.connection).select(
+      ...columns,
+    )
+  }
+
+  join(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).join(target)
+  }
+
+  leftJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).leftJoin(target)
   }
 
-  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)
-  }
-
-  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)
+  rightJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).rightJoin(
+      target,
+    )
+  }
+
+  fullJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).fullJoin(target)
+  }
+
+  crossJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).crossJoin(
+      target,
+    )
+  }
+
+  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 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")
+      }
     }
-    const row = columnsOrRow as Record<string, unknown>
-    return new InsertBuilder(this.connection, this.table, Object.keys(row), [row])
+    return new InsertBuilder(this.connection, this.table, columns, rows)
   }
 
   update(row: Partial<any>): Update<any, number> {

package/src/api/DatabaseView.ts

@@ -1,22 +1,45 @@
-// oxlint-disable typescript/no-explicit-any
-import type { Connection, Select, ViewApi } from "./api.types"
+import type { Connection } from "./api.types"
 import type { TableData } from "../schemaBuilder"
-import { SelectBuilder } from "../queryBuilder"
+import { QuerySourceBuilder } from "../queryBuilder/QuerySourceBuilder"
+import type { QuerySource } from "../queryBuilder/QuerySource"
+import type { Projection } from "../queryBuilder/Projection"
 
-export class DatabaseView implements ViewApi<any> {
-  private connection: Connection
-  private tableData: TableData
+export class DatabaseView {
+  private readonly connection: Connection
+  private readonly source: QuerySource.Data
 
   constructor(connection: Connection, tableData: TableData) {
     this.connection = connection
-    this.tableData = tableData
+    this.source = { kind: "table", name: tableData.name, tableData }
   }
 
-  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(...columns: Projection.Input[]) {
+    return new QuerySourceBuilder(this.source, this.connection).select(
+      ...columns,
+    )
+  }
+
+  join(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).join(target)
+  }
+
+  leftJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).leftJoin(target)
+  }
+
+  rightJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).rightJoin(
+      target,
+    )
+  }
+
+  fullJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).fullJoin(target)
+  }
+
+  crossJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).crossJoin(
+      target,
+    )
   }
 }

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.")
+  }
+}