simple_query 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6095e96524f3fda796bd8965a24595814091f2e84e74c3ca1789ca644269a22
-  data.tar.gz: b665f9077a68854e225c14188ce83948390d665ef7a6d30c4a04a3f2349d5150
+  metadata.gz: f15e71d4ac10ed8d359f177e46f36f12b9721da6f9f51c75d8a0571cf245aac0
+  data.tar.gz: 8090bd8f93899061f15a048a7c57a73e48e8805e7fee3807bb39ba91e0012b1f
 SHA512:
-  metadata.gz: ff9b7c518565311e9a1bbd23b03a5d6ce988ac9ed3bac2ef8f1e16088d846629190818d36163c2a9cfd95b943c734c1b6a3b3ab843413b6acfaf504528388d32
-  data.tar.gz: ce323624e8df7f73cedfea917acedc8cc07c295a10e86b9ecb896c34fa3ca151becfff1357d80d68b388cbe3998522ffe21cb2557d9cdab590d68a8bf435e43d
+  metadata.gz: 903a9d4754ed89bf718918de17d94bf09969dc5a725d933b68c101a71737d397e90a89ac3ab141b4e18f855b39a81d62a27982c207dca20e7df7f0c6d8571746
+  data.tar.gz: 2965ff1462a4036112ba0bfe974087c72ba5e8f9b8db15d39a5f5879394dbe074cf9942682f9b50732c61f0d25749c514d38f1e11e2c8e0414308ee676f14ba1

data/README.md

@@ -20,6 +20,30 @@ Or install it yourself as:
 gem install simple_query
 ```
 
+## Configuration
+
+By default, `SimpleQuery` does **not** automatically patch `ActiveRecord::Base`. You can **manually** include the module in individual models or in a global initializer:
+
+```ruby
+# Manual include (per model)
+class User < ActiveRecord::Base
+  include SimpleQuery
+end
+
+# or do it globally
+ActiveRecord::Base.include(SimpleQuery)
+```
+If you prefer a “just works” approach (i.e., every model has `.simple_query`), you can opt in:
+
+```ruby
+# config/initializers/simple_query.rb
+SimpleQuery.configure do |config|
+  config.auto_include_ar = true
+end
+```
+
+This tells SimpleQuery to automatically do `ActiveRecord::Base.include(SimpleQuery)` for you.
+
 ## Usage
 
 SimpleQuery offers an intuitive interface for building queries with joins, conditions, and aggregations. Here are some examples:
@@ -58,6 +82,74 @@ User.simple_query
     .lazy_execute
 ```
 
+## Custom Read Models
+By default, SimpleQuery returns results as `Struct` objects for maximum speed. However, you can also define a lightweight model class for more explicit attribute handling or custom logic.
+
+**Create a read model** inheriting from `SimpleQuery::ReadModel`:
+```ruby
+class MyUserReadModel < SimpleQuery::ReadModel
+  attribute :identifier, column: :id
+  attribute :full_name,  column: :name
+end
+```
+
+**Map query results** to your read model:
+```ruby
+results = User.simple_query
+              .select("users.id AS id", "users.name AS name")
+              .where(active: true)
+              .map_to(MyUserReadModel)
+              .execute
+
+results.each do |user|
+  puts user.identifier    # => user.id from the DB
+  puts user.full_name     # => user.name from the DB
+end
+```
+This custom read model approach provides more clarity or domain-specific logic while still being faster than typical ActiveRecord instantiation.
+
+## Named Scopes
+SimpleQuery now supports named scopes, allowing you to reuse common query logic in a style similar to ActiveRecord’s built-in scopes. To define a scope, use the simple_scope class method in your model:
+```ruby
+class User < ActiveRecord::Base
+  include SimpleQuery
+
+  simple_scope :active do
+    where(active: true)
+  end
+
+  simple_scope :admins do
+    where(admin: true)
+  end
+
+  simple_scope :by_name do |name|
+    where(name: name)
+  end
+end
+```
+You can then chain these scopes seamlessly with the normal SimpleQuery DSL:
+
+```ruby
+# Parameterless scopes
+results = User.simple_query.active.admins.execute
+
+# Parameterized scope
+results = User.simple_query.by_name("Jane Doe").execute
+
+# Mixing scopes with other DSL calls
+results = User.simple_query
+              .by_name("John")
+              .active
+              .select(:id, :name)
+              .order(name: :asc)
+              .execute
+```
+### How It Works
+
+Each scope block (e.g. by_name) is evaluated in the context of the SimpleQuery builder, so you can call any DSL method (where, order, etc.) inside it.
+Parameterized scopes accept arguments — passed directly to the block (e.g. |name| above).
+Scopes return self, so you can chain multiple scopes or mix them with standard query methods.
+
 ## Features
 
 - Efficient query building
@@ -67,7 +159,10 @@ User.simple_query
 - Aggregations
 - LIMIT and OFFSET
 - ORDER BY clause
+- Having and Grouping
 - Subqueries
+- Custom Read models
+- Named Scopes
 
 ## Performance
 
@@ -75,9 +170,12 @@ SimpleQuery is designed to potentially outperform standard ActiveRecord queries
 
 ```
 🚀 Performance Results (100,000 records):
-ActiveRecord Query:        0.43343 seconds
-SimpleQuery Execution:      0.06186 seconds
+ActiveRecord Query:                  0.47441 seconds
+SimpleQuery Execution (Struct):      0.05346 seconds
+SimpleQuery Execution (Read model):  0.14408 seconds
 ```
+- The **Struct-based** approach is the fastest. 
+- The **Read model** approach is still significantly faster than ActiveRecord, while letting you define custom logic or domain-specific attributes.
 
 ## Development
 

data/lib/simple_query/builder.rb

@@ -2,21 +2,24 @@
 
 module SimpleQuery
   class Builder
-    attr_reader :model, :arel_table, :selects, :wheres, :joins, :orders, :limits, :offsets
+    attr_reader :model, :arel_table
 
     def initialize(source)
       @model = source
       @arel_table = @model.arel_table
+
       @selects = []
-      @wheres = []
-      @joins = []
-      @orders = []
-      @limits = nil
-      @offsets = nil
-      @distinct_flag = false
+      @wheres = WhereClause.new(@arel_table)
+      @joins = JoinClause.new
+      @group_having = GroupHavingClause.new(@arel_table)
+      @orders = OrderClause.new(@arel_table)
+      @limits = LimitOffsetClause.new
+      @distinct_flag = DistinctClause.new
+
       @query_cache = {}
-      @result_struct = nil
       @query_built = false
+      @read_model_class = nil
+      @result_struct = nil
     end
 
     def select(*fields)
@@ -26,58 +29,75 @@ module SimpleQuery
     end
 
     def where(condition)
-      @wheres.concat(parse_where_condition(condition))
+      @wheres.add(condition)
       reset_query
       self
     end
 
     def join(table1, table2, foreign_key:, primary_key:)
-      @joins << {
-        table1: arel_table(table1),
-        table2: arel_table(table2),
-        foreign_key: foreign_key,
-        primary_key: primary_key
-      }
+      @joins.add(table1, table2, foreign_key: foreign_key, primary_key: primary_key)
       reset_query
       self
     end
 
     def order(order_conditions)
-      @orders.concat(parse_order_conditions(order_conditions))
+      @orders.add(order_conditions)
       reset_query
       self
     end
 
     def limit(number)
-      validate_positive_integer(number, "LIMIT")
-      @limits = number
+      @limits.with_limit(number)
       reset_query
       self
     end
 
     def offset(number)
-      validate_non_negative_integer(number, "OFFSET")
-      @offsets = number
+      @limits.with_offset(number)
       reset_query
       self
     end
 
     def distinct
-      @distinct_flag = true
+      @distinct_flag.set_distinct
+      reset_query
+      self
+    end
+
+    def group(*fields)
+      @group_having.add_group(*fields)
+      reset_query
+      self
+    end
+
+    def having(condition)
+      @group_having.add_having(condition)
+      reset_query
+      self
+    end
+
+    def map_to(klass)
+      @read_model_class = klass
       reset_query
       self
     end
 
     def execute
       records = ActiveRecord::Base.connection.select_all(cached_sql)
-      build_result_objects(records)
+      build_result_objects_from_rows(records)
     end
 
     def lazy_execute
       Enumerator.new do |yielder|
         records = ActiveRecord::Base.connection.select_all(cached_sql)
-        struct = result_struct(records.columns)
-        records.rows.each { |row| yielder << struct.new(*row) }
+        if @read_model_class
+          build_read_models_enumerator(records, yielder)
+        else
+          struct = result_struct(records.columns)
+          records.rows.each do |row_array|
+            yielder << struct.new(*row_array)
+          end
+        end
       end
     end
 
@@ -87,10 +107,11 @@ module SimpleQuery
       @query = Arel::SelectManager.new(Arel::Table.engine)
       @query.from(@arel_table)
       @query.project(*(@selects.empty? ? [@arel_table[Arel.star]] : @selects))
-      @query.distinct if @distinct_flag
 
+      apply_distinct
       apply_where_conditions
       apply_joins
+      apply_group_and_having
       apply_order_conditions
       apply_limit_and_offset
 
@@ -106,78 +127,117 @@ module SimpleQuery
     end
 
     def cached_sql
-      @query_cache[@wheres] ||= build_query.to_sql
+      key = [
+        @selects,
+        @wheres.conditions,
+        @joins.joins,
+        @group_having.group_fields,
+        @group_having.having_conditions,
+        @orders.orders,
+        @limits.limit_value,
+        @limits.offset_value,
+        @distinct_flag.use_distinct?
+      ]
+
+      @query_cache[key] ||= build_query.to_sql
+    end
+
+    def build_result_objects_from_rows(records)
+      if @read_model_class
+        build_read_models_from_arrays(records)
+      else
+        struct = result_struct(records.columns)
+        records.rows.map { |row_array| struct.new(*row_array) }
+      end
     end
 
-    def result_struct(columns)
-      @result_struct ||= Struct.new(*columns.map(&:to_sym))
-    end
+    def build_read_models_from_arrays(records)
+      columns = records.columns
+      column_map = columns.each_with_index.to_h
+      rows = records.rows
 
-    def parse_select_field(field)
-      case field
-      when Symbol then @arel_table[field]
-      when String then Arel.sql(field)
-      when Arel::Nodes::Node then field
-      else
-        raise ArgumentError, "Unsupported select field type: #{field.class}"
+      rows.map do |row_array|
+        obj = @read_model_class.allocate
+        @read_model_class.attributes.each do |attr_name, col_name|
+          idx = column_map[col_name]
+          obj.instance_variable_set(:"@#{attr_name}", row_array[idx]) if idx
+        end
+        obj
       end
     end
 
-    def parse_where_condition(condition)
-      case condition
-      when Hash then condition.map { |field, value| @arel_table[field].eq(value) }
-      when Arel::Nodes::Node then [condition]
-      else [Arel.sql(condition.to_s)]
+    def build_read_models_enumerator(records, yielder)
+      columns = records.columns
+      column_map = columns.each_with_index.to_h
+      records.rows.each do |row_array|
+        obj = @read_model_class.allocate
+        @read_model_class.attributes.each do |attr_name, col_name|
+          idx = column_map[col_name]
+          obj.instance_variable_set(:"@#{attr_name}", row_array[idx]) if idx
+        end
+        yielder << obj
       end
     end
 
-    def arel_table(table)
-      table.is_a?(Arel::Table) ? table : Arel::Table.new(table)
+    def result_struct(columns)
+      @result_struct ||= Struct.new(*columns.map(&:to_sym))
     end
 
-    def parse_order_conditions(order_conditions)
-      order_conditions.map do |field, direction|
-        validate_order_direction(direction)
-        @arel_table[field].send(direction)
-      end
+    def apply_distinct
+      @distinct_flag.apply_to(@query)
     end
 
-    def validate_order_direction(direction)
-      return if [:asc, :desc].include?(direction)
+    def apply_where_conditions
+      condition = @wheres.to_arel
+      @query.where(condition) if condition
+    end
 
-      raise ArgumentError, "Invalid order direction: #{direction}. Use :asc or :desc."
+    def apply_joins
+      @joins.apply_to(@query)
     end
 
-    def validate_positive_integer(number, label)
-      raise ArgumentError, "#{label} must be a positive integer" unless number.is_a?(Integer) && number.positive?
+    def apply_group_and_having
+      @group_having.apply_to(@query)
     end
 
-    def validate_non_negative_integer(number, label)
-      raise ArgumentError, "#{label} must be a non-negative integer" unless number.is_a?(Integer) && number >= 0
+    def apply_order_conditions
+      @orders.apply_to(@query)
     end
 
-    def build_result_objects(records)
-      struct = result_struct(records.columns)
-      records.rows.map { |row| struct.new(*row) }
+    def apply_limit_and_offset
+      @limits.apply_to(@query)
     end
 
-    def apply_where_conditions
-      @query.where(@wheres.inject(&:and)) if @wheres.any?
+    def parse_select_field(field)
+      case field
+      when Symbol
+        @arel_table[field]
+      when String
+        Arel.sql(field)
+      when Arel::Nodes::Node
+        field
+      else
+        raise ArgumentError, "Unsupported select field type: #{field.class}"
+      end
     end
 
-    def apply_joins
-      @joins.each do |join|
-        @query.join(join[:table2]).on(join[:table2][join[:foreign_key]].eq(join[:table1][join[:primary_key]]))
+    def method_missing(method_name, *args, &block)
+      if (scope_block = find_scope(method_name))
+        instance_exec(*args, &scope_block)
+        self
+      else
+        super
       end
     end
 
-    def apply_order_conditions
-      @orders.each { |order| @query.order(order) }
+    def respond_to_missing?(method_name, include_private = false)
+      !!find_scope(method_name) || super
     end
 
-    def apply_limit_and_offset
-      @query.take(@limits) if @limits
-      @query.skip(@offsets) if @offsets
+    def find_scope(method_name)
+      return unless model.respond_to?(:_simple_scopes)
+
+      model._simple_scopes[method_name.to_sym]
     end
   end
 end

data/lib/simple_query/clauses/distinct_clause.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class DistinctClause
+    def initialize
+      @use_distinct = false
+    end
+
+    def use_distinct?
+      @use_distinct
+    end
+
+    def set_distinct
+      @use_distinct = true
+    end
+
+    def apply_to(query)
+      query.distinct if @use_distinct
+      query
+    end
+  end
+end

data/lib/simple_query/clauses/group_having_clause.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class GroupHavingClause
+    attr_reader :group_fields, :having_conditions
+
+    def initialize(table)
+      @table = table
+      @group_fields = []
+      @having_conditions = []
+    end
+
+    def add_group(*fields)
+      @group_fields.concat(fields.map { |f| @table[f] })
+    end
+
+    def add_having(condition)
+      @having_conditions << condition
+    end
+
+    def apply_to(query)
+      @group_fields.each { |g| query.group(g) }
+      if @having_conditions.any?
+        combined = @having_conditions.inject { |c, a| c.and(a) }
+        query.having(combined)
+      end
+      query
+    end
+  end
+end

data/lib/simple_query/clauses/join_clause.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class JoinClause
+    attr_reader :joins
+
+    def initialize
+      @joins = []
+    end
+
+    def add(table1, table2, foreign_key:, primary_key:)
+      @joins << {
+        table1: to_arel_table(table1),
+        table2: to_arel_table(table2),
+        foreign_key: foreign_key,
+        primary_key: primary_key
+      }
+    end
+
+    def apply_to(query)
+      @joins.each do |join|
+        query.join(join[:table2])
+             .on(join[:table2][join[:foreign_key]]
+                   .eq(join[:table1][join[:primary_key]]))
+      end
+      query
+    end
+
+    private
+
+    def to_arel_table(obj)
+      obj.is_a?(Arel::Table) ? obj : Arel::Table.new(obj)
+    end
+  end
+end

data/lib/simple_query/clauses/limit_offset_clause.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class LimitOffsetClause
+    attr_reader :limit_value, :offset_value
+
+    def initialize
+      @limit_value = nil
+      @offset_value = nil
+    end
+
+    def with_limit(limit)
+      raise ArgumentError, "LIMIT must be a positive integer" unless limit.is_a?(Integer) && limit.positive?
+
+      @limit_value = limit
+    end
+
+    def with_offset(offset)
+      raise ArgumentError, "OFFSET must be a non-negative integer" unless offset.is_a?(Integer) && offset >= 0
+
+      @offset_value = offset
+    end
+
+    def apply_to(query)
+      query.take(@limit_value) if @limit_value
+      query.skip(@offset_value) if @offset_value
+      query
+    end
+  end
+end

data/lib/simple_query/clauses/order_clause.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class OrderClause
+    attr_reader :orders
+
+    def initialize(table)
+      @table = table
+      @orders = []
+    end
+
+    def add(order_conditions)
+      order_conditions.each do |field, direction|
+        validate_order_direction(direction)
+        @orders << @table[field].send(direction)
+      end
+    end
+
+    def apply_to(query)
+      @orders.each { |order_node| query.order(order_node) }
+      query
+    end
+
+    private
+
+    def validate_order_direction(direction)
+      return if [:asc, :desc].include?(direction)
+
+      raise ArgumentError, "Invalid order direction: #{direction}. Use :asc or :desc."
+    end
+  end
+end

data/lib/simple_query/clauses/where_clause.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class WhereClause
+    attr_reader :conditions
+
+    def initialize(table)
+      @table = table
+      @conditions = []
+    end
+
+    def add(condition)
+      parsed_conditions = parse_condition(condition)
+      @conditions.concat(parsed_conditions)
+    end
+
+    def to_arel
+      return nil if @conditions.empty?
+
+      @conditions.inject do |combined, current|
+        combined.and(current)
+      end
+    end
+
+    private
+
+    def parse_condition(condition)
+      case condition
+      when Hash
+        condition.map { |field, value| @table[field].eq(value) }
+      when Arel::Nodes::Node
+        [condition]
+      else
+        [Arel.sql(condition.to_s)]
+      end
+    end
+  end
+end

data/lib/simple_query/read_model.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class ReadModel
+    def self.attribute(attr_name, column: attr_name)
+      @attributes ||= {}
+      @attributes[attr_name] = column.to_s
+      attr_reader attr_name
+    end
+
+    def self.attributes
+      @attributes || {}
+    end
+
+    def self.build_from_row(row_hash)
+      obj = allocate
+      attributes.each do |attr_name, column_name|
+        obj.instance_variable_set(:"@#{attr_name}", row_hash[column_name])
+      end
+      obj
+    end
+
+    def initialize; end
+  end
+end

data/lib/simple_query/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleQuery
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/simple_query.rb

@@ -1,16 +1,65 @@
 # frozen_string_literal: true
 
+require "active_support/concern"
 require "active_record"
-require "simple_query/builder"
+
+require_relative "simple_query/builder"
+require_relative "simple_query/read_model"
+require_relative "simple_query/clauses/where_clause"
+require_relative "simple_query/clauses/join_clause"
+require_relative "simple_query/clauses/order_clause"
+require_relative "simple_query/clauses/distinct_clause"
+require_relative "simple_query/clauses/limit_offset_clause"
+require_relative "simple_query/clauses/group_having_clause"
 
 module SimpleQuery
   extend ActiveSupport::Concern
 
+  class Configuration
+    attr_accessor :auto_include_ar
+
+    def initialize
+      @auto_include_ar = false
+    end
+  end
+
+  def self.configure
+    yield config
+    auto_include! if config.auto_include_ar
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.auto_include!
+    ActiveRecord::Base.include(SimpleQuery)
+  end
+
+  class_methods do
+    def _simple_scopes
+      @_simple_scopes ||= {}
+    end
+
+    # A reusable scope that can be applied to a SimpleQuery::Builder instance
+    # Example:
+    #   simple_scope :active do
+    #     where(active: true)
+    #   end
+    #
+    # Parameterized scope:
+    #   simple_scope :by_name do |name|
+    #     where(name: name)
+    #   end
+    #
+    def simple_scope(name, &block)
+      _simple_scopes[name.to_sym] = block
+    end
+  end
+
   included do
     def self.simple_query
-      SimpleQuery::Builder.new(self)
+      Builder.new(self)
     end
   end
 end
-
-ActiveRecord::Base.include SimpleQuery

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_query
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex Kholodniak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-18 00:00:00.000000000 Z
+date: 2025-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,20 +16,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
-    - - "<"
+        version: '7.0'
+    - - "<="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
-    - - "<"
+        version: '7.0'
+    - - "<="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +100,21 @@ files:
 - README.md
 - lib/simple_query.rb
 - lib/simple_query/builder.rb
+- lib/simple_query/clauses/distinct_clause.rb
+- lib/simple_query/clauses/group_having_clause.rb
+- lib/simple_query/clauses/join_clause.rb
+- lib/simple_query/clauses/limit_offset_clause.rb
+- lib/simple_query/clauses/order_clause.rb
+- lib/simple_query/clauses/where_clause.rb
+- lib/simple_query/read_model.rb
 - lib/simple_query/version.rb
-homepage: https://oneruby.dev
+homepage: https://github.com/kholdrex/simple_query
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://oneruby.dev
+  homepage_uri: https://github.com/kholdrex/simple_query
   source_code_uri: https://github.com/kholdrex/simple_query
-  changelog_uri: https://github.com/kholdrex/simple_query/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/kholdrex/simple_query/blob/master/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: