occams-record 1.4.0 → 1.9.0

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,10 +58,11 @@ module OccamsRecord
   class RawQuery
     # @return [String]
     attr_reader :sql
-    # @return [Hash]
+    # @return [Hash|Array]
     attr_reader :binds
 
     include OccamsRecord::Batches::CursorHelpers
+    include OccamsRecord::Pluck
     include EagerLoaders::Builder
     include Enumerable
     include Measureable
@@ -69,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
@@ -78,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
@@ -109,15 +110,16 @@ 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
-      row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.names, model: @eager_loaders.model, modules: @use)
+      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)
       yield_measurements!
@@ -209,19 +211,54 @@ module OccamsRecord
       )
     end
 
+    #
+    # Returns the column(s) you've SELECT as an array of values.
+    #
+    # 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 *args DEPRECATED
+    # @return [Array]
+    #
+    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, model: @eager_loaders.model)
+    end
+
     private
 
     # 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.
@@ -17,9 +10,14 @@ module OccamsRecord
     # @param association_names [Array<String>] names of associations that will be eager loaded into the results.
     # @param model [ActiveRecord::Base] the AR model representing the table (it holds column & type info).
     # @param modules [Array<Module>] (optional)
+    # @param tracer [OccamsRecord::EagerLoaders::Tracer] the eager loaded that loaded this class of records
+    # @param active_record_fallback [Symbol] If passed, missing methods will be forwarded to an ActiveRecord instance. Options are :lazy (allow lazy loading in the AR record) or :strict (require strict loading)
     # @return [OccamsRecord::Results::Row] a class customized for this result set
     #
-    def self.klass(column_names, column_types, association_names = [], model: nil, modules: nil)
+    def self.klass(column_names, column_types, association_names = [], model: nil, modules: nil, tracer: nil, active_record_fallback: nil)
+      raise ArgumentError, "Invalid active_record_fallback option :#{active_record_fallback}. Valid options are :lazy, :strict" if active_record_fallback and !%i(lazy strict).include?(active_record_fallback)
+      raise ArgumentError, "Option active_record_fallback is not allowed when no model is present" if active_record_fallback and model.nil?
+
       Class.new(Results::Row) do
         Array(modules).each { |mod| prepend mod } if modules
 
@@ -28,36 +26,33 @@ module OccamsRecord
         self._model = model
         self.model_name = model ? model.name : nil
         self.table_name = model ? model.table_name : nil
-        self.primary_key = if model&.primary_key and (pkey = model.primary_key.to_s) and columns.include?(pkey)
-                             pkey
-                           end
+        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
 
         # 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)
-          case type&.type
-          when nil
-            define_method(col) { @raw_values[idx] }
-          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) }
+          caster = casters[col]
+
+          if caster
+            define_method(col) {
+              @cast_values[idx] = caster.(@raw_values[idx]) unless @cast_values.has_key?(idx)
+              @cast_values[idx]
+            }
           else
-            define_method(col) { @cast_values[idx] ||= type.send(CASTER, @raw_values[idx]) }
+            define_method(col) {
+              @raw_values[idx]
+            }
           end
+
+          define_method("#{col}?") { send(col).present? }
         end
       end
     end

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

@@ -19,6 +19,10 @@ module OccamsRecord
         attr_accessor :table_name
         # Name of primary key column (nil if column wasn't in the SELECT)
         attr_accessor :primary_key
+        # A trace of how this record was loaded (for debugging)
+        attr_accessor :eager_loader_trace
+        # If present, missing methods will be forwarded to the ActiveRecord model. :lazy allows lazy loading in AR, :strict doesn't
+        attr_accessor :active_record_fallback
       end
       self.columns = []
       self.associations = []
@@ -36,7 +40,7 @@ module OccamsRecord
       #
       # Hash-like accessor for attributes and associations.
       #
-      # @param attr [String|Symbol\
+      # @param attr [String|Symbol]
       # @return [Object]
       #
       def [](attr)
@@ -65,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
 
@@ -110,19 +113,24 @@ module OccamsRecord
       IDS_SUFFIX = /_ids$/
       def method_missing(name, *args, &block)
         model = self.class._model
-        return super if args.any? or !block.nil? or model.nil?
+        ex = NoMethodError.new("Undefined method `#{name}' for #{self.inspect}. Occams Record trace: #{self.class.eager_loader_trace}", name, args)
+        raise ex if model.nil?
 
         name_str = name.to_s
         assoc = name_str.sub(IDS_SUFFIX, "").pluralize
-        if name_str =~ IDS_SUFFIX and can_define_ids_reader? assoc
+        no_args = args.empty? && block.nil?
+
+        if no_args and name_str =~ IDS_SUFFIX and can_define_ids_reader? assoc
           define_ids_reader! assoc
           send name
-        elsif model.reflections.has_key? name_str
+        elsif no_args and model.reflections.has_key? name_str
           raise MissingEagerLoadError.new(self, name)
-        elsif model.columns_hash.has_key? name_str
+        elsif no_args and model.columns_hash.has_key? name_str
           raise MissingColumnError.new(self, name)
+        elsif self.class.active_record_fallback
+          active_record_fallback(name, *args, &block)
         else
-          super
+          raise ex
         end
       end
 
@@ -141,6 +149,15 @@ module OccamsRecord
 
       private
 
+      def active_record_fallback(name, *args, &block)
+        @active_record_fallback ||= Ugly::active_record(self.class._model, self).tap { |record|
+          record.strict_loading! if self.class.active_record_fallback == :strict
+        }
+        @active_record_fallback.send(name, *args, &block)
+      rescue NoMethodError => e
+        raise NoMethodError.new("#{e.message}. Occams Record trace: #{self.class.eager_loader_trace}.active_record_fallback(#{self.class._model.name})", name, args)
+      end
+
       def can_define_ids_reader?(assoc)
         model = self.class._model
         self.class.associations.include?(assoc) &&

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.4.0".freeze
+  VERSION = "1.9.0".freeze
 end

data/lib/occams-record.rb

@@ -3,8 +3,10 @@ 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'
 require 'occams-record/cursor'
 require 'occams-record/errors'
 
@@ -12,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.4.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Jordan Hollinger
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-05-25 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
@@ -70,20 +60,23 @@ files:
 - lib/occams-record/eager_loaders/has_one.rb
 - lib/occams-record/eager_loaders/polymorphic_belongs_to.rb
 - lib/occams-record/eager_loaders/through.rb
+- lib/occams-record/eager_loaders/tracer.rb
 - lib/occams-record/errors.rb
 - lib/occams-record/measureable.rb
 - lib/occams-record/merge.rb
+- lib/occams-record/pluck.rb
 - lib/occams-record/query.rb
 - 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/
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -98,8 +91,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: The missing high-efficiency query API for ActiveRecord
 test_files: []