dynamini 1.8.2 → 1.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 13893f0fc6ee9e9871a4627e5becc6d28586faa2
-  data.tar.gz: 47ad7abf1223ebc4e7372540a109146adf59644e
+  metadata.gz: 356f8de542ea075c952843efbed411bbd65f223d
+  data.tar.gz: 97f98ccc45f1e5dcf93ed8f66628cc647c1018fb
 SHA512:
-  metadata.gz: 98a97520da94e1396c0a78c8f0d609d4caadb48ce0adaa2f9c778e1e79b75e73478124aa93e65d9b3f0823472f35ffc31a656a0d81c83f7a1f28f0629f194462
-  data.tar.gz: 93936a76f1efe1b2dd22d4f30d05d3cc4019a8bc53e3ca0ee3d59886c2cc58ec5f70d53a3e78633d5e88b9815f664d6595917be2a413ee2739d15c6359f9d38a
+  metadata.gz: 7cc1c405737dc4e50018be9b2141aab9d1af70263a929c2d18c3d274b92266b8c10feec881f5a7121a307a1f22032121020b6fca5441a9a13966d7d43315c593
+  data.tar.gz: e8a6743e11f1fc7ff9a3cb8e17795a273b45ce0ac4cd30b9a2f0324746b68cbdbe53cd9f048cc415adf445637d8ed8470fb8bfac0db93ab000f06f3491c5ca0c

data/.gitignore

@@ -0,0 +1,7 @@
+.idea
+*.gem
+dynamini.iml
+/.ruby-version
+/.ruby-gemset
+.DS_Store
+/spec/.DS_Store

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format Fuubar

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+script: bundle exec rspec
+rvm:
+- 2.0.0
+- 2.2.1
+notifications:
+  email:
+    recipients:
+      - dev@retailcommon.com
+    on_success: change
+    on_failure: always

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,101 @@
+PATH
+  remote: .
+  specs:
+    dynamini (1.9.1)
+      activemodel (>= 3, < 5.0)
+      aws-sdk (~> 2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (4.2.5)
+      activesupport (= 4.2.5)
+      builder (~> 3.1)
+    activesupport (4.2.5)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    aws-sdk (2.2.5)
+      aws-sdk-resources (= 2.2.5)
+    aws-sdk-core (2.2.5)
+      jmespath (~> 1.0)
+    aws-sdk-resources (2.2.5)
+      aws-sdk-core (= 2.2.5)
+    builder (3.2.2)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    ffi (1.9.10)
+    formatador (0.2.5)
+    fuubar (2.0.0)
+      rspec (~> 3.0)
+      ruby-progressbar (~> 1.4)
+    guard (2.13.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, <= 4.0)
+      lumberjack (~> 1.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.6.4)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    guard-shell (0.7.1)
+      guard (>= 2.0.0)
+      guard-compat (~> 1.0)
+    i18n (0.7.0)
+    jmespath (1.1.3)
+    json (1.8.3)
+    listen (3.0.3)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.9)
+    method_source (0.8.2)
+    minitest (5.8.3)
+    nenv (0.2.0)
+    notiffany (0.0.8)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    pry (0.10.3)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rb-fsevent (0.9.6)
+    rb-inotify (0.9.5)
+      ffi (>= 0.5.0)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    ruby-progressbar (1.7.5)
+    shellany (0.0.1)
+    slop (3.6.0)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  dynamini!
+  fuubar (~> 2)
+  guard-rspec
+  guard-shell
+  pry (~> 0)
+  rspec (~> 3)

data/Guardfile

@@ -0,0 +1,79 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.("routing/#{m[1]}_routing"),
+      rspec.spec.("controllers/#{m[1]}_controller"),
+      rspec.spec.("acceptance/#{m[1]}")
+    ]
+  end
+
+  watch(%r{^lib\/[a-zA-Z]+\/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.("features/#{m[1]}") }
+  watch(rails.layouts)       { |m| rspec.spec.("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  end
+end
+
+# Add files and commands to this file, like the example:
+#   watch(%r{file/path}) { `command(s)` }
+#
+guard :shell do
+  watch(/(.*).txt/) {|m| `tail #{m[0]}` }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 47colborne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,214 @@
+## Dynamini
+Dynamini is a lightweight DynamoDB interface designed as a drop-in replacement for ActiveRecord. This gem powers part of our stack at yroo.com.
+
+[![Build Status](https://travis-ci.org/47colborne/dynamini.svg?branch=master)](https://travis-ci.org/47colborne/dynamini)
+[![Code Climate](https://codeclimate.com/github/47colborne/dynamini/badges/gpa.svg)](https://codeclimate.com/github/47colborne/dynamini)
+[![Gem Version](https://badge.fury.io/rb/dynamini.svg)](https://badge.fury.io/rb/dynamini)
+
+## The Basics
+This gem provides an opinionated interface, set up to let you use Amazon's DynamoDB at its most efficient. That means traditional relational DB functions like WHERE, GROUP BY, and HAVING aren't provided, since these trigger table scans that defeat the performance gains realized by switching to Dynamo in the first place. Use this gem when you have an relational table with too much concurrent activity, resulting in constant table locking. After you've moved your data to Dynamo, and installed and configured Dynamini, the following ActiveRecord functions will be preserved:
+
+Class methods:
+* create(attributes)
+* create!(attributes)
+* find(hash_key, range_key)
+* exists?(hash_key, range_key)
+* find_or_new(hash_key, range_key)
+* import(model_array)
+
+Note: The range_key arguments are only necessary if your DynamoDB table is configured with a range key.
+
+Instance methods:
+* new(attributes)
+* ==(object)
+* assign_attributes(attributes)
+* update_attributes(attributes)
+* update_attribute(attribute, value)
+* save
+* save!
+* delete
+* touch
+* changes
+* changed
+* _was (e.g. model.foo_was, model.bar_was)
+* new_record?
+* updated_at
+* created_at
+
+We've included ActiveModel::Validations, so any validators will still work and be triggered by the save/create methods.
+There are also some new functions specific to DynamoDB's API:
+
+* batch_find([keys]) - to retrieve multiple objects at once.
+* enqueue_for_save(attributes) - to add your object to the batch write queue, which automatically sends a batch_save at length 25.
+* flush_queue! - to send the items in batch_save queue before reaching length 25.
+* increment!({attribute1: amount, attribute2: amount}) - to update your record using DynamoDB's Atomic Counter functionality. (For more information, see http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.AtomicCounters )
+
+## Configuration
+In application.rb, or in initializers/dynamini.rb, include your AWS settings like so:
+
+```ruby
+Dynamini.configure do |config|
+  config.aws_region = '[AWS region containing your DynamoDB instance]'
+  config.access_key_id = '[access_key_id for your AWS account]'
+  config.secret_access_key = '[secret_access_key for your AWS account]'
+end
+```
+
+Then set up your model. You'll need to have it inherit from Dynamini::Base, then identify the primary key and table name to match your DynamoDB setup.
+
+Here's what a sample model looks like. This one includes a range key - sometimes your table will only need a hash key. If you aren't sure how or why to use range keys (also known as sort keys) with your DynamoDB instance, check here for help: http://stackoverflow.com/a/27348364
+
+```ruby
+class Vehicle < Dynamini::Base
+    set_table_name 'cars-dev' # must match the table name configured in AWS
+    set_hash_key :model       # defaults to :id if not set
+    set_range_key :vin        # must be set if your AWS table is configured with a range key
+    
+    # ...All the rest of your class methods, instance methods, and validators
+end
+```
+
+## Datatype Handling
+There are a few quirks about how the Dynamo Ruby SDK stores data. It stores numeric values as BigDecimal objects, symbols as strings, and doesn't accept ruby Date or Time objects. To save you from having to convert your data to the correct type before saving and after retrieval, you can use the :handle helper for automatic type conversion. You can also use this to specify default values for your fields. Here's how it works:
+
+```ruby
+class Vehicle < Dynamini::Base
+    set_hash_key :vin
+    handle :top_speed, :integer, default: 80
+end
+
+car = Vehicle.new(vin: '43H1R')
+car.top_speed
+> 80
+car.top_speed = 90
+car.save
+Vehicle.find('43H1R').top_speed
+> 90
+# This would return BigDecimal(90) without the handle helper.
+```
+
+Defaults are optional - without a default, a handled field without a value assigned to it will return nil like any other field.
+
+The following datatypes are supported by handle:
+* :integer
+* :float
+* :symbol
+* :boolean
+* :date
+* :time
+* :string
+
+Booleans and strings don't actually need to be translated, but you can set up defaults for those fields this way.
+The magic fields updated_at and created_at are handled as :time by default.
+
+## Querying With Range Keys
+
+Dynamini includes a query function that's much more narrow than ActiveRecord's where function. It's designed to retrieve a selection of records that belong to a given hash key but have various range key values. To use .query, your table needs to be configured with a range key, and you need to :handle that range field as a fundamentally numeric type - integer, float, date, or time. If your range key field isn't numeric, you won't be able to .query, but you'll still be able to .find your records normally.
+
+Query takes three arguments; a mandatory :hash_key, an optional :start, and an optional :end. Here's how you'd use it to find daily temperature data for a given city, selecting for specific date ranges:
+
+```ruby
+class DailyWeather < Dynamini::Base
+    set_hash_key :city
+    set_range_key :record_date
+    handle :temperature, :integer
+    handle :record_date, :date
+end
+
+# Seeding our dataset...
+A = DailyWeather.create!(city: "Toronto",  record_date: Date.new(2015,10,08), temperature: 15)
+B = DailyWeather.create!(city: "Toronto",  record_date: Date.new(2015,10,09), temperature: 17)
+C = DailyWeather.create!(city: "Toronto",  record_date: Date.new(2015,10,10), temperature: 12)
+D = DailyWeather.create!(city: "Seville",  record_date: Date.new(2015,10,10), temperature: 30)
+
+DailyWeather.query(hash_key: "Toronto")
+> [A, B, C]
+
+DailyWeather.query(hash_key: "Seville")
+> [D]
+
+DailyWeather.query(hash_key: "Bangkok")
+> []
+
+DailyWeather.query(hash_key: "Toronto", start: Date.new(2015,10,09))
+> [B, C]
+
+DailyWeather.query(hash_key: "Toronto", end: Date.new(2015,10,08))
+> [A]
+
+DailyWeather.query(hash_key: "Toronto", start: Date.new(2015,10,08), end: Date.new(2015,10,09))
+> [A, B]
+```
+
+## Array Support
+You can save arrays to your Dynamini model. If you've :handled that attribute, it will attempt to convert its contents to the correct datatype when setting and getting. Here's how it works:
+
+```ruby
+class Vehicle < Dynamini::Base
+    set_hash_key :vin
+    handle :parts, :symbol, default: []
+end
+
+car = Vehicle.new(vin: 'H3LL0')
+car.parts
+> []
+
+car.parts = 'wheel'
+car.parts
+> :wheel
+
+car.parts = ['wheel', 'brakes', 'seat']
+car.parts
+> [:wheel, :brakes, :seat]
+
+# This line will raise an error since 5 cannot be converted to a symbol.
+car.parts = ['wheel', 'brakes', 5]
+
+# That multitype array can be saved to a non-:handled attribute.
+car.stuff = ['wheel', 'brakes', 5]
+car.stuff
+> ['wheel', 'brakes', 5]
+# But then you won't have any type conversion.
+car.save
+Vehicle.find('H3LLO').stuff
+> ['wheel', 'brakes', BigDecimal(5)]
+```
+
+## Testing
+There's a test client included with this gem, meaning you don't have to connect to a real Dynamo instance when testing.
+You could also use this in development if you dont have a real Dynamo instance yet, but the data saved to it won't persist through a server restart.
+To activate this feature, just call:
+```ruby
+Vehicle.in_memory = true
+```
+After which any internal API calls will be replaced with calls to Dynamini::TestClient.
+
+The test client will not reset its database unless you tell it to, like so:
+```ruby
+Vehicle.client.reset
+```
+
+So, for instance, to get Rspec working with your test suite the way your ActiveRecord model behaved, add these lines to your spec_helper.rb:
+```ruby
+config.before(:all) {
+  Vehicle.in_memory = true
+}
+config.after(:each) {
+  Vehicle.client.reset # Large test suites will be very slow and unpredictable otherwise!
+}
+```
+
+## Things to remember
+* Since DynamoDB is schemaless, your model will respond to any method that looks like a reader, meaning model.foo will return nil.
+* You can also write any arbitrary attribute to your model.
+* Other models in your app cannot have a has_one or has_many relationship with your Dynamini model, since these would require a table scan. Your other models can still use belongs_to.
+* If you change the primary key value on an instance of your model, then resave it, you'll have two copies in your database.
+* If you use non-numeric strings for your primary key, remember to change your foreign key columns on related objects to be string type.
+* You might want to conditionally set the table name for your model based on the Rails.env, enabling separate tables for development and production.
+
+## Coming Soon
+* Conditional updates ( http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html )
+
+## Contributing
+
+If you'd like to contribute, pull requests are welcome!