re_sorcery 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b2890e5efcd2dbd01d5f849d9ba9887ac5c78077057b6406ae458ef3c048337
+  data.tar.gz: 3971c5c49f0c6d6bc0ac407b6b79091e1e2e9d16fa7d80c7deab0e12d3a94954
+SHA512:
+  metadata.gz: 6281d8f26287f854baccd61aa8e800dd27720053262b99380c5f2a26b4336b8bef238f7073722f8789d4da9b84f17a021df2e74030b64be995425c6cf5ae9f70
+  data.tar.gz: 546cc421b749cd28393494f10190bd34e9e7ed1ff5170b91a07724fccc94ece8351e03fc3d672e98e3c1e9908aa21abbdf91fc8eb86d0db2426ea9131eb7f0dd

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.3
+before_install: gem install bundler -v 2.0.2

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in re_sorcery.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    re_sorcery (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.3)
+    method_source (1.0.0)
+    minitest (5.14.4)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rake (10.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  re_sorcery!
+  minitest (~> 5.0)
+  pry
+  rake (~> 10.0)
+
+BUNDLED WITH
+   2.0.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Spencer Christiansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# ReSorcery
+
+> *Create resources with run-time payload type checking and link validation*
+
+Frontend clients can decode and type check `JSON` responses from their backends using packages like
+[Elm's Decoders] or [`jsonous` for TypeScript].
+
+[Elm's Decoders]: https://package.elm-lang.org/packages/elm/json/latest/Json-Decode
+[`jsonous` for TypeScript]: https://github.com/kofno/festive-possum/tree/main/packages/jsonous
+
+This is a similar package for the backend, so that Ruby can perform run-time payload type checking
+and link validation before sending resources to the client.
+
+- A `<resource>` is a `Hash` with a `:payload` field (a `Hash`) and a `:links` field (an
+  `Array` of `<link>` objects).
+- Each entry in the `:payload` is type checked using a `Decoder` (inspired by [Elm's Decoders]).
+- A `<link>` is a `Hash` with four fields:
+  - `:href`, which is either a `URI` or a `String` that parses as a valid `URI`;
+  - `:rel`, which is a white-listed `String`;
+  - `:method`, which is also a white-listed `String`; and
+  - `:type`, which is a `String`.
+
+Demo:
+
+```ruby
+class StaticResource
+  include ReSorcery
+  field :string, is(String), -> { "a string" }
+  field :number, is(Numeric), -> { 42 }
+  links do
+    link 'self', '/here'
+    link 'create', '/here', 'post'
+  end
+end
+
+StaticResource.new.resource
+# #<ReSorcery::Result::Ok @value={
+#   :payload=>{:string=>"a string", :number=>42},
+#   :links=>[{:rel=>"self", :href=>"/here", :method=>"get", :type=>"application/json"},
+#            {:rel=>"create", :href=>"/here", :method=>"post", :type=>"application/json"}]
+# }>
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 're_sorcery'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install re_sorcery
+
+## Usage
+
+```ruby
+class User
+  include ReSorcery
+
+  def initialize(**args)
+    @args = args
+  end
+
+  def admin?
+    @args[:admin] == true
+  end
+
+  field :name, String, -> { @args[:name] }
+  field :id, is(Integer).and { |i| i.positive? || '`id` must be positive' }, -> { @args[:id] }
+  field :admin?, is(true, false)
+
+  links do
+    link 'self', "/users/#{@args[:id]}"
+    link 'destroy', "/users/#{@args[:id]}", 'delete' unless admin? # Don't delete admins
+  end
+end
+
+User.new(name: "Spencer", id: 1, admin: true).as_json #=> {
+#   :payload=>{:name=>"Spencer", :id=>1, :admin?=>true},
+#   :links=>[
+#     {:rel=>"self", :href=>"/users/1", :method=>"get", :type=>"application/json"}
+#   ]
+# }
+
+# An invalid `name` raises an error when calling `as_json`
+User.new(name: :Invalid, id: 1).as_json
+# ReSorcery::Error::InvalidResourceError: Error at field `name` of `User`: Expected a(n) String, but
+# got a(n) Symbol
+```
+
+The implementation of `ReSorcery#as_json` raises an exception on invalid data, instead of serving
+the error message to the user as JSON.
+
+If you want to serve the error message to the user as JSON, use `ReSorcery#resource.as_json`, which
+will return a JSON representation of a `Result` object.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run
+the tests. You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`, which
+will create a git tag for the version, push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/spejamchr/re_sorcery.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "re_sorcery"
+require "pry"
+
+# 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.
+
+class Horse
+  include ReSorcery
+  attr_reader :name, :age, :children
+
+  def initialize(name, age, children)
+    @name = name
+    @age = age
+    @children = children
+  end
+
+  field :name, String
+  field :age, Numeric
+  field :children, array(Horse)
+
+  links do
+    link 'self', "/horses/#{name}"
+  end
+end
+
+class HorseCollection
+  include ReSorcery
+  attr_reader :person, :horses
+
+  def initialize(person, horses)
+    @person = person
+    @horses = horses
+  end
+
+  field :horses, array(Horse)
+
+  links do
+    link 'self', "/person/#{person.name}/horses" if person.kind == 'owner'
+  end
+end
+
+class Person
+  include ReSorcery
+  attr_reader :name, :age, :kind, :horses
+
+  def initialize(name, age, kind, horses)
+    @name = name
+    @age = age
+    @kind = kind
+    @horses = horses
+  end
+
+  field :name, String
+  field :age, Numeric
+  field :kind, is("owner", "jockey")
+  field :horses, HorseCollection, -> { HorseCollection.new(self, horses) }
+
+  links do
+    link 'self', "/users/#{name}"
+  end
+end
+
+def dave
+  Horse.new("Dave", 1, [])
+end
+
+def rigby
+  Horse.new("Rigby", 2, [])
+end
+
+def ruby
+  Horse.new("Ruby", 6, [dave, rigby])
+end
+
+def bad_horse
+  Horse.new("bad horse", 4, [bob])
+end
+
+def bob
+  Person.new("Bob", 70, "owner", [dave, rigby, ruby])
+end
+
+def jockey
+  Person.new("Jack", 23, "jockey", [dave, ruby])
+end
+
+def bab
+  Person.new("Bab", "bad", "owner", [dave, rigby, ruby])
+end
+
+def bab2
+  Person.new("Bob", 70, "owner", [dave, rigby, bad_horse])
+end
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/re_sorcery/arg_check.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ReSorcery
+  module ArgCheck
+    def self.[](name, value, *types)
+      return value if types.any? { |t| value.is_a?(t) }
+
+      fn = caller_locations.first.label
+      s = "`#{fn}` expected `#{name}` to be #{types.join(' or ')}; but got #{value.class}: #{value.inspect}"
+      raise ReSorcery::Error::ArgumentError, s
+    end
+  end
+  private_constant :ArgCheck
+end

data/lib/re_sorcery/configuration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ReSorcery
+  # Configure `ReSorcery`: All configuration kept in one place
+  #
+  # `ReSorcery` has some values that can be configured by users. To keep such
+  # configuration clear, and to prevent confusing behavior, `#configure` can
+  # only be called once, and must be called before `include`ing `ReSorcery`.
+  #
+  # Example:
+  #
+  #     ReSorcery.configure do
+  #       link_rels ['self', 'create', 'update']
+  #       link_methods ['get', 'post', 'put']
+  #     end
+  #
+  # @see `Configuration::CONFIGURABLES` for a list of what can be configured and
+  # what value each configurable takes.
+  #
+  module Configuration
+    extend Decoder::BuiltinDecoders
+
+    CONFIGURABLES = {
+      link_rels: array(String),
+      link_methods: array(String),
+    }.freeze
+
+    def configuration
+      @configuration ||= {}
+    end
+
+    def configure(&block)
+      raise Error::InvalidConfigurationError, @configured if configured?
+
+      @configured = "configured at #{caller_locations.first}"
+      instance_exec(&block)
+    end
+
+    private
+
+    def configured?
+      @configured ||= false
+    end
+
+    CONFIGURABLES.each do |name, decoder|
+      define_method(name) do |value|
+        decoder.test(value).cata(
+          ok: ->(v) { configuration[name] = v },
+          err: ->(e) { raise Error::ArgumentError, "Error configuring `#{name}`: #{e}" },
+        )
+      end
+    end
+  end
+end

data/lib/re_sorcery/decoder/builtin_decoders.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module ReSorcery
+  class Decoder
+    # Common decoders implemented here for convenience
+    module BuiltinDecoders
+      include Helpers
+
+      private
+
+      # A Decoder that always succeeds with a given value
+      def succeed(value)
+        Decoder.new { ok(value) }
+      end
+
+      # A decoder that always fails with some error message
+      def fail(message = '`fail` Decoder always fails')
+        ArgCheck['message', message, String]
+
+        Decoder.new { message }
+      end
+
+      # Test if an object is a thing (or one of a list of things)
+      #
+      # Convenience method for creating common types of `Decoder`s.
+      #
+      # @param [Decoder|Class|Module|unknown] thing
+      # @param [Array<Decoder|Class|Module|unknown>] others
+      #
+      # Accepts any number of arguments greater than 1. Call the list of
+      # arguments `things`.
+      #
+      # For each argument `thing` in `things`:
+      #
+      # - If `thing` is a Decoder, return it unchanged.
+      # - If `thing` is a Class or Module, create a Decoder that tests whether
+      #   an object `is_a?(thing)`.
+      # - Otherwise, create a Decoder that tests if an object equals `thing`
+      #   (using `==`).
+      #
+      # Then create a decoder that tests each of these decoders one by one
+      # against a given item until one passes or they have all failed.
+      #
+      # @return [Decoder]
+      def is(thing, *others)
+        things = [thing] + others
+        decoders = things.map { |t| make_decoder_from(t) }
+
+        Decoder.new do |instance|
+          test_multiple(decoders, instance).map_error do |errors|
+            errors.count == 1 ? errors[0] : "all decoders in `is` failed: (#{errors.join(' | ')})"
+          end
+        end
+      end
+
+      # Test that an object is an array of objects that pass the decoder `is(thing)`
+      #
+      # @param thing @see `is` for details
+      # @param others @see `is` for details
+      # @return [Decoder]
+      def array(thing, *others)
+        decoder = is(thing, *others)
+        Decoder.new do |instance|
+          is(Array).test(instance).and_then do |arr|
+            arr.each_with_index.inject(ok([])) do |result_array, (unknown, index)|
+              result_array.and_then do |ok_array|
+                decoder.test(unknown)
+                  .map { |tested| ok_array << tested }
+                  .map_error { |error| "Error at index `#{index}` of Array: #{error}" }
+              end
+            end
+          end
+        end
+      end
+
+      # Test that an object is a Maybe whose `value` passes some `Decoder`
+      #
+      # @param thing @see `is` for details
+      # @param others @see `is` for details
+      # @return [Decoder]
+      def maybe(thing, *others)
+        decoder = is(thing, *others)
+        Decoder.new do |instance|
+          is(Maybe::Just, Maybe::Nothing).test(instance).and_then do |maybe|
+            maybe
+              .map { |v| decoder.test(v).map { |c| just(c) } }
+              .get_or_else { ok(nothing) }
+          end
+        end
+      end
+
+      # Test that an object is a hash and has a field that passes a given decoder
+      def field(key, thing, *others)
+        key_decoder = is(thing, *others).map_error { |e| "Error at key `#{key}`: #{e}" }
+
+        is(Hash)
+          .and_then { Decoder.new { |u| u.key?(key) || "Expected key `#{key}` in: #{u.inspect}" } }
+          .and_then { Decoder.new { |u| key_decoder.test(u.fetch(key)) } }
+      end
+
+      def make_decoder_from(thing)
+        nillish = thing.nil? || thing == NilClass
+        raise ReSorcery::Error::ArgumentError, "Do not use `nil`" if nillish
+
+        case thing
+        when Decoder
+          thing
+        when Class, Module
+          Decoder.new { |n| n.is_a?(thing) || "Expected a(n) #{thing}, but got a(n) #{n.class}" }
+        else
+          Decoder.new { |n| n == thing || "Expected #{thing.inspect}, but got #{n.inspect}" }
+        end
+      end
+
+      def test_multiple(decoders, instance)
+        decoders.inject(err([])) do |error_array, decoder|
+          error_array.or_else do |errors|
+            decoder.test(instance).map_error { |error| errors << error }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/re_sorcery/decoder.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 're_sorcery/decoder/builtin_decoders'
+
+module ReSorcery
+  # Test that an object satisfies some property
+  #
+  # A `Decoder` represents a piece of logic for verifying some property. A
+  # simple example would be a `Decoder` that verifies that an object
+  # `is_a?(String)`. A `ReSorcery::Result` is used to represent the result
+  # of the logic. This can be created like:
+  #
+  #     is_string =
+  #       Decoder.new { |n| n.is_a?(String) ? ok(n) : err("Expected String, got #{n.class}") }
+  #
+  # And then used like:
+  #
+  #     is_string.test("I'm a string") #=> ok("I'm a string")
+  #     is_string.test(:symbol) #=> err("Expected String, got Symbol")
+  #
+  # Because returning the original object wrapped in `ok` is the common result
+  # when a `Decoder` passes, a shorthand in the initializer is to return
+  # `true`, and `Decoder` will wrap the object for you.
+  #
+  #     is_string =
+  #       Decoder.new { |n| n.is_a?(String) || err("Expected String, got #{n.class}") }
+  #
+  # A similar shorthand: Since the alternative is always something wrapped in
+  # `err`, if anything but `true` or a `Result` is returned, it will be wrapped
+  # in `err`.
+  #
+  #     is_string =
+  #       Decoder.new { |n| n.is_a?(String) || "Expected String, got #{n.class}" }
+  #
+  # All three of these implementations of `is_string` are equivalent.
+  #
+  # Note that this library has strong opinions against using `nil`, so `nil`
+  # will never pass `Decoder#test`.
+  #
+  class Decoder
+    include Helpers
+
+    def initialize(&block)
+      @block = block
+    end
+
+    # Use the decoder to `test` that an `unknown` object satisfies some property
+    #
+    # Note that `ok(nil)` will never be returned.
+    #
+    # @param [unknown] unknown
+    # @return [Result]
+    def test(unknown)
+      result = @block.call(unknown)
+      case result
+      when Result::Ok, Result::Err
+        result
+      when TrueClass
+        ok(unknown)
+      else
+        err(result)
+      end.and_then { |r| r.nil? ? err("`nil` was returned on a successful test!") : ok(r) }
+    end
+
+    # Apply some block within the context of a successful decoder
+    def map(&block)
+      Decoder.new { |unknown| test(unknown).map(&block) }
+    end
+
+    # Apply some block within the context of an unsuccessful decoder
+    def map_error(&block)
+      Decoder.new { |unknown| test(unknown).map_error(&block) }
+    end
+
+    # Chain decoders
+    #
+    # The second decoder can be chosen based on the (successful) result of the
+    # first decoder.
+    #
+    # The block must return a `Decoder`.
+    def and_then(decoder = nil, &block)
+      ArgCheck['decoder', decoder, Decoder] unless decoder.nil?
+
+      Decoder.new do |unknown|
+        test(unknown).and_then do |value|
+          # Don't try to re-assign `decoder` here, because it's captured from outside the Decoder
+          (decoder || ArgCheck['block.call(value)', block.call(value), Decoder]).test(unknown)
+        end
+      end
+    end
+
+    # If the `Decoder` failed, try another `Decoder`
+    #
+    # The block must return a `Decoder`.
+    def or_else(decoder = nil, &block)
+      ArgCheck['decoder', decoder, Decoder] unless decoder.nil?
+
+      Decoder.new do |unknown|
+        test(unknown).or_else do |value|
+          decoder ||= ArgCheck['block.call(value)', block.call(value), Decoder]
+
+          decoder.test(unknown)
+        end
+      end
+    end
+
+    # Chain decoders like `and_then`, but always with a specific decoder
+    def and(&block)
+      and_then { Decoder.new(&block) }
+    end
+
+    # Chain decoders like and_then, but use the chain to build an object
+    def assign(key, other)
+      ArgCheck['key', key, Symbol]
+      ArgCheck['other', other, Proc, Decoder]
+      other = ->(_) { other.call } if other.is_a?(Proc) && other.arity.zero?
+
+      and_then do |a|
+        ArgCheck['decoded value', a, Hash]
+
+        decoder = other.is_a?(Decoder) ? other : ArgCheck['other.call', other.call(a), Decoder]
+        decoder.map { |b| a.merge(key => b) }
+      end
+    end
+  end
+end

data/lib/re_sorcery/error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ReSorcery
+  module Error
+    class ReSorceryError < StandardError; end
+
+    class ArgumentError < ReSorceryError; end
+
+    class InvalidResourceError < ReSorceryError; end
+
+    class NonHashAssignError < ReSorceryError
+      def initialize(value)
+        super(value)
+        @value = value
+      end
+
+      def message
+        "#assign can only be used when the @value is a Hash, but was a(n) #{@value.class}"
+      end
+    end
+
+    class InvalidConfigurationError < ReSorceryError
+      def initialize(details)
+        @details = details
+      end
+
+      def message
+        "ReSorcery can only be configured once, and only before `include`ing ReSorcery, but was " +
+          @details
+      end
+    end
+  end
+end