mince 2.0.0.pre → 2.0.0.pre.2

data/lib/mince/config.rb

@@ -1,15 +1,31 @@
-module Mince
+module Mince # :nodoc:
   require 'singleton'
 
+  # = Configuration for Mince
+  #
+  # Mince can be configured to interact with different mince supported data interfaces.
+  #
+  # Simply run the following to specify the data interface to use
+  #   Mince::Config.interface = Mince::MyDb::Interface
+  #
+  # This is a singleton object in order to prevent multiple instances of this object from
+  # being used.
   class Config
     include Singleton
 
     attr_accessor :interface
 
+    # Sets the singleton's interface attribute so that you can change your storage strategy
+    # without changing all references to that class.
+    #
+    # @param [Class] interface the Mince Supported Interface class
     def self.interface=(interface)
       instance.interface = interface
     end
 
+    # Returns the interface that is configured to be used. Use this method instead of hard coding 
+    # which mince interface to use throughout your code so that you can change mince interfaces
+    # as needed.
     def self.interface
       instance.interface
     end

data/lib/mince/data_model.rb

@@ -0,0 +1,319 @@
+require 'active_support/hash_with_indifferent_access'
+require 'active_support/core_ext/object/instance_variables'
+require 'active_support/core_ext/hash/slice'
+require 'active_support/concern'
+
+require_relative 'config'
+
+module Mince # :nodoc:
+  # = DataModel
+  #
+  # Mince::DataModel is used as a mixin to easily mixin behavior into an object that 
+  # you wish to act as a data model and interact with mince data interfaces.
+  #
+  # Simply mixin this module in order to get a wrapper class to interact with a mince
+  # interface for a specific collection
+  #
+  # Example:
+  #   require 'mince/data_model'
+  #
+  #   class UserDataModel
+  #     include Mince::DataModel
+  #
+  #     data_collection :users
+  #     data_fields :username, :first_name, :last_name, :email, :password
+  #   end
+  #
+  # To access methods on the data model do the following:
+  #   user = User.new first_name: 'Matt'  # initialize a user from some User class
+  #   user.id = UserDataModel.store user  # returns the id of the stored user
+  #
+  #   UserDataModel.find 1                # => returns the data for the user with an id of 1
+  #   UserDataModel.find_all              # => returns all users
+  #
+  # View the docs for each method available
+  module DataModel
+    extend ActiveSupport::Concern
+
+    included do
+      # creates readonly attribute for id and model
+      attr_reader :id, :model
+    end
+
+    module ClassMethods # :nodoc:
+      # The interface configured by Mince::Config.interface=
+      #
+      # @returns [Class] interface class to be used by all mince data interactions
+      def interface
+        Config.interface
+      end
+
+      # Sets what data fields to accept
+      # Returns the fields
+      #
+      # * Calling multiple times will do an ammendment to the existing list of fields
+      # * Calling without any fields will simply return the current list of fields
+      #
+      # @param [*Array] *fields an array of fields to add to the data model
+      # @returns [Array] the fields defined for the data model
+      def data_fields(*fields)
+        create_data_fields(*fields) if fields.any?
+        @data_fields
+      end
+
+      # Sets the name of the data collection
+      # Returns the name of the data collection
+      #
+      # @param [String] collection_name the name of the collection to use
+      # @returns [String] returns the name of the collection
+      def data_collection(collection_name = nil)
+        set_data_collection(collection_name) if collection_name
+        @data_collection
+      end
+
+      # Stores the given model into the data store
+      #
+      # @param [Class] model a ruby class instance object to store into the data store
+      # @returns [id] returns the id of the newly stored object
+      def store(model)
+        new(model).tap do |p|
+          p.add_to_interface
+        end.id
+      end
+
+      # Updates the given model in the data store with the fields and values in model
+      #
+      # Uses model.id to find the record to update
+      #
+      # @param [Class] model a ruby class instance object to store into the data store
+      def update(model)
+        new(model).tap do |p|
+          p.replace_in_interface
+        end
+      end
+
+      # Updates a specific field with a value for the record with the given id
+      #
+      # @param [id] id the id of the record to update
+      # @param [Symbol] field the field to update
+      # @param [*] value the value to update the field with
+      def update_field_with_value(id, field, value)
+        interface.update_field_with_value(data_collection, id, field, value)
+      end
+
+      # Increments a field by a given amount
+      #
+      # Some databases provide very efficient algorithms for incrementing or decrementing a 
+      # value.
+      #
+      # @param [id] id the id of the record to update
+      # @param [Symbol] field the field to update
+      # @param [Numeric] amount the amount to increment or decrement the field with
+      def increment_field_by_amount(id, field, amount)
+        interface.increment_field_by_amount(data_collection, id, field, amount)
+      end
+
+      # Removes a value from an field that is an array
+      #
+      # @param [id] id the id of the record to update
+      # @param [Symbol] field the field to update
+      # @param [*] value the value to update the field with
+      def remove_from_array(id, field, value)
+        interface.remove_from_array(data_collection, interface.primary_key, id, field, value)
+      end
+
+      # Pushes a value to an array field
+      #
+      # @param [id] id the id of the record to update
+      # @param [Symbol] field the field to update
+      # @param [*] value the value to update the field with
+      def push_to_array(id, field, value)
+        interface.push_to_array(data_collection, interface.primary_key, id, field, value)
+      end
+
+      # Returns a record that has the given id
+      #
+      # Returns nil if nothing found
+      #
+      # @param [id] id the id of the record to find
+      # @returns [HashWithIndifferentAccess, nil] a hash with the data for the record
+      def find(id)
+        translate_from_interface interface.find(data_collection, interface.primary_key, id)
+      end
+
+      # Deletes a field from all records in the collection
+      #
+      # @param [Symbol] field the field to remove
+      def delete_field(field)
+        interface.delete_field(data_collection, field)
+      end
+
+
+      # Deletes a field from all records that matches the field / value key pairs in the 
+      # params provided in the collection
+      #
+      # This will only delete records that match all key/value pairs in the params hash.
+      #
+      #   DataModel.delete_by_params(username: 'railsgrammer', first_name: 'Matt Simpson')
+      #
+      # @param [Hash] params the key/value pair hash to delete records by
+      def delete_by_params(params)
+        interface.delete_by_params(data_collection, params)
+      end
+
+      # Finds all records in the collection
+      #
+      # @returns [Array] all records in the collection, empty array if non found.
+      def all
+        translate_each_from_interface interface.find_all(data_collection)
+      end
+
+      # Returns all records in the collection that has the given field and value
+      #
+      # @param [Symbol] field the field to query for
+      # @param [*] value the value to query on the field for
+      # @returns [Array] the set of records matching the field / value pair
+      def all_by_field(field, value)
+        translate_each_from_interface interface.get_all_for_key_with_value(data_collection, field, value)
+      end
+
+      # Finds all recurds that match a set of key / value pairs
+      #
+      # @param [Hash] hash a hash of field / value pairs to query records for
+      # @returns [Array] the set of records matching all key / value pairs
+      def all_by_fields(hash)
+        translate_each_from_interface interface.get_by_params(data_collection, hash)
+      end
+
+      # Finds One record that matches all of the field / value pairs
+      #
+      # @param [Hash] hash the hash to query for
+      # @returns [Hash] a hash containing the data for the found record, nil is returned when nothing is found
+      def find_by_fields(hash)
+        translate_from_interface all_by_fields(hash).first
+      end
+
+      # Finds One record that matches a field / value pair
+      #
+      # @param [Symbol] field the field to query for
+      # @param [*] value the value to query on the field for
+      # @returns [Hash] a hash containing the data for the found record, nil is returned when nothing is found
+      def find_by_field(field, value)
+        translate_from_interface interface.get_for_key_with_value(data_collection, field, value)
+      end
+
+      # Finds all records where the field contains any of the values
+      #
+      # @param [Symbol] field the field to query against
+      # @param [Array] values an array of values to get records for
+      # @returns [Array] an array containing all records that match the criteria
+      def containing_any(field, values)
+        translate_each_from_interface interface.containing_any(data_collection, field, values)
+      end
+
+      # Finds all records where the field, which must be an array field, contains the value
+      #
+      # @param [Symbol] field the field to query against
+      # @param [*] value the value to query against
+      # @returns [Array] an array containing all records that match the criteria
+      def array_contains(field, value)
+        translate_each_from_interface interface.array_contains(data_collection, field, value)
+      end
+
+      # Deletes the entire collection from the database
+      def delete_collection
+        interface.delete_collection(data_collection)
+      end
+
+      private
+
+      def translate_from_interface(hash)
+        if hash
+          hash["id"] = hash[primary_key] if hash[primary_key]
+          HashWithIndifferentAccess.new hash
+        end
+      end
+
+      def translate_each_from_interface(data)
+        data.collect {|d| translate_from_interface(d) }
+      end
+
+      def primary_key
+        @primary_key ||= interface.primary_key
+      end
+
+      def set_data_collection(collection_name)
+        @data_collection = collection_name
+      end
+
+      def create_data_fields(*fields)
+        attr_accessor *fields
+        @data_fields = fields
+      end
+    end
+
+    def initialize(model)
+      @model = model
+      set_data_field_values
+      set_id
+    end
+
+    def interface
+      self.class.interface
+    end
+
+    def data_fields
+      self.class.data_fields
+    end
+
+    def data_collection
+      self.class.data_collection
+    end
+
+    def add_to_interface
+      interface.add(data_collection, attributes)
+    end
+
+    def replace_in_interface
+      interface.replace(data_collection, attributes)
+    end
+
+    private
+
+    def attributes
+      model_instance_values.merge(primary_key => id)
+    end
+
+    def model_instance_values
+      HashWithIndifferentAccess.new(model.instance_values).slice(*data_fields)
+    end
+
+    def set_id
+      @id = model_has_id? ? model.id : generated_id
+    end
+
+    def generated_id
+      interface.generate_unique_id(model)
+    end
+
+    def model_has_id?
+      model.respond_to?(:id) && model.id
+    end
+
+    def set_data_field_values
+      data_fields.each { |field| set_data_field_value(field) }
+    end
+
+    def primary_key
+      interface.primary_key
+    end
+
+    def set_data_field_value(field)
+      self.send("#{field}=", model.send(field)) if field_exists?(field)
+    end
+
+    def field_exists?(field)
+      model.respond_to?(field) && !model.send(field).nil?
+    end
+  end
+end

data/lib/mince/model.rb

@@ -0,0 +1,161 @@
+require 'active_support'
+require 'active_model'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/object/instance_variables'
+
+module Mince
+  # = Model
+  #
+  # The mince model is a module that provides standard model to data behavior to the Mince data model mixing for a specific model.
+  #
+  # Simply mixin this module in order to get a wrapper class to interact with a mince
+  # interface for a specific collection
+  #
+  # Example:
+  #   require 'mince'
+  #
+  #   class BookDataModel
+  #     include Mince::DataModel
+  #
+  #     data_collection :books
+  #     data_fields :title, :publisher
+  #   end
+  #
+  #   class Book
+  #     include Mince::Model
+  #
+  #     data_model BookDataModel
+  #     fields :title, :publisher
+  #   end
+  #
+  #   book = Book.new title: 'The World In Photographs', publisher: 'National Geographic'
+  #   book.save
+  #
+  # View the docs for each method available
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveModel::Conversion
+      extend ActiveModel::Naming
+
+      attr_accessor :id
+    end
+
+    module ClassMethods
+      # Sets or returns the data model class for the model
+      def data_model(model=nil)
+        @data_model = model if model
+        @data_model
+      end
+
+      # Returns all models from the data model
+      def all
+        data_model.all.map{|a| new a }
+      end
+
+      # Returns a model that matches a given id, returns nil if none found
+      def find(id)
+        a = data_model.find(id)
+        new a if a
+      end
+
+      # Adds a field to the object.  Takes options to indicate assignability.  If `assignable`
+      # is set, the field will be assignable via 
+      #   model.field = 'foo'
+      #   model.attributes = { field: 'foo' }
+      #
+      def field(field_name, options={})
+        if options[:assignable]
+          add_assignable_field(field_name)
+        else
+          add_readonly_field(field_name)
+        end
+      end
+
+      # Adds a read only field, values for these fields can only be set in the class itself
+      # or from the hash sent in to the initializer
+      def add_readonly_field(field_name)
+        fields << field_name
+        readonly_fields << field_name
+        attr_reader field_name
+      end
+
+      # Adds an assignable field, values for these fields can be set using the field writer
+      # or from the `attributes=` method.
+      def add_assignable_field(field_name)
+        fields << field_name
+        assignable_fields << field_name
+        attr_accessor field_name
+      end
+
+      # Adds multiple readonly fields to the fields array, and returns the current list
+      # of fields.  If no fields are given, it just returns the current list of fields
+      def fields(*field_names)
+        @fields ||= []
+        field_names.each {|field_name| field(field_name) }
+        @fields
+      end
+
+      # Returns the list of assignable fields
+      def assignable_fields
+        @assignable_fields ||= []
+      end
+
+      # Returns the list of readonly fields
+      def readonly_fields
+        @readonly_fields ||= []
+      end
+    end
+
+    delegate :data_model, :assignable_fields, :readonly_fields, :fields, to: 'self.class'
+
+    # Sets values (for fields defined by calling .field or .fields) in the hash to the object 
+    # includes assignable and non-assignable fields
+    def initialize(hash={})
+      @id = hash[:id]
+      readonly_fields.each do |field_name|
+        self.instance_variable_set("@#{field_name}", hash[field_name]) if hash[field_name]
+      end
+      self.attributes = hash
+    end
+
+    # Returns true if the record indicates that it has been persisted to a data model.
+    # Returns false otherwise.
+    def persisted?
+      !!id
+    end
+
+    # Saves the object to the data model.  Stores if new, updates previous entry if it has already
+    # been saved.
+    def save
+      ensure_no_extra_fields
+      if persisted?
+        data_model.update(self)
+      else
+        @id = data_model.store(self)
+      end
+    end
+
+    # Sets values (for assignable fields only, defined by calling .field or .fields) in the hash
+    # to the object.
+    #
+    # Allows the proxy to have whitelisted attributes to be assigned from http requests.
+    def attributes=(hash={})
+      assignable_fields.each do |field|
+        send("#{field}=", hash[field]) if hash[field]
+      end
+    end
+
+    private
+
+    # Ensures that the data model has all of the fields that are trying to be saved. Raises an
+    # exception if the data model does not.
+    def ensure_no_extra_fields
+      extra_fields = (fields - data_model.data_fields)
+      if extra_fields.any?
+        raise "Tried to save a #{self.class.name} with fields not specified in #{data_model.name}: #{extra_fields.join(', ')}"
+      end
+    end
+  end
+end

data/lib/mince/shared_examples/interface_example.rb

@@ -1,5 +1,42 @@
 require_relative '../../mince'
 
+# = Shared example for a Mince Interface
+#
+# This is an Rspec Shared Example.  It provides the ability to test 
+# shared behavior of objects without duplication.
+#
+# Use this shared example as documentation on what API a mince data interface 
+# must implement and as a specification and integration test while developing
+# your mince data interface.
+#
+# == How to use
+#
+# For example. If I were writing a MySQL mince interface I would add mince
+# as a gem dependency in my library (in your Gemfile or gemspec file). I would
+# add Rspec, create a new spec file at spec/integration/mince_interface_spec.rb
+# with the following contents
+#   
+#   require_relative '../../lib/my_mince_mysql'
+#   require 'mince/shared_examples/interface_example'
+#
+#   describe 'Mince Interface with MySQL' do
+#     before do
+#       Mince::Config.interface = Mince::MyMinceMySQL::Interface
+#     end
+#
+#     it_behaves_like 'a mince interface'
+#   end
+# 
+# Run your spec
+# 
+#   bundle exec spec rspec/integration/mince_inerface_spect.rb
+#
+# Make the failures pass, when there are no failures your interface is fully
+# supported.  Be sure to submit your library when you've finished so others
+# can use it.
+#
+# For a real examples, view the hashy_db, mingo, or mince_dynamo_db gems
+#
 shared_examples_for 'a mince interface' do
   describe 'Mince Interface v2' do
     let(:interface) { Mince::Config.interface }
@@ -10,11 +47,15 @@ shared_examples_for 'a mince interface' do
     let(:data3) { { primary_key => 3, field_1: 'value 3', field_2: 9, shared_between_1_and_2: 'not the same as 1 and 2', :some_array => [1, 7]} }
 
     before do
-      interface.set_data({})
+      interface.clear
 
       interface.insert(:some_collection, [data1, data2, data3])
     end
 
+    after do
+      interface.clear
+    end
+
     describe "Generating a primary key" do
       subject do 
         (1..number_of_records).map do |salt|
@@ -40,7 +81,7 @@ shared_examples_for 'a mince interface' do
     it 'can delete a collection' do
       interface.delete_collection(:some_collection)
       
-      interface.find_all(:some_collection).should == []
+      interface.find_all(:some_collection).to_a.should == []
     end
 
     it 'can delete records that match a given set of fields' do
@@ -48,85 +89,94 @@ shared_examples_for 'a mince interface' do
 
       interface.delete_by_params(:some_collection, params)
 
-      interface.find_all(:some_collection).should == [data2, data3]
+      convert_each(interface.find_all(:some_collection)).should == convert_each([data2, data3])
     end
 
     it 'can write and read data to and from a collection' do
-      data4 = {primary_key =>3, field_1: 'value 3', field_2: 9, shared_between_1_and_2: 'not the same as 1 and 2', :some_array => [1, 7]}
+      data4 = {primary_key =>4, field_1: 'value 3', field_2: 9, shared_between_1_and_2: 'not the same as 1 and 2', :some_array => [1, 7]}
 
       interface.add(:some_collection, data4)
-      interface.find_all(:some_collection).should == [data1, data2, data3, data4]
+      convert_each(interface.find_all(:some_collection)).should == convert_each([data1, data2, data3, data4])
     end
 
     it 'can replace a record' do
       data2[:field_1] = 'value modified'
       interface.replace(:some_collection, data2)
 
-      interface.find(:some_collection, primary_key, 2)[:field_1].should == 'value modified'
+      convert(interface.find(:some_collection, primary_key, 2))[:field_1].should == 'value modified'
     end
 
     it 'can update a field with a value on a specific record' do
       interface.update_field_with_value(:some_collection, 3, :field_2, '10')
-      
-      interface.find(:some_collection, primary_key, 3)[:field_2].should == '10'
+
+      convert(interface.find(:some_collection, primary_key, 3))[:field_2].should == '10'
     end
 
     it 'can increment a field with a given amount for a specific field' do
       interface.increment_field_by_amount(:some_collection, 1, :field_2, 3)
-      
-      interface.find(:some_collection, primary_key, 1)[:field_2].should == 6
+
+      convert(interface.find(:some_collection, primary_key, 1))[:field_2].should == 6
     end
 
     it 'can get one document' do
-      interface.find(:some_collection, :field_1, 'value 1').should == data1
-      interface.find(:some_collection, :field_2, 6).should == data2
+      convert(interface.find(:some_collection, :field_1, 'value 1')).should == convert(data1)
+      convert(interface.find(:some_collection, :field_2, 6)).should == convert(data2)
     end
 
     it 'can clear the data store' do
       interface.clear
 
-      interface.find_all(:some_collection).should == []
+      interface.find_all(:some_collection).to_a.should == []
     end
 
     it 'can get all records of a specific key value' do
-      interface.get_all_for_key_with_value(:some_collection, :shared_between_1_and_2, 'awesome_value').should == [data1, data2]
+      convert_each(interface.get_all_for_key_with_value(:some_collection, :shared_between_1_and_2, 'awesome_value')).should == convert_each([data1, data2])
     end
 
     it 'can get all records where a value includes any of a set of values' do
-      interface.containing_any(:some_collection, :some_array, []).should == []
-      interface.containing_any(:some_collection, :some_array, [7, 2, 3]).should == [data1, data3]
-      interface.containing_any(:some_collection, primary_key, [1, 2, 5]).should == [data1, data2]
+      interface.containing_any(:some_collection, :some_array, []).to_a.should == []
+      convert_each(interface.containing_any(:some_collection, :some_array, [7, 2, 3])).should == convert_each([data1, data3])
+      convert_each(interface.containing_any(:some_collection, primary_key, [1, 2, 5])).should == convert_each([data1, data2])
     end
 
     it 'can get all records where the array includes a value' do
-      interface.array_contains(:some_collection, :some_array, 1).should == [data1, data3]
-      interface.array_contains(:some_collection, :some_array_2, 1).should == []
+      convert_each(interface.array_contains(:some_collection, :some_array, 1)).should == convert_each([data1, data3])
+      interface.array_contains(:some_collection, :some_array_2, 1).to_a.should == []
     end
 
     it 'can push a value to an array for a specific record' do
       interface.push_to_array(:some_collection, primary_key, 1, :field_3, 'add to existing array')
       interface.push_to_array(:some_collection, primary_key, 1, :new_field, 'add to new array')
 
-      interface.find(:some_collection, primary_key, 1)[:field_3].should include('add to existing array')
-      interface.find(:some_collection, primary_key, 1)[:new_field].should == ['add to new array']
+      record = convert(interface.find(:some_collection, primary_key, 1))
+      record[:field_3].should include('add to existing array')
+      record[:new_field].should == ['add to new array']
     end
 
     it 'can remove a value from an array for a specific record' do
       interface.remove_from_array(:some_collection, primary_key, 1, :field_3, 2)
 
-      interface.find(:some_collection, primary_key, 1)[:field_3].should_not include(2)
+      convert(interface.find(:some_collection, primary_key, 1))[:field_3].should_not include(2)
     end
 
     it 'can get all records that match a given set of keys and values' do
-      records = interface.get_by_params(:some_collection, field_1: 'value 1', shared_between_1_and_2: 'awesome_value')
+      records = interface.get_by_params(:some_collection, field_1: 'value 1', shared_between_1_and_2: 'awesome_value').to_a
       records.size.should be(1)
-      records.first[primary_key].should == 1
-      interface.find_all(:some_collection).size.should == 3
+      convert(records.first)[primary_key].should == 1
+      interface.find_all(:some_collection).to_a.size.should == 3
     end
 
     it 'can get a record for a specific key and value' do
-      interface.get_for_key_with_value(:some_collection, :field_1, 'value 1').should == data1
+      convert(interface.get_for_key_with_value(:some_collection, :field_1, 'value 1')).should == convert(data1)
     end
   end
+
+  def convert(hash)
+    HashWithIndifferentAccess.new(hash)
+  end
+
+  def convert_each(ary)
+    ary.map{|a| convert(a) }
+  end
 end