jade-sql 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5986c28a9014fcf2a656282a1c34d0303a2c6e37d10dbb5b1eb8591c5a1ebaf
-  data.tar.gz: 378c771dc40c70f3567727e4475b8383f28a723be48beff82dc5f5c25ea6e8f5
+  metadata.gz: 06d76c59dbdec2e461a437690981df433898e1366503d665d2b10778fa504d48
+  data.tar.gz: 2c608f51a766507d5f9f13df7acce793177d6241e742edf05968eacff8482525
 SHA512:
-  metadata.gz: c09395f48662acf1c6ae08189f700229d03a23dbcfe170725f681094cb76357665dc18775c441eb7961f6afcdc841bf035e4fbe1da4d43e8bfe8d3e23f997af1
-  data.tar.gz: 52fe13eb1ed8ec5c43db442d85923e972b35c26e2be57939e75b8d0f0bb16817ab45404abd3db9ff640b7609e0d4491e199278691c9e07253be97f1bd298a5ed
+  metadata.gz: f87fac54b24c1a530fa20ee750168654ec6c7a20d60dc5f09afb556862a132ae71e3a8c5e1683e041ccd749ca6fd51db3615a04ac6bfc631c03e61fc533fba68
+  data.tar.gz: 8e6fe0954616823a3cf8b44da971562a4cf8fbefa50cad20d66604e77c8c016a6b0c12a5c8e3bbfb5e5c72afe10961db4a4b996bf1b08d22ae4a4b4682068faf

data/docs/building.md

@@ -109,6 +109,23 @@ Notes:
   fills one slot in declared order.
 - `to_sql(q)` returns `(String, List(Value))`.
 
+### Predicates
+
+`eq`, `gt`, `gte`, `lt`, `lte` compare two `Expr(a)` and yield `Expr(Bool)`;
+`is_null` / `is_not_null` take one; `and` joins two; `in_` matches a list.
+`now` is the DB clock (`now()`), for time comparisons:
+
+```jade
+import Sql exposing (column, gt, now, to_expr)
+
+a.starts_at |> gte(to_expr(cutoff))          # a.starts_at >= ?
+column("s", "expires_at") |> gt(now)         # s.expires_at > now()
+```
+
+`now` is `Expr(Instant)` — the *DB* transaction clock, not the app clock.
+It's the right tool for `WHERE` filters; for `created_at`/`updated_at` use
+`Sql.Mutation.timestamped` (below), which uses the app clock like Rails.
+
 ### Sorting and grouping
 
 `order(q, e)` appends an ASC term, `order_desc(q, e)` a DESC term, and
@@ -443,38 +460,25 @@ sparse_changes
 
 ### Timestamps
 
-`Mutation.insert`/`update` emit only the columns you explicitly set —
-they don't auto-fill `created_at` / `updated_at`. Two ways to handle
-NOT NULL timestamp columns:
-
-**1. DB-side defaults (recommended).** Let the schema own timestamp
-policy:
-
-```sql
-ALTER TABLE patients ALTER COLUMN created_at SET DEFAULT now();
-ALTER TABLE patients ALTER COLUMN updated_at SET DEFAULT now();
-```
-
-The mutation builder stays a thin SQL emitter; the DB fills in
-defaults for any column the INSERT didn't list.
-
-**2. Explicit injection in app code.** When you want Jade to carry the
-timestamp values (Rails-style), tack assignments onto the list before
-the call:
+`insert`/`update` emit only the columns you set — they don't auto-fill
+`created_at` / `updated_at`. Opt in per-write with `timestamped`, which
+works like ActiveRecord: `created_at` + `updated_at` on insert, `updated_at`
+only on update.
 
 ```jade
-def with_timestamps(assigns: List(Assignment), now: Instant)
-    -> List(Assignment)
-  assigns ++ [assign("created_at", now), assign("updated_at", now)]
-end
+import Sql.Mutation exposing (insert, timestamped, update)
 
-def create(p: Patient, now: Instant) -> Mutation(Int, PatientsCols)
-  encode_patient(p)
-    |> with_timestamps(now)
-    |> insert(_, patients)
-end
+new_patient |> insert(patients) |> timestamped |> execute   -- both set
+patient     |> update(patients) |> timestamped |> execute   -- updated_at only
+new_import  |> insert(patients) |> execute                  -- no timestamps
 ```
 
+It's opt-in on purpose — backfills, imports, and `touch: false`-style writes
+just omit it (and can set the columns explicitly). The value is the **app
+clock** at execute time (set in Ruby, the same clock Rails uses, so
+`travel_to`/Timecop freeze it), and `created_at` == `updated_at` on an
+insert. No schema changes and no DB-side `DEFAULT` needed.
+
 ### UUIDs
 
 `Sql.Uuid` defines an opaque `Uuid` type plus generation/parse helpers.

data/docs/running.md

@@ -45,6 +45,9 @@ at the boundary.
 - `DbError(String)` — AR `StatementInvalid` message
 - `NotFound` — `fetch_one` with zero rows
 - `NotUnique` — `fetch_one` with more than one row
+- `Conflict(String)` — a write hit a unique index; the `String` is the
+  violated constraint name (e.g. `users_email_key`), so you can route it to a
+  field error instead of string-matching a `DbError` message
 
 A decode mismatch (column type doesn't match the field type) raises on
 the Ruby side rather than becoming a recoverable error — schema drift is

data/lib/jade-sql/runtime.rb

@@ -12,7 +12,9 @@ module JadeSql
     task :port_execute_count do |t, pair|
       sql, params = pair._1, pair._2
       conn = ::ActiveRecord::Base.connection
-      t.ok(conn.exec_update(adapt_sql(sql, conn), "Jade", typed_params(params, conn)))
+      t.ok(conn.exec_update(adapt_sql(fill_now(sql), conn), "Jade", typed_params(params, conn)))
+    rescue ::ActiveRecord::RecordNotUnique => e
+      t.err(JadeSql::SqlErrors.conflict(constraint_name(e)))
     rescue ::ActiveRecord::StatementInvalid => e
       t.err(JadeSql::SqlErrors.db_error(e.message))
     end
@@ -20,12 +22,14 @@ module JadeSql
     task :port_execute_one do |t, pair|
       sql, params = pair._1, pair._2
       conn = ::ActiveRecord::Base.connection
-      rows = conn.exec_query(adapt_sql(sql, conn), "Jade", typed_params(params, conn)).to_a
+      rows = conn.exec_query(adapt_sql(fill_now(sql), conn), "Jade", typed_params(params, conn)).to_a
       case rows.length
       when 0 then t.err(JadeSql::SqlErrors.not_found)
       when 1 then t.ok(coerce_row(rows.first))
       else        t.err(JadeSql::SqlErrors.not_unique)
       end
+    rescue ::ActiveRecord::RecordNotUnique => e
+      t.err(JadeSql::SqlErrors.conflict(constraint_name(e)))
     rescue ::ActiveRecord::StatementInvalid => e
       t.err(JadeSql::SqlErrors.db_error(e.message))
     end
@@ -33,8 +37,10 @@ module JadeSql
     task :port_execute_many do |t, pair|
       sql, params = pair._1, pair._2
       conn = ::ActiveRecord::Base.connection
-      rows = conn.exec_query(adapt_sql(sql, conn), "Jade", typed_params(params, conn)).to_a
+      rows = conn.exec_query(adapt_sql(fill_now(sql), conn), "Jade", typed_params(params, conn)).to_a
       t.ok(rows.map { |row| coerce_row(row) })
+    rescue ::ActiveRecord::RecordNotUnique => e
+      t.err(JadeSql::SqlErrors.conflict(constraint_name(e)))
     rescue ::ActiveRecord::StatementInvalid => e
       t.err(JadeSql::SqlErrors.db_error(e.message))
     end
@@ -160,6 +166,32 @@ module JadeSql
       raw == "NULL" ? nil : raw
     end
 
+    # The constraint/index name behind a RecordNotUnique, so callers can route
+    # by which unique index was violated. PG reports it in the error's
+    # diagnostics; other adapters (or a missing name) fall back to "".
+    def self.constraint_name(error)
+      cause = error.cause
+      return "" unless defined?(::PG::Result) && cause.respond_to?(:result) && cause.result
+
+      cause.result.error_field(::PG::Result::PG_DIAG_CONSTRAINT_NAME) || ""
+    rescue StandardError
+      ""
+    end
+
+    # Sql.Mutation.timestamped emits "$JADE_SQL_NOW$" where created_at /
+    # updated_at go. Swap it for one UTC timestamp literal per statement,
+    # computed here — the app clock, so it moves with travel_to/Timecop
+    # (unlike DB now()). The token lives in SQL we generate, never in a
+    # bound value, so it can't collide with user data.
+    NOW_TOKEN = "$JADE_SQL_NOW$"
+
+    def self.fill_now(sql)
+      return sql unless sql.include?(NOW_TOKEN)
+
+      stamp = "'#{::Time.now.utc.strftime('%Y-%m-%d %H:%M:%S.%6N+00')}'"
+      sql.gsub(NOW_TOKEN) { stamp }
+    end
+
     # Sql renders `?` placeholders uniformly. AR's exec_query/exec_update
     # path on the PG adapter expects `$1, $2, …` — there is no `?`-to-`$n`
     # rewrite at that layer. SQLite and MySQL accept `?` directly, so this

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

@@ -5,13 +5,14 @@ module Sql.Mutation exposing (
   insert,
   insert_all,
   returning,
+  timestamped,
   to_sql,
   update,
   update_all,
 )
 
 import Sql exposing (
-  Assignment,
+  Assignment(..),
   Expr(..),
   Renderable,
   Selector(..),
@@ -132,6 +133,40 @@ def returning(m: Mutation(a, c), build: c -> Q(Selector(b))) -> Mutation(b, c)
 end
 
 
+# Opt-in ActiveRecord-style timestamps: fills created_at + updated_at on
+# insert and updated_at on update, with the app clock at execute time.
+# The "$JADE_SQL_NOW$" token carries no param; the runtime swaps it for a
+# single UTC timestamp literal per statement (so created_at == updated_at).
+# A plain `insert`/`update` without this stays timestamp-free.
+def timestamped(m: Mutation(ret, c)) -> Mutation(ret, c)
+  case m.kind
+  in InsertK then with_rows(m, List.map(m.rows, append_insert_stamps))
+  in UpdateK then with_rows(m, List.map(m.rows, append_update_stamps))
+  in DeleteK then m
+  end
+end
+
+
+def append_insert_stamps(row: List(Assignment)) -> List(Assignment)
+  row ++ [now_assignment("created_at"), now_assignment("updated_at")]
+end
+
+
+def append_update_stamps(row: List(Assignment)) -> List(Assignment)
+  row ++ [now_assignment("updated_at")]
+end
+
+
+def now_assignment(col: String) -> Assignment
+  Assignment(col, "$JADE_SQL_NOW$", [])
+end
+
+
+def with_rows(m: Mutation(ret, c), rows: List(List(Assignment))) -> Mutation(ret, c)
+  Mutation(m.kind, m.table, m.cols, rows, m.wheres, m.returning_selector)
+end
+
+
 def pk_predicate(cols: List(String), values: List(Value)) -> Expr(Bool)
   sql = cols
     |> List.map((col) -> { col ++ " = ?" })

data/lib/jade-sql/sql.jd

@@ -32,13 +32,18 @@ module Sql exposing (
   fetch_many_raw,
   fetch_one,
   fetch_one_raw,
+  gt,
+  gte,
   in_,
   is_not_null,
   is_null,
   jsonb_contains,
   jsonb_path_exists,
+  lt,
+  lte,
   maybe_columns,
   neg,
+  now,
   nullable,
   pk_values,
   render,
@@ -52,6 +57,7 @@ module Sql exposing (
 
 import Encode exposing (Encodable, encode)
 import Decode exposing (Decodable, Decoder, Value)
+import Clock exposing (Instant)
 
 
 struct Expr(a) = {
@@ -139,11 +145,38 @@ def to_expr(value: a) -> Expr(a)
 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)
+  Expr("now()", [])
+end
+
+
 def eq(left: Expr(a), right: Expr(a)) -> Expr(Bool)
   Expr(left.sql ++ " = " ++ right.sql, left.params ++ right.params)
 end
 
 
+def gt(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  Expr(left.sql ++ " > " ++ right.sql, left.params ++ right.params)
+end
+
+
+def gte(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  Expr(left.sql ++ " >= " ++ right.sql, left.params ++ right.params)
+end
+
+
+def lt(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  Expr(left.sql ++ " < " ++ right.sql, left.params ++ right.params)
+end
+
+
+def lte(left: Expr(a), right: Expr(a)) -> Expr(Bool)
+  Expr(left.sql ++ " <= " ++ right.sql, left.params ++ right.params)
+end
+
+
 def is_null(e: Expr(a)) -> Expr(Bool)
   Expr(e.sql ++ " IS NULL", e.params)
 end
@@ -320,10 +353,14 @@ def aliased(t: Table(c, m), alias_: String) -> Table(c, m)
 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.
 type SqlError
   = DbError(String)
   | NotFound
   | NotUnique
+  | Conflict(String)
 
 
 implements Encodable(SqlError) with
@@ -336,6 +373,7 @@ def encode_sql_error(e: SqlError) -> Value
   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)])
   end
 end
 
@@ -350,6 +388,7 @@ def sql_error_decoder -> Decoder(SqlError)
     |> Decode.variant("DbError", db_error_decoder)
     |> Decode.variant("NotFound", Decode.succeed(NotFound))
     |> Decode.variant("NotUnique", Decode.succeed(NotUnique))
+    |> Decode.variant("Conflict", conflict_decoder)
 end
 
 
@@ -358,6 +397,11 @@ def db_error_decoder -> Decoder(SqlError)
 end
 
 
+def conflict_decoder -> Decoder(SqlError)
+  Decode.index(1, Decode.string) |> Decode.map(Conflict)
+end
+
+
 uses JadeSql::Runtime with
   port_execute_count : (String, List(Value)) -> Task(Int, SqlError),
   port_execute_one : (String, List(Value)) -> Task(a, SqlError),

data/lib/jade-sql/version.rb

@@ -1,3 +1,3 @@
 module JadeSql
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/jade-sql.rb

@@ -14,9 +14,10 @@ module JadeSql
     NOT_FOUND  = ["NotFound"].freeze
     NOT_UNIQUE = ["NotUnique"].freeze
 
-    def self.db_error(msg) = ["DbError", msg]
-    def self.not_found     = NOT_FOUND
-    def self.not_unique    = NOT_UNIQUE
+    def self.db_error(msg)  = ["DbError", msg]
+    def self.not_found      = NOT_FOUND
+    def self.not_unique     = NOT_UNIQUE
+    def self.conflict(name) = ["Conflict", name]
   end
 end
 
@@ -26,11 +27,13 @@ module Sql
     class DbError   < Error; end
     class NotFound  < Error; end
     class NotUnique < Error; end
+    class Conflict  < Error; end
 
     BY_TAG = {
       "DbError"   => DbError,
       "NotFound"  => NotFound,
       "NotUnique" => NotUnique,
+      "Conflict"  => Conflict,
     }.freeze
   end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jade-sql
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - agustin
 bindir: exe
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jade-lang