occams-record 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 846af974c8bc267fe8e901995d0aa3341b018d135eeb267c11d9add447cd0155
-  data.tar.gz: 763f8a038908cb9a990bcf305644661736dd9133e51a9d8fb8ece2b8ff018fd2
+  metadata.gz: e26a6e33886dfdb5cb2d3000e32c9de7e04bb7b26cc4434c5df7f1deb094ac58
+  data.tar.gz: 9cc37f3ab8beeef6e55d5adae2e1f76268acad3381b789f70c896a515abe8cfa
 SHA512:
-  metadata.gz: 24e1c5dfb09cb35b2b7116cb40aafcb1eb215ac96e3c8bab7ff6558598b31e8abb77b49c2b711392567862b182e1aed705888e939f8b66f15285f2ca352dbc89
-  data.tar.gz: 04f78d14765b6ae4d9ccee5f01633132ed1e39662071dfc39f6e33583e9cd3e6214841225eb35ce2f678472ce34bf45e27e23660114f28cede6a27cdb38613b0
+  metadata.gz: a8236d746e52a2890dfb83e838db153150c249ff0b5fb53a1bc949d386258b5047dc93e63a40d747e0f584ffbcaf3d069122962c23a2fc3691a4e162044927af
+  data.tar.gz: 1883cb2f7d7817561837b911828b56b540b5dff7845a943340c489786b73be9b3c24270ec2d32a5e7b9ecdb324a21f346948f183e13439e9339424ee9b593ad9

data/README.md

@@ -1,4 +1,4 @@
-# Occams Record [![Build Status](https://travis-ci.org/jhollinger/occams-record.svg?branch=master)](https://travis-ci.org/jhollinger/occams-record)
+# Occams Record
 
 > Do not multiply entities beyond necessity. -- Occam's Razor
 
@@ -130,6 +130,18 @@ orders = OccamsRecord
 
 ActiveRecord has raw SQL escape hatches like `find_by_sql` and `exec_query`, but they give up critical features like eager loading and `find_each`/`find_in_batches`. Occams Record's escape hatches don't make you give up anything.
 
+**Query params**
+
+```ruby
+# Supported in all versions of OccamsRecord
+OccamsRecord.sql("SELECT * FROM orders WHERE user_id = %{user_id}", {user_id: user.id}).run
+
+# Supported in OccamsRecord 1.9+
+OccamsRecord.sql("SELECT * FROM orders WHERE user_id = :user_id", {user_id: user.id}).run
+OccamsRecord.sql("SELECT * FROM orders WHERE user_id = ?", [user.id]).run
+OccamsRecord.sql("SELECT * FROM orders WHERE user_id = %s", [user.id]).run
+```
+
 **Batched loading with cursors**
 
 `find_each_with_cursor`, `find_in_batches_with_cursor`, and `cursor.open` are all available.
@@ -298,32 +310,50 @@ On the other hand, Active Record makes it *very* easy to forget to eager load as
 
 # Testing
 
-```bash
-bundle install
-
-# test against SQLite
-bundle exec rake test
+Tests are run with `appraisal` in Docker Compose using the `bin/test` or `bin/testall` scripts.
 
-# test against Postgres
-TEST_DATABASE_URL=postgresql://postgres@localhost:5432/occams_record bundle exec rake test
-
-# test against MySQL
-TEST_DATABASE_URL=mysql2://root:@127.0.0.1:3306/occams_record bundle exec rake test
+```bash
+# Run tests against all supported ActiveRecord versions, Ruby versions, and databases
+bin/testall
+
+# Run tests for Ruby vX only
+bin/testall ruby-3.1
+
+# Run tests for ActiveRecord vX only
+bin/testall ar-6.1
+
+# Run tests against a specific database
+bin/testall sqlite|postgres-14|mysql-8
+
+# Run exactly one set of tests
+bin/test ruby-3.1 ar-7.0 postgres-14
+
+# If all tests complete successfully, you'll be rewarded by an ASCII Nyancat!
+
++      o     +              o
+    +             o     +       +
+o          +
+    o  +           +        +
++        o     o       +        o
+-_-_-_-_-_-_-_,------,      o
+_-_-_-_-_-_-_-|   /\_/\
+-_-_-_-_-_-_-~|__( ^ .^)  +     +
+_-_-_-_-_-_-_-""  ""
+    +      o         o   +       o
+    +         +
+o        o         o      o     +
+    o           +
++      +     o        o      +
 ```
 
-**Test against all supported ActiveRecord versions**
-
-```bash
-bundle exec appraisal install
+## Testing without Docker
 
-# test against all supported AR versions (defaults to SQLite)
-bundle exec appraisal rake test
+It's possible to run tests without Docker Compose, but you'll be limited by the Ruby version(s) and database(s) you have on your system.
 
-# test against a specific AR version
+```bash
+bundle install
+bundle exec appraisal ar-7.0 bundle install
 bundle exec appraisal ar-7.0 rake test
-
-# test against Postgres
-TEST_DATABASE_URL=postgresql://postgres@localhost:5432/occams_record bundle exec appraisal rake test
 ```
 
 # License

data/lib/occams-record/batches/offset_limit/raw_query.rb

@@ -9,8 +9,12 @@ module OccamsRecord
           @conn, @sql, @binds = conn, sql, binds
           @use, @query_logger, @eager_loaders = use, query_logger, eager_loaders
 
+          unless binds.is_a? Hash
+            raise ArgumentError, "When using find_each/find_in_batches with raw SQL, binds MUST be a Hash. SQL statement: #{@sql}"
+          end
+
           unless @sql =~ /LIMIT\s+%\{batch_limit\}/i and @sql =~ /OFFSET\s+%\{batch_offset\}/i
-            raise ArgumentError, "When using find_each/find_in_batches you must specify 'LIMIT %{batch_limit} OFFSET %{batch_offset}'. SQL statement: #{@sql}"
+            raise ArgumentError, "When using find_each/find_in_batches with raw SQL, you must specify 'LIMIT %{batch_limit} OFFSET %{batch_offset}'. SQL statement: #{@sql}"
           end
         end
 

data/lib/occams-record/binds_converter/abstract.rb

@@ -0,0 +1,71 @@
+module OccamsRecord
+  module BindsConverter
+    #
+    # A base class for converting a SQL string with Rails-style query params (?, :foo) to native Ruby format (%s, %{foo}).
+    #
+    # It works kind of like a tokenizer. Subclasses must 1) implement get_bind to return the converted bind
+    # from the current position and 2) pass the bind sigil (e.g. ?, :) to the parent constructor.
+    #
+    class Abstract
+      # @private
+      ESCAPE = "\\".freeze
+
+      def initialize(sql, bind_sigil)
+        @sql = sql
+        @end = sql.size - 1
+        @start_i, @i = 0, 0
+        @bind_sigil = bind_sigil
+      end
+
+      # @return [String] The converted SQL string
+      def to_s
+        sql = ""
+        each { |frag| sql << frag }
+        sql
+      end
+
+      protected
+
+      # Yields each SQL fragment and converted bind to the given block
+      def each
+        escape = false
+        until @i > @end
+          char = @sql[@i]
+          unescape = escape
+          case char
+          when @bind_sigil
+            if escape
+              @i += 1
+            elsif @i > @start_i
+              yield flush_sql
+            else
+              yield get_bind
+            end
+          when ESCAPE
+            if escape
+              @i += 1
+            elsif @i > @start_i
+              yield flush_sql
+              escape = true
+              @i += 1
+              @start_i = @i
+            else
+              escape = true
+              @i += 1
+            end
+          else
+            @i += 1
+          end
+          escape = false if unescape
+        end
+        yield flush_sql if @i > @start_i
+      end
+
+      def flush_sql
+        t = @sql[@start_i..@i - 1]
+        @start_i = @i
+        t
+      end
+    end
+  end
+end

data/lib/occams-record/binds_converter/named.rb

@@ -0,0 +1,35 @@
+module OccamsRecord
+  module BindsConverter
+    # @private
+    WORD = /\w/
+
+    #
+    # Converts Rails-style named binds (:foo) into native Ruby format (%{foo}).
+    #
+    class Named < Abstract
+      def initialize(sql)
+        super(sql, ":".freeze)
+      end
+
+      protected
+
+      def get_bind
+        old_i = @i
+        @i += 1
+        @start_i = @i
+
+        until @i > @end or @sql[@i] !~ WORD
+          @i += 1
+        end
+
+        if @i > @start_i
+          name = @sql[@start_i..@i - 1]
+          @start_i = @i
+          "%{#{name}}"
+        else
+          @sql[old_i]
+        end
+      end
+    end
+  end
+end

data/lib/occams-record/binds_converter/positional.rb

@@ -0,0 +1,20 @@
+module OccamsRecord
+  module BindsConverter
+    #
+    # Converts Rails-style positional binds (?) into native Ruby format (%s).
+    #
+    class Positional < Abstract
+      def initialize(sql)
+        super(sql, "?".freeze)
+      end
+
+      protected
+
+      def get_bind
+        @i += 1
+        @start_i = @i
+        "%s".freeze
+      end
+    end
+  end
+end

data/lib/occams-record/binds_converter.rb

@@ -0,0 +1,23 @@
+module OccamsRecord
+  #
+  # Classes and methods for converting from Rails-style binds (?, :foo) to native Ruby format (%s, %{foo}).
+  #
+  module BindsConverter
+    #
+    # Convert any Rails-style binds (?, :foo) to native Ruby format (%s, %{foo}).
+    #
+    # @param sql [String]
+    # @param binds [Hash|Array]
+    # @return [String] the converted SQL string
+    #
+    def self.convert(sql, binds)
+      converter =
+        case binds
+        when Hash then Named.new(sql)
+        when Array then Positional.new(sql)
+        else raise ArgumentError, "OccamsRecord: Unsupported SQL bind params '#{binds.inspect}'. Only Hash and Array are supported"
+        end
+      converter.to_s
+    end
+  end
+end

data/lib/occams-record/cursor.rb

@@ -203,9 +203,8 @@ module OccamsRecord
     #   end
     #
     def execute(sql, binds = {})
-      conn.execute(sql % binds.reduce({}) { |acc, (key, val)|
+      conn.execute(sql % binds.each_with_object({}) { |(key, val), acc|
         acc[key] = conn.quote(val)
-        acc
       })
     end
 

data/lib/occams-record/eager_loaders/ad_hoc_base.rb

@@ -51,12 +51,13 @@ module OccamsRecord
       #
       def run(rows, query_logger: nil, measurements: nil)
         fkey_binds = calc_fkey_binds rows
-        assoc = if fkey_binds.all? { |_, vals| vals.any? }
-                  binds = @binds.merge(fkey_binds)
-                  RawQuery.new(@sql, binds, use: @use, eager_loaders: @eager_loaders, query_logger: query_logger, measurements: measurements).run
-                else
-                  []
-                end
+        assoc =
+          if fkey_binds.all? { |_, vals| vals.any? }
+            binds = @binds.merge(fkey_binds)
+            RawQuery.new(@sql, binds, use: @use, eager_loaders: @eager_loaders, query_logger: query_logger, measurements: measurements).run
+          else
+            []
+          end
         merge! assoc, rows
         nil
       end
@@ -69,17 +70,15 @@ module OccamsRecord
       # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
       #
       def calc_fkey_binds(rows)
-        @mapping.keys.reduce({}) { |a, fkey|
-          a[fkey.to_s.pluralize.to_sym] = rows.reduce(Set.new) { |aa, row|
+        @mapping.keys.each_with_object({}) { |fkey, acc|
+          acc[fkey.to_s.pluralize.to_sym] = rows.each_with_object(Set.new) { |row, acc2|
             begin
               val = row.send fkey
-              aa << val if val
+              acc2 << val if val
             rescue NoMethodError => e
               raise MissingColumnError.new(row, e.name)
             end
-            aa
           }.to_a
-          a
         }
       end
 

data/lib/occams-record/eager_loaders/belongs_to.rb

@@ -20,7 +20,6 @@ module OccamsRecord
             raise MissingColumnError.new(row, e.name)
           end
         }.compact.uniq
-        ids.sort! if $occams_record_test
 
         q = base_scope.where(@ref.association_primary_key => ids)
         yield q if ids.any?

data/lib/occams-record/eager_loaders/habtm.rb

@@ -24,23 +24,21 @@ module OccamsRecord
       # @param join_rows [Array<Array<String>>] raw join'd ids from the db
       #
       def merge!(assoc_rows, rows, join_rows)
-        joins_by_id = join_rows.reduce({}) { |a, join|
+        joins_by_id = join_rows.each_with_object({}) { |join, acc|
           id = join[0].to_s
-          a[id] ||= []
-          a[id] << join[1].to_s
-          a
+          acc[id] ||= []
+          acc[id] << join[1].to_s
         }
 
         assoc_order_cache = {} # maintains the original order of assoc_rows
-        assoc_rows_by_id = assoc_rows.each_with_index.reduce({}) { |a, (row, idx)|
+        assoc_rows_by_id = assoc_rows.each_with_index.each_with_object({}) { |(row, idx), acc|
           begin
             id = row.send(@ref.association_primary_key).to_s
           rescue NoMethodError => e
             raise MissingColumnError.new(row, e.name)
           end
           assoc_order_cache[id] = idx
-          a[id] = row
-          a
+          acc[id] = row
         }
 
         assign = "#{name}="

data/lib/occams-record/eager_loaders/has_one.rb

@@ -20,7 +20,6 @@ module OccamsRecord
             raise MissingColumnError.new(row, e.name)
           end
         }.compact.uniq
-        ids.sort! if $occams_record_test
 
         q = base_scope.where(@ref.foreign_key => ids)
         q.where!(@ref.type => rows[0].class&.model_name) if @ref.options[:as]

data/lib/occams-record/eager_loaders/polymorphic_belongs_to.rb

@@ -85,7 +85,6 @@ module OccamsRecord
           next if type.nil? or type == ""
           model = type.constantize
           ids = rows_of_type.map(&@foreign_key).uniq
-          ids.sort! if $occams_record_test
           q = base_scope(model).where(@ref.active_record_primary_key => ids)
           yield q if ids.any?
         end

data/lib/occams-record/eager_loaders/through.rb

@@ -20,7 +20,7 @@ module OccamsRecord
           raise ArgumentError, "#{@ref.active_record.name}##{@ref.name} cannot be eager loaded because these `through` associations are polymorphic: #{names.join ', '}"
         end
         unless @optimizer == :none or @optimizer == :select
-          raise ArgumentError, "Unrecognized optimizer '#{@optimizer}'"
+          raise ArgumentError, "Unrecognized optimizer '#{@optimizer}' (valid options are :none, :select)"
         end
 
         chain = @ref.chain.reverse
@@ -31,7 +31,6 @@ module OccamsRecord
         @loader = build_loader
       end
 
-      # TODO make not hacky
       def through_name
         @loader.name
       end
@@ -47,6 +46,7 @@ module OccamsRecord
 
       private
 
+      # starting at the top of the chain, recurse and return the leaf node(s)
       def reduce(node, depth = 0)
         link = @chain[depth]
         case link&.macro
@@ -69,38 +69,48 @@ module OccamsRecord
         end
       end
 
+      # build all the nested eager loaders
       def build_loader
         head = @chain[0]
         links = @chain[1..-2]
         tail = @chain[-1]
 
-        outer_loader = EagerLoaders.fetch!(head.ref).new(head.ref, optimized_select(head), parent: tracer.parent)
+        outer_loader = EagerLoaders.fetch!(head.ref).new(head.ref, optimized_scope(head), parent: tracer.parent)
         outer_loader.tracer.through = true
 
         inner_loader = links.
           reduce(outer_loader) { |loader, link|
-            nested_loader = loader.nest(link.ref.source_reflection.name, optimized_select(link))
+            nested_loader = loader.nest(link.ref.source_reflection.name, optimized_scope(link))
             nested_loader.tracer.through = true
             nested_loader
           }.
-          nest(tail.ref.source_reflection.name, @scope, use: @use, as: @as, active_record_fallback: @active_record_fallback)
+          nest(tail.ref.source_reflection.name, @scopes, use: @use, as: @as, active_record_fallback: @active_record_fallback)
 
         @eager_loaders.each { |loader| inner_loader.eager_loaders << loader }
         inner_loader.tracer.name = tracer.name
         outer_loader
       end
 
-      def optimized_select(link)
-        return nil unless @optimizer == :select
+      def optimized_scope(link)
+        case @optimizer
+        when :select
+          optimized_select(link)
+        when :none
+          nil
+        end
+      end
 
-        cols = case link.macro
-               when :belongs_to
-                 [link.ref.association_primary_key]
-               when :has_one, :has_many
-                 [link.ref.association_primary_key, link.ref.foreign_key]
-               else
-                 raise "Unsupported through chain link type '#{link.macro}'"
-               end
+      # only select the ids/foreign keys required to link the parent/child records
+      def optimized_select(link)
+        cols =
+          case link.macro
+          when :belongs_to
+            [link.ref.association_primary_key]
+          when :has_one, :has_many
+            [link.ref.association_primary_key, link.ref.foreign_key]
+          else
+            raise "Unsupported through chain link type '#{link.macro}'"
+          end
 
         case link.next_ref.source_reflection.macro
         when :belongs_to

data/lib/occams-record/merge.rb

@@ -35,14 +35,13 @@ module OccamsRecord
       # Optimized for merges where there's a single mapping key pair (which is the vast majority)
       if mapping.size == 1
         target_attr, assoc_attr = target_attrs[0], assoc_attrs[0]
-        assoc_rows_by_ids = assoc_rows.reduce({}) { |a, assoc_row|
+        assoc_rows_by_ids = assoc_rows.each_with_object({}) { |assoc_row, acc|
           begin
             id = assoc_row.send assoc_attr
           rescue NoMethodError => e
             raise MissingColumnError.new(assoc_row, e.name)
           end
-          a[id] ||= assoc_row
-          a
+          acc[id] ||= assoc_row
         }
 
         target_rows.each do |row|
@@ -56,14 +55,13 @@ module OccamsRecord
 
       # Slower but works with any number of mapping key pairs
       else
-        assoc_rows_by_ids = assoc_rows.reduce({}) { |a, assoc_row|
+        assoc_rows_by_ids = assoc_rows.each_with_object({}) { |assoc_row, acc|
           begin
             ids = assoc_attrs.map { |attr| assoc_row.send attr }
           rescue NoMethodError => e
             raise MissingColumnError.new(assoc_row, e.name)
           end
-          a[ids] ||= assoc_row
-          a
+          acc[ids] ||= assoc_row
         }
 
         target_rows.each do |row|

data/lib/occams-record/pluck.rb

@@ -2,55 +2,37 @@ module OccamsRecord
   module Pluck
     private
 
-    def pluck_results(results, cols, model: nil)
-      if cols.size == 1
-        pluck_results_single(results, cols[0].to_s, model: model)
+    def pluck_results(results, model: nil)
+      casters = TypeCaster.generate(results.columns, results.column_types, model: model)
+      if results[0]&.size == 1
+        pluck_results_single(results, casters)
       else
-        pluck_results_multi(results, cols.map(&:to_s), model: model)
+        pluck_results_multi(results, casters)
       end
     end
 
     # returns an array of values
-    def pluck_results_single(results, col, model: nil)
-      enum = model&.defined_enums&.[](col)
-      inv_enum = enum&.invert
-      if enum
-        results.map { |r|
-          val = r[col]
-          enum.has_key?(val) ? val : inv_enum[val]
+    def pluck_results_single(results, casters)
+      col = results.columns[0]
+      caster = casters[col]
+      if caster
+        results.map { |row|
+          val = row[col]
+          caster.(val)
         }
       else
-        # micro-optimization for when there are no enums
-        results.map { |r| r[col] }
+        results.map { |row| row[col] }
       end
     end
 
     # returns an array of arrays
-    def pluck_results_multi(results, cols, model: nil)
-      any_enums = false
-      cols_with_enums = cols.map { |col|
-        enum = model&.defined_enums&.[](col)
-        any_enums ||= !!enum
-        [col, enum, enum&.invert]
-      }
-
-      if any_enums
-        results.map { |row|
-          cols_with_enums.map { |(col, enum, inv_enum)|
-            if enum
-              val = row[col]
-              enum.has_key?(val) ? val : inv_enum[val]
-            else
-              row[col]
-            end
-          }
+    def pluck_results_multi(results, casters)
+      results.map { |row|
+        row.map { |col, val|
+          caster = casters[col]
+          caster ? caster.(val) : val
         }
-      else
-        # micro-optimization for when there are no enums
-        results.map { |row|
-          cols.map { |col| row[col] }
-        }
-      end
+      }
     end
   end
 end

data/lib/occams-record/query.rb

@@ -99,14 +99,15 @@ module OccamsRecord
       return [] if sql.blank? # return early in case ActiveRecord::QueryMethods#none was used
 
       @query_logger << "#{@eager_loaders.tracer}: #{sql}" if @query_logger
-      result = if measure?
-                 record_start_time!
-                 measure!(model.table_name, sql) {
-                   model.connection.exec_query sql
-                 }
-               else
-                 model.connection.exec_query sql
-               end
+      result =
+        if measure?
+          record_start_time!
+          measure!(model.table_name, sql) {
+            model.connection.exec_query sql
+          }
+        else
+          model.connection.exec_query sql
+        end
       row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.names, model: model, modules: @use, tracer: @eager_loaders.tracer, active_record_fallback: @active_record_fallback)
       rows = result.rows.map { |row| row_class.new row }
       @eager_loaders.run!(rows, query_logger: @query_logger, measurements: @measurements)
@@ -238,19 +239,20 @@ module OccamsRecord
     # @return [Array]
     #
     def pluck(*cols)
-      sql = (block_given? ? yield(scope).to_sql : scope).select(*cols).to_sql
+      sql = (block_given? ? yield(scope).to_sql : scope).unscope(:select).select(*cols).to_sql
       return [] if sql.blank? # return early in case ActiveRecord::QueryMethods#none was used
 
       @query_logger << "#{@eager_loaders.tracer}: #{sql}" if @query_logger
-      result = if measure?
-                 record_start_time!
-                 measure!(model.table_name, sql) {
-                   model.connection.exec_query sql
-                 }
-               else
-                 model.connection.exec_query sql
-               end
-      pluck_results result, cols, model: @model
+      result =
+        if measure?
+          record_start_time!
+          measure!(model.table_name, sql) {
+            model.connection.exec_query sql
+          }
+        else
+          model.connection.exec_query sql
+        end
+      pluck_results(result, model: @model)
     end
   end
 end

data/lib/occams-record/raw_query.rb

@@ -1,7 +1,7 @@
 module OccamsRecord
   #
   # Starts building a OccamsRecord::RawQuery. Pass it a raw SQL statement, optionally followed by
-  # a Hash of binds. While this doesn't offer an additional performance boost, it's a nice way to
+  # a Hash or Array of binds. While this doesn't offer an additional performance boost, it's a nice way to
   # write safe, complicated SQL by hand while also supporting eager loading.
   #
   #   results = OccamsRecord.sql("
@@ -39,10 +39,10 @@ module OccamsRecord
   # It is possible to coerce the SQLite adapter into returning native types for everything IF they're columns of a table
   # that you have an AR model for. e.g. if you're selecting from the widgets, table: `OccamsRecord.sql("...").model(Widget)...`.
   #
-  # MySQL ?
+  # MySQL Mostly native Ruby types, but more testing is needed.
   #
-  # @param sql [String] The SELECT statement to run. Binds should use Ruby's named string substitution.
-  # @param binds [Hash] Bind values (Symbol keys)
+  # @param sql [String] The SELECT statement to run. Binds may be Rails-style (?, :foo) or Ruby-style (%s, %{foo}).
+  # @param binds [Hash] Bind values as Hash (with Symbol keys) or an Array
   # @param use [Array<Module>] optional Module to include in the result class (single or array)
   # @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes
   # @return [OccamsRecord::RawQuery]
@@ -58,7 +58,7 @@ module OccamsRecord
   class RawQuery
     # @return [String]
     attr_reader :sql
-    # @return [Hash]
+    # @return [Hash|Array]
     attr_reader :binds
 
     include OccamsRecord::Batches::CursorHelpers
@@ -70,8 +70,8 @@ module OccamsRecord
     #
     # Initialize a new query.
     #
-    # @param sql [String] The SELECT statement to run. Binds should use Ruby's named string substitution.
-    # @param binds [Hash] Bind values (Symbol keys)
+    # @param sql [String] The SELECT statement to run. Binds may be Rails-style (?, :foo) or Ruby-style (%s, %{foo}).
+    # @param binds [Hash] Bind values as Hash (with Symbol keys) or an Array
     # @param use [Array<Module>] optional Module to include in the result class (single or array)
     # @param eager_loaders [OccamsRecord::EagerLoaders::Context]
     # @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes
@@ -79,7 +79,7 @@ module OccamsRecord
     # @param connection
     #
     def initialize(sql, binds, use: nil, eager_loaders: nil, query_logger: nil, measurements: nil, connection: nil)
-      @sql = sql
+      @sql = BindsConverter.convert(sql, binds)
       @binds = binds
       @use = use
       @eager_loaders = eager_loaders || EagerLoaders::Context.new
@@ -110,14 +110,15 @@ module OccamsRecord
     def run
       _escaped_sql = escaped_sql
       @query_logger << _escaped_sql if @query_logger
-      result = if measure?
-                 record_start_time!
-                 measure!(table_name, _escaped_sql) {
-                   conn.exec_query _escaped_sql
-                 }
-               else
-                 conn.exec_query _escaped_sql
-               end
+      result =
+        if measure?
+          record_start_time!
+          measure!(table_name, _escaped_sql) {
+            conn.exec_query _escaped_sql
+          }
+        else
+          conn.exec_query _escaped_sql
+        end
       row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.names, model: @eager_loaders.model, modules: @use, tracer: @eager_loaders.tracer)
       rows = result.rows.map { |row| row_class.new row }
       @eager_loaders.run!(rows, query_logger: @query_logger, measurements: @measurements)
@@ -211,25 +212,29 @@ module OccamsRecord
     end
 
     #
-    # Returns the specified column(s) as an array of values.
+    # Returns the column(s) you've SELECT as an array of values.
     #
-    # If more than one column is given, the result will be an array of arrays.
+    # If you're selecting multiple columns, you'll get back an array of arrays.
+    # Otherwise you'll get an array of the single column's values.
     #
-    # @param cols [Array] one or more column names as Symbols or Strings. Also accepts SQL functions, e.g. "LENGTH(name)".
+    # @param *args DEPRECATED
     # @return [Array]
     #
-    def pluck(*cols)
+    def pluck(*args)
+      $stderr.puts "OccamsRecord: passing arguments to OccamsRecord.sql(\"...\").pluck is deprecated and will be removed in a future version. Called from #{caller[0]}" if args.any?
+
       _escaped_sql = escaped_sql
       @query_logger << _escaped_sql if @query_logger
-      result = if measure?
-                 record_start_time!
-                 measure!(table_name, _escaped_sql) {
-                   conn.exec_query _escaped_sql
-                 }
-               else
-                 conn.exec_query _escaped_sql
-               end
-      pluck_results result, cols, model: @eager_loaders.model
+      result =
+        if measure?
+          record_start_time!
+          measure!(table_name, _escaped_sql) {
+            conn.exec_query _escaped_sql
+          }
+        else
+          conn.exec_query _escaped_sql
+        end
+      pluck_results(result, model: @eager_loaders.model)
     end
 
     private
@@ -237,14 +242,23 @@ module OccamsRecord
     # Returns the SQL as a String with all variables escaped
     def escaped_sql
       return sql if binds.empty?
-      sql % binds.reduce({}) { |a, (col, val)|
-        a[col.to_sym] = if val.is_a? Array
-                          val.map { |x| conn.quote x }.join(', ')
-                        else
-                          conn.quote val
-                        end
-        a
-      }
+      escaped_binds =
+        if binds.is_a? Array
+          binds.map { |val| quote val }
+        else
+          binds.each_with_object({}) { |(col, val), acc|
+            acc[col.to_sym] = quote val
+          }
+        end
+      sql % escaped_binds
+    end
+
+    def quote(val)
+      if val.is_a? Array
+        val.map { |x| conn.quote x }.join(', ')
+      else
+        conn.quote val
+      end
     end
 
     def table_name

data/lib/occams-record/results/results.rb

@@ -1,13 +1,6 @@
 module OccamsRecord
   # Classes and methods for handing query results.
   module Results
-    # ActiveRecord's internal type casting API changes from version to version.
-    CASTER = case ActiveRecord::VERSION::MAJOR
-             when 4 then :type_cast_from_database
-             when 5, 6, 7 then :deserialize
-             else raise "OccamsRecord::Results::CASTER does yet support this version of ActiveRecord"
-             end
-
     #
     # Dynamically build a class for a specific set of result rows. It inherits from OccamsRecord::Results::Row, and optionall prepends
     # user-defined modules.
@@ -35,61 +28,31 @@ module OccamsRecord
         self.table_name = model ? model.table_name : nil
         self.eager_loader_trace = tracer
         self.active_record_fallback = active_record_fallback
-        self.primary_key = if model&.primary_key and (pkey = model.primary_key.to_s) and columns.include?(pkey)
-                             pkey
-                           end
+        self.primary_key =
+          if model&.primary_key and (pkey = model.primary_key.to_s) and columns.include?(pkey)
+            pkey
+          end
 
         # Build getters & setters for associations. (We need setters b/c they're set AFTER the row is initialized
         attr_accessor(*association_names)
 
         # Build a getter for each attribute returned by the query. The values will be type converted on demand.
-        model_column_types = model ? model.attributes_builder.types : nil
+        casters = TypeCaster.generate(column_names, column_types, model: model)
         self.columns.each_with_index do |col, idx|
-          #
-          # NOTE there's lots of variation between DB adapters and AR versions here. Some notes:
-          # * Postgres AR < 6.1 `column_types` will contain entries for every column.
-          # * Postgres AR >= 6.1 `column_types` only contains entries for "exotic" types. Columns with "common" types have already been converted by the PG adapter.
-          # * SQLite `column_types` will always be empty. Some types will have already been convered by the SQLite adapter, but others will depend on
-          #   `model_column_types` for converstion. See test/raw_query_test.rb#test_common_types for examples.
-          # * MySQL ?
-          #
-          type = column_types[col] || model_column_types&.[](col)
+          caster = casters[col]
 
-          #
-          # NOTE is also some variation in when enum values are mapped in different AR versions.
-          # In >=5.0, <=7.0, ActiveRecord::Result objects contain the human-readable values. In 4.2 and
-          # pre-release versions of 7.1, they instead have the RAW values (e.g. integers) which we must map ourselves.
-          #
-          enum = model&.defined_enums&.[](col)
-          inv_enum = enum&.invert
-
-          case type&.type
-          when nil
-            if enum
-              define_method(col) {
-                val = @raw_values[idx]
-                enum.has_key?(val) ? val : inv_enum[val]
-              }
-            else
-              define_method(col) { @raw_values[idx] }
-            end
-          when :datetime
-            define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx])&.in_time_zone }
-          when :boolean
-            define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx]) }
-            define_method("#{col}?") { !!send(col) }
+          if caster
+            define_method(col) {
+              @cast_values[idx] = caster.(@raw_values[idx]) unless @cast_values.has_key?(idx)
+              @cast_values[idx]
+            }
           else
-            if enum
-              define_method(col) {
-                @cast_values[idx] ||= (
-                  val = type.send(CASTER, @raw_values[idx])
-                  enum.has_key?(val) ? val : inv_enum[val]
-                )
-              }
-            else
-              define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx]) }
-            end
+            define_method(col) {
+              @raw_values[idx]
+            }
           end
+
+          define_method("#{col}?") { send(col).present? }
         end
       end
     end

data/lib/occams-record/results/row.rb

@@ -69,21 +69,20 @@ module OccamsRecord
       # @return [Hash] a Hash with String or Symbol keys
       #
       def to_h(symbolize_names: false, recursive: false)
-        hash = self.class.columns.reduce({}) { |a, col_name|
+        hash = self.class.columns.each_with_object({}) { |col_name, acc|
           key = symbolize_names ? col_name.to_sym : col_name
-          a[key] = send col_name
-          a
+          acc[key] = send col_name
         }
 
-        recursive ? self.class.associations.reduce(hash) { |a, assoc_name|
+        recursive ? self.class.associations.each_with_object(hash) { |assoc_name, acc|
           key = symbolize_names ? assoc_name.to_sym : assoc_name
           assoc = send assoc_name
-          a[key] = if assoc.is_a? Array
-                     assoc.map { |x| x.to_h(symbolize_names: symbolize_names, recursive: true) }
-                   elsif assoc
-                     assoc.to_h(symbolize_names: symbolize_names, recursive: true)
-                   end
-          a
+          acc[key] =
+            if assoc.is_a? Array
+              assoc.map { |x| x.to_h(symbolize_names: symbolize_names, recursive: true) }
+            elsif assoc
+              assoc.to_h(symbolize_names: symbolize_names, recursive: true)
+            end
         } : hash
       end
 

data/lib/occams-record/type_caster.rb

@@ -0,0 +1,62 @@
+module OccamsRecord
+  module TypeCaster
+    # @private
+    CASTER =
+      case ActiveRecord::VERSION::MAJOR
+      when 4 then :type_cast_from_database
+      when 5, 6, 7 then :deserialize
+      else raise "OccamsRecord::TypeCaster::CASTER does yet support this version of ActiveRecord"
+      end
+
+    #
+    # Returns a Hash containing type converters (a Proc) for each column. The Proc's accept a value and return a converted value, mapping enum values from the model if necessary.
+    #
+    # NOTE Some columns may have no Proc (particularly if you're using SQLite and running a raw SQL query).
+    #
+    # @param column_names [Array<String>] the column names in the result set (ActiveRecord::Result#columns). The order MUST match the order returned by the query.
+    # @param column_types [Hash] Column name => type (ActiveRecord::Result#column_types)
+    # @param model [ActiveRecord::Base] the AR model representing the table (it holds column & type info as well as enums).
+    # @return [Hash<Proc>] a Hash of casting Proc's keyed by column
+    #
+    def self.generate(column_names, column_types, model: nil)
+      column_names.each_with_object({}) { |col, memo|
+        #
+        # NOTE there's lots of variation between DB adapters and AR versions here. Some notes:
+        # * Postgres AR < 6.1 `column_types` will contain entries for every column.
+        # * Postgres AR >= 6.1 `column_types` only contains entries for "exotic" types. Columns with "common" types have already been converted by the PG adapter.
+        # * SQLite `column_types` will always be empty. Some types will have already been convered by the SQLite adapter, but others will depend on
+        #   `model_column_types` for converstion. See test/raw_query_test.rb#test_common_types for examples.
+        # * MySQL ?
+        #
+        type = column_types[col] || model&.attributes_builder&.types&.[](col)
+
+        #
+        # NOTE is also some variation in when enum values are mapped in different AR versions.
+        # In >=5.0, <=7.0, ActiveRecord::Result objects *usually* contain the human-readable values. In 4.2 and
+        # pre-release versions of 7.1, they instead have the RAW values (e.g. integers) which we must map ourselves.
+        #
+        enum = model&.defined_enums&.[](col)
+        inv_enum = enum&.invert
+
+        memo[col] =
+          case type&.type
+          when nil
+            if enum
+              ->(val) { enum.has_key?(val) ? val : inv_enum[val] }
+            end
+          when :datetime
+            ->(val) { type.send(CASTER, val)&.in_time_zone }
+          else
+            if enum
+              ->(val) {
+                val = type.send(CASTER, val)
+                enum.has_key?(val) ? val : inv_enum[val]
+              }
+            else
+              ->(val) { type.send(CASTER, val) }
+            end
+          end
+      }
+    end
+  end
+end

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # @private
-  VERSION = "1.8.0".freeze
+  VERSION = "1.9.0".freeze
 end

data/lib/occams-record.rb

@@ -3,6 +3,7 @@ require 'occams-record/version'
 require 'occams-record/merge'
 require 'occams-record/measureable'
 require 'occams-record/eager_loaders/eager_loaders'
+require 'occams-record/type_caster'
 require 'occams-record/results/results'
 require 'occams-record/results/row'
 require 'occams-record/pluck'
@@ -13,6 +14,11 @@ require 'occams-record/batches/offset_limit/scoped'
 require 'occams-record/batches/offset_limit/raw_query'
 require 'occams-record/batches/cursor_helpers'
 
+require 'occams-record/binds_converter'
+require 'occams-record/binds_converter/abstract'
+require 'occams-record/binds_converter/named'
+require 'occams-record/binds_converter/positional'
+
 require 'occams-record/query'
 require 'occams-record/raw_query'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-01 00:00:00.000000000 Z
+date: 2023-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -30,20 +30,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '7.1'
-- !ruby/object:Gem::Dependency
-  name: appraisal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: A faster, lower-memory, fuller-featured querying API for ActiveRecord
   that returns results as unadorned, read-only objects.
 email: jordan.hollinger@gmail.com
@@ -56,6 +42,10 @@ files:
 - lib/occams-record/batches/cursor_helpers.rb
 - lib/occams-record/batches/offset_limit/raw_query.rb
 - lib/occams-record/batches/offset_limit/scoped.rb
+- lib/occams-record/binds_converter.rb
+- lib/occams-record/binds_converter/abstract.rb
+- lib/occams-record/binds_converter/named.rb
+- lib/occams-record/binds_converter/positional.rb
 - lib/occams-record/cursor.rb
 - lib/occams-record/eager_loaders/ad_hoc_base.rb
 - lib/occams-record/eager_loaders/ad_hoc_many.rb
@@ -79,6 +69,7 @@ files:
 - lib/occams-record/raw_query.rb
 - lib/occams-record/results/results.rb
 - lib/occams-record/results/row.rb
+- lib/occams-record/type_caster.rb
 - lib/occams-record/ugly.rb
 - lib/occams-record/version.rb
 homepage: https://jhollinger.github.io/occams-record/