brainstem 0.0.2

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in brainstem.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: .
+  specs:
+    brainstem (0.0.2)
+      activerecord (~> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.2.13)
+      activesupport (= 3.2.13)
+      builder (~> 3.0.0)
+    activerecord (3.2.13)
+      activemodel (= 3.2.13)
+      activesupport (= 3.2.13)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.13)
+      i18n (= 0.6.1)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.4)
+    diff-lcs (1.2.2)
+    i18n (0.6.1)
+    multi_json (1.7.2)
+    rake (10.0.4)
+    redcarpet (2.2.2)
+    rr (1.0.5)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    sqlite3 (1.3.7)
+    tzinfo (0.3.37)
+    yard (0.8.5.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  brainstem!
+  rake
+  redcarpet
+  rr
+  rspec
+  sqlite3
+  yard

data/Guardfile

@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Mavenlink, Inc.
+
+MIT License
+
+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,181 @@
+# Brainstem
+
+Brainstem is designed to power rich APIs in Rails. The Brainstem gem provides a presenter library that handles converting ActiveRecord objects into structured JSON and a set of API abstractions that allow users to request sorts, filters, and association loads, allowing for simpler implementations, fewer requests, and smaller responses.
+
+## Why Brainstem?
+
+* Seperate business and presentation logic with Presenters.
+* Version your Presenters for consistency as your API evolves.
+* Expose end-user selectable filters and sorts.
+* Whitelist your existing scopes to act as API filters for your users.
+* Allow users to side-load multiple objects, with their associations, in a single request, reducing the number of requests needed to get the job done.  This is especially helpful for building speedy mobile applications.
+* Prevent data duplication by pulling associations into top-level hashes, easily indexable by ID.
+* Easy integration with Backbone.js.  "It's like Ember Data for Backbone.js!"
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'brainstem'
+
+## Usage
+
+Create a class that inherits from Brainstem::Presenter, named after the model that you want to present, and preferrably versioned in a module. For example:
+
+    module Api
+	  module V1
+	    class WidgetPresenter < Brainstem::Presenter
+	      presents "Widget"
+	
+	      # Available sort orders to expose through the API
+	      sort_order :updated_at, "widgets.updated_at"
+	      sort_order :created_at, "widgets.created_at"
+	
+	      # Default sort order to apply
+	      default_sort_order "updated_at:desc"
+	
+	      # Optional filter that delegates to the Widget model :popular scope, 
+	      # which should take one argument of true or false.
+	      filter :popular
+	
+	      # Optional filter that applies a lambda.
+	      filter :location_name do |scope, location_name|
+	        scope.joins(:locations).where("locations.name = ?", location_name)
+	      end
+	
+	      # Filter with an overridable default that runs on all requests.
+	      filter :include_legacy_widgets, :default => false do |scope, bool|
+	        bool ? scope : scope.without_legacy_widgets
+	      end
+	
+	      # Return a ruby hash that can be converted to JSON
+	      def present(widget)
+	        {
+	            :name           => widget.name,
+	            :legacy         => widget.legacy?,
+	            :updated_at     => widget.updated_at,
+	            :created_at     => widget.created_at,
+	            # Associations can be included by request
+	            :features       => association(:features),
+	            :location       => association(:location)
+	        }
+	      end
+	    end
+	  end
+	end
+
+Once you've created a presenter like the one above, pass requests through from your controller.
+
+    class Api::WidgetsController < ActionController::Base
+      include Brainstem::ControllerMethods
+
+      def index
+        render :json => present("widgets") { Widgets.visible_to(current_user) }
+      end
+    end
+
+The scope passed to `present` could contain any starting conditions that you'd like.  Requests can have includes, filters, and sort orders.
+
+    GET /api/widgets.json?include=features&sort_order=popularity:desc&location_name=san+francisco
+
+Responses will look like the following:
+
+    {
+      # Total number of results that matched the query.
+      count: 5,
+      
+      # A lookup table to top-level keys.  Necessary
+      # because some objects can have associations of
+      # the same type as themselves.
+      results: [
+        { key: "widgets", id: "2" },
+        { key: "widgets", id: "10" }
+      ],
+      
+      # Serialized models with any requested associations, keyed by ID.
+
+      widgets: {
+        "10": {
+          id: "10",
+          name: "disco ball",
+          feature_ids: ["5"],
+          popularity: 85,
+          location_id: "2"
+        },
+        
+        "2": {
+       	  id: "2",
+       	  name: "flubber",
+       	  feature_ids: ["6", "12"],
+       	  popularity: 100,
+       	  location_id: "2"
+       	}
+      },
+
+      features: {
+        "5": { id: "5", name: "shiny" },
+        "6": { id: "6", name: "bouncy" },
+        "12": { id: "12", name: "physically impossible" }
+      }
+    }
+
+You may want to setup an initializer in `config/initializers/brainstem.rb` like the following:
+
+    Brainstem.default_namespace = :v1
+ 
+    module Api
+	  module V1
+	    module Helper
+	      def current_user
+	        # However you get your current user.
+	      end
+	    end
+	  end
+	end
+	Brainstem::Presenter.helper(Api::V1::Helper)
+	
+	require 'api/v1/widget_presenter'
+	require 'api/v1/feature_presenter'
+	require 'api/v1/location_presenter'
+	# ...
+	
+	# Or you could do something like this:
+	#  Dir[Rails.root.join("lib/api/v1/*_presenter.rb").to_s].each { |p| require p }
+
+For more detailed examples, please see the documentation for methods on {Brainstem::Presenter} and our detailed [Rails example application](https://github.com/mavenlink/brainstem-demo-rails).
+
+## Consuming a Brainstem API
+
+APIs presented with Brainstem are just JSON APIs, so they can be consumed with just about any language.  As Brainstem evolves, we hope that people will contributed consumption libraries in various languages.
+
+### The Results Array
+
+    {
+      results: [
+        { key: "widgets", id: "2" }, { key: "widgets", id: "10" }
+      ],
+      
+      widgets: {
+        "10": {
+          id: "10",
+          name: "disco ball",
+          …
+
+
+Brainstem returns objects as top-level hashes and provides a `results` array of `key` and `id` objects for finding the returned data in those hashes.  The reason that we use the `results` array is two-fold: 1st) it provides order outside of the serialized objects so that we can provide objects keyed by ID, and 2nd) it allows for polymorphic responses and for objects that have associations of their own type (like posts and replies or tasks and sub-tasks).
+
+### Brainstem and Backbone.js
+
+If you're already using Backbone.js, integrating with a Brainstem API is super simple.  Just use the [Brainstem.js](https://github.com/mavenlink/brainstem-js) gem (or its JavaScript contents) to access your relational Brainstem API from JavaScript.
+
+## Contributing
+
+1. Fork Brainstem or Brainstem.js
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request (`git pull-request`)
+
+## License
+
+Brainstem and Brainstem.js were created by Mavenlink, Inc. and are available under the MIT License.

data/Rakefile

@@ -0,0 +1,6 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/brainstem.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require "brainstem/version"
+
+Gem::Specification.new do |gem|
+  gem.name          = "brainstem"
+  gem.authors       = ["Sufyan Adam", "André Arko", "Andrew Cantino", "Katlyn Daniluk", "Reid Gillette"]
+  gem.email         = ["dev@mavenlink.com"]
+  gem.description   = %q{Brainstem allows you to create rich API presenters that know how to filter, sort, and include associations.}
+  gem.summary       = %q{ActiveRecord presenters with a rich request API}
+  gem.homepage      = "http://developer.mavenlink.com"
+  gem.license       = "MIT"
+
+  gem.files         = Dir["**/*"]
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  gem.version       = Brainstem::VERSION
+
+  gem.add_dependency "activerecord", "~> 3.0"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "redcarpet" # for markdown in yard
+  gem.add_development_dependency "rr"
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "sqlite3"
+  gem.add_development_dependency "yard"
+end

data/lib/brainstem.rb

@@ -0,0 +1,63 @@
+require "brainstem/version"
+require "brainstem/presenter"
+require "brainstem/presenter_collection"
+require "brainstem/controller_methods"
+
+# The Brainstem module itself contains a +default_namespace+ class attribute and a few helpers that make managing +PresenterCollections+ and their corresponding namespaces easier.
+module Brainstem
+
+  # Sets {default_namespace} to a new value.
+  # @param [String] namespace
+  # @return [String] the new default namespace
+  def self.default_namespace=(namespace)
+    @default_namespace = namespace
+  end
+
+  # The namespace that will be used by {presenter_collection} and {add_presenter_class} if none is given or implied.
+  # @return [String] the default namespace
+  def self.default_namespace
+    @default_namespace || "none"
+  end
+
+  # @param [String] namespace
+  # @return [PresenterCollection] the {PresenterCollection} for the given namespace.
+  def self.presenter_collection(namespace = nil)
+    namespace ||= default_namespace
+    @presenter_collection ||= {}
+    @presenter_collection[namespace.to_s.downcase] ||= PresenterCollection.new
+  end
+
+  # Helper method to quickly add presenter classes that are in a namespace. For example, +add_presenter_class(Api::V1::UserPresenter, "User")+ would add +UserPresenter+ to the PresenterCollection for the +:v1+ namespace as the presenter for the +User+ class.
+  # @param [Brainstem::Presenter] presenter_class The presenter class that is being registered.
+  # @param [Array<String, Class>] klasses Classes that will be presented by the given presenter.
+  def self.add_presenter_class(presenter_class, *klasses)
+    presenter_collection(namespace_of(presenter_class)).add_presenter_class(presenter_class, *klasses)
+  end
+
+  # @param [Class] klass The Ruby class whose namespace we would like to know.
+  # @return [String] The name of the module containing the passed-in class.
+  def self.namespace_of(klass)
+    names = klass.to_s.split("::")
+    names[-2] ? names[-2] : default_namespace
+  end
+
+  # @return [Logger] The Brainstem logger. If Rails is loaded, defaults to the Rails logger. If Rails is not loaded, defaults to a STDOUT logger.
+  def self.logger
+    @logger ||= begin
+      if defined?(Rails)
+        Rails.logger
+      else
+        require "logger"
+        Logger.new(STDOUT)
+      end
+    end
+  end
+
+  # Sets a new Brainstem logger.
+  # @param [Logger] logger A new Brainstem logger.
+  # @return [Logger] The new Brainstem logger.
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+end

data/lib/brainstem/association_field.rb

@@ -0,0 +1,35 @@
+module Brainstem
+  # AssociationField acts as a standin for associations.
+  # @api private
+  class AssociationField
+    # @!attribute [r] method_name
+    # @return [Symbol] The name of the method that is being proxied.
+    attr_reader :method_name
+
+    # @!attribute [r] json_name
+    # @return [Symbol] The name of the top-level JSON key for objects provided by this association.
+    attr_accessor :json_name
+
+    # @param method_name The name of the method being proxied. Not required if
+    #   a block is passed instead.
+    # @option options [Boolean] :json_name The name of the top-level JSON key for objects provided by this association.
+    def initialize(method_name = nil, options = {}, &block)
+      @json_name = options[:json_name]
+      if block_given?
+        raise ArgumentError, "Method name is invalid with a block" if method_name
+        @block = block
+      elsif method_name
+        @method_name = method_name
+      else
+        raise ArgumentError, "Method name or block is required"
+      end
+    end
+
+    # Call the method or block being proxied.
+    # @param model The object to call the proxied method on.
+    # @return The value returned by calling the method or block being proxied.
+    def call(model)
+      @block ? @block.call : model.send(@method_name)
+    end
+  end
+end

data/lib/brainstem/controller_methods.rb

@@ -0,0 +1,44 @@
+module Brainstem
+
+  # ControllerMethods are intended to be included into controllers that will be handling requests for presented objects.
+  # The present method will pass through +params+, so that any allowed and requested includes, filters, sort orders
+  # will be applied to the presented data.
+  module ControllerMethods
+
+    # Return a Ruby hash that contains models requested by the user's params and allowed
+    # by the +name+ presenter's configuration.
+    #
+    # Pass the returned hash to the render method to convert it into a useful format.
+    # For example:
+    #    render :json => present("post"){ Post.where(:draft => false) }
+    # @param (see PresenterCollection#presenting)
+    # @option options [String] :namespace ("none") the namespace to be presented from
+    # @yield (see PresenterCollection#presenting)
+    # @return (see PresenterCollection#presenting)
+    def present(name, options = {}, &block)
+      Brainstem.presenter_collection(options[:namespace]).presenting(name, options.reverse_merge(:params => params), &block)
+    end
+
+    # Similar to ControllerMethods#present, but always returns all of the given objects, not just those that match any provided
+    # filters.
+    # @option options [String] :namespace ("none") the namespace to be presented from
+    # @option options [Hash]   :key_map a Hash from Class name to json key name, if desired.
+    #                           e.g., map 'SystemWidgets' objects to the 'widgets' key in the JSON.  This is
+    #                           only required if the name cannot be inferred.
+    # @return (see PresenterCollection#presenting)
+    def present_object(objects, options = {})
+      options.reverse_merge(:params => params)
+      if objects.is_a?(ActiveRecord::Relation) || objects.is_a?(Array)
+        raise ActiveRecord::RecordNotFound if objects.empty?
+        klass = objects.first.class
+        ids = objects.map(&:id)
+      else
+        klass = objects.class
+        ids = objects.id
+      end
+      json_key = (options[:key_map] || {})[klass.to_s] || klass.table_name
+      present(klass, :as => json_key, :apply_default_filters => false){ klass.where(:id => ids) }
+    end
+    alias_method :present_objects, :present_object
+  end
+end