shapeable 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ed1e8139b673601f51a5a4a95830670945710d4
-  data.tar.gz: 013a597aba452cc63d267909298c84e7ee027449
+  metadata.gz: f6950ec9d5f7b64533f0f5eb8a6b0cc8b9f20bd3
+  data.tar.gz: edc0ef5b43d1a8e3ddd1277ae000bfff82cb9407
 SHA512:
-  metadata.gz: 7e3babc9c59f8fb1ee8a8e9a6825d83ff29f6afc93ef9ef546a526170e2cd728cd33d3b3bd52ce4136294eb62701486d9fad02ba5330e9bda3f19be8c3ba5b54
-  data.tar.gz: 4990746ce0a05398bf8ab340147fc1158fee3a92c5215d85bcfb1f659a6ed452e646f89235f1bf55617d732bd3f58b1771c3f61b0cc8a36777f829ae9ddab661
+  metadata.gz: d5330318952bc212e50be07ac8a31defb8362b54dc595ba9f89bf5854444d473bfb79ba981680990c525af0394752f6eb5ebf12052132370988abbef5224f8da
+  data.tar.gz: 2532a733031bfe3f58c77a85bc761fe8fed6a961c2affeecc5a2bc4e681df830d89469cb15db6b853701c6c3fde58893580e00f2e917663c900b8a2682687071

data/Gemfile

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

data/README.md

@@ -5,7 +5,7 @@ API versioning that promotes convention over configuration.
 The premise of this gem is that consumers of your API need versioning and different shapes of your resources. Without proper thought into versioning and shaping, your codebase can quickly resolve into a redundant and confusing state. This gem tries to solve that problem by allowing the API owner to use simple conventions -- Accept headers and ActiveModelSerializer namespacing -- to achieve controller reuse by controllers delegating resource versioning and shaping to the serializer level.
 
 
-## example
+## Example
 
 
 Let's say we have a resource of type `Foo` and `foos_controller.rb` that includes our gem and has a `show` action:
@@ -21,43 +21,90 @@ class FoosController < ActionController::Base
 end
 ```
 
-A client on v1 would like a list of `foos` in short form:
+Assume we have the following `ActiveModelSerializer` directory structure:
+
+```
+app
+  serializers
+    foo
+      v1
+        foo_short_serializer.rb
+        foo_full_serializer.rb
+      v2
+        foo_full_serializer.rb
+        foo_serializer.rb
+```
 
+Inside our controller we can reference the `shape` method, which returns the serializer constant. The top level module path in which the serializer can be found must be specified using the `path` option on either the `acts_as_shapeable`, or the `shape` method. In this case it would be `Serializers::Foo`. If the path is not specified either in `acts_as_shapeable` or `shape`, then calling `shape` will raise an `ArgumentError`.
+
+Now say we have several clients, each expecting a different serialized response.
+
+A client on v1 would like a list of `foos` in short form:
 `curl http://localhost:3000/foos -H 'Accept: application/javascript; version=1 shape=short'`
 
-A client on v2 would like a list of `foos` in short form:
+When we reference `shape` inside the controller, it returns the following constant: `Serializers::Foo::V1::FooShortSerializer`
+
 
+A client on v2 would like a list of `foos` in short form:
 `curl http://localhost:3000/foos -H 'Accept: application/javascript; version=2 shape=short'`
 
-A client on v1 would like a list of `foos` in full form:
+When we reference `shape` inside the controller, it returns the following constant: `Serializers::Foo::V2::FooShortSerializer`
+
 
+A client on v1 would like a list of `foos` in full form:
 `curl http://localhost:3000/foos -H 'Accept: application/javascript; version=1 shape=full'`
 
-A client on v2 would like a list of `foos` in default form, in this case short:
+When we reference `shape` inside the controller, it returns the following constant: `Serializers::Foo::V1::FooFullSerializer`
 
+
+## Configuring Defaults
+
+Both `acts_as_shapeable` and `shape` accept the following arguments:
+
+* `default_version`: The default version in cases where the header is not specified.
+* `default_shape`: The deafault shape in cases where the shape is not specified.
+
+The options defined on `shape` have greater precedence over those defined on `acts_as_shapeable`.
+
+In cases where the version and/or the shape is not specified in the Accept Header Shapeable will instead use the provided defaults. If no default is provided, and nothing is specified in the header, Shapeable will raise an `UnresolvedShapeError`.
+
+Using the same example controller and directory structure from above, a client sends no headers:
 `curl http://localhost:3000/foos -H 'Accept: application/javascript;`
+Shapeable uses the defaults provided, and resolves `shape` to the following constant: `Serializers::Foo::V1::FooShortSerializer`
 
-Assuming we have the following ActiveModelSerializer directory structure, we wouldn't have to change the above controller at all to fulfill these requests:
 
-```
-app
-  serializers
-    foo
-      v1
-        foo_short_serializer.rb
-        foo_full_serializer.rb
-      v2
-        foo_full_serializer.rb
-        foo_serializer.rb
+Shapeable can also be configured with a global configuration file. All options which can be passed to `acts_as_shapeable` and `shape` can also be configured using this method. Configuration options inside the config file have the lowest precedence.
+
+You can configure shapeable by passing in all configuration options(`default_version`, `default_shape`, and `path`), to `Shapeable.configure` in block format. One approach is to put this in a config file that lives at `config/shapeable.rb`.
+
+```Ruby
+# config/shapeable.rb
+Shapeable.configure do |config|
+  config.default_version = 1
+  config.default_shape = 'default'
+  config.path = Serializers::Bar
+end
 ```
 
+## Enforce Versioning and Shaping
 
-The `shape` method returns the serializer constant.
+There are a few additional options which allow you to decide whether you want to enforce version or shape.
 
-Both `acts_as_shapeable` and `shape` accept the following arguments:
+`enforce_versioning`, and `enforce_shape` can be passed to `Shapeable.configure`. By default both are set to true.
+
+When `enforce_versioning` is set to false, version will be ignored, and the version module will not be prepended. So the following request
+
+`curl http://localhost:3000/foos -H 'Accept: application/javascript; shape=default'`
+
+Will be constructed as `Serializers::Foo::FooDefaultSerializer` without the version module prepended.
+
+When `enforce_shape` is set to false, shape will be optional. When shape is not specified, the constant will be constructed with no shape. So the following request:
+
+`curl http://localhost:3000/foos -H 'Accept: application/javascript; version=1'`
+
+Will be constructed as `Serializers::Foo::V1::FooSerializer`.
 
-* `path`: The top level module where the serializers are defined
-* `default_version`: The default version in cases where the header is not specified
-* `default_shape`: The deafault shape in cases where the shape is not specified
+## Gotchas
 
-All three options must be defined either on `acts_as_shapeable` or `shape`. The options defined on `shape` have greater precedence than those on `acts_as_shapeable`.
+* Shapeable infers the resource name from the path. Specifically it expects that the last constant in the path is the resource. So in the case of `acts_as_shapeable(path: Serializers::Foo)` Shapeable assumes that the resource is `Foo`.
+* If we want a shape of `FooSerializer` we must specify a default_shape of `''` (empty string).

data/lib/shapeable.rb

@@ -1,49 +1,37 @@
 require 'shapeable/version'
+require 'shapeable/configuration'
+require 'shapeable/shape'
+require 'shapeable/errors'
+require 'shapeable/extenders'
 
 module Shapeable
-
-  def acts_as_shapeable(**opts)
-
-    normalize_shapeable_options(opts)
-    acts_as_shapeable_opts = opts || {}
-
-    define_method(:shape) do |opts={}|
-      opts = acts_as_shapeable_opts.merge(opts)
-      default_shape = opts[:default_shape]
-      default_version = opts[:default_version]
-      path = opts[:path]
-      raise ArgumentError, "Specify a path" unless path
-      resource = path.name.split('::').last.constantize
-      if request.accept
-        version_str = request.accept[/version\s?=\s?(\d+)/, 1]
-        version = version_str.nil? ? default_version : version_str.to_i
-        shape = request.accept[/shape\s?=\s?(\w+)/, 1] || default_shape
-        raise UnresolvedShapeError, "Unable to resolve shape. Try specifying a default version and shape" unless version && shape
-        begin
-          serializer = path.const_get("V#{version}").const_get("#{resource}#{shape.camelize}Serializer")
-        rescue NameError
-          raise InvalidShapeError, "Invalid shape. Tried to find version #{version} with shape #{shape}"
+  CONFIG_FILE = './config/shapeable.rb'
+
+  class << self
+    attr_accessor :configuration_data
+
+    def configure(file = nil)
+      configuration
+      if block_given?
+        yield(configuration)
+      else
+        if File.exists?(CONFIG_FILE)
+          file ||= CONFIG_FILE
+          require file
+        else
+          raise ArgumentError, "Configure requires a block or the existance of a #{CONFIG_FILE} in your project"
         end
       end
-      serializer
     end
-  end
 
-  private
-
-  def normalize_shapeable_options(opts)
-    opts.keep_if do |k, _v|
-      [:path, :default_shape, :default_version].include?(k)
+    def configuration
+      self.configuration_data ||= Shapeable::Configuration.new
     end
   end
-
-  class InvalidShapeError < NameError; end
-  class UnresolvedShapeError < Exception; end
-
 end
 
 if defined? ActionController::Base
   ActionController::Base.class_eval do
-    extend Shapeable
+    extend Shapeable::Extenders
   end
 end

data/lib/shapeable/configuration.rb

@@ -0,0 +1,24 @@
+module Shapeable
+  class Configuration
+
+    attr_accessor :path, :default_version, :default_shape, :enforce_versioning, :enforce_shape
+
+    def initialize
+      @path = nil
+      @default_version = nil
+      @default_shape = nil
+      @enforce_versioning = true
+      @enforce_shape = true
+    end
+
+    def as_json
+      {
+        path: path,
+        default_version: default_version,
+        default_shape: default_shape,
+        enforce_versioning: enforce_versioning,
+        enforce_shape: enforce_shape
+      }
+    end
+  end
+end

data/lib/shapeable/errors.rb

@@ -0,0 +1,22 @@
+module Shapeable
+  module Errors
+    class InvalidShapeError < NameError
+      def initialize(path, shape, version: nil)
+        resource = path.name.split('::').last.constantize
+        if version
+          super("Invalid shape #{path}::V#{version}::#{resource}#{shape.camelize}Serializer")
+        else
+          super("Invalid shape #{path}::#{resource}#{shape.camelize}Serializer")
+        end
+      end
+    end
+
+    class UnresolvedShapeError < Exception
+      def initialize(msg = 'Unable to resolve shape.' \
+                     ' Try specifying a default version and shape.'
+                    )
+        super
+      end
+    end
+  end
+end

data/lib/shapeable/extenders.rb

@@ -0,0 +1,16 @@
+module Shapeable
+  module Extenders
+
+    def acts_as_shapeable(**opts)
+      require_relative 'shape'
+      include Shapeable::Shape
+
+      class_eval do
+        define_method(:acts_as_shapeable_opts) do
+          opts
+        end
+      end
+    end
+
+  end
+end

data/lib/shapeable/shape.rb

@@ -0,0 +1,67 @@
+require_relative 'errors'
+module Shapeable
+  module Shape
+
+    def self.included base
+      base.class_eval do
+        def shape(shape_opts = {})
+          return unless request.accept
+          opts = merge_shapeable_options(
+            Shapeable.configuration.as_json, acts_as_shapeable_opts, shape_opts
+          )
+          normalize_shapeable_options(opts)
+          raise ArgumentError, 'Specify a path' unless opts[:path]
+          shape = resolve_shape(request.accept, opts[:default_shape])
+          if opts[:enforce_versioning]
+            version = resolve_version(request.accept, opts[:default_version])
+            raise Shapeable::Errors::UnresolvedShapeError unless version && shape if opts[:enforce_shape]
+            constant = construct_constant(opts[:path], shape: shape, version: version)
+          else
+            raise Shapeable::Errors::UnresolvedShapeError unless shape if opts[:enforce_shape]
+            constant = construct_constant(opts[:path], shape: shape)
+          end
+          constant
+        end
+      end
+    end
+
+    def normalize_shapeable_options(opts)
+      opts.keep_if do |k, _v|
+        [:path, :default_shape, :default_version, :enforce_versioning, :enforce_shape].include?(k)
+      end
+    end
+
+    def merge_shapeable_options(*opts_array)
+      opts_array.each_with_object({}) do |val, obj|
+        obj.merge!(val)
+      end
+    end
+
+    def resolve_version(accept_header, default)
+      version_str = accept_header[/version\s?=\s?(\d+)/, 1]
+      version_str.nil? ? default : version_str.to_i
+    end
+
+    def resolve_shape(accept_header, default)
+      accept_header[/shape\s?=\s?(\w+)/, 1] || default
+    end
+
+    def construct_constant(path, shape: nil, version: nil)
+      resource = infer_resource_name(path)
+      if shape
+        return path.const_get("#{resource}#{shape.camelize}Serializer") unless version
+        path_with_version = path.const_get("V#{version}")
+        return path_with_version.const_get("#{resource}#{shape.camelize}Serializer")
+      else
+        return path.const_get("#{resource}Serializer") unless version
+        return path_with_version.const_get("#{resource}Serializer")
+      end
+    rescue NameError
+      raise Shapeable::Errors::InvalidShapeError.new(path, shape, version: version)
+    end
+
+    def infer_resource_name(path)
+      path.name.split('::').last.constantize
+    end
+  end
+end

data/lib/shapeable/version.rb

@@ -1,3 +1,3 @@
 module Shapeable
-  VERSION = '0.3.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shapeable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Shawn O'Mara
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-08 00:00:00.000000000 Z
+date: 2016-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -87,6 +87,10 @@ files:
 - README.md
 - circle.yml
 - lib/shapeable.rb
+- lib/shapeable/configuration.rb
+- lib/shapeable/errors.rb
+- lib/shapeable/extenders.rb
+- lib/shapeable/shape.rb
 - lib/shapeable/version.rb
 - shapeable.gemspec
 homepage: https://github.com/viewthespace/shapeable