dynamoid 3.3.0 → 3.7.0

data/lib/dynamoid/fields/declare.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  module Fields
+    # @private
+    class Declare
+      def initialize(source, name, type, options)
+        @source = source
+        @name = name.to_sym
+        @type = type
+        @options = options
+      end
+
+      def call
+        # Register new field metadata
+        @source.attributes = @source.attributes.merge(
+          @name => { type: @type }.merge(@options)
+        )
+
+        # Should be called before `define_attribute_methods` method because it
+        # defines an attribute getter itself
+        warn_about_method_overriding
+
+        # Dirty API
+        @source.define_attribute_method(@name)
+
+        # Generate getters and setters as well as other helper methods
+        generate_instance_methods
+
+        # If alias name specified - generate the same instance methods
+        if @options[:alias]
+          generate_instance_methods_for_alias
+        end
+      end
+
+      private
+
+      def warn_about_method_overriding
+        warn_if_method_exists(@name)
+        warn_if_method_exists("#{@name}=")
+        warn_if_method_exists("#{@name}?")
+        warn_if_method_exists("#{@name}_before_type_cast?")
+      end
+
+      def generate_instance_methods
+        # only local variable is visible in `module_eval` block
+        name = @name
+
+        @source.generated_methods.module_eval do
+          define_method(name) { read_attribute(name) }
+          define_method("#{name}?") do
+            value = read_attribute(name)
+            case value
+            when true        then true
+            when false, nil  then false
+            else
+              !value.nil?
+            end
+          end
+          define_method("#{name}=") { |value| write_attribute(name, value) }
+          define_method("#{name}_before_type_cast") { read_attribute_before_type_cast(name) }
+        end
+      end
+
+      def generate_instance_methods_for_alias
+        # only local variable is visible in `module_eval` block
+        name = @name
+
+        alias_name = @options[:alias].to_sym
+
+        @source.generated_methods.module_eval do
+          alias_method alias_name, name
+          alias_method "#{alias_name}=", "#{name}="
+          alias_method "#{alias_name}?", "#{name}?"
+          alias_method "#{alias_name}_before_type_cast", "#{name}_before_type_cast"
+        end
+      end
+
+      def warn_if_method_exists(method)
+        if @source.instance_methods.include?(method.to_sym)
+          Dynamoid.logger.warn("Method #{method} generated for the field #{@name} overrides already existing method")
+        end
+      end
+    end
+  end
+end

data/lib/dynamoid/finders.rb

@@ -6,6 +6,7 @@ module Dynamoid
   module Finders
     extend ActiveSupport::Concern
 
+    # @private
     RANGE_MAP = {
       'gt'            => :range_greater_than,
       'lt'            => :range_less_than,
@@ -19,9 +20,25 @@ module Dynamoid
     module ClassMethods
       # Find one or many objects, specified by one id or an array of ids.
       #
-      # @param [Array/String] *id an array of ids or one single id
-      # @param [Hash] options
+      # By default it raises +RecordNotFound+ exception if at least one model
+      # isn't found. This behavior can be changed with +raise_error+ option. If
+      # specified +raise_error: false+ option then +find+ will not raise the
+      # exception.
       #
+      # When a document schema includes range key it always should be specified
+      # in +find+ method call. In case it's missing +MissingRangeKey+ exception
+      # will be raised.
+      #
+      # Please note that +find+ doesn't preserve order of models in result when
+      # passes multiple ids.
+      #
+      # Supported following options:
+      # * +consistent_read+
+      # * +range_key+
+      # * +raise_error+
+      #
+      # @param ids [String|Array] hash key or an array of hash keys
+      # @param options [Hash]
       # @return [Dynamoid::Document] one object or an array of objects, depending on whether the input was an array or not
       #
       # @example Find by partition key
@@ -45,36 +62,45 @@ module Dynamoid
       # @since 0.2.0
       def find(*ids, **options)
         if ids.size == 1 && !ids[0].is_a?(Array)
-          _find_by_id(ids[0], options.merge(raise_error: true))
+          _find_by_id(ids[0], options.reverse_merge(raise_error: true))
         else
-          _find_all(ids.flatten(1), options.merge(raise_error: true))
+          _find_all(ids.flatten(1), options.reverse_merge(raise_error: true))
         end
       end
 
-      # Return objects found by the given array of ids, either hash keys, or hash/range key combinations using BatchGetItem.
+      # Find several models at once.
+      #
+      # Returns objects found by the given array of ids, either hash keys, or
+      # hash/range key combinations using +BatchGetItem+.
+      #
       # Returns empty array if no results found.
       #
-      # Uses backoff specified by `Dynamoid::Config.backoff` config option
+      # Uses backoff specified by +Dynamoid::Config.backoff+ config option.
       #
-      # @param [Array<ID>] ids
-      # @param [Hash] options: Passed to the underlying query.
+      # @param ids [Array] array of primary keys
+      # @param options [Hash]
+      # @option options [true|false] :consistent_read
+      # @option options [true|false] :raise_error
       #
       # @example
-      #   find all the user with hash key
+      #   # Find all the user with hash key
       #   User.find_all(['1', '2', '3'])
       #
-      #   find all the tweets using hash key and range key with consistent read
-      #   Tweet.find_all([['1', 'red'], ['1', 'green']], :consistent_read => true)
+      #   # Find all the tweets using hash key and range key with consistent read
+      #   Tweet.find_all([['1', 'red'], ['1', 'green']], consistent_read: true)
       def find_all(ids, options = {})
         ActiveSupport::Deprecation.warn('[Dynamoid] .find_all is deprecated! Call .find instead of')
 
         _find_all(ids, options)
       end
 
-      # Find one object directly by id.
-      #
-      # @param [String] id the id of the object to find
+      # Find one object directly by primary key.
       #
+      # @param id [String] the id of the object to find
+      # @param options [Hash]
+      # @option options [true|false] :consistent_read
+      # @option options [true|false] :raise_error
+      # @option options [Scalar value] :range_key
       # @return [Dynamoid::Document] the found object, or nil if nothing was found
       #
       # @example Find by partition key
@@ -90,7 +116,10 @@ module Dynamoid
         _find_by_id(id, options)
       end
 
+      # @private
       def _find_all(ids, options = {})
+        raise Errors::MissingRangeKey if range_key && ids.any? { |pk, sk| sk.nil? }
+
         if range_key
           ids = ids.map do |pk, sk|
             sk_casted = TypeCasting.cast_field(sk, attributes[range_key])
@@ -131,7 +160,10 @@ module Dynamoid
         end
       end
 
+      # @private
       def _find_by_id(id, options = {})
+        raise Errors::MissingRangeKey if range_key && options[:range_key].nil?
+
         if range_key
           key = options[:range_key]
           key_casted = TypeCasting.cast_field(key, attributes[range_key])
@@ -149,10 +181,10 @@ module Dynamoid
         end
       end
 
-      # Find one object directly by hash and range keys
+      # Find one object directly by hash and range keys.
       #
-      # @param [String] hash_key of the object to find
-      # @param [String/Number] range_key of the object to find
+      # @param hash_key [Scalar value] hash key of the object to find
+      # @param range_key [Scalar value] range key of the object to find
       #
       def find_by_composite_key(hash_key, range_key, options = {})
         ActiveSupport::Deprecation.warn('[Dynamoid] .find_by_composite_key is deprecated! Call .find instead of')
@@ -169,6 +201,7 @@ module Dynamoid
       #     range :level,                   :integer
       #     table :key => :chamber_type
       #   end
+      #
       #   ChamberType.find_all_by_composite_key('DustVault', range_greater_than: 1)
       #
       # @param [String] hash_key of the objects to find
@@ -183,7 +216,7 @@ module Dynamoid
       def find_all_by_composite_key(hash_key, options = {})
         ActiveSupport::Deprecation.warn('[Dynamoid] .find_all_composite_key is deprecated! Call .where instead of')
 
-        Dynamoid.adapter.query(table_name, options.merge(hash_value: hash_key)).flat_map{ |i| i }.collect do |item|
+        Dynamoid.adapter.query(table_name, options.merge(hash_value: hash_key)).flat_map { |i| i }.collect do |item|
           from_database(item)
         end
       end
@@ -193,20 +226,22 @@ module Dynamoid
       # @example
       #   class User
       #     include Dynamoid::Document
-      #     field :email,          :string
-      #     field :age,            :integer
-      #     field :gender,         :string
-      #     field :rank            :number
+      #
       #     table :key => :email
-      #     global_secondary_index :hash_key => :age, :range_key => :rank
+      #     global_secondary_index hash_key: :age, range_key: :rank
+      #
+      #     field :email,  :string
+      #     field :age,    :integer
+      #     field :gender, :string
+      #     field :rank    :number
       #   end
+      #
       #   # NOTE: the first param and the second param are both hashes,
       #   #       so curly braces must be used on first hash param if sending both params
-      #   User.find_all_by_secondary_index({:age => 5}, :range => {"rank.lte" => 10})
+      #   User.find_all_by_secondary_index({ age: 5 }, range: { "rank.lte": 10 })
       #
-      # @param [Hash] eg: {:age => 5}
-      # @param [Hash] eg: {"rank.lte" => 10}
-      # @param [Hash] options - query filter, projected keys, scan_index_forward etc
+      # @param hash [Hash] conditions for the hash key e.g. +{ age: 5 }+
+      # @param options [Hash] conditions on range key e.g. +{ "rank.lte": 10 }, query filter, projected keys, scan_index_forward etc.
       # @return [Array] an array of all matching items
       def find_all_by_secondary_index(hash, options = {})
         ActiveSupport::Deprecation.warn('[Dynamoid] .find_all_by_secondary_index is deprecated! Call .where instead of')
@@ -240,12 +275,13 @@ module Dynamoid
           opts[range_op_mapped] = range_key_value
         end
         dynamo_options = opts.merge(options.reject { |key, _| key == :range })
-        Dynamoid.adapter.query(table_name, dynamo_options).flat_map{ |i| i }.map do |item|
+        Dynamoid.adapter.query(table_name, dynamo_options).flat_map { |i| i }.map do |item|
           from_database(item)
         end
       end
 
-      # Find using exciting method_missing finders attributes. Uses criteria chains under the hood to accomplish this neatness.
+      # Find using exciting method_missing finders attributes. Uses criteria
+      # chains under the hood to accomplish this neatness.
       #
       # @example find a user by a first name
       #   User.find_by_first_name('Josh')
@@ -253,8 +289,9 @@ module Dynamoid
       # @example find all users by first and last name
       #   User.find_all_by_first_name_and_last_name('Josh', 'Symonds')
       #
-      # @return [Dynamoid::Document/Array] the found object, or an array of found objects if all was somewhere in the method
+      # @return [Dynamoid::Document|Array] the found object, or an array of found objects if all was somewhere in the method
       #
+      # @private
       # @since 0.2.0
       def method_missing(method, *args)
         if method =~ /find/
@@ -267,9 +304,9 @@ module Dynamoid
           chain = chain.where({}.tap { |h| attributes.each_with_index { |attr, index| h[attr.to_sym] = args[index] } })
 
           if finder =~ /all/
-            return chain.all
+            chain.all
           else
-            return chain.first
+            chain.first
           end
         else
           super

data/lib/dynamoid/identity_map.rb

@@ -13,6 +13,7 @@ module Dynamoid
         @identity_map ||= {}
       end
 
+      # @private
       def from_database(attrs = {})
         return super if identity_map_off?
 
@@ -29,6 +30,7 @@ module Dynamoid
         document
       end
 
+      # @private
       def find_by_id(id, options = {})
         return super if identity_map_off?
 
@@ -41,6 +43,7 @@ module Dynamoid
         identity_map[key] || super
       end
 
+      # @private
       def identity_map_key(attrs)
         key = attrs[hash_key].to_s
         key += "::#{attrs[range_key]}" if range_key
@@ -60,6 +63,7 @@ module Dynamoid
       self.class.identity_map
     end
 
+    # @private
     def save(*args)
       return super if self.class.identity_map_off?
 
@@ -69,6 +73,7 @@ module Dynamoid
       result
     end
 
+    # @private
     def delete
       return super if self.class.identity_map_off?
 
@@ -76,6 +81,7 @@ module Dynamoid
       super
     end
 
+    # @private
     def identity_map_key
       key = hash_key.to_s
       key += "::#{range_value}" if self.class.range_key

data/lib/dynamoid/indexes.rb

@@ -15,19 +15,43 @@ module Dynamoid
       # Defines a Global Secondary index on a table. Keys can be specified as
       # hash-only, or hash & range.
       #
-      # @param [Hash] options options to pass for this table
-      # @option options [Symbol] :name the name for the index; this still gets
-      #         namespaced.  If not specified, will use a default name.
-      # @option options [Symbol] :hash_key the index hash key column.
-      # @option options [Symbol] :range_key the index range key column (if
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     field :category
+      #
+      #     global_secondary_indexes hash_key: :category
+      #   end
+      #
+      # The full example with all the options being specified:
+      #
+      #   global_secondary_indexes hash_key: :category,
+      #                            range_key: :created_at,
+      #                            name: 'posts_category_created_at_index',
+      #                            projected_attributes: :all,
+      #                            read_capacity: 100,
+      #                            write_capacity: 20
+      #
+      # Global secondary index should be declared after fields for mentioned
+      # hash key and optional range key are declared (with method +field+)
+      #
+      # The only mandatory option is +hash_key+. Raises
+      # +Dynamoid::Errors::InvalidIndex+ exception if passed incorrect
+      # options.
+      #
+      # @param [Hash] options the options to pass for this table
+      # @option options [Symbol] name the name for the index; this still gets
+      #         namespaced. If not specified, will use a default name.
+      # @option options [Symbol] hash_key the index hash key column.
+      # @option options [Symbol] range_key the index range key column (if
       #         applicable).
-      # @option options [Symbol, Array<Symbol>] :projected_attributes table
-      #         attributes to project for this index. Can be :keys_only, :all
+      # @option options [Symbol, Array<Symbol>] projected_attributes table
+      #         attributes to project for this index. Can be +:keys_only+, +:all+
       #         or an array of included fields. If not specified, defaults to
-      #         :keys_only.
-      # @option options [Integer] :read_capacity set the read capacity for the
+      #         +:keys_only+.
+      # @option options [Integer] read_capacity set the read capacity for the
       #         index; does not work on existing indexes.
-      # @option options [Integer] :write_capacity set the write capacity for
+      # @option options [Integer] write_capacity set the write capacity for
       #         the index; does not work on existing indexes.
       def global_secondary_index(options = {})
         unless options.present?
@@ -55,14 +79,38 @@ module Dynamoid
       # Defines a local secondary index on a table. Will use the same primary
       # hash key as the table.
       #
+      #   class Comment
+      #     include Dynamoid::Document
+      #
+      #     table hash_key: :post_id
+      #     range :created_at, :datetime
+      #     field :author_id
+      #
+      #     local_secondary_indexes hash_key: :author_id
+      #   end
+      #
+      # The full example with all the options being specified:
+      #
+      #   local_secondary_indexes range_key: :created_at,
+      #                           name: 'posts_created_at_index',
+      #                           projected_attributes: :all
+      #
+      # Local secondary index should be declared after fields for mentioned
+      # hash key and optional range key are declared (with method +field+) as
+      # well as after +table+ method call.
+      #
+      # The only mandatory option is +range_key+. Raises
+      # +Dynamoid::Errors::InvalidIndex+ exception if passed incorrect
+      # options.
+      #
       # @param [Hash] options options to pass for this index.
-      # @option options [Symbol] :name the name for the index; this still gets
+      # @option options [Symbol] name the name for the index; this still gets
       #         namespaced. If not specified, a name is automatically generated.
-      # @option options [Symbol] :range_key the range key column for the index.
-      # @option options [Symbol, Array<Symbol>] :projected_attributes table
-      #         attributes to project for this index. Can be :keys_only, :all
+      # @option options [Symbol] range_key the range key column for the index.
+      # @option options [Symbol, Array<Symbol>] projected_attributes table
+      #         attributes to project for this index. Can be +:keys_only+, +:all+
       #         or an array of included fields. If not specified, defaults to
-      #         :keys_only.
+      #         +:keys_only+.
       def local_secondary_index(options = {})
         unless options.present?
           raise Dynamoid::Errors::InvalidIndex, 'empty index definition'
@@ -94,11 +142,28 @@ module Dynamoid
         self
       end
 
+      # Returns an index by its hash key and optional range key.
+      #
+      # It works only for indexes without explicit name declared.
+      #
+      # @param hash [scalar] the hash key used to declare an index
+      # @param range [scalar] the range key used to declare an index (optional)
+      # @return [Dynamoid::Indexes::Index, nil] index object or nil if it isn't found
       def find_index(hash, range = nil)
         index = indexes[index_key(hash, range)]
         index
       end
 
+      # Returns an index by its name
+      #
+      # @param name [string, symbol] the name of the index to lookup
+      # @return [Dynamoid::Indexes::Index, nil] index object or nil if it isn't found
+      def find_index_by_name(name)
+        string_name = name.to_s
+        indexes.each_value.detect{ |i| i.name.to_s == string_name }
+      end
+
+
       # Returns true iff the provided hash[,range] key combo is a local
       # secondary index.
       #
@@ -150,6 +215,10 @@ module Dynamoid
         local_secondary_indexes.merge(global_secondary_indexes)
       end
 
+      # Returns an array of hash keys for all the declared Glocal Secondary
+      # Indexes.
+      #
+      # @return [Array[String]] array of hash keys
       def indexed_hash_keys
         global_secondary_indexes.map do |_name, index|
           index.hash_key.to_s
@@ -165,8 +234,8 @@ module Dynamoid
       DEFAULT_PROJECTION_TYPE = :keys_only
 
       attr_accessor :name, :dynamoid_class, :type, :hash_key, :range_key,
-        :hash_key_schema, :range_key_schema, :projected_attributes,
-        :read_capacity, :write_capacity
+                    :hash_key_schema, :range_key_schema, :projected_attributes,
+                    :read_capacity, :write_capacity
 
       validate do
         validate_index_type