briefly 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6c561612c29ff83aaaccdf483e6e563633e54d3dc81c92856857db2f26978b3
-  data.tar.gz: a257e3be54bb8e1bb076009dc5982a7c15a6add60f16225bb774e9e3100f3db4
+  metadata.gz: 74e48b9af79f6a7c0b0f1ff2f601a7718e3a8071d314ee305aa36d0d43db7e77
+  data.tar.gz: fbdfadc26d3c27bd2c7393c1e03771313cf263911dbe392d712868219451d269
 SHA512:
-  metadata.gz: 4496b43e5d42fb6b90d0b8f528092207ff867dfbab5febe1d36b69451c307527bd1a056da118a20a48770b77601c49c8965018fa76c904fc203642a4bd5dc178
-  data.tar.gz: 430188265df3b33c124f90cbf28de0b34f27fa3090174e74d60a94a63d32a97a4bb905bfb46a72e50263977a44c89cecd29a66799f25847e520ee268071ea18e
+  metadata.gz: d62e84d079845a5206409e9d5897b1ab55eadc64676791b07ce178a73135c440714b784439a960a434eb3c84aa355e9265ff0fde2a4ed98259364f9e03424d14
+  data.tar.gz: 40a3f01ecf038df93220d73df675c5e25422d0f483950100d976ecd9e8dc4bf5b01dca50db8fb7b750a2c19ff5b35d0074489bd46a850a991c18dc9cdc29beb0

data/CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## Unreleased
 
+## v0.3.0 (2026-10-06)
+
+### Added
+- `App.db.value(sql, *binds)` returns the first column of the first row through `select_value`, or
+  `nil` for no row or SQL NULL. It uses the same positional and named binds as `select` and `query`.
+
+### Changed
+- **BREAKING:** the minimum supported Ruby is now 3.3. Ruby 3.2 reached end of life in March 2026, and the CI matrix no longer tests it.
+
 ## v0.2.1 (2026-07-31)
 
 No change to `lib/` or `sig/`: this release carries the documentation the gem ships and the process

data/README.md

@@ -6,9 +6,9 @@ A terse, curated facade over your application's most reached-for objects.
 [![CI](https://github.com/svyatov/briefly/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/briefly/actions/workflows/main.yml)
 [![coverage](https://codecov.io/gh/svyatov/briefly/branch/main/graph/badge.svg)](https://app.codecov.io/gh/svyatov/briefly)
 
-- **Ruby 3.2 and up.** Rails is optional: the gem does not declare it, and `Briefly::Rails` is
+- **Ruby 3.3 and up.** Rails is optional: the gem does not declare it, and `Briefly::Rails` is
   autoloaded only when you name it. The Rails packs themselves need Rails 7.2 or newer.
-- **25 shortcuts across six packs.** Config, env, view, db, instrument and reload, each usable on
+- **26 shortcuts across six packs.** Config, env, view, db, instrument and reload, each usable on
   its own or taken together through the `"rails"` umbrella.
 - **One runtime dependency.** [candor](https://github.com/svyatov/candor), which is itself
   dependency-free.
@@ -349,7 +349,7 @@ end
 | `Briefly::Rails::Config` | `"rails/config"` | `config`, `config_x`, `root`, `cache`, `logger`, `credentials`, `error`, `config_for` |
 | `Briefly::Rails::Env` | `"rails/env"` | `env` and its predicates |
 | `Briefly::Rails::View` | `"rails/view"` | `helpers`, `routes`, `renderer`, `render` |
-| `Briefly::Rails::DB` | `"rails/db"` | `connection`, `transaction`, `select`, `query`, `connected_to`, `reading`, `writing` |
+| `Briefly::Rails::DB` | `"rails/db"` | `connection`, `transaction`, `select`, `value`, `query`, `connected_to`, `reading`, `writing` |
 | `Briefly::Rails::Instrument` | `"rails/instrument"` | `instrument` |
 | `Briefly::Rails::Reload` | `"rails/reload"` | none; clears memos on every code reload |
 
@@ -370,6 +370,7 @@ end
 | `connection` | `conn` | forwards keywords and the block to `base.with_connection`, yielding the connection and auto-releasing |
 | `transaction` | `txn` | forwards keywords and the block to `base.transaction` |
 | `select` | | `base.with_connection { \|c\| c.select_all(sql) }`, a read (SELECT) on the cache-aware path |
+| `value` | | `base.with_connection { \|c\| c.select_value(sql) }`, the first column of the first row, or `nil` for no row or SQL NULL |
 | `query` | | `base.with_connection { \|c\| c.exec_query(sql) }`, arbitrary SQL, writes and DDL included |
 | `connected_to` | | forwards every argument to `base.connected_to` (`role:`, `shard:`, `prevent_writes:`) |
 | `reading` | | runs the block under the `:reading` role |
@@ -384,22 +385,27 @@ App = Briefly.define do
 end
 
 App.db.txn { App.db.select("select * from users where id = ?", 1) }
-App.db.conn { |c| c.select_value("select count(*) from users") }
+App.db.value("select count(*) from users")
 ```
 
-`select` and `query` are the two raw-SQL helpers, differing only in which adapter path they take.
+`select`, `value` and `query` are the raw-SQL helpers, differing only in which adapter path they take.
 `select(sql, *binds)` runs a read through `select_all`, the path Rails recommends for a raw SELECT,
 returning an `ActiveRecord::Result` without clearing the query cache. `query(sql, *binds)` runs
 arbitrary SQL through `exec_query`: reads, writes, and DDL all execute. The name tells you which
 you're reaching for; neither polices the SQL it's handed, so `select` will happily run a write you
 give it. The split is name and cache-path, not a runtime guard.
 
-Both sanitize through `base.sanitize_sql_array` when binds are given, and pass the statement through
+`value(sql, *binds)` reads through `select_value` when you need a single result, such as a count.
+It returns the first column of the first row, or `nil` for no row or SQL NULL. Its arguments follow
+the same bind convention as `select` and `query`, rather than the adapter's full signature.
+
+All three sanitize through `base.sanitize_sql_array` when binds are given, and pass the statement through
 untouched when they are not. Positional and named binds both work, from application code:
 
 ```ruby
 App.db.select("select * from users where name like '%ada%'")         # no binds, passed through
 App.db.select("select * from users where id = ?", 123)               # positional
+App.db.value("select count(*) from users where active = :active", active: true)
 App.db.query("update users set active = true where id = :id", id: 1) # named, a write via `query`
 ```
 

data/briefly.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.homepage = "https://github.com/svyatov/briefly"
   spec.license = "MIT"
 
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   spec.require_paths = ["lib"]
   spec.files = Dir["lib/**/*.{rb,tt}"] + Dir["sig/**/*"] +

data/lib/briefly/builder.rb

@@ -9,7 +9,7 @@ module Briefly
     # A validated {#compile!} pass, ready for a {Briefly::Facade} to install. +child_plans+ holds one
     # +[child_facade, child_plan]+ pair per namespace this pass collected, so +__commit+ can walk the
     # tree children first.
-    Plan = Struct.new(:defs, :rescue_entries, :children, :child_plans)
+    Plan = Data.define(:defs, :rescue_entries, :children, :child_plans)
 
     # @return [Briefly::Facade] the facade under construction, for packs that need lifecycle hooks
     attr_reader :facade

data/lib/briefly/rails/db.rb

@@ -16,7 +16,7 @@ module Briefly
     # the captured class would go stale on the first code reload — permanently, since {Reload} clears
     # memos, not closures. A Module is accepted for applications outside the autoloader, with that caveat.
     #
-    # Nothing here memoizes: the block-form shortcuts can't be memoized, and +select+/+query+ take
+    # Nothing here memoizes: the block-form shortcuts can't be memoized, and +select+/+value+/+query+ take
     # arguments. So the pack does not wire {Reload}, and works without a booted application.
     #
     # +connected_to+ forwards every argument to +base.connected_to+ — +role:+, +shard:+, +prevent_writes:+,
@@ -48,11 +48,12 @@ module Briefly
         # always reads, while `shard:` and `prevent_writes:` still forward.
         builder.shortcut(:reading) { |**opts, &blk| connected_to(**opts, role: :reading, &blk) }
         builder.shortcut(:writing) { |**opts, &blk| connected_to(**opts, role: :writing, &blk) }
-        # `select` and `query` share one closure, differing only by the adapter method. `select` runs a
+        # `select`, `value` and `query` share one closure, differing only by the adapter method. `select` runs a
         # read through `select_all` — the read-optimized path for a raw SELECT, returning an
         # `ActiveRecord::Result` without clearing the query cache. `query` runs arbitrary SQL through
         # `exec_query` — writes and DDL included. Neither polices the SQL it's given; the split is name
         # and cache-path, not a runtime read/write guard.
+        # `value` uses `select_value` for the first column of the first row, or nil for no row or SQL NULL.
         #
         # `with_connection`, not `connection`: the latter is soft-deprecated, and raises outright under
         # `ActiveRecord.permanent_connection_checkout = :disallowed`.
@@ -60,7 +61,7 @@ module Briefly
         # A bindless statement must skip `sanitize_sql_array`, which would fall through to its
         # `statement % values` branch and raise on any literal `%` — `... like '%foo%'`.
         #
-        # No `**` parameter on either shortcut, deliberately: taking no keywords is what makes Ruby pack
+        # No `**` parameter on these shortcuts, deliberately: taking no keywords is what makes Ruby pack
         # `select(sql, id: 1)` into `binds` as a trailing Hash, which is how named binds reach
         # `sanitize_sql_array`. A `**opts` would swallow them and send the statement unbound.
         run = lambda do |method, sql, binds|
@@ -69,6 +70,7 @@ module Briefly
           record.with_connection { |connection| connection.public_send(method, statement) }
         end
         builder.shortcut(:select) { |sql, *binds| run.call(:select_all, sql, binds) }
+        builder.shortcut(:value) { |sql, *binds| run.call(:select_value, sql, binds) }
         builder.shortcut(:query) { |sql, *binds| run.call(:exec_query, sql, binds) }
         builder
       end

data/lib/briefly/rescues.rb

@@ -10,7 +10,7 @@ module Briefly
   # mutex, because rebinding alone would drop concurrent registrations.
   class Rescues
     # A single registration.
-    Entry = Struct.new(:klass, :handler)
+    Entry = Data.define(:klass, :handler)
 
     def initialize
       @entries = [].freeze

data/lib/briefly/version.rb

@@ -2,5 +2,5 @@
 
 module Briefly
   # The gem version.
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/generators/briefly/install/templates/briefly.rb.tt

@@ -39,6 +39,7 @@ end
 #   db       <%= name %>.db.connection { |c| }, <%= name %>.db.conn { |c| } -> yields a connection, auto-releases
 #            <%= name %>.db.transaction { }, <%= name %>.db.txn { } -> wraps the block in a transaction
 #            <%= name %>.db.select(sql, id: 1) / select(sql, 1) -> a read (SELECT); named or positional binds
+#            <%= name %>.db.value(sql, id: 1) / value(sql, 1) -> first column of first row; nil for no row or SQL NULL
 #            <%= name %>.db.query(sql, id: 1) / query(sql, 1) -> arbitrary SQL (writes, DDL); same binds
 #            <%= name %>.db.connected_to(role:, shard:, prevent_writes:) { }
 #            <%= name %>.db.reading { }, <%= name %>.db.writing { } -> run the block under a role

data/sig/briefly/builder.rbs

@@ -2,11 +2,11 @@ module Briefly
   # Receives the DSL. Blocks are `instance_eval`'d here, never on the facade.
   class Builder
     # A validated `compile!` pass, ready for a `Facade` to install.
-    class Plan < ::Struct[untyped]
-      attr_accessor defs: Hash[Symbol, Shortcut]
-      attr_accessor rescue_entries: Array[Briefly::rescue_entry]
-      attr_accessor children: Hash[Symbol, Facade]
-      attr_accessor child_plans: Array[[ Facade, Plan ]]
+    class Plan < ::Data
+      attr_reader defs: Hash[Symbol, Shortcut]
+      attr_reader rescue_entries: Array[Briefly::rescue_entry]
+      attr_reader children: Hash[Symbol, Facade]
+      attr_reader child_plans: Array[[ Facade, Plan ]]
 
       def self.new: (Hash[Symbol, Shortcut] defs, Array[Briefly::rescue_entry] rescue_entries, Hash[Symbol, Facade] children, Array[[ Facade, Plan ]] child_plans) -> Plan
     end

data/sig/briefly/rescues.rbs

@@ -2,9 +2,9 @@ module Briefly
   # An ordered list of facade-wide and global `rescue_from` registrations, queried at dispatch time.
   class Rescues
     # A single registration.
-    class Entry < ::Struct[untyped]
-      attr_accessor klass: Class
-      attr_accessor handler: Briefly::handler
+    class Entry < ::Data
+      attr_reader klass: Class
+      attr_reader handler: Briefly::handler
 
       def self.new: (Class klass, Briefly::handler handler) -> Entry
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: briefly
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -77,14 +77,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A terse, curated facade over your application's most reached-for objects.
 test_files: []