jade-sql 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5b511ba76f20947fbccd7ebb7800746ca4ff7deaa7db27f02c0f9e0c2063fa5
-  data.tar.gz: 4f280996410b7a415c14ce431879074d3ea14db4da9305358595738a8f31f674
+  metadata.gz: 06d76c59dbdec2e461a437690981df433898e1366503d665d2b10778fa504d48
+  data.tar.gz: 2c608f51a766507d5f9f13df7acce793177d6241e742edf05968eacff8482525
 SHA512:
-  metadata.gz: df9d4acfa3ac509e4a9730a727befae3197cdd9abb9959c60d107191fb574898e1d75ca23eb7814ab5a6b80a81b0e7e5e2d2131954a47053726c0a1e3354e720
-  data.tar.gz: 582f7bcacd1543c00d6efc7710762fe1b6b9a388c8e71c2fedaf006229d3ac7bce49510473e8ae3b97773314c6ead9445b5f38c8d6aeb678cfbc6c573adae763
+  metadata.gz: f87fac54b24c1a530fa20ee750168654ec6c7a20d60dc5f09afb556862a132ae71e3a8c5e1683e041ccd749ca6fd51db3615a04ac6bfc631c03e61fc533fba68
+  data.tar.gz: 8e6fe0954616823a3cf8b44da971562a4cf8fbefa50cad20d66604e77c8c016a6b0c12a5c8e3bbfb5e5c72afe10961db4a4b996bf1b08d22ae4a4b4682068faf

data/README.md

@@ -1,5 +1,7 @@
 # jade-sql
 
+[![CI](https://github.com/agustinrhcp/jade-sql/actions/workflows/ci.yml/badge.svg)](https://github.com/agustinrhcp/jade-sql/actions/workflows/ci.yml)
+
 Type-safe SQL for Jade. Builds queries and mutations from a generated
 schema, renders them to `(String, List(Value))`, and runs them against
 ActiveRecord via a Task port that auto-decodes rows into typed Jade

data/docs/building.md

@@ -27,13 +27,23 @@ bundle exec rake jade:schema \
   OUTPUT=app/jade/schema/billing.jd
 ```
 
-Type map: `bigint`/`integer`/`smallint` → `Int`, `varchar`/`text`/`char` →
-`String`, `boolean` → `Bool`, `jsonb`/`json` → `Decode.Value`, `date` →
-`Calendar.Date`, `timestamp` → `Clock.Instant`, `uuid` → `Uuid` (from
-`Sql.Uuid`). Unknown types fail loudly with the table+column name.
-`bytea` and `decimal`/`numeric` aren't wired into the type map yet —
-`bytea` has a natural target in jade's `Bytes`, and a decimal can be
-modeled as a struct of `Int`s.
+Type map: `bigint`/`integer`/`smallint` → `Int`, `numeric`/`decimal` →
+`Decimal` (from `Sql.Decimal`), `double precision`/`real` → `Float`,
+`varchar`/`text`/`char` → `String`, `boolean` → `Bool`, `jsonb`/`json` →
+`Decode.Value`, `date` → `Calendar.Date`, `timestamp` → `Clock.Instant`,
+`uuid` → `Uuid` (from `Sql.Uuid`). Unknown types fail loudly with the
+table+column name.
+
+`numeric`/`decimal` map to `Sql.Decimal` — an exact base-10 value
+(`mantissa * 10^exponent`), never `Float`, so no precision is lost. Genuine
+floating-point columns (`double precision`/`real`) map to `Float`. `bytea`
+isn't mapped yet, though jade's `Bytes` is the natural target.
+
+`Sql.Decimal` implements `Numeric`, so `+`/`-`/`*` work and stay exact.
+Mirroring `BigDecimal`, `/` can't represent a repeating quotient, so it
+rounds half-up to a default scale (use `div(a, b, scale)` for explicit
+control, `round(d, scale)` to round); division by zero raises. `to_i`
+truncates toward zero and `to_float` converts (lossily, on purpose).
 
 For each table, the generator emits:
 
@@ -51,6 +61,24 @@ Strict cols mirror NOT NULL constraints; the maybe version wraps every
 field in `Maybe` for left-join projections. The default alias is the
 table name; override per-call with `aliased` (see joins below).
 
+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:
+
+```jade
+def entries -> Q(Selector(JournalEntriesRow))
+  c <- from(journal_entries)
+  journal_entries_row(c)
+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).
+
 ## Build queries
 
 ```jade
@@ -81,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
@@ -415,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/bin/generate_schema.rb

@@ -23,10 +23,18 @@ module JadeSql
       /\Adate\[\]/ => "List(Calendar.Date)",
       /\Atimestamp\[\]/ => "List(Clock.Instant)",
       /\Auuid\[\]/ => "List(Uuid)",
+      /\Anumeric\[\]/ => "List(Decimal)",
+      /\Adecimal\[\]/ => "List(Decimal)",
+      /\Adouble precision\[\]/ => "List(Float)",
+      /\Areal\[\]/ => "List(Float)",
 
       /\Abigint\b/ => "Int",
       /\Ainteger\b/ => "Int",
       /\Asmallint\b/ => "Int",
+      /\Anumeric\b/ => "Decimal",
+      /\Adecimal\b/ => "Decimal",
+      /\Adouble precision\b/ => "Float",
+      /\Areal\b/ => "Float",
       /\Acharacter varying\b/ => "String",
       /\Avarchar\b/ => "String",
       /\Acharacter\b/ => "String",
@@ -45,16 +53,24 @@ module JadeSql
       "Clock.Instant" => "import Clock",
       "Decode.Value"  => "import Decode",
       "Uuid"          => "import Sql.Uuid exposing(Uuid)",
+      "Decimal"       => "import Sql.Decimal exposing(Decimal)",
     }.freeze
 
+    # Column names that collide with Jade keywords get a trailing underscore
+    # in the struct field; the SQL column reference keeps the real name.
+    RESERVED = %w[
+      type def module import exposing struct interface implements uses
+      case in if then else end with
+    ].freeze
+
     Table = Data.define(:name, :columns, :pk_columns)
     Column = Data.define(:name, :jade_type, :nullable)
 
     def generate(sql, tables: nil, module_name: 'Schema')
-      parsed = parse_tables(sql)
+      bodies = scan_table_bodies(sql)
+      bodies = select_tables(bodies, tables) if tables
       pks = parse_pks(sql)
-      parsed = parsed.map { |t| t.with(pk_columns: pks[t.name] || []) }
-      parsed = filter_tables(parsed, tables) if tables
+      parsed = bodies.map { |name, body| Table[name, parse_columns(body, name), pks[name] || []] }
       format(emit(parsed, module_name))
     end
 
@@ -77,17 +93,18 @@ module JadeSql
 
     private
 
-    def filter_tables(parsed, whitelist)
-      missing = whitelist - parsed.map(&:name)
-      raise "Unknown table(s): #{missing.join(', ')}" if missing.any?
-
-      parsed.select { |t| whitelist.include?(t.name) }
+    # Returns [[name, body], ...] without parsing columns, so the whitelist
+    # can be applied before type-mapping — an unsupported type in a table the
+    # caller didn't ask for shouldn't abort the whole run.
+    def scan_table_bodies(sql)
+      sql.scan(/CREATE TABLE (?:\w+\.)?(\w+)\s*\((.*?)\);/m)
     end
 
-    def parse_tables(sql)
-      sql
-        .scan(/CREATE TABLE (?:\w+\.)?(\w+)\s*\((.*?)\);/m)
-        .map { |name, body| Table[name, parse_columns(body, name), []] }
+    def select_tables(bodies, whitelist)
+      missing = whitelist - bodies.map(&:first)
+      raise "Unknown table(s): #{missing.join(', ')}" if missing.any?
+
+      bodies.select { |name, _| whitelist.include?(name) }
     end
 
     def parse_columns(body, table_name)
@@ -127,17 +144,30 @@ module JadeSql
     def emit(tables, module_name)
       [
         emit_header(tables, module_name),
-        *tables.flat_map { |t| [emit_strict_cols(t), emit_maybe_cols(t), emit_row(t), emit_table_fn(t)] },
+        *tables.flat_map { |t|
+          parts = [emit_strict_cols(t), emit_maybe_cols(t), emit_row(t), emit_table_fn(t)]
+          reserved_cols?(t) ? parts + [emit_row_projector(t)] : parts
+        },
       ].join("\n\n") + "\n"
     end
 
+    def reserved_cols?(t)
+      t.columns.any? { |c| RESERVED.include?(c.name) }
+    end
+
     def emit_header(tables, module_name)
-      exposed = tables
+      projectored = tables.select { |t| reserved_cols?(t) }
+
+      names = tables
         .flat_map { |t| ["#{camel(t.name)}Cols", "Maybe#{camel(t.name)}Cols", "#{camel(t.name)}Row(..)", t.name] }
-        .sort
-        .join(", ")
+      names += projectored.map { |t| "#{t.name}_row" }
+      exposed = names.sort.join(", ")
 
-      imports = ["import Sql exposing(Expr, Table, column, table)", *extra_imports_for(tables)]
+      sql_import = projectored.any? ?
+        "import Sql exposing(Expr, Selector, Table, column, table)" :
+        "import Sql exposing(Expr, Table, column, table)"
+      query_import = projectored.any? ? ["import Sql.Query exposing(Q, field_as, select)"] : []
+      imports = [sql_import, *query_import, *extra_imports_for(tables)]
 
       <<~JADE.strip
         module #{module_name} exposing(#{exposed})
@@ -158,7 +188,7 @@ module JadeSql
 
     def emit_strict_cols(t)
       fields = t.columns
-        .map { |c| "  #{c.name}: Expr(#{c.nullable ? "Maybe(#{c.jade_type})" : c.jade_type})" }
+        .map { |c| "  #{field_name(c.name)}: Expr(#{c.nullable ? "Maybe(#{c.jade_type})" : c.jade_type})" }
         .join(",\n")
 
       "struct #{camel(t.name)}Cols = {\n#{fields}\n}"
@@ -166,7 +196,7 @@ module JadeSql
 
     def emit_maybe_cols(t)
       fields = t.columns
-        .map { |c| "  #{c.name}: Expr(Maybe(#{c.jade_type}))" }
+        .map { |c| "  #{field_name(c.name)}: Expr(Maybe(#{c.jade_type}))" }
         .join(",\n")
 
       "struct Maybe#{camel(t.name)}Cols = {\n#{fields}\n}"
@@ -174,12 +204,16 @@ module JadeSql
 
     def emit_row(t)
       fields = t.columns
-        .map { |c| "  #{c.name}: #{c.nullable ? "Maybe(#{c.jade_type})" : c.jade_type}" }
+        .map { |c| "  #{field_name(c.name)}: #{c.nullable ? "Maybe(#{c.jade_type})" : c.jade_type}" }
         .join(",\n")
 
       "struct #{camel(t.name)}Row = {\n#{fields}\n}"
     end
 
+    def field_name(name)
+      RESERVED.include?(name) ? "#{name}_" : name
+    end
+
     def emit_table_fn(t)
       strict_fields = t.columns.map { |c| "column(a, #{c.name.inspect})" }.join(", ")
       maybe_fields = t.columns.map { |c| "column(a, #{c.name.inspect})" }.join(", ")
@@ -198,6 +232,27 @@ 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:
+    #   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})" }
+        .join("\n")
+
+      <<~JADE.strip
+        def #{t.name}_row(c: #{klass}Cols) -> Q(Selector(#{klass}Row))
+          select(#{klass}Row(#{holes}))
+        #{projections}
+        end
+      JADE
+    end
+
     def camel(snake)
       snake.split('_').map(&:capitalize).join
     end

data/lib/jade-sql/runtime.rb

@@ -1,4 +1,5 @@
 require 'date'
+require 'bigdecimal'
 require 'jade/tasks'
 
 # Opt-in runtime: requires ActiveRecord. The Jade-side Sql.Run module
@@ -11,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
@@ -19,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
@@ -32,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
@@ -73,6 +80,10 @@ module JadeSql
     # when AR's exec_query path doesn't run the OID typecast. Parse them
     # back to Ruby Arrays so `Decode.list(...)` works the same as for any
     # other List(a) column.
+    #
+    # numeric/decimal columns come back as ::BigDecimal; the schema generator
+    # maps them to Sql.Decimal, whose decoder reads the exact
+    # "<mantissa>e<exponent>" wire form. Float would lose precision, so don't.
     def self.coerce_row(row)
       row.transform_values { |v| coerce_value(v) }
     end
@@ -81,12 +92,28 @@ module JadeSql
       case v
       when ::Date             then v.iso8601
       when ::Time, ::DateTime then v.iso8601
+      when ::BigDecimal       then decimal_wire(v)
       when ::String
         pg_array_literal?(v) ? parse_pg_array(v) : v
       else v
       end
     end
 
+    # ::BigDecimal -> "<mantissa>e<exponent>" with value = mantissa * 10^exp,
+    # exactly (BigDecimal#split gives sign, significant digits, and a base-10
+    # exponent). Matches the wire form Sql.Decimal's decoder parses.
+    #
+    # 'NaN'/'Infinity'::numeric are legal Postgres values that Sql.Decimal
+    # can't represent; fail loudly rather than silently decode them as 0.
+    def self.decimal_wire(v)
+      raise ArgumentError, "non-finite numeric: #{v}" unless v.finite?
+
+      sign, digits, _base, exp = v.split
+      mantissa = sign * digits.to_i
+      exponent = exp - digits.length
+      "#{mantissa}e#{exponent}"
+    end
+
     # PG arrays render as `{}`, `{a,b,c}`, `{"a,b","c"}`, with NULL as
     # bare `NULL`. Quoted elements escape `"` and `\` with backslashes.
     # The JSON-object guard rejects `{"key":...}` shapes — they share the
@@ -139,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/decimal.jd

@@ -0,0 +1,193 @@
+module Sql.Decimal exposing (
+  Decimal,
+  decimal,
+  div,
+  exponent,
+  mantissa,
+  parse,
+  round,
+  to_float,
+  to_i,
+)
+
+import Decode exposing (Decodable, Decoder)
+import Encode exposing (Encodable)
+
+
+# An exact base-10 decimal: value = mantissa * 10 ^ exponent. Lossless for
+# Postgres numeric/decimal — no Float rounding. The wire form is
+# "<mantissa>e<exponent>" (e.g. "175e-3"), which Postgres casts to numeric
+# exactly and which decodes back without parsing a decimal point.
+type Decimal = Decimal(Int, Int)
+
+
+def decimal(m: Int, e: Int) -> Decimal
+  Decimal(m, e)
+end
+
+
+def mantissa(d: Decimal) -> Int
+  Decimal(m, _) = d
+
+  m
+end
+
+
+def exponent(d: Decimal) -> Int
+  Decimal(_, e) = d
+
+  e
+end
+
+
+def pow10(n: Int) -> Int
+  n <= 0 ? 1 : 10 * pow10(n - 1)
+end
+
+
+def abs(x: Int) -> Int
+  x < 0 ? 0 - x : x
+end
+
+
+# Integer division, rounding ties half away from zero — i.e. Java's HALF_UP
+# and Ruby BigDecimal's default mode (2.5 -> 3, -2.5 -> -3). Rounds the
+# magnitude, then re-applies the sign. A zero `den` raises through Int `/`.
+def round_div(num: Int, den: Int) -> Int
+  negative = not ((num < 0) == (den < 0))
+  n = abs(num)
+  d = abs(den)
+  q = n / d
+  r = n - q * d
+  rounded = (2 * r) >= d ? q + 1 : q
+
+  negative ? 0 - rounded : rounded
+end
+
+
+def trunc_div(num: Int, den: Int) -> Int
+  q = abs(num) / abs(den)
+
+  num < 0 ? 0 - q : q
+end
+
+
+# `+` `-` `*` are exact. `+`/`-` line the operands up on the smaller exponent
+# first; `*` adds exponents.
+def add(a: Decimal, b: Decimal) -> Decimal
+  Decimal(ma, ea) = a
+  Decimal(mb, eb) = b
+  e = ea < eb ? ea : eb
+
+  Decimal((ma * pow10(ea - e)) + (mb * pow10(eb - e)), e)
+end
+
+
+def sub(a: Decimal, b: Decimal) -> Decimal
+  Decimal(ma, ea) = a
+  Decimal(mb, eb) = b
+  e = ea < eb ? ea : eb
+
+  Decimal((ma * pow10(ea - e)) - (mb * pow10(eb - e)), e)
+end
+
+
+def mul(a: Decimal, b: Decimal) -> Decimal
+  Decimal(ma, ea) = a
+  Decimal(mb, eb) = b
+
+  Decimal(ma * mb, ea + eb)
+end
+
+
+# a / b rounded half-up to `scale` decimal places — like Java's
+# BigDecimal.divide(divisor, scale, HALF_UP). Division by zero raises.
+def div(a: Decimal, b: Decimal, scale: Int) -> Decimal
+  Decimal(ma, ea) = a
+  Decimal(mb, eb) = b
+  k = (ea - eb) + scale
+  num = k >= 0 ? ma * pow10(k) : ma
+  den = k >= 0 ? mb : mb * pow10(0 - k)
+
+  Decimal(round_div(num, den), 0 - scale)
+end
+
+
+# The Numeric `/`: like Ruby's BigDecimal `/`, it can't be exact for a
+# repeating quotient (1/3), so it rounds half-up to a generous default scale.
+def divide(a: Decimal, b: Decimal) -> Decimal
+  div(a, b, 32)
+end
+
+
+implements Numeric(Decimal) with
+  (+): add,
+  (-): sub,
+  (*): mul,
+  (/): divide
+end
+
+
+# Round to `scale` decimal places, half-up. Fewer places than the value
+# already has are left untouched.
+def round(d: Decimal, scale: Int) -> Decimal
+  Decimal(m, e) = d
+  shift = e + scale
+
+  shift >= 0 ? d : Decimal(round_div(m, pow10(0 - shift)), 0 - scale)
+end
+
+
+# Truncates toward zero (drops the fractional part).
+def to_i(d: Decimal) -> Int
+  Decimal(m, e) = d
+
+  e >= 0 ? m * pow10(e) : trunc_div(m, pow10(0 - e))
+end
+
+
+def to_float(d: Decimal) -> Float
+  Decimal(m, e) = d
+
+  e >= 0
+    ? Basics.to_float(m * pow10(e))
+    : Basics.to_float(m) / Basics.to_float(pow10(0 - e))
+end
+
+
+def to_wire(d: Decimal) -> String
+  Decimal(m, e) = d
+
+  String.from_int(m) ++ "e" ++ String.from_int(e)
+end
+
+
+def parse(s: String) -> Maybe(Decimal)
+  case String.split(s, "e")
+  in [m, e]
+    String.to_int(m)
+      |> Maybe.and_then((mi) -> {
+        String.to_int(e) |> Maybe.map((ei) -> { Decimal(mi, ei) })
+      })
+
+  else Nothing
+  end
+end
+
+
+def decimal_decoder(s: String) -> Decoder(Decimal)
+  case parse(s)
+  in Just(d) then Decode.succeed(d)
+  in Nothing then Decode.fail("invalid decimal: " ++ s)
+  end
+end
+
+
+implements Decodable(Decimal) with
+  decoder: -> { Decode.string |> Decode.and_then(decimal_decoder) }
+end
+
+
+implements Encodable(Decimal) with
+  encoder: (d) -> { Encode.string(to_wire(d)) }
+end

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/query.jd

@@ -1,6 +1,7 @@
 module Sql.Query exposing (
   Q,
   field,
+  field_as,
   from,
   group,
   join,
@@ -235,6 +236,23 @@ def field(qs: Q(Selector(a -> b)), e: Expr(a)) -> Q(Selector(b))
 end
 
 
+def field_as(qs: Q(Selector(a -> b)), e: Expr(a), name: String) -> Q(Selector(b))
+  Q(
+    qs.tables,
+    qs.joins,
+    qs.wheres,
+    qs.groups,
+    qs.orders,
+    qs.limit_,
+    qs.offset_,
+    Selector(
+      qs.result.columns_sql ++ [e.sql ++ " AS " ++ name],
+      qs.result.params ++ e.params,
+    ),
+  )
+end
+
+
 def join_keyword(k: JoinKind) -> String
   case k
   in InnerJ then "INNER JOIN"

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.1.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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - agustin
 bindir: exe
 cert_chain: []
-date: 2026-06-14 00:00:00.000000000 Z
+date: 2026-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jade-lang
@@ -42,6 +42,7 @@ files:
 - lib/jade-sql/bin/generate_schema.rb
 - lib/jade-sql/runtime.rb
 - lib/jade-sql/sql.jd
+- lib/jade-sql/sql/decimal.jd
 - lib/jade-sql/sql/loader.jd
 - lib/jade-sql/sql/mutation.jd
 - lib/jade-sql/sql/query.jd