brainstem 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6284bb9b32ad35fb5e88a28ada0cb128a533dbae
-  data.tar.gz: 3f1624b6bde3c0703b3540b70a77566c6312bd7b
+  metadata.gz: a5785540a81ca6119478cd1c8567f3c96fa73fa6
+  data.tar.gz: c8ea012472c8d23767b446dfb941d0ebff5ec067
 SHA512:
-  metadata.gz: '06469a9fd4016afafc4c169208eecf714bfc0159ff11a1f3442eefdcfe7406a5017288f146e25f5d4bdc203705fe3b26986ac8adac1d6112e05775898c7b33d4'
-  data.tar.gz: 2fccd29843c5b613e288520a9897f3c0dac7a02bcaf5953bf5dfa4bdeacf876711bf3d07cc65c4f1f14dc725b389c4541a1e002dc865ebc435507521686e474a
+  metadata.gz: 71a2fd84129676cd27b0d669c94080f92b23417c4d7eb0ccb1366b02e2baa388fd53e0a54d0bbb0f84ea47d139bd54d13bd1e725bafa2bfc613ecb343f7cd119
+  data.tar.gz: e5a35cc09a2a048fa30a4633b1c7b66f2d60f56f52e1889e46466983f4b9dcddbd4828859836680b012a68cbca8fbd74ad66b2cacb6ed2e53a810ea160ee7be8

data/CHANGELOG.md

@@ -1,12 +1,89 @@
 # Changelog
 
-+ **1.1.1 - _01/15/2017_
-  - Add `Brainstem.mysql_use_calc_found_rows` boolean config option to utilize MySQL's [FOUND_ROWS()](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_found-rows) functionality to avoid issuing a new query to calculate the record count, which has the potential to up to double the response time of the endpoint. 
++ **1.3.0** - _04/12/2018_
+  - Add the capability to nest fields under evaluable parent blocks where the nested fields are evaluated
+    with the resulting value of the parent field.
+    ```ruby
+        fields :tags, :array,
+               info: "The tags for the given category",
+               dynamic: -> (widget) { widget.tags } do |tag|
 
-+ **1.1.0 - _12/18/2017_
+          tag.field :name, :string,
+                    info: "Name of the assigned tag"
+        end
+    ```
+  - Add support for nested parameters on an endpoint.
+    ```ruby
+        model_params :post do |param|
+          ...
+
+          param.valid :message, :string, ...
+
+          param.model_params :rating do |rating_param|
+            ...
+
+            rating_param.valid :stars, :integer, ...
+          end
+
+          params.valid :replies, :array,
+                       item_type: :hash, ... do |reply_params|
+
+            reply_params.valid :message, :string,
+                               info: "the message of the post"
+
+            ...
+          end
+        end
+    ```
+  - Fix issue with nested fields being unable to have the same name as top level fields. 
+  - Support generation of markdown documentation for the nested block fields and nested parameters.
+
++ **1.2.0** - _03/29/2018_
+  - Add the capability to indicate an endpoint param is required with the `required` key in the options hash.
+  ```ruby
+        params.valid :message, :text,
+                     required: true,
+                     info: "the message of the post"
+  ```
+  - Add support for specifying the type of an endpoint param. For an endpoint param that has type `Array`,
+    type of list items can be specified using `item_type` key in the options hash.
+  ```ruby
+        params.valid :viewable_by, :array,
+                     item_type: :integer,
+                     info: "an array of user ids that can access the post"
+  ```
+  - Add support for specifying the data type of an item for a presenter field using `item_type` key in the
+    options hash when the field is of type `Array`.
+  ```ruby
+        field :aliases, :array,
+              item_type: :string,
+              info: "an array of user ids that can access the post"
+  ```
+  - Include the type and item type when generating markdown documentation for endpoint params.
+  - Specify the data type of a filter and available values with `items` key in the options hash. If filter is an array,
+    data type of items can be specified with the `item_type` property in options.
+  ```ruby
+        filter :status, :string,
+               items: ['Started', 'Completed'],
+               info: "only returns elements with the given status"
+
+        filter :sprocket_ids, :array,
+               item_type: :integer,
+               info: "returns objects associated with given sprocket Ids"
+  ```
+  - Add support for generating markdown documentation for the following:
+    - when the `required` option is specified on an endpoint param
+    - when the `type` and `item_type` params are specified on the endpoint param
+    - when the `type` and `item_type` params are specified on a presenter field
+    - when the `type` and `items` params are specified on a presenter filter
+
++ **1.1.1** - _01/15/2017_
+  - Add `Brainstem.mysql_use_calc_found_rows` boolean config option to utilize MySQL's [FOUND_ROWS()](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_found-rows) functionality to avoid issuing a new query to calculate the record count, which has the potential to up to double the response time of the endpoint.
+
++ **1.1.0** - _12/18/2017_
   - Add `meta` key to API responses which includes `page_number`, `page_count`, and `page_size` keys.
 
-+ **1.0.0 - _07/20/2017_
++ **1.0.0** - _07/20/2017_
   - Add the capability to generate the documentation extracted from your properly annotated
     presenters and controllers using `bundle exec brainstem generate [ARGS]`.
   - Update Brainstem to use Ruby version 2.3.3.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brainstem (1.1.1)
+    brainstem (1.3.0)
       activerecord (>= 4.1)
       activesupport (>= 4.1)
 
@@ -22,30 +22,30 @@ GEM
     arel (8.0.0)
     coderay (1.1.2)
     concurrent-ruby (1.0.5)
-    database_cleaner (1.6.2)
+    database_cleaner (1.6.1)
     db-query-matchers (0.9.0)
       activesupport (>= 4.0, <= 6.0)
       rspec (~> 3.0)
     diff-lcs (1.3)
-    i18n (0.9.1)
+    i18n (0.9.0)
       concurrent-ruby (~> 1.0)
     method_source (0.9.0)
-    minitest (5.11.1)
-    mysql2 (0.3.18)
+    minitest (5.10.3)
+    mysql2 (0.4.10)
     pry (0.9.12.6)
       coderay (~> 1.0)
       method_source (~> 0.8)
       slop (~> 3.4)
     pry-nav (0.2.4)
       pry (>= 0.9.10, < 0.11.0)
-    rake (12.3.0)
+    rake (12.2.1)
     redcarpet (3.4.0)
     rr (1.2.1)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
       rspec-expectations (~> 3.7.0)
       rspec-mocks (~> 3.7.0)
-    rspec-core (3.7.1)
+    rspec-core (3.7.0)
       rspec-support (~> 3.7.0)
     rspec-expectations (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -59,7 +59,7 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.4)
       thread_safe (~> 0.1)
-    yard (0.9.12)
+    yard (0.9.9)
 
 PLATFORMS
   ruby
@@ -68,7 +68,7 @@ DEPENDENCIES
   brainstem!
   database_cleaner
   db-query-matchers
-  mysql2
+  mysql2 (= 0.4.10)
   pry
   pry-nav
   rake

data/README.md

@@ -50,13 +50,13 @@ module Api
       default_sort_order "updated_at:desc"
 
       # Optional filter that applies a lambda.
-      filter :location_name do |scope, location_name|
+      filter :location_name, :string, items: [:sf, :la] do |scope, location_name|
         scope.joins(:locations).where("locations.name = ?", location_name)
       end
 
       # Filter with an overridable default. This will run on every request,
       # passing in `bool` as `false` unless a user has specified otherwise.
-      filter :include_legacy_widgets, default: false do |scope, bool|
+      filter :include_legacy_widgets, :boolean, default: false do |scope, bool|
         bool ? scope : scope.without_legacy_widgets
       end
 
@@ -66,11 +66,54 @@ module Api
 
       # Specify the fields to be present in the returned JSON.
       fields do
-        field :name, :string, info: "the Widget's name"
-        field :legacy, :boolean, info: "true for legacy Widgets, false otherwise", via: :legacy?
-        field :longform_description, :string, info: "feature-length description of this Widget", optional: true
-        field :updated_at, :datetime, info: "the time of this Widget's last update"
-        field :created_at, :datetime, info: "the time at which this Widget was created"
+        field :name, :string,
+              info: "the Widget's name"
+        field :legacy, :boolean,
+              info: "true for legacy Widgets, false otherwise",
+              via: :legacy?
+        field :longform_description, :string,
+              info: "feature-length description of this Widget",
+              optional: true
+        field :aliases, :array,
+              item_type: :string,
+              info: "the differnt aliases for the widget"
+        field :updated_at, :datetime,
+              info: "the time of this Widget's last update"
+        field :created_at, :datetime,
+              info: "the time at which this Widget was created"
+
+        # Fields can be nested under non-evaluable parent fields where the nested fields
+        # are evaluated with the presented model.
+        fields :permissions, :hash do |permissions_field|
+
+          # Since the permissions parent field is not evaluable, the can_edit? method is
+          # evaluated with the presented Widget model.
+          permissions_field.field :can_edit, :boolean,
+                                  via: :can_edit?,
+                                  info: "Indicates if the user can edit the widget"
+        end
+
+        # Specify nested fields within an evaluable parent block field. A parent block field
+        # is evaluable only if one of the following options :via, :dynamic or :lookup is specified.
+        # The nested fields are evaluated with the value of the parent.
+        fields :tags, :array,
+               item_type: :hash,
+               info: "The tags for the given category",
+               dynamic: -> (widget) { widget.tags } do |tag|
+
+          # The name method will be evaluated with each tag model returned by the the parent block.
+          tag.field :name, :string,
+                    info: "Name of the assigned tag"
+        end
+
+        fields :primary_category, :hash,
+               via: :primary_category,
+               info: "The primary category of the widget" do |category|
+
+          # The title method will be evaluated with each category model returned by the parent block.
+          category.field :title, :string,
+                         info: "The title of the category"
+        end
       end
 
       # Associations can be included by providing include=association_name in the URL.
@@ -78,8 +121,10 @@ module Api
       # columns on the model, otherwise the user must explicitly request associations
       # to avoid unnecessary loads.
       associations do
-        association :features, Feature, info: "features associated with this Widget"
-        association :location, Location, info: "the location of this Widget"
+        association :features, Feature,
+                    info: "features associated with this Widget"
+        association :location, Location,
+                    info: "the location of this Widget"
       end
     end
   end
@@ -447,11 +492,14 @@ class PostsPresenter < Brainstem::Presenter
   MARKDOWN
 
   associations do
-    association :author, User, info: "the author of the post"
+    association :author, User,
+                info: "the author of the post"
 
     # Temporarily disable documenting this relationship as we revamp the
     # editorial system:
-    association :editor, User, info: "the editor of the post", nodoc: true
+    association :editor, User,
+                info: "the editor of the post",
+                nodoc: true
   end
 end
 ```
@@ -489,17 +537,19 @@ context, and it will keep the documentation isolated to that specific action:
 
 ```ruby
 brainstem_params do
-  valid :global_controller_param,
-    info: "A trivial example of a param that applies to all actions."
+  valid :global_controller_param, :string,
+        info: "A trivial example of a param that applies to all actions."
 
   actions :index do
     # This adds a `blog_id` param to just the `index` action.
-    valid :blog_id, info: "The id of the blog to which this post belongs"
+    valid :blog_id, :integer,
+          info: "The id of the blog to which this post belongs"
   end
 
   actions :create, :update do
     # This will add an `id` param to both `create` and `update` actions.
-    valid :id, info: "The id of the blog post"
+    valid :id, :integer,
+          info: "The id of the blog post"
   end
 end
 ```
@@ -575,21 +625,55 @@ class BlogPostsController < ApiController
   brainstem_params do
 
     # Add an `:category_id` param to all actions in this controller / children:
-    valid :category_id, info: "(required) the category's ID"
+    valid :category_id, :integer,
+          info: "(required) the category's ID"
 
     # Do not document this additional field.
-    valid :lang,
-      info: "(optional) the language of the requested post",
-      nodoc: true
+    valid :lang, :string,
+          info: "(optional) the language of the requested post",
+          nodoc: true
+
 
     actions :show do
       # Declare a nested param under the `brainstem_model_name` root key,
       # i.e. `params[:blog_post][:id]`):
       model_params do |post|
-        post.valid :id, info: "(required) the id of the post"
+        post.valid :id, :integer,
+                   info: "the id of the post", required: true
+      end
+    end
+
+
+    actions :create do
+      model_params :post do |params|
+        params.valid :message, :string,
+                     info: "the message of the post",
+                     required: true
+
+        params.valid :viewable_by, :array,          
+                     item_type: :integer,
+                     info: "an array of user ids that can access the post"
+
+        # Declare a nested param with an explicit root key:, i.e. `params[:rating][...]`
+        model_params :rating do |rating_param|
+          rating_param.valid :stars, :integer,
+                             info: "the rating of the post"
+        end
+
+        # Declare nested array params with an explicit key:, i.e. `params[:replies][0][...]`
+        params.valid :replies, :array,
+                     item_type: :hash,
+                     info: "an array of reply params that can be created along with the post" do |reply_params|
+          reply_params.valid :message, :string,
+                             info: "the message of the post"
+          reply_params.valid :replier_id, :integer,
+                             info: "the ID of the user"
+          ...
+        end
       end
     end
 
+
     actions :share do
       # Declare a nested param with an explicit root key:, i.e. `params[:share][...]`
       model_param :share do
@@ -826,13 +910,13 @@ Brainstem provides a rich DSL for building presenters.  This section details the
 
   ```ruby
   # Optional filter that applies a lambda.
-  filter :location_name do |scope, location_name|
+  filter :location_name, :string do |scope, location_name|
     scope.joins(:locations).where("locations.name = ?", location_name)
   end
 
   # Filter with an overridable default. This will run on every request,
   # passing in `bool` as `false` unless a user has specified otherwise.
-  filter :include_legacy_widgets, default: false do |scope, bool|
+  filter :include_legacy_widgets, :boolean, default: false do |scope, bool|
     bool ? scope : scope.without_legacy_widgets
   end
   ```
@@ -892,6 +976,9 @@ Brainstem provides a rich DSL for building presenters.  This section details the
     field :dynamic_name, :string,
           info: "a formatted name for this Widget",
           dynamic: lambda { |widget| "This Widget's name is #{widget.name}" }
+    field :aliases, :array,
+          item_type: :string,
+          info: "the differnt aliases for the widget"
     field :longform_description, :string,
           info: "feature-length description of this Widget",
           optional: true
@@ -900,6 +987,16 @@ Brainstem provides a rich DSL for building presenters.  This section details the
     fields :permissions do
       field :access_level, :integer
     end
+
+    # Fields can be nested under executable parent blocks.
+    # Sub fields are evaluated with the value of the parent block.
+    fields :tags, :array,
+           info: "The tags for the given category",
+           dynamic: -> (widget) { widget.tags } do |tag|
+
+      tag.field :name, :string,
+                info: "Name of the assigned tag"
+    end
   end
   ```
 
@@ -946,12 +1043,12 @@ the `lookup` will be used.
   ```ruby
   associations do
     association :current_user_groups, Group,
-      info: "the Groups for the current user",
-      lookup: lambda { |models|
-        Group.where(subject_id: models.map(&:id)
-          .where(user_id: current_user.id)
-          .group_by { |group| group.subject_id }
-      }
+                info: "the Groups for the current user",
+                lookup: lambda { |models|
+                  Group.where(subject_id: models.map(&:id)
+                    .where(user_id: current_user.id)
+                    .group_by { |group| group.subject_id }
+                }
   end
   ```
 
@@ -963,15 +1060,15 @@ the `lookup` will be used.
   ```ruby
   fields do
     field :current_user_post_count, Post,
-      info: "count of Posts the current_user has for this model",
-      lookup: lambda { |models|
-        lookup = Post.where(subject_id: models.map(&:id)
-          .where(user_id: current_user.id)
-          .group_by { |post| post.subject_id }
-
-        lookup
-       },
-       lookup_fetch: lambda { |lookup, model| lookup[model.id] }
+          info: "count of Posts the current_user has for this model",
+          lookup: lambda { |models|
+            lookup = Post.where(subject_id: models.map(&:id)
+              .where(user_id: current_user.id)
+              .group_by { |post| post.subject_id }
+
+            lookup
+          },
+          lookup_fetch: lambda { |lookup, model| lookup[model.id] }
   end
   ```
 

data/brainstem.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "rr"
   gem.add_development_dependency "rspec", "~> 3.5"
   gem.add_development_dependency "sqlite3"
-  gem.add_development_dependency "mysql2"
+  gem.add_development_dependency "mysql2", "0.4.10"
   gem.add_development_dependency "database_cleaner"
   gem.add_development_dependency "yard"
   gem.add_development_dependency "pry"