introspective_grape 0.4.3 → 0.5.0

data/.ruby-version

@@ -1 +1 @@
-2.3.0
+2.5.0

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+0.5.0 10/20/2021
+================
+
+Bring support up to Rails 5.2.6 and ruby 2.6.2.
+
+All Virtus::Attribute::Boolean parameters should be declared Grape::API::Boolean instead.
+
+Change the filters on unique identifiers to Array[String] to support non-integer indeces,
+which is backwards compat with Array[Integer] as ActiveRecord's find coerces strings properly.
+
+Update Kaminari pagination declarations from
+
+  ``` paginate per_page: klass.pagination[:per_page]||25, max_per_page: klass.pagination[:max_per_page], offset: klass.pagination[:offset]||0```
+
+to
+
+  ``` use :pagination, per_page: klass.pagination[:per_page]||25, max_per_page: klass.pagination[:max_per_page], offset: klass.pagination[:offset]||0```
+
+
 0.4.1 10/20/2020
 ================
 

data/Gemfile

@@ -1,20 +1,18 @@
 source 'https://rubygems.org'
+gemspec
 
 # Declare your gem's dependencies in introspective_grape.gemspec.
 # Bundler will treat runtime dependencies like base dependencies, and
 # development dependencies will be added by default to the :development group.
-gemspec
-
-gem 'grape-kaminari', :github => 'alexey-klimuk/grape-kaminari'
 
-gem 'coveralls', require: false
 
 # Declare any dependencies that are still in development here instead of in
 # your gemspec. These might include edge Rails or gems from your path or
 # Git. Remember to move these dependencies to your gemspec before releasing
 # your gem to rubygems.org.
 
-group :development do
+group :development, :test do
   gem 'byebug'
   gem 'rb-readline'
+  gem 'coveralls_reborn', require: false
 end

data/README.md

@@ -1,79 +1,64 @@
 # IntrospectiveGrape
 
 [![Gem Version][GV img]][Gem Version]
-[![Build Status][BS img]][Build Status]
-[![Dependency Status][DS img]][Dependency Status]
 [![Coverage Status][CS img]][Coverage Status]
+[![Tests](https://github.com/buermann/introspective_grape/actions/workflows/test.yml/badge.svg)][Tests]
+[![Lints](https://github.com/buermann/introspective_grape/actions/workflows/lint.yml/badge.svg)][Lints]
 
+[Tests]: https://github.com/buermann/introspective_grape/actions
+[Lints]: https://github.com/buermann/introspective_grape/actions
 [Gem Version]: https://rubygems.org/gems/introspective_grape
-[Build Status]: https://travis-ci.org/buermann/introspective_grape
-[travis pull requests]: https://travis-ci.org/buermann/introspective_grape/pull_requests
-[Dependency Status]: https://gemnasium.com/buermann/introspective_grape
 [Coverage Status]: https://coveralls.io/r/buermann/introspective_grape
 
 [GV img]: https://badge.fury.io/rb/introspective_grape.png
-[BS img]: https://travis-ci.org/buermann/introspective_grape.png
-[DS img]: https://gemnasium.com/buermann/introspective_grape.png
 [CS img]: https://coveralls.io/repos/buermann/introspective_grape/badge.png?branch=master
 
+IntrospectiveGrape is a rails plugin for DRYing up
+[Grape APIs](https://github.com/ruby-grape/grape) by laying out simple
+(or, if you like, very complex) RESTful defaults based on the introspection of your database by
+[SchemaPlusValidations](https://github.com/SchemaPlus/schema_validations).
 
-IntrospectiveGrape is a Rails Plugin for DRYing up Grape APIs by laying out simple
-RESTful defaults based on the model definitions. If you use a schema validator
-like [SchemaPlus](https://github.com/SchemaPlus/schema_plus) it will, by
-extension, define your endpoints according to your database schema.
-
-It provides handling for deeply nested relations according to the models'
+IntrospectiveGrape provides handling for deeply nested relations according to the models'
 `accepts_nested_attributes_for` declarations, generating all the necessary
 boilerplate for flexible and consistent bulk endpoints on plural associations,
 and building nested routes for the same.
 
-It also snake cases everything coming in and camelizes parameters in your swagger docs
-by default if you `require 'introspective_grape/camel_snake'` in your API.
-This behavior can be disabled.
+It relies on [Kaminari](https://github.com/kaminari/kaminari) for pagination and [Pundit](https://github.com/varvet/pundit) for authorization, both of which are semi-optional.
+
+To facilitate idiomatic ruby and javascript, respectively, it also makes it easy to snakecase incoming parameters and camelize outputs, all the way through to your swagger docs.
 
-In addition it provides a `IntrospectiveGrape::Formatter::CamelJson` json formatter to
-recursively camelize the keys of all your outputs, so ruby and javascript developers
-can speak in their own idioms.
+NOTE: SchemaPlus is not currently being maintained and is unavailable for Rails > 2.5, and thus so is
+IntrospectiveGrape. Which is too bad! I don't know how anybody with a relational database gets by
+without it. We're working on it when we get the chance.
 
 ## Documentation
 
 In your Gemfile:
 
 ```
-gem 'grape-kaminari', :github => 'alexey-klimuk/grape-kaminari' # some middleware has fallen into deep disrepair
 gem 'introspective_grape'
 ```
 
 And bundle install.
 
-
 ## Grape Configuration
 
 ### Camelization
 
-IntrospectiveGrape's default behavior is to camelize all outputs and snake case all inputs. To camel case all your json output you'll need to use its formatter in your API:
+To camelcase your JSON outputs you'll need to use IntrospectiveGrape's formatter in your API:
 
 ```
-formatter :json, IntrospectiveGrape::Formatter::CamelJson
+require 'introspective_grape/camel_snake'
+class MyAPI < Grape::API
+  formatter :json, IntrospectiveGrape::Formatter::CamelJson
+end
 ```
 
-It also defaults to monkey patching Grape::Swagger to camelize the API's parameters in the swagger docs and, vice-versa, snake casing the parameters that are sent to your API.
-
-You can disable this behavior by setting `IntrospectiveGrape.config.camelize_parameters = false`.
+This also monkey patches Grape::Swagger to camelize your API's self-documentation, while snakecasing parameters passed to your API.
 
 To include this behavior in your test coverage you need to either access the API's params hash or you can format the response body to `JSON.parse(response.body).with_snake_keys` in a helper method with the `using CamelSnakeKeys` refinement.
 
-### Reloading an object after an update request
-
-By default the gem reloads the object instance before presenting the updated model, a lazy but
-effective workaround to updates that may not propagate in the working instance due to actions
-a user may take in hooks, or some updates to has_many :through associations. We want to put up
-APIs with haste rather than digging our way out of tricky minutae that can be handled later as
-technical debt.
-
-This behavior can be disabled by setting `IntrospectiveGrape.config.skip_object_reload = true`,
-when you have time for technical debt you can toggle it and work on fixing broken tests (you
-did take the time to write comprehensive test coverage, didn't you?).
+If you need to disable all camel-snake transliteration set `IntrospectiveGrape.config.camelize_parameters = false` down in `config/initializers` and do not `require` or `formatter` those patches.
 
 ## Authentication and authorization
 
@@ -88,7 +73,7 @@ Pundit authorization is invoked against index?, show?, update?, create?, and des
 The joke goes that you may find you need to allow an unauthenticated user to attempt a log in, which can be handled with something like:
 
 ```
- def authorize!
+  def authorize!
     unauthorized! unless current_user || login_request?
   end
 
@@ -98,7 +83,9 @@ The joke goes that you may find you need to allow an unauthenticated user to att
   end
 ```
 
-## Generate End Points for Models
+## Generating End Points for Models
+
+IntrospectiveGrape's parameterization of a model begins with the `restful` declaration, which expects an array of parameters that can be passed on to the model for update and create actions, including its nested models.
 
 The simplest app/api/v1/my_model_api.rb with the broadest functionality would look like:
 
@@ -117,17 +104,18 @@ class MyModelAPI < IntrospectiveGrape::API
     expose :nested, using: <NestedModel>Entity>
   end
 end
+
 ```
 
 This would set up all the basic RESTFUL actions with nested routes for the associated model and its association, providing a good deal of flexibility for API consumers out of the box.
 
 IntrospectiveGrape looks in the MyModelAPI class for grape-entity definitions. If you prefer to define your entities elsewhere you could inherit them here instead.
 
-Note that nested entities must be defined before their parents.
+NOTE: Nested entities must be defined before their parents, inside-out, or you'll run into loading errors.
 
 ## Customizing End Points
 
-Many simple customizations are available to carve out from the default behaviors:
+Many simple customizations are available to carve out behaviors from the expansive defaults:
 
 ```
 class MyModelAPI < IntrospectiveGrape::API
@@ -144,7 +132,7 @@ class MyModelAPI < IntrospectiveGrape::API
   filter_on :param
 
   restful MyModel, [:strong, :param, :fields, :and, { nested_model_attributes: [:nested,:fields, :_destroy] }] do
-    # Add additional end points to the model's namespace
+    # Here you can add additional end points to the model's namespace, or customize one you've recently excluded so you can implement a caching strategy.
   end
 
   class <NestedModel>Entity < Grape::Entity
@@ -158,10 +146,11 @@ class MyModelAPI < IntrospectiveGrape::API
 end
 ```
 
+Please note, again, that the nested Grape::Entity is declared before its parent.
 
 ## Skipping a Presence Validation for a Required Field
 
-If a model has, say, a procedurally generated default for a not-null field
+If a model has, say, a procedurally generated default for a not-null field in the database
 `skip_presence_validations` will make IntrospectiveGrape declare the parameter
 optional rather than required.
 
@@ -169,28 +158,48 @@ optional rather than required.
 
 By default any association included in the strong params argument will have all
 RESTful (`:index,:show,:create,:update, :destroy`) endpoints defined. These can
-be excluded (or conversely included) with the `exclude_actions` or `include_actions`
-declarations in the API class. You can also include or exclude :all or :none as shorthand.
+be excluded (or conversely included) with the `exclude_actions` (or `include_actions`)
+declarations in the API class.
+
+```
+  include_actions NestedModel, <:index,:show,:create,:update,:destroy>
+```
+
+You can also include or exclude `:all` or `:none` on the association as shorthand.
 
 ## Eager Loading
 
 Declaring `default_includes` on an activerecord class will tell IntrospectiveGrape which associations to eager load when fetching a collection or instance.
 
+If you can diagnose an N+1 problem then this ought to fix it.
+
+You can also eager load nested associations, if necessary:
+
+```
+  default_includes NestedModel, <associations for eager loading>
+```
+
 ## Pagination
 
-The index action by default will not be paginated, simply declared `paginate` before the `restful` declaration will enable [Kaminari](https://github.com/amatsuda/kaminari) pagination on the index results using a default 25 results per page with an offset of 0. You can pass Kaminari's options to the paginate declaration, `per_page`, `max_per_page`, etc.
+The index action by default will not be paginated. Simply declaring `paginate` before the `restful` declaration will enable [Kaminari](https://github.com/amatsuda/kaminari) pagination on the index results using a default 25 results per page with an offset of 0. You can pass Kaminari's options to the paginate declaration, `per_page`, `max_per_page`, etc.
+
+This will likewise add Kaminari's "X-" pagination headers to the response.
 
 ## Validating Virtual Attributes and Overriding Grape Validations
 
-To define a Grape param type for a virtual attribute or override the defaut param
-type from database introspection, define a class method in the model with the param
+Sometimes you need to break out of IntrospectiveGrape to handle behavior that is outside
+its scope, sometimes you just need to add an override or virtual attribute on the
+represented model to handled that behavior. Consider the latter first!
+
+To define a Grape param type for a virtual attribute or override the defaut param type
+from database introspection, define a class method in the model with the param
 types for the attributes specified in a hash, e.g.:
 
 ```
    def self.grape_param_types
     { "<attribute name 1>" => String,
       "<attribute name 2>" => Integer,
-      "<attribute name 3>" => Virtus::Attribute::Boolean }
+      "<attribute name 3>" => Grape::API::Boolean }
    end
 ```
 
@@ -205,6 +214,8 @@ class method ("grape_validations") that will be applied to that field's param de
   end
 ```
 
+Many bespoke behaviors can be relegated to the model via virtual attributes in this way.
+
 ## Validating JSON Parameters
 
 IntrospectiveGrape provides the following custom grape validators for JSON string parameters:
@@ -216,7 +227,7 @@ json_hash: true  # validates that the JSON string parses and returns a Hash
 ```
 
 
-## Filtering and Searching
+## Filtering and Searching on GET :index
 
 Simple filters on field values (and start and end values for timestamps) can be added with the `filter_on` declaration. Declaring `filter_on :all` will add filters for every attribute of the model.
 
@@ -226,7 +237,7 @@ class MyModelAPI < IntrospectiveGrape::API
 end
 ```
 
-Multiple values can be specified at once for Integer attributes that end in "id" (i.e.
+Multiple values can be queried for at once for attributes that end in "id" (i.e.
 conventional primary and foreign keys) by passing a comma separated list of IDs.
 
 For timestamp attributes it will generate `<name_of_timestamp>_start` and
@@ -237,7 +248,9 @@ this allows more complex filtering if one is familiar with ActiveRecord's query
 
 ### Overriding Filter Queries
 
-If, e.g., a field is some sort of complex composite rather than a simple field value you can override the default behavior (`where(field: params[field])`) by adding a query method on the model class:
+If, e.g., a field is some sort of complex composite rather than a simple field value you can
+override the default behavior (`where(field: params[field])`) by adding a query method on the
+model class:
 
 ```
 class MyAPI < IntrospectiveGrape::API
@@ -274,29 +287,48 @@ class MyModel
 end
 ```
 
+### Performance Tuning: IntrospectiveGrape defaults to reloading an object after any update!
+
+By default the gem reloads the object instance before presenting the updated model, a lazy but
+effective workaround to updates that may not propagate in the working instance due to actions
+a user may take in hooks or some updates to has_many :through associations. We want to put up
+APIs with haste rather than digging our way out of tricky minutae that can be handled later as
+technical debt.
+
+This behavior can be disabled by setting `IntrospectiveGrape.config.skip_object_reload = true`,
+when you have time for technical debt you can toggle it and work on fixing broken tests (you
+did take the time to write comprehensive test coverage, didn't you?).
+
+It is presently only an application wide configuration setting, not having made much use of it
+myself, but would be trivial to make more atomistic.
+
 ## Documenting Endpoints
 
 If you wish to provide additional documentation for end points you can define
-`self.<action>_documentation` class methods in the API class (or extend them from a module).
+`self.<index,show,update,create,destroy>_documentation` class methods in the API class (or extend them
+from a documentation module, which would be preferable).
 
-## Grape Hooks
+## Grape Hooks - The Precedence of Declaration Matters
 
 Grape only applies hooks in the order they were declared, so to hook into the default
 RESTful actions defined by IntrospectiveGrape you need to declare any hooks before the
 `restful` declaration, rather than inside its block, where the hook will only apply to
 your own subsequently declared endpoints.
 
-
 ## Dependencies
 
-Tool                  | Description
---------------------- | -----------
-[Grape]               | An opinionated micro-framework for creating REST-like APIs in Ruby
-[GrapeEntity]         | Adds Entity support to API frameworks, such as Grape.
-[GrapeSwagger]        | Swagger docs.
-[GrapeKaminari]       | Pagination.
-[Pundit]              | Minimal authorization through OO design and pure Ruby classes
-
+Tool                    | Description
+---------------------   | -----------
+[Rails]                 | A web-application framework using a Model-View-Controller pattern
+[SchemaValidations]     | Automatically defining validations based on the database schema
+[Grape]                 | An opinionated micro-framework for creating REST-like APIs in Ruby
+[GrapeEntity]           | Adds Entity support to API frameworks, such as Grape.
+[GrapeSwagger]          | Swagger docs.
+[GrapeKaminari]         | Pagination.
+[Pundit]                | Minimal authorization through OO design and pure Ruby classes
+
+[Rails]:         https://github.com/rails/rails
+[SchemaValidations]: https://github.com/SchemaPlus/schema_validations
 [Grape]:         https://github.com/ruby-grape/grape
 [GrapeEntity]:   https://github.com/ruby-grape/grape-entity
 [GrapeSwagger]:  https://github.com/ruby-grape/grape-swagger

data/Rakefile

@@ -14,13 +14,8 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
 load 'rails/tasks/engine.rake'
-
-
 load 'rails/tasks/statistics.rake'
 
-
-
 Bundler::GemHelper.install_tasks
-

data/introspective_grape.gemspec

@@ -1,51 +1,63 @@
-$:.push File.expand_path("../lib", __FILE__)
-
-# Maintain your gem's version:
-require "introspective_grape/version"
-#require "introspective_grape/api"
-
-# Describe your gem and declare its dependencies:
-Gem::Specification.new do |s|
-  s.name        = "introspective_grape"
-  s.version     = IntrospectiveGrape::VERSION
-  s.authors     = ["Josh Buermann"]
-  s.email       = ["buermann@gmail.com"]
-  s.homepage    = "https://github.com/buermann/introspective_grape"
-  s.summary     = "Introspectively configure deeply nested RESTful Grape APIs for ActiveRecord models."
-  s.description = "Introspectively configure deeply nested RESTful Grape APIs for ActiveRecord models."
-  s.license     = "MIT"
-
-  s.files         = `git ls-files`.split("\n").sort
-  s.test_files    = `git ls-files -- spec/*`.split("\n")
-
-  s.required_ruby_version = '>= 2.3'
-
-  s.add_runtime_dependency "rails", '> 5.0.0'
-  s.add_runtime_dependency "rack", '< 2.0.9' # grape < 1.3.0 is incompatible with rack 2.1.0
-  s.add_runtime_dependency 'grape', ['~> 1.2.0', '< 1.2.5']
-  s.add_runtime_dependency 'grape-entity'
-  s.add_runtime_dependency 'grape-swagger'
-  s.add_runtime_dependency 'kaminari' #, '< 1.0' # version 1.0.0 breaks
-  #s.add_dependency 'grape-kaminari', :github => 'alexey-klimuk/grape-kaminari'
-  # Pundit 2.0 mysteriously made authorize a protected method...
-  s.add_runtime_dependency 'pundit' #, '<2.0'
-  s.add_runtime_dependency 'camel_snake_keys', '>0.0.4'
-
-  if RUBY_PLATFORM == 'java'
-    #s.add_development_dependency "jdbc-sqlite3"
-    s.add_development_dependency "activerecord-jdbcsqlite3-adapter"
-  else
-    s.add_development_dependency "sqlite3", '<1.4.0' #'< 1.3.14'
-  end
-
-  #s.add_development_dependency "byebug"
-  #s.add_development_dependency "rb-readline"
-  s.add_development_dependency "rspec-rails", '>= 3.0'
-  s.add_development_dependency 'devise'
-  #s.add_development_dependency 'devise-async'
-  s.add_development_dependency 'paperclip', ">= 5.2.0" #'< 5.0'
-  s.add_development_dependency 'machinist_redux'
-  s.add_development_dependency 'simplecov'
-  s.add_development_dependency 'rufus-mnemo'
-
-end
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+
+# Maintain your gem's version:
+require 'introspective_grape/version'
+
+# Describe your gem and declare its dependencies:
+Gem::Specification.new do |s|
+  s.name        = 'introspective_grape'
+  s.version     = IntrospectiveGrape::VERSION
+  s.authors     = ['Josh Buermann']
+  s.email       = ['buermann@gmail.com']
+  s.homepage    = 'https://github.com/buermann/introspective_grape'
+  s.summary     = 'Quickly configure Grape APIs around your database schema and models.'
+  s.description = <<-DESC
+    IntrospectiveGrape provides handling for deeply nested relations according to the models'
+    `accepts_nested_attributes_for` declarations, generating all the necessary
+  boilerplate for flexible and consistent bulk endpoints on plural associations,
+    and building nested routes for the same.
+  DESC
+  s.license     = 'MIT'
+
+  s.files         = `git ls-files`.split("\n").sort
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+
+  s.required_ruby_version = '>= 2.5'
+
+  s.add_runtime_dependency 'rails', '~> 5.2'
+  s.add_runtime_dependency 'schema_validations'
+  s.add_runtime_dependency 'rack'
+
+  s.add_runtime_dependency 'grape'
+  s.add_runtime_dependency 'dry-types'
+  s.add_runtime_dependency 'grape-entity'
+  s.add_runtime_dependency 'grape-swagger'
+
+  s.add_runtime_dependency 'kaminari'
+  s.add_runtime_dependency 'grape-kaminari'
+
+  s.add_runtime_dependency 'pundit'
+
+  s.add_runtime_dependency 'camel_snake_keys', '>0.0.4'
+
+  if RUBY_PLATFORM == 'java'
+    s.add_development_dependency 'activerecord-jdbcsqlite3-adapter'
+  else
+    s.add_development_dependency 'sqlite3'
+  end
+
+  # testing gems
+  s.add_development_dependency 'rspec-rails', '>= 3.0'
+  s.add_development_dependency 'coveralls_reborn'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'bundler-audit'
+  s.add_development_dependency 'brakeman'
+  s.add_development_dependency 'rubocop'
+  s.add_development_dependency 'byebug'
+  s.add_development_dependency 'machinist_redux'
+
+  # dummy app dependencies
+  s.add_development_dependency 'paperclip'
+  s.add_development_dependency 'rufus-mnemo'
+  s.add_development_dependency 'devise'
+end