nueca_rails_interfaces 1.1.2 → 1.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbcdb703d90c83096aa868e52808ce08c4801267cca85927ae1299cf70f0ed32
-  data.tar.gz: ea0af8ccfca4f1561382d5e25ee97ff4ca4b95d5702d4ad5957bf80ab80284b4
+  metadata.gz: 06fa9d84241065bed1906ea3c75590d9d3651ad508e4994653e5edfc7f7f9b60
+  data.tar.gz: 1a08ad66325e0db8c57f2601115bee93d00490b4f59d4aaf0226c7a06cebdc39
 SHA512:
-  metadata.gz: 66f4e97c4d687815f825d0fc4c22d529f716846b4f845415b0f5f35784140cef97cd159b30617e009484f84b9c3ddec80bbdc8e1b8e502ee82eae1e52d49a5e8
-  data.tar.gz: 859e241733b214d7c168f0ab0a020e906eab24179a60d78bf777146cb30f617b62c247f710797a45936528c8795731a453091d62c69d2d049933dd1fbba76fed
+  metadata.gz: cc1c35a7af8f4e6e871ff6d0445f27fc4405faae4f8e2ed9fd6b1c51652b6688c2d708e63a8ae4697d4ed500a2ba40086307a81150953e7f3c2a9eef73e3355a
+  data.tar.gz: ac34f696efc3b533c3bbb0c5d19aa1806b18c457f80fb28e8908f07631a8d02d28ff145d444ed960a63ba8f3d033cccf4f125ab94a01fd0eefa7c035caf3ea9d

data/.rubocop.yml

@@ -1,17 +1,9 @@
 plugins:
-  - rubocop-rails
+  - rubocop-nueca
   - rubocop-rake
-  - rubocop-rspec
 
-AllCops:
-  TargetRubyVersion: 3.3
-  NewCops: enable
-
-Layout/LineLength:
-  Max: 120
-
-RSpec/NestedGroups:
-  Max: 5
+Style/ClassMethodsDefinitions:
+  Enabled: false
 
-RSpec/VerifiedDoubles:
+Style/OptionHash:
   Enabled: false

data/Rakefile

@@ -9,4 +9,4 @@ require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: [:spec, :rubocop]

data/lib/nueca_rails_interfaces/v1/query_interface.rb

@@ -86,7 +86,7 @@ module NuecaRailsInterfaces
 
       # Paginates the collection based on query or settings.
       def apply_pagination!
-        raise 'Invalid pagination settings.' unless correct_pagination_settings?
+        raise 'Invalid pagination settings.' unless correct_pagination_settings? # rubocop:disable Style/ImplicitRuntimeError
         return unless @pagination_flag
 
         @collection = collection.paginate(page: fetch_page_value, per_page: fetch_per_page_value)

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

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module NuecaRailsInterfaces
+  module V3
+    # V3 Form Interface delegates model validation to the actual model instances
+    # rather than reimplementing model validations inside the form.
+    #
+    # 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;
+    # e.g. `school_year: { name: "..." }`.  This maps directly to:
+    # `params.expect(my_form: [{ school_year: [:name] }, :other_field])`
+    #
+    # Only models listed in the `model` macro are processed; any key whose name
+    # matches a declared model and whose value is a Hash (or Parameters) is treated
+    # as model attributes.  Everything else is treated as a regular form attribute.
+    # Fields inside a model hash that the model does not recognise are silently
+    # discarded.
+    #
+    # Custom form-level fields (fields that belong to the form, not to any model)
+    # are declared as plain `attr_accessor`s on the form class, just like any other
+    # ActiveModel attribute.
+    #
+    # Calling `valid?` on the form runs form-level validations first, then calls
+    # `valid?` on each model instance and propagates any model errors onto the form
+    # under the model name key (e.g. `errors[:payment]`).  `fields_for :payment`
+    # in the view binds to `form.payment` and reads that object's own errors for
+    # per-field error rendering, so both levels work naturally together.
+    #
+    # The `attributes` method returns a hash of model instances merged with any
+    # regular form attributes.  It can be overridden in the form class.
+    module FormInterface
+      # Prepended so these methods precede ActiveModel::Model's versions in the
+      # method resolution order.  When `base.include(ActiveModel::Model)` is called
+      # inside the `included` hook, ActiveModel ends up earlier in the ancestor chain,
+      # which would otherwise cause ActiveModel::API#initialize to intercept `new`
+      # before our param-splitting logic runs.
+      module InstanceMethods
+        def initialize(options = {})
+          @model_instances = {}
+          @regular_attributes = extract_regular_attributes(options)
+
+          # Pre-instantiate declared models that were not present in the params
+          # (e.g. the form is used in a `new` action with no input yet).
+          (self.class.declared_models - @model_instances.keys).each do |model_sym|
+            @model_instances[model_sym] = model_sym.to_s.camelize.constantize.new
+          end
+
+          super(**@regular_attributes)
+        end
+
+        def valid?(context = nil)
+          # Clears errors and runs form-level validations.
+          super
+
+          error_key = self.class.flatten_errors? ? :base : nil
+
+          @model_instances.each do |model_name, model_instance|
+            next if model_instance.valid?
+
+            model_instance.errors.each do |error|
+              errors.add(error_key || model_name, error.full_message)
+            end
+          end
+
+          errors.empty?
+        end
+
+        def method_missing(name, *args, &)
+          return @model_instances[name] if @model_instances.key?(name)
+
+          super
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          @model_instances.key?(name) || super
+        end
+
+        private
+
+        # 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
+        # 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.
+        # Hash-valued keys for undeclared models are silently discarded.
+        # All other (scalar) keys are returned as regular attributes for super.
+        def extract_regular_attributes(options)
+          regular_attrs = {}
+          options.each do |key, value|
+            if self.class.declared_models.include?(key.to_sym) && value.respond_to?(:each_pair)
+              build_model_instance(key.to_sym, value)
+            elsif !value.respond_to?(:each_pair)
+              regular_attrs[key] = value
+            end
+          end
+          regular_attrs
+        end
+
+        # `model_field?` provides the equivalent of strong-param filtering here.
+        def build_model_instance(model_name, attrs)
+          model_class = model_name.to_s.camelize.constantize
+          attrs_hash = attrs.respond_to?(:to_unsafe_h) ? attrs.to_unsafe_h : attrs.to_h
+          model_attrs = attrs_hash.each_with_object({}) do |(field, value), hash|
+            hash[field.to_sym] = value if model_field?(model_class, field.to_s)
+          end
+          @model_instances[model_name] = model_class.new(**model_attrs)
+        end
+
+        # A field belongs to the model if the model class declares it via
+        # `attribute_names` (ActiveRecord) or has an assignment method
+        # (ActiveModel attr_accessor, etc.).
+        def model_field?(model_class, field_name)
+          (model_class.respond_to?(:attribute_names) && model_class.attribute_names.include?(field_name)) ||
+            model_class.method_defined?("#{field_name}=")
+        end
+      end
+
+      class << self
+        def included(base)
+          base.include(ActiveModel::Model)
+          base.prepend(InstanceMethods)
+          define_class_macros(base)
+        end
+
+        private
+
+        def define_class_macros(base)
+          base.instance_variable_set(:@declared_models, [])
+          base.instance_variable_set(:@flatten_errors, false)
+
+          base.define_singleton_method(:flatten_errors) { @flatten_errors = true }
+          base.define_singleton_method(:flatten_errors?) { @flatten_errors }
+
+          # Declares one or more models managed by this form.  Each symbol must be
+          # the underscored model name (e.g. `model :payment`, `model :school_year`).
+          # Only declared models are processed from params.  Declared models are always instantiated
+          # (with blank attributes) even when their params are absent.
+          base.define_singleton_method(:model) do |*model_names|
+            model_names.each { |n| @declared_models << n.to_sym }
+          end
+
+          base.define_singleton_method(:declared_models) { @declared_models }
+
+          base.define_singleton_method(:check) do |*arguments|
+            instance = NuecaRailsInterfaces::Util.process_class_arguments(self, *arguments)
+            instance.valid?
+            instance
+          end
+        end
+      end
+
+      # 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
+      # first in the MRO, falling back to this default when no override exists.
+      def attributes
+        result = {}
+        result.merge!(@model_instances)
+        result.merge!(@regular_attributes.transform_keys(&:to_sym))
+        result.with_indifferent_access
+      end
+    end
+  end
+end

data/lib/nueca_rails_interfaces/version.rb

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

data/lib/nueca_rails_interfaces.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-raise 'Rails not found' unless defined?(Rails)
+raise 'Rails not found' unless defined?(Rails) # rubocop:disable Style/ImplicitRuntimeError
 
 require 'to_bool'
 

data/nueca_rails_interfaces.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .gitlab-ci.yml appveyor Gemfile])
+        f.start_with?('bin/', 'test/', 'spec/', 'features/', '.git', '.gitlab-ci.yml', 'appveyor', 'Gemfile')
     end
   end
   spec.bindir = 'exe'

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nueca_rails_interfaces
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  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,7 +65,13 @@ 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
 - lib/nueca_rails_interfaces/version.rb
 - nueca_rails_interfaces.gemspec
@@ -72,6 +80,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -86,7 +95,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Interfaces for known object entities in Rails Development at Nueca.
 test_files: []