ama-entity-mapper 0.1.0.beta.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0d0c0cf60104e47b8740fcf39308aed94336b1d8
+  data.tar.gz: 939f7581b6587ef04c5c8ceddfdf56c81e27343d
+SHA512:
+  metadata.gz: 54823c3cf8e775b9a9021c4d0606b1423169f5c5608670a11a299e07470cc5b03bc0c318c38364283e235bdf95a93bdbd8d4566644da6c7c472aa33e6b71c75f
+  data.tar.gz: 11fe5500ee4d7b69f0146a33c544ef49bdf2b8ad8bdc888504d04420afa6636bbf6c2c55cbcddb8c79c626606c223bbda35eb7c29565e758d6ff06455ba58a61

data/docs/algorithm.md

@@ -0,0 +1,61 @@
+---
+title: Algorithm
+---
+
+To start with something, let's explain type system. Every concrete type 
+consists of enclosed class and set of attributes. Every attribute, in 
+turn, has it's own type, name, and set of settings. Most of the time 
+attributes represent the very same concept as the ones defined by 
+`attr_accessor`, however, there is also a concept of virtual attributes - 
+they are created as a holder for attached type, and this serves for 
+non-trivial cases (say, all container types, such as collections). Type 
+classes, among other things, include entity factory, normalizer, 
+denormalizer, attribute enumerator, attribute extractor and attribute 
+injector (those will be discussed in a moment).
+
+When mapper is asked to map input `I` into types `T1...Tn`, it uses 
+following algorithm:
+
+- If `I` is not a `T`, then normalize `I` as `I1`, create instance 
+`E1`, and denormalize `I1` into `E1`, otherwise assign `I` to `E1`
+- Enumerate all attributes of `E1`. Recursively start scenario from
+the start for every attribute, validate result, and accumulate results
+- If none of attributes have changed, just return `E1`
+- If there is at least one changed attribute, create instance `E2` and
+set all attributes on it.
+- If something went wrong or is impossible, throw mapping error
+- If there are more target types specified, catch exception and try
+next type
+
+It is important to understand that mapper works only at one level at a
+time - denormalization never tries to denormalize entity and it's 
+attributes, it's just creates new entity and assigns attribute without
+paying attention to attribute contents. It just goes level after level,
+reaching the bottom and then rebuilding target entity level by level,
+starting with leaves and going closer to root.
+
+Because some of those operations may get tricky (treating every class as a 
+bag of instance variables is bad idea, because Set would be normalized as
+two-level hash instead of array), they are not made by mapper directly, but
+rather by type helpers mentioned above:
+
+- Factory allows new entity creation
+- Normalizer and denormalizer speak for themselves
+- Enumerator enumerates attributes of passed entity
+- Extractor extracts attributes out of normalized object
+- Acceptor takes created entity on creation and accepts attribute values,
+setting them on passed entity
+
+*Those are described in detail on [handlers]() page.*
+
+This allows mapper to never know real classes structure, delegating all
+weird work onto specific types. The concrete type class provides reasonable 
+defaults for helpers that won't be changed in most cases, however, as 
+specified above, collections need some special treatment, which is easily
+targeted by such scheme. Default types (Hash, Enumerable, Set) are already
+bundled in.
+
+Whenever mapper receives a request for mapping, it analyzes which type it
+has got, and uses proper algorithm for it. Primitives are mostly just passed
+through, if class is not registered as entity, defaults are used, otherwise
+it's definition is fetched from registry.

data/docs/basic-usage.md

@@ -0,0 +1,179 @@
+---
+title: Basic Usage
+---
+
+Entity mapper is quite simple from the inside. Basically it acts in following
+way:
+
+- Validate that provided types are resolved and create a context
+- Accept an entity
+- With next type in type list:
+    - If entity is not of that target type, normalize it down to basic 
+      structure and then denormalize result into instance of target type
+    - Take the original entity or denormalized result and repeat the 
+      procedure with every attribute
+    - If error is raised, suppress it
+- If result is acquired, return it
+- Else raise last error
+
+So it's basically an horrific recursion machine. It already knows how to 
+work with basic types, how to decompose arbitrary class into Hash of 
+attribute, how to create new instance given a class (yes, just call
+`#new()`) and that methods like `#fuu=(value)` are setters, and you can
+map hash into entity of specific type with ease:
+
+```ruby
+class Person
+  attr_accessor :first_name
+  attr_accessor :last_name
+  
+  def name=(name)
+    @first_name, @last_name = name.split(/\s+/)
+  end
+end
+
+input = { name: 'Stephen Fry' }
+person = AMA::Entity::Mapper.map(input, Person)
+```
+
+`.map(input, *types, **context)` is used to map entities from one 
+type to another automatically. `.normalize(input, **context)` method 
+is used to break entity into the primitive types - hashes, strings, symbols,
+floats, etc.:
+
+```ruby
+normalized = AMA::Entity::Mapper.normalize(person)
+normalized[:first_name] == 'Stephen'
+normalized[:last_name] == 'Fry'
+```
+
+Mapper understands nested types as well, however, it may require
+developer to hint it about used types:
+
+```ruby
+input = {
+  created_by: 'Bill Lawrence',
+  stars: ['Zack Braff', 'Sarah Chalke']
+}
+
+scrubs = AMA::Entity::Mapper.map(input, [Hash, K: Symbol, V: Person])
+```
+
+In this example developer is explicitly telling the Mapper that
+hash keys have to be symbols, and values have to be persons. Please 
+note the array notation - it is required so mapper would combine this
+as a single type.
+
+However, chances are end developer would like to deal with `Series`
+class instance rather than hash. This is possible as well - with some
+hints again:
+
+```ruby
+class Series
+  include AMA::Entity::Mapper::DSL
+  
+  attribute :created_by, Person
+  attribute :stars, [Enumerable, T: Person]
+end
+
+scrubs = AMA::Entity::Mapper.map(input, Series)
+puts scrubs.created_by.first_name # Bill 
+```
+
+`attribute` method registers attribute information within a type. By
+default, it is required to specify attribute name and at least one
+type (yeah, there may be several), but it also has a set of options:
+
+- :nullable (default: true), whether that attribute may be represented
+  by a `nil`
+- :default (default: nil), default value for attribute
+- :values (default: []), allowed ste of values for attribute
+- :sensitive (default: false), forces attribute to be omitted during 
+  normalization
+- :virtual (default: false), forces attribute to be ignored
+- :aliases (default: []), set of other names attribute may be given
+
+So more complex example may look like that:
+
+```ruby
+class Account
+  attribute :id, Symbol, aliases: %i[user_id login]
+  attribute :role, Symbol, values: %i[admin writer reader], default: :reader
+  attribute :metadata, [Hash, K: Symbol, V: Symbol], default: {}
+  attribute :active, TrueClass, FalseClass, default: true
+  attribute :last_login, DateTime, nullable: true
+end
+```
+
+Please feel free to note that:
+
+- :active attribute specifies two types (thanks to ruby that doesn't 
+  have bool type)
+- only :id attribute is required to be present in structure being 
+  denormalized
+- if structure contains `user_id` entry - that would work as well
+(however, having both `id` and `user_id` would result in `id` winning 
+the priority race)
+
+Last but not least: attribute has `attr_accessor` semantics, so,
+after you've called attribute, you already have setter and getter.
+
+## Multiple types
+
+So, what about multiple types? Basically, mapper takes all the
+specified types and tries to use them one by one. As soon as error
+is hit, it will try next, and so on. So given the following example:
+
+```ruby
+class Post
+  attribute :title, String
+  attribute :type, Symbol, values: %i[post repost advertisement]
+  attribute :content, String
+  attribute :reporter, Author, Integer
+end
+
+class JsonProblem
+  attribute :title, String
+  attribute :type, String, default: 'about:blank'
+  attribute :status, Integer
+  attribute :detail, String, nullable: true
+  attribute :instance, String, nullable: true
+  attribute :origin, Author, Integer
+end
+
+input = {
+  title: 'Server has vanished',
+  type: 'about:blank',
+  origin: 'frontend-01.company.com',
+  status: '500'
+}
+
+response = AMA::Entity::Mapper.map(input, Post, JsonProblem)
+```
+
+mapper will do following things
+
+- Try to map data into Post
+  - Start mapping Post attributes
+  - Try to map origin into Author and fail
+  - Try to map origin into Integer and fail
+- Try to map data into JsonProblem
+  - Start mapping JsonProblem attributes
+  - Fail on mapping status into Integer
+- Raise last exception
+
+## Handlers
+
+If none of the above fully solved your case, it's time to mess with 
+handlers.
+
+Handlers are specific objects that process specific part of domain,
+like:
+
+- Enumerate all entity attributes
+- Set attribute on entity
+- Create entity
+- Normalize entity
+
+Handlers are very specific, so [standalone page](handlers) has been
+allocated to describe their principles.

data/docs/dsl.md

@@ -0,0 +1,90 @@
+---
+title: DSL In Detail
+---
+
+To add mapper support in your classes, you need to include DSL module:
+
+```ruby
+class User
+  include AMA::Entity::Mapper::DSL
+end
+```
+
+After that you can specify attributes, parameters and handlers via added
+methods. Also, `#bound_type()` class method will be defined that will return
+current class mapping.
+
+## Attributes
+
+Attributes are specified via 
+`#attribute(name:Symbol, *types:Class|module|Type, **options)` method:
+
+```ruby
+attribute :password, String, sensitive: true
+```
+
+You can specify arbitrary amount of types in case attribute may be one of
+several classes:
+
+```ruby
+attribute :disabled, TrueClass, FalseClass
+```
+
+Attributes have following options:
+
+- :nullable (default: true), whether that attribute may be represented
+  by a `nil`
+- :default (default: nil), default value for attribute
+- :values (default: []), allowed ste of values for attribute
+- :sensitive (default: false), forces attribute to be omitted during 
+  normalization
+- :virtual (default: false), forces attribute to be ignored
+- :aliases (default: []), set of other names attribute may be given
+
+Attribute declaration creates corresponding getter and setter.
+
+## Parameters
+
+Parameters are defined by simple `#parameter(id:Symbol)` method. They are used
+to specify attribute type that is not yet known:
+
+```ruby
+attribute :value, parameter(:T)
+```
+
+After that parameter can be configured during type specification:
+
+```ruby
+Mapper.map(input, [CustomClass, T: Integer])
+```
+
+Parameters may be resolved with singular or multiple types:
+
+```ruby
+Mapper.map(input, [CustomClass, T: [TrueClass, FalseClass, NilClass]])
+```
+
+## Handlers
+
+Handlers are custom logic processors for described type. There are following
+handler types:
+
+- Factory, creates new instances
+- Normalizer, converts class instance into low-level data structure
+- Denormalizer, populates empty instance using low-level data structure
+- Enumerator, enumerates attributes for specified entity
+- Extractor, extracts entity attributes out of low-level type
+- Injector, injects attributes in specified entity
+
+They may be set as objects or blocks using corresponding setters:
+
+```ruby
+factory = factory_object
+denormalizer_block do
+  # ...
+end
+```
+
+The specific interfaces of handlers are described on 
+[corresponding page](handlers), the need for them is explained on [algorithm]()
+page.

data/docs/generics.md

@@ -0,0 +1,55 @@
+---
+title: Parametrized Types (Generics)
+---
+
+Amongst other types, there is separate kind of *container* types, with
+the most recognizable examples of Enumerable, Array and Hash. It is not
+clear how to define types, because one scenario requires Hash values
+to be symbol, another one requires them to be integers. To handle this,
+concept of parametrized types (or generics), widely known in statically
+typed languages, is introduced.
+
+Type may define one or more parameters during it's definition using 
+`.parameter()` call. Parameters can be used to substitute types, 
+consider following example:
+
+
+```yml
+# input:
+pagination:
+  number: 3
+  total: 271
+content:
+  - item #1
+  - item #2
+  - ...
+```
+
+```ruby
+class Pagination
+  attribute :number, Integer
+  attribute :total, Integer
+end
+
+class Page
+  attribute :pagination, Pagination
+  attribute :content, [Enumerable, T: parameter(:E)]
+end
+```
+
+What has happened there? Page `:content` attribute has been declared
+with type Enumerable, and it's parameter `T` had been substituted with
+Page parameter `E`. To finalize this up, resolve page parameters in 
+mapping definition:
+
+```ruby
+AMA::Entity::Mapper.map(input, [Page, E: Person])
+```
+
+In fact, parameters are resolved with type collections rather than
+singular types, so this is perfectly valid (and, in fact, the only way
+to allow nils in array):
+
+```ruby
+AMA::Entity::Mapper.map(input, [Enumerable, T: [Float, Integer, NilClass]])
+```

data/docs/handlers.md

@@ -0,0 +1,196 @@
+---
+title: Handlers
+---
+
+Handlers are specific logic processors that allow to customize entity 
+processing. 
+
+Some common rules apply for all processors: they can be set as block or object
+(latter may help in avoiding block hell), they have always accept type instance
+(because it's parameters may be resolved to something not yet known at the 
+moment of processor definition) and they are wrapped in safety 
+wrappers, so invalid signature will be reported, and errors would be wrapped
+in description errors with paths where that thing has happened.
+
+## Normalizer
+
+Normalizer is a processor that takes entity and emits low-level representation
+of that entity - Hash, Array, String, or something like that. Normalizer can
+be set as standalone object or simple block with same signature:
+
+```ruby
+normalizer = Object.new.tap do |instance|
+  instance.define_singleton_method :normalize do |entity, type, context|
+    data = yield(entity, type, context)
+    data[:private] = nil
+    data[:owner] = data[:owner][:id]
+    data
+  end
+end
+```
+
+```ruby
+normalizer_block do |entity, type, context|
+  # ...
+end
+```
+
+Normalizer is provided with a block that allows for fallback to default 
+processing. This may be used to perform pre- or post-processing.
+
+Default normalizer implementation simply represents all instance 
+variables as hash.
+
+## Denormalizer
+
+Denormalizer returns entity with values from low-level structure. As
+with normalizer, it is fed with a block that may be used for fallback 
+processing:
+
+```ruby
+denormalizer = Object.new.tap do |instance|
+  instance.define_singleton_method :denormalize do |input, type, context|
+    yield(entity, input, type, context)
+    entity.id ||= input[:user_id]
+    entity
+  end
+end
+```
+
+```ruby
+denormalizer_block do |input, type, context, &block|
+  # ...
+end
+```
+
+Default denormalizer accepts only hash and sets instance variables / calls
+setter methods using it's contents.
+
+Common usage for denomralization is input unification:
+
+```ruby
+denormalizer_block do |input, type, context, &block|
+  input = {} if input.nil?
+  input = { name: input } if input.is_a?(String)
+  block.call(input, type, context)
+end
+```
+
+## Factory
+
+Factory is plain simple and used to create new instances:
+
+```ruby
+factory = Object.new.tap do |instance|
+  instance.define_singleton_method :create do |type, input, context|
+    type.type.new
+  end
+end
+```
+
+```ruby
+factory_block do |type, input, context|
+  # ...
+end
+```
+
+Default factory creates entity using `Class#new` and sets default 
+values for attributes with default values.
+
+## Enumerator
+
+Enumerator is a class that takes entity and returns standard ruby enumerator,
+which emits triplets of attribute, value, and segment. It allows mapper to
+delegate attribute location and allows resolution of complex cases with virtual
+types. It is used to inspect entity contents:
+
+```ruby
+type.enumerator(entity).each do |attribute, value, segment|
+  local_ctx = context.advance(segment)
+  puts "#{local_ctx.path} value: #{value}" 
+end
+```
+
+Setting examples:
+
+```ruby
+enumerator = Object.new.tap do |instance|
+  instance.define_singleton_method :enumerate do |entity, type, context = nil|
+    ::Enumerator.new do |y|
+      type.attributes.each do |attribute|
+        segment = ::AMA::Entity::Mapper::Path::Segment.attribute(attribute.name)
+        y << [attribute, entity.send(attribute.name), segment]
+      end
+    end
+  end
+end
+```
+
+```ruby
+enumerator_block do |entity, type, context = nil|
+  # ...
+end
+```
+
+## Injector
+
+Injector is enumerator counterpart: it takes in entity and attribute and sets 
+the latter on the former
+
+```ruby
+injector = Object.new.tap do |instance|
+  instance.define_singleton_method :inject do |entity, type, attribute, value|
+    entity.send("#{attribute.name}=", value)
+  end
+end
+```
+
+```ruby
+injector_block do |entity, type, attribute, value, context|
+  # ...
+end
+```
+
+The argument list is quite huge, but it is still easier that way than dealing
+with intermediate object.
+
+## Attribute validator
+
+Allows to validate attribute correctness, returns list of 
+violations as strings:
+
+```ruby
+validator = Object.new.tap do |instance|
+  instance.define_singleton_method :validate do |value, attribute, context|
+    return [] if attribute.values.include?(value)
+    ["Values #{attribute.values} don't contain #{value}"]
+  end
+end
+```
+
+```ruby
+validator_block do |value, attribute, context|
+  # ...
+end
+```
+
+## Entity validator
+
+The very same thing for entities (usually there is no need in that).
+
+```ruby
+validator = Object.new.tap do |instance|
+  instance.define_singleton_method :validate do |entity, type, context|
+    if entity.policy == :read and entity.roles.include?(:admin)
+      return ['Something\'s misty here!']
+    end
+    []
+  end
+end
+```
+
+```ruby
+validator_block do |value, attribute, context|
+  # ...
+end
+