dynamoid 3.5.0 → 3.6.0

data/lib/dynamoid/dumping.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module Dumping
     def self.dump_attributes(attributes, attributes_options)
       {}.tap do |h|
@@ -35,6 +36,7 @@ module Dynamoid
                      when :serialized then SerializedDumper
                      when :raw        then RawDumper
                      when :boolean    then BooleanDumper
+                     when :binary     then BinaryDumper
                      when Class       then CustomTypeDumper
                      end
 
@@ -287,6 +289,13 @@ module Dynamoid
       end
     end
 
+    # string -> string
+    class BinaryDumper < Base
+      def process(value)
+        Base64.strict_encode64(value)
+      end
+    end
+
     # any object -> string
     class CustomTypeDumper < Base
       def process(value)

data/lib/dynamoid/dynamodb_time_zone.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module DynamodbTimeZone
     def self.in_time_zone(value)
       case Dynamoid::Config.dynamodb_timezone

data/lib/dynamoid/fields.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # All fields on a Dynamoid::Document must be explicitly defined -- if you have fields in the database that are not
   # specified with field, then they will be ignored.
   module Fields
     extend ActiveSupport::Concern
 
+    # @private
     # Types allowed in indexes:
     PERMITTED_KEY_TYPES = %i[
       number
@@ -33,18 +34,101 @@ module Dynamoid #:nodoc:
     module ClassMethods
       # Specify a field for a document.
       #
-      # Its type determines how it is coerced when read in and out of the datastore.
-      # You can specify :integer, :number, :set, :array, :datetime, :date and :serialized,
+      #   class User
+      #     include Dynamoid::Document
+      #
+      #     field :last_name
+      #     field :age, :integer
+      #     field :last_sign_in, :datetime
+      #   end
+      #
+      # Its type determines how it is coerced when read in and out of the
+      # datastore. You can specify +string+, +integer+, +number+, +set+, +array+,
+      # +map+, +datetime+, +date+, +serialized+, +raw+, +boolean+ and +binary+
       # or specify a class that defines a serialization strategy.
       #
+      # By default field type is +string+.
+      #
+      # Set can store elements of the same type only (it's a limitation of
+      # DynamoDB itself). If a set should store elements only some particular
+      # type +of+ option should be specified:
+      #
+      #   field :hobbies, :set, of: :string
+      #
+      # Only +string+, +integer+, +number+, +date+, +datetime+ and +serialized+
+      # element types are supported.
+      #
+      # Element type can have own options - they should be specified in the
+      # form of +Hash+:
+      #
+      #   field :hobbies, :set, of: { serialized: { serializer: JSON } }
+      #
+      # Array can contain element of different types but if supports the same
+      # +of+ option to convert all the provided elements to the declared type.
+      #
+      #   field :rates, :array, of: :number
+      #
+      # By default +date+ and +datetime+ fields are stored as integer values.
+      # The format can be changed to string with option +store_as_string+:
+      #
+      #   field :published_on, :datetime, store_as_string: true
+      #
+      # Boolean field by default is stored as a string +t+ or +f+. But DynamoDB
+      # supports boolean type natively. In order to switch to the native
+      # boolean type an option +store_as_native_boolean+ should be specified:
+      #
+      #   field :active, :boolean, store_as_native_boolean: true
+      #
+      # If you specify the +serialized+ type a value will be serialized to
+      # string in Yaml format by default. Custom way to serialize value to
+      # string can be specified with +serializer+ option. Custom serializer
+      # should have +dump+ and +load+ methods.
+      #
       # If you specify a class for field type, Dynamoid will serialize using
-      # `dynamoid_dump` or `dump` methods, and load using `dynamoid_load` or `load` methods.
+      # +dynamoid_dump+ method and load using +dynamoid_load+ method.
+      #
+      # Default field type is +string+.
+      #
+      # A field can have a default value. It's assigned at initializing a model
+      # if no value is specified:
+      #
+      #   field :age, :integer, default: 1
+      #
+      # If a defautl value should be recalculated every time it can be
+      # specified as a callable object (it should implement a +call+ method
+      # e.g. +Proc+ object):
+      #
+      #   field :date_of_birth, :date, default: -> { Date.today }
+      #
+      # For every field Dynamoid creates several methods:
+      #
+      # * getter
+      # * setter
+      # * predicate +<name>?+ to check whether a value set
+      # * +<name>_before_type_cast?+ to get an original field value before it was type casted
+      #
+      # It works in the following way:
+      #
+      #   class User
+      #     include Dynamoid::Document
+      #
+      #     field :age, :integer
+      #   end
+      #
+      #   user = User.new
+      #   user.age # => nil
+      #   user.age? # => false
+      #
+      #   user.age = 20
+      #   user.age? # => true
       #
-      # Default field type is :string.
+      #   user.age = '21'
+      #   user.age # => 21 - integer
+      #   user.age_before_type_cast # => '21' - string
       #
-      # @param [Symbol] name the name of the field
-      # @param [Symbol] type the type of the field (refer to method description for details)
-      # @param [Hash] options any additional options for the field
+      # @param name [Symbol] name of the field
+      # @param type [Symbol] type of the field (optional)
+      # @param options [Hash] any additional options for the field type (optional)
       #
       # @since 0.2.0
       def field(name, type = :string, options = {})
@@ -79,11 +163,69 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # Declare a table range key.
+      #
+      #   class User
+      #     include Dynamoid::Document
+      #
+      #     range :last_name
+      #   end
+      #
+      # By default a range key is a string. In order to use any other type it
+      # should be specified as a second argument:
+      #
+      #   range :age, :integer
+      #
+      # Type options can be specified as well:
+      #
+      #   range :date_of_birth, :date, store_as_string: true
+      #
+      # @param name [Symbol] a range key attribute name
+      # @param type [Symbol] a range key type (optional)
+      # @param options [Symbol] type options (optional)
       def range(name, type = :string, options = {})
         field(name, type, options)
         self.range_key = name
       end
 
+      # Set table level properties.
+      #
+      # There are some sensible defaults:
+      #
+      # * table name is based on a model class e.g. +users+ for +User+ class
+      # * hash key name - +id+ by default
+      # * hash key type - +string+ by default
+      # * generating timestamp fields +created_at+ and +updated_at+
+      # * billing mode and read/write capacity units
+      #
+      # The +table+ method can be used to override the defaults:
+      #
+      #   class User
+      #     include Dynamoid::Document
+      #
+      #     table name: :customers, key: :uuid
+      #   end
+      #
+      # The hash key field is declared by default and a type is a string. If
+      # another type is needed the field should be declared explicitly:
+      #
+      #   class User
+      #     include Dynamoid::Document
+      #
+      #     field :id, :integer
+      #   end
+      #
+      # @param options [Hash] options to override default table settings
+      # @option options [Symbol] :name name of a table
+      # @option options [Symbol] :key name of a hash key attribute
+      # @option options [Symbol] :inheritance_field name of an attribute used for STI
+      # @option options [Symbol] :capacity_mode table billing mode - either +provisioned+ or +on_demand+
+      # @option options [Integer] :write_capacity table write capacity units
+      # @option options [Integer] :read_capacity table read capacity units
+      # @option options [true|false] :timestamps whether generate +created_at+ and +updated_at+ fields or not
+      # @option options [Hash] :expires set up a table TTL and should have following structure +{ field: <attriubute name>, after: <seconds> }+
+      #
+      # @since 0.4.0
       def table(options)
         # a default 'id' column is created when Dynamoid::Document is included
         unless attributes.key? hash_key
@@ -104,6 +246,12 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # Remove a field declaration
+      #
+      # Removes a field from the list of fields and removes all te generated
+      # for a field methods.
+      #
+      # @param field [Symbol] a field name
       def remove_field(field)
         field = field.to_sym
         attributes.delete(field) || raise('No such field')
@@ -120,6 +268,7 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # @private
       def timestamps_enabled?
         options[:timestamps] || (options[:timestamps].nil? && Dynamoid::Config.timestamps)
       end
@@ -135,7 +284,7 @@ module Dynamoid #:nodoc:
       end
 
       def warn_about_method_overriding(method_name, field_name)
-        if self.instance_methods.include?(method_name.to_sym)
+        if instance_methods.include?(method_name.to_sym)
           Dynamoid.logger.warn("Method #{method_name} generated for the field #{field_name} overrides already existing method")
         end
       end
@@ -145,10 +294,16 @@ module Dynamoid #:nodoc:
     attr_accessor :attributes
     alias raw_attributes attributes
 
-    # Write an attribute on the object. Also marks the previous value as dirty.
+    # Write an attribute on the object.
+    #
+    #   user.age = 20
+    #   user.write_attribute(:age, 21)
+    #   user.age # => 21
     #
-    # @param [Symbol] name the name of the field
-    # @param [Object] value the value to assign to that field
+    # Also marks the previous value as dirty.
+    #
+    # @param name [Symbol] the name of the field
+    # @param value [Object] the value to assign to that field
     #
     # @since 0.2.0
     def write_attribute(name, value)
@@ -169,22 +324,40 @@ module Dynamoid #:nodoc:
 
     # Read an attribute from an object.
     #
-    # @param [Symbol] name the name of the field
+    #   user.age = 20
+    #   user.read_attribute(:age) # => 20
     #
+    # @param name [Symbol] the name of the field
+    # @return attribute value
     # @since 0.2.0
     def read_attribute(name)
       attributes[name.to_sym]
     end
     alias [] read_attribute
 
-    # Returns a hash of attributes before typecasting
+    # Return attributes values before type casting.
+    #
+    #   user = User.new
+    #   user.age = '21'
+    #   user.age # => 21
+    #
+    #   user.attributes_before_type_cast # => { age: '21' }
+    #
+    # @return [Hash] original attribute values
     def attributes_before_type_cast
       @attributes_before_type_cast
     end
 
-    # Returns the value of the attribute identified by name before typecasting
+    # Return the value of the attribute identified by name before type casting.
+    #
+    #   user = User.new
+    #   user.age = '21'
+    #   user.age # => 21
+    #
+    #   user.read_attribute_before_type_cast(:age) # => '21'
     #
-    # @param [Symbol] attribute name
+    # @param name [Symbol] attribute name
+    # @return original attribute value
     def read_attribute_before_type_cast(name)
       return nil unless name.respond_to?(:to_sym)
 

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
@@ -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')
@@ -245,7 +280,8 @@ module Dynamoid
         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/