jade-sql 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d437d0d6f0732ff240bc1833dd724ab0ddb17f11f048f64484971d4986c189a
-  data.tar.gz: 7570a5c8616b4281d64535e577dd9c70a504c285197ede6bda39e07b1061e397
+  metadata.gz: 4a375c4f1e9f8a4e724d4cfdb8019c47781be6fa151d63365dc217e0166d1cc3
+  data.tar.gz: cf7c46f4b57d31144dd38b15bf3471c437be7e0c3ae1315d1c5364de5a81f68b
 SHA512:
-  metadata.gz: 88fd20a47981bd6735bee0d63fcb65d950c34da7b4deaa5f4d132f6d8342a2fe7c0f9db78628fbdfe043e001262e1751eec24528eef449234f0746076b791304
-  data.tar.gz: aab1dbb9f6a251c3b61827bd605cb89ac81ca783f13f421db0093831c294556a863e3321e75e39531cc204a25693be8434a7caf3535b978b0712e100cc6454ff
+  metadata.gz: ef176c28d0a9d6dd4beb054940cc639ddf460bab7d05fc96cd9172b4d3f6841b855ea6b5e8aa4c66e1a83642a1167f412636dba1bf508d1a9c121e3708b50ae3
+  data.tar.gz: f54a7d82ec1d8c95441f5856a26298c6b8561dc4466b0ebab2820ac60b98fc7e2257c2d468016c5cb00021e262543f8183436970257d5ab07056b9658efa112e

data/docs/building.md

@@ -56,10 +56,32 @@ type VisitStatus
   | Done
 ```
 
-Nullary unions derive `Encodable` and `Decodable` with the variant name in
-snake_case, which is the label Postgres stores — so the codec is free and
-`eq(v.status, "schedulled")` stops compiling. Before this, an enum
-column failed generation outright with `Unknown SQL type`.
+The module carries a codec written from the labels, so `eq(v.status,
+"schedulled")` stops compiling, and a `Finite` instance listing every variant.
+That list is what lets `Expr.per_variant` give a `CASE` one arm per value:
+
+```jade
+v.status
+  |> Expr.per_variant((s) -> {
+    case s
+    in Scheduled then val("upcoming")
+    in InProgress then val("now")
+    in Done then val("past")
+    end
+  })
+# (CASE v.status WHEN ? THEN ? WHEN ? THEN ? WHEN ? THEN ? END)
+```
+
+The arms come from a jade `case`, so a missing one is a compile error, and a
+label added to the enum stops every `per_variant` that doesn't cover it
+until it does. The branch runs once per value while the query is built, not
+once per row. `Bool` has an instance too; anything else — a number, a string,
+a nullable column — has no list of values to exhaust, so the compiler asks
+for `case_of` instead: `No implementation of Sql.Expr.Finite for Int`.
+
+A NULL scrutinee matches no arm and makes the whole `CASE` NULL. A nullable
+column belongs in `case_when` with `is_null`, where that case is written
+down.
 
 `bytea` isn't mapped yet, though jade's `Bytes` is the natural target. See
 jade-lang's `Decimal` for the full API (`of`/`scaled`/`parse`, arithmetic,
@@ -168,9 +190,8 @@ carries `NoJoins`.
 
 A column whose name is a Jade keyword (e.g. `type`) gets a trailing
 underscore in the struct field (`type_`) while the SQL column reference
-keeps the real name. For a table with such a column the generator also
-emits a `<table>_row` projector that aliases every column to its field name
-(`SELECT … AS type_`), so reads round-trip without hand-written SQL:
+keeps the real name. The generator also emits a `<table>_row` projector
+that reads every column into the table's `Row` struct:
 
 ```jade
 def entries -> Select(JournalEntriesRow)
@@ -179,10 +200,14 @@ def entries -> Select(JournalEntriesRow)
 end
 ```
 
-In hand-written selects, `field_as(e, "name")` sets a column's output name
-when it differs from the SQL — needed for renamed columns and computed
-projections (decode keys by field name, so `field_as(count_all, "visits")`
-makes a `COUNT(*)` land in a `visits` field).
+A projection is read back by position: each `field` fills the constructor
+argument in the same place, which is the order the type-checker matched
+them in. A column's name never has to match its field, so a renamed column,
+a computed one and two `id`s from a join all read the same way:
+
+```jade
+select(Visits(_)) |> field(count_all)     # lands in whatever Visits calls it
+```
 
 ## Build queries
 
@@ -380,8 +405,31 @@ builder — params stitch in declaration order automatically.
 | `sum(Expr(Int)) -> Expr(Maybe(Int))`           | `SUM(e)`           | `NULL` on empty group → `Maybe`.       |
 | `count(Expr(a)) -> Expr(Int)`                  | `COUNT(e)`         | Counts non-null rows for the column.   |
 | `count_all -> Expr(Int)`                       | `COUNT(*)`         | Total row count.                       |
+| `count_distinct(Expr(a)) -> Expr(Int)`         | `COUNT(DISTINCT e)` | Distinct non-null values.             |
+| `max`, `min(Expr(a)) -> Expr(Maybe(a))`        | `MAX(e)`, `MIN(e)` | `NULL` on empty group.                 |
+| `avg(Expr(Int)) -> Expr(Maybe(Decimal))`       | `AVG(e)`           | Postgres averages integers exactly.    |
 | `coalesce(Expr(Maybe(a)), a) -> Expr(a)`       | `COALESCE(e, ?)`   | Drops the `Maybe` with a fallback.     |
 | `neg(Expr(Int)) -> Expr(Int)`                  | `-(e)`             | Unary minus.                           |
+| `lower`, `upper(Expr(String)) -> Expr(String)` | `LOWER(e)`         |                                        |
+| `trunc_date(DateUnit, Expr(Date)) -> Expr(Date)` | `date_trunc('month', e)` | First day of the unit.         |
+| `json_text(Expr(Value), String) -> Expr(Maybe(String))` | `e ->> ?` | `NULL` where the key is absent.      |
+
+`Sql.Expr` holds the ones that take a second expression rather than a value:
+
+| Function                                        | SQL                         |
+|-------------------------------------------------|-----------------------------|
+| `plus`, `minus`, `times`, `div` on `Expr(Int)`  | `(a + b)`; `div` truncates  |
+| `concat(Expr(String), Expr(String))`            | `(a \|\| b)`                |
+| `plus_days(Expr(Date), Expr(Int))`              | `(a + b)`                   |
+| `coalesce(Expr(Maybe(a)), Expr(a))`             | `COALESCE(a, b)`            |
+| `greatest`, `least(Expr(a), Expr(a))`           | `GREATEST(a, b)`            |
+| `filtered_to(Expr(a), Expr(Bool))`             | `agg FILTER (WHERE cond)`   |
+| `case_when` / `when` / `otherwise`              | `CASE WHEN … ELSE … END`    |
+| `per_variant(Expr(a), a -> Expr(b))`           | `CASE e WHEN … END`         |
+| `case_of` / `when_eq` / `otherwise`             | `CASE e WHEN … ELSE … END`  |
+
+A value you hold goes in through `val`, so each operation has one function:
+`p.balance |> Expr.times(val(12))`.
 
 Worked example — count visits and the most recent visit number,
 coalesced to 0 when a patient has none:
@@ -399,8 +447,42 @@ end
 # SELECT COUNT(*), COALESCE(SUM(a.visit_no), ?) FROM appointments a
 ```
 
-For `CASE WHEN` and arithmetic, fall back to the raw-`Expr`
-escape hatch until they get a typed builder.
+Three CASE spellings, by what the arms match on. Each builder takes its first
+arm, and a `Case` is not an expression until `otherwise` closes it, so neither
+a CASE without arms nor one without an `ELSE` can be written.
+
+Conditions, where nothing can list every case:
+
+```jade
+case_when(p.balance |> Expr.lt(val(0)), val("owes"))
+  |> Expr.when(p.balance |> Expr.gt(val(100)), val("credit"))
+  |> Expr.otherwise(val("even"))
+```
+
+A value, where you care about some of what it can be:
+
+```jade
+case_of(p.tier, val(1), val("gold"))
+  |> Expr.when_eq(val(2), val("silver"))
+  |> Expr.otherwise(val("basic"))
+```
+
+Both sides of `when_eq` are expressions of the same shape, so a mapping
+written the wrong way round is still a mapping — read those arms.
+
+A value whose every case you want, which is `per_variant` and needs no
+`ELSE` (see [enums](#generate-schemajd-from-dbstructuresql)). Adding an
+`otherwise` to a CASE over an enum is legal and loses that check: a label
+added to the enum lands quietly in the fallback, where `per_variant` would
+have stopped compiling.
+
+One total per condition is not a CASE. `SUM(CASE WHEN kind = 'income' THEN
+amount ELSE 0 END)` is `filtered_to`, which says the same thing to Postgres
+without the arms:
+
+```jade
+sum(tl.amount_cents) |> Expr.filtered_to(eq(t.kind, Income))
+```
 
 ### Subqueries
 
@@ -662,8 +744,8 @@ values directly, so this is for the positions that cannot — a constant field
 in a projection or a JSON document:
 
 ```jade
-select(Row(_, _)) |> field(c.id) |> field_as(val("patient"), "kind")
-# SELECT patients.id, ? AS kind FROM patients patients
+select(Row(_, _)) |> field(c.id) |> field(val("patient"))
+# SELECT patients.id, ? FROM patients patients
 ```
 
 It binds rather than inlining, so a string with a quote in it is a parameter
@@ -680,7 +762,7 @@ a `SET` takes no alias.
 
 ### RETURNING
 
-`returning_with` names the columns coming back, from the table's accessors.
+`returning` names the columns coming back, from the table's accessors.
 It is a step of its own rather than something `fetch_one` does for you: a
 write has one type whether you run it for a count or for a row, so folding the
 projection into the runner would mean `execute` and `fetch_one` producing
@@ -689,13 +771,13 @@ different SQL from the same `Write`.
 ```jade
 import Sql exposing(Selector)
 import Sql.Query exposing(select, field)
-import Sql.Write exposing(insert, returning_with, to_sql)
+import Sql.Write exposing(insert, returning, to_sql)
 
 # INSERT INTO patients (name, mrn) VALUES (?, ?)
 #   RETURNING patients.id, patients.name, patients.mrn
 np
 |> insert(patients)
-|> returning_with((p) -> {
+|> returning((p) -> {
   select(Patient(_, _, _))
   |> field(p.id)
   |> field(p.name)
@@ -714,7 +796,7 @@ def patient_row(p: PatientsCols) -> Select(Patient)
 end
 ```
 
-`from(patients) |> patient_row` for the read, `returning_with(patient_row)`
+`from(patients) |> patient_row` for the read, `returning(patient_row)`
 for the write. With row polymorphism a projection can span tables — one
 `def just_id(c: { a | id: Expr(Int) })` serves every table with an `id`.
 

data/docs/running.md

@@ -55,19 +55,18 @@ fetch_values : Query(c), Expr(b)  -> Task(List(b), e)  # one column, every row
 
 `fetch_exists` stops at the first row Postgres finds rather than counting
 every one of them. `exists` is the `Expr(Bool)` a `WHERE` takes, which is
-where the keyword appears in SQL. `fetch_values` reads one column; two would
-come back as a tuple, and a tuple of two columns of the same type is the
-projection bug with no field names to catch it.
+where the keyword appears in SQL. `fetch_values` reads one column; for more
+than one, `select |> field` names the shape they land in.
 
 For raw SQL, skip the builders: `fetch_one_raw` / `fetch_many_raw` /
 `execute_raw` take a `(String, List(Value))` pair. Their result type is
 unconstrained, which is honest — nothing about a hand-written string says
 what it returns.
 
-Row decoding is automatic — the caller's type (`Patient`, `List(Patient)`)
-threads its `Decodable` instance into the polymorphic port. The runtime
-returns plain Ruby hashes from AR, and they're decoded into typed structs
-at the boundary.
+A projection's rows come back as arrays, and each column goes through its
+field type's `Decodable` in the position `field` put it. The `*_raw` runners
+have no projection, so they decode by column name into the result type
+instead.
 
 `SqlError` variants:
 - `NotFound` — `fetch_one` with zero rows
@@ -174,10 +173,8 @@ describe MyApp do
   include Jade::Tasks::RSpec
 
   it 'queries patients' do
-    all_calls_to(JadeSql::Runtime.port_execute_many) do |t, _sql, _params|
-      t.ok([
-        { "id" => 1, "name" => "Paul", "mrn" => "MRN-001" }
-      ])
+    all_calls_to(JadeSql::Runtime.port_execute_rows) do |t, _sql, _params|
+      t.ok([[1, "Paul", "MRN-001"]])
     end
 
     expect(MyApp.list.run).to be_ok
@@ -185,7 +182,9 @@ describe MyApp do
 end
 ```
 
-The three ports are `port_execute_count`, `port_execute_one`,
-`port_execute_many` — `Sql.execute*` / `Sql.fetch_*` and their `*_raw`
-siblings ultimately dispatch through these. Stub them with
+Everything dispatches through four ports. `port_execute_rows` runs the
+builders' reads and RETURNING writes and answers with one array per row, in
+`field` order. `port_execute_count` runs `execute`, and `port_execute_one` /
+`port_execute_many` run the `*_raw` reads, answering with hashes keyed by
+column name. Stub them with
 `all_calls_to(JadeSql::Runtime.port_execute_*) { |t, sql, params| ... }`.

data/lib/jade-sql/bin/generate_schema.rb

@@ -503,7 +503,7 @@ module JadeSql
       ].sort
       sql_import = "import Sql exposing(#{(types + fns).join(', ')})"
       enum_imports = enum_imports_for(tables, module_name)
-      query_import = ["import Sql.Query exposing(Select, field_as, select)"]
+      query_import = ["import Sql.Query exposing(Select, field, select)"]
       # A join predicate compares two columns, which is `Sql.Expr`'s side of
       # the operator split rather than `Sql`'s value-taking one.
       expr_import = joined.any? ? ["import Sql.Expr as Expr"] : []
@@ -793,17 +793,14 @@ module JadeSql
       JADE
     end
 
-    # A row projector that aliases every column to its (possibly renamed)
-    # field name, so a reserved-word column like `type` round-trips through
-    # decode: `SELECT alias.type AS type_`. Emitted only for tables that have
-    # a renamed column. Composes in a bind-chain:
+    # Every column of the table into its Row struct. Composes in a bind-chain:
     #   c <- from(t)
     #   t_row(c) |> where(...)
     def emit_row_projector(t)
       klass = camel(t.name)
       holes = t.columns.map { "_" }.join(", ")
       projections = t.columns
-        .map { |c| "    |> field_as(c.#{field_name(c.name)}, #{field_name(c.name).inspect})" }
+        .map { |c| "    |> field(c.#{field_name(c.name)})" }
         .join("\n")
 
       <<~JADE.strip
@@ -851,6 +848,7 @@ module JadeSql
 
           import Decode exposing (Decodable, Decoder, Value)
           import Encode exposing (Encodable)
+          import Sql.Expr exposing (Finite)
 
 
           type #{type_name}
@@ -895,6 +893,16 @@ module JadeSql
         %(  else Decode.fail("not a #{enum.name}: " ++ s)),
         '  end',
         'end',
+        '',
+        '',
+        "implements Finite(#{type_name}) with",
+        "  variants: #{snake}_variants",
+        'end',
+        '',
+        '',
+        "def #{snake}_variants -> List(#{type_name})",
+        "  [#{variants_of(enum).join(', ')}]",
+        'end',
       ].join("\n")
     end
 

data/lib/jade-sql/runtime.rb

@@ -36,6 +36,14 @@ module JadeSql
       t.err(translate(e))
     end
 
+    task :port_execute_rows do |t, sql, params|
+      conn = ::ActiveRecord::Base.connection
+      rows = conn.exec_query(statement(sql, params, conn), "Jade", typed_params(params, conn)).rows
+      t.ok(rows.map { |row| row.map { coerce_value(it) } })
+    rescue ::ActiveRecord::StatementInvalid => e
+      t.err(translate(e))
+    end
+
     # Transaction control on the shared connection. The execute/fetch ports
     # above use the same `ActiveRecord::Base.connection`, so anything they
     # run between begin and commit/rollback is part of this transaction.

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

@@ -1,15 +1,38 @@
 module Sql.Expr exposing (
+  Case,
+  Finite,
+  Matching,
+  Searched,
+  case_of,
+  case_when,
+  coalesce,
+  concat,
+  div,
   eq,
+  filtered_to,
+  greatest,
   gt,
   gte,
   ilike,
+  least,
   like,
   lt,
   lte,
+  minus,
   neq,
+  otherwise,
+  per_variant,
+  plus,
+  plus_days,
+  times,
+  when,
+  when_eq,
 )
 
 import Sql exposing (Expr(..))
+import Encode exposing (Encodable, encode)
+import Decode exposing (Value)
+import Calendar exposing (Date)
 
 
 # The same comparisons `Sql` exposes, against another expression rather than a
@@ -63,3 +86,198 @@ end
 def binary(left: Expr(a), op: String, right: Expr(b)) -> Expr(Bool)
   Expr(left.sql ++ op ++ right.sql, left.params ++ right.params)
 end
+
+
+# A type whose every value is known: a database enum, whose instance the schema
+# generator writes next to its codec, and `Bool`.
+# A type with finitely many values, all of them listed. The schema generator
+# writes an instance beside each database enum's codec, so the list is
+# regenerated with the type. Writing one by hand is the one way to make
+# `per_variant` render a CASE that misses a value.
+interface Finite(a) with
+  variants: List(a)
+end
+
+
+implements Finite(Bool) with
+  variants: bool_variants
+end
+
+
+def bool_variants -> List(Bool)
+  [True, False]
+end
+
+
+# A `CASE` with one arm per value of `e`, each arm what `branch` makes of it.
+# `branch` is an ordinary function, so the `case` inside it is checked for
+# every value, and the SQL needs no `ELSE`:
+#
+#   t.kind |> Expr.per_variant((k) -> {
+#     case k
+#     in Income then tl.amount_cents
+#     in Expense then neg(tl.amount_cents)
+#     end
+#   })
+#   # (CASE t.kind WHEN ? THEN tl.amount_cents WHEN ? THEN -(tl.amount_cents) END)
+#
+# `per_variant` is finished the moment you call it — the arms are the
+# type's, so there is no `otherwise` to mark the end.
+#
+# `branch` runs once per value while the query is built, not once per row. A
+# NULL scrutinee matches no arm and the CASE is NULL, so a nullable column
+# belongs in `case_when` with `is_null` rather than here.
+def per_variant(e: Expr(a), branch: a -> Expr(b)) -> Expr(b)
+  arms = variants |> List.map((v) -> { (encode(v), branch(v)) })
+  whens = arms
+    |> List.map((arm) -> { " WHEN ? THEN " ++ Tuple.second(arm).sql })
+    |> String.concat
+  params = arms
+    |> List.and_then((arm) -> { [Tuple.first(arm)] ++ Tuple.second(arm).params })
+
+  Expr("(CASE " ++ e.sql ++ whens ++ " END)", e.params ++ params)
+end
+
+
+# Arithmetic on integers. Postgres divides integers by truncating toward
+# zero, and raises on a zero divisor.
+def plus(left: Expr(Int), right: Expr(Int)) -> Expr(Int)
+  operator(left, " + ", right)
+end
+
+
+def minus(left: Expr(Int), right: Expr(Int)) -> Expr(Int)
+  operator(left, " - ", right)
+end
+
+
+def times(left: Expr(Int), right: Expr(Int)) -> Expr(Int)
+  operator(left, " * ", right)
+end
+
+
+def div(left: Expr(Int), right: Expr(Int)) -> Expr(Int)
+  operator(left, " / ", right)
+end
+
+
+def concat(left: Expr(String), right: Expr(String)) -> Expr(String)
+  operator(left, " || ", right)
+end
+
+
+# Typed on both sides, since `date + integer` is one of several `+`s and a
+# bound value names neither.
+def plus_days(d: Expr(Date), days: Expr(Int)) -> Expr(Date)
+  Expr(
+    "((" ++ d.sql ++ ")::date + (" ++ days.sql ++ ")::integer)",
+    d.params ++ days.params,
+  )
+end
+
+
+def operator(left: Expr(a), op: String, right: Expr(b)) -> Expr(c)
+  Expr("(" ++ left.sql ++ op ++ right.sql ++ ")", left.params ++ right.params)
+end
+
+
+# `COALESCE` against an expression: another column, a subquery. `Sql.coalesce`
+# takes a value you hold.
+def coalesce(e: Expr(Maybe(a)), fallback: Expr(a)) -> Expr(a)
+  Expr("COALESCE(" ++ e.sql ++ ", " ++ fallback.sql ++ ")", e.params ++ fallback.params)
+end
+
+
+def greatest(left: Expr(a), right: Expr(a)) -> Expr(a)
+  Expr("GREATEST(" ++ left.sql ++ ", " ++ right.sql ++ ")", left.params ++ right.params)
+end
+
+
+def least(left: Expr(a), right: Expr(a)) -> Expr(a)
+  Expr("LEAST(" ++ left.sql ++ ", " ++ right.sql ++ ")", left.params ++ right.params)
+end
+
+
+# An aggregate over only the rows `condition` keeps:
+#
+#   sum(tl.amount_cents) |> Expr.filtered_to(eq(t.kind, Income))
+#   # SUM(tl.amount_cents) FILTER (WHERE t.kind = ?)
+def filtered_to(aggregate: Expr(a), condition: Expr(Bool)) -> Expr(a)
+  Expr(
+    aggregate.sql ++ " FILTER (WHERE " ++ condition.sql ++ ")",
+    aggregate.params ++ condition.params,
+  )
+end
+
+
+# A `CASE` you close yourself, in the two shapes Postgres writes. `t` says
+# which shape — `Searched` for `case_when`, `Matching(a)` for a `case_of` over
+# an `Expr(a)` — so an arm can only be added by the builder it belongs to, and
+# `b` is what the arms produce. A `Case` is not an expression
+# until `otherwise` gives it an `ELSE`, and each builder takes its first arm,
+# so a `CASE` with no arms cannot be written:
+#
+#   case_when(p.age |> Expr.lt(val(18)), val("minor"))
+#     |> Expr.when(p.age |> Expr.gte(val(65)), val("senior"))
+#     |> Expr.otherwise(val("adult"))
+#   # (CASE WHEN p.age < ? THEN ? WHEN p.age >= ? THEN ? ELSE ? END)
+#
+#   case_of(p.tier, val(1), val("gold"))
+#     |> Expr.when_eq(val(2), val("silver"))
+#     |> Expr.otherwise(val("basic"))
+#   # (CASE p.tier WHEN ? THEN ? WHEN ? THEN ? ELSE ? END)
+#
+# Over a type whose values are all known, `per_variant` covers them without
+# an `ELSE`, and the compiler checks the arms. Reach for `case_of` when the
+# values are not, and read the arms carefully: both sides of `when_eq` are
+# expressions of the same shape, so a mapping written the wrong way round is
+# still a mapping.
+type Searched = SearchedOnly
+
+
+type Matching(a) = MatchingOnly
+
+
+struct Case(t, b) = {
+  sql: String,
+  params: List(Value)
+}
+
+
+def case_when(condition: Expr(Bool), result: Expr(b)) -> Case(Searched, b)
+  Case(
+    "CASE WHEN " ++ condition.sql ++ " THEN " ++ result.sql,
+    condition.params ++ result.params,
+  )
+end
+
+
+def when(c: Case(Searched, b), condition: Expr(Bool), result: Expr(b)) -> Case(Searched, b)
+  with_arm(c, condition, result)
+end
+
+
+def case_of(e: Expr(a), value: Expr(a), result: Expr(b)) -> Case(Matching(a), b)
+  Case(
+    "CASE " ++ e.sql ++ " WHEN " ++ value.sql ++ " THEN " ++ result.sql,
+    e.params ++ value.params ++ result.params,
+  )
+end
+
+
+def when_eq(c: Case(Matching(a), b), value: Expr(a), result: Expr(b)) -> Case(Matching(a), b)
+  with_arm(c, value, result)
+end
+
+
+def with_arm(c: Case(t, b), matched: Expr(a), result: Expr(b)) -> Case(t, b)
+  Case(
+    c.sql ++ " WHEN " ++ matched.sql ++ " THEN " ++ result.sql,
+    c.params ++ matched.params ++ result.params,
+  )
+end
+
+
+def otherwise(c: Case(t, b), fallback: Expr(b)) -> Expr(b)
+  Expr("(" ++ c.sql ++ " ELSE " ++ fallback.sql ++ " END)", c.params ++ fallback.params)
+end

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

@@ -128,12 +128,11 @@ def text(d: Doc(a)) -> String
 end
 
 
-# The row comes back as a hash keyed by column name, so the projection needs
-# an alias matching Doc's field. `cast` is the escape hatch that erases
-# Json(a) to the String the column actually holds — it stays inside this
-# module, and the signature ties the result's tag back to the projection's.
+# `unsafe_cast` erases Json(a) to the String the column actually holds — it
+# stays inside this module, and the signature ties the result's tag back to
+# the projection's.
 def select(e: Expr(Json(a))) -> Query(Selector(Doc(a)))
-  Query.select(Doc(_)) |> Query.field_as(unsafe_cast(e), "text")
+  Query.select(Doc(_)) |> Query.field(unsafe_cast(e))
 end
 
 

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

@@ -2,7 +2,6 @@ module Sql.Query exposing (
   Query,
   Select,
   field,
-  field_as,
   distinct,
   exists,
   from,
@@ -37,7 +36,7 @@ import Sql exposing (
   ToSql,
   from_sql_error,
 )
-import Decode exposing (Value)
+import Decode exposing (Decodable, Decoder, Value)
 
 
 type JoinKind
@@ -257,28 +256,25 @@ end
 
 
 def select(make: a -> b) -> Query(Selector(a -> b))
-  Query([], [], [], [], [], [], Nothing, Nothing, False, Selector([], []), Nothing)
-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),
-    qs.result_alias,
+    [],
+    [],
+    [],
+    [],
+    [],
+    [],
+    Nothing,
+    Nothing,
+    False,
+    Selector([], [], Decode.succeed(make)),
+    Nothing,
   )
 end
 
 
-def field_as(qs: Query(Selector(a -> b)), e: Expr(a), name: String) -> Select(b)
+def field(qs: Query(Selector(a -> b)), e: Expr(a)) -> Select(b)
+  position = List.length(qs.result.columns_sql)
+
   Query(
     qs.tables,
     qs.joins,
@@ -290,8 +286,9 @@ def field_as(qs: Query(Selector(a -> b)), e: Expr(a), name: String) -> Select(b)
     qs.offset_,
     qs.distinct_,
     Selector(
-      qs.result.columns_sql ++ [e.sql ++ " AS " ++ name],
+      qs.result.columns_sql ++ [e.sql],
       qs.result.params ++ e.params,
+      qs.result.decoder |> Decode.and_map(Decode.index(position, Decode.decoder)),
     ),
     qs.result_alias,
   )
@@ -446,15 +443,17 @@ end
 # `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, e)
-  to_sql(q) |> Sql.fetch_one_raw |> Task.map_error(from_sql_error)
+  Sql.fetch_decoded(to_sql(q), q.result.decoder)
+    |> Task.and_then(Sql.exactly_one)
+    |> Task.map_error(from_sql_error)
 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), e)
-  to_sql(q)
-    |> Sql.fetch_one_raw
+  Sql.fetch_decoded(to_sql(q), q.result.decoder)
+    |> Task.and_then(Sql.exactly_one)
     |> Task.map(Just)
     |> Task.on_error(nothing_if_missing)
     |> Task.map_error(from_sql_error)
@@ -474,74 +473,42 @@ 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), e)
-  to_sql(q) |> Sql.fetch_many_raw |> Task.map_error(from_sql_error)
+  Sql.fetch_decoded(to_sql(q), q.result.decoder) |> Task.map_error(from_sql_error)
 end
 
 
-# A read with nothing to decode renders its own select list over the query's
-# clauses, so it needs no projection and carries no `Selectable`. The port
-# hands back a record either way, which is what these one-field shapes are
-# for.
-
-
-struct CountRow = { tally: Int }
-
-
-struct PresentRow = { present: Bool }
-
-
-struct ValueRow(a) = { value: a }
-
-
 def fetch_count(q: Query(a)) -> Task(Int, e)
-  render(q, ["COUNT(*) AS tally"], [])
-    |> Sql.fetch_one_raw
-    |> Task.map(count_of)
+  Sql.fetch_decoded(render(q, ["COUNT(*)"], []), Decode.index(0, Decode.int))
+    |> Task.and_then(Sql.exactly_one)
     |> Task.map_error(from_sql_error)
 end
 
 
-def count_of(r: CountRow) -> Int
-  r.tally
-end
-
-
 # `SELECT EXISTS (...)`, which stops at the first row Postgres finds rather
 # than counting every one of them. `exists` is the `Expr(Bool)` for a `WHERE`,
 # where the keyword actually appears.
 def fetch_exists(q: Query(a)) -> Task(Bool, e)
   present = exists(q)
 
-  Tuple.Tuple2("SELECT " ++ present.sql ++ " AS present", present.params)
-    |> Sql.fetch_one_raw
-    |> Task.map(present_of)
+  Sql.fetch_decoded(
+    ("SELECT " ++ present.sql, present.params),
+    Decode.index(0, Decode.bool),
+  )
+    |> Task.and_then(Sql.exactly_one)
     |> Task.map_error(from_sql_error)
 end
 
 
-def present_of(r: PresentRow) -> Bool
-  r.present
-end
-
-
 # One column out of every row, for the reads whose answer is a list of values
 # rather than a list of rows:
 #
 #   from(patients) |> where(p.archived |> eq(False)) |> fetch_values(p.id)
 #
-# Worth it only for a single column. Two would come back as a tuple, and a
-# tuple of two columns of the same type is the projection bug with no field
-# names to catch it — that is what `select |> field` is for.
+# Worth it only for a single column; more than one is what `select |> field`
+# is for.
 def fetch_values(q: Query(c), e: Expr(b)) -> Task(List(b), err)
-  render(q, [e.sql ++ " AS value"], e.params)
-    |> Sql.fetch_many_raw
-    |> Task.map((rows) -> { List.map(rows, value_of) })
+  Sql.fetch_decoded(render(q, [e.sql], e.params), Decode.index(0, Decode.decoder))
     |> Task.map_error(from_sql_error)
 end
 
 
-def value_of(r: ValueRow(a)) -> a
-  r.value
-end
-
-

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

@@ -12,7 +12,7 @@ module Sql.Write exposing (
   insert,
   insert_all,
   Stamped,
-  returning_with,
+  returning,
   timestamped,
   to_sql,
   update,
@@ -37,7 +37,7 @@ import Sql exposing (
   to_assigns,
 )
 import Sql.Query exposing (Query)
-import Decode exposing (Value)
+import Decode exposing (Decoder, Value)
 import Encode
 
 
@@ -87,6 +87,11 @@ def do_update(build: s -> List(Assignment)) -> Action(s)
 end
 
 
+def no_returning -> Selector(Int)
+  Selector([], [], Decode.fail("a write without RETURNING has no rows"))
+end
+
+
 def insert(value: a, t: Table(c, m, k, o, r, s)) -> Write(Int, c, s)
   Write(
     InsertK,
@@ -95,7 +100,7 @@ def insert(value: a, t: Table(c, m, k, o, r, s)) -> Write(Int, c, s)
     t.set_cols,
     [to_assigns(value)],
     [],
-    Selector([], []),
+    no_returning,
     Nothing,
     Nothing,
   )
@@ -110,7 +115,7 @@ def insert_all(values: List(a), t: Table(c, m, k, o, r, s)) -> Write(Int, c, s)
     t.set_cols,
     List.map(values, (v) -> { to_assigns(v) }),
     [],
-    Selector([], []),
+    no_returning,
     Nothing,
     Nothing,
   )
@@ -125,7 +130,7 @@ def update(value: a, t: Table(c, m, k, o, r, s), key: k) -> Write(Int, c, s)
     t.set_cols,
     [without_created_at(without_key(t.pk, to_assigns(value)))],
     [key_predicate(t.pk, key)],
-    Selector([], []),
+    no_returning,
     Nothing,
     Nothing,
   )
@@ -140,7 +145,7 @@ def delete(t: Table(c, m, k, o, r, s), key: k) -> Write(Int, c, s)
     t.set_cols,
     [],
     [key_predicate(t.pk, key)],
-    Selector([], []),
+    no_returning,
     Nothing,
     Nothing,
   )
@@ -177,7 +182,7 @@ def update_all(
     t.set_cols,
     [build(cols_, t.set_cols)],
     [pred],
-    Selector([], []),
+    no_returning,
     Nothing,
     Nothing,
   )
@@ -194,7 +199,7 @@ def update_many(rows_: List((k, a)), t: Table(c, m, k, o, r, s)) -> Write(Int, c
     t.set_cols,
     [source_assigns(t.pk, rows)],
     [pk_join(t.alias_, t.pk.columns)],
-    Selector([], []),
+    no_returning,
     Just(source_of(t.name, rows)),
     Nothing,
   )
@@ -280,7 +285,7 @@ def delete_all(t: Table(c, m, k, o, r, s), pred_fn: c -> Expr(Bool)) -> Write(In
     t.set_cols,
     [],
     [pred],
-    Selector([], []),
+    no_returning,
     Nothing,
     Nothing,
   )
@@ -303,7 +308,7 @@ def on_conflict(m: Write(ret, c, s), u: Unique(c, uk), action: Action(s)) -> Wri
 end
 
 
-def returning_with(m: Write(a, c, s), build: c -> Query(Selector(b))) -> Write(b, c, s)
+def returning(m: Write(a, c, s), build: c -> Query(Selector(b))) -> Write(b, c, s)
   Write(
     m.kind,
     m.table,
@@ -607,12 +612,15 @@ end
 # insert, the new state of an update. A write with no `returning` selects
 # nothing, so this errors with `NotFound`.
 def fetch_one(m: Write(ret, c, s)) -> Task(ret, e)
-  to_sql(m) |> Sql.fetch_one_raw |> Task.map_error(from_sql_error)
+  Sql.fetch_decoded(to_sql(m), m.returning_selector.decoder)
+    |> Task.and_then(Sql.exactly_one)
+    |> Task.map_error(from_sql_error)
 end
 
 
 # The same for a write that returns many rows, as `insert_all` and
 # `update_all` do.
 def fetch_many(m: Write(ret, c, s)) -> Task(List(ret), e)
-  to_sql(m) |> Sql.fetch_many_raw |> Task.map_error(from_sql_error)
+  Sql.fetch_decoded(to_sql(m), m.returning_selector.decoder)
+    |> Task.map_error(from_sql_error)
 end

data/lib/jade-sql/sql.jd

@@ -1,6 +1,7 @@
 module Sql exposing (
   Assignable,
   Assignment(..),
+  DateUnit(..),
   Col(..),
   Expr(..),
   NoJoins,
@@ -28,16 +29,20 @@ module Sql exposing (
   array_overlaps,
   array_remove,
   assign,
+  avg,
   coalesce,
   column,
   columns,
   count,
   count_all,
+  count_distinct,
   db_now,
   eq,
+  exactly_one,
   excluded,
   execute,
   execute_raw,
+  fetch_decoded,
   fetch_many_raw,
   fetch_one_raw,
   gt,
@@ -45,12 +50,16 @@ module Sql exposing (
   ilike,
   is_not_null,
   is_null,
+  json_text,
   jsonb_contains,
   jsonb_path_exists,
   left_columns,
   like,
+  lower,
   lt,
   lte,
+  max,
+  min,
   neg,
   neq,
   no_joins,
@@ -65,16 +74,21 @@ module Sql exposing (
   table,
   to_assigns,
   transaction,
+  trunc_date,
   unique,
   unkeyed,
   unsafe_cast,
+  upper,
   val,
   within,
 )
 
 import Encode exposing (Encodable, encode)
 import Decode exposing (Decodable, Decoder, Value)
+import Calendar exposing (Date)
 import Clock exposing (Instant)
+import Decimal exposing (Decimal)
+import Show exposing (show)
 
 
 struct Expr(a) = {
@@ -85,7 +99,8 @@ struct Expr(a) = {
 
 struct Selector(a) = {
   columns_sql: List(String),
-  params: List(Value)
+  params: List(Value),
+  decoder: Decoder(a)
 }
 
 
@@ -289,7 +304,7 @@ end
 # 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")
+#   select(Row(_, _)) |> field(c.id) |> field(val("patient"))
 #   Json.object(Row(_)) |> Json.prop("kind", val("patient"))
 #
 # Every library that has this calls it `val`, and none of them has a word for
@@ -437,6 +452,74 @@ def neg(e: Expr(Int)) -> Expr(Int)
 end
 
 
+# Aggregates over no rows are NULL, so all but the counts come back in `Maybe`.
+def max(e: Expr(a)) -> Expr(Maybe(a))
+  Expr("MAX(" ++ e.sql ++ ")", e.params)
+end
+
+
+def min(e: Expr(a)) -> Expr(Maybe(a))
+  Expr("MIN(" ++ e.sql ++ ")", e.params)
+end
+
+
+# Postgres averages integers as `numeric`, which is exact.
+def avg(e: Expr(Int)) -> Expr(Maybe(Decimal))
+  Expr("AVG(" ++ e.sql ++ ")", e.params)
+end
+
+
+def count_distinct(e: Expr(a)) -> Expr(Int)
+  Expr("COUNT(DISTINCT " ++ e.sql ++ ")", e.params)
+end
+
+
+def lower(e: Expr(String)) -> Expr(String)
+  Expr("LOWER(" ++ e.sql ++ ")", e.params)
+end
+
+
+def upper(e: Expr(String)) -> Expr(String)
+  Expr("UPPER(" ++ e.sql ++ ")", e.params)
+end
+
+
+type DateUnit
+  = Year
+  | Quarter
+  | Month
+  | Week
+  | Day
+
+
+# The first day of the unit `d` falls in. `date_trunc` has no date form: the
+# date goes in as a timestamp, which a bound one would not name on its own, and
+# the result comes back to a date.
+def trunc_date(unit: DateUnit, d: Expr(Date)) -> Expr(Date)
+  Expr(
+    "date_trunc('" ++ unit_name(unit) ++ "', (" ++ d.sql ++ ")::timestamp)::date",
+    d.params,
+  )
+end
+
+
+def unit_name(unit: DateUnit) -> String
+  case unit
+  in Year then "year"
+  in Quarter then "quarter"
+  in Month then "month"
+  in Week then "week"
+  in Day then "day"
+  end
+end
+
+
+# A key's text out of a JSON object, `NULL` where the key is absent.
+def json_text(col: Expr(Value), key: String) -> Expr(Maybe(String))
+  Expr("(" ++ col.sql ++ " ->> ?)", col.params ++ [encode(key)])
+end
+
+
 # PG array predicates.
 # All bind the array as a single param (`$1`) instead of expanding to
 # `ARRAY[$1,...,$N]`. The pg driver maps Ruby Array → PG array; PG
@@ -701,6 +784,7 @@ uses JadeSql::Runtime with
   port_execute_count : String, List(Value) -> Task(Int, SqlError),
   port_execute_one : String, List(Value) -> Task(a, SqlError),
   port_execute_many : String, List(Value) -> Task(List(a), SqlError),
+  port_execute_rows : String, List(Value) -> Task(Value, SqlError),
   port_begin : Task(Bool, SqlError),
   port_commit : Task(Bool, SqlError),
   port_rollback : Task(Bool, SqlError)
@@ -725,6 +809,32 @@ def fetch_many_raw(p: (String, List(Value))) -> Task(List(a), SqlError)
 end
 
 
+# The rows as arrays, each through `decoder`: a projection decodes by
+# position, so a column's name never has to match the field it lands in.
+def fetch_decoded(p: (String, List(Value)), decoder: Decoder(a)) -> Task(List(a), SqlError)
+  (sql, params) = p
+
+  port_execute_rows(sql, params)
+    |> Task.and_then((rows) -> { decode_rows(rows, decoder) })
+end
+
+
+def decode_rows(rows: Value, decoder: Decoder(a)) -> Task(List(a), SqlError)
+  Decode.decode(Decode.list(decoder), rows)
+    |> Result.map_error((e) -> { DbError("row did not decode: " ++ show(e)) })
+    |> Task.from_result
+end
+
+
+def exactly_one(rows: List(a)) -> Task(a, SqlError)
+  case rows
+  in [row] then Task.succeed(row)
+  in [] then Task.fail(NotFound)
+  else Task.fail(TooManyRows)
+  end
+end
+
+
 def execute(r: r) -> Task(Int, e)
   to_sql(r) |> execute_raw |> Task.map_error(from_sql_error)
 end

data/lib/jade-sql/version.rb

@@ -1,3 +1,3 @@
 module JadeSql
-  VERSION = '0.9.1'
+  VERSION = '0.10.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jade-sql
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - agustin
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jade-lang