aws-record 1.0.0.pre.1 → 1.0.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 84fe186e9a5995f6ca277aa4776a37dfaef73928
-  data.tar.gz: 267cf8b8556f23108e5cc3e660177af43ebe0c26
+  metadata.gz: f411d61078b7eeb8fbd7081d51c3f41b1c9116ca
+  data.tar.gz: 073b4953897897aba7298b5ba90e8050a015fcde
 SHA512:
-  metadata.gz: e69390465c8fe8f2eb45eaffeeef9d90a8ded9159a440170e3d5a3258e0679a230f4c6cc50930e2b6cd377f4a132a84389607569c1811238cd858f6a5fb9e830
-  data.tar.gz: b2ff7b50b0c2a652f21901d592ed6476fe97bd146cc95c89bdb0fccd34a2ffec3fe4233ea1e764fe72ff53bbf9af5d53e58a7cd4ac10e4717f2c45d9fe778778
+  metadata.gz: ba35bcbfadff82862f5170c428d213c23157307c07ef9325263d877596cb2c32e0a9b65ee150e7492538b67f422c90d3f8112b5d51def09508e55c974ae6944f
+  data.tar.gz: 9301a70e55fae642dd83c814720ab78543dae3ec12e1c806df096326009308dce7fbb2666a1a8610cd18c69418be9e70d93649b1d2780b42523fb9361c7e04a6

data/lib/aws-record.rb

@@ -1,15 +1,31 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 require 'aws-sdk-resources'
 
 module Aws
   autoload :Record, 'aws-record/record'
 
   module Record
-    autoload :Attribute,      'aws-record/record/attribute'
-    autoload :Attributes,     'aws-record/record/attributes'
-    autoload :Errors,         'aws-record/record/errors'
-    autoload :ItemOperations, 'aws-record/record/item_operations'
-    autoload :TableMigration, 'aws-record/record/table_migration'
-    autoload :VERSION,        'aws-record/record/version'
+    autoload :Attribute,        'aws-record/record/attribute'
+    autoload :Attributes,       'aws-record/record/attributes'
+    autoload :Errors,           'aws-record/record/errors'
+    autoload :ItemCollection,   'aws-record/record/item_collection'
+    autoload :ItemOperations,   'aws-record/record/item_operations'
+    autoload :Query,            'aws-record/record/query'
+    autoload :SecondaryIndexes, 'aws-record/record/secondary_indexes'
+    autoload :TableMigration,   'aws-record/record/table_migration'
+    autoload :VERSION,          'aws-record/record/version'
 
     module Attributes
       autoload :StringMarshaler,   'aws-record/record/attributes/string_marshaler'

data/lib/aws-record/record.rb

@@ -1,9 +1,33 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
+
+    # Usage of {Aws::Record} requires only that you include this module. This
+    # method will then pull in the other default modules.
+    #
+    # @example
+    #   class MyTable
+    #     include Aws::Record
+    #     # Attribute definitions go here...
+    #   end
     def self.included(sub_class)
-      sub_class.extend(RecordClassMethods)
-      sub_class.include(Attributes)
-      sub_class.include(ItemOperations)
+      sub_class.send(:extend, RecordClassMethods)
+      sub_class.send(:include, Attributes)
+      sub_class.send(:include, ItemOperations)
+      sub_class.send(:include, Query)
+      sub_class.send(:include, SecondaryIndexes)
     end
 
     private
@@ -12,6 +36,25 @@ module Aws
     end
 
     module RecordClassMethods
+
+      # Returns the Amazon DynamoDB table name for this model class.
+      #
+      # By default, this will simply be the name of the class. However, you can
+      # also define a custom table name at the class level to be anything that
+      # you want.
+      #
+      # @example
+      #   class MyTable
+      #     include Aws::Record
+      #   end
+      #   
+      #   class MyTableTest
+      #     include Aws::Record
+      #     set_table_name "test_MyTable"
+      #   end
+      #   
+      #   MyTable.table_name      # => "MyTable"
+      #   MyOtherTable.table_name # => "test_MyTable"
       def table_name
         if @table_name
           @table_name
@@ -20,10 +63,33 @@ module Aws
         end
       end
 
+      # Allows you to set a custom Amazon DynamoDB table name for this model
+      # class.
+      #
+      # @example
+      #   class MyTable
+      #     include Aws::Record
+      #     set_table_name "prod_MyTable"
+      #   end
+      #   
+      #   class MyTableTest
+      #     include Aws::Record
+      #     set_table_name "test_MyTable"
+      #   end
+      #   
+      #   MyTable.table_name      # => "prod_MyTable"
+      #   MyOtherTable.table_name # => "test_MyTable"
       def set_table_name(name)
         @table_name = name
       end
 
+      # Fetches the table's provisioned throughput from the associated Amazon
+      # DynamoDB table.
+      #
+      # @return [Hash] a hash containing the +:read_capacity_units+ and
+      #   +:write_capacity_units+ of your remote table.
+      # @raise [Aws::Record::Errors::TableDoesNotExist] if the table name does
+      #   not exist in DynamoDB.
       def provisioned_throughput
         begin
           resp = dynamodb_client.describe_table(table_name: @table_name)
@@ -37,6 +103,9 @@ module Aws
         end
       end
 
+      # Checks if the model's table name exists in Amazon DynamoDB.
+      #
+      # @return [Boolean] true if the table does exist, false if it does not.
       def table_exists?
         begin
           resp = dynamodb_client.describe_table(table_name: @table_name)
@@ -50,16 +119,50 @@ module Aws
         end
       end
 
+      # Configures the Amazon DynamoDB client used by this class and all
+      # instances of this class.
+      #
+      # Please note that this method is also called internally when you first
+      # attempt to perform an operation against the remote end, if you have not
+      # already configured a client. As such, please read and understand the
+      # documentation in the AWS SDK for Ruby V2 around
+      # {http://docs.aws.amazon.com/sdkforruby/api/index.html#Configuration configuration}
+      # to ensure you understand how default configuration behavior works. When
+      # in doubt, call this method to ensure your client is configured the way
+      # you want it to be configured.
+      #
+      # @param [Hash] opts the options you wish to use to create the client.
+      #  Note that if you include the option +:client+, all other options
+      #  will be ignored. See the documentation for other options in the
+      #  {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#initialize-instance_method AWS SDK for Ruby V2}.
+      # @option opts [Aws::DynamoDB::Client] :client allows you to pass in your
+      #  own pre-configured client.
       def configure_client(opts = {})
         provided_client = opts.delete(:client)
-        opts[:user_agent_suffix] = user_agent(opts.delete(:user_agent_suffix))
+        opts[:user_agent_suffix] = _user_agent(opts.delete(:user_agent_suffix))
         client = provided_client || Aws::DynamoDB::Client.new(opts)
         @dynamodb_client = client
       end
 
+      # Gets the
+      # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html Aws::DynamoDB::Client}
+      # instance that this model uses. When called for the first time, if
+      # {#configure_client} has not yet been called, will configure a new client
+      # for you with default parameters.
+      #
+      # @return [Aws::DynamoDB::Client] the Amazon DynamoDB client instance.
       def dynamodb_client
         @dynamodb_client ||= configure_client
       end
+
+      private
+      def _user_agent(custom)
+        if custom
+          custom
+        else
+          " aws-record/#{VERSION}"
+        end
+      end
     end
   end
 end

data/lib/aws-record/record/attribute.rb

@@ -1,9 +1,40 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     class Attribute
 
       attr_reader :name, :database_name, :dynamodb_type
 
+      # @param [Symbol] name Name of the attribute. It should be a name that is
+      #  safe to use as a method.
+      # @param [Hash] options
+      # @option options [Marshaler] :marshaler The marshaler for this attribute.
+      #   So long as you provide a marshaler which implements `#type_cast` and
+      #   `#serialize` that consume raw values as expected, you can bring your
+      #   own marshaler type.
+      # @option options [Array] :validators An array of validator classes that
+      #   will be run when an attribute is checked for validity.
+      # @option options [String] :database_attribute_name Optional attribute
+      #   used to specify a different name for database persistence than the
+      #   `name` parameter. Must be unique (you can't have overlap between
+      #   database attribute names and the names of other attributes).
+      # @option options [String] :dynamodb_type Generally used for keys and
+      #   index attributes, one of "S", "N", "B", "BOOL", "SS", "NS", "BS",
+      #   "M", "L". Optional if this attribute will never be used for a key or
+      #   secondary index, but most convenience methods for setting attributes
+      #   will provide this.
       def initialize(name, options = {})
         @name = name
         @database_name = options[:database_attribute_name] || name.to_s
@@ -12,14 +43,31 @@ module Aws
         @validators = options[:validators] || []
       end
 
+      # Attempts to type cast a raw value into the attribute's type. This call
+      # will forward the raw value to this attribute's marshaler class.
+      #
+      # @return [Object] the type cast object. Return type is dependent on the
+      #  marshaler used. See your attribute's marshaler class for details.
       def type_cast(raw_value)
         @marshaler.type_cast(raw_value)
       end
 
+      # Attempts to serialize a raw value into the attribute's serialized
+      # storage type. This call will forward the raw value to this attribute's
+      # marshaler class.
+      #
+      # @return [Object] the serialized object. Return type is dependent on the
+      #  marshaler used. See your attribute's marshaler class for details.
       def serialize(raw_value)
         @marshaler.serialize(raw_value)
       end
 
+      # Checks if the raw value is valid for this attribute. This is done by
+      # type casting the raw value, then running that value through each
+      # validator present for this attribute.
+      #
+      # @return [Boolean] true if the raw value is valid for this attribute,
+      #  false if it is not.
       def valid?(raw_value)
         value = type_cast(raw_value)
         @validators.all? do |validator|
@@ -27,8 +75,9 @@ module Aws
         end
       end
 
+      # @api private
       def extract(dynamodb_item)
-        dynamodb_item[database_name]
+        dynamodb_item[@database_name]
       end
 
     end

data/lib/aws-record/record/attributes.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     module Attributes
@@ -30,21 +43,21 @@ module Aws
         #   as you provide a marshaler which implements `#type_cast` and
         #   `#serialize` that consume raw values as expected, you can bring your
         #   own marshaler type. Convenience methods will provide this for you.
-        # @param [Hash] options
-        # @option options [Array] :validators An array of validator classes that
+        # @param [Hash] opts
+        # @option opts [Array] :validators An array of validator classes that
         #   will be run when an attribute is checked for validity.
-        # @option options [String] :database_attribute_name Optional attribute
+        # @option opts [String] :database_attribute_name Optional attribute
         #   used to specify a different name for database persistence than the
         #   `name` parameter. Must be unique (you can't have overlap between
         #   database attribute names and the names of other attributes).
-        # @option options [String] :dynamodb_type Generally used for keys and
+        # @option opts [String] :dynamodb_type Generally used for keys and
         #   index attributes, one of "S", "N", "B", "BOOL", "SS", "NS", "BS",
         #   "M", "L". Optional if this attribute will never be used for a key or
         #   secondary index, but most convenience methods for setting attributes
         #   will provide this.
-        # @option options [Boolean] :hash_key Set to true if this attribute is
+        # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
-        # @option options [Boolean] :range_key Set to true if this attribute is
+        # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
         def attr(name, marshaler, opts = {})
           validate_attr_name(name)
@@ -68,84 +81,84 @@ module Aws
         #
         # @param [Symbol] name Name of this attribute.  It should be a name that
         #   is safe to use as a method.
-        # @param [Hash] options
-        # @option options [Boolean] :hash_key Set to true if this attribute is
+        # @param [Hash] opts
+        # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
-        # @option options [Boolean] :range_key Set to true if this attribute is
+        # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
-        def string_attr(id, opts = {})
+        def string_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
-          attr(id, Attributes::StringMarshaler, opts)
+          attr(name, Attributes::StringMarshaler, opts)
         end
 
         # Define a boolean-type attribute for your model.
         #
         # @param [Symbol] name Name of this attribute.  It should be a name that
         #   is safe to use as a method.
-        # @param [Hash] options
-        # @option options [Boolean] :hash_key Set to true if this attribute is
+        # @param [Hash] opts
+        # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
-        # @option options [Boolean] :range_key Set to true if this attribute is
+        # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
-        def boolean_attr(id, opts = {})
+        def boolean_attr(name, opts = {})
           opts[:dynamodb_type] = "BOOL"
-          attr(id, Attributes::BooleanMarshaler, opts)
+          attr(name, Attributes::BooleanMarshaler, opts)
         end
 
         # Define a integer-type attribute for your model.
         #
         # @param [Symbol] name Name of this attribute.  It should be a name that
         #   is safe to use as a method.
-        # @param [Hash] options
-        # @option options [Boolean] :hash_key Set to true if this attribute is
+        # @param [Hash] opts
+        # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
-        # @option options [Boolean] :range_key Set to true if this attribute is
+        # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
-        def integer_attr(id, opts = {})
+        def integer_attr(name, opts = {})
           opts[:dynamodb_type] = "N"
-          attr(id, Attributes::IntegerMarshaler, opts)
+          attr(name, Attributes::IntegerMarshaler, opts)
         end
 
         # Define a float-type attribute for your model.
         #
         # @param [Symbol] name Name of this attribute.  It should be a name that
         #   is safe to use as a method.
-        # @param [Hash] options
-        # @option options [Boolean] :hash_key Set to true if this attribute is
+        # @param [Hash] opts
+        # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
-        # @option options [Boolean] :range_key Set to true if this attribute is
+        # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
-        def float_attr(id, opts = {})
+        def float_attr(name, opts = {})
           opts[:dynamodb_type] = "N"
-          attr(id, Attributes::FloatMarshaler, opts)
+          attr(name, Attributes::FloatMarshaler, opts)
         end
 
         # Define a date-type attribute for your model.
         #
         # @param [Symbol] name Name of this attribute.  It should be a name that
         #   is safe to use as a method.
-        # @param [Hash] options
-        # @option options [Boolean] :hash_key Set to true if this attribute is
+        # @param [Hash] opts
+        # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
-        # @option options [Boolean] :range_key Set to true if this attribute is
+        # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
-        def date_attr(id, opts = {})
+        def date_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
-          attr(id, Attributes::DateMarshaler, opts)
+          attr(name, Attributes::DateMarshaler, opts)
         end
 
         # Define a datetime-type attribute for your model.
         #
         # @param [Symbol] name Name of this attribute.  It should be a name that
         #   is safe to use as a method.
-        # @param [Hash] options
-        # @option options [Boolean] :hash_key Set to true if this attribute is
+        # @param [Hash] opts
+        # @option opts [Boolean] :hash_key Set to true if this attribute is
         #   the hash key for the table.
-        # @option options [Boolean] :range_key Set to true if this attribute is
+        # @option opts [Boolean] :range_key Set to true if this attribute is
         #   the range key for the table.
-        def datetime_attr(id, opts = {})
+        def datetime_attr(name, opts = {})
           opts[:dynamodb_type] = "S"
-          attr(id, Attributes::DateTimeMarshaler, opts)
+          attr(name, Attributes::DateTimeMarshaler, opts)
         end
 
         # @return [Hash] hash of symbolized attribute names to attribute objects
@@ -153,6 +166,11 @@ module Aws
           @attributes
         end
 
+        # @return [Hash] hash of database names to attribute names
+        def storage_attributes
+          @storage_attributes
+        end
+
         # @return [Aws::Record::Attribute,nil]
         def hash_key
           @attributes[@keys[:hash]]
@@ -218,12 +236,12 @@ module Aws
         end
 
         def check_for_naming_collisions(name, storage_name)
-          if @attributes[storage_name]
+          if @attributes[storage_name.to_sym]
             raise Errors::NameCollision.new(
               "Custom storage name #{storage_name} already exists as an"\
                 " attribute name in #{@attributes}"
             )
-          elsif @storage_attributes[name]
+          elsif @storage_attributes[name.to_s]
             raise Errors::NameCollision.new(
               "Attribute name #{name} already exists as a custom storage"\
                 " name in #{@storage_attributes}"

data/lib/aws-record/record/attributes/boolean_marshaler.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     module Attributes

data/lib/aws-record/record/attributes/date_marshaler.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 require 'date'
 
 module Aws

data/lib/aws-record/record/attributes/date_time_marshaler.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 require 'date'
 
 module Aws

data/lib/aws-record/record/attributes/float_marshaler.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     module Attributes

data/lib/aws-record/record/attributes/integer_marshaler.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     module Attributes

data/lib/aws-record/record/attributes/string_marshaler.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     module Attributes

data/lib/aws-record/record/errors.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     module Errors

data/lib/aws-record/record/item_collection.rb

@@ -0,0 +1,42 @@
+module Aws
+  module Record
+    class ItemCollection
+      include Enumerable
+
+      def initialize(search_method, search_params, model, client)
+        @search_method = search_method
+        @search_params = search_params
+        @model = model
+        @client = client
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block_given?
+        unless @result
+          @result = @client.send(@search_method, @search_params)
+        end
+        @result.each_page do |page|
+          items = _build_items_from_response(page.items, @model)
+          items.each do |item|
+            yield item
+          end
+        end
+      end
+
+      private
+      def _build_items_from_response(items, model)
+        ret = []
+        items.each do |item|
+          record = model.new
+          data = record.instance_variable_get("@data")
+          model.attributes.each do |name, attr|
+            data[name] = attr.extract(item)
+          end
+          ret << record
+        end
+        ret
+      end
+
+    end
+  end
+end

data/lib/aws-record/record/item_operations.rb

@@ -1,11 +1,32 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     module ItemOperations
 
+      # @api private
       def self.included(sub_class)
         sub_class.extend(ItemOperationsClassMethods)
       end
 
+      # Saves this instance of an item to Amazon DynamoDB using the
+      # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#put_item-instance_method Aws::DynamoDB::Client#put_item}
+      # API. Uses this item instance's attributes in order to build the request
+      # on your behalf.
+      #
+      # @raise [Aws::Record::Errors::KeyMissing] if a required key attribute
+      #  does not have a value within this item instance.
       def save
         dynamodb_client.put_item(
           table_name: self.class.table_name,
@@ -13,6 +34,10 @@ module Aws
         )
       end
 
+      # Deletes the item instance that matches the key values of this item
+      # instance in Amazon DynamoDB. Uses the
+      # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#delete_item-instance_method Aws::DynamoDB::Client#delete_item}
+      # API.
       def delete!
         dynamodb_client.delete_item(
           table_name: self.class.table_name,
@@ -60,6 +85,21 @@ module Aws
       end
 
       module ItemOperationsClassMethods
+
+        # @example Usage Example
+        #   class MyModel
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #   end
+        #   
+        #   MyModel.find(id: 1, name: "First")
+        #
+        # @param [Hash] opts attribute-value pairs for the key you wish to
+        #  search for.
+        # @return [Aws::Record] builds and returns an instance of your model.
+        # @raise [Aws::Record::Errors::KeyMissing] if your option parameters do
+        #  not include all table keys.
         def find(opts)
           key = {}
           @keys.each_value do |attr_sym|
@@ -92,14 +132,6 @@ module Aws
           end
           record
         end
-
-        def user_agent(custom)
-          if custom
-            custom
-          else
-            " aws-record/#{VERSION}"
-          end
-        end
       end
 
     end

data/lib/aws-record/record/query.rb

@@ -0,0 +1,56 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
+module Aws
+  module Record
+    module Query
+
+      # @api private
+      def self.included(sub_class)
+        sub_class.extend(QueryClassMethods)
+      end
+
+      module QueryClassMethods
+
+        # This method calls
+        # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#query-instance_method Aws::DynamoDB::Client#query},
+        # populating the +:table_name+ parameter from the model class, and
+        # combining this with the other parameters you provide.
+        #
+        # @param [Hash] opts options to pass on to the client call to +#query+.
+        #   See the documentation above in the AWS SDK for Ruby V2.
+        # @return [Aws::Record::ItemCollection] an enumerable collection of the
+        #   query result.
+        def query(opts)
+          query_opts = opts.merge(table_name: table_name)
+          ItemCollection.new(:query, query_opts, self, dynamodb_client)
+        end
+
+        # This method calls
+        # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#scan-instance_method Aws::DynamoDB::Client#scan},
+        # populating the +:table_name+ parameter from the model class, and
+        # combining this with the other parameters you provide.
+        #
+        # @param [Hash] opts options to pass on to the client call to +#scan+.
+        #   See the documentation above in the AWS SDK for Ruby V2.
+        # @return [Aws::Record::ItemCollection] an enumerable collection of the
+        #   scan result.
+        def scan(opts = {})
+          scan_opts = opts.merge(table_name: table_name)
+          ItemCollection.new(:scan, scan_opts, self, dynamodb_client)
+        end
+      end
+
+    end
+  end
+end

data/lib/aws-record/record/secondary_indexes.rb

@@ -0,0 +1,156 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
+module Aws
+  module Record
+    module SecondaryIndexes
+
+      # @api private
+      def self.included(sub_class)
+        sub_class.instance_variable_set("@local_secondary_indexes", {})
+        sub_class.instance_variable_set("@global_secondary_indexes", {})
+        sub_class.extend(SecondaryIndexesClassMethods)
+      end
+
+      module SecondaryIndexesClassMethods
+
+        # Creates a local secondary index for the model. Learn more about Local
+        # Secondary Indexes in the
+        # {http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html Amazon DynamoDB Developer Guide}.
+        #
+        # @param [Symbol] name index name for this local secondary index
+        # @param [Hash] opts
+        # @option opts [Symbol] :range_key the range key used by this local
+        #   secondary index. Note that the hash key MUST be the table's hash
+        #   key, and so that value will be filled in for you.
+        # @option opts [Hash] :projection a hash which defines which attributes
+        #   are copied from the table to the index. See shape details in the
+        #   {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Types/Projection.html AWS SDK for Ruby V2 docs}.
+        def local_secondary_index(name, opts)
+          opts[:hash_key] = hash_key.name
+          _validate_required_lsi_keys(opts)
+          local_secondary_indexes[name] = opts
+        end
+
+        # Creates a global secondary index for the model. Learn more about
+        # Global Secondary Indexes in the
+        # {http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html Amazon DynamoDB Developer Guide}.
+        #
+        # @param [Symbol] name index name for this global secondary index
+        # @param [Hash] opts
+        # @option opts [Symbol] :hash_key the hash key used by this global
+        #   secondary index.
+        # @option opts [Symbol] :range_key the range key used by this global
+        #   secondary index.
+        # @option opts [Hash] :projection a hash which defines which attributes
+        #   are copied from the table to the index. See shape details in the
+        #   {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Types/Projection.html AWS SDK for Ruby V2 docs}.
+        def global_secondary_index(name, opts)
+          _validate_required_gsi_keys(opts)
+          global_secondary_indexes[name] = opts
+        end
+
+        # @return [Hash] hash of local secondary index names to the index's
+        #   attributes.
+        def local_secondary_indexes
+          @local_secondary_indexes
+        end
+
+        # @return [Hash] hash of global secondary index names to the index's
+        #   attributes.
+        def global_secondary_indexes
+          @global_secondary_indexes
+        end
+
+        # @return [Hash] hash of the local secondary indexes in a form suitable
+        #   for use in a table migration. For example, any attributes which
+        #   have a unique database storage name will use that name instead.
+        def local_secondary_indexes_for_migration
+          _migration_format_indexes(local_secondary_indexes)
+        end
+
+        # @return [Hash] hash of the global secondary indexes in a form suitable
+        #   for use in a table migration. For example, any attributes which
+        #   have a unique database storage name will use that name instead.
+        def global_secondary_indexes_for_migration
+          _migration_format_indexes(global_secondary_indexes)
+        end
+
+        private
+        def _migration_format_indexes(indexes)
+          return nil if indexes.empty?
+          indexes.collect do |name, opts|
+            h = { index_name: name }
+            h[:key_schema] = _si_key_schema(opts)
+            opts.delete(:hash_key)
+            opts.delete(:range_key)
+            h = h.merge(opts)
+            h
+          end
+        end
+
+        def _si_key_schema(opts)
+          key_schema = [{
+            key_type: "HASH",
+            attribute_name: @attributes[opts[:hash_key]].database_name
+          }]
+          if opts[:range_key]
+            key_schema << {
+              key_type: "RANGE",
+              attribute_name: @attributes[opts[:range_key]].database_name
+            }
+          end
+          key_schema
+        end
+
+        def _validate_required_lsi_keys(params)
+          if params[:hash_key] && params[:range_key]
+            _validate_attributes_exist(params[:hash_key], params[:range_key])
+          else
+            raise ArgumentError.new(
+              "Local Secondary Indexes require a hash and range key!"
+            )
+          end
+        end
+
+        def _validate_required_gsi_keys(params)
+          if params[:hash_key]
+            if params[:range_key]
+              _validate_attributes_exist(params[:hash_key], params[:range_key])
+            else
+              _validate_attributes_exist(params[:hash_key])
+            end
+          else
+            raise ArgumentError.new(
+              "Global Secondary Indexes require at least a hash key!"
+            )
+          end
+        end
+
+        def _validate_attributes_exist(*attr_names)
+          missing = attr_names.select do |attr_name|
+            @attributes[attr_name].nil?
+          end
+          unless missing.empty?
+            raise ArgumentError.new(
+              "#{missing.join(", ")} not present in model attributes."\
+                " Please ensure that attributes are defined in the model"\
+                " class BEFORE defining a index on those attributes."
+            )
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/aws-record/record/table_migration.rb

@@ -1,24 +1,88 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
     class TableMigration
 
+      # @!attribute [rw] client
+      #   @return [Aws::DynamoDB::Client] the
+      #     {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html Aws::DynamoDB::Client}
+      #     class used by this table migration instance.
       attr_accessor :client
 
-      def initialize(model, client: nil)
+      # @param [Aws::Record] model a model class that includes {Aws::Record}.
+      # @param [Hash] opts
+      # @option opts [Aws::DynamoDB::Client] :client Allows you to inject your
+      #  own
+      #  {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html Aws::DynamoDB::Client}
+      #  class. If this option is not included, a client will be constructed for
+      #  you with default parameters.
+      def initialize(model, opts = {})
         assert_model_valid(model)
         @model = model
-        @client = client || Aws::DynamoDB::Client.new
+        @client = opts[:client] || Aws::DynamoDB::Client.new
       end
 
+      # This method calls
+      # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#create_table-instance_method Aws::DynamoDB::Client#create_table},
+      # populating the attribute definitions and key schema based on your model
+      # class, as well as passing through other parameters as provided by you.
+      #
+      # @param [Hash] opts options to pass on to the client call to
+      #  +#create_table+. See the documentation above in the AWS SDK for Ruby
+      #  V2.
+      # @option opts [Hash] :provisioned_throughput This is a required argument,
+      #  in which you must specify the +:read_capacity_units+ and
+      #  +:write_capacity_units+ of your new table.
+      # @option opts [Hash] :global_secondary_index_throughput This argument is
+      #  required if you define any global secondary indexes. It should map your
+      #  global secondary index names to their provisioned throughput, similar
+      #  to how you define the provisioned throughput for the table in general.
       def create!(opts)
+        gsit = opts.delete(:global_secondary_index_throughput)
         create_opts = opts.merge({
           table_name: @model.table_name,
           attribute_definitions: attribute_definitions,
           key_schema: key_schema
         })
+        if lsis = @model.local_secondary_indexes_for_migration
+          create_opts[:local_secondary_indexes] = lsis
+          _append_to_attribute_definitions(lsis, create_opts)
+        end
+        if gsis = @model.global_secondary_indexes_for_migration
+          unless gsit
+            raise ArgumentError.new(
+              "If you define global secondary indexes, you must also define"\
+                " :global_secondary_index_throughput on table creation."
+            )
+          end
+          gsis_with_throughput = _add_throughout_to_gsis(gsis, gsit)
+          create_opts[:global_secondary_indexes] = gsis_with_throughput
+          _append_to_attribute_definitions(gsis, create_opts)
+        end
         @client.create_table(create_opts)
       end
 
+      # This method calls
+      # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#update_table-instance_method Aws::DynamoDB::Client#update_table}
+      # using the parameters that you provide.
+      #
+      # @param [Hash] opts options to pass on to the client call to
+      #  +#update_table+. See the documentation above in the AWS SDK for Ruby
+      #  V2.
+      # @raise [Aws::Record::Errors::TableDoesNotExist] if the table does not
+      #  currently exist in Amazon DynamoDB.
       def update!(opts)
         begin
           update_opts = opts.merge({
@@ -30,6 +94,12 @@ module Aws
         end
       end
 
+      # This method calls
+      # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#delete_table-instance_method Aws::DynamoDB::Client#delete_table}
+      # using the table name of your model.
+      #
+      # @raise [Aws::Record::Errors::TableDoesNotExist] if the table did not
+      #  exist in Amazon DynamoDB at the time of calling.
       def delete!
         begin
           @client.delete_table(table_name: @model.table_name)
@@ -38,6 +108,10 @@ module Aws
         end
       end
 
+      # This method waits on the table specified in the model to exist and be
+      # marked as ACTIVE in Amazon DynamoDB. Note that this method can run for
+      # several minutes if the table does not exist, and is not created within
+      # the wait period.
       def wait_until_available
         @client.wait_until(:table_exists, table_name: @model.table_name)
       end
@@ -69,6 +143,46 @@ module Aws
         end
       end
 
+      def _append_to_attribute_definitions(secondary_indexes, create_opts)
+        attr_def = create_opts[:attribute_definitions]
+        secondary_indexes.each do |si|
+          si[:key_schema].each do |key_schema|
+            exists = attr_def.find { |a|
+              a[:attribute_name] == key_schema[:attribute_name]
+            }
+            unless exists
+              attr = @model.attributes[
+                @model.storage_attributes[key_schema[:attribute_name]]
+              ]
+              attr_def << {
+                attribute_name: attr.database_name,
+                attribute_type: attr.dynamodb_type
+              }
+            end
+          end
+        end
+        create_opts[:attribute_definitions] = attr_def
+      end
+
+      def _add_throughout_to_gsis(global_secondary_indexes, gsi_throughput)
+        missing_throughput = []
+        ret = global_secondary_indexes.map do |params|
+          name = params[:index_name]
+          throughput = gsi_throughput[name]
+          missing_throughput << name unless throughput
+          params.merge(provisioned_throughput: throughput)
+        end
+        unless missing_throughput.empty?
+          raise ArgumentError.new(
+            "Missing provisioned throughput for the following global secondary"\
+              " indexes: #{missing_throughput.join(", ")}. GSIs:"\
+              " #{global_secondary_indexes} and defined throughput:"\
+              " #{gsi_throughput}"
+          )
+        end
+        ret
+      end
+
       def key_schema
         keys.map do |type, attr|
           {

data/lib/aws-record/record/version.rb

@@ -1,5 +1,18 @@
+# Copyright 2015-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not
+# use this file except in compliance with the License. A copy of the License is
+# located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
 module Aws
   module Record
-    VERSION = "1.0.0.pre.1"
+    VERSION = "1.0.0.pre.2"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.1
+  version: 1.0.0.pre.2
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-23 00:00:00.000000000 Z
+date: 2016-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-resources
@@ -42,7 +42,10 @@ files:
 - lib/aws-record/record/attributes/integer_marshaler.rb
 - lib/aws-record/record/attributes/string_marshaler.rb
 - lib/aws-record/record/errors.rb
+- lib/aws-record/record/item_collection.rb
 - lib/aws-record/record/item_operations.rb
+- lib/aws-record/record/query.rb
+- lib/aws-record/record/secondary_indexes.rb
 - lib/aws-record/record/table_migration.rb
 - lib/aws-record/record/version.rb
 homepage: http://github.com/aws/aws-sdk-ruby-record
@@ -65,7 +68,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: AWS Record library for Amazon DynamoDB