mince 2.0.0.pre → 2.0.0.pre.2

data/lib/mince/version.rb

@@ -9,7 +9,7 @@ module Mince
     end
 
     def self.patch
-      '0.pre'
+      '0.pre.2'
     end
   end
 

data/lib/mince.rb

@@ -1,2 +1,130 @@
-require_relative 'mince/version'
-require_relative 'mince/config'
+# = Mince
+#
+# Mince is focused to provide support to write database agnostic applications
+# and to write applications with an architecture that follows the Single
+# Responsibility principle.
+#
+# The highest level difference between using mince and using something
+# like Rails' ActiveRecord library is that mince does not encourage 
+# the "Active Record Pattern" in general.  Look "Active Record Pattern"
+# up in wikipedia to get a good understanding of what that means.
+#
+# Mince encourages separating your data objects and behavior from your
+# business objects and behavior.  These are two separate classes of 
+# objects with two complete separate responsibilities.
+#
+# * The data object provides access to the data store for a particular 
+#   collection of data.
+# * The business object adds behavior to the data object in order for the 
+#   application to provide business value
+#
+# Creating an architecture like this provides more flexibility and more
+# extensibility for your application.  While you are developing your application
+# you shoud be asking, what is the responsibility of this object? And make clear
+# separations of behavior and responsibility
+#
+# Given that being said.  The standard way to structure your directories while
+# using mince is the following
+#
+#   ./app
+#     ./models
+#       - authenticator.rb
+#       - user.rb
+#       - project.rb
+#     ./data_models
+#       - user_data_model.rb
+#       - project_data_model.rb
+#
+# 1. `Authenticator` is a standard ruby class that uses the user class
+#    to provide strong and clean authentication.
+# 2. `User` and `Project` are ruby classes with the Mince::Model mixed in to
+#    provide some standard behavior to interact with a mince data model.
+# 3. `UserDataModel` and `ProjectDataModel` are classes with the Mince::DataModel 
+#    mixed in to provide standard behavior to interact with a mince data interface.
+#
+# A quick example of the extensibility of this would be if you needed to get users
+# from LDAP or Active Directory rather than from MongoDB. This is a pretty common
+# request and similar to other requirements for enterprise applications.
+#
+# With this architecture you could easily expand it to the following:
+#
+#   ./app
+#     ./models
+#       - authenticator.rb
+#       - user.rb
+#       - project.rb
+#     ./data_models
+#       - ldap_user_data_model.rb
+#       - project_data_model.rb
+#
+# The only difference is now, instead of using a mince user data model, you are using
+# a custom ldap user data model.  As long as the API you wrote for the ldap user data
+# model requires the same input and provides the same output as the mince user data
+# model, then you did not have to change any other code in your application.
+#
+# Let's take this a little further. Say you have LDAP auth now, and you've continued
+# developing on your application.  You start feeling some pain with having your 
+# development environment depend on so many external systems in order to be up and
+# running.  Think about it, right now you are dependent on MongoDB and a deve LDAP
+# environment to be running and seeded with data. That was the position I was in
+# and one of the reasons I wrote mince.
+#
+# Let's extend the architecture like so:
+#
+#   - app/
+#     - models/
+#       - authenticator.rb
+#       - user.rb
+#       - user_data_provider.rb
+#       - project.rb
+#     ./data_models
+#       - ldap_user_data_model.rb
+#       - user_data_model.rb
+#       - project_data_model.rb
+#
+# I added a user data model and user data provider.  The user data provider determines
+# which user data source to use for the specific environment that you are in.
+#
+# If you are running in a development environment, then you would configure it to
+# use the user data model, if you are in staging, or production environments, you
+# would use the ldap user data model.
+#
+# This removes one external system dependency from our development environment, let's 
+# remove MongoDB from being a development dependency as well so that we can focus
+# on the business logic of our application, and not waste time on database maintenance
+# issues.
+#
+# Configure mince to use hashy_db when you are running in Development mode like so:
+#   # require mince, if you haven't already
+#   require 'mince'
+#
+#   # require the gem (needs to be installed via `gem install`, bundler, gemspec, 
+#   # or some other way)
+#   require 'hashy_db'
+#
+#   # Tell mince to use hashy_db
+#   Mince::Config.interface = Mince::HashyDb::Interface
+#
+# Now, all of mince related data interactions will use an in-memory hash.
+#
+# Configure mince to use mingo (a mince MongoDB interface) when you are running in Staging, or Production mode:
+#   # require mince, if you haven't already
+#   require 'mince'
+#
+#   # require the gem (needs to be installed via `gem install`, bundler, gemspec, 
+#   # or some other way)
+#   require 'mingo'
+#
+#   # Tell mince to use mingo
+#   Mince::Config.interface = Mince::Mingo::Interface
+#
+# Done. Now we can simply start the ruby server and develop away.
+#
+# @author Matt Simpson
+module Mince
+  # Load all mince libraries
+  require_relative 'mince/version'
+  require_relative 'mince/config'
+  require_relative 'mince/data_model'
+  require_relative 'mince/model'
+end

data/spec/integration/simple_mince_data_model_spec.rb

@@ -0,0 +1,55 @@
+require 'mince'
+require 'hashy_db'
+
+describe 'A simple mince data model integration spec' do
+  before do
+    Mince::Config.interface = Mince::HashyDb::Interface
+    Mince::HashyDb::Interface.clear
+  end
+
+  after do
+    Mince::HashyDb::Interface.clear
+  end
+
+  describe 'a model' do
+    subject { model_klass.new attributes }
+
+    let(:model_klass) do
+      Class.new do
+        include Mince::Model
+
+        data_model(
+          Class.new do
+            include Mince::DataModel
+
+            data_collection :guitars
+            data_fields :brand, :price, :type, :color
+          end
+        )
+        fields :brand, :price, :type, :color
+      end
+    end
+
+    let(:attributes) { { brand: brand, price: price, type: type, color: color } }
+    let(:brand) { mock }
+    let(:price) { mock }
+    let(:type) { mock }
+    let(:color) { mock }
+
+    it 'is initialized with the correct data' do
+      subject.brand.should == brand
+      subject.price.should == price
+      subject.type.should == type
+      subject.color.should == color
+    end
+
+    it 'can be persisted to the mince data interface' do
+      subject.save
+
+      raw_record = Mince::Config.interface.find(:guitars, Mince::HashyDb::Interface.primary_key, subject.id)
+      model_record = model_klass.find(subject.id)
+      raw_record[:brand].should == brand
+      model_record.brand.should == brand
+    end
+  end
+end

data/spec/units/mince/data_model_spec.rb

@@ -0,0 +1,228 @@
+require_relative '../../../lib/mince/data_model'
+require 'digest'
+
+describe Mince::DataModel, 'Mixin' do
+  let(:described_class) { klass }
+
+  let(:collection_name) { :guitars }
+  let(:data_field_attributes) do
+    {
+            brand: 'a brand everyone knows',
+            price: 'a price you save up for',
+            type: 'the kind you want',
+            color: 'should be your favorite'
+    }
+  end
+
+  let(:klass) do
+    Class.new do
+      include Mince::DataModel
+
+      data_collection :guitars
+      data_fields :brand, :price, :type, :color
+    end
+  end
+
+  let(:interface) { mock 'mince data interface class', generate_unique_id: unique_id, primary_key: primary_key }
+  let(:unique_id) { mock 'id' }
+  let(:primary_key) { "custom_id" }
+
+  before do
+    Mince::Config.stub(:interface => interface)
+  end
+
+  describe "storing a data model" do
+    let(:model) { mock 'a model', instance_values: data_field_attributes }
+
+    before do
+      interface.stub(:add)
+    end
+
+    it 'generates a unique id using the model as a salt' do
+      interface.should_receive(:generate_unique_id).with(model).and_return(unique_id)
+
+      described_class.store(model)
+    end
+
+    it 'adds the data model to the db store' do
+      interface.should_receive(:add).with(collection_name, HashWithIndifferentAccess.new({primary_key => unique_id}).merge(data_field_attributes))
+
+      described_class.store(model)
+    end
+  end
+
+  it 'can delete the collection' do
+    interface.should_receive(:delete_collection).with(collection_name)
+    
+    described_class.delete_collection
+  end
+
+  it 'can delete a field' do
+    field = mock 'field to delete from the collection'
+
+    interface.should_receive(:delete_field).with(collection_name, field)
+
+    described_class.delete_field(field)
+  end
+
+  it 'can delete records by a given set of params' do
+    params = mock 'params that provide a condition of what records to delete from the collection'
+
+    interface.should_receive(:delete_by_params).with(collection_name, params)
+
+    described_class.delete_by_params(params)
+  end
+
+  describe "updating a data model" do
+    let(:data_model_id) { '1234567' }
+    let(:model) { mock 'a model', id: data_model_id, instance_values: data_field_attributes }
+
+    before do
+      interface.stub(:replace)
+    end
+
+    it 'replaces the data model in the db store' do
+      interface.should_receive(:replace).with(collection_name, HashWithIndifferentAccess.new({primary_key => data_model_id}).merge(data_field_attributes))
+
+      described_class.update(model)
+    end
+  end
+
+  describe 'updating a specific field for a data model' do
+    let(:data_model_id) { '1234567' }
+    
+    it 'has the data store update the field' do
+      interface.should_receive(:update_field_with_value).with(collection_name, data_model_id, :some_field, 'some value')
+
+      described_class.update_field_with_value(data_model_id, :some_field, 'some value')
+    end
+  end
+
+  describe 'incrementing a specific field by a given an amount' do
+    let(:data_model_id) { mock 'id' }
+
+    it 'has the data store update the field' do
+      interface.should_receive(:increment_field_by_amount).with(collection_name, data_model_id, :some_field, 4)
+
+      described_class.increment_field_by_amount(data_model_id, :some_field, 4)
+    end
+  end
+
+  describe "pushing a value to an array for a data model" do
+    let(:data_model_id) { '1234567' }
+
+    it 'replaces the data model in the db store' do
+      interface.should_receive(:push_to_array).with(collection_name, primary_key, data_model_id, :array_field, 'some value')
+
+      described_class.push_to_array(data_model_id, :array_field, 'some value')
+    end
+  end
+
+  describe "getting all data models with a specific value for a field" do
+    let(:data_model) { {primary_key => 'some id'} }
+    let(:expected_data_models) { [HashWithIndifferentAccess.new({:id => 'some id', primary_key => 'some id'})] }
+    let(:data_models) { [data_model] }
+    subject { described_class.array_contains(:some_field, 'some value') }
+
+    it 'returns the stored data models with the requested field / value' do
+      interface.should_receive(:array_contains).with(collection_name, :some_field, 'some value').and_return(data_models)
+
+      subject.should == expected_data_models
+    end
+  end
+
+  describe "removing a value from an array for a data model" do
+    let(:data_model_id) { '1234567' }
+
+    it 'removes the value from the array' do
+      interface.should_receive(:remove_from_array).with(collection_name, primary_key, data_model_id, :array_field, 'some value')
+
+      described_class.remove_from_array(data_model_id, :array_field, 'some value')
+    end
+  end
+
+  describe 'getting all of the data models' do
+    let(:data_model) { {primary_key => 'some id'} }
+    let(:expected_data_models) { [HashWithIndifferentAccess.new({:id => 'some id', primary_key => 'some id'})] }
+    let(:data_models) { [data_model] }
+
+    it 'returns the stored data models' do
+      interface.should_receive(:find_all).with(collection_name).and_return(data_models)
+
+      described_class.all.should == expected_data_models
+    end
+  end
+
+  describe "getting all the data fields by a parameter hash" do
+    let(:data_model) { {primary_key => 'some id'} }
+    let(:expected_data_models) { [{:id => 'some id', primary_key => 'some id'}] }
+    let(:data_models) { [data_model] }
+    let(:expected_data_models) { [HashWithIndifferentAccess.new(data_model)] }
+
+    it 'passes the hash to the interface_class' do
+      interface.should_receive(:get_all_for_key_with_value).with(collection_name, :field2, 'not nil').and_return(data_models)
+
+      described_class.all_by_field(:field2, 'not nil').should == expected_data_models
+    end
+  end
+
+  describe "getting a record by a set of key values" do
+    let(:data_model) { {primary_key => 'some id'} }
+    let(:data_models) { [data_model] }
+    let(:expected_data_models) { [{:id => 'some id', primary_key => 'some id'}] }
+
+    let(:sample_hash) { {field1: nil, field2: 'not nil'} }
+
+    it 'passes the hash to the interface_class' do
+      interface.should_receive(:get_by_params).with(collection_name, sample_hash).and_return(data_models)
+
+      described_class.find_by_fields(sample_hash).should == HashWithIndifferentAccess.new(expected_data_models.first)
+    end
+  end
+
+  describe "getting all of the data models for a where a field contains any value of a given array of values" do
+    let(:data_models) { [{primary_key => 'some id'}, {primary_key => 'some id 2'}] }
+    let(:expected_data_models) { [{"id" => 'some id', primary_key => 'some id'}, {"id" => 'some id 2', primary_key => 'some id 2'}] }
+
+    subject { described_class.containing_any(:some_field, ['value 1', 'value 2']) }
+
+    it 'returns the stored data models' do
+      interface.should_receive(:containing_any).with(collection_name, :some_field, ['value 1', 'value 2']).and_return(data_models)
+
+      subject.should == expected_data_models
+    end
+  end
+
+  describe "getting a record by a key and value" do
+    let(:data_model) { {primary_key => 'some id'} }
+    let(:expected_data_model) { {:id => 'some id', primary_key => 'some id'} }
+
+    it 'returns the correct data model' do
+      interface.should_receive(:get_for_key_with_value).with(collection_name, :field2, 'not nil').and_return(data_model)
+
+      described_class.find_by_field(:field2, 'not nil').should == HashWithIndifferentAccess.new(expected_data_model)
+    end
+  end
+
+  describe "getting all data models with a specific value for a field" do
+    let(:data_models) { [{primary_key => 'some id'}, {primary_key => 'some id 2'}] }
+    let(:expected_data_models) { [HashWithIndifferentAccess.new({:id => 'some id', primary_key => 'some id'}), HashWithIndifferentAccess.new({id: 'some id 2', primary_key => 'some id 2'})] }
+    subject { described_class.all_by_field(:some_field, 'some value') }
+
+    it 'returns the stored data models with the requested field / value' do
+      interface.should_receive(:get_all_for_key_with_value).with(collection_name, :some_field, 'some value').and_return(data_models)
+
+      subject.should == expected_data_models
+    end
+  end
+
+  describe 'getting a specific data model' do
+    let(:data_model) { {primary_key => 'id', :id => 'id' } }
+
+    it 'returns the data model from the data store' do
+      interface.should_receive(:find).with(collection_name, primary_key, 'id').and_return(data_model)
+
+      described_class.find(data_model[:id]).should == HashWithIndifferentAccess.new(data_model)
+    end
+  end
+end

data/spec/units/mince/model_spec.rb

@@ -0,0 +1,128 @@
+require_relative '../../../lib/mince/model'
+
+describe Mince::Model do
+  let(:klass) do
+    Class.new do
+      include Mince::Model
+
+      data_model Class.new
+
+      field :meh
+      field :foo, assignable: true
+      field :bar, assignable: false
+      fields :baz, :qaaz
+    end
+  end
+
+  let(:meh) { mock 'meh' }
+  let(:foo) { mock 'foo' }
+  let(:bar) { mock 'bar' }
+  let(:baz) { mock 'baz' }
+  let(:qaaz) { mock 'qaaz' }
+
+  subject { klass.new(meh: meh, foo: foo, bar: bar, baz: baz, qaaz: qaaz) }
+
+  it 'initializes the object and assigns values to the fields' do
+    subject.meh.should == meh
+    subject.foo.should == foo
+    subject.bar.should == bar
+    subject.baz.should == baz
+    subject.qaaz.should == qaaz
+  end
+
+  it 'can set the assignable fields outside of the initilizer' do
+    subject.foo = 'foo1'
+    subject.foo.should == 'foo1'
+    subject.attributes = { foo: 'foo2' }
+    subject.foo.should == 'foo2'
+  end
+
+  it 'cannot set the readonly field outside of the initilizer' do
+    subject.attributes = { bar: 'bar1' }
+    subject.bar.should == bar
+  end
+
+  it 'fields are readonly by default' do
+    subject.attributes = { meh: 'meh1' }
+    subject.meh.should == meh
+  end
+
+  describe 'saving' do
+    let(:id) { mock 'id' }
+    let(:data_fields) { subject.fields }
+
+    before do
+      subject.data_model.stub(:data_fields).and_return(data_fields)
+    end
+
+    context 'when the model has fields that are not defined in the data model' do
+      let(:data_fields) { subject.fields - extra_fields }
+      let(:extra_fields) { subject.fields[0..-2] }
+
+      it 'raises an exception with a message' do
+        expect { subject.save }.to raise_error("Tried to save a #{subject.class.name} with fields not specified in #{subject.data_model.name}: #{extra_fields.join(', ')}")
+      end
+    end
+
+    context 'when it has not yet been persisted to the mince data model' do
+      before do
+        subject.data_model.stub(:store => id)
+      end
+
+      it 'stores the model' do
+        subject.data_model.should_receive(:store).with(subject).and_return(id)
+
+        subject.save
+      end
+
+      it 'assigns the id' do
+        subject.save
+
+        subject.id.should == id
+      end
+    end
+
+    context 'when it has already been persisted to the mince data model' do
+      let(:subject) { klass.new(id: id) }
+
+      it 'updates the model' do
+        subject.data_model.should_receive(:update).with(subject)
+
+        subject.save
+      end
+    end
+  end
+
+  describe "Query Methods:" do
+    describe 'finding a model by id' do
+      subject { klass.find(id) }
+
+      let(:id) { mock 'id' }
+
+      before do
+        klass.data_model.stub(:find).with(id).and_return(data)
+      end
+
+      context 'when it exists' do
+        let(:data) { mock 'data' }
+        let(:model) { mock 'model' }
+
+        before do
+          klass.stub(:new).with(data).and_return(model)
+        end
+
+        it 'returns the model' do
+          subject.should == model
+        end
+      end
+
+      context 'when it does not exist' do
+        let(:data) { nil }
+
+        it 'returns nothing' do
+          subject.should be_nil
+        end
+      end
+    end
+  end
+end