nueca_rails_interfaces 1.2.8 → 1.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4666de0cb174c7bfac30b5efbade4c91b77e974747e15ff18e5b7159f3e557fc
-  data.tar.gz: 4b487712a93e076adf1431c5fcaa5ed535cdb189b1c87917779b0b8c668d83e3
+  metadata.gz: 06fa9d84241065bed1906ea3c75590d9d3651ad508e4994653e5edfc7f7f9b60
+  data.tar.gz: 1a08ad66325e0db8c57f2601115bee93d00490b4f59d4aaf0226c7a06cebdc39
 SHA512:
-  metadata.gz: d5b80763ac2da7bf9720b564716d5f8b1e0bb578f43cad3e7b2ecd8b526393a72a0d682cb4eb2b32936f8c3503e8f76f226e87695db467b3516689c6518bfc47
-  data.tar.gz: 9468e0254e8ad17fe0c90e88a477f739718ca32263179a9bac51ab7f8bcafd82231a0c1bfb242777ef76da13ffde2e06a7a49d44f1b5e356bc394c8d2c162328
+  metadata.gz: cc1c35a7af8f4e6e871ff6d0445f27fc4405faae4f8e2ed9fd6b1c51652b6688c2d708e63a8ae4697d4ed500a2ba40086307a81150953e7f3c2a9eef73e3355a
+  data.tar.gz: ac34f696efc3b533c3bbb0c5d19aa1806b18c457f80fb28e8908f07631a8d02d28ff145d444ed960a63ba8f3d033cccf4f125ab94a01fd0eefa7c035caf3ea9d

data/lib/nueca_rails_interfaces/v2/pagination/base_adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module NuecaRailsInterfaces
+  module V2
+    module Pagination
+      # Base adapter module for pagination strategies
+      # Modules must implement the .paginate(collection, page, per_page) method
+      module BaseAdapter
+        # Paginate the collection based on the provided page and per page values.
+        # @param [ActiveRecord::Relation] collection The collection to be paginated.
+        # @param [Integer] page The page number.
+        # @param [Integer] per_page The number of records per page.
+        # @return [ActiveRecord::Relation] The paginated collection.
+        def paginate(collection, page, per_page)
+          raise NotImplementedError, "#{name} must implement the .paginate(collection, page, per_page) method"
+        end
+      end
+    end
+  end
+end

data/lib/nueca_rails_interfaces/v2/pagination/kaminari_adapter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_adapter'
+
+module NuecaRailsInterfaces
+  module V2
+    module Pagination
+      # Adapter for Kaminari gem.
+      module KaminariAdapter
+        extend BaseAdapter
+
+        def self.paginate(collection, page, per_page)
+          collection.page(page).per(per_page)
+        end
+      end
+    end
+  end
+end

data/lib/nueca_rails_interfaces/v2/pagination/pagy_adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base_adapter'
+
+module NuecaRailsInterfaces
+  module V2
+    module Pagination
+      # Adapter for Pagy gem.
+      module PagyAdapter
+        extend BaseAdapter
+
+        def self.paginate(collection, page, per_page)
+          @helper ||= Class.new { include ::Pagy::Backend }.new
+          _pagy, records = @helper.send(:pagy, collection, page: page, items: per_page)
+          records
+        end
+      end
+    end
+  end
+end

data/lib/nueca_rails_interfaces/v2/pagination/will_paginate_adapter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base_adapter'
+
+module NuecaRailsInterfaces
+  module V2
+    module Pagination
+      # Adapter for WillPaginate gem.
+      module WillPaginateAdapter
+        extend BaseAdapter
+
+        def self.paginate(collection, page, per_page)
+          collection.paginate(page: page, per_page: per_page)
+        end
+      end
+    end
+  end
+end

data/lib/nueca_rails_interfaces/v2/query_interface.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative 'pagination/base_adapter'
+require_relative 'pagination/will_paginate_adapter'
+require_relative 'pagination/kaminari_adapter'
+require_relative 'pagination/pagy_adapter'
+
+module NuecaRailsInterfaces
+  module V2
+    # V2 Query Interface is the same as V1 Query Interface,
+    # but with changes in the pagination logic.
+    # V1 had tight coupling with WillPaginate, this version decouples the query interface from it,
+    # allowing for custom pagination adapters to be used.
+    module QueryInterface
+      # The basis for validity of pagination settings. It also contains default values.
+      VALID_PAGINATION_HASH = {
+        max: 20, # Absolute maximum number of records per page, even if the query requests for more.
+        min: 1, # Absolute minimum number of records per page, even if the query requests for less.
+        per_page: 20, # Default number of records per page if not specified in the query.
+        page: 1 # Default page number if not specified in the query.
+      }.freeze
+
+      # Basis for considering a non-paging result even when the query is being processed for pagination.
+      # This number states the invalidity of pagination, but it exists for legacy support.
+      NO_PAGING_THRESHOLD = 1_000_000
+
+      class << self
+        def included(base)
+          # This is the method to call outside this object to apply the query filters, sortings and paginations.
+          # @param [Hash] query The query parameters.
+          # @param [ActiveRecord::Relation] collection The collection to be queried.
+          base.define_singleton_method(:call) do |query, collection|
+            new(query, collection).call
+          end
+        end
+      end
+
+      attr_reader :query, :collection
+
+      # Do not override! This is how we will always initialize our query objects.
+      # No processing should be done in the initialize method.
+      # @param [Hash] query The query parameters.
+      # @param [ActiveRecord::Relation] collection The collection to be queried.
+      def initialize(query, collection, pagination: true)
+        @query = query
+        @collection = collection
+        @pagination_flag = pagination
+        query_aliases
+      end
+
+      # Do not override. This is the method to call outside this object
+      # to apply the query filters, sortings and paginations.
+      def call
+        apply_filters!
+        apply_sorting!
+        apply_pagination!
+        collection
+      end
+
+      private
+
+      # Place here filters. Be sure to assign @collection to override the original collection. Be sure it is private!
+      def filters; end
+
+      # Place here sorting logic. Be sure to assign @collection to override the original collection.
+      # Be sure it is private!
+      def sorts; end
+
+      # Pagination settings to modify the default behavior of a query object.
+      # Default values are in VALID_PAGINATION_HASH constant.
+      # Override the method to change the default values.
+      def pagination_settings
+        {}
+      end
+
+      # Always updated alias of filters.
+      def apply_filters!
+        filters
+      end
+
+      # Always updated alias of sorts.
+      def apply_sorting!
+        sorts
+      end
+
+      # Paginates the collection based on query or settings.
+      def apply_pagination!
+        raise 'Invalid pagination settings.' unless correct_pagination_settings? # rubocop:disable Style/ImplicitRuntimeError
+        return unless @pagination_flag
+
+        @collection = pagination_adapter.paginate(collection, fetch_page_value, fetch_per_page_value)
+      end
+
+      # Selects the appropriate pagination adapter based on loaded gems.
+      # The first adapter found will be used.
+      # The adapters are checked in the following order: WillPaginate, Kaminari, Pagy.
+      # Override this method if using custom pagination adapter.
+      # @return [NuecaRailsInterfaces::V2::Pagination::BaseAdapter] The pagination adapter.
+      def pagination_adapter
+        @pagination_adapter ||=
+          if defined?(::WillPaginate)
+            NuecaRailsInterfaces::V2::Pagination::WillPaginateAdapter
+          elsif defined?(::Kaminari)
+            NuecaRailsInterfaces::V2::Pagination::KaminariAdapter
+          elsif defined?(::Pagy)
+            NuecaRailsInterfaces::V2::Pagination::PagyAdapter
+          else
+            # rubocop:disable Style/ImplicitRuntimeError
+            raise 'No compatible pagination library detected (WillPaginate, Kaminari, or Pagy) ' \
+                  'and collection does not respond to :paginate.'
+            # rubocop:enable Style/ImplicitRuntimeError
+          end
+      end
+
+      # Logic for fetching the page value from the query or settings.
+      def fetch_page_value
+        query&.key?(:page) ? query[:page].to_i : merged_pagination_settings[:page]
+      end
+
+      # Logic for fetching the per page value from the query or settings.
+      def fetch_per_page_value
+        per_page = query&.key?(:per_page) ? query[:per_page].to_i : merged_pagination_settings[:per_page]
+        per_page.clamp(merged_pagination_settings[:min], merged_pagination_settings[:max])
+      end
+
+      # Checks if the pagination settings are correct.
+      # The app crashes on misconfiguration.
+      def correct_pagination_settings?
+        return false unless pagination_settings.is_a?(Hash)
+
+        detected_keys = []
+        merged_pagination_settings.each_key do |key|
+          return false unless VALID_PAGINATION_HASH.key?(key)
+
+          detected_keys << key
+        end
+
+        detected_keys.sort == VALID_PAGINATION_HASH.keys.sort
+      end
+
+      # The final result of pagination settings, and thus the used one.
+      def merged_pagination_settings
+        @merged_pagination_settings ||= VALID_PAGINATION_HASH.merge(pagination_settings)
+      end
+
+      # Aliases for query parameters for legacy support.
+      # No need to override this in children. Directly modify this method in this interface if need be.
+      def query_aliases
+        query[:per_page] = query[:limit] if query[:limit].present? && query[:per_page].blank?
+      end
+
+      # For deprecation. Use this for queries that do not need pagination.
+      # Queries will still be paginated as a result, but with the use of the threshold,
+      # the result is as good as a non-paginated result,
+      # and it will be treated as such.
+      def no_pagination
+        Rails.logger.warn 'Querying without paging is deprecated. Enforce paging in queries!'
+        { max: NO_PAGING_THRESHOLD, min: NO_PAGING_THRESHOLD }
+      end
+    end
+  end
+end

data/lib/nueca_rails_interfaces/v3/form_interface.rb

@@ -7,7 +7,7 @@ module NuecaRailsInterfaces
     #
     # Models managed by the form are declared explicitly with the `model` macro.
     # Their attributes arrive as a nested hash keyed by the model name, which is
-    # what `fields_for :school_year, f.object.school_year` produces in the view —
+    # what `fields_for :school_year, f.object.school_year` produces in the view;
     # e.g. `school_year: { name: "..." }`.  This maps directly to:
     # `params.expect(my_form: [{ school_year: [:name] }, :other_field])`
     #
@@ -80,7 +80,7 @@ module NuecaRailsInterfaces
 
         # Builds the model instance from the given attributes hash, assigning only
         # fields the model recognises.  Unknown fields are silently discarded.
-        # `attrs` may be a plain Hash or ActionController::Parameters — both are
+        # `attrs` may be a plain Hash or ActionController::Parameters; both are
         # normalised to a plain Hash before processing; field whitelisting via
         # Splits options into model instances and regular form attributes.
         # Hash-valued keys matching a declared model are built into model instances.
@@ -153,7 +153,7 @@ module NuecaRailsInterfaces
 
       # Returns a merged hash of model instances and regular form attributes.
       # Defined here (included, not prepended) so that a form class can override it
-      # by defining its own `attributes` method — the class-level definition is found
+      # by defining its own `attributes` method; the class-level definition is found
       # first in the MRO, falling back to this default when no override exists.
       def attributes
         result = {}

data/lib/nueca_rails_interfaces/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NuecaRailsInterfaces
-  VERSION = '1.2.8'
+  VERSION = '1.2.9'
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nueca_rails_interfaces
 version: !ruby/object:Gem::Version
-  version: 1.2.8
+  version: 1.2.9
 platform: ruby
 authors:
 - Tien
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -43,6 +44,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+description: 
 email:
 - tieeeeen1994@gmail.com
 executables: []
@@ -63,6 +65,11 @@ files:
 - lib/nueca_rails_interfaces/v1/query_interface.rb
 - lib/nueca_rails_interfaces/v1/service_interface.rb
 - lib/nueca_rails_interfaces/v2/form_interface.rb
+- lib/nueca_rails_interfaces/v2/pagination/base_adapter.rb
+- lib/nueca_rails_interfaces/v2/pagination/kaminari_adapter.rb
+- lib/nueca_rails_interfaces/v2/pagination/pagy_adapter.rb
+- lib/nueca_rails_interfaces/v2/pagination/will_paginate_adapter.rb
+- lib/nueca_rails_interfaces/v2/query_interface.rb
 - lib/nueca_rails_interfaces/v2/service_interface.rb
 - lib/nueca_rails_interfaces/v3/form_interface.rb
 - lib/nueca_rails_interfaces/v3/service_interface.rb
@@ -73,6 +80,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -87,7 +95,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.7
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Interfaces for known object entities in Rails Development at Nueca.
 test_files: []