strict_pagination 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7234dbd288be581e5a708b4c854d4918e7ddb7f79c80c13d4be3f3cfd681bf23
-  data.tar.gz: 9edfc21298022007fa6727da2d93b92ee5ff160ab9bb094de7a43f24749c14f6
+  metadata.gz: 88249f37e3e76bb824c4c0a527bf42d5206562f239c55896d30459990b9047f9
+  data.tar.gz: c0ecab0ea113dbbfdd792a7854f21011af99e703e8038281a04e1edd42951aad
 SHA512:
-  metadata.gz: c4fea6505c3b97324c0520271ddfbd722aacec173ab014fd969f459de5d6fca545b7eb5fb5cf59a41e17344a7948ebaf582c17925f4c52f8b61d1b027f7a8126
-  data.tar.gz: e074c0ebcbf7cc4664ecfad44552b1ba67f58478b6602b2af14a82d67af45d2f3d4781cdbf09a5cd200d66946fe368c66d3ba0ba93908d298f1a6124a3d5b20b
+  metadata.gz: 40be886cb36389573902cbdaf8cfdda2ec8161b94dbe0df1ab0c35ac2219c709d368c8178a1597205e5ab1fe2d7954fa99bbaa8031c3f7d86289a8494d610ab1
+  data.tar.gz: 15db3c489fa654ad9b2cde3529b03986a74a5a0d8a8fd5111eec78d6ff22043b0c734023b4b8f02463d385d7140f70bb9a4242fb2cceefbaccc0dc2f9bcd88bb

data/README.md

@@ -1,7 +1,12 @@
 # StrictPagination
 
+> **Keywords:** `pagination`, `rails`, `ruby`, `activerecord`, `api`, `validation`, `params`, `database`, `sql`, `query-validation`
+
 A Ruby gem that adds strict pagination validation to ActiveRecord, preventing unsafe JOINs that can cause inconsistent pagination results.
 
+[![Gem Version](https://badge.fury.io/rb/strict_pagination.svg)](https://badge.fury.io/rb/strict_pagination)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## Problem
 
 When using LIMIT/OFFSET with DISTINCT and JOINs to associations that multiply rows (like `has_many` or unsafe `has_one`), pagination can become inconsistent. This happens because:
@@ -15,6 +20,11 @@ When using LIMIT/OFFSET with DISTINCT and JOINs to associations that multiply ro
 
 This gem provides `strict_pagination` mode that validates queries before execution, ensuring they don't use JOINs that multiply rows when using pagination.
 
+## Requirements
+
+- Ruby 3.1.0 or higher
+- ActiveRecord 6.1 or higher (Rails 6.1+)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -43,29 +53,29 @@ Simply add `.strict_pagination` to your ActiveRecord queries with DISTINCT:
 
 ```ruby
 # Safe: no associations
-User.strict_pagination.distinct.page(1).per(10)
+User.strict_pagination.distinct.limit(10).offset(0)
 
 # Safe: belongs_to associations don't multiply rows
 Article.strict_pagination
        .includes(:author)
        .distinct
-       .page(1).per(10)
+       .limit(10).offset(0)
 
 # Safe: view-backed has_one associations
 Order.strict_pagination
      .includes(:latest_payment)  # backed by a database view
      .distinct
-     .page(1).per(10)
+     .limit(10).offset(0)
 
 # ERROR: has_many multiplies rows
 User.strict_pagination
     .includes(:posts)
     .distinct
-    .page(1).per(10)
+    .limit(10).offset(0)
 # => StrictPagination::ViolationError
 ```
 
-**Note:** Validation only runs when **both** `LIMIT` (from `.page()`) and `DISTINCT` are present. This is because the pagination issue only occurs with DISTINCT queries.
+**Note:** Validation only runs when **both** `LIMIT` (from `.limit()`) and `DISTINCT` are present. This is because the pagination issue only occurs with DISTINCT queries.
 
 ### When is Validation Triggered?
 
@@ -155,7 +165,7 @@ end
 
 # Now these are considered safe
 class Reports::UserSummary < ApplicationRecord; end
-Order.strict_pagination.includes(:user_summary).page(1)  # Safe
+Order.strict_pagination.includes(:user_summary).limit(20)  # Safe
 ```
 
 ## Best Practices
@@ -167,11 +177,14 @@ Use `strict_pagination` on all paginated API endpoints with DISTINCT:
 ```ruby
 # app/controllers/api/v1/users_controller.rb
 def index
+  page = (params[:page] || 1).to_i
+  per_page = (params[:per_page] || 20).to_i
+
   @users = User.strict_pagination
                .includes(:profile)  # Safe: belongs_to
                .distinct
-               .page(params[:page])
-               .per(params[:per_page])
+               .limit(per_page)
+               .offset((page - 1) * per_page)
 
   render json: @users
 end
@@ -201,7 +214,7 @@ end
 Author.strict_pagination
       .includes(:latest_book)
       .distinct
-      .page(1).per(10)
+      .limit(10).offset(0)
 ```
 
 ### Gradual Adoption
@@ -212,15 +225,27 @@ You can gradually adopt strict pagination in your codebase:
 # Start with critical endpoints
 class Api::V1::OrdersController < ApplicationController
   def index
-    @orders = Order.strict_pagination.distinct.page(params[:page])
+    page = (params[:page] || 1).to_i
+    per_page = 20
+
+    @orders = Order.strict_pagination
+                   .distinct
+                   .limit(per_page)
+                   .offset((page - 1) * per_page)
   end
 end
 
 # Once confident, use it everywhere
 class ApplicationRecord < ActiveRecord::Base
-  # Override default scope to use strict_pagination
-  def self.paginated(**options)
-    strict_pagination.distinct.page(options[:page]).per(options[:per_page])
+  # Helper method for pagination
+  def self.paginated(page: 1, per_page: 20)
+    page = page.to_i
+    per_page = per_page.to_i
+
+    strict_pagination
+      .distinct
+      .limit(per_page)
+      .offset((page - 1) * per_page)
   end
 end
 ```
@@ -250,25 +275,25 @@ The gem follows Rails best practices:
 
 ```ruby
 # No associations
-User.strict_pagination.distinct.page(1).per(20)
+User.strict_pagination.distinct.limit(20).offset(0)
 
 # belongs_to only
 Comment.strict_pagination
        .includes(:author, :post)
        .distinct
-       .page(1).per(20)
+       .limit(20).offset(0)
 
 # View-backed has_one
 Invoice.strict_pagination
        .includes(:latest_payment)
        .distinct
-       .page(1).per(20)
+       .limit(20).offset(0)
 
 # has_one with unique constraint
 User.strict_pagination
     .includes(:profile)  # profiles.user_id has unique index
     .distinct
-    .page(1).per(20)
+    .limit(20).offset(0)
 ```
 
 ### Unsafe Queries
@@ -278,19 +303,19 @@ User.strict_pagination
 User.strict_pagination
     .includes(:posts)  # Error: posts multiplies rows
     .distinct
-    .page(1).per(20)
+    .limit(20).offset(0)
 
 # has_and_belongs_to_many
 Article.strict_pagination
        .includes(:tags)  # Error: tags multiplies rows
        .distinct
-       .page(1).per(20)
+       .limit(20).offset(0)
 
 # has_one without unique constraint
 Account.strict_pagination
        .includes(:primary_contact)  # Error: no unique constraint
        .distinct
-       .page(1).per(20)
+       .limit(20).offset(0)
 ```
 
 ## Development
@@ -317,6 +342,28 @@ gem build strict_pagination.gemspec
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/hdamico/strict_pagination.
 
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## Roadmap
+
+- [ ] Add helper methods for easier pagination parameter handling
+- [ ] Performance benchmarks and optimization guide
+- [ ] Rails generator for adding strict_pagination to existing controllers
+- [ ] Automated migration helper for converting has_many to view-backed has_one
+- [ ] Support for custom validation rules
+
+## Community & Support
+
+- **Issues:** Report bugs or request features at [GitHub Issues](https://github.com/hdamico/strict_pagination/issues)
+- **Discussions:** Ask questions and share ideas at [GitHub Discussions](https://github.com/hdamico/strict_pagination/discussions)
+- **Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+---
+
+**Made with ❤️ for the Ruby and Rails community**
+
+*If you find this gem useful, please ⭐ star the repository and share it with others!*

data/lib/strict_pagination/active_record.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-require "strict_pagination/version"
-require "strict_pagination/validator"
-require "strict_pagination/relation_methods"
-require "strict_pagination/relation_extension"
-require "active_support/lazy_load_hooks"
+require 'strict_pagination/version'
+require 'strict_pagination/validator'
+require 'strict_pagination/relation_methods'
+require 'strict_pagination/relation_extension'
+require 'active_support/lazy_load_hooks'
 
 ActiveSupport.on_load :active_record do
-  require "active_record"
+  require 'active_record'
 
-  ::ActiveRecord::Relation.include StrictPagination::RelationMethods
-  ::ActiveRecord::Relation.include StrictPagination::Validator
-  ::ActiveRecord::Relation.prepend StrictPagination::RelationExtension
+  ActiveRecord::Relation.include StrictPagination::RelationMethods
+  ActiveRecord::Relation.include StrictPagination::Validator
+  ActiveRecord::Relation.prepend StrictPagination::RelationExtension
 end

data/lib/strict_pagination/railtie.rb

@@ -2,9 +2,9 @@
 
 module StrictPagination
   class Railtie < ::Rails::Railtie
-    initializer "strict_pagination.configure_rails_initialization" do
+    initializer 'strict_pagination.configure_rails_initialization' do
       ActiveSupport.on_load(:active_record) do
-        require "strict_pagination/active_record"
+        require 'strict_pagination/active_record'
       end
     end
   end

data/lib/strict_pagination/relation_methods.rb

@@ -65,9 +65,7 @@ module StrictPagination
       return unless limit_value
 
       # Check if we should validate without DISTINCT requirement
-      unless StrictPagination.config.validate_on_all_queries
-        return unless distinct_value
-      end
+      return if !StrictPagination.config.validate_on_all_queries && !distinct_value
 
       # Get all unsafe associations that are actually included/joined
       unsafe_associations = detect_unsafe_included_associations

data/lib/strict_pagination/validator.rb

@@ -47,8 +47,8 @@ module StrictPagination
       klass_obj = reflection.klass
 
       # Check if it's a database view (default prefixes)
-      return true if klass_obj.name.start_with?("Views::")
-      return true if klass_obj.table_name.start_with?("views_")
+      return true if klass_obj.name.start_with?('Views::')
+      return true if klass_obj.table_name.start_with?('views_')
 
       # Check custom view prefixes from config
       StrictPagination.config.safe_view_prefixes.each do |prefix|
@@ -119,7 +119,7 @@ module StrictPagination
     end
 
     def build_error_message(unsafe_associations)
-      associations_list    = unsafe_associations.map { |name| "`#{name}`" }.join(", ")
+      associations_list    = unsafe_associations.map { |name| "`#{name}`" }.join(', ')
       associations_details = unsafe_associations.map { |a| "  - #{a}: #{describe_association_type(a)}" }.join("\n")
 
       <<~MSG.squish
@@ -141,16 +141,16 @@ module StrictPagination
     # Describes the association type for error messages.
     def describe_association_type(association_name)
       reflection = klass.reflect_on_association(association_name.to_sym)
-      return "unknown" unless reflection
+      return 'unknown' unless reflection
 
       association_type_description(reflection.macro)
     end
 
     def association_type_description(macro)
       case macro
-      when :has_many then "has_many (always multiplies rows)"
-      when :has_and_belongs_to_many then "has_and_belongs_to_many (always multiplies rows)"
-      when :has_one then "has_one without unique constraint (can multiply rows)"
+      when :has_many then 'has_many (always multiplies rows)'
+      when :has_and_belongs_to_many then 'has_and_belongs_to_many (always multiplies rows)'
+      when :has_one then 'has_one without unique constraint (can multiply rows)'
       else macro.to_s
       end
     end

data/lib/strict_pagination/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StrictPagination
-  VERSION = "0.1.1"
+  VERSION = '0.2.0'
 end

data/lib/strict_pagination.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-require "active_support/lazy_load_hooks"
-require "strict_pagination/version"
-require "strict_pagination/config"
+require 'active_record'
+require 'active_support/lazy_load_hooks'
+require 'strict_pagination/version'
+require 'strict_pagination/config'
 
 module StrictPagination
   # Custom error raised when attempting pagination with unsafe JOINs
@@ -12,8 +13,8 @@ end
 
 # Load Rails integration if Rails is available
 if defined?(Rails::Railtie)
-  require "strict_pagination/railtie"
+  require 'strict_pagination/railtie'
 else
   # For non-Rails environments, load ActiveRecord integration directly
-  require "strict_pagination/active_record"
+  require 'strict_pagination/active_record'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strict_pagination
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Hernán d'Amico
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.0'
@@ -25,41 +25,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-description: Adds strict_pagination mode to ActiveRecord::Relation to validate queries
-  before execution, ensuring they don't use JOINs that multiply rows (has_many, unsafe
-  has_one). Helps prevent inconsistent pagination with LIMIT/OFFSET + DISTINCT.
+description: StrictPagination enforces type-safe pagination parameters and validates
+  queries before execution, preventing unsafe JOINs (has_many, unsafe has_one) that
+  multiply rows and cause inconsistent pagination with LIMIT/OFFSET + DISTINCT. Provides
+  helpers for ActiveRecord and API responses.
 email:
 - hernan.damico67@gmail.com
 executables: []
@@ -80,8 +53,10 @@ homepage: https://github.com/hdamico/strict_pagination
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/hdamico/strict_pagination
+  homepage_uri: https://github.com/hdamico/strict_pagination
   changelog_uri: https://github.com/hdamico/strict_pagination/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/hdamico/strict_pagination/issues
+  documentation_uri: https://github.com/hdamico/strict_pagination/blob/main/README.md
 rdoc_options: []
 require_paths:
 - lib
@@ -89,7 +64,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -98,5 +73,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.1
 specification_version: 4
-summary: Strict pagination validation for ActiveRecord to prevent unsafe JOINs
+summary: Strict and safe pagination for Ruby/Rails apps with ActiveRecord
 test_files: []