mapping 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 62eeea4a078392af4033ea474e602e46380f292a
-  data.tar.gz: d42f4dbec45ba55de098a4d9460f56fb7fbf8bf3
+  metadata.gz: ff5729eb2b5ed25394691d7b0eddbc6083ec181e
+  data.tar.gz: a9a4b1ba4d65cd2851dd31459a89c603d4118c52
 SHA512:
-  metadata.gz: 48aebf04842380c3fab0f9074aeec5b095d4c1c992c278f7f3e7e148c447a052c5d18f5e4139344fd9e15647160667c71e9c65dfad7ffe8c8cfb0d1bfb766b0a
-  data.tar.gz: fd36ade69b67a8bb2b2c78be72eb490e3b75cc2cc62a5dfb55875f6df343995ca44561454175530d6087897f0dee5a0b9c78032752bb600102322d8fdd2d82bb
+  metadata.gz: 875e03d2ddf007893fbc87e4cfcc6f6decc4bc5e96730da64b7a858997856674a5d739d1620ba4e6eef7250bf5b6c230f4e83782e9844d2230643cd337636da1
+  data.tar.gz: e15c06f44348dad4378319aef715303ac4c0027469fe6bb3fdbbf266d6ca24309f2d1021996eaf1a0a0f239cf8fb3d18c3d4847ae3c842d7cd42f7576c682f24

data/README.md

@@ -6,6 +6,35 @@ The mapping gem is a structured system for mapping one model to another, using a
 [![Code Climate](https://codeclimate.com/github/ioquatix/mapping.svg)](https://codeclimate.com/github/ioquatix/mapping)
 [![Coverage Status](https://coveralls.io/repos/ioquatix/mapping/badge.svg)](https://coveralls.io/r/ioquatix/mapping)
 
+## Motivation
+
+I've been thinking (and designing) versioned APIs which serve their data primarily from `ActiveRecord` models. Initially we have been using `as_json/serializable_hash/to_json` where it made sense. 
+
+	records.as_json
+
+This was fine for really simple models and APIs. However, as things get more complex, this approach gets cumbersome:
+
+	records.as_json(
+		only: [:id, :name, :image, :longitude, :latitude],
+		include: [:major_category, :categories],
+	)
+
+We need versioned, internationalized APIs which don't always directly match up to the underlying database models, or in some cases the underlying models change but the API should remain stable (e.g. column renamed, tables changed).
+
+	# image attribute was renamed to image_url, how do we version the response?
+	records.as_json(
+		only: [:id, :name, :image_url, :longitude, :latitude],
+		include: [:major_category, :categories],
+	)
+
+It's also not obvious how to inject methods that take arguments, or even handle per-request state (e.g. `Accept-Language`). Even if it is possible (e.g. using a lambda) I'm not sure that this approach is really desirable - the argument list is becoming impossibly complex: Possibly buggy, hard to reuse, test and difficult to document.
+
+[ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers) looks awesome at first but ultimately seems like an over-engineered version of `as_json`. It **directly** depends on globally defined models which makes versioning hard and doesn't provide any obvious way to inject per-request state (e.g. language). It [clutters up existing models and splits serialization concerns over multiple classes](http://programmingisterrible.com/post/139222674273/write-code-that-is-easy-to-delete-not-easy-to-extend). It's implementation is difficult to understand, it has a large surface area, and it doesn't really address the major concerns regarding versioning, stability and (per-request) state.
+
+I've implemented a [framework for Objective-C many years ago](https://github.com/oriontransfer/SWXMLMapping) which exposes a single primary concept: a mapping model. A mapping model is an object which describes the process mapping an input model (e.g. an `ActiveRecord` model) to an output model (e.g. a hash suitable for `JSON::generate`). A mapping model is entirely isolated from state which is not directly related to the mapping process itself. Because of this, multiple models can co-exist, and the models themselves can be versioned, localized, or whatever else necessary to perform a suitable mapping. It's easy to remove a model if it's no longer being used as all the code is in one place. It's easy to test a mapping model in isolation. Models can be documented like normal code. They can be reused and composed together easily.
+
+The design of this library is centered around being explicit where being explicit makes life easier in the long term.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -41,7 +70,7 @@ class APIv1 < Mapping::Model
 	end
 end
 
-class APIv2 < MappingModelV1
+class APIv2 < APIv1
 	map(Human::Person) do |object|
 		super.merge(
 			posessions: self.map(object.posessions)

data/lib/mapping/model.rb

@@ -27,8 +27,8 @@ module Mapping
 			PREFIX + klass.name.gsub(/::/, '_')
 		end
 		
-		def method_for_mapping(klass)
-			self.class.method_for_mapping(klass)
+		def method_for_mapping(object)
+			self.class.method_for_mapping(object.class)
 		end
 		
 		def self.map(klass, &block)
@@ -36,6 +36,18 @@ module Mapping
 			define_method(method_name, &block)
 		end
 		
+		map(NilClass) do |object|
+			nil
+		end
+		
+		map(TrueClass) do |object|
+			true
+		end
+		
+		map(FalseClass) do |object|
+			false
+		end
+		
 		map(Array) do |items|
 			items.collect{|object| map(object)}
 		end
@@ -44,10 +56,10 @@ module Mapping
 			hash
 		end
 		
-		def map(root)
-			method_name = self.method_for_mapping(root.class)
+		def map(root, *args)
+			method_name = self.method_for_mapping(root)
 
-			self.send(method_name, root)
+			self.send(method_name, root, *args)
 		end
 	end
 end

data/lib/mapping/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Mapping
-	VERSION = "0.1.0"
+	VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mapping
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-01 00:00:00.000000000 Z
+date: 2016-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler