jade-sql 0.6.0 → 0.8.0

data/lib/jade-sql/sql.jd

@@ -1,15 +1,24 @@
 module Sql exposing (
+  Assignable,
+  Selectable,
+  selector,
   Assignment(..),
+  Col(..),
   Expr(..),
-  Identified,
-  Renderable,
+  NoJoins,
+  NoKey,
+  NoRequiredCols,
+  Pk,
   Selector(..),
   SqlError(..),
-  SqlMapper,
   Table,
   TableRef(..),
+  Unique,
+  matching,
+  ToSql,
   aliased,
   and,
+  any_of,
   array_append,
   array_concat,
   array_contained_by,
@@ -19,40 +28,48 @@ module Sql exposing (
   array_overlaps,
   array_remove,
   assign,
-  cast,
   coalesce,
   column,
   columns,
   count,
   count_all,
+  db_now,
   eq,
+  excluded,
   execute,
   execute_raw,
-  fetch_many,
   fetch_many_raw,
-  fetch_one,
   fetch_one_raw,
   gt,
   gte,
-  in_,
+  ilike,
   is_not_null,
   is_null,
   jsonb_contains,
   jsonb_path_exists,
+  left_columns,
+  like,
   lt,
   lte,
-  maybe_columns,
   neg,
-  now,
+  neq,
+  no_joins,
+  not,
   nullable,
-  pk_values,
-  render,
-  set_,
+  or,
+  pk,
+  set,
+  set_excluded,
+  set_expr,
   sum,
   table,
   to_assigns,
-  to_expr,
   transaction,
+  unique,
+  unkeyed,
+  unsafe_cast,
+  val,
+  within,
 )
 
 import Encode exposing (Encodable, encode)
@@ -72,21 +89,137 @@ struct Selector(a) = {
 }
 
 
-struct Table(c, m) = {
+# A table, as `structure.sql` declares it. `c` is its strict column struct
+# (`Expr(String)` for a NOT NULL text column), `m` the same columns lifted into
+# `Maybe` for left-join projections, `k` the type of its primary key, `o` a
+# record of one join predicate per foreign key it declares, `r` a struct of the
+# columns an insert has to write, and `s` a record of `Col` accessors for the
+# left of a `SET`.
+#
+# `schema.jd` generates one of these per table, so you name the table rather
+# than build it: `from(patients)`, `insert(row, patients)`. Reach for `table`
+# yourself only for something the generator does not see.
+struct Table(c, m, k, o, r, s) = {
   name: String,
   alias_: String,
   cols: String -> c,
-  maybe_cols: String -> m,
-  pk_columns: List(String)
+  left_cols: String -> m,
+  set_cols: s,
+  pk: Pk(c, k),
+  on: o
 }
 
 
+# The `on` of a table that declares no foreign keys. There is no relation to
+# name, so there is no join predicate to reach for — join such a table by
+# writing the predicate yourself:
+#
+#   from(patients) |> join(events, (e) -> { p.id |> Expr.eq(e.patient_id) })
+type NoJoins = NoJoinsOnly
+
+
+# The `r` of a table an insert can leave entirely to the database — every
+# column is nullable, or has a default, or is filled by its sequence. There is
+# no struct of required columns to name, so there is nothing to write.
+type NoRequiredCols = NoRequiredColsOnly
+
+
+# The `on` you hand `table` for such a table.
+def no_joins -> NoJoins
+  NoJoinsOnly
+end
+
+
 struct TableRef = {
   name: String,
   alias_: String
 }
 
 
+# A table's primary key: the columns that make it up, and how to spread a key
+# value across them. `k` is what you pass to `update` and `delete` — `Int` for
+# a serial id, `Uuid` for a uuid one, a tuple like `(Int, Int)` for a composite
+# key, in the order `structure.sql` declares the columns.
+#
+# Phantom in `c`, the table's column struct, so a key belongs to the one table
+# it came from and cannot be passed to another. Both halves are generated from
+# the same DDL, so the columns and the values cannot fall out of step.
+struct Pk(c, k) = {
+  name: String,
+  columns: List(String),
+  values: k -> List(Value)
+}
+
+
+# The key type of a table that has none — a join table, an append-only log,
+# anything `structure.sql` declares without a PRIMARY KEY. `NoKey` has no
+# constructor you can reach, so there is no value to pass where a key is
+# expected.
+type NoKey = NoKey
+
+
+# The primary key of a table: the constraint that declares it, its key columns
+# in DDL order, and how to spread a key value across them.
+#
+#   pk("patients_pkey", ["id"], (v) -> { [Encode.encode(v)] })
+def pk(name: String, key_cols: List(String), values: k -> List(Value)) -> Pk(c, k)
+  Pk(name, key_cols, values)
+end
+
+
+# The `Pk` of a table with no primary key. Reaching for it means giving up
+# `update` and `delete`, which take a key; write to the table with
+# `update_all`/`delete_all`, which take a predicate:
+#
+#   delete_all(events, (c) -> { c.recorded_at |> lt(cutoff) })
+#
+# The generator passes this for you. You need it by hand only when writing a
+# table function yourself.
+def unkeyed -> Pk(c, NoKey)
+  Pk("", [], (v) -> { [] })
+end
+
+
+# A column on the left of a `SET`, carrying the name rather than an
+# expression that happens to look like one. `set` reads the name off it, so
+# there is nothing to recover from a rendered string and nothing to get wrong:
+# an aggregate or a `COALESCE` cannot be assigned to, and now cannot be
+# offered.
+#
+# The generator emits one record of these per table, which `update_all` hands
+# to the builder alongside the column accessors.
+struct Col(a) = { name: String }
+
+
+# A unique index, by the name Postgres reports when it is violated. Phantom
+# in the column struct, so an index cannot be used with a table it is not on.
+# The generator emits one per unique index and per table-level UNIQUE.
+struct Unique(c, k) = {
+  name: String,
+  columns: List(String),
+  values: k -> List(Value)
+}
+
+
+def unique(name: String, cols: List(String), values: k -> List(Value)) -> Unique(c, k)
+  Unique(name, cols, values)
+end
+
+
+
+# `email = ?`, or every column of a composite index joined by AND. The key
+# type comes from the index, so the wrong one does not compile and a
+# composite cannot be given in the wrong order.
+def matching(u: Unique(c, k), key: k) -> Expr(Bool)
+  Expr(
+    u.columns
+      |> List.map((col) -> { col ++ " = ?" })
+      |> String.join(" AND "),
+    key |> u.values,
+  )
+end
+
+
 struct Assignment = {
   col: String,
   value_sql: String,
@@ -94,8 +227,33 @@ struct Assignment = {
 }
 
 
-def set_(col: Expr(a), value: Expr(a)) -> Assignment
-  Assignment(strip_alias(col.sql), value.sql, value.params)
+# The assignment `update` and `update_all` take, given a column accessor and
+# the value to write:
+#
+#   [c.archived |> set(True)]
+def set(col: Col(a), value: a) -> Assignment
+  Assignment(col.name, "?", [encode(value)])
+end
+
+
+# `set`, where the new value is built from the row rather than held by the
+# caller:
+#
+#   [c.tags |> set_expr(array_append(c.tags, tag))]
+def set_expr(col: Col(a), value: Expr(a)) -> Assignment
+  Assignment(col.name, value.sql, value.params)
+end
+
+
+# The row that could not be inserted, for the `DO UPDATE` arm of an upsert.
+def excluded(col: Col(a)) -> Expr(a)
+  Expr("EXCLUDED." ++ col.name, [])
+end
+
+
+# `email = EXCLUDED.email`, which is what an upsert wants nearly every time.
+def set_excluded(col: Col(a)) -> Assignment
+  Assignment(col.name, "EXCLUDED." ++ col.name, [])
 end
 
 
@@ -104,34 +262,26 @@ def assign(col: String, value: a) -> Assignment
 end
 
 
-def strip_alias(sql: String) -> String
-  parts = String.split(sql, ".")
 
-  case parts
-  in [] then sql
-  in [name] then name
-  in [_ | rest] then String.join(rest, ".")
-  end
+interface Selectable(a) with
+  selector : Selector(a)
 end
 
 
-interface SqlMapper(a) with
+interface Assignable(a) with
   to_assigns : a -> List(Assignment)
 end
 
 
-implements SqlMapper(List(Assignment)) with
+implements Assignable(List(Assignment)) with
   to_assigns: (a) -> { a }
 end
 
 
-interface Identified(a) with
-  pk_values : a -> List(Value)
-end
-
-
-interface Renderable(r) with
-  render : r -> (String, List(Value))
+# Anything that can be handed to the database: a query, a write. The pair is
+# the statement and its parameters, in the order the statement binds them.
+interface ToSql(r) with
+  to_sql : r -> (String, List(Value))
 end
 
 
@@ -140,40 +290,60 @@ def column(alias_: String, name: String) -> Expr(a)
 end
 
 
-def to_expr(value: a) -> Expr(a)
+# A value where an expression is wanted. The operators take values directly,
+# so this is for the positions that cannot: a constant field in a projection
+# or a JSON document.
+#
+#   select(Row(_, _)) |> field(c.id) |> field_as(val("patient"), "kind")
+#   Json.object(Row(_)) |> Json.prop("kind", val("patient"))
+#
+# Every library that has this calls it `val`, and none of them has a word for
+# the other direction, since there the expression side is the default.
+def val(value: a) -> Expr(a)
   Expr("?", [encode(value)])
 end
 
 
-# The DB clock (Postgres `now()`), for `where(col |> gt(now))`-style
-# comparisons. This is the transaction timestamp, not the app clock.
-def now -> Expr(Instant)
+# The database's clock, as `now()` in the statement — evaluated by Postgres
+# when the query runs, at the start of the enclosing transaction. Not the
+# app's clock: `Sql.Write.timestamped` and `stamped` use that one, so two
+# rows written by one request share an instant this would not give them.
+#
+#   where(s.expires_at |> Expr.gt(db_now))
+def db_now -> Expr(Instant)
   Expr("now()", [])
 end
 
 
-def eq(left: Expr(a), right: Expr(a)) -> Expr(Bool)
-  Expr(left.sql ++ " = " ++ right.sql, left.params ++ right.params)
+def eq(col: Expr(a), value: a) -> Expr(Bool)
+  Expr(col.sql ++ " = " ++ "?", col.params ++ [encode(value)])
+end
+
+
+# `NULL <> x` is NULL, not true, so a nullable column never matches this.
+# Pair it with `is_null` when "different, or absent" is what you mean.
+def neq(col: Expr(a), value: a) -> Expr(Bool)
+  Expr(col.sql ++ " <> " ++ "?", col.params ++ [encode(value)])
 end
 
 
-def gt(left: Expr(a), right: Expr(a)) -> Expr(Bool)
-  Expr(left.sql ++ " > " ++ right.sql, left.params ++ right.params)
+def gt(col: Expr(a), value: a) -> Expr(Bool)
+  Expr(col.sql ++ " > " ++ "?", col.params ++ [encode(value)])
 end
 
 
-def gte(left: Expr(a), right: Expr(a)) -> Expr(Bool)
-  Expr(left.sql ++ " >= " ++ right.sql, left.params ++ right.params)
+def gte(col: Expr(a), value: a) -> Expr(Bool)
+  Expr(col.sql ++ " >= " ++ "?", col.params ++ [encode(value)])
 end
 
 
-def lt(left: Expr(a), right: Expr(a)) -> Expr(Bool)
-  Expr(left.sql ++ " < " ++ right.sql, left.params ++ right.params)
+def lt(col: Expr(a), value: a) -> Expr(Bool)
+  Expr(col.sql ++ " < " ++ "?", col.params ++ [encode(value)])
 end
 
 
-def lte(left: Expr(a), right: Expr(a)) -> Expr(Bool)
-  Expr(left.sql ++ " <= " ++ right.sql, left.params ++ right.params)
+def lte(col: Expr(a), value: a) -> Expr(Bool)
+  Expr(col.sql ++ " <= " ++ "?", col.params ++ [encode(value)])
 end
 
 
@@ -192,18 +362,58 @@ def nullable(e: Expr(a)) -> Expr(Maybe(a))
 end
 
 
-def cast(e: Expr(a)) -> Expr(b)
+# Re-labels what a column expression claims to hold, without touching the SQL
+# or the value. Nothing converts, and nothing checks: if the database returns
+# something the new type cannot decode, the failure lands at decode time.
+#
+# Reach for it where the schema is less specific than the code, and the code
+# is right — a `text` column the application only ever writes enum labels to:
+#
+#   select(Visit(_)) |> field(v.status |> unsafe_cast)
+def unsafe_cast(e: Expr(a)) -> Expr(b)
   Expr(e.sql, e.params)
 end
 
 
+def not(e: Expr(Bool)) -> Expr(Bool)
+  # `NOT a AND b` binds as `(NOT a) AND b`.
+  Expr("NOT (" ++ e.sql ++ ")", e.params)
+end
+
+
+# `LIKE` is case-sensitive, `ILIKE` is not. Neither escapes `%` or `_` in the
+# pattern — a user-supplied string containing either is a wildcard, so escape
+# it yourself before it gets here.
+#
+#   c.name |> like("Ada%")
+def like(col: Expr(String), pattern: String) -> Expr(Bool)
+  Expr(col.sql ++ " LIKE " ++ "?", col.params ++ [encode(pattern)])
+end
+
+
+def ilike(col: Expr(String), pattern: String) -> Expr(Bool)
+  Expr(col.sql ++ " ILIKE " ++ "?", col.params ++ [encode(pattern)])
+end
+
+
 def and(left: Expr(Bool), right: Expr(Bool)) -> Expr(Bool)
   Expr(left.sql ++ " AND " ++ right.sql, left.params ++ right.params)
 end
 
 
+# Parenthesised where `and` is not, because `where` joins its predicates with
+# AND: without them `x = 1 AND a OR b` binds as `(x = 1 AND a) OR b`, which is
+# not what anyone writing `or` meant.
+def or(left: Expr(Bool), right: Expr(Bool)) -> Expr(Bool)
+  Expr(
+    "(" ++ left.sql ++ " OR " ++ right.sql ++ ")",
+    left.params ++ right.params,
+  )
+end
+
+
 # SUM may return NULL on an empty group, so the result is Expr(Maybe(Int)).
-# Wrap with `coalesce(sum(x), to_expr(0))` for a strict total.
+# Wrap with `coalesce(sum(x), 0)` for a strict total.
 def sum(e: Expr(Int)) -> Expr(Maybe(Int))
   Expr("SUM(" ++ e.sql ++ ")", e.params)
 end
@@ -219,10 +429,10 @@ def count_all -> Expr(Int)
 end
 
 
-def coalesce(maybe_e: Expr(Maybe(a)), default: Expr(a)) -> Expr(a)
+def coalesce(col: Expr(Maybe(a)), default: a) -> Expr(a)
   Expr(
-    "COALESCE(" ++ maybe_e.sql ++ ", " ++ default.sql ++ ")",
-    maybe_e.params ++ default.params,
+    "COALESCE(" ++ col.sql ++ ", ?)",
+    col.params ++ [encode(default)],
   )
 end
 
@@ -285,8 +495,8 @@ def array_remove(col: Expr(List(a)), value: a) -> Expr(List(a))
 end
 
 
-def array_concat(left: Expr(List(a)), right: Expr(List(a))) -> Expr(List(a))
-  Expr(left.sql ++ " || " ++ right.sql, left.params ++ right.params)
+def array_concat(col: Expr(List(a)), values: List(a)) -> Expr(List(a))
+  Expr(col.sql ++ " || ?", col.params ++ [encode(values)])
 end
 
 
@@ -296,8 +506,14 @@ end
 #   jsonb_contains(column("rules", "match"), { kind: "income" })
 #
 # pg binds Ruby Hash/Array as jsonb when paired with a jsonb column.
-# The `@?` jsonpath operator needs an explicit `::jsonpath` cast since
-# the param is bound as text.
+#
+# Four of Postgres' jsonb operators spell themselves with a `?` — `@?`, `?`,
+# `?|` and `?&` — and the runtime rewrites every `?` outside a quoted span
+# into a `$n` placeholder. It cannot tell an operator from a parameter, since
+# `meta ? 'kind'` and `id = ?` are the same character in the same position.
+# So these render as the functions Postgres gives them instead, which contain
+# no `?` and need no escaping. The functions also declare their parameter
+# types, which is what the operator form needed a cast to supply.
 
 
 def jsonb_contains(col: Expr(Value), value: a) -> Expr(Bool)
@@ -306,11 +522,39 @@ end
 
 
 def jsonb_path_exists(col: Expr(Value), path: String) -> Expr(Bool)
-  Expr(col.sql ++ " @? ?::jsonpath", col.params ++ [encode(path)])
+  Expr(
+    "jsonb_path_exists(" ++ col.sql ++ ", ?)",
+    col.params ++ [encode(path)],
+  )
+end
+
+
+# A column against a range, as `a..b` builds one. Both ends are inclusive,
+# matching `Range.contains?`, so the whole span renders as SQL rather than
+# being tested row by row:
+#
+#   where(c.seen_on |> within(start..finish))
+#   where(c.seen_on |> within(Range.from(start)))
+#
+# The degenerate ends render as constants: an empty range is `FALSE`, an
+# unbounded one `TRUE`, the same way `any_of([])` is `FALSE`.
+def within(col: Expr(a), range: Range(a)) -> Expr(Bool)
+  case (Range.empty?(range), Range.lower(range), Range.upper(range))
+  in (True, _, _) then Expr("FALSE", [])
+
+  in (_, Just(low), Just(high))
+  then Expr(col.sql ++ " BETWEEN ? AND ?", col.params ++ [encode(low), encode(high)])
+
+  in (_, Just(low), Nothing) then Expr(col.sql ++ " >= ?", col.params ++ [encode(low)])
+
+  in (_, Nothing, Just(high)) then Expr(col.sql ++ " <= ?", col.params ++ [encode(high)])
+
+  in (_, Nothing, Nothing) then Expr("TRUE", [])
+  end
 end
 
 
-def in_(col: Expr(a), values: List(a)) -> Expr(Bool)
+def any_of(col: Expr(a), values: List(a)) -> Expr(Bool)
   case values
   in [] then Expr("FALSE", [])
   else in_nonempty(col, List.map(values, encode))
@@ -331,36 +575,48 @@ def table(
   name: String,
   alias_: String,
   cols: String -> c,
-  maybe_cols: String -> m,
-  pk_columns: List(String),
-) -> Table(c, m)
-  Table(name, alias_, cols, maybe_cols, pk_columns)
+  left_cols: String -> m,
+  set_cols: s,
+  pk_: Pk(c, k),
+  on_: o,
+) -> Table(c, m, k, o, r, s)
+  Table(name, alias_, cols, left_cols, set_cols, pk_, on_)
 end
 
 
-def columns(t: Table(c, m), alias_: String) -> c
-  alias_ |> t.cols
+# A table's columns, bound to the alias the table carries. Reach for it to
+# build a predicate outside a bind chain, where `from` has not handed you the
+# columns yet:
+#
+#   p = columns(persons)
+#   from(persons) |> where(p.name |> eq("Paul"))
+#
+# Use `aliased` first to read the same table under another name.
+def columns(t: Table(c, m, k, o, r, s)) -> c
+  t.alias_ |> t.cols
 end
 
 
-def maybe_columns(t: Table(c, m), alias_: String) -> m
-  alias_ |> t.maybe_cols
+# The same columns as a left join produces them, every one lifted into
+# `Maybe`.
+def left_columns(t: Table(c, m, k, o, r, s)) -> m
+  t.alias_ |> t.left_cols
 end
 
 
-def aliased(t: Table(c, m), alias_: String) -> Table(c, m)
-  Table(t.name, alias_, t.cols, t.maybe_cols, t.pk_columns)
+def aliased(t: Table(c, m, k, o, r, s), alias_: String) -> Table(c, m, k, o, r, s)
+  Table(t.name, alias_, t.cols, t.left_cols, t.set_cols, t.pk, t.on)
 end
 
 
-# `NotUnique` is a read-side failure (fetch_one saw more than one row).
-# `Conflict` is a write-side unique-index violation, carrying the violated
-# constraint name so callers route it to a field error without string-matching.
+# `UniqueViolation` carries the violated constraint name. Compare it against
+# a generated index rather than a literal: `i == users_email_key.name` stops
+# compiling when the index is renamed, where a literal quietly stops matching.
 type SqlError
   = DbError(String)
   | NotFound
-  | NotUnique
-  | Conflict(String)
+  | TooManyRows
+  | UniqueViolation(String)
 
 
 implements Encodable(SqlError) with
@@ -372,8 +628,8 @@ def encode_sql_error(e: SqlError) -> Value
   case e
   in DbError(msg) then Encode.variant("DbError", [Encode.string(msg)])
   in NotFound then Encode.variant("NotFound", [])
-  in NotUnique then Encode.variant("NotUnique", [])
-  in Conflict(name) then Encode.variant("Conflict", [Encode.string(name)])
+  in TooManyRows then Encode.variant("TooManyRows", [])
+  in UniqueViolation(name) then Encode.variant("UniqueViolation", [Encode.string(name)])
   end
 end
 
@@ -387,8 +643,8 @@ def sql_error_decoder -> Decoder(SqlError)
   Decode.type_
     |> Decode.variant("DbError", db_error_decoder)
     |> Decode.variant("NotFound", Decode.succeed(NotFound))
-    |> Decode.variant("NotUnique", Decode.succeed(NotUnique))
-    |> Decode.variant("Conflict", conflict_decoder)
+    |> Decode.variant("TooManyRows", Decode.succeed(TooManyRows))
+    |> Decode.variant("UniqueViolation", unique_violation_decoder)
 end
 
 
@@ -397,8 +653,8 @@ def db_error_decoder -> Decoder(SqlError)
 end
 
 
-def conflict_decoder -> Decoder(SqlError)
-  Decode.index(1, Decode.string) |> Decode.map(Conflict)
+def unique_violation_decoder -> Decoder(SqlError)
+  Decode.index(1, Decode.string) |> Decode.map(UniqueViolation)
 end
 
 
@@ -431,24 +687,18 @@ end
 
 
 def execute(r: r) -> Task(Int, SqlError)
-  render(r) |> execute_raw
+  to_sql(r) |> execute_raw
 end
 
 
-def fetch_one(r: r) -> Task(a, SqlError)
-  render(r) |> fetch_one_raw
-end
 
 
-def fetch_many(r: r) -> Task(List(a), SqlError)
-  render(r) |> fetch_many_raw
-end
 
 
 # Runs `task` inside a single DB transaction on the shared connection:
 # every execute/fetch the task performs participates in it. Commits on
-# Ok, rolls back and re-raises the error on Err. Does not nest — wrapping
-# a transaction in a transaction is unsupported for now (no savepoints).
+# Ok, rolls back and re-raises the error on Err. Nests as a savepoint of
+# whichever transaction is already open, jade's or ActiveRecord's.
 def transaction(task: Task(a, SqlError)) -> Task(a, SqlError)
   port_begin()
     |> Task.and_then((_) -> { commit_on_ok(task) })