flatter 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f1e1af6544620264587af098834b94ddf548bac7
-  data.tar.gz: c48b5d92d0692cb453c84a84782dcfa77ea4c5f7
+  metadata.gz: 543de04a22f3559983f3dd01ee360a7f78117df6
+  data.tar.gz: 5e6e173e3c3b60d0109ddb9a898b61fcd756254f
 SHA512:
-  metadata.gz: 05a93c13278b98f3eeb51f27095575d39a713c13c7933c6863a4f9b0cd800709b7de781afd6e36dc147021bfbd459a0977e194efc739d1a4fbec62e4c92cbce6
-  data.tar.gz: f9b66855aab233cd339eb94315abb527a81bd3cf188c8a05b679866ddf82c076264b2e906cc131cd174ea19c2a3223e2a06fcc1001c4f4c9ead9aa230df67dfd
+  metadata.gz: 8d818795d50e0d5a138e430ad5b1e5c3b4983e93bba7f5a34561592d92a35ca17ac57e3d340f7674f3662602e6a290fcadf7a78482f6b9fb66bdcc288d02655a
+  data.tar.gz: 052590d63bd471a285e3268497189bf14185d9bd24b1a69058a363b550f4370c590239abe7277d29f91247a20b180146ab34bf3264be689897ad1b7bfca71687

data/README.md

@@ -1,7 +1,10 @@
 # Flatter
 
-This gem supersedes [FlatMap](https://github.com/TMXCredit/flat_map) gem. With only it's core concepts in mind
-it has been written from complete scratch to provide more pure, clean, extensible code and reliable functionality.
+[![Build Status](https://secure.travis-ci.org/akuzko/flatter.png)](http://travis-ci.org/akuzko/flatter)
+
+This gem supersedes [FlatMap](https://github.com/TMXCredit/flat_map) gem. With
+only it's core concepts in mind it has been written from complete scratch to
+provide more pure, clean, extensible code and reliable functionality.
 
 ## Installation
 
@@ -21,11 +24,683 @@ Or install it yourself as:
 
 ## Usage
 
-Coming soon.
+If you happen to use `FlatMap` gem , check out
+[Flatter and FlatMap: What's Changed](https://github.com/akuzko/flatter/wiki/Flatter-and-FlatMap:-What's-Changed) wiki page.
+
+Flatter's main working units are instances of `Mapper` class. **Mappers** are essentially
+wrappers around your related ActiveModel-like objects, map their attributes to mapper's
+accessors via **mappings**, can be **mounted** by other mappers, and can define flexible
+behavior via **traits**. Let's cover this topics one by one.
+
+### Mappings
+
+Mappings represent a mapper's property, which maps it to some attribute of the
+target object. Since eventually mappers are used in combination with each other, it is
+better to map model's attribute with a unique "full name" to avoid collisions, for example:
+
+```ruby
+# models:
+class Person
+  include ActiveModel::Model
+
+  attr_accessor :first_name, :last_name
+end
+
+class Group
+  include ActiveModel::Model
+
+  attr_accessor :name
+end
+
+class Department
+  include ActiveModel::Model
+
+  attr_accessor :name
+end
+
+# mappers:
+class PersonMapper < Flatter::Mapper
+  map :first_name, :last_name
+  # it's ok, since :first_name and :last_name attributes are
+  # not likely to be used somewhere else
+end
+
+class GroupMapper < Flatter::Mapper
+  map group_name: :name
+  # maps mapper's :group_name attribute to target's :name attribute
+end
+
+class DepartmentMapper < Flatter::Mapper
+  map department_name: :name
+  # maps mapper's :department_name attribute to target's :name attribute
+end
+```
+
+#### Mapping Options
+
+- `:reader` Allows to add a custom logic for reading target's attribute.
+  When value is `String` or `Symbol`, calls a method defined by a **mapper** class.
+  If that method accepts an argument, mapping name will be passed to it.
+  When value is `Proc`, it is executed in context of mapper object, yielding
+  mapping name if block has arity of 1. For other arbitrary objects will simply
+  return that object.
+
+- `:writer` Allows to control a way how value is assigned (written).
+  When value is `String` or `Symbol`, calls a method defined by a **mapper** class,
+  passing a value to it. If that method accepts second argument, mapping name will be
+  additionally passed to it.
+  When value is `Proc`, it is executed in context of mapper object, yielding
+  value and optionally mapping name if block has arity of 2. For other values will
+  raise error.
+
+### Mountings
+
+Stand-alone mappers provide not very much benefit. However, mappers have a powerful
+ability to be mounted on top of each other. When mapper mounts another one, it
+gains access to all of it's mappings, and they become accessible in a plain way.
+
+For example, having `Person`, `Department` and `Group` classes defined above with
+additional sample relationship we might have:
+
+```ruby
+# models:
+class Person
+  def department
+    @department ||= Department.new(name: 'Default')
+  end
+
+  def group
+    @group ||= Group.new(name: 'General')
+  end
+end
+
+# mappers:
+class PersonMapper < Flatter::Mapper
+  map :first_name, :last_name
+
+  mount :department
+  mount :group
+end
+
+person = Person.new(first_name: 'John', last_name: 'Smith')
+mapper = PersonMapper.new(person)
+
+mapper.read # =>
+  # { 'first_name'      => 'John',
+  #   'last_name'       => 'Smith',
+  #   'department_name' => 'Default',
+  #   'group_name'      => 'General' }
+
+mapper.group_name = 'Managers'
+person.group.name # => "Managers"
+```
+
+#### Mounting Options
+
+- `:mapper_class_name` Name of the mapper class (`String`) if it cannot be
+  determined from the mounting name itself. By default it is camelized name
+  followed by 'Mapper', for example, for `:group` mounting, default mapper
+  class name is `'GroupMapper'`.
+
+- `:mapper_class` Used mostly internally, but allows to specify mapper class
+  itself. Has more priority than `:mapper_class_name` option.
+
+- `:target` Allows to manually set mounted mapper's target. By default target is
+  obtained from mounting mapper's target by sending it mounting name. In example
+  above target for `:group` mapping was obtained by sending `:group` method to
+  `person` object, which was the target of root mapper.
+  When value is `String` or `Symbol`, it is considered as a method name of the
+  **mapper**, which is called with no arguments.
+  When value is `Proc`, it is called yielding mapper's target to it.
+  For other objects, objects themselves are used as targets.
+
+- `:traits` Allows to specify a list of traits to be applied for mounted mappers.
+  See **Traits** section bellow.
+
+### Callbacks
+
+Mappers include `ActiveModel::Validation` module and thus support `ActiveSupport`'s
+callbacks. Additionally, `:save` callbacks have been defined for `Flatter::Mapper`,
+so you can do something like `set_callback :save, :after, :send_invitation`.
+
+### Traits
+
+Traits are another powerful mapper ability. Traits allow to encapsulate named sets
+of additional definitions, and optionally use them on mapper initialization or
+when mounting mapper in other one. Everything that can be defined within the mapper
+can be defined withing the trait. For example (suppose we have some additional
+`:with_counts` trait defined on `DepartmentMapper` alongside with model relationships):
+
+```ruby
+class PersonMapper < Flatter::Mapper
+  map :first_name, :last_name
+
+  trait :full_info do
+    map :middle_name, dob: :date_of_birth
+
+    mount :group
+  end
+
+  trait :with_department do
+    mount :department, traits: :with_counts
+  end
+end
+
+mapper = PersonMapper.new(person)
+full_mapper = PersonMapper.new(person, :full_info, :with_department)
+
+mapper.read # =>
+  # { 'first_name'      => 'John',
+  #   'last_name'       => 'Smith' }
+
+full_mapper.read # =>
+  # { 'first_name'              => 'John',
+  #   'last_name'               => 'Smith',
+  #   'middle_name'             => nil,
+  #   'dob'                     => Wed, 18 Feb 1981,
+  #   'group_name'              => 'General'
+  #   'department_name'         => 'Default',
+  #   'department_people_count' => 31 }
+```
+
+#### Traits and callbacks
+
+Since traits are internally mappers (which allows you to define everything mapper
+can), you can also define callbacks on traits, allowing you to dynamically opt-in,
+opt-out and reuse functionality. Keep in mind that `ActiveModel`'s validation
+routines are also just a set of callbacks, meaning that you can define sets of
+validation in traits, mix them together in any way. For example:
+
+```ruby
+class PersonMapper < Flatter::Mapper
+  map :first_name, :last_name
+
+  trait :registration do
+    map personal_email: :email
+
+    validates_presence_of :first_name, :last_name
+    validates :personal_email, :presence: true, email: true
+
+    set_callback :save, :after, :send_greeting
+
+    def send_greeting
+      PersonMailer.greeting(target).deliver_now
+    end
+  end
+end
+```
+
+#### Traits and shared methods
+
+Despite the fact traits are separate objects, you can call methods defined in
+one trait from another trait, as well as methods defined in root mapper itself
+(such as attribute methods). That allows you to treat traits as parts of the
+root mapper.
+
+#### Inline extension traits
+
+When initializing a mapper, or defining a mounting, you can pass a block with
+additional definitions. This block will be treated as an anonymous extension trait.
+For example, let's suppose that `email` from example above is actually a part
+of another `User` model that has it's own `UserMapper` with defined `:email` mapping.
+Then we might have something like:
+
+```ruby
+class PersonMapper < Flatter::Mapper
+  map :first_name, :last_name
+
+  trait :registration do
+    validates_presence_of :first_name, :last_name
+
+    mount :user do
+      validates :email, :presence: true, email: true
+      set_callback :save, :after, :send_greeting
+
+      def send_greeting
+        UserMailer.greeting(target).deliver_now
+      end
+    end
+  end
+end
+
+```
+
+### Processing Order
+
+`Flatter` mappers have a well-defined processing order of mountings (including
+traits), best shown by example. Suppose we have something like this:
+
+```ruby
+class AMapper < Flatter::Mapper
+  trait :trait_a1 do
+    mount :b, traits: :trait_b do
+      # extension callbacks definitions
+    end
+  end
+
+  trait :trait_a2 do
+    mount :c
+  end
+
+  mount :d
+end
+```
+
+Mappers are processed (validated and saved) from top to bottom. Let's have initialized
+
+```ruby
+mapper = AMapper.new(a, :trait_a2, :trait_a1)
+```
+
+Please note traits order, it is very important: `:trait_a2` goes first, so it's
+callbacks and mountings will go first too. So if we call `mapper.save`, we will have
+following execution order (suppose, we have defined callbacks for all traits and mappers):
+
+```
+trait_a2.before_save
+trait_a1.before_save
+A.before_save
+A.save
+A.after_save
+trait_a1.after_save
+trait_a2.after_save
+C.before_save
+C.save
+C.after_save
+trait_b.before_save
+B_extension.before_save
+B.before_save
+B.save
+B.after_save
+B_extension.after_save
+trait_b.after_save
+D.before_save
+D.save
+D.after_save
+```
+
+### Attribute methods
+
+All mappers can access mapped values via attribute methods that match mapping names.
+That allows you to easily use mappers for building forms or developing other
+functionality.
+
+You also have reader methods that match mounting names. They will return
+value read for a specific mounting (including it's own nested mountings).
+For example:
+
+```ruby
+class UserMapper < Flatter::Mapper
+  map :email
+
+  mount :person do
+    map :first_name, :last_name
+
+    mount :phone do
+      map phone_number: :number
+    end
+  end
+end
+
+mapper = UserMapper.new(User.new)
+mapper.email = "user@email.com"
+mapper.first_name = "John"
+mapper.phone_number = "111-222-3333"
+
+mapper.read # =>
+  # { "email" => "user@email.com",
+  #   "first_name" => "John",
+  #   "last_name" => nil,
+  #   "phone_number" => "111-222-3333" }
+
+mapper.person # =>
+  # { "first_name" => "John",
+  #   "last_name" => nil,
+  #   "phone_number" => "111-222-3333" }
+
+mapper.phone # =>
+  # { "phone_number" => "111-222-3333" }
+```
+
+Please also read "Attribute methods" subsection for Collections bellow
+for details on what methods do you get when mapping collections.
+
+### Collections
+
+Starting from version `0.2.0`, Flatter mappers also support handling of collections.
+
+#### Declaration
+
+To declare a mapper that will handle a collection of items, simply mount it
+with a pluralized name:
+
+```ruby
+class PersonMapper < Flatter::Mapper
+  mount :phones
+end
+```
+
+If you need to mount a mapper with already pluralized name to handle single
+item in common fashion, mount it with `collection: false` option:
+
+```ruby
+class SeamstressMapper < Flatter::Mapper
+  mount :scissors, collection: false
+end
+```
+
+If you need your root mapper to handle a collection of items, initialize it
+with `collection: true` option:
+
+```ruby
+mapper = PhoneMapper.new(user.phones, collection: true)
+```
+
+#### Key
+
+Mapper that will be used for mapping collection should define `key` mapping.
+`Flatter` offers `key` class-level method to do it easier. You can call it
+on mapper definition:
+
+```ruby
+class PhoneMapper
+  key :id
+end
+```
+
+or when mounting mapper for collection handling:
+
+```ruby
+class PersonMapper
+  mount :phones do
+    key -> { target.number }
+  end
+end
+```
+
+All non-nil `key` mappings have to have unique value (within collection they
+belong to). Otherwise `NonUniqKeysError` will be raised on reading. All items
+that have `nil` as a key value are considered to be "new items". All such
+items are removed from collection on writing.
+
+#### Reading
+
+As well as can be expected, collection mappers provide an array of hashes
+derived from reading from all items in the collection. Each hash in this array
+will have `"key"` key for item identification. It should be used for writing
+(see bellow). For example:
+
+```ruby
+class CompanyMapper < Flatter::Mapper
+  map company_name: :name
+
+  mount :departments do
+    key :id
+
+    mount :location
+  end
+end
+
+class DepartmentMapper < Flatter::Mapper
+  map department_name: :name
+end
+
+class LocationMapper < Flatter::Mapper
+  map location_name: :name
+end
+
+# ...
+
+mapper = CompanyMapper.new(company)
+
+mapper.read # =>
+  # { "company_name" => "Web Developers, Inc.",
+  #   "departments"  => [{
+  #     "key" => 1,
+  #     "department_name" => "R & D",
+  #     "location_name" => "Good Office"
+  #   }, {
+  #     "key" => 2,
+  #     "department_name" => "QA",
+  #     "location_name" => "QA Office"
+  #   }]
+  # }
+
+```
+
+#### Writing
+
+To update collection items, you should pass an array of hashes to it's mapper.
+Value of the `:key` key of each hash is important and defines how each set of
+params will be used.
+
+- If `key` is present in the original collection, `params` hash will be used
+  to update mapped item via `write` method
+
+- If `key` is `nil`, params are treated as attributes for the new record, so
+  new instance of mapped target class is created and updated via `write` method.
+
+- In original collection, *all* items with keys that are not listed in given
+  array of hash params considered to be marked for destruction and corresponding
+  items will be removed from mapped collection. The same concerns for *all*
+  current items in collection, which have `key` mapped to `nil`.
+
+Example:
+
+```ruby
+company.departments.map(&:id)   # => [1, 2]
+company.departments.map(&:name) # => ["R & D", "QA"]
+
+company_mapper.write(departments: [
+  {key: 1, department_name: "D & R"},
+  {department_name: "Testers"}
+])
+
+company.departments.map(&:id)   # => [1, nil]
+company.departments.map(&:name) # => ["D & R", "Testers"]
+```
+
+#### Attribute Methods
+
+When you use mappers to map collection of items, attribute method behavior
+is slightly different. For example, when you have
+
+```ruby
+class PersonMapper < Flatter::Mapper
+  map :first_name, :last_name
+  mount :phone
+end
+
+class DepartmentMapper < Flatter::Mapper
+  mount :people do
+    key :id
+  end
+end
+```
+
+`mapper.first_name` no longer able to return specific value, since it's
+not clear which first name should it be. Thus, when mapper is mounted as
+a collection item, instead of singular value accessors you gain pluralized
+reader methods:
+
+```ruby
+  # all first_names of all people of the mapped department:
+  mapper.first_names # => ["John", "Derek"]
+```
+
+The same concerns for all nested (singular or collection) mappings and mountings
+under collection mapper:
+
+```ruby
+  # all phone number of all people of the mapped department
+  mapper.phone_numbers # => ["111-222-3333", "222-111-33333"]
+
+  # all the people
+  mapper.people # =>
+  # [{"first_name" => "John", "last_name" => "Smith", "key" => 1, "phone_number" => "111-222-3333"},
+  #  {"first_name" => "Derek", "last_name" => "Parker", "key" => 2, "phone_number" => "222-111-3333"}]
+
+  # all phones (note the :phone mapper mounted on :people, opposed to it's :phone_number mapping)
+  mapper.phones # =>
+  # [{"phone_number" => "111-222-3333"}, {"phone_number" => "222-111-33333"}]
+```
+
+Please note that attempt to use writer method to update collection of mappings,
+such as `first_names=` will raise runtime `"Cannot directly write to a collection"`
+error. To update collection items and their data you have to use `write`/`apply`
+methods to utilize `key`-dependent logic to properly update your collection items
+alongside with all nested mappings/mountings they might have.
+
+#### Errors
+
+Since all errors after validation process are consolidated into a plain hash
+of errors, there is a need to distinct errors of one collection items from
+another ones. To achieve this, Flatter adds special prefix to error key, which is
+formed from collection name and item **index** (not id or key). For example:
+
+```ruby
+class Person
+  include ActiveModel::Model
+
+  attr_accessor :name, :age
+end
+
+class Department
+  include ActiveModel::Model
+
+  attr_accessor :name
+
+  def people
+    @people ||= []
+  end
+end
+
+class PersonMapper < Flatter::Mapper
+  map :age, person_name: :name
+
+  validates :age, numericality: {only_integer: true, greater_than_or_equal_to: 1}
+end
+
+class DepartmentMapper < Flatter::Mapper
+  map department_name: :name
+
+  mount :people
+end
+
+department = Department.new
+mapper = DepartmentMapper.new(department)
+mapper.apply(people: [
+  { person_name: "John", age: "22.5" },
+  { person_name: "Dave", age: "18" },
+  { person_name: "Kile", age: "0" }
+]) # => false
+
+mapper.errors.messages # =>
+  # { :"people.0.age" => ["must be an integer"],
+  #   :"people.2.age" => ["must be greater than or equal to 1"] }
+```
+
+### Extensions
+
+Aside from core functionality and behavior defined in this gem, there is also
+[flatter-extensions](https://github.com/akuzko/flatter-extensions) gem that
+provides extensions to help you use mappers more efficiently. At this point there
+are following extensions:
+
+- `:multiparam` Allows you to define multiparam mappings by adding `:multiparam`
+  option to mapping. Works pretty much like `Rails` multiparam attribute assignment.
+- `:skipping` Allows to skip mappers (mountings) from the processing chain by
+  calling `skip!` method on a particular mapper. When used in before validation
+  callbacks, for example, allows you to ignore some extra processing.
+- `:order` Allows you to manually control processing order of mappers and their
+  mountings. Provides `:index` option for mountings, which can be either a Number,
+  which means order for both validation and saving routines, or a hash like
+  `index: {validate: -1, save: 2}`. By default all mappers have index of `0` and
+  processed from top to bottom.
+- `:active_record` Very useful extension that allows you to effectively use mappers
+  when working with ActiveRecord objects with defined relationships and associations
+  that form a structured graph that you want to work with as a plain data structure.
+
+### Public API
+
+Some methods of the public API that should help you building your mappers:
+
+#### Mapper methods
+
+- `name` - return a mapper name.
+
+- `target` - returns mapper target - an object mapper extracts values from
+  and assigns values to using defined mappings.
+
+- `mappings` - returns a plain hash of all the mappings (including ones related
+  to mounted mappers) in a form of `{name <String> => mapping object <Mapping>}`.
+  Note that for empty collections there will be no mentions of item mappings at all.
+  If collection has only one item, it's mappings will be listed as the rest.
+  If there are multiple same-named mappings, they will be listed in array.
+
+- `mapping_names` - returns a list of all **available** mappings. This differs
+  from `mappings.keys`, since `mapping_names` represents a list of all mappings
+  that may be used by mapper. Essentially, this is the list of mapper's
+  attribute accessor methods.
+
+- `mapping(name)` - returns a mapping with a `name` name. The same as `mappings[name.to_s]`
+
+- `mountings` - returns a plain hash of all mounted mappers (including all used traits)
+  in a form of `{name <String> => mapper object <Mapper>}`. Just like in case with
+  mappings, mountings with same name will be listed in array.
+
+- `mounting_names` - returns a list of all **available** mountings. This represents
+  a list of reader methods that will return a sub-hash of specific mounting or
+  an array of such hashes for collections.
+
+- `mounting(name)` - finds a mounting by name. Best used for addressing singular
+  mountings within a mapper, but also has other internal usages under the hood
+  (see sources of `Flatter::Mapper::AttributeMethods` module).
+
+- `read` - returns a hash of all values obtained by all mappings in a form of
+  `{name <String> => value <Object>}`.
+
+- `write(params)` - for each defined mapping, including mappings from mounted
+  mappers and traits, passes value from params that corresponds to mapping name
+  to that mapping's `write` method.
+
+- `valid?` - runs validation routines and returns `true` if there are no errors.
+
+- `errors` - returns mapper's `Errors` object.
+
+- `save` - runs save routines. If target object responds to `save` method, will
+  call it and return it's value. Returns true otherwise. If multiple mappers
+  are mounted, returns `true` only if all mounted mappers returned `true` on saving
+  their targets.
+
+- `apply(params)` - writes `params`, runs validation and runs save routines if
+  validation passed.
+
+- `collection?` - returns `true` if mapper is a collection mapper.
+
+- `trait?` - returns `true` if mapper is a trait mapper.
+
+#### Mapping methods
+
+- `name` - returns mapping name.
+
+- `target_attribute` - returns an attribute name which mapping maps to.
+
+- `read` - reads value from target according to setup.
+
+- `read!` - tries to directly read value from target based on mapping's `target_attribute`
+  property. Ignores `:reader` option.
+
+- `write(value)` - assigns a `value` to target according to setup.
+
+- `write!(value)` - tries to directly assign a value to target based on mapping's
+  `target_attribute` property. Ignores `:writer` option.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
 
 ## Contributing
 
@@ -35,4 +710,3 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/akuzko
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-