jade-sql 0.7.0 → 0.8.0

data/lib/jade-sql/sql/query.jd

@@ -1,21 +1,44 @@
 module Sql.Query exposing (
-  Q,
+  Query,
+  Select,
   field,
   field_as,
+  distinct,
+  exists,
   from,
   group,
+  in_subquery,
+  having,
+  not_exists,
   join,
+  rows,
   left_join,
   limit,
   offset,
   order,
   order_desc,
   select,
+  fetch_at_most_one,
+  fetch_many,
+  fetch_one,
+  fetch_row,
+  fetch_rows,
+  selected,
   to_sql,
+  subquery,
   where,
+  filter,
 )
 
-import Sql exposing (Expr, Renderable, Selector(..), Table, TableRef(..))
+import Sql exposing (
+  Expr(..),
+  Selector(..),
+  SqlError(..),
+  Table,
+  TableRef(..),
+  ToSql,
+  selector,
+)
 import Decode exposing (Value)
 
 
@@ -50,39 +73,69 @@ struct GroupTerm = {
 }
 
 
-struct Q(a) = {
+
+# A finished query: one you have projected columns into with `select` and
+# `field`, and can hand to `fetch_one` / `fetch_many`. A bare `Query(c)` is a
+# query mid-chain, still carrying a table's column accessors.
+#
+#   def scheduled_visits -> Select(Visit)
+type alias Select(a) = Query(Selector(a))
+
+
+struct Query(a) = {
   tables: List(TableRef),
   joins: List(Join),
   wheres: List(Expr(Bool)),
   groups: List(GroupTerm),
+  havings: List(Expr(Bool)),
   orders: List(OrderTerm),
   limit_: Maybe(Int),
   offset_: Maybe(Int),
+  distinct_: Bool,
   result: a
 }
 
 
-implements Chainable(Q(a)) with
+implements Chainable(Query(a)) with
   and_then: q_and_then
 end
 
 
-def q_and_then(q: Q(a), fn: a -> Q(b)) -> Q(b)
+def q_and_then(q: Query(a), fn: a -> Query(b)) -> Query(b)
   next_ = q.result |> fn
 
-  Q(
-    q.tables ++ next_.tables,
+  Query(
+    merge_tables(q.tables, next_.tables),
     q.joins ++ next_.joins,
     q.wheres ++ next_.wheres,
     q.groups ++ next_.groups,
+    q.havings ++ next_.havings,
     q.orders ++ next_.orders,
     merge_paging(q.limit_, next_.limit_),
     merge_paging(q.offset_, next_.offset_),
+    q.distinct_ || next_.distinct_,
     next_.result,
   )
 end
 
 
+# One entry per name-and-alias. Two `from`s of different tables still cross
+# join, and the same table under two aliases is still two tables; only the
+# exact repeat collapses, and that repeat was a duplicate-alias error before.
+def merge_tables(prev: List(TableRef), next_: List(TableRef)) -> List(TableRef)
+  List.fold(
+    next_,
+    prev,
+    (seen, t) -> { List.any?(seen, (s) -> { same_table?(s, t) }) ? seen : seen ++ [t] },
+  )
+end
+
+
+def same_table?(a: TableRef, b: TableRef) -> Bool
+  a.name == b.name && a.alias_ == b.alias_
+end
+
+
 def merge_paging(prev: Maybe(Int), next_: Maybe(Int)) -> Maybe(Int)
   case next_
   in Just(_) then next_
@@ -91,160 +144,153 @@ def merge_paging(prev: Maybe(Int), next_: Maybe(Int)) -> Maybe(Int)
 end
 
 
-def from(t: Table(c, m)) -> Q(c)
+def from(t: Table(c, m, k, o, r, s)) -> Query(c)
   cols_ = t.alias_ |> t.cols
 
-  Q([TableRef(t.name, t.alias_)], [], [], [], [], Nothing, Nothing, cols_)
+  Query([TableRef(t.name, t.alias_)], [], [], [], [], [], Nothing, Nothing, False, cols_)
 end
 
 
-def join(t: Table(c, m), on_: c -> Expr(Bool)) -> Q(c)
+def join(t: Table(c, m, k, o, r, s), on_: c -> Expr(Bool)) -> Query(c)
   cols_ = t.alias_ |> t.cols
   pred = cols_ |> on_
 
-  Q(
+  Query(
     [],
     [Join(InnerJ, t.name, t.alias_, pred)],
     [],
     [],
     [],
+    [],
     Nothing,
     Nothing,
+    False,
     cols_,
   )
 end
 
 
-def left_join(t: Table(c, m), on_: c -> Expr(Bool)) -> Q(m)
+def left_join(t: Table(c, m, k, o, r, s), on_: c -> Expr(Bool)) -> Query(m)
   cols_strict = t.alias_ |> t.cols
-  cols_maybe = t.alias_ |> t.maybe_cols
+  cols_maybe = t.alias_ |> t.left_cols
   pred = cols_strict |> on_
 
-  Q(
+  Query(
     [],
     [Join(LeftJ, t.name, t.alias_, pred)],
     [],
     [],
     [],
+    [],
     Nothing,
     Nothing,
+    False,
     cols_maybe,
   )
 end
 
 
-def where(q: Q(a), predicate: Expr(Bool)) -> Q(a)
-  Q(
-    q.tables,
-    q.joins,
-    q.wheres ++ [predicate],
-    q.groups,
-    q.orders,
-    q.limit_,
-    q.offset_,
-    q.result,
-  )
+def where(q: Query(a), predicate: Expr(Bool)) -> Query(a)
+  { q | wheres: q.wheres ++ [predicate] }
 end
 
 
-def group(q: Q(a), e: Expr(b)) -> Q(a)
-  Q(
-    q.tables,
-    q.joins,
-    q.wheres,
-    q.groups ++ [GroupTerm(e.sql, e.params)],
-    q.orders,
-    q.limit_,
-    q.offset_,
-    q.result,
-  )
+def filter(q: Query(a), build: a -> Expr(Bool)) -> Query(a)
+  where(q, build(q.result))
 end
 
 
-def order(q: Q(a), e: Expr(b)) -> Q(a)
-  Q(
-    q.tables,
-    q.joins,
-    q.wheres,
-    q.groups,
-    q.orders ++ [OrderTerm(Asc, e.sql, e.params)],
-    q.limit_,
-    q.offset_,
-    q.result,
-  )
+def group(q: Query(a), e: Expr(b)) -> Query(a)
+  { q | groups: q.groups ++ [GroupTerm(e.sql, e.params)] }
 end
 
 
-def order_desc(q: Q(a), e: Expr(b)) -> Q(a)
-  Q(
-    q.tables,
-    q.joins,
-    q.wheres,
-    q.groups,
-    q.orders ++ [OrderTerm(Desc, e.sql, e.params)],
-    q.limit_,
-    q.offset_,
-    q.result,
-  )
+# Filters on an aggregate, after `group` has collapsed the rows. `where`
+# cannot: it runs before the grouping, so `count_all` has nothing to count
+# yet.
+#
+#   group(p.id) |> having(count_all |> Expr.gt(val(3)))
+def having(q: Query(a), predicate: Expr(Bool)) -> Query(a)
+  { q | havings: q.havings ++ [predicate] }
 end
 
 
-def limit(q: Q(a), n: Int) -> Q(a)
-  Q(
-    q.tables,
-    q.joins,
-    q.wheres,
-    q.groups,
-    q.orders,
-    Just(n),
-    q.offset_,
-    q.result,
-  )
+# Drops duplicate rows from the result. Applies to the whole row the query
+# projects, which is `SELECT DISTINCT` rather than Postgres' `DISTINCT ON`.
+def distinct(q: Query(a)) -> Query(a)
+  { q | distinct_: True }
 end
 
 
-def offset(q: Q(a), n: Int) -> Q(a)
-  Q(
-    q.tables,
-    q.joins,
-    q.wheres,
-    q.groups,
-    q.orders,
-    q.limit_,
-    Just(n),
-    q.result,
-  )
+def order(q: Query(a), e: Expr(b)) -> Query(a)
+  { q | orders: q.orders ++ [OrderTerm(Asc, e.sql, e.params)] }
 end
 
 
-def select(make: a -> b) -> Q(Selector(a -> b))
-  Q([], [], [], [], [], Nothing, Nothing, Selector([], []))
+def order_desc(q: Query(a), e: Expr(b)) -> Query(a)
+  { q | orders: q.orders ++ [OrderTerm(Desc, e.sql, e.params)] }
 end
 
 
-def field(qs: Q(Selector(a -> b)), e: Expr(a)) -> Q(Selector(b))
-  Q(
+def limit(q: Query(a), n: Int) -> Query(a)
+  { q | limit_: Just(n) }
+end
+
+
+def offset(q: Query(a), n: Int) -> Query(a)
+  { q | offset_: Just(n) }
+end
+
+
+def select(make: a -> b) -> Query(Selector(a -> b))
+  Query([], [], [], [], [], [], Nothing, Nothing, False, Selector([], []))
+end
+
+
+# `select`'s unprojected twin, for a query the caller carries on building
+# rather than projects. It is what lets a subquery be written in a bind chain:
+#
+#   v <- from(visits)
+#
+#   rows(visits) |> where(...) |> order_desc(v.seen_on) |> limit(1)
+#
+# It names the table rather than the columns, so the query it starts stands on
+# its own. A query that only borrowed columns would render without a `FROM`
+# and read the outer query's table instead, which is legal SQL and a different
+# question. Naming the same table the chain already bound costs nothing: a
+# table is listed once however many times it is named.
+def rows(t: Table(c, m, k, o, r, s)) -> Query(c)
+  from(t)
+end
+
+
+def field(qs: Query(Selector(a -> b)), e: Expr(a)) -> Select(b)
+  Query(
     qs.tables,
     qs.joins,
     qs.wheres,
     qs.groups,
+    qs.havings,
     qs.orders,
     qs.limit_,
     qs.offset_,
+    qs.distinct_,
     Selector(qs.result.columns_sql ++ [e.sql], qs.result.params ++ e.params),
   )
 end
 
 
-def field_as(qs: Q(Selector(a -> b)), e: Expr(a), name: String) -> Q(Selector(b))
-  Q(
+def field_as(qs: Query(Selector(a -> b)), e: Expr(a), name: String) -> Select(b)
+  Query(
     qs.tables,
     qs.joins,
     qs.wheres,
     qs.groups,
+    qs.havings,
     qs.orders,
     qs.limit_,
     qs.offset_,
+    qs.distinct_,
     Selector(
       qs.result.columns_sql ++ [e.sql ++ " AS " ++ name],
       qs.result.params ++ e.params,
@@ -274,10 +320,17 @@ def render_order_term(t: OrderTerm) -> String
 end
 
 
+# Every table the query was built from, which is a cross join when there is
+# more than one. Rendering only the first would leave the statement
+# disagreeing with the value: `from` twice puts two tables in `tables`, and
+# accessors for both are in scope.
 def render_from(tables: List(TableRef)) -> String
   case tables
   in [] then ""
-  in [first | _] then " FROM " ++ first.name ++ " " ++ first.alias_
+
+  in _
+  then " FROM "
+    ++ String.join(List.map(tables, (t) -> { t.name ++ " " ++ t.alias_ }), ", ")
   end
 end
 
@@ -290,13 +343,71 @@ def render_int_clause(keyword: String, m: Maybe(Int)) -> String
 end
 
 
-implements Renderable(Q(Selector(a))) with
-  render: to_sql
+implements ToSql(Query(Selector(a))) with
+  to_sql: to_sql
+end
+
+
+def to_sql(q: Select(a)) -> (String, List(Value))
+  render(q, q.result.columns_sql, q.result.params)
 end
 
 
-def to_sql(q: Q(Selector(a))) -> (String, List(Value))
-  select_clause = "SELECT " ++ String.join(q.result.columns_sql, ", ")
+# `EXISTS (SELECT 1 FROM …)`, for asking whether a related row is there
+# without joining to it and without projecting anything from it. The inner
+# query may name the outer query's columns, which is what makes it correlated:
+#
+#   p <- from(patients)
+#   where(exists(from(visits) |> filter((v) -> { v.patient_id |> Expr.eq(p.id) })))
+def exists(q: Query(a)) -> Expr(Bool)
+  wrap_subquery("EXISTS (", q)
+end
+
+
+def not_exists(q: Query(a)) -> Expr(Bool)
+  wrap_subquery("NOT EXISTS (", q)
+end
+
+
+def wrap_subquery(keyword: String, q: Query(a)) -> Expr(Bool)
+  case render(q, ["1"], [])
+  in (sql, params) then Expr(keyword ++ sql ++ ")", params)
+  end
+end
+
+
+# A subquery in a value position: `(SELECT v.seen_on FROM ... LIMIT 1)`.
+# `Maybe`, because a subquery over no rows is NULL, same as `sum`.
+#
+# The column is picked rather than projected: `Select(a)` says nothing about
+# having exactly one, and a subquery with two is a runtime error.
+def subquery(q: Query(c), pick: c -> Expr(a)) -> Expr(Maybe(a))
+  picked = pick(q.result)
+
+  case render(q, [picked.sql], picked.params)
+  in (sql, params) then Expr("(" ++ sql ++ ")", params)
+  end
+end
+
+
+def in_subquery(e: Expr(a), q: Query(c), pick: c -> Expr(a)) -> Expr(Bool)
+  picked = pick(q.result)
+
+  case render(q, [picked.sql], picked.params)
+  in (sql, params) then Expr(e.sql ++ " IN (" ++ sql ++ ")", e.params ++ params)
+  end
+end
+
+
+# Every clause but the select list, which the caller supplies: `to_sql` passes
+# the projected columns, a subquery passes `1`.
+def render(
+  q: Query(a),
+  columns_sql: List(String),
+  result_params: List(Value),
+) -> (String, List(Value))
+  select_clause = (q.distinct_ ? "SELECT DISTINCT " : "SELECT ")
+    ++ String.join(columns_sql, ", ")
   from_clause = render_from(q.tables)
   joins_clause = q.joins
     |> List.map((j) -> { " " ++ render_join(j) })
@@ -307,6 +418,9 @@ def to_sql(q: Q(Selector(a))) -> (String, List(Value))
   group_clause = List.empty?(q.groups)
     ? ""
     : " GROUP BY " ++ String.join(List.map(q.groups, (g) -> { g.sql }), ", ")
+  having_clause = List.empty?(q.havings)
+    ? ""
+    : " HAVING " ++ String.join(List.map(q.havings, (h) -> { h.sql }), " AND ")
   order_clause = List.empty?(q.orders)
     ? ""
     : " ORDER BY " ++ String.join(List.map(q.orders, render_order_term), ", ")
@@ -315,6 +429,7 @@ def to_sql(q: Q(Selector(a))) -> (String, List(Value))
   join_ps = List.fold(q.joins, [], (acc, j) -> { acc ++ j.on.params })
   where_ps = List.fold(q.wheres, [], (acc, w) -> { acc ++ w.params })
   group_ps = List.fold(q.groups, [], (acc, g) -> { acc ++ g.params })
+  having_ps = List.fold(q.havings, [], (acc, h) -> { acc ++ h.params })
   order_ps = List.fold(q.orders, [], (acc, o) -> { acc ++ o.params })
 
   Tuple.Tuple2(
@@ -323,9 +438,86 @@ def to_sql(q: Q(Selector(a))) -> (String, List(Value))
       ++ joins_clause
       ++ where_clause
       ++ group_clause
+      ++ having_clause
       ++ order_clause
       ++ limit_clause
       ++ offset_clause,
-    q.result.params ++ join_ps ++ where_ps ++ group_ps ++ order_ps,
+    result_params ++ join_ps ++ where_ps ++ group_ps ++ having_ps ++ order_ps,
+  )
+end
+
+
+
+# Runs the query and decodes the single row it selected. Errors with
+# `NotFound` on none and `TooManyRows` on more than one, so "exactly one" is
+# checked rather than assumed.
+def fetch_one(q: Select(a)) -> Task(a, SqlError)
+  to_sql(q) |> Sql.fetch_one_raw
+end
+
+
+# `fetch_one` where no row is an answer rather than an error. More than one
+# is still `TooManyRows`: nothing is dropped to make the type fit.
+def fetch_at_most_one(q: Select(a)) -> Task(Maybe(a), SqlError)
+  q
+    |> fetch_one
+    |> Task.map(Just)
+    |> Task.on_error((e) -> {
+      case e
+      in NotFound then Task.succeed(Nothing)
+      else Task.fail(e)
+      end
+    })
+end
+
+
+# Runs the query and decodes every row it selected. No rows is an empty list,
+# not an error.
+def fetch_many(q: Select(a)) -> Task(List(a), SqlError)
+  to_sql(q) |> Sql.fetch_many_raw
+end
+
+
+# The shape you asked for names the columns, so a read with nothing computed
+# in it needs no `select`. `fetch_one` stays for a query that has one.
+def fetch_row(q: Query(c)) -> Task(a, SqlError)
+  q |> selected |> fetch_one
+end
+
+
+def fetch_rows(q: Query(c)) -> Task(List(a), SqlError)
+  q |> selected |> fetch_many
+end
+
+
+def selected(q: Query(c)) -> Select(a)
+  Query(
+    q.tables,
+    q.joins,
+    q.wheres,
+    q.groups,
+    q.havings,
+    q.orders,
+    q.limit_,
+    q.offset_,
+    q.distinct_,
+    qualified(q.tables, selector),
   )
 end
+
+
+# The shape names columns, not tables, so the alias comes from where the read
+# is rooted. Bare names would let Postgres choose: on a join it refuses an
+# ambiguous one, but a name that exists in only one of the joined tables
+# resolves to that one silently, whichever table the shape meant. Qualified,
+# that case is `column patients.note does not exist` instead.
+#
+# A query with no table of its own is left alone; there is no alias to use.
+def qualified(tables: List(TableRef), s: Selector(a)) -> Selector(a)
+  case tables
+  in [] then s
+
+  in [t | _]
+  then Selector(List.map(s.columns_sql, (c) -> { t.alias_ ++ "." ++ c }), s.params)
+  end
+end