@sigitex/outlaw 1.2.0 → 2.0.0

package/src/queryBuilder/SelectQueryBuilder.ts

@@ -1,93 +1,82 @@
-// 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"
+import type { BinaryOperator, UnaryOperator } from "../api/api.types"
+import type { ColumnRef } from "../schemaBuilder/ColumnRef"
+import { QuerySource } from "./QuerySource"
+import type { SelectQuery } from "./queryBuilders.types"
+import { isBinaryOperator, isUnaryOperator } from "./operators"
+import { Projection } from "./Projection"
 
-/** 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
+  constructor(query: SelectQuery) {
+    this.query = query
   }
 
-  offset(n: number) {
-    this.query.offset = n
-    return this
+  as(name: string) {
+    return QuerySource.create({ ...QuerySource.target(this), alias: name })
   }
 
-  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)
+  limit(count: number) {
+    this.query.limit = count
     return this
   }
 
-  orderBy(sorts: [string, "asc" | "desc"][]): this {
-    this.query.orderBy = sorts.map(([column, direction]) => ({
-      column,
-      direction,
-    }))
+  offset(count: number) {
+    this.query.offset = count
     return this
   }
 
-  private addJoin(type: JoinType, target: JoinTarget): this {
-    if (!this.query.joins) {
-      this.query.joins = []
+  where(column: string | ColumnRef, value: unknown): this
+  where(
+    column: string | ColumnRef,
+    operator: BinaryOperator | UnaryOperator,
+    value?: unknown,
+  ): this
+  where(column: string | ColumnRef, operator: unknown, value?: unknown) {
+    const scope = QuerySource.scope(this.query)
+    const identifier = QuerySource.identifier(scope, column)
+    this.query.conditions ??= []
+    if (
+      typeof operator === "string" &&
+      isUnaryOperator(operator) &&
+      arguments.length === 2
+    ) {
+      this.query.conditions.push({
+        column: identifier,
+        arity: 1,
+        operator: operator as UnaryOperator,
+      })
+    } else {
+      const binary =
+        arguments.length === 3 &&
+        typeof operator === "string" &&
+        isBinaryOperator(operator)
+      const operand = binary ? value : operator
+      const columns = QuerySource.resolve(scope, identifier)
+      const mapping = columns.length
+        ? Projection.merge(columns).mapping
+        : undefined
+      this.query.conditions.push({
+        column: identifier,
+        arity: 2,
+        operator: binary ? (operator as BinaryOperator) : "=",
+        value: mapping && operand !== null ? mapping.to(operand) : operand,
+      })
     }
-    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 })
+  orderBy(sorts: readonly (readonly [string | ColumnRef, "asc" | "desc"])[]) {
+    const scope = QuerySource.scope(this.query)
+    const outputs = Projection.columns(this.query)
+    this.query.orderBy = sorts.map(([column, direction]) => ({
+      column:
+        typeof column === "string" &&
+        outputs.some((output) => output.name === column)
+          ? { column }
+          : QuerySource.identifier(scope, column),
+      direction,
+    }))
     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/index.ts

@@ -1,4 +1,6 @@
 export * from "./queryBuilders.types"
+export * from "./QueryScope"
+export * from "./QuerySource"
 export * from "./operators"
 export * from "./SelectQueryBuilder"
 export * from "./SelectBuilder"

package/src/queryBuilder/queryBuilders.types.ts

@@ -1,35 +1,39 @@
 // oxlint-disable typescript/consistent-type-definitions -- review
 import type { BinaryOperator, UnaryOperator } from "../api/api.types"
-import type { ColumnRef, TableData } from "../schemaBuilder"
+import type { QuerySource } from "./QuerySource"
+import type { Projection } from "./Projection"
+
+export type ColumnIdentifier = { table?: string; column: string }
+export type SelectCondition =
+  | (Omit<UnaryCondition, "column"> & { column: ColumnIdentifier })
+  | (Omit<BinaryCondition, "column"> & { column: ColumnIdentifier })
 
 /** Represents a select query. */
 export interface SelectQuery {
   /** Table this query is performed on. */
-  table: string
+  source: QuerySource.Data
   /** Limit clause. */
   limit?: number
   /** Offset clause. */
   offset?: number
   /** Conditions of the SELECT. */
-  conditions?: Condition[]
+  conditions?: SelectCondition[]
   /** Which columns are being selected in this query. */
-  selected?: string[]
+  selected: Projection[]
   /** Order By clause */
-  orderBy?: OrderBySort[]
+  orderBy?: { column: ColumnIdentifier; direction: "asc" | "desc" }[]
   /** Join clauses. */
   joins?: JoinClause[]
 }
 
-export type JoinType = "join" | "left join" | "right join" | "cross join"
+export type JoinType =
+  | "join"
+  | "left join"
+  | "right join"
+  | "full join"
+  | "cross join"
 
-export type JoinTarget =
-  | { kind: "table"; name: string; tableData: TableData }
-  | {
-      kind: "subquery"
-      table: string
-      query: SelectQuery
-      tableData: TableData
-    }
+export type JoinTarget = QuerySource.Data
 
 export interface JoinClause {
   /** The type of join. */
@@ -38,15 +42,16 @@ export interface JoinClause {
   target: JoinTarget
   /** Join conditions (ON clause). */
   on: JoinOn[]
+  using?: string[]
 }
 
 export interface JoinOn {
   /** Left side of the ON condition. */
-  left: ColumnRef
+  left: ColumnIdentifier
   /** The comparison operator. */
   operator: BinaryOperator
   /** Right side of the ON condition. */
-  right: ColumnRef
+  right: ColumnIdentifier
 }
 
 /** Represents an update command. */

package/src/queryGenerator/Clause.ts

@@ -1,19 +1,24 @@
 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 type {
+  Condition,
+  JoinClause,
+  JoinTarget,
+  ColumnIdentifier,
+  SelectCondition,
+} from "../queryBuilder"
 import { generateSelectNode } from "./generateSelect"
 
 export namespace Clause {
-  export function where(conditions: Condition[], baseTable?: string): Node[] {
+  export function where(conditions: (Condition | SelectCondition)[]): Node[] {
     return [
       "where ",
       indent(
         conditions.map((condition, index) => [
           index > 0 && " and ",
-          baseTable
-            ? qualifyColumn(baseTable, condition.column)
-            : Format.name(condition.column),
+          typeof condition.column === "string"
+            ? Format.name(condition.column)
+            : identifier(condition.column),
           " ",
           condition.operator,
           condition.arity === 2 && [" ", Format.value(condition.value)],
@@ -30,50 +35,46 @@ export namespace Clause {
     return ["returning ", join(", ", columns, Format.name), newline]
   }
 
-  export function joins(
-    clauses: JoinClause[],
-    aliasMap: Map<JoinClause, string>,
-  ): Node {
+  export function identifier(column: ColumnIdentifier): string {
+    return column.table === undefined
+      ? Format.identifier(column.column)
+      : `${Format.identifier(column.table)}.${Format.identifier(column.column)}`
+  }
+
+  export function source(target: JoinTarget): Node {
+    return [
+      target.kind === "table"
+        ? Format.identifier(target.name)
+        : ["(", newline, indent([generateSelectNode(target.query)]), ")"],
+      target.alias !== undefined && [" as ", Format.identifier(target.alias)],
+    ]
+  }
+
+  export function joins(clauses: JoinClause[]): Node {
     return clauses.map((clause) => {
       const { type, on } = clause
-      const alias = aliasMap.get(clause)!
       return [
         type,
         " ",
-        formatTarget(clause.target, alias),
+        source(clause.target),
         newline,
         on.length > 0 &&
           indent(
             on.map(({ left, operator, right }, index) => [
               index === 0 ? "on " : "and ",
-              formatRef(left),
+              identifier(left),
               ` ${operator} `,
-              formatRef(right),
+              identifier(right),
               newline,
             ]),
           ),
+        clause.using?.length && [
+          "using (",
+          join(", ", clause.using, Format.identifier),
+          ")",
+          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/generateSelect.ts

@@ -1,89 +1,54 @@
-import { indent, join, newline, type Node, print } from "@sigitex/print"
+import { join, newline, type Node, print } from "@sigitex/print"
 import { Format } from "../framework"
-import type { JoinClause, OrderBySort, SelectQuery } from "../queryBuilder"
+import type { SelectQuery } from "../queryBuilder/queryBuilders.types"
 import { Clause } from "./Clause"
 
 export function generateSelect(query: SelectQuery) {
   return print([generateSelectNode(query)])
 }
 
-export function generateSelectNode({
-  selected,
-  table,
-  conditions,
-  limit,
-  offset,
-  orderBy,
-  joins,
-}: SelectQuery): Node {
-  const hasJoins = !!joins?.length
-  const aliasMap = hasJoins ? buildAliasMap(table, joins!) : undefined
+export function generateSelectNode(query: SelectQuery): Node {
   return [
     "select ",
-    selected &&
-      join(", ", selected, (col: string) =>
-        hasJoins ? qualifyColumn(table, col) : Format.name(col),
-      ),
-    !selected &&
-      (hasJoins ? allColumnsQualified(table, joins!, aliasMap!) : "*"),
+    join(", ", query.selected, (projection) => {
+      if (projection === "*") {
+        return "*"
+      }
+      if ("wildcard" in projection) {
+        return [Format.identifier(projection.table), ".*"]
+      }
+      return [
+        Clause.identifier(projection.column),
+        projection.alias !== undefined && [
+          " as ",
+          Format.identifier(projection.alias),
+        ],
+      ]
+    }),
     newline,
     "from ",
-    Format.name(table),
+    Clause.source(query.source),
     newline,
-    hasJoins && Clause.joins(joins!, aliasMap!),
-    conditions?.length &&
-      Clause.where(conditions, hasJoins ? table : undefined),
-    limit && ["limit ", Format.number(limit), newline],
-    offset && ["offset ", Format.number(offset), newline],
-    orderBy && orderByClause(orderBy),
-  ]
-}
-
-function buildAliasMap(
-  baseTable: string,
-  joins: JoinClause[],
-): Map<JoinClause, string> {
-  const map = new Map<JoinClause, string>()
-  const used = new Set([baseTable])
-
-  for (const clause of joins) {
-    const sourceName =
-      clause.target.kind === "table" ? clause.target.name : clause.target.table
-    let alias = sourceName
-    let i = 1
-    while (used.has(alias)) {
-      alias = `${sourceName}_${i++}`
-    }
-    used.add(alias)
-    map.set(clause, alias)
-  }
-  return map
-}
-
-function qualifyColumn(baseTable: string, column: string): string {
-  return `${Format.name(baseTable)}.${Format.name(column)}`
-}
-
-function allColumnsQualified(
-  table: string,
-  joins: JoinClause[],
-  aliasMap: Map<JoinClause, string>,
-): Node {
-  const names = [table, ...joins.map((j) => aliasMap.get(j)!)]
-  return names.map((t, i) => [i > 0 && ", ", Format.name(t), ".*"])
-}
-
-function orderByClause(orderBy: OrderBySort[]): Node {
-  return [
-    "order by ",
-    indent(
-      orderBy.map(({ column, direction }, index) => [
-        index > 0 && ", ",
-        Format.name(column),
+    query.joins?.length && Clause.joins(query.joins),
+    query.conditions?.length && Clause.where(query.conditions),
+    query.orderBy?.length && [
+      "order by ",
+      join(", ", query.orderBy, (sort) => [
+        Clause.identifier(sort.column),
         " ",
-        direction,
-        newline,
+        sort.direction,
       ]),
-    ),
+      newline,
+    ],
+    query.limit !== undefined && [
+      "limit ",
+      Format.number(query.limit),
+      newline,
+    ],
+    query.offset !== undefined && [
+      "offset ",
+      Format.number(query.offset),
+      newline,
+    ],
   ]
 }

package/src/schemaBuilder/ColumnRef.ts

@@ -0,0 +1,36 @@
+export type ColumnRef<
+  Table extends string = string,
+  Column extends string = string,
+> = {
+  readonly table: Table
+  readonly column: Column
+  as<Alias extends string>(
+    alias: Alias,
+  ): ColumnRef.Aliased<Table, Column, Alias>
+}
+
+export namespace ColumnRef {
+  export type Aliased<
+    Table extends string,
+    Column extends string,
+    Alias extends string,
+  > = ColumnRef<Table, Column> & { readonly alias: Alias }
+
+  export type Wildcard<Table extends string = string> = {
+    readonly table: Table
+    readonly wildcard: true
+  }
+
+  export function create<Table extends string, Column extends string>(
+    table: Table,
+    column: Column,
+  ): ColumnRef<Table, Column> {
+    return {
+      table,
+      column,
+      as(alias) {
+        return { ...create(table, column), alias }
+      },
+    }
+  }
+}

package/src/schemaBuilder/columnBuilders.ts

@@ -1,5 +1,10 @@
 // oxlint-disable typescript/no-explicit-any
-import type { CheckExpression, ColumnData, ColumnRef, MappingData } from "./metadata"
+import type {
+  CheckExpression,
+  ColumnData,
+  ColumnRef,
+  MappingData,
+} from "./metadata"
 import { Mapping } from "./Mapping"
 import type {
   BuildColumn,
@@ -49,7 +54,7 @@ function composeColumn(
         references(ref: ColumnRef) {
           return composeColumn({
             ...$meta,
-            foreignKey: ref,
+            foreignKey: { table: ref.table, column: ref.column },
           })
         },
       }

package/src/schemaBuilder/createTable.ts

@@ -1,15 +1,15 @@
-import type { ColumnData, ColumnRef, TableData } from "./metadata"
+import type { ColumnData, TableData } from "./metadata"
 import type {
   BuildColumns,
   BuildColumnInner,
   BuildTable,
 } from "./schemaBuilder.types"
-import { SelectQueryBuilder } from "../queryBuilder/SelectQueryBuilder"
+import { QuerySource } from "../queryBuilder/QuerySource"
 
-export function createTable<Columns extends BuildColumns>(
-  name: string,
+export function createTable<Columns extends BuildColumns, Name extends string>(
+  name: Name,
   defineColumns: Columns,
-): BuildTable<Columns> {
+): BuildTable<Columns, Name> {
   const columns = Object.entries(defineColumns).map<ColumnData>(
     ([name, define]) => {
       const meta = (define as BuildColumnInner).$meta
@@ -31,27 +31,30 @@ export function createTable<Columns extends BuildColumns>(
     columns,
     constraints: [],
   }
-  const by = new Proxy({}, {
-    get(_, col: string) {
-      return (value: unknown) => ({
-        _tag: "RefBy" as const,
-        table: defineTable,
-        column: col,
-        value,
-      })
+  const by = new Proxy(
+    {},
+    {
+      get(_, col: string) {
+        return (value: unknown) => ({
+          _tag: "RefBy" as const,
+          table: defineTable,
+          column: col,
+          value,
+        })
+      },
     },
-  })
-  function select(...columns: ("*" | string)[]) {
-    if (columns[0] === "*" || columns.length === 0) {
-      return new SelectQueryBuilder($meta, "*")
-    }
-    return new SelectQueryBuilder($meta, columns)
-  }
-  const defineTable = { $kind: "table" as const, $meta, by, primaryKey, unique, check, select } as unknown as BuildTable<Columns>
-  for (const col of Object.keys(defineColumns)) {
-    // oxlint-disable-next-line typescript/no-explicit-any
-    ;(defineTable as any)[col] = { table: name, column: col } satisfies ColumnRef
-  }
+  )
+  const defineTable = Object.assign(
+    QuerySource.create({ kind: "table", name, tableData: $meta }),
+    {
+      $kind: "table" as const,
+      $meta,
+      by,
+      primaryKey,
+      unique,
+      check,
+    },
+  ) as unknown as BuildTable<Columns, Name>
   return defineTable
 
   function primaryKey(...columns: (keyof Columns)[]) {
@@ -70,7 +73,11 @@ export function createTable<Columns extends BuildColumns>(
     return defineTable
   }
 
-  function check(expression: string | ((columns: Record<string, string>, table: TableData) => string)) {
+  function check(
+    expression:
+      | string
+      | ((columns: Record<string, string>, table: TableData) => string),
+  ) {
     $meta.constraints.push({
       type: "check",
       expression,

package/src/schemaBuilder/createView.ts

@@ -1,21 +1,33 @@
-// oxlint-disable typescript/no-explicit-any
 import { print } from "@sigitex/print"
 import { generateSelectNode } from "../queryGenerator/generateSelect"
 import type { SelectQueryBuilder } from "../queryBuilder/SelectQueryBuilder"
+import { Projection } from "../queryBuilder/Projection"
+import type { QueryScope } from "../queryBuilder/QueryScope"
+import { QuerySource } from "../queryBuilder/QuerySource"
 import type { TableData, ViewData } from "./metadata"
-import type { BuildView, SchemaSelect } from "./schemaBuilder.types"
+import type { BuildView } from "./schemaBuilder.types"
 
-export function createView<SelectColumns>(
-  name: string,
-  queryBuilder: SchemaSelect<SelectColumns, any>,
-): BuildView<SelectColumns> {
+export function createView<
+  Name extends string,
+  Columns extends QueryScope.Columns,
+>(
+  name: Name,
+  queryBuilder: { readonly $type: QueryScope.State<"", Columns> },
+): BuildView<Columns, Name> {
   const builder = queryBuilder as unknown as SelectQueryBuilder
   const sql = print([generateSelectNode(builder.query)])
   const $meta: ViewData = { kind: "view", name, sql }
-  const allColumns = [
-    ...builder.table.columns,
-    ...(builder.query.joins?.flatMap(j => j.target.tableData.columns) ?? []),
-  ]
-  const $tableData: TableData = { name, columns: allColumns, constraints: [] }
-  return { $kind: "view", $meta, $tableData }
+  const $tableData: TableData = {
+    name,
+    columns: Projection.columns(builder.query),
+    constraints: [],
+  }
+  return Object.assign(
+    QuerySource.create({ kind: "table", name, tableData: $tableData }),
+    {
+      $kind: "view" as const,
+      $meta,
+      $tableData,
+    },
+  ) as unknown as BuildView<Columns, Name>
 }

package/src/schemaBuilder/index.ts

@@ -1,4 +1,5 @@
 export * from "./Mapping"
+export { ColumnRef } from "./ColumnRef"
 export * from "./metadata"
 export * from "./schemaBuilder.types"
 export * from "./createSchema"