dynamoid 3.4.0 → 3.7.1

data/lib/dynamoid/document.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+module Dynamoid
   # This is the base module for all domain objects that need to be persisted to
   # the database as documents.
   module Document
@@ -17,28 +17,19 @@ module Dynamoid #:nodoc:
     end
 
     module ClassMethods
-      # Set up table options, including naming it whatever you want, setting the id key, and manually overriding read and
-      # write capacity.
-      #
-      # @param [Hash] options options to pass for this table
-      # @option options [Symbol] :name the name for the table; this still gets namespaced
-      # @option options [Symbol] :id id column for the table
-      # @option options [Integer] :read_capacity set the read capacity for the table; does not work on existing tables
-      # @option options [Integer] :write_capacity set the write capacity for the table; does not work on existing tables
-      #
-      # @since 0.4.0
+      # @private
       def table(options = {})
         self.options = options
         super if defined? super
       end
 
       def attr_readonly(*read_only_attributes)
-        ActiveSupport::Deprecation.warn('[Dynamoid] .attr_readonly is deprecated! Call .find instead of')
         self.read_only_attributes.concat read_only_attributes.map(&:to_s)
       end
 
-      # Returns the read_capacity for this table.
+      # Returns the read capacity for this table.
       #
+      # @return [Integer] read capacity units
       # @since 0.4.0
       def read_capacity
         options[:read_capacity] || Dynamoid::Config.read_capacity
@@ -46,32 +37,53 @@ module Dynamoid #:nodoc:
 
       # Returns the write_capacity for this table.
       #
+      # @return [Integer] write capacity units
       # @since 0.4.0
       def write_capacity
         options[:write_capacity] || Dynamoid::Config.write_capacity
       end
 
-
       # Returns the billing (capacity) mode for this table.
-      # Could be either :provisioned or :on_demand
+      #
+      # Could be either +provisioned+ or +on_demand+.
+      #
+      # @return [Symbol]
       def capacity_mode
         options[:capacity_mode] || Dynamoid::Config.capacity_mode
       end
 
       # Returns the field name used to support STI for this table.
+      #
+      # Default field name is +type+ but it can be overrided in the +table+
+      # method call.
+      #
+      #   User.inheritance_field # => :type
       def inheritance_field
         options[:inheritance_field] || :type
       end
 
-      # Returns the id field for this class.
+      # Returns the hash key field name for this class.
+      #
+      # By default +id+ field is used. But it can be overriden in the +table+
+      # method call.
       #
+      #   User.hash_key # => :id
+      #
+      # @return [Symbol] a hash key name
       # @since 0.4.0
       def hash_key
         options[:key] || :id
       end
 
-      # Returns the number of items for this class.
+      # Return the count of items for this class.
+      #
+      # It returns aproximate value based on DynamoDB statistic. DynamoDB
+      # updates it periodicaly so the value can be no accurate.
       #
+      # It's a reletivly cheap operation and doesn't read all the items in a
+      # table. It makes just one HTTP request to DynamoDB.
+      #
+      # @return [Integer] items count in a table
       # @since 0.6.1
       def count
         Dynamoid.adapter.count(table_name)
@@ -79,35 +91,67 @@ module Dynamoid #:nodoc:
 
       # Initialize a new object.
       #
-      # @param [Hash] attrs Attributes with which to create the object.
+      #   User.build(name: 'A')
       #
-      # @return [Dynamoid::Document] the new document
+      # Initialize an object and pass it into a block to set other attributes.
+      #
+      #   User.build(name: 'A') do |u|
+      #     u.age = 21
+      #   end
+      #
+      # The only difference between +build+ and +new+ methods is that +build+
+      # supports STI (Single table inheritance) and looks at the inheritance
+      # field. So it can build a model of actual class. For instance:
+      #
+      #   class Employee
+      #     include Dynamoid::Document
+      #
+      #     field :type
+      #     field :name
+      #   end
       #
+      #   class Manager < Employee
+      #   end
+      #
+      #   Employee.build(name: 'Alice', type: 'Manager') # => #<Manager:0x00007f945756e3f0 ...>
+      #
+      # @param attrs [Hash] Attributes with which to create the document
+      # @param block [Proc] Block to process a document after initialization
+      # @return [Dynamoid::Document] the new document
       # @since 0.2.0
-      def build(attrs = {})
-        choose_right_class(attrs).new(attrs)
+      def build(attrs = {}, &block)
+        choose_right_class(attrs).new(attrs, &block)
       end
 
-      # Does this object exist?
+      # Does this model exist in a table?
+      #
+      #   User.exists?('713') # => true
       #
-      # Supports primary key in format that `find` call understands.
-      # Multiple keys and single compound primary key should be passed only as Array explicitily.
+      # If a range key is declared it should be specified in the following way:
       #
-      # Supports conditions in format that `where` call understands.
+      #   User.exists?([['713', 'range-key-value']]) # => true
       #
-      # @param [Mixed] id_or_conditions the id of the object or a hash with the options to filter from.
+      # It's possible to check existence of several models at once:
       #
-      # @return [Boolean] true/false
+      #   User.exists?(['713', '714', '715'])
       #
-      # @example With id
+      # Or in case when a range key is declared:
       #
-      #   Post.exist?(713)
-      #   Post.exist?([713, 210])
+      #   User.exists?(
+      #     [
+      #       ['713', 'range-key-value-1'],
+      #       ['714', 'range-key-value-2'],
+      #       ['715', 'range-key-value-3']
+      #     ]
+      #   )
       #
-      # @example With attributes conditions
+      # It's also possible to specify models not with primary key but with
+      # conditions on the attributes (in the +where+ method style):
       #
-      #   Post.exist?(version: 1, 'created_at.gt': Time.now - 1.day)
+      #   User.exists?(age: 20, 'created_at.gt': Time.now - 1.day)
       #
+      # @param id_or_conditions [String|Array[String]|Array[Array]|Hash] the primary id of the model, a list of primary ids or a hash with the options to filter from.
+      # @return [true|false]
       # @since 0.2.0
       def exists?(id_or_conditions = {})
         case id_or_conditions
@@ -122,10 +166,12 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # @private
       def deep_subclasses
         subclasses + subclasses.map(&:deep_subclasses).flatten
       end
 
+      # @private
       def choose_right_class(attrs)
         attrs[inheritance_field] ? attrs[inheritance_field].constantize : self
       end
@@ -133,12 +179,20 @@ module Dynamoid #:nodoc:
 
     # Initialize a new object.
     #
-    # @param [Hash] attrs Attributes with which to create the object.
+    #   User.new(name: 'A')
     #
+    # Initialize an object and pass it into a block to set other attributes.
+    #
+    #   User.new(name: 'A') do |u|
+    #     u.age = 21
+    #   end
+    #
+    # @param attrs [Hash] Attributes with which to create the document
+    # @param block [Proc] Block to process a document after initialization
     # @return [Dynamoid::Document] the new document
     #
     # @since 0.2.0
-    def initialize(attrs = {})
+    def initialize(attrs = {}, &block)
       run_callbacks :initialize do
         @new_record = true
         @attributes ||= {}
@@ -156,11 +210,19 @@ module Dynamoid #:nodoc:
         attrs_virtual = attrs.slice(*(attrs.keys - self.class.attributes.keys))
 
         load(attrs_with_defaults.merge(attrs_virtual))
+
+        if block
+          block.call(self)
+        end
       end
     end
 
-    # An object is equal to another object if their ids are equal.
+    # Check equality of two models.
     #
+    # A model is equal to another model only if their primary keys (hash key
+    # and optionaly range key) are equal.
+    #
+    # @return [true|false]
     # @since 0.2.0
     def ==(other)
       if self.class.identity_map_on?
@@ -172,36 +234,54 @@ module Dynamoid #:nodoc:
       end
     end
 
+    # Check equality of two models.
+    #
+    # Works exactly like +==+ does.
+    #
+    # @return [true|false]
     def eql?(other)
       self == other
     end
 
+    # Generate an Integer hash value for this model.
+    #
+    # Hash value is based on primary key. So models can be used safely as a
+    # +Hash+ keys.
+    #
+    # @return [Integer]
     def hash
       hash_key.hash ^ range_value.hash
     end
 
-    # Return an object's hash key, regardless of what it might be called to the object.
+    # Return a model's hash key value.
     #
     # @since 0.4.0
     def hash_key
-      send(self.class.hash_key)
+      self[self.class.hash_key.to_sym]
     end
 
-    # Assign an object's hash key, regardless of what it might be called to the object.
+    # Assign a model's hash key value, regardless of what it might be called to
+    # the object.
     #
     # @since 0.4.0
     def hash_key=(value)
-      send("#{self.class.hash_key}=", value)
+      self[self.class.hash_key.to_sym] = value
     end
 
+    # Return a model's range key value.
+    #
+    # Returns +nil+ if a range key isn't declared for a model.
     def range_value
-      if range_key = self.class.range_key
-        send(range_key)
+      if self.class.range_key
+        self[self.class.range_key.to_sym]
       end
     end
 
+    # Assign a model's range key value.
     def range_value=(value)
-      send("#{self.class.range_key}=", value)
+      if self.class.range_key
+        self[self.class.range_key.to_sym] = value
+      end
     end
 
     private
@@ -213,7 +293,7 @@ module Dynamoid #:nodoc:
     # Evaluates the default value given, this is used by undump
     # when determining the value of the default given for a field options.
     #
-    # @param [Object] :value the attribute's default value
+    # @param val [Object] the attribute's default value
     def evaluate_default_value(val)
       if val.respond_to?(:call)
         val.call
@@ -225,3 +305,5 @@ module Dynamoid #:nodoc:
     end
   end
 end
+
+ActiveSupport.run_load_hooks(:dynamoid, Dynamoid::Document)

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/errors.rb

@@ -75,5 +75,7 @@ module Dynamoid
     class InvalidQuery < Error; end
 
     class UnsupportedKeyType < Error; end
+
+    class UnknownAttribute < Error; end
   end
 end

data/lib/dynamoid/fields.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
-module Dynamoid #:nodoc:
+require 'dynamoid/fields/declare'
+
+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
       integer
       string
+      date
       datetime
       serialized
     ].freeze
@@ -33,51 +37,188 @@ 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
+      # data store. 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 of some particular
+      # type then +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+.
       #
-      # Default field type is :string.
+      # A field can have a default value. It's assigned at initializing a model
+      # if no value is specified:
       #
-      # @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
+      #   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
+      #
+      #   user.age = '21'
+      #   user.age # => 21 - integer
+      #   user.age_before_type_cast # => '21' - string
+      #
+      # There is also an option +alias+ which allows to use another name for a
+      # field:
+      #
+      #   class User
+      #     include Dynamoid::Document
+      #
+      #     field :firstName, :string, alias: :first_name
+      #   end
+      #
+      #   user = User.new(firstName: 'Michael')
+      #   user.firstName # Michael
+      #   user.first_name # Michael
+      #
+      # @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 = {})
-        named = name.to_s
         if type == :float
           Dynamoid.logger.warn("Field type :float, which you declared for '#{name}', is deprecated in favor of :number.")
           type = :number
         end
-        self.attributes = attributes.merge(name => { type: type }.merge(options))
 
-        define_attribute_method(name) # Dirty API
-
-        generated_methods.module_eval do
-          define_method(named) { read_attribute(named) }
-          define_method("#{named}?") do
-            value = read_attribute(named)
-            case value
-            when true        then true
-            when false, nil  then false
-            else
-              !value.nil?
-            end
-          end
-          define_method("#{named}=") { |value| write_attribute(named, value) }
-          define_method("#{named}_before_type_cast") { read_attribute_before_type_cast(named) }
-        end
+        Dynamoid::Fields::Declare.new(self, name, type, options).call
       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
@@ -98,6 +239,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')
@@ -114,12 +261,12 @@ module Dynamoid #:nodoc:
         end
       end
 
+      # @private
       def timestamps_enabled?
         options[:timestamps] || (options[:timestamps].nil? && Dynamoid::Config.timestamps)
       end
 
-      private
-
+      # @private
       def generated_methods
         @generated_methods ||= begin
           Module.new.tap do |mod|
@@ -133,15 +280,25 @@ 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)
       name = name.to_sym
 
+      unless attribute_is_present_on_model?(name)
+        raise Dynamoid::Errors::UnknownAttribute.new("Attribute #{name} is not part of the model")
+      end
+
       if association = @associations[name]
         association.reset
       end
@@ -157,22 +314,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.
     #
-    # @param [Symbol] attribute name
+    #   user = User.new
+    #   user.age = '21'
+    #   user.age # => 21
+    #
+    #   user.read_attribute_before_type_cast(:age) # => '21'
+    #
+    # @param name [Symbol] attribute name
+    # @return original attribute value
     def read_attribute_before_type_cast(name)
       return nil unless name.respond_to?(:to_sym)
 
@@ -192,7 +367,8 @@ module Dynamoid #:nodoc:
     #
     # @since 0.2.0
     def set_updated_at
-      if self.class.timestamps_enabled? && !updated_at_changed?
+      # @_touch_record=false means explicit disabling
+      if self.class.timestamps_enabled? && !updated_at_changed? && @_touch_record != false
         self.updated_at = DateTime.now.in_time_zone(Time.zone)
       end
     end
@@ -219,5 +395,10 @@ module Dynamoid #:nodoc:
         send("#{type}=", self.class.name)
       end
     end
+
+    def attribute_is_present_on_model?(attribute_name)
+      setter = "#{attribute_name}=".to_sym
+      respond_to?(setter)
+    end
   end
 end