sequel 5.100.0 → 5.101.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e8ed38ad86fbbbd643eb1a2579b799025ff77400d250abe807f41e19a533d9e
-  data.tar.gz: 2a4e5b271a96b87d1b2e78f073c4d9a3e91d5147297e555a23c75ac0537b918d
+  metadata.gz: 9de2d20e1483de5f15a285b695d5eab98601c26f1e711e378de1a03331f197a1
+  data.tar.gz: 4d7df1811d7242dad22f6c9968fb43feecb5a86fd814aa2ba7434bdb44369cb8
 SHA512:
-  metadata.gz: f1c4b4be8a1b1ce7537799d882e0cde6bd3967a414c8beb60c3ccfff08eb0ed2a84125bca68754510d4c6b80743a49c5c9ca784b1004b3d074e9674760c2e06c
-  data.tar.gz: 4e9386540fa22fd976b2ea915d0536225b0d5d231cd3d820e916c7dcc636bcda5a4fabda8604d3848aa183443d0c84d1f951b5ba0bef94cd79cf69526866c014
+  metadata.gz: a9aa7a3bd15f4f35457aace92b68b4734d367273996dc605d80adbe87bca1c945fc484571cad90149e69807980eea2f8b2a6a6fea85a4a0670c10a082a056a03
+  data.tar.gz: ca5c1eb34d71d16660a0b5eb2b9e5b4c784f06d6e4f89b036f00a62f31b57d564f071b8346bdcb9ebd9cced7bcfbe429e2c50bcda1b8b150d723b1e59105c474

data/lib/sequel/dataset/actions.rb

@@ -372,6 +372,15 @@ module Sequel
     #   DB[:table].import([:x, :y], DB[:table2].select(:a, :b))
     #   # INSERT INTO table (x, y) SELECT a, b FROM table2 
     #
+    # The return value of this method is undefined and should not be used,
+    # except in two cases:
+    #
+    # * When the <tt>return: :primary_key</tt> option is used.
+    # * On PostgreSQL, when the dataset uses RETURNING. In this case, if
+    #   a single value is returned per row, the return value is an array
+    #   of those values. If multiple values are returned per row, the
+    #   return value is an array of hashes.
+    #
     # Options:
     # :commit_every :: Open a new transaction for every given number of
     #                  records. For example, if you provide a value of 50,

data/lib/sequel/plugins/detect_unnecessary_association_options.rb

@@ -0,0 +1,164 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The detect_unnecessary_association_options plugin can detect unnecessary
+    # association options, and either warn or raise if they are detected.
+    # This allows you to find and remove the unnecessary options.
+    # Association options are considered unnecessary if they specify the same
+    # value as Sequel's defaults.
+    #
+    # To detect unnecessary association options, you should load the plugin
+    # into your model base class (e.g. Sequel::Model) before loading your model
+    # classes. Then, after all models have been loaded, you can call the
+    # detect_unnecessary_association_options on each to check for unnecessary
+    # association options. Additionally, if you are calling finalize_associations,
+    # it will automatically check for unnecessary association options.
+    #
+    # A typical usage would be to combine this with the subclasses plugin:
+    #
+    #   Sequel::Model.plugin :detect_unnecessary_association_options
+    #   Sequel::Model.plugin :subclasses
+    #   # load model classes
+    #
+    #   # implicitly check all subclasses when freezing descendants
+    #   Sequel::Model.freeze_descendants
+    #
+    #   # or, if not freezing all descendants
+    #   Sequel::Model.descendants.each(&:detect_unnecessary_association_options)
+    #
+    # By default, the plugin warns for every unnecessary association option.
+    # To raise an error instead, you can pass the <tt>action: :raise</tt> option when loading the
+    # plugin:
+    #
+    #   Sequel::Model.plugin :detect_unnecessary_association_options, action: :raise
+    #
+    # This plugin only detects the most common unnecessary association options, such as:
+    #
+    # * :class (all associations)
+    # * :key and :primary_key (associations without join tables)
+    # * :join_table, :left_key, :right_key, :left_primary_key, :right_primary_key (single join table associations)
+    # * :left_primary_key, :right_primary_key (*_through_many associations)
+    #
+    # Only association types supported by default or supported by a plugin that
+    # ships with Sequel are supported by this plugin. Other association types are
+    # ignored.
+    module DetectUnnecessaryAssociationOptions
+      def self.configure(model, opts={})
+        model.instance_variable_set(:@detect_unnecessary_association_options_action, opts[:action] || :warn)
+      end
+
+      # Raised if the plugin action is to raise and an unnecessary association option
+      # is detected.
+      class UnnecessaryAssociationOption < Sequel::Error
+      end
+
+      module ClassMethods
+        Plugins.inherited_instance_variables(self, :@detect_unnecessary_association_options_action => nil)
+
+        # Implicitly check for unnecessary association options when finalizing associations.
+        def finalize_associations
+          res = super
+          detect_unnecessary_association_options
+          res
+        end
+
+        # Check for unnecessary association options.
+        def detect_unnecessary_association_options
+          @association_reflections.each_value do |ref|
+            meth = "detect_unnecessary_association_options_#{ref[:type]}"
+            # Expected to call private methods.
+            # Ignore unrecognized association types.
+            # External association types can define the appropriate method to
+            # support their own unnecessary association option checks.
+            if respond_to?(meth, true)
+              # All recognized association types need same class check
+              _detect_unnecessary_association_options_class(ref)
+              send(meth, ref)
+            end
+          end
+
+          nil
+        end
+
+        private
+
+        # Action to take if an unnecessary association option is detected.
+        def unnecessary_association_options_detected(ref, key)
+          if @detect_unnecessary_association_options_action == :raise
+            raise UnnecessaryAssociationOption, "#{ref.inspect} :#{key} option unnecessary"
+          else
+            warn "#{ref.inspect} :#{key} option unnecessary"
+          end
+        end
+
+        # Detect unnecessary :class option.
+        def _detect_unnecessary_association_options_class(ref)
+          return unless ref[:orig_class]
+
+          h = {}
+          name = ref[:name]
+          late_binding_class_option(h, ref.returns_array? ? singularize(name) : name)
+
+          begin
+            default_association_class = constantize(h[:class_name])
+            actual_association_class = ref.associated_class
+          rescue NameError
+            # Do not warn. For the default association class to not be a valid
+            # constant is expected. For the actual association class to not be
+            # a valid constant is not expected and a bug in the association, but
+            # the job of this plugin is not to detect invalid options, only
+            # unnecessary options.
+          else
+            if default_association_class.equal?(actual_association_class)
+              unnecessary_association_options_detected(ref, "class")
+            end
+          end
+        end
+
+        # Detect other unnecessary options. An option is considered unnecessary
+        # if the key was submitted as an association option and the value for
+        # the option is the same as the given value.
+        def _detect_unnecessary_association_options_key_value(ref, key, value)
+          if ref[:orig_opts].has_key?(key) && ref[:orig_opts][key] == value
+            unnecessary_association_options_detected(ref, key)
+          end
+        end
+
+        # Same as _detect_unnecessary_association_options_key_value, but calls
+        # the default_* method on the association reflection to get the default value.
+        def _detect_unnecessary_association_options_key(ref, key)
+          _detect_unnecessary_association_options_key_value(ref, key, ref.send(:"default_#{key}"))
+        end
+
+        def detect_unnecessary_association_options_many_to_one(ref)
+          _detect_unnecessary_association_options_key(ref, :key)
+          _detect_unnecessary_association_options_key_value(ref, :primary_key, ref.associated_class.primary_key)
+        end
+        alias detect_unnecessary_association_options_pg_array_to_many detect_unnecessary_association_options_many_to_one
+
+        def detect_unnecessary_association_options_one_to_many(ref)
+          _detect_unnecessary_association_options_key(ref, :key)
+          _detect_unnecessary_association_options_key_value(ref, :primary_key, primary_key)
+        end
+        alias detect_unnecessary_association_options_one_to_one detect_unnecessary_association_options_one_to_many
+        alias detect_unnecessary_association_options_many_to_pg_array detect_unnecessary_association_options_one_to_many
+
+        def detect_unnecessary_association_options_many_to_many(ref)
+          [:join_table, :left_key, :right_key].each do |key|
+            _detect_unnecessary_association_options_key(ref, key)
+          end
+          _detect_unnecessary_association_options_key_value(ref, :left_primary_key, primary_key)
+          _detect_unnecessary_association_options_key_value(ref, :right_primary_key, ref.associated_class.primary_key)
+        end
+        alias detect_unnecessary_association_options_one_through_one detect_unnecessary_association_options_many_to_many
+
+        def detect_unnecessary_association_options_many_through_many(ref)
+          _detect_unnecessary_association_options_key_value(ref, :left_primary_key, primary_key)
+          _detect_unnecessary_association_options_key_value(ref, :right_primary_key, ref.associated_class.primary_key)
+        end
+        alias detect_unnecessary_association_options_one_through_many detect_unnecessary_association_options_many_through_many
+      end
+    end
+  end
+end

data/lib/sequel/version.rb

@@ -6,7 +6,7 @@ module Sequel
 
   # The minor version of Sequel.  Bumped for every non-patch level
   # release, generally around once a month.
-  MINOR = 100
+  MINOR = 101
 
   # The tiny version of Sequel.  Usually 0, only bumped for bugfix
   # releases that fix regressions from previous versions.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel
 version: !ruby/object:Gem::Version
-  version: 5.100.0
+  version: 5.101.0
 platform: ruby
 authors:
 - Jeremy Evans
@@ -344,6 +344,7 @@ files:
 - lib/sequel/plugins/defaults_setter.rb
 - lib/sequel/plugins/delay_add_association.rb
 - lib/sequel/plugins/deprecated_associations.rb
+- lib/sequel/plugins/detect_unnecessary_association_options.rb
 - lib/sequel/plugins/dirty.rb
 - lib/sequel/plugins/eager_each.rb
 - lib/sequel/plugins/eager_graph_eager.rb