cistern 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a4ab124cf563b30d3d4a15c1b8b1ada69a30b434
-  data.tar.gz: e52206d15a0da143a293cfacd1ed105f13dcda2b
+  metadata.gz: 8a2797ca8edb773a77fe40604024aeca97df9880
+  data.tar.gz: 4bfd89a74eef61fdd0cca096a01465235a40009f
 SHA512:
-  metadata.gz: 189206346dc0a43b654527bf72d31fba3accb7327b0355ede31a713e3b94a27a05d92e153e84489cd79afb78d99d5d0060b1f4dac44754f5daad58956e42b0c8
-  data.tar.gz: 3440beaa800a967faadca537eee39661294ff10ba681a1d7805733e16714627990d00d4bee942b60f58870873b451bc70577cc1fd7827bcac2098a77f07113f9
+  metadata.gz: bab52f2a7c09673e54e943da2ada9cacdf8684ca0b3b419c415a8fbc031f5090a9c378ba366adeee9d662770a744975b6732b6715dbc03baccbc0bde93d3fa23
+  data.tar.gz: 805ab1b15511ada7e048f0ebdea1f7e1ca8ab15bfdd3cf7fca417c8662eeef7e4cfd5851381491cc432fcb21f9ece6bd033bd2ea150634195307578b2ec1ab33

data/.gitignore

@@ -16,3 +16,4 @@ test/tmp
 test/version_tmp
 tmp
 .rspec
+gemfiles/*.lock

data/.travis.yml

@@ -2,7 +2,6 @@ language: ruby
 rvm:
 - 2.3.0
 - 2.2
-- 1.9
 bundler_args: "--without development"
 before_install:
 - gem install bundler -v "~> 1.10"
@@ -12,6 +11,11 @@ notifications:
 sudo: false
 services:
 - redis-server
+matrix:
+  include:
+    - rvm: 1.9
+      gemfile: gemfiles/ruby_lt_2.0.gemfile
+
 env:
   matrix:
     secure: eiDhDgp8jBYKZVOqe891g4StnFsqRXcQwlDSnXthRSuWNMd6oFyFOo/s9aXd9lNFkaTBnSAFrUvywH1t2+H3j+cPMn/91W2s2Ldc+SxVxjrY3mWyr6NIudro/rdK7nIfIcWJFtm0teSXg/1nRPZt0qlXc4bZmvwvN3T8MvdgI2I=

data/Appraisals

@@ -0,0 +1,3 @@
+appraise "ruby lt 2.0" do
+  gem "json", '~> 1.8'
+end

data/CHANGELOG.md

@@ -2,7 +2,23 @@
 
 ## [Unreleased](https://github.com/lanej/cistern/tree/HEAD)
 
-[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.7...HEAD)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.3.0...HEAD)
+
+**Implemented enhancements:**
+
+- refactor\(singular\): a collection-less model [\#61](https://github.com/lanej/cistern/pull/61) ([lanej](https://github.com/lanej))
+
+**Merged pull requests:**
+
+- test\(ci\): use `appraisal` for gemfile splitting [\#63](https://github.com/lanej/cistern/pull/63) ([lanej](https://github.com/lanej))
+- modernize README [\#62](https://github.com/lanej/cistern/pull/62) ([lanej](https://github.com/lanej))
+- feature\(hash\): refactor implementation, mixin helpers [\#60](https://github.com/lanej/cistern/pull/60) ([lanej](https://github.com/lanej))
+- refactor\(attributes\): overhaul internals [\#59](https://github.com/lanej/cistern/pull/59) ([lanej](https://github.com/lanej))
+- fix\(attributes\): allow string types to be nil [\#58](https://github.com/lanej/cistern/pull/58) ([lanej](https://github.com/lanej))
+- Tweaks for Readme [\#56](https://github.com/lanej/cistern/pull/56) ([jaw6](https://github.com/jaw6))
+
+## [v2.3.0](https://github.com/lanej/cistern/tree/v2.3.0) (2016-05-17)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.2.7...v2.3.0)
 
 **Implemented enhancements:**
 

data/Gemfile

@@ -3,6 +3,8 @@ source "https://rubygems.org"
 # Specify your gem"s dependencies in cistern.gemspec
 gemspec
 
+gem "appraisal"
+
 group :test do
   gem "guard-rspec", "~> 4.2", require: false
   gem "guard-bundler", "~> 2.0", require: false

data/README.md

@@ -9,14 +9,18 @@ Cistern helps you consistently build your API clients and faciliates building mo
 
 ## Usage
 
-### Custom Architecture
+### Notice: Cistern 3.0
+
+Cistern 3.0 will change the way Cistern interacts with your `Request`, `Collection` and `Model` classes.
 
-By default a service's `Request`, `Collection`, and `Model` are all classes. In cistern `~> 3.0`, the default will be modules.
+Prior to 3.0, your `Request`, `Collection` and `Model` classes would have inherited from `<service>::Client::Request`, `<service>::Client::Collection` and `<service>::Client::Model` classes, respectively.
 
-You can modify your client's architecture to be forwards compatible by using `Cistern::Client.with`
+In cistern `~> 3.0`, the default will be for `Request`, `Collection` and `Model` classes to instead include their respective `<service>::Client` modules.
+
+If you want to be forwards-compatible today, you can configure your client by using `Cistern::Client.with`
 
 ```ruby
-class Foo::Client
+class Blog
   include Cistern::Client.with(interface: :module)
 end
 ```
@@ -24,95 +28,133 @@ end
 Now request classes would look like:
 
 ```ruby
-class Foo::GetBar
-  include Foo::Request
+class Blog::GetPost
+  include Blog::Request
 
   def real
-    "bar"
+    "post"
   end
 end
 ```
 
-Other options include `:collection`, `:request`, and `:model`.  This options define the name of module or class interface for the service component.
 
-If `Request` is to reserved for a model, then the `Request` component name can be remapped to `Prayer`
+### Service
+
+This represents the remote service that you are wrapping. If the service name is `blog` then a good name is `Blog`.
 
-For example:
+Service initialization parameters are enumerated by `requires` and `recognizes`. Parameters defined using `recognizes` are optional.
 
 ```ruby
-class Foo::Client
-  include Cistern::Client.with(request: "Prayer")
+# lib/blog.rb
+class Blog
+  include Cistern::Client
+
+  requires :hmac_id, :hmac_secret
+  recognizes :url
 end
+
+# Acceptable
+Blog.new(hmac_id: "1", hmac_secret: "2")                            # Blog::Real
+Blog.new(hmac_id: "1", hmac_secret: "2", url: "http://example.org") # Blog::Real
+
+# ArgumentError
+Blog.new(hmac_id: "1", url: "http://example.org")
+Blog.new(hmac_id: "1")
 ```
 
-allows a model named `Request` to exist
+Cistern will define for you two classes, `Mock` and `Real`. Create the corresponding files and initialzers for your
+new service.
 
 ```ruby
-class Foo::Request < Foo::Model
-  identity :jovi
+# lib/blog/real.rb
+class Blog::Real
+  attr_reader :url, :connection
+
+  def initialize(attributes)
+    @hmac_id, @hmac_secret = attributes.values_at(:hmac_id, :hmac_secret)
+    @url = attributes[:url] || 'http://blog.example.org'
+    @connection = Faraday.new(url)
+  end
 end
 ```
 
-while living on a `Prayer`
-
 ```ruby
-class Foo::GetBar < Foo::Prayer
-  def real
-    cistern.request.get("/wing")
+# lib/blog/mock.rb
+class Blog::Mock
+  attr_reader :url
+
+  def initialize(attributes)
+    @url = attributes[:url]
   end
 end
 ```
 
+### Mocking
 
-### Service
+Cistern strongly encourages you to generate mock support for your service. Mocking can be enabled using `mock!`.
 
-This represents the remote service that you are wrapping. If the service name is `foo` then a good name is `Foo::Client`.
+```ruby
+Blog.mocking?          # falsey
+real = Blog.new        # Blog::Real
+Blog.mock!
+Blog.mocking?          # true
+fake = Blog.new        # Blog::Mock
+Blog.unmock!
+Blog.mocking?          # false
+real.is_a?(Blog::Real) # true
+fake.is_a?(Blog::Mock) # true
+```
 
-Service initialization parameters are enumerated by `requires` and `recognizes`. Parameters defined using `recognizes` are optional.
+### Working with data
 
-```ruby
-class Foo::Client
-  include Cistern::Client
+`Cistern::Hash` contains many useful functions for working with data normalization and transformation.
 
-  requires :hmac_id, :hmac_secret
-  recognizes :url
-end
+**#stringify_keys**
 
-# Acceptable
-Foo::Client.new(hmac_id: "1", hmac_secret: "2")                            # Foo::Client::Real
-Foo::Client.new(hmac_id: "1", hmac_secret: "2", url: "http://example.org") # Foo::Client::Real
+```ruby
+# anywhere
+Cistern::Hash.stringify_keys({a: 1, b: 2}) #=> {'a' => 1, 'b' => 2}
+# within a Resource
+hash_stringify_keys({a: 1, b: 2}) #=> {'a' => 1, 'b' => 2}
+```
 
-# ArgumentError
-Foo::Client.new(hmac_id: "1", url: "http://example.org")
-Foo::Client.new(hmac_id: "1")
+**#slice**
+
+```ruby
+# anywhere
+Cistern::Hash.slice({a: 1, b: 2, c: 3}, :a, :c) #=> {a: 1, c: 3}
+# within a Resource
+hash_slice({a: 1, b: 2, c: 3}, :a, :c) #=> {a: 1, c: 3}
 ```
 
-Cistern will define for you two classes, `Mock` and `Real`.
+**#except**
 
-### Mocking
+```ruby
+# anywhere
+Cistern::Hash.except({a: 1, b: 2}, :a) #=> {b: 2}
+# within a Resource
+hash_except({a: 1, b: 2}, :a) #=> {b: 2}
+```
 
-Cistern strongly encourages you to generate mock support for your service. Mocking can be enabled using `mock!`.
+
+**#except!**
 
 ```ruby
-Foo::Client.mocking?          # falsey
-real = Foo::Client.new        # Foo::Client::Real
-Foo::Client.mock!
-Foo::Client.mocking?          # true
-fake = Foo::Client.new        # Foo::Client::Mock
-Foo::Client.unmock!
-Foo::Client.mocking?          # false
-real.is_a?(Foo::Client::Real) # true
-fake.is_a?(Foo::Client::Mock) # true
+# same as #except but modify specified Hash in-place
+Cistern::Hash.except!({:a => 1, :b => 2}, :a) #=> {:b => 2}
+# within a Resource
+hash_except!({:a => 1, :b => 2}, :a) #=> {:b => 2}
 ```
 
+
 ### Requests
 
 Requests are defined by subclassing `#{service}::Request`.
 
-* `cistern` represents the associated `Foo::Client` instance.
+* `cistern` represents the associated `Blog` instance.
 
 ```ruby
-class Foo::Client::GetBar < Foo::Client::Request
+class Blog::GetPost < Blog::Request
   def real(params)
     # make a real request
     "i'm real"
@@ -124,126 +166,240 @@ class Foo::Client::GetBar < Foo::Client::Request
   end
 end
 
-Foo::Client.new.get_bar # "i'm real"
+Blog.new.get_post # "i'm real"
 ```
 
 The `#cistern_method` function allows you to specify the name of the generated method.
 
 ```ruby
-class Foo::Client::GetBars < Foo::Client::Request
-  cistern_method :get_all_the_bars
+class Blog::GetPosts < Blog::Request
+  cistern_method :get_all_the_posts
 
   def real(params)
-    "all the bars"
+    "all the posts"
   end
 end
 
-Foo::Client.new.respond_to?(:get_bars) # false
-Foo::Client.new.get_all_the_bars       # "all the bars"
+Blog.new.respond_to?(:get_posts) # false
+Blog.new.get_all_the_posts       # "all the posts"
 ```
 
 All declared requests can be listed via `Cistern::Client#requests`.
 
 ```ruby
-Foo::Client.requests # => [Foo::Client::GetBars, Foo::Client::GetBar]
+Blog.requests # => [Blog::GetPosts, Blog::GetPost]
 ```
 
 ### Models
 
-* `cistern` represents the associated `Foo::Client` instance.
-* `collection` represents the related collection (if applicable)
+* `cistern` represents the associated `Blog::Real` or `Blog::Mock` instance. 
+* `collection` represents the related collection.
 * `new_record?` checks if `identity` is present
 * `requires(*requirements)` throws `ArgumentError` if an attribute matching a requirement isn't set
+* `requires_one(*requirements)` throws `ArgumentError` if no attribute matching requirement is set
 * `merge_attributes(attributes)` sets attributes for the current model instance
+* `dirty_attributes` represents attributes changed since the last `merge_attributes`.  This is useful for using `update`
 
 #### Attributes
 
-Attributes are designed to be a flexible way of parsing service request responses.
+Cistern attributes are designed to make your model flexible and developer friendly.
+
+* `attribute :post_id` adds an accessor to the model.
+	```ruby
+	attribute :post_id
+
+	model.post_id #=> nil
+	model.post_id = 1 #=> 1
+	model.post_id #=> 1
+	model.attributes #=> {'post_id' => 1 }
+	model.dirty_attributes #=> {'post_id' => 1 }
+	```
+* `identity` represents the name of the model's unique identifier.  As this is not always available, it is not required.
+	```ruby
+	identity :name
+	```
+
+	creates an attribute called `name` that is aliased to identity.
+
+	```ruby
+	model.name = 'michelle'
+
+	model.identity   #=> 'michelle'
+	model.name       #=> 'michelle'
+	model.attributes #=> {  'name' => 'michelle' }
+	```
+* `:aliases` or `:alias` allows a attribute key to be different then a response key. 
+	```ruby
+	attribute :post_id, alias: "post"
+	```
+
+	allows
+
+	```ruby
+	model.merge_attributes("post" => 1)
+	model.post_id #=> 1
+	```
+* `:type` automatically casts the attribute do the specified type. 
+	```ruby
+	attribute :private_ips, type: :array
+
+	model.merge_attributes("private_ips" => 2)
+	model.private_ips #=> [2]
+	```
+* `:squash` traverses nested hashes for a key. 
+	```ruby
+	attribute :post_id, aliases: "post", squash: "id"
+
+	model.merge_attributes("post" => {"id" => 3})
+	model.post_id #=> 3
+	```
+
+#### Persistence
+
+* `save` is used to persist the model into the remote service.  `save` is responsible for determining if the operation is an update to an existing resource or a new resource.
+* `reload` is used to grab the latest data and merge it into the model.  `reload` uses `collection.get(identity)` by default.
+* `update(attrs)` is a `merge_attributes` and a `save`.  When calling `update`, `dirty_attributes` can be used to persist only what has changed locally.
 
-`identity` is special but not required.
 
-`attribute :flavor` makes `Foo::Client::Bar.new.respond_to?(:flavor)`
-
-* `:aliases` or `:alias` allows a attribute key to be different then a response key. `attribute :keypair_id, alias: "keypair"` with `merge_attributes("keypair" => 1)` sets `keypair_id` to `1`
-* `:type` automatically casts the attribute do the specified type. `attribute :private_ips, type: :array` with `merge_attributes("private_ips" => 2)` sets `private_ips` to `[2]`
-* `:squash` traverses nested hashes for a key. `attribute :keypair_id, aliases: "keypair", squash: "id"` with `merge_attributes("keypair" => {"id" => 3})` sets `keypair_id` to `3`
-
-Example
+For example:
 
 ```ruby
-class Foo::Client::Bar < Foo::Client::Model
-  identity :id
+class Blog::Post < Blog::Model
+  identity :id, type: :integer
 
-  attribute :flavor
-  attribute :keypair_id, aliases: "keypair",  squash: "id"
-  attribute :private_ips, type: :array
+  attribute :body
+  attribute :author_id, aliases: "author",  squash: "id"
+  attribute :deleted_at, type: :time
 
   def destroy
-    params  = {
-      "id" => self.identity
-    }
-    self.cistern.destroy_bar(params).body["request"]
+    requires :identity
+
+    data = cistern.destroy_post(params).body['post']
   end
 
   def save
-    requires :keypair_id
+    requires :author_id
 
-    params = {
-      "keypair" => self.keypair_id,
-      "bar"     => {
-        "flavor" => self.flavor,
-      },
-    }
+    response = if new_record?
+                 cistern.create_post(attributes)
+               else
+                 cistern.update_post(dirty_attributes)
+               end
 
-    if new_record?
-      merge_attributes(cistern.create_bar(params).body["bar"])
-    else
-      requires :identity
+    merge_attributes(response.body['post'])
+  end
+end
+```
 
-      merge_attributes(cistern.update_bar(params).body["bar"])
-    end
+Usage:
+
+**create**
+
+```ruby
+blog.posts.create(author_id: 1, body: 'text')
+```
+
+is equal to
+
+```ruby
+post = blog.posts.new(author_id: 1, body: 'text')
+post.save
+```
+
+**update**
+
+```ruby
+post = blog.posts.get(1)
+post.update(author_id: 1) #=> calls #save with #dirty_attributes == { 'author_id' => 1 }
+post.author_id #=> 1
+```
+
+### Singular
+
+Singular resources do not have an associated collection and the model contains the `get` and`save` methods.
+
+For instance:
+
+```ruby
+class Blog::PostData
+  include Blog::Singular
+
+  attribute :post_id, type: :integer
+  attribute :upvotes, type: :integer
+  attribute :views, type: :integer
+  attribute :rating, type: :float
+
+  def get
+    response = cistern.get_post_data(post_id)
+    merge_attributes(response.body['data'])
+  end
+  
+  def save
+    response = cistern.update_post_data(post_id, dirty_attributes)
+    merge_attributes(response.data['data'])
   end
 end
 ```
 
+Singular resources often hang off of other models or collections.
+
+```ruby
+class Blog::Post
+  include Cistern::Model
+
+  identity :id, type: :integer
+
+  def data
+    cistern.post_data(post_id: identity).load
+  end
+end
+```
+
+They are special cases of Models and have similar interfaces.
+
+```ruby
+post.data.views #=> nil
+post.data.update(views: 3)
+post.data.views #=> 3
+```
+
+
 ### Collection
 
-* `model` tells Cistern which class is contained within the collection.
-* `cistern` is the associated `Foo::Client` instance
+* `model` tells Cistern which resource class this collection represents.
+* `cistern` is the associated `Blog::Real` or `Blog::Mock` instance
 * `attribute` specifications on collections are allowed. use `merge_attributes`
 * `load` consumes an Array of data and constructs matching `model` instances
 
 ```ruby
-class Foo::Client::Bars < Foo::Client::Collection
+class Blog::Posts < Blog::Collection
 
   attribute :count, type: :integer
 
-  model Foo::Client::Bar
+  model Blog::Post
 
   def all(params = {})
-    response = cistern.get_bars(params)
+    response = cistern.get_posts(params)
 
     data = response.body
 
-    self.load(data["bars"])     # store bar records in collection
-    self.merge_attributes(data) # store any other attributes of the response on the collection
+    load(data["posts"])    # store post records in collection
+    merge_attributes(data) # store any other attributes of the response on the collection
   end
 
-  def discover(provisioned_id, options={})
+  def discover(author_id, options={})
     params = {
-      "provisioned_id" => provisioned_id,
+      "author_id" => author_id,
     }
-    params.merge!("location" => options[:location]) if options.key?(:location)
+    params.merge!("topic" => options[:topic]) if options.key?(:topic)
 
-    cistern.requests.new(cistern.discover_bar(params).body["request"])
+    cistern.blogs.new(cistern.discover_blog(params).body["blog"])
   end
 
   def get(id)
-    if data = cistern.get_bar("id" => id).body["bar"]
-      new(data)
-    else
-      nil
-    end
+    data = cistern.get_post(id).body["post"]
+
+    new(data) if data
   end
 end
 ```
@@ -253,16 +409,16 @@ end
 A uniform interface for mock data is mixed into the `Mock` class by default.
 
 ```ruby
-Foo::Client.mock!
-client = Foo::Client.new     # Foo::Client::Mock
+Blog.mock!
+client = Blog.new     # Blog::Mock
 client.data                  # Cistern::Data::Hash
-client.data["bars"] += ["x"] # ["x"]
+client.data["posts"] += ["x"] # ["x"]
 ```
 
 Mock data is class-level by default
 
 ```ruby
-Foo::Client::Mock.data["bars"] # ["x"]
+Blog::Mock.data["posts"] # ["x"]
 ```
 
 `reset!` dimisses the `data` object.
@@ -270,18 +426,18 @@ Foo::Client::Mock.data["bars"] # ["x"]
 ```ruby
 client.data.object_id # 70199868585600
 client.reset!
-client.data["bars"]   # []
+client.data["posts"]   # []
 client.data.object_id # 70199868566840
 ```
 
 `clear` removes existing keys and values but keeps the same object.
 
 ```ruby
-client.data["bars"] += ["y"] # ["y"]
-client.data.object_id        # 70199868378300
+client.data["posts"] += ["y"] # ["y"]
+client.data.object_id         # 70199868378300
 client.clear
-client.data["bars"]          # []
-client.data.object_id        # 70199868378300
+client.data["posts"]          # []
+client.data.object_id         # 70199868378300
 ```
 
 * `store` and `[]=` write
@@ -290,7 +446,7 @@ client.data.object_id        # 70199868378300
 You can make the service bypass Cistern's mock data structures by simply creating a `self.data` function in your service `Mock` declaration.
 
 ```ruby
-class Foo::Client
+class Blog
   include Cistern::Client
 
   class Mock
@@ -330,22 +486,58 @@ Dirty attributes are tracked and cleared when `merge_attributes` is called.
 
 
 ```ruby
-bar = Foo::Client::Bar.new(id: 1, flavor: "x") # => <#Foo::Client::Bar>
+post = Blog::Post.new(id: 1, flavor: "x") # => <#Blog::Post>
+
+post.dirty?           # => false
+post.changed          # => {}
+post.dirty_attributes # => {}
+
+post.flavor = "y"
 
-bar.dirty?           # => false
-bar.changed          # => {}
-bar.dirty_attributes # => {}
+post.dirty?           # => true
+post.changed          # => {flavor: ["x", "y"]}
+post.dirty_attributes # => {flavor: "y"}
+
+post.save
+post.dirty?           # => false
+post.changed          # => {}
+post.dirty_attributes # => {}
+```
+
+### Custom Architecture
 
-bar.flavor = "y"
+When configuring your client, you can use `:collection`, `:request`, and `:model` options to define the name of module or class interface for the service component.
 
-bar.dirty?           # => true
-bar.changed          # => {flavor: ["x", "y"]}
-bar.dirty_attributes # => {flavor: "y"}
+For example: if you'd `Request` is to be used for a model, then the `Request` component name can be remapped to `Demand`
 
-bar.save
-bar.dirty?           # => false
-bar.changed          # => {}
-bar.dirty_attributes # => {}
+For example:
+
+```ruby
+class Blog
+  include Cistern::Client.with(interface: :modules, request: "Demand")
+end
+```
+
+allows a model named `Request` to exist
+
+```ruby
+class Blog::Request
+  include Blog::Model
+
+  identity :jovi
+end
+```
+
+while living on a `Demand`
+
+```ruby
+class Blog::GetPost
+  include Blog::Demand
+
+  def real
+    cistern.request.get("/wing")
+  end
+end
 ```
 
 ## Examples