@sigitex/outlaw 1.2.0 → 2.0.0

package/README.md

@@ -238,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

@@ -49,5 +49,5 @@
   "files": [
     "src"
   ],
-  "version": "1.2.0"
+  "version": "2.0.0"
 }

package/src/api/DatabaseTable.ts

@@ -1,36 +1,50 @@
 // 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)
+  }
+
+  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)
   }
 
-  select(all: "*"): Select<any, any>
-  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)
+  crossJoin(target: QuerySource.Input) {
+    return new QuerySourceBuilder(this.source, this.connection).crossJoin(
+      target,
+    )
   }
 
   insert(...rows: [Partial<any>, ...Partial<any>[]]): Insert<any, any, number>

package/src/api/DatabaseView.ts

@@ -1,23 +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> {
-    const selected = columns[0] === "*" || columns.length === 0 ? "*" : columns
-    return new SelectBuilder(this.connection, this.tableData, selected)
+  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/api.types.ts

@@ -3,14 +3,12 @@
 // oxlint-disable typescript/consistent-type-definitions
 import type { BINARY_OPERATORS, UNARY_OPERATORS } from "../queryBuilder"
 import type {
-  BuildTable,
-  BuildView,
-  ColumnRef,
   InferColumn,
   SchemaMembers,
   TablesOf,
   ViewsOf,
 } from "../schemaBuilder"
+import type { QueryScope } from "../queryBuilder/QueryScope"
 
 // Utilities
 
@@ -27,8 +25,9 @@ export type InsertRecord<R> = Partial<R> &
 
 // Deconstruction
 
-export type ColumnsOf<BT> =
-  BT extends BuildTable<infer Columns> ? Columns : never
+export type ColumnsOf<BT> = BT extends { readonly $columns: infer Columns }
+  ? Columns
+  : never
 
 export type ColumnTypesOf<BCS> = {
   readonly [BCK in keyof BCS]: InferColumn<BCS[BCK]>
@@ -64,9 +63,15 @@ 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 TablesOf<M>]: TableApi<
+    ColumnsOf<TablesOf<M>[K]>,
+    QueryScope.Of<TablesOf<M>[K]>["name"]
+  >
 } & {
-  readonly [K in keyof ViewsOf<M>]: ViewApi<ColumnsOfView<ViewsOf<M>[K]>>
+  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>(
@@ -76,25 +81,23 @@ export type DatabaseApi<
   ) => Promise<Result>
 }
 
-export type ColumnsOfView<BV> =
-  BV extends BuildView<infer Columns> ? Columns : never
+export type ColumnsOfView<BV> = QueryScope.Of<BV>["columns"]
 
-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 ViewApi<
+  Columns extends QueryScope.Columns,
+  Name extends string = string,
+> = QueryScope.Composition<
+  QueryScope.Initial<QueryScope.State<Name, Columns>>,
+  true
+>
 
-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 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, ...InsertColumns[]]
@@ -125,61 +128,10 @@ export interface HasWhereClause<Columns> {
   ): 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> {

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/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 }
+  }
+}