sober_swag 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e58f142c7c7e5716d0d023844846ffcac306ff45f6ab84650cdf33003898ff83
-  data.tar.gz: 33e35fb1910ebe36f1618b2091e0cfb7762dbadbebaba046c8a67d3f58038e24
+  metadata.gz: bb2b4cc3cb2635010c4c3c0950e6ce87272046bf2e4cdbf08cf2e299518444b0
+  data.tar.gz: c407225c2c1c5abfadc3e074e5aba98ffb929dc47dda16f5f32293a73669c444
 SHA512:
-  metadata.gz: 747f4d9f9c0750de1a8109fb443bbe21df72929f74f447ce1473d676b2dcbc952c52dcc7731c6cd097d6f06452220ee808b883d4529da458b89baa2dde84ee76
-  data.tar.gz: 839284d0a57c363348e486320256c3f4d097b4c193eab3914416037a178a4a32e7b07e236e72b77376a68fce9715ffe62898a2b8ef7659fb9f2ccbf3a7b01378
+  metadata.gz: 3dbeeaec1ac6280e3029d779b31490a1661e436e87f833b4e5dce4c3eef96031e18988148aa48ebd1d849fe85353e93c1308f64a013c25d03424ad5b81041c8e
+  data.tar.gz: 51d0d80744d371cc51a2ba5497a9e8942d26a3e96a97625069476b12b612562fff00a0e371441c7851662e2f181a5ff9e33f0d4dcaecb92c233d6a8c4c07f66f

data/.github/config/rubocop_linter_action.yml

@@ -0,0 +1,5 @@
+check_name: 'Rubocop Lint'
+versions:
+  rubocop: 'latest'
+  rubocop-rspec: 'latest'
+

data/.github/workflows/lint.yml

@@ -0,0 +1,15 @@
+name: Linters
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Rubocop Linter
+      uses: andrewmcodes/rubocop-linter-action@v3.0.0
+      with:
+        action_config_path: '.github/config/rubocop_linter_action.yml' # Note: this is the default location
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/ruby.yml

@@ -27,7 +27,29 @@ jobs:
       uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
       with:
         ruby-version: 2.7
+    - uses: actions/cache@v2
+      with:
+        path: vendor/bundle
+        key: ${{ runner.os }}-gem-deps-${{ hashFiles('**/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-gem-deps-
     - name: Install dependencies
-      run: bundle install
+      run: |
+        bundle config path vendor/bundle
+        bundle install
     - name: Run tests
       run: bundle exec rake
+    - uses: actions/cache@v2
+      with:
+        path: example/vendor/bundle
+        key: ${{ runner.os }}-example-deps-${{ hashFiles('example/**/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-example-deps-
+    - name: Install example dependencies for example
+      working-directory: example
+      run: |
+        bundle config path vendor/bundle
+        bundle install
+    - name: Run specs for example
+      working-directory: example
+      run: rake

data/.gitignore

@@ -9,3 +9,6 @@
 
 # rspec failure tracking
 .rspec_status
+.ruby-version
+
+*.gem

data/.rubocop.yml

@@ -3,5 +3,77 @@ Style/FrozenStringLiteralComment:
 Style/BlockDelimiters:
   EnforcedStyle: braces_for_chaining
 AllCops:
-  TargetRubyVersion: 2.7.0
+  TargetRubyVersion: 2.7.1
+  Exclude:
+    - 'bin/bundle'
+    - 'example/bin/bundle'
+
+Layout/LineLength:
+  Max: 160
 require: rubocop-rspec
+RSpec/NamedSubject:
+  Enabled: false
+RSpec/DescribeClass:
+  Enabled: false
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+    - 'sober_swag.gemspec'
+    - 'example/spec/**/*.rb'
+RSpec/ImplicitBlockExpectation:
+  Enabled: false
+RSpec/ImplicitExpect:
+  EnforcedStyle: should
+Style/MultilineBlockChain:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Style/Documentation:
+  Exclude:
+    - 'example/db/migrate/**/*'
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+Lint/DuplicateElsifCondition:
+  Enabled: true
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+Lint/RaiseException:
+  Enabled: true
+Lint/StructNewOverride:
+  Enabled: true
+Style/AccessorGrouping:
+  Enabled: true
+Style/ArrayCoercion:
+  Enabled: true
+Style/BisectedAttrAccessor:
+  Enabled: true
+Style/CaseLikeIf:
+  Enabled: true
+Style/ExponentialNotation:
+  Enabled: true
+Style/HashAsLastArrayItem:
+  Enabled: true
+Style/HashEachMethods:
+  Enabled: true
+Style/HashLikeCase:
+  Enabled: true
+Style/HashTransformKeys:
+  Enabled: true
+Style/HashTransformValues:
+  Enabled: true
+Style/RedundantAssignment:
+  Enabled: true
+Style/RedundantFetchBlock:
+  Enabled: true
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+Style/RedundantRegexpEscape:
+  Enabled: true
+Style/SlicingWithRange:
+  Enabled: true

data/.ruby-version

@@ -1 +1 @@
-2.7.0
+2.7.1

data/Gemfile.lock

@@ -9,12 +9,13 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.0.2.1)
+    activesupport (6.0.3.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-      zeitwerk (~> 2.2)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    ast (2.4.1)
     coderay (1.1.2)
     concurrent-ruby (1.1.6)
     diff-lcs (1.3)
@@ -50,11 +51,17 @@ GEM
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
     method_source (0.9.2)
-    minitest (5.14.0)
+    minitest (5.14.1)
+    parallel (1.19.2)
+    parser (2.7.1.4)
+      ast (~> 2.4.1)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
+    rainbow (3.0.0)
     rake (13.0.1)
+    regexp_parser (1.7.1)
+    rexml (3.2.4)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -68,13 +75,28 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-support (3.9.2)
+    rubocop (0.88.0)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.7)
+      rexml
+      rubocop-ast (>= 0.1.0, < 1.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (0.1.0)
+      parser (>= 2.7.0.1)
+    rubocop-rspec (1.42.0)
+      rubocop (>= 0.87.0)
+    ruby-progressbar (1.10.1)
     simplecov (0.18.5)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
     simplecov-html (0.12.2)
     thread_safe (0.3.6)
-    tzinfo (1.2.6)
+    tzinfo (1.2.7)
       thread_safe (~> 0.1)
+    unicode-display_width (1.7.0)
     zeitwerk (2.3.0)
 
 PLATFORMS
@@ -85,8 +107,10 @@ DEPENDENCIES
   pry
   rake (~> 13.0)
   rspec (~> 3.0)
+  rubocop
+  rubocop-rspec
   simplecov
   sober_swag!
 
 BUNDLED WITH
-   2.1.2
+   2.1.4

data/README.md

@@ -1,7 +1,116 @@
 # SoberSwag
 
 ![Ruby Test Status](https://github.com/SonderMindOrg/sober_swag/workflows/Ruby/badge.svg?branch=master)
+![Linters Status](https://github.com/SonderMindOrg/sober_swag/workflows/Linters/badge.svg?branch=master)
+
+***NOTE: THIS GEM IS HIGHLY EXPERIMENTAL AND PROBABLY SHOULD NOT YET BE USED IN PRODUCTION***.
 
 SoberSwag is a combination of [Dry-Types](https://dry-rb.org/gems/dry-types/1.2/) and [Swagger](https://swagger.io/) that makes your Rails APIs more awesome.
 Other tools generate documenation from a DSL.
 This generates documentation from *types*, which (conveniently) also lets you get supercharged strong-params-on-steroids.
+
+An introductory presentation is available [here](https://www.icloud.com/keynote/0bxP3Dn8ETNO0lpsSQSVfEL6Q#SoberSwagPresentation).
+
+This gem uses pattern matching, and is thus only compatible with Ruby 2.7 or later.
+
+## Types for a fully-automated API
+
+SoberSwag lets you type your API using describe blocks.
+In any controller that includes `SoberSwag::Controller`, you get access to the super-cool DSL method `define`.
+This lets you type your API endpoint:
+
+```ruby
+  class PeopleController < ApplicationController
+    include SoberSwag::Controller
+    define :patch, :update, '/people/{id}' do
+      query_params do
+        attribute? :include_extra_info, Types::Params::Bool
+      end
+      request_body do
+        attribute? :name, Types::Params::String
+        attribute? :age, Types::Params::Integer
+      end
+      path_params { attribute :id, Types::Params::Integer }
+    end
+  end
+```
+
+We can now us this information to generate swagger documentation, available at the `swagger` action on this controller.
+More than that, we can use this information *inside* our controller methods:
+
+```ruby
+def update
+  @person = Person.find(parsed_path.id)
+  @person.update!(parsed_body.to_h)
+end
+```
+
+No need for `params.require` or anything like that.
+You define the type of parameters you accept, and we reject anything that doesn't fit.
+
+### Typed Responses
+
+Want to go further and type your responses too?
+Use SoberSwag blueprints, a serializer library heavily inspired by [OutputObjecter](https://github.com/procore/blueprinter)
+
+```ruby
+PersonOutputObject = SoberSwag::OutputObject.define do
+  field :id, primitive(:Integer)
+  field :name, primitive(:String).optional
+  field :is_registered, primitive(:Bool) do |person|
+    person.registered?
+  end
+end
+```
+
+Now, in your `define` block, you can tell us that this is the *type* of your response:
+
+```ruby
+class PeopleController < ApplicationController
+  include SoberSwag::Controller
+  define :patch, :update, '/people/{id}' do
+    request_body do
+      attribute? :name, Types::Params::String
+      attribute? :age, Types::Params::Integer
+    end
+    path_params { attribute :id, Types::Params::Integer }
+    response(:ok, 'the updated person', PersonOutputObject)
+  end
+  def update
+    person = Person.find(parsed_path.id)
+    if person.update(parsed_body.to_h)
+      respond!(:ok, person)
+    else
+      render json: person.errors
+    end
+  end
+end
+```
+
+Support for easily typing "render the activerecord errors for me please" is (unfortunately) under development.
+
+### SoberSwag Structs
+
+Input parameters (including path, query, and request body) are typed using [dry-struct](https://dry-rb.org/gems/dry-struct/1.0/).
+You don't have to do them inline: you can define them in another file, like so:
+
+```ruby
+User = SoberSwag.struct do
+  attribute :name, SoberSwag::Types::String
+  # use ? if attributes are not required
+  attribute? :favorite_movie, SoberSwag::Types::String
+  # use .optional if attributes may be null
+  attribute :age, SoberSwag::Types::Params::::Integer.optional
+end
+```
+
+Under the hood, this literally just generates a subclass of `Dry::Struct`.
+We use the DSL-like method just to make working with Rails' reloading less annoying.
+
+## Special Thanks
+
+This gem is a mismatch of ideas from various sources.
+The biggest thanks is owed to the [dry-rb](https://github.com/dry-rb) project, upon which the typing of SoberSwag is based.
+On an API design level, much is owed to [blueprinter](https://github.com/procore/blueprinter) for the serializers.
+The idea of a strongly-typed API came from the Haskell framework [servant](https://www.servant.dev/).
+Generating the swagger documenation happens via the use of a catamorphism, which I believe I first really understood thanks to [this medium article by Jared Tobin](https://medium.com/@jaredtobin/practical-recursion-schemes-c10648ec1c29).

data/bin/console

@@ -3,7 +3,6 @@
 
 require 'bundler/setup'
 require 'sober_swag'
-require 'dry-struct'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -11,28 +10,30 @@ module Types
   include Dry.Types()
 end
 
-class Bio < Dry::Struct
-  attribute :name, Types::String
+Bio = SoberSwag.input_object do
+  attribute :name, primitive(:String).meta(description: 'A very basic bio name')
 end
 
-class Person < Dry::Struct
-  attribute :name, Types::String
-  attribute :age, Types::Integer.constrained(gt: 0).optional | Types::String.optional
+Person = SoberSwag.input_object do
+  attribute :name, primitive(:String).meta(description: 'The full name description')
+  attribute :age, param(:Integer).constrained(gt: 0).optional.meta(description: 'My cool age')
   attribute? :mood, Types::String
-  attribute :bio, Bio
-
-  attribute :foo do
-    attribute :bar, Types::String
-    attribute :baz, Types::String.optional
-  end
 end
 
-class PersonSearch < Dry::Struct
+##
+# Demonstration of subclass-style.
+class PersonSearch < SoberSwag::InputObject
   attribute? :name, Types::String
   attribute? :age, Types::Integer
 end
 
+##
+# Demonstration of subclass-style *and* recursion in structs.
+class LinkedList < SoberSwag::InputObject
+  attribute :value, Types::String
+  attribute? :next, LinkedList
+end
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-require "pry"
+require 'pry'
 Pry.start

data/docs/serializers.md

@@ -0,0 +1,203 @@
+# Serializers
+
+Serializers are a way to transform from one type to another.
+For example, you might want to change an ActiveRecord object to a JSON struct.
+You might also want to change an internal date-interval into a two-element array of dates, or some custom text format.
+You can do all of these things with SoberSwag serializers.
+Furthermore, Serializers document the *type* that they serialize, so you can use it to degenerate documentation.
+
+## The Basics
+
+All serializers are inherted from [`SoberSwag::Serializer::Base`](../lib/sober_swag/serializer/base.rb).
+This is an abstract class that implements several methods, most of which will be documented later.
+The two that are most interesting, however, are `#type` and `#serialize`.
+
+The first, `#type`, returns a SoberSwag-compatible type definition.
+This might be an instance of `SoberSwag::Struct`, or something else.
+You'll never need to implement this yourself, but you should note that we generally do not *enforce* these types *at serialization time*.
+This might change in the future, likely under a debug flag.
+
+The second, `#serialize`, does the actual work of serialization.
+It takes *two arguments*.
+The first is the argument that we will transform into the output type.
+The second is *always* optional, and is a *hash of options* to use to customize serialization.
+For example, you might have a serializer that can return a date in two formats, depending on a boolean flag.
+In this case, it might be used as:
+
+```ruby
+serializer.new(my_record, { format: :newstyle })
+```
+
+However, since it is *always* optional, you can also do:
+
+```ruby
+serilaizer.new(my_record)
+```
+
+And it *should* pick some default format.
+
+### Primitives
+
+Primitive serializers, or "identity serializers," are serializers that do nothing.
+They are implemented as [`SoberSwag::Serializer::Primitive`](../lib/sober_swag/serializer/primitive.rb), or as the `#primitive` method on a `OutputObject`.
+Since they don't do anything, they can be considered the most "basic" serializer.
+
+These serializers *do not* check types.
+That is, the following code will not throw an error:
+
+```ruby
+serializer = SoberSwag::Serializer::Primitive.new(SoberSwag::Types::String)
+serializer.serialize(10) # => 10
+```
+
+Thus, care should be used when working with these serializers.
+In the future, we might add some "debug mode" sorta thing that will do type-checking and throw errors, however, the cost of doing so in production is probably not worth it.
+
+### Mapped
+
+Sometimes, you can create a serilaizer via a *proc*.
+For example, let's say that I want a serializer that takes a `Date` and returns a string.
+I can do this:
+
+```ruby
+date_string = SoberSwag::Serializer.Primitive(:String).via_map { |d| d.to_s }
+```
+
+This is implemented via [`SoberSwag::Serializer::Mapped`](../lib/sober_swag/serializer/mapped.rb).
+Basically, it uses your given proc to do serialization.
+
+Once again, this does not do type-checking.
+In the future, we might add a debug mode.
+
+### Optional
+
+Oftentimes, we want to give a serializer the ability to serialize `nil` values.
+This is often useful in serializing fields.
+
+It turns out that it's pretty easy to make a serializer that can serialize `nil` values: just propogate nils.
+For example, let's say I have the following code:
+
+```ruby
+Foo = Struct.new(:bar, :baz)
+my_serializer.serialize(Foo.new(10, 11)) # => { bar: 10, baz: 11 }
+# ^ my_serializer is defined elsewhere
+my_serializer.optional.serialize(Foo.new(10, 11)) # => { bar: 10, baz: 11 }
+# ^ can serialize the type from before
+my_serializer.optional.serialize(nil) # => nil
+# ^ nils become nil
+```
+
+This properly changes the `type` to be a nillable type, as well.
+
+### Array
+
+Oftentimes, if we have a serializer for a single value, we want to serialize an array of values.
+You can use the `#array` method on a serializer to get that.
+Continuing our example from earlier:
+
+```ruby
+my_serializer.array.serialize([Foo.new(10, 11)]) #=> [{ bar: 10, baz: 11 }]
+```
+
+This changes the type properly, too.
+
+## OutputObjects
+
+98% of the time, when we're writing web APIs, we want to transform our domain objects into JSON objects.
+We often want different ways to do this, too.
+Consider, for exmaple, and API for a college.
+We might want to provide one detailed way to serialize a student, which includes their full name, grade, student ID, GPA, and so on.
+On another page, we might want to display a classroom with a list of students.
+However, on the classroom page, we don't want to serialize a full student: that's sending too much data.
+Instead, we probably want to serialize a "stub" view.
+
+OutputObjects are the answer to these problems.
+They're a way to define a serializer for a JSON object, along with a type, and to define "variant" ways to serialize things.
+
+
+### The Basics
+
+Let's define an output object:
+
+```ruby
+StudentOutputObject = SoberSwag::OutputObject.define do
+  field :first_name, Primitive(:String)
+  field :last_name, Primitive(:String)
+  field :recent_grades, Primitive(:Integer).array do |student|
+    student.graded_assignments.limit(100).pluck(:grade)
+  end
+end
+```
+
+We can see a few things here:
+
+1. You define field names with a `field` definition, which is a way to define the serializer for a single field.
+2. You must provide types with field names
+3. You can use blocks to do data formatting, which lets you pick different fields and such.
+
+### Views
+
+Sometimes, you might want to add "variant" ways to look at data.
+We call these "views," based on the output objecter concept.
+Let's take a look at their use:
+
+```ruby
+StudentOutputObject = SoberSwag::OutputObject.define do
+  field :first_name, Primitive(:String)
+  field :last_name, Primitive(:String)
+  view :detail do
+    field :recent_grades, Primitive(:Integer).array do |student|
+      student.graded_assignments.limit(100).pluck(:grade)
+    end
+  end
+ end
+
+StudentOutputObject.serialize(my_student) # => { first_name: 'Rich', last_name: 'Evans' }
+StudentOutputObject.serialize(
+  my_student,
+  { view: :detail }
+) # => { first_name: 'Rich', last_name: 'Evans', recent_grades: [0, 0, 0, 1] }
+```
+
+The options hash of the serializer will be used to determine which view to serialize with.
+Handily, each view is actually *its own* serializer.
+You can obtain a serializer for a single view very easily:
+
+```ruby
+StudentOutputObject.view(:detail)
+```
+
+If you want an output object without the view-checking behavior, you can use `.base` on an output object.
+
+```ruby
+StudentOutputObject.base
+```
+
+Both of these are great for defining *relationships* between data.
+
+### Circular OutputObjects
+
+Sometimes, you might want to include an output object inside another output object, that itself has that output object inside it.
+Or, less confusingly, you wanna do this:
+
+```ruby
+StudentOutputObject = SoberSwag::OutputObject.define do
+  # some other fields
+  view :detail do
+    field :classes, ClassOutputObject.array
+  end
+end
+```
+
+This can cause a circular dependecy.
+To break this, you can use a lambda:
+
+```ruby
+StudentOutputObject = SoberSwag::OutputObject.define do
+  view :detail do
+    field :classes, -> { ClassOutputObject.view(:base).array }
+  end
+end
+```
+
+For clarity (and to prevent infinitely-looping serializers on accident, we reccomend you *always* use an explicit view for dependent output objects.