@sigitex/outlaw 1.2.0 → 2.0.0

package/src/queryBuilder/QueryScope.ts

@@ -0,0 +1,272 @@
+import type { BinaryOperator, UnaryOperator } from "../api/api.types"
+import type { ColumnRef } from "../schemaBuilder/ColumnRef"
+import type { InferColumn } from "../schemaBuilder/schemaBuilder.types"
+import type { QuerySource } from "./QuerySource"
+import type { JoinType } from "./queryBuilders.types"
+
+export type QueryScope = {
+  sources: readonly QueryScope.State[]
+  output: QueryScope.Entry
+}
+
+export namespace QueryScope {
+  export type Column = { value: unknown; mapped: boolean }
+  export type Columns = Record<string, Column>
+  export type State<
+    Name extends string = string,
+    Fields extends Columns = Columns,
+  > = {
+    name: Name
+    columns: Fields
+  }
+  export type Entry = {
+    name: string
+    value: unknown
+    mapped: boolean
+    origin: string
+  }
+  export type SchemaColumns<Fields> = {
+    [Key in keyof Fields & string]: {
+      value: InferColumn<Fields[Key]>
+      mapped: Fields[Key] extends { readonly $defined?: infer Defined }
+        ? "map" extends Defined
+          ? true
+          : false
+        : false
+    }
+  }
+  export type Of<Target> = Target extends {
+    readonly $type: infer Shape extends State
+  }
+    ? Shape
+    : never
+  export type Initial<Shape extends State> = {
+    sources: [Shape]
+    output: Entries<Shape>
+  }
+  export type Entries<Shape extends State> = {
+    [Key in keyof Shape["columns"] & string]: {
+      value: Shape["columns"][Key]["value"]
+      mapped: Shape["columns"][Key]["mapped"]
+      name: Key
+      origin: `${Shape["name"]}.${Key}`
+    }
+  }[keyof Shape["columns"] & string]
+
+  export type Identifier<Scope extends QueryScope> =
+    | Scope["output"]["name"]
+    | SourceIdentifiers<Scope["sources"][number]>
+  export type Projection<Scope extends QueryScope> =
+    | Identifier<Scope>
+    | "*"
+    | Wildcards<Scope["sources"][number]>
+  export type Resolve<Scope extends QueryScope, Input> = Input extends {
+    table: infer Table
+    column: infer Key
+  }
+    ? Qualified<Scope, Table, Key>
+    : Input extends Scope["output"]["name"]
+      ? Extract<Scope["output"], { name: Input }>
+      : Input extends `${infer Table}.${infer Key}`
+        ? Qualified<Scope, Table, Key>
+        : never
+
+  export type Project<
+    Scope extends QueryScope,
+    Inputs extends readonly unknown[],
+  > = Collapse<
+    Inputs extends readonly []
+      ? Scope["output"]
+      : ProjectEntry<Scope, Inputs[number]>
+  >
+  export type Values<Fields extends Columns> = {
+    [Key in keyof Fields]: Fields[Key]["value"]
+  }
+
+  export type Join<
+    Scope extends QueryScope,
+    Right extends State,
+    Kind extends JoinType,
+  > = {
+    sources: [
+      ...ExtendSources<Scope["sources"], Kind>,
+      ExtendRight<Right, Kind>,
+    ]
+    output:
+      | ExtendLeft<Scope["output"], Kind>
+      | Entries<ExtendRight<Right, Kind>>
+  }
+  export type Using<
+    Scope extends QueryScope,
+    Right extends State,
+    Kind extends JoinType,
+    Keys extends string,
+  > = {
+    sources: Join<Scope, Right, Kind>["sources"]
+    output:
+      | Exclude<Join<Scope, Right, Kind>["output"], { name: Keys }>
+      | Common<Scope, Right, Kind, Keys>
+  }
+
+  export type Composition<
+    Scope extends QueryScope,
+    Executable extends boolean = false,
+  > = {
+    select<const Inputs extends readonly Projection<Scope>[]>(
+      ...columns: Inputs
+    ): Selection<Project<Scope, Inputs>, Scope, Executable>
+    join<Target extends QuerySource.Target>(
+      target: Target,
+    ): Joined<Scope, Of<Target>, "join", Executable>
+    leftJoin<Target extends QuerySource.Target>(
+      target: Target,
+    ): Joined<Scope, Of<Target>, "left join", Executable>
+    rightJoin<Target extends QuerySource.Target>(
+      target: Target,
+    ): Joined<Scope, Of<Target>, "right join", Executable>
+    fullJoin<Target extends QuerySource.Target>(
+      target: Target,
+    ): Joined<Scope, Of<Target>, "full join", Executable>
+    crossJoin<Target extends QuerySource.Target>(
+      target: Target,
+    ): Joined<Scope, Of<Target>, "cross join", Executable>
+  }
+  export type Joined<
+    Left extends QueryScope,
+    Right extends State,
+    Kind extends JoinType,
+    Executable extends boolean,
+    Constraint extends "none" | "on" = "none",
+  > = Composition<Join<Left, Right, Kind>, Executable> & {
+    on(
+      left: Identifier<Join<Left, Right, Kind>>,
+      operator: BinaryOperator,
+      right: Identifier<Join<Left, Right, Kind>>,
+    ): Joined<Left, Right, Kind, Executable, "on">
+  } & (Constraint extends "none"
+      ? {
+          using<
+            const Keys extends readonly [
+              Left["output"]["name"] & keyof Right["columns"] & string,
+              ...(Left["output"]["name"] & keyof Right["columns"] & string)[],
+            ],
+          >(
+            ...columns: Keys
+          ): Composition<Using<Left, Right, Kind, Keys[number]>, Executable>
+        }
+      : {})
+
+  export type Selection<
+    Fields extends Columns,
+    Scope extends QueryScope,
+    Executable extends boolean = false,
+  > = {
+    readonly $type: State<"", Fields>
+    as<Name extends string>(name: Name): QuerySource<Name, Fields>
+    where<const Input extends Identifier<Scope>>(
+      column: Input,
+      value: Value<Resolve<Scope, NoInfer<Input>>> | UnaryOperator,
+    ): Selection<Fields, Scope, Executable>
+    where<const Input extends Identifier<Scope>>(
+      column: Input,
+      operator: BinaryOperator,
+      value: Value<Resolve<Scope, NoInfer<Input>>>,
+    ): Selection<Fields, Scope, Executable>
+    orderBy(
+      sorts: readonly (readonly [
+        Identifier<Scope> | (keyof Fields & string),
+        "asc" | "desc",
+      ])[],
+    ): Selection<Fields, Scope, Executable>
+    limit(count: number): Selection<Fields, Scope, Executable>
+    offset(count: number): Selection<Fields, Scope, Executable>
+  } & (Executable extends true
+    ? {
+        fetch(): Promise<Values<Fields>[]>
+        first(): Promise<Values<Fields>>
+      }
+    : {})
+
+  type SourceIdentifiers<Shape extends State> = Shape extends State
+    ? {
+        [Key in keyof Shape["columns"] & string]:
+          | ColumnRef<Shape["name"], Key>
+          | (Shape["name"] extends "" ? never : `${Shape["name"]}.${Key}`)
+      }[keyof Shape["columns"] & string]
+    : never
+  type Wildcards<Shape extends State> = Shape extends State
+    ? ColumnRef.Wildcard<Shape["name"]>
+    : never
+  type Qualified<Scope extends QueryScope, Name, Key> =
+    Entries<
+      Extract<Scope["sources"][number], { name: Name }>
+    > extends infer Fields
+      ? Extract<Fields, { name: Key }>
+      : never
+  type ProjectEntry<Scope extends QueryScope, Input> = Input extends "*"
+    ? Scope["output"]
+    : Input extends { table: infer Table; wildcard: true }
+      ? Entries<Extract<Scope["sources"][number], { name: Table }>>
+      : Input extends { alias: infer Alias extends string }
+        ? Rename<Resolve<Scope, Input>, Alias>
+        : Resolve<Scope, Input>
+  type Rename<Fields extends Entry, Name extends string> = Fields extends Entry
+    ? Omit<Fields, "name"> & { name: Name }
+    : never
+  type IsUnion<Value, Whole = Value> = Value extends Whole
+    ? [Whole] extends [Value]
+      ? false
+      : true
+    : never
+  type Value<Fields extends Entry> =
+    true extends IsUnion<Fields["origin"]>
+      ? true extends Fields["mapped"]
+        ? unknown
+        : Fields["value"]
+      : Fields["value"]
+  type Collapse<Fields extends Entry> = {
+    [Name in Fields["name"]]: {
+      value: Value<Extract<Fields, { name: Name }>>
+      mapped: true extends IsUnion<Extract<Fields, { name: Name }>["origin"]>
+        ? false
+        : Extract<Fields, { name: Name }>["mapped"]
+    }
+  }
+  type Nullable<Fields extends Columns> = {
+    [Key in keyof Fields]: {
+      value: Fields[Key]["value"] | null
+      mapped: Fields[Key]["mapped"]
+    }
+  }
+  type ExtendSources<
+    Sources extends readonly State[],
+    Kind extends JoinType,
+  > = {
+    [Index in keyof Sources]: Kind extends "right join" | "full join"
+      ? State<Sources[Index]["name"], Nullable<Sources[Index]["columns"]>>
+      : Sources[Index]
+  }
+  type ExtendRight<Right extends State, Kind extends JoinType> = Kind extends
+    | "left join"
+    | "full join"
+    ? State<Right["name"], Nullable<Right["columns"]>>
+    : Right
+  type ExtendLeft<
+    Fields extends Entry,
+    Kind extends JoinType,
+  > = Fields extends Entry
+    ? Kind extends "right join" | "full join"
+      ? Omit<Fields, "value"> & { value: Fields["value"] | null }
+      : Fields
+    : never
+  type Common<
+    Scope extends QueryScope,
+    Right extends State,
+    Kind extends JoinType,
+    Keys extends string,
+  > = Kind extends "right join"
+    ? Extract<Entries<Right>, { name: Keys }>
+    : Kind extends "full join"
+      ? Extract<Scope["output"] | Entries<Right>, { name: Keys }>
+      : Extract<Scope["output"], { name: Keys }>
+}

package/src/queryBuilder/QuerySource.ts

@@ -0,0 +1,231 @@
+import type { Connection } from "../api/api.types"
+import { ColumnRef } from "../schemaBuilder/ColumnRef"
+import type { ColumnData, TableData } from "../schemaBuilder/metadata"
+import type { QueryScope } from "./QueryScope"
+import type { SelectQuery, ColumnIdentifier } from "./queryBuilders.types"
+import { QuerySourceBuilder } from "./QuerySourceBuilder"
+import { Projection } from "./Projection"
+
+export type QuerySource<
+  Name extends string,
+  Columns extends QueryScope.Columns,
+> = {
+  readonly $source: QuerySource.Data
+  readonly $type: QueryScope.State<Name, Columns>
+  readonly all: ColumnRef.Wildcard<Name>
+  as<Alias extends string>(alias: Alias): QuerySource<Alias, Columns>
+} & {
+  readonly [Key in keyof Columns & string]: ColumnRef<Name, Key>
+} & QueryScope.Composition<QueryScope.Initial<QueryScope.State<Name, Columns>>>
+
+export namespace QuerySource {
+  export type Data = (
+    | { kind: "table"; name: string }
+    | { kind: "subquery"; query: SelectQuery }
+  ) & { alias?: string; tableData: TableData }
+
+  export type Target = { readonly $type: QueryScope.State }
+  export type Input =
+    | { readonly $source: Data }
+    | { readonly query: SelectQuery }
+  export type Scope = {
+    sources: Data[]
+    output: ColumnData[]
+    coalesced: Set<string>
+  }
+
+  export function create(
+    data: Data,
+    connection?: Connection,
+  ): QuerySource<string, QueryScope.Columns> {
+    const source = snapshotSource(data)
+    const name = qualifier(source)
+    const result = {
+      $source: source,
+      all: { table: name, wildcard: true as const },
+      as(alias: string) {
+        return create({ ...source, alias }, connection)
+      },
+      select(...columns: Projection.Input[]) {
+        return new QuerySourceBuilder(source, connection).select(...columns)
+      },
+      join(target: Input) {
+        return new QuerySourceBuilder(source, connection).join(target)
+      },
+      leftJoin(target: Input) {
+        return new QuerySourceBuilder(source, connection).leftJoin(target)
+      },
+      rightJoin(target: Input) {
+        return new QuerySourceBuilder(source, connection).rightJoin(target)
+      },
+      fullJoin(target: Input) {
+        return new QuerySourceBuilder(source, connection).fullJoin(target)
+      },
+      crossJoin(target: Input) {
+        return new QuerySourceBuilder(source, connection).crossJoin(target)
+      },
+    }
+    for (const column of source.tableData.columns) {
+      Object.defineProperty(result, column.name, {
+        value: ColumnRef.create(name, column.name),
+        enumerable: true,
+      })
+    }
+    return result as unknown as QuerySource<string, QueryScope.Columns>
+  }
+
+  export function target(input: Input): Data {
+    if ("$source" in input) {
+      return snapshotSource(input.$source)
+    }
+    const query = snapshot(input.query)
+    return {
+      kind: "subquery",
+      query,
+      tableData: {
+        name: "",
+        columns: Projection.columns(query),
+        constraints: [],
+      },
+    }
+  }
+
+  export function qualifier(source: Data): string {
+    return source.alias ?? (source.kind === "table" ? source.name : "")
+  }
+
+  export function snapshot(query: SelectQuery): SelectQuery {
+    return {
+      ...query,
+      source: snapshotSource(query.source),
+      selected: query.selected.map((projection) =>
+        projection === "*" ? projection : { ...projection },
+      ),
+      conditions: query.conditions?.map((condition) => ({ ...condition })),
+      orderBy: query.orderBy?.map((sort) => ({ ...sort })),
+      joins: query.joins?.map((clause) => ({
+        ...clause,
+        target: snapshotSource(clause.target),
+        on: clause.on.map((condition) => ({ ...condition })),
+        using: clause.using ? [...clause.using] : undefined,
+      })),
+    }
+  }
+
+  export function scope(query: SelectQuery): Scope {
+    let sources = [query.source]
+    let output = [...query.source.tableData.columns]
+    const coalesced = new Set<string>()
+    for (const clause of query.joins ?? []) {
+      const right = clause.target
+      const leftOutput = output
+      const extendLeft =
+        clause.type === "right join" || clause.type === "full join"
+      const extendRight =
+        clause.type === "left join" || clause.type === "full join"
+      if (extendLeft) {
+        sources = sources.map(nullableSource)
+        output = output.map(nullableColumn)
+      }
+      const incoming = extendRight ? nullableSource(right) : right
+      sources.push(incoming)
+      if (clause.using?.length) {
+        const common = new Set(clause.using)
+        for (const name of common) {
+          if (clause.type === "full join") {
+            coalesced.add(name)
+          } else if (clause.type === "right join") {
+            coalesced.delete(name)
+          }
+        }
+        output = output.map((column) => {
+          if (!common.has(column.name)) {
+            return column
+          }
+          const left = leftOutput.find(
+            (candidate) => candidate.name === column.name,
+          )!
+          const rightColumn = right.tableData.columns.find(
+            (candidate) => candidate.name === column.name,
+          )!
+          if (clause.type === "right join") {
+            return rightColumn
+          }
+          if (clause.type === "full join") {
+            return Projection.merge([left, rightColumn])
+          }
+          return left
+        })
+        output.push(
+          ...incoming.tableData.columns.filter(
+            (column) => !common.has(column.name),
+          ),
+        )
+      } else {
+        output.push(...incoming.tableData.columns)
+      }
+    }
+    return { sources, output, coalesced }
+  }
+
+  export function identifier(
+    scope: Scope,
+    input: string | ColumnRef,
+  ): ColumnIdentifier {
+    if (typeof input !== "string") {
+      return { table: input.table || undefined, column: input.column }
+    }
+    if (scope.output.some((column) => column.name === input)) {
+      return { column: input }
+    }
+    for (const source of scope.sources) {
+      const name = qualifier(source)
+      if (name && input.startsWith(`${name}.`)) {
+        return { table: name, column: input.slice(name.length + 1) }
+      }
+    }
+    return { column: input }
+  }
+
+  export function resolve(
+    scope: Scope,
+    identifier: ColumnIdentifier,
+  ): ColumnData[] {
+    if (identifier.table === undefined) {
+      return scope.output.filter((column) => column.name === identifier.column)
+    }
+    return scope.sources
+      .filter((source) => qualifier(source) === identifier.table)
+      .flatMap((source) =>
+        source.tableData.columns.filter(
+          (column) => column.name === identifier.column,
+        ),
+      )
+  }
+
+  function snapshotSource(source: Data): Data {
+    return {
+      ...source,
+      ...(source.kind === "subquery" ? { query: snapshot(source.query) } : {}),
+      tableData: {
+        ...source.tableData,
+        columns: [...source.tableData.columns],
+        constraints: [...source.tableData.constraints],
+      },
+    }
+  }
+
+  function nullableColumn(column: ColumnData): ColumnData {
+    return { ...column, notNull: false, primaryKey: undefined }
+  }
+
+  function nullableSource(source: Data): Data {
+    return {
+      ...source,
+      tableData: {
+        ...source.tableData,
+        columns: source.tableData.columns.map(nullableColumn),
+      },
+    }
+  }
+}

package/src/queryBuilder/QuerySourceBuilder.ts

@@ -0,0 +1,76 @@
+import type { BinaryOperator, Connection } from "../api/api.types"
+import type { ColumnRef } from "../schemaBuilder/ColumnRef"
+import { Projection } from "./Projection"
+import { QuerySource } from "./QuerySource"
+import { SelectBuilder } from "./SelectBuilder"
+import { SelectQueryBuilder } from "./SelectQueryBuilder"
+import type { JoinType, SelectQuery } from "./queryBuilders.types"
+
+export class QuerySourceBuilder {
+  private readonly query: SelectQuery
+  private readonly connection?: Connection
+
+  constructor(
+    source: QuerySource.Data,
+    connection?: Connection,
+    query?: SelectQuery,
+  ) {
+    this.query = query ?? { source, selected: ["*"] }
+    this.connection = connection
+  }
+
+  select(...columns: Projection.Input[]) {
+    const query = QuerySource.snapshot(this.query)
+    const scope = QuerySource.scope(query)
+    query.selected = columns.length
+      ? columns.map((column) => Projection.create(scope, column))
+      : ["*"]
+    return this.connection
+      ? new SelectBuilder(this.connection, query)
+      : new SelectQueryBuilder(query)
+  }
+
+  join(target: QuerySource.Input) {
+    return this.addJoin("join", target)
+  }
+  leftJoin(target: QuerySource.Input) {
+    return this.addJoin("left join", target)
+  }
+  rightJoin(target: QuerySource.Input) {
+    return this.addJoin("right join", target)
+  }
+  fullJoin(target: QuerySource.Input) {
+    return this.addJoin("full join", target)
+  }
+  crossJoin(target: QuerySource.Input) {
+    return this.addJoin("cross join", target)
+  }
+
+  on(
+    left: string | ColumnRef,
+    operator: BinaryOperator,
+    right: string | ColumnRef,
+  ) {
+    const query = QuerySource.snapshot(this.query)
+    const scope = QuerySource.scope(query)
+    query.joins![query.joins!.length - 1].on.push({
+      left: QuerySource.identifier(scope, left),
+      operator,
+      right: QuerySource.identifier(scope, right),
+    })
+    return new QuerySourceBuilder(query.source, this.connection, query)
+  }
+
+  using(...columns: string[]) {
+    const query = QuerySource.snapshot(this.query)
+    query.joins![query.joins!.length - 1].using = columns
+    return new QuerySourceBuilder(query.source, this.connection, query)
+  }
+
+  private addJoin(type: JoinType, input: QuerySource.Input) {
+    const query = QuerySource.snapshot(this.query)
+    query.joins ??= []
+    query.joins.push({ type, target: QuerySource.target(input), on: [] })
+    return new QuerySourceBuilder(query.source, this.connection, query)
+  }
+}

package/src/queryBuilder/SelectBuilder.ts

@@ -1,37 +1,31 @@
-// oxlint-disable typescript/no-explicit-any
-import type { Connection, Select } from "../api"
-import type { TableData } from "../schemaBuilder"
-import { generateSelect } from "../queryGenerator"
+import type { Connection } from "../api/api.types"
+import { generateSelect } from "../queryGenerator/generateSelect"
 import { Mappings } from "./Mappings"
+import { Projection } from "./Projection"
 import { SelectQueryBuilder } from "./SelectQueryBuilder"
+import type { SelectQuery } from "./queryBuilders.types"
 
-/** Constructs declarative `SELECT` statements with connection-based execution. */
-export class SelectBuilder extends SelectQueryBuilder implements Select<any, any> {
+export class SelectBuilder extends SelectQueryBuilder {
   readonly connection: Connection
 
-  constructor(
-    connection: Connection,
-    table: TableData,
-    columns: "*" | string[],
-  ) {
-    super(table, columns)
+  constructor(connection: Connection, query: SelectQuery) {
+    super(query)
     this.connection = connection
   }
 
-  async fetch(): Promise<any[]> {
+  async fetch() {
     const rows = await this.connection.query(generateSelect(this.query))
-    const tables = [
-      this.table,
-      ...(this.query.joins?.map((j) => j.target.tableData) ?? []),
-    ]
-    return Mappings.results(tables, rows)
+    return Mappings.results(
+      { name: "", columns: Projection.columns(this.query), constraints: [] },
+      rows,
+    )
   }
 
-  async first(): Promise<any> {
+  async first() {
     const results = await this.fetch()
     if (results[0] === undefined) {
       throw new Error(
-        `Query did not return a result (table: "${this.table.name}").`,
+        `Query did not return a result (table: "${this.query.source.tableData.name}").`,
       )
     }
     return results[0]