Skip to content
This repository has been archived by the owner on Nov 8, 2017. It is now read-only.

Latest commit

 

History

History
148 lines (99 loc) · 5.17 KB

README.md

File metadata and controls

148 lines (99 loc) · 5.17 KB

Collector

Build Status Code Climate

Collector is an implementation of the Repository Pattern for MongoDB. For those new to the Repository Pattern, it is a Facade that isolates the persistence layer from your application. If you're familiar with Rails, or more specifically ActiveRecord or most other ORMs, you'll know that the models and persistence layer are tightly coupled—literally they are the same object. That pattern is a great way to cut your teeth, but ultimately it's a terrible design. Your application does not and should not care about how its data is persisted. Collector will help with that.

Collector is currently under initial development, and I mean that in the context of semantic versioning, which I follow. Initial development is anything with a major version of zero (0.x.x), which means anything may change at any time; there is no public API. I'll do my best not to wildly change anything, but if you upgrade, run your application tests to see if anything breaks. If you don't have application tests then you have failed. Go home and re-think your life choices that have brought you to this point.

Installation

Add this line to your application's Gemfile:

gem "collector"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install collector

Usage

Configuration

Set up a connection.

Collector.connection = Mongo::Connection.new

Models

Include Collector::Model in your domain objects to turn them into models. Create accessors for any attributes. Accessors for id, created_at, and updated_at are created automatically.

class Pickle

  include Collector::Model

  attr_accessor :brine, :started_at

end

Models can be instantiated with a hash of attributes.

Pickle.new(brine: "vinegar", started_at: Time.now)

Models automatically create and update timestamps for created_at and updated_at.

Repositories

Include Collector::Repository in an object to turn it into a repository for a model of the same name. Use the same inflection as your model's name (singular).

class PickleRepository

  include Collector::Repository

end

Repositories can save models.

pickle = Pickle.new(brine: "vinegar", started_at: Time.now)
PickleRepository.save(pickle)

Repositories can find all models, find by id, find dynamically by any attribute, and then find first by id or any other attribute.

PickleRepository.all
PickleRepository.find_by_id(BSON::ObjectId("50af1f3fb392d4aa0d000001"))
PickleRepository.find_by_color("green")
PickleRepository.find_by_taste("delicious")
PickleRepository.find_first_by_id(BSON::ObjectId("50af1f3fb392d4aa0d000001"))
PickleRepository.find_first_by_color("green")
PickleRepository.find_first_by_taste("delicious")

Repositories can delete models.

pickle = Pickle.new(brine: "vinegar", started_at: Time.now)
PickleRepository.save(pickle)
PickleRepository.delete(pickle)

Requirements

Collector will only work with 1.9.x and above. Specifically it's tested with 1.9.2 and 1.9.3.

FAQ

What databases does it support?

Currently only MongoDB. I'd like to add an in-memory store, and if possible, a file store and Redis store.

Why is this better than an ORM?

If you don't already know why you need or want the Repository Pattern, then don't use it yet. It took me far longer than it should have to realize the benefits, despite having them explained to me many times. I just never really understood them until I'd actually experienced the pain this pattern solves myself. Once you do, come back and try it out.

This looks awfully similar to curator. What's the difference?

I rolled my own application-specific version of the Repository Pattern for each project I worked on before I realized I was using it often enough to merit extracting it into a gem. Right about that time Braintree announced curator, and since both their implentation and mine were very similar—except theirs was further along and had more features—I decided to use theirs instead. But after using it for a few months and then reading through the code to try and contribute back to it, I decided to go back to my own implementation and extract it into a gem after all.

The specific, functional differences are:

<tr>
  <td>curator</td>
  <td>MongoDB, Riak, In-memory</td>
  <td>RSpec</td>
  <td>1.9.x, 1.8.7</td>
</tr>
Project Stores Test suite Ruby version(s)
collector MongoDB MiniTest 1.9.x

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request