activerecord_extras 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4faa1738c4c2baf22f8e3503ee92b411373ec7d5b99810dd67e7544af47833b2
+  data.tar.gz: 909628842c1d2f26e1017b1415ced32dccf63435c5733b8f99f5c0c08679eee2
+SHA512:
+  metadata.gz: 436f270c9237b4f14744ba39f771260104e23c6d562b5739db01d30b77d3b3bd4f53566fef6919813ccf605be6f4ff1047934dc6d18c6a7db2b98f99a2770a61
+  data.tar.gz: c576cdb811f946cda9cc581edb3bce96d9cbd7f224f7f77eaa06a75f552968ea2df8f50790a35d324df1c03b153f30430182d753d0e7d3e9a05bb7358c99d1e3

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Till Schulte-Coerne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# ActiveRecord Extras
+
+**ActiveRecord Extras** provides helpful utility methods and query extensions for ActiveRecord models.
+It focuses on building SQL subqueries for `has_many` associations using `EXISTS` and `COUNT`, while keeping full composability within ActiveRecord queries.
+
+---
+
+## Features
+
+- `exists_association` and `count_association` methods for Arel-based subqueries
+- Scopes:
+  - `with_existing(:association)`
+  - `without_existing(:association)`
+- Extended select support:
+  - `with_counts(:association)` — includes counts in result sets
+  - Accepts optional block for filtering join conditions
+- Fully composable ActiveRecord relations
+- No monkey-patching, Rails 6+ compatible
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "activerecord_extras"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install manually:
+
+```bash
+gem install activerecord_extras
+```
+
+---
+
+## Usage
+
+### `with_existing` and `without_existing`
+
+```ruby
+User.with_existing(:posts)
+User.without_existing(:comments)
+```
+
+### `with_counts`
+
+Adds a `SELECT COUNT(*)` subquery per association:
+
+```ruby
+User.with_counts(:posts)
+```
+
+Supports filtering via block:
+
+```ruby
+User.with_counts(:posts) do |join_condition, posts|
+  join_condition.and(posts[:published].eq(true))
+end
+```
+
+This produces SQL like:
+
+```sql
+SELECT users.*, (
+  SELECT COUNT(*) FROM posts
+  WHERE posts.user_id = users.id AND posts.published = TRUE
+) AS posts_count
+```
+
+---
+
+## API Reference
+
+### `exists_association(association_name, &block)`
+
+Returns an Arel EXISTS subquery.
+
+### `count_association(association_name, &block)`
+
+Returns a grouped COUNT(*) Arel subquery.
+
+### `with_counts(*association_names, &block)`
+
+Selects all columns from the model and adds one COUNT subquery per named association. The optional block modifies join conditions.
+
+---
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+Tests use SQLite in-memory schema and require no database setup.
+
+---
+
+## License
+
+MIT License © [Till Schulte-Coerne](https://github.com/tillsc)

data/lib/active_record/extras/association_scopes.rb

@@ -0,0 +1,105 @@
+module ActiveRecord
+  module Extras
+    module AssociationScopes
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Builds a subquery for a has_many association.
+        # Can be used to generate EXISTS or COUNT subqueries.
+        #
+        # @param association_name [Symbol, String] the name of the has_many association
+        # @param mode [:exists, :count] determines the kind of subquery
+        # @yield [join_conditions, target_table] optional block to modify the join conditions
+        # @return [Arel::Nodes::SqlLiteral] the subquery as an Arel node
+        def association_subquery(association_name, mode: :exists, &extra_conditions_block)
+          reflection = reflections[association_name.to_s]
+
+          unless reflection
+            raise ArgumentError, "Unknown association: #{association_name}"
+          end
+
+          unless reflection.macro == :has_many
+            raise ArgumentError, "Only has_many associations are supported (got #{reflection.macro})"
+          end
+
+          foreign_keys = Array(reflection.foreign_key)
+          primary_keys = Array(reflection.active_record_primary_key)
+
+          unless foreign_keys.size == primary_keys.size
+            raise ArgumentError, "Mismatch in key counts: #{foreign_keys} vs #{primary_keys}"
+          end
+
+          source_table = arel_table
+          target_table = reflection.klass.arel_table
+
+          join_conditions = foreign_keys.zip(primary_keys).map do |fk, pk|
+            target_table[fk].eq(source_table[pk])
+          end.reduce(&:and)
+
+          # Allow caller to modify the join condition via block
+          if extra_conditions_block
+            new_conditions = extra_conditions_block.call(join_conditions, target_table)
+            join_conditions = new_conditions if new_conditions
+          end
+
+          case mode
+          when :exists
+            target_table.project(Arel.sql("1")).where(join_conditions).exists
+          when :count
+            Arel::Nodes::Grouping.new(
+              target_table.project(Arel.star.count).where(join_conditions)
+            )
+          else
+            raise ArgumentError, "Unknown mode: #{mode.inspect} (expected :exists or :count)"
+          end
+        end
+
+        # Builds an EXISTS subquery for the given association.
+        # Shorthand for association_subquery(..., mode: :exists)
+        def exists_association(association_name, &block)
+          association_subquery(association_name, mode: :exists, &block)
+        end
+
+        # Builds a COUNT subquery for the given association.
+        # Shorthand for association_subquery(..., mode: :count)
+        def count_association(association_name, &block)
+          association_subquery(association_name, mode: :count, &block)
+        end
+
+        # Adds a WHERE EXISTS (...) clause for the given association.
+        #
+        # Example:
+        #   User.with_existing(:posts)
+        def with_existing(association_name, &block)
+          where(exists_association(association_name, &block))
+        end
+
+        # Adds a WHERE NOT EXISTS (...) clause for the given association.
+        #
+        # Example:
+        #   User.without_existing(:comments)
+        def without_existing (association_name, &block)
+          where.not(exists_association(association_name, &block))
+        end
+
+        # Selects all columns plus COUNT subqueries for the given associations.
+        #
+        # Example:
+        #   User.with_counts(:posts, :comments)
+        #
+        # Produces:
+        #   SELECT users.*, (SELECT COUNT(*) FROM posts WHERE ...) AS posts_count,
+        #                      (SELECT COUNT(*) FROM comments WHERE ...) AS comments_count
+        def with_counts (*association_names, &block)
+          selections = [arel_table[Arel.star]] +
+                       association_names.map do |name|
+                         count_association(name, &block).as("#{name}_count")
+                       end
+
+          select(*selections)
+        end
+      end
+
+    end
+  end
+end

data/lib/active_record/extras/engine.rb

@@ -0,0 +1,11 @@
+module ActiveRecord
+  module Extras
+    class Engine < ::Rails::Engine
+      initializer "active_record.extras.active_record_integration" do
+        ActiveSupport.on_load(:active_record) do
+          include ActiveRecord::Extras::AssociationScopes
+        end
+      end
+    end
+  end
+end

data/lib/active_record/extras/version.rb

@@ -0,0 +1,6 @@
+module ActiveRecord
+  module Extras
+    VERSION = "0.1.0"
+    Version = VERSION
+  end
+end

data/lib/active_record/extras.rb

@@ -0,0 +1,7 @@
+require 'active_record/extras/version'
+
+module ActiveRecord
+  module Extras
+
+  end
+end

data/lib/activerecord_extras.rb

@@ -0,0 +1 @@
+require 'active_record/extras'

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: activerecord_extras
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Till Schulte-Coerne
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: activerecord_extras provides utility methods and scopes for ActiveRecord
+  models, including EXISTS and COUNT subqueries on has_many associations, and SQL
+  helpers for boolean casting.
+email:
+- ruby@trsnet.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/active_record/extras.rb
+- lib/active_record/extras/association_scopes.rb
+- lib/active_record/extras/engine.rb
+- lib/active_record/extras/version.rb
+- lib/activerecord_extras.rb
+homepage: https://github.com/tillsc/activerecord_extras
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tillsc/activerecord_extras
+  source_code_uri: https://github.com/tillsc/activerecord_extras
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Extensions and utilities for ActiveRecord, including association subqueries
+  and convenience scopes.
+test_files: []