jade-sql 0.6.0 → 0.8.0

data/lib/jade-sql/schema_drift.rb

@@ -0,0 +1,115 @@
+module JadeSql
+  # What a checked-in schema.jd says against what the database says now.
+  #
+  # The generator reads `structure.sql` and nothing else, so a schema that
+  # was not regenerated after a migration describes a database that no
+  # longer exists, and every type built on it is wrong in a way the
+  # compiler cannot see.
+  module SchemaDrift
+    extend self
+
+    Report = Data.define(:added, :removed, :changed) do
+      def any?
+        [added, removed, changed].any?(&:any?)
+      end
+
+      def to_s
+        [
+          'schema.jd no longer matches the database:',
+          '',
+          *line('in the database, missing here', added),
+          *line('here, gone from the database', removed),
+          *line('different', changed),
+          '',
+          'Regenerate it with `jade-sql schema`.',
+        ].join("\n")
+      end
+
+      private
+
+      def line(label, names)
+        names.empty? ? [] : ["  #{label}: #{names.join(', ')}"]
+      end
+    end
+
+    # Both sides are module name to source, since a schema is a module per
+    # enum plus the root one. A module the database no longer calls for is
+    # itself a difference, so the comparison is per module rather than over
+    # everything concatenated.
+    def between(generated, existing)
+      names = generated.keys | existing.keys
+      tables = names
+        .flat_map { table_names(generated[it].to_s) + table_names(existing[it].to_s) }
+        .uniq
+
+      names
+        .map { module_report(generated[it], existing[it], it, tables) }
+        .then { |reports| merge(reports) }
+    end
+
+    private
+
+    # A module present on one side only is reported whole, under its own name.
+    # Otherwise the definitions inside it are compared and grouped by table.
+    def module_report(from_db, on_disk, name, tables)
+      case [from_db, on_disk]
+      in [String, nil] then Report[[name], [], []]
+      in [nil, String] then Report[[], [name], []]
+      in [String, String] then report(definitions(from_db), definitions(on_disk), tables)
+      end
+    end
+
+    def merge(reports)
+      Report[
+        reports.flat_map(&:added).uniq.sort,
+        reports.flat_map(&:removed).uniq.sort,
+        reports.flat_map(&:changed).uniq.sort,
+      ]
+    end
+
+    def report(from_db, on_disk, tables)
+      Report[
+        grouped(from_db.keys - on_disk.keys, tables),
+        grouped(on_disk.keys - from_db.keys, tables),
+        grouped((from_db.keys & on_disk.keys).select { from_db[it] != on_disk[it] }, tables),
+      ]
+    end
+
+    # One table produces eight definitions, and a report naming all eight
+    # says less than one naming the table.
+    def grouped(names, tables)
+      names.map { table_for(it, tables) || it }.uniq.sort
+    end
+
+    def table_for(name, tables)
+      name
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+        .then { |snake| tables.select { snake.include?(it) } }
+        .max_by(&:length)
+    end
+
+    # A table function returns the per-table alias rather than `Table(...)`
+    # itself, so the aliases are read first and the functions matched against
+    # them. Grouping every definition under its table is the whole point of
+    # the report: one migration renames a column and a dozen structs change.
+    def table_names(source)
+      source
+        .scan(/^type alias (\w+) = Table\(/)
+        .flatten
+        .then { |aliases| source.scan(/^def (\w+) -> (#{Regexp.union(aliases)})$/) }
+        .map(&:first)
+    end
+
+    # Split on what a definition starts with, so the report names the table
+    # or type that moved rather than a line number.
+    DEFINITION = /^(?:def|struct|type)\s+([\w.?!]+)/
+
+    def definitions(source)
+      source
+        .split(/^(?=(?:def|struct|type)\s)/)
+        .filter_map { |chunk| chunk[DEFINITION, 1]&.then { |name| [name, chunk.strip] } }
+        .to_h
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Sql.Expr exposing (
+  eq,
+  gt,
+  gte,
+  ilike,
+  like,
+  lt,
+  lte,
+  neq,
+)
+
+import Sql exposing (Expr(..))
+
+
+# The same comparisons `Sql` exposes, against another expression rather than a
+# value you hold: a second column, `db_now`, an aggregate, anything already
+# built. Import it qualified, so the call says which side it takes:
+#
+#   join(orders, (o) -> { p.id |> Expr.eq(o.person_id) })
+#   where(s.expires_at |> Expr.gt(db_now))
+def eq(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  binary(left, " = ", right)
+end
+
+
+def neq(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  binary(left, " <> ", right)
+end
+
+
+def gt(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  binary(left, " > ", right)
+end
+
+
+def gte(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  binary(left, " >= ", right)
+end
+
+
+def lt(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  binary(left, " < ", right)
+end
+
+
+def lte(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  binary(left, " <= ", right)
+end
+
+
+def like(e: Expr(String), pattern: Expr(String)) -> Expr(Bool)
+  binary(e, " LIKE ", pattern)
+end
+
+
+def ilike(e: Expr(String), pattern: Expr(String)) -> Expr(Bool)
+  binary(e, " ILIKE ", pattern)
+end
+
+
+
+
+def binary(left: Expr(a), op: String, right: Expr(b)) -> Expr(Bool)
+  Expr(left.sql ++ op ++ right.sql, left.params ++ right.params)
+end

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

@@ -0,0 +1,154 @@
+module Sql.Json exposing (
+  Doc,
+  Json,
+  Object,
+  agg,
+  build,
+  coalesce,
+  correlated,
+  empty_list,
+  fetch_many,
+  fetch_one,
+  nested,
+  object,
+  of_array,
+  prop,
+  select,
+  text,
+)
+
+# Builds JSON in the database instead of in Ruby.
+#
+# `Expr(Json(a))` is a SQL expression whose value is JSON text encoding an
+# `a`. `Json(a)` has no exported constructors, so the only way to get one is
+# through this module — which means a projection can't drift from the type it
+# claims to encode without the type checker noticing.
+#
+# The builder mirrors `Sql.Query.select`/`field` deliberately: `object` takes
+# the target constructor as a type witness and `prop` peels one argument per
+# field, so a projection that doesn't match the struct's fields in arity and
+# type fails to compile. The witness is never called — Postgres does the
+# constructing.
+
+import Sql exposing (Expr(..), Selector, SqlError, unsafe_cast)
+import Sql.Query as Query exposing (Query)
+import Decode exposing (Value)
+
+
+type Json(a)
+  = Json
+
+
+struct Object(a) = {
+  pairs: List(String),
+  params: List(Value)
+}
+
+
+def object(make: a -> b) -> Object(a -> b)
+  Object([], [])
+end
+
+
+def prop(o: Object(a -> b), name: String, e: Expr(a)) -> Object(b)
+  Object(o.pairs ++ ["'" ++ name ++ "', " ++ e.sql], o.params ++ e.params)
+end
+
+
+def build(o: Object(a)) -> Expr(Json(a))
+  Expr("json_build_object(" ++ String.join(o.pairs, ", ") ++ ")", o.params)
+end
+
+
+# `json_agg` over an empty group is NULL, not `[]` — the same hazard
+# `Sql.sum` models. Returning Maybe forces the caller through `coalesce`,
+# which makes the empty-collection bug unrepresentable rather than merely
+# documented.
+def agg(e: Expr(Json(a)), by: Expr(b)) -> Expr(Maybe(List(a)))
+  Expr(
+    "json_agg(" ++ e.sql ++ " ORDER BY " ++ by.sql ++ ")",
+    e.params ++ by.params,
+  )
+end
+
+
+# `json_agg` over no rows is NULL, so an aggregation that may match nothing is
+# `Maybe`. This is how it stops being one.
+#
+# `Sql.coalesce` cannot: its default is a value it binds, and the empty JSON
+# array is a literal Postgres has to read as `json` rather than a parameter it
+# would take for an array.
+def coalesce(e: Expr(Maybe(List(a)))) -> Expr(List(a))
+  Expr("COALESCE(" ++ e.sql ++ ", '[]'::json)", e.params)
+end
+
+
+def empty_list -> Expr(List(a))
+  Expr("'[]'::json", [])
+end
+
+
+# Embeds one object as an object-valued field. `agg` is the same placement
+# for a list-valued one: both take a rendered object and hand back the type
+# the target field actually has, because `prop` peels the field's type.
+def nested(e: Expr(Json(a))) -> Expr(a)
+  Expr(e.sql, e.params)
+end
+
+
+# Postgres arrays (`text[]`) are not JSON arrays: without this a `List(a)`
+# column serializes as `{a,b}`. The type is unchanged — this is a rendering
+# concern, not a different value.
+def of_array(e: Expr(List(a))) -> Expr(List(a))
+  Expr("to_jsonb(" ++ e.sql ++ ")", e.params)
+end
+
+
+# A scalar subquery, which is what a preload becomes once the child rows are
+# aggregated. The outer columns are passed in rather than closed over so the
+# correlated scope is a named argument: reusing a builder under a different
+# outer table is then a type error instead of a silently wrong correlation.
+def correlated(outer: c, q: c -> Query(Selector(a))) -> Expr(a)
+  (sql, params) = outer |> q |> Query.to_sql
+
+  Expr("(" ++ sql ++ ")", params)
+end
+
+
+# JSON text that decodes as an `a`. The tag survives the round trip, so a
+# signature can still say what a response contains after the value has
+# stopped being a structure.
+struct Doc(a) = {
+  text: String
+}
+
+
+def text(d: Doc(a)) -> String
+  d.text
+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.
+def select(e: Expr(Json(a))) -> Query(Selector(Doc(a)))
+  Query.select(Doc(_)) |> Query.field_as(unsafe_cast(e), "text")
+end
+
+
+# The parent list is joined here rather than aggregated in SQL: LIMIT applies
+# to an aggregate's single output row, not to the rows feeding it, so a paged
+# json_agg silently returns the wrong page.
+def fetch_many(q: Query(Selector(Doc(a)))) -> Task(Doc(List(a)), SqlError)
+  docs <- Query.fetch_many(q)
+
+  Task.succeed(Doc("[" ++ String.join(List.map(docs, text), ",") ++ "]"))
+end
+
+
+def fetch_one(q: Query(Selector(Doc(a)))) -> Task(Doc(a), SqlError)
+  doc <- Query.fetch_one(q)
+
+  Task.succeed(doc)
+end