sober_swag 0.19.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63ab4c5db5ca2e6fe63713b7416d127b3bdc730e82562d4ca13b477eaf362460
-  data.tar.gz: ce6351db33dc3506be6baa66e228532bd8e3830c9e7b67b27c2c6b899a77677c
+  metadata.gz: 13d3f48bc3d3d8fb42984b13e7b260f0c5e52331cbc6b641b600511b67aed323
+  data.tar.gz: 32437d0fc96f42c5c05120946154108d0ffa2a6d9ad3fce648c8c49884addbce
 SHA512:
-  metadata.gz: bab9a59d19cef6552f33555a5cac081c750df97f0364d06fb39fbd5ad4973262f43ca233d52be1f0544815830345a59574dd4913ca2ec6cb2ef7f9e465502f35
-  data.tar.gz: f0e3db070ac4b30457d309d68a88c81b2cb090478553a622f9463e8cff9f3f67bb128f120ebcd9ce73164f21fb2e83b4a8befa02e87779e241fae96188ccc077
+  metadata.gz: 2e643f5d730c20eac9671c6e306f63c8c0b679dd26eab69a5eea91aa456c094f240399c7058d59300e7c333c3747980a814a7db43f979f2e800cdc9ef940f577
+  data.tar.gz: 4454eee231879d67313f1d9c1d1b094faf1131d3487f68d96fa1e529055ce48954ad8fa74eeef78b675baf7a4404afb778d607ce701b27a3e40bbeb513aaab15

data/.github/workflows/benchmark.yml

@@ -0,0 +1,39 @@
+name: Ruby Benchmark
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  benchmark:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: [ '2.6', '2.7', '3.0' ]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - uses: actions/cache@v2
+      with:
+        path: vendor/bundle
+        key: ${{ runner.os }}-${{ matrix.ruby }}-gem-deps-${{ hashFiles('**/Gemfile.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-${{ matrix.ruby }}-gem-deps-
+    - name: Install dependencies
+      run: |
+        bundle config path vendor/bundle
+        bundle install
+    - name: Run Benchmark
+      run: bundle exec ruby bench/benchmark.rb
+    - uses: actions/upload-artifact@v2
+      with:
+        name: benchmark-result
+        path: benchmark_results.yaml
+        if-no-files-found: error

data/.github/workflows/lint.yml

@@ -14,13 +14,11 @@ on:
     branches: [ master ]
 
 jobs:
-  test:
-
+  lint:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [ '2.6', '2.7' ]
-
+        ruby: [ '2.6', '2.7', '3.0' ]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby

data/.github/workflows/ruby.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: [ '2.6', '2.7' ]
+        ruby: [ '2.6', '2.7', '3.0' ]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby

data/.gitignore

@@ -15,3 +15,6 @@ Gemfile.lock
 *.gem
 
 /vendor/
+
+.yardoc
+benchmark_results.yaml

data/.rubocop.yml

@@ -2,10 +2,12 @@ require: rubocop-rspec
 
 AllCops:
   TargetRubyVersion: 2.6.0
+  NewCops: enable
   Exclude:
     - 'bin/bundle'
     - 'example/bin/bundle'
     - 'vendor/bundle/**/*'
+    - 'bin/console'
 
 Layout/LineLength:
   Max: 160
@@ -22,6 +24,9 @@ Metrics/BlockLength:
     - 'sober_swag.gemspec'
     - 'example/spec/**/*.rb'
 
+Lint/MissingSuper:
+  Enabled: false
+
 RSpec/ImplicitBlockExpectation:
   Enabled: false
 
@@ -123,4 +128,4 @@ Style/FrozenStringLiteralComment:
   Enabled: false
 
 Style/BlockDelimiters:
-  EnforcedStyle: braces_for_chaining
+  EnforcedStyle: braces_for_chaining

data/.yardopts

@@ -0,0 +1,7 @@
+--markup-provider=redcarpet
+--markup=markdown
+--plugin activesupport-concern
+--plugin solargraph
+--private
+--protected
+--files docs/serializers.md

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [v0.22.0] 2021-12-21
+
+- Added `SoberSwag::Reporting`, which is basically a v2 of the gem!
+  Docs for this can be found in [docs/reporting.md].
+
+## [v0.21.0] 2021-09-02
+
+- Added a new method of serializing views based on hash lookups, improving performance
+- Added a benchmarking suite
+- Added `except` parameter to the `merge` method, which allows a specified field to be excluded from the merge.
+- Add `type_key` to output objects, for easily serializing out type fields with a constant string.
+- Added `type_attribute` to `SoberSwag::InputObject` to add easy constant-value disambiguation.
+
+## [v0.20.0] 2021-05-17
+
+- Added YARD documentation to almost every method
+
+
 ## [v0.19.0] 2021-03-10
 
 - Use [redoc](https://github.com/Redocly/redoc) for generated documentation UI

data/Gemfile

@@ -4,3 +4,15 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in sober_swag.gemspec
 gemspec
+
+gem 'yard'
+
+gem 'redcarpet'
+
+gem 'yard-activesupport-concern'
+
+gem 'solargraph'
+
+gem 'benchmark-ips'
+
+gem 'rspec-its'

data/README.md

@@ -11,7 +11,7 @@ An introductory presentation is available [here](https://www.icloud.com/keynote/
 
 Further documentation on using the gem is available in the `docs/` directory:
 
-- [Serializers](docs/serializers.md)
+- {file:docs/serializers.md Serializers}
 
 ## Types for a fully-automated API
 

data/bench/benchmark.rb

@@ -0,0 +1,34 @@
+require 'bundler/setup'
+
+require 'sober_swag'
+
+require 'yaml'
+require 'benchmark/ips'
+
+##
+# Quick and dirty way to benchmark things.
+class Bench
+  class << self
+    def report(name, &block)
+      puts name
+
+      data[name] ||= Benchmark.ips(&block).data
+    end
+
+    def data
+      @data ||= {}
+    end
+
+    def write!(filename)
+      File.open(filename, 'w') do |f|
+        f << YAML.dump(data)
+      end
+    end
+  end
+end
+
+Dir['bench/benchmarks/**/*.rb'].sort.each do |file|
+  require_relative file.gsub(%r{^bench/}, '')
+end
+
+Bench.write!('benchmark_results.yaml')

data/bench/benchmarks/basic_field_serializer.rb

@@ -0,0 +1,21 @@
+##
+# Bench test for serializing multiple fields.
+class BasicFieldSerializer
+  Idea = Struct.new(:name, :grade, :cool)
+
+  Output = SoberSwag::OutputObject.define do
+    field :name, primitive(:String)
+    field :grade, primitive(:Integer)
+    field :cool, primitive(:Bool)
+  end
+
+  OutputSerializer = Output.serializer
+
+  MyIdea = Idea.new('Bob', 12, false)
+
+  Bench.report 'Basic Field Serializers' do |bm|
+    bm.report('Output Object') { Output.serialize(MyIdea) }
+    bm.report('Serializer of Output Object') { OutputSerializer.serialize(MyIdea) }
+    bm.compare!
+  end
+end

data/bench/benchmarks/view_selection.rb

@@ -0,0 +1,47 @@
+##
+# Benchmark for speed of selecting what view to use.
+class ViewSelection
+  Accomplishment = Struct.new(:name, :description)
+  Person = Struct.new(:first_name, :last_name, :accomplishments)
+
+  MyPerson = Person.new(
+    'Joeseph',
+    'Biden',
+    [
+      Accomplishment.new('Became President', 'Won a Presidential Election'),
+      Accomplishment.new('Oldest President', 'Oldest man to be elected president at time of election'),
+      Accomplishment.new('Became Senator', 'Got Elected to the Senate'),
+      Accomplishment.new('Youngest Senator', 'Youngest person elected Senator at time of election')
+    ]
+  )
+
+  AccomplishmentSerializer = SoberSwag::OutputObject.define do
+    field :name, primitive(:String)
+
+    view :detail do
+      field :description, primitive(:String)
+    end
+  end
+
+  PersonSerializer = SoberSwag::OutputObject.define do
+    field :first_name, primitive(:String)
+    field :last_name, primitive(:String)
+
+    # make a bunch of dummy views
+    1.upto(10).each { |n| view(:"view_#{n}") {} }
+
+    view :detail do
+      field :accomplishments, AccomplishmentSerializer.view(:detail)
+    end
+
+    1.upto(10).each { |n| view(:"view_after_#{n}") {} }
+  end
+
+  Bench.report 'View Selection' do |bm|
+    bm.report('With no view') { PersonSerializer.serialize(MyPerson) }
+
+    bm.report('With a view') { PersonSerializer.serialize(MyPerson, { view: :detail }) }
+
+    bm.compare!
+  end
+end

data/bin/console

@@ -9,11 +9,6 @@ Bio = SoberSwag.input_object do
   attribute :gender, SoberSwag::Types::String.enum('male', 'female') | SoberSwag::Types::String
 end
 
-Person = SoberSwag.input_object do
-  attribute :name, SoberSwag::Types::String
-  attribute? :bio, Bio.optional
-end
-
 MultiFloorLocation = SoberSwag.input_object do
   attribute :building, SoberSwag::Types::String.enum('science', 'mathematics', 'literature')
   attribute :floor, SoberSwag::Types::String
@@ -25,12 +20,37 @@ SingleFloorLocation = SoberSwag.input_object do
   attribute :room, SoberSwag::Types::Integer
 end
 
-SchoolClass = SoberSwag.input_object do
-  attribute :prof, Person.meta(description: 'The person who teaches this class.')
-  attribute :students, SoberSwag::Types::Array.of(Person)
-  attribute :location, (SingleFloorLocation | MultiFloorLocation).meta(description: 'What building and room this is in')
+SortDirections = SoberSwag::Types::CommaArray.of(SoberSwag::Types::String.enum('created_at', 'updated_at', '-created_at', '-updated_at'))
+
+# test
+class Whatever < SoberSwag::Reporting::Input::Struct
+  attribute :first_name, SoberSwag::Reporting::Input::Text.new
+  attribute :last_name, SoberSwag::Reporting::Input::Text.new
+  attribute? :father, SoberSwag::Reporting::Input::Null.new | SoberSwag::Reporting::Input::Defer.new(proc { Whatever }), description: 'if the father is in our db, will be present'
+  attribute? :mother, SoberSwag::Reporting::Input::Null.new | SoberSwag::Reporting::Input::Defer.new(proc { Whatever }), description: 'if the mother is in our db, will be present'
 end
 
-SortDirections = SoberSwag::Types::CommaArray.of(SoberSwag::Types::String.enum('created_at', 'updated_at', '-created_at', '-updated_at'))
+# Kinda neat thing
+class Otherwised < Whatever
+  attribute :ident, SoberSwag::Reporting::Input::Text.new.with_pattern(/^[A-Za-z0-9]+$/)
+end
+
+ArrayOfPeople = Otherwised.or(Whatever).list
+
+##
+# Output for a person
+class OutputPerson < SoberSwag::Reporting::Output::Struct
+  field :first_name, SoberSwag::Reporting::Output::Text.new
+  field :last_name, SoberSwag::Reporting::Output::Text.new
+  define_view :detail do
+    field :initials, SoberSwag::Reporting::Output::Text.new do |obj|
+      [obj.first_name, obj.last_name].map { |e| e[0..0] }.map { |e| "#{e}." }.join(' ')
+    end
+  end
+end
+
+Person = Struct.new(:first_name, :last_name)
+
+OutputPerson.view(:base)
 
 Pry.start

data/docs/reporting.md

@@ -0,0 +1,190 @@
+# SoberSwag Reporting
+
+`SoberSwag::Reporting` is a new module that provides a more *composable* interface of sober swag types.
+Unlike the base version, it is *not* based on `dry-types`, instead using a simpler scheme.
+It also allows for modeling of more complex type domains, and more reusable types.
+
+The module is called `SoberSwag::Reporting` because it *reports* what happened on failure.
+Consider trying to parse a struct with a first and last name, both of which need to be non-empty strings.
+If I give it this input:
+
+```json
+{
+  "first_name": 10,
+  "last_name": ""
+}
+```
+
+I will get back a report, which can tell me:
+
+```json
+{
+  "$.first_name": ["must be a string"],
+  "$.last_name": ["does not match pattern (.+)"]
+}
+```
+
+As you can see, we get a dictionary of JSON-path values to errors.
+
+More interestingly, you can use serializers in "reporting mode," which will *verify* that you're actually serializing what you said you would.
+If you mess up, it'll give you a report of where the errors were.
+This is intended to be used to make writing specs easier: to check that your serializer gives the right types, just use it in reporting mode and check the value!
+
+## Basic Design
+
+SoberSwag's reporting module is designed from the ground up to be *node-based*.
+Everything conforms to a common interface.
+For reporting *inputs*, all values:
+
+- Have a method `call` which converts an input to the desired format, or a report if there was an error
+- Have a method `call!` which converts an input to the desired format, or raises an exception if there was an error
+- Have a method `swagger_schema` which converts the node to its swagger schema.
+
+
+For reporting *outputs*, all values:
+
+- Have a method `call` which serializes out a value
+- Have a method `serialize_report` which serializes in "reporting mode," IE, it will return a report if serialization happened improperly
+- Have a method `views` which returns a *set of applicable views*.
+  This is used to implement a serializer with many alternatives.
+  These views *propagate* correctly.
+  So if you have views `[:base, :detail]` on a serializer for a person, a serializer for an array of people will have the same views.
+- Have a method `view` which takes in an argument, and returns a serializer specialized to that view.
+- Have a method `swagger_schema` which converts the node to its swagger schema
+
+From there, everything is done via composition.
+Nodes delegate to other nodes to provide functionality like "wrap this type in a common reference" and "validate that this string matches this regexp."
+Currently, the only validator built-in is matching a regexp or being a member of an enum, but we may add more in the future.
+You can also use `.mapped` to do custom validation:
+
+```ruby
+NotTheStringBob = SoberSwag::Reporting::Input.text.mapped do |text|
+  if text == "Bob"
+    Report::Value.new(['was the string bob I specifically told you not to be the string bob'])
+  else
+    text
+  end
+end
+```
+
+## Input Structs
+
+SoberSwag's reporting mode includes a class called `SoberSwag::Reporting::Input::Struct`.
+It can be used to model *struct inputs*, IE, inputs that have some properties and are represented by JSON objects.
+
+These structs behave much like Ruby structs, and implement inheritance *correctly*.
+This means that the following works:
+
+```ruby
+class Person < SoberSwag::Reporting::Input::Struct
+  attribute :first_name, SoberSwag::Reporting::Input.text
+  attribute :last_name, SoberSwag::Reporting::Input.text
+end
+
+class GradedPerson < Person
+  attribute :grade, SoberSwag::Reporting::Input.text.enum('A', 'B', 'C', 'D', 'F')
+end
+```
+
+## Output Structs
+
+SoberSwag's Reporting Output Structs work much the same way.
+You can define *fields* on them, which they will serialize.
+You can use them to define how to serialize an object, like so:
+
+```ruby
+class PersonOutput < SoberSwag::Output::Struct
+  field :first_name, SoberSwag::Reporting::Output.text
+  field :last_name, SoberSwag::Reporting::Output.text
+
+  field :grade, SoberSwag::Reporting::Output.text.nilable do
+    if object_to_serialize.respond_to?(:grade)
+      object_to_serialize.grade
+    else
+      nil
+    end
+  end
+
+  field :has_grade, SoberSwag::Reporting::Output.bool do
+    grade.nil? # fields are defined as *methods* on the output struct
+  end
+end
+```
+
+Output Structs can also have *views*.
+Views can be nested only once - if you use a serializer with views as the key of an object, we will *always* use the base view.
+This prevents some weirdness with the non-reporting SoberSwag serializers, where views could technically be read by child objects in some circumstances as they were only passed in the `view` key.
+A view will *always inherit all attributes of the parent object, regardless of order.*
+
+```ruby
+class AlternativePersonOutput < SoberSwag::Output::Struct
+  field :first_name, SoberSwag::Reporting::Output.text
+
+  view :with_grade do
+    field :grade, SoberSwag::Reporting::Output.text.nilable do
+      if object_to_serialize.respond_to?(:grade)
+        object_to_serialize.grade
+      else
+        nil
+      end
+    end
+  end
+
+  field :last_name, SoberSwag::Reporting::Output.text
+end
+
+AlternativePersonOutput.views # => Set.new(:base, :with_grade)
+AlternativePersonOutput.view(:with_grade).serialize(my_person) # includes the last_name field
+```
+
+View relationships are modeled with *composition*.
+This leads to slightly more natural to read swagger schemas.
+
+## Dictionary Types
+
+SoberSwag's reporting outputs allow defining a *dictionary* of key-value types.
+This lets you represent an object like this in your schema:
+
+```json
+{
+  "name": "Advanced Time Travel",
+  "student_grades": {
+    "student_id_1": "F",
+    "student_id_2": "F"
+  }
+}
+```
+
+This type would probably be represented by:
+
+```ruby
+class Classroom < SoberSwag::Reporting::Input::Struct
+  attribute :name, SoberSwag::Reporting::Input.text
+  attribute :student_grades, SoberSwag::Reporting::Input::Dictionary.of(
+    SoberSwag::Reporting::Input.text.enum('A', 'B', 'C', 'D', 'F')
+  )
+end
+```
+
+## Referenced Types
+
+If you have a type you use a lot, and you want to refer to it by a common name, you can describe it like so:
+
+```ruby
+GradeEnum = SoberSwag::Reporting::Input.text.enum('A', 'B', 'C', 'D', 'F').referenced('GradeEnum')
+```
+
+This will now be represented as a Reference type in generated swagger.
+
+## Things not present
+
+There are basically two things to keep in mind when upgrading to `SoberSwag::Reporting`.
+
+1. There is no longer a `default` for a type.
+   This is because that was really hard to model in Swagger, and can be better served via use of `.mapped` and `.optional`.
+   We may add this back eventually.
+2. Serializers no longer take an arbitrary `options` key.
+   Instead, view management is now *explicit*.
+   This is because it was too tempting to pass data to serialize in the options key, which is against the point of the serializers.
+
+

data/docs/serializers.md

@@ -105,7 +105,7 @@ This changes the type properly too.
 
 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.
+Consider, for example, an 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.
@@ -241,6 +241,9 @@ end
 Using `#merge` lets you add in all the fields from one output object into another.
 You can even use `merge` from within a view.
 
+Exclude any unneeded fields from the merge by passing a hash:
+`merge GenericBioOutput, { except: [:position] }`
+
 Note that `merge` does *not* copy anything but fields.
 Identifiers and views will not be copied over.
 

data/example/Gemfile

@@ -8,7 +8,7 @@ gem 'actionpack', '>= 6.0.3.2'
 # Use sqlite3 as the database for Active Record
 gem 'sqlite3', '~> 1.4'
 # Use Puma as the app server
-gem 'puma', '~> 5.2'
+gem 'puma', '~> 5.4'
 # Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
 # gem 'jbuilder', '~> 2.7'
 # Use Active Model has_secure_password
@@ -34,7 +34,7 @@ group :development, :test do
 end
 
 group :development do
-  gem 'listen', '>= 3.0.5', '< 3.5'
+  gem 'listen', '>= 3.0.5', '< 3.8'
   # Spring speeds up development by keeping your application running in the background. Read more: https://github.com/rails/spring
   gem 'spring'
   gem 'spring-watcher-listen', '~> 2.0.0'