snfoil-controller 1.0.0

data/README.md

@@ -0,0 +1,537 @@
+# SnFoil::Controller
+
+![build](https://github.com/limited-effort/snfoil-controller/actions/workflows/main.yml/badge.svg) [![maintainability](https://api.codeclimate.com/v1/badges/10885d7b7231f3e9b0b7/maintainability)](https://codeclimate.com/github/limited-effort/snfoil-controller/maintainability)
+
+SnFoil Controllers help seperate your business logic from your api layer.  
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'snfoil-controller'
+```
+
+## Usage
+Ultimately SnFoil Controllers are just SnFoil Contexts, but they setup their workflow a little differently.  `endpoint` creates `setup_*` and `process_*` intervals to handle your data, and the method or block provided renders it.
+
+### Quickstart Example
+
+```ruby
+# app/controllers/people_controller.rb
+
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  context PeopleContext
+  serializer PeopleSerializer
+  context PeopleDeserializer
+
+  endpoint :create, do |object:, **options|
+    if object.errors
+      render json: object.errors, status: :unprocessable_entity
+    else
+      render json: serialize(object, **options), status: :created
+    end
+  end
+
+  endpoint :update, do |object:, **options|
+    if object.errors
+      render json: object.errors, status: :unprocessable_entity
+    else
+      render json: serialize(object, **options), status: :ok
+    end
+  end
+
+  endpoint :show, do |object:, **options|
+    render json: serialize(object, **options), status: :created
+  end
+
+  endpoint :delete, do |object:, **options|
+    if object.errors
+      render json: object.errors, status: :unprocessable_entity
+    else
+      render json: {}, status: :no_content
+    end
+  end
+
+  setup_create { |**options| options[:params] = deserialize(params, **options) }
+  setup_update { |**options| options[:params] = deserialize(params, **options) }
+
+  process_create { |**options| run_context(**options) }
+  process_update { |**options| run_context(**options) }
+  process_show { |**options| run_context(**options) }
+  process_delete { |**options| run_context(**options) }
+end
+```
+
+### Controller
+
+A controller is a combination of a Context, Serializer, Deserializer, and a some Endpoints.  See the Quickstart exaple above and the description of functions below for more details.
+
+##### Ussing SSR
+
+You don't need a serializer.  You can just use a standard render in the endpoint's function. 
+
+```ruby
+# taken from https://guides.rubyonrails.org/layouts_and_rendering.html
+
+class BooksController < ApplicationController
+  def index
+    @books = Book.all
+  end
+end
+
+# becomes
+
+class BooksController < ApplicationController
+  include SnFoil::Controller
+
+  endpoint(:index) { |**options| @books = Book.all }
+end
+
+```
+
+#### Endpoint
+
+Endpoint creates a workflow with two intervals and a primary function for rendering.
+
+
+```ruby
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  endpoint(:create) { |**options| render json: options[:object] }
+end
+```
+
+In this exmaple the `setup_create` and `process_create` intervals are defined for you and the method finally returns the block.  If you don't want to provide a block you can instead pass in a method name
+
+```ruby
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  endpoint(:create, with: :render_create)
+  
+  def render_create(**options)
+    render json: options[:object]
+  end
+end
+```
+
+Any options passed in as arguements to endpoint will be passed to the intervals and flow through just like a Context (becuase it is a Context under the hood).
+
+```ruby
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  endpoint(:create, with: :render_create, interesting: 'key you have there')
+
+  setup_create do |**options|
+    puts options[:interesting] # => 'key you have there'
+    ...
+  end
+end
+```
+##### Arguments
+
+<table>
+  <thead>
+    <th>name</th>
+    <th>type</th>
+    <th>description</th>
+    <th>required</th>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td>name</td>
+      <td>string|symbol</td>
+      <td>The name of the method to be defined on the controller and the intervals</td>
+      <td>true</td>
+    </tr>
+    <tr>
+      <td>options</td>
+      <td>keyword arguments</td>
+      <td>The options you want passed down the chain of intervals and to the context</td>
+      <td>false</td>
+    </tr>
+    <tr>
+      <td>block</td>
+      <td>proc</td>
+      <td>The function you want to render your controller action</td>
+      <td>conditionally based on if you don't provide a `:with` in the only</td>
+    </tr>
+  </tbody>
+</table>
+
+There are a few reserved keyword arguements that cause different functionlity/configuration for options:
+
+* `with` - The method name to use if a block is not provided to the endpoint
+* `context` - The context to use for this endpoint.  Overrides the one configured using #self.context
+* `context_action` - The method name to call on the context.  Defaults to the endpoint name.
+* `serializer` - The serializer to use for this endpoint. Overrides the one configured using #self.serializer
+* `serialize` - The block used to process the serializer. Overrides the one configured using #self.serializer
+* `serialize_with` - The method used to process the serializer. Overrides the one configured using #self.serializer
+* `deserializer` - The deserializer to use for this endpoint. Overrides the one configured using #self.deserializer
+* `deserialize` - The block used to process the deserializer. Overrides the one configured using #self.deserializer
+* `deserialize_with` - The method used to process the deserializer. Overrides the one configured using #self.deserializer
+
+#### Context
+
+The main context intended to be called by the Controller.
+
+```ruby
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  context PeopleContext
+end
+```
+##### Arguments
+
+<table>
+  <thead>
+    <th>name</th>
+    <th>type</th>
+    <th>description</th>
+    <th>required</th>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td>name</td>
+      <td>class</td>
+      <td>The context class for the controller</td>
+      <td>true</td>
+    </tr>
+  </tbody>
+</table>
+
+#### Serializer
+
+The main serializer intended to be called by the Controller.  Also the default serializer and block used by the '#serialize` method.
+
+```ruby
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  serializer PeopleSerializer
+end
+```
+##### Arguments
+
+<table>
+  <thead>
+    <th>name</th>
+    <th>type</th>
+    <th>description</th>
+    <th>required</th>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td>name</td>
+      <td>class</td>
+      <td>The serializer class for the controller</td>
+      <td>false</td>
+    </tr>
+    <tr>
+      <td>block</td>
+      <td>proc</td>
+      <td>The block to be called to serialize the data</td>
+      <td>false</td>
+    </tr>
+  </tbody>
+</table>
+
+##### Default Call
+
+If no block or method is provided, `#serialize` will try to new up the Serializer class with arguments `object` and `options` and call `#to_hash`.
+
+```ruby
+Serializer.new(object, **options).to_hash
+```
+
+##### Passing in a Block
+
+If you provide a block to the `#self.serializer` method you can define how you want the serializer to be called.
+
+```ruby
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  serializer(PeopleSerializer) { |object, serializer, **_options| serializer.new(object).serialize }
+end
+```
+
+#### Deserializer
+
+The main deserializer intended to be called by the Controller.  Also the default deserializer and block used by the '#deserialize` method.
+
+```ruby
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  deserializer PeopleDeserializer
+end
+```
+##### Arguments
+
+<table>
+  <thead>
+    <th>name</th>
+    <th>type</th>
+    <th>description</th>
+    <th>required</th>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td>name</td>
+      <td>class</td>
+      <td>The deserializer class for the controller</td>
+      <td>false</td>
+    </tr>
+    <tr>
+      <td>block</td>
+      <td>proc</td>
+      <td>The block to be called to deserialize the data</td>
+      <td>false</td>
+    </tr>
+  </tbody>
+</table>
+
+##### Default Call
+
+If no block or method is provided, `#deserialize` will try to new up the Deserializer class with arguments `object` and `options` and call `#to_hash`.
+
+```ruby
+Deserializer.new(object, **options).to_hash
+```
+
+##### Passing in a Block
+
+If you provide a block to the `#self.deserializer` method you can define how you want the deserializer to be called.
+
+```ruby
+class PeopleController < ActionController::API
+  include SnFoil::Controller
+
+  deserializer(PeopleDeserializer) { |object, deserializer, **_options| deserializer.new(object).deserialize }
+end
+```
+
+### Serializers and Deserializers
+
+Since Serializers seem so abundant SnFoil Controllers does not ship with any.  We recommend the awesome [jsonapi-serializer](https://github.com/jsonapi-serializer/jsonapi-serializer).
+
+Deserializers haven't come so far - so we've setup two:
+
+* SnFoil::Deserializer::JSON
+* SnFoil::Deserializer::JSONAPI
+
+These allow you to allow-list and format any incoming data into a standard more usable by your business logic.
+
+##### Usage
+
+```ruby
+class PeopleDeserializer
+  include SnFoil::Deserializer::JSON
+
+  key_transform :underscore
+
+  attributes :first_name, :middle_name, :last_name
+  attributes :line1, :line2, :city, :state, :zip, prefix: :address_
+
+  has_many :books, deserializer: BookDeserializer
+end
+```
+
+Both these deserializers share some common functions
+
+##### key_transform
+
+How you want to format the keys in the incoming payload.  SnFoil::Deserializers will always `:to_sym` all of the keys and will by default `:underscore` them.  You can pass in most active_support inflections or you can run some custom logic on them.
+
+###### Arguments
+
+<table>
+  <thead>
+    <th>name</th>
+    <th>type</th>
+    <th>description</th>
+    <th>required</th>
+  </thead>
+  <tbody>
+    <tr>
+      <td>tranform</td>
+      <td>symbol</td>
+      <td>The inflection you want called on the key value. ex: `underscore`, `camelcase`</td>
+      <td>false</td>
+    </tr>
+    <tr>
+      <td>block</td>
+      <td>proc</td>
+      <td>A custom proc passed the input request and the key the return value will be stored under.</td>
+      <td>false</td>
+    </tr>
+  </tbody>
+</table>
+
+##### attribute
+
+An attribute to be taken from the input payload.
+
+```ruby
+attribute :first_name 
+attribute :last_name
+attribute :line1, :prefix: :addr_
+attribute :line2, :prefix: :addr_
+attribute :city, :prefix: :addr_
+attribute :state, :prefix: :addr_
+attribute :zip_code, key: :addr_postal_code
+```
+
+###### Arguments
+
+<table>
+  <thead>
+    <th>name</th>
+    <th>type</th>
+    <th>description</th>
+    <th>required</th>
+  </thead>
+  <tbody>
+    <tr>
+      <td>name</td>
+      <td>symbol</td>
+      <td>The name of the key to be output in the final hash</td>
+      <td>true</td>
+    </tr>
+    <tr>
+      <td>options</td>
+      <td>keyword arguments</td>
+      <td>The options you want passed down the chain of intervals and to the context</td>
+      <td>false</td>
+    </tr>
+    <tr>
+      <td>block</td>
+      <td>proc</td>
+      <td></td>
+      <td>false</td>
+    </tr>
+  </tbody>
+</table>
+
+If you are using a block or the `:with` argument it will be passed the input, the key, and any options for the deserializer.  The return of the block or method is what will be used as the value instead of looking up the key directly in the input.
+
+example:
+
+```ruby
+attribute(:test) { |request, key, **options| request[:data][key] }
+```
+
+There are a few reserved keyword arguements that cause different functionlity/configuration for options:
+
+* `key` the name of the key from the original input payload.  If not provided this defaults to the name of the attribute.
+* `prefix` a prefix for the key you are looking for.  ex `attribute(:line1, prefix: :addr_)` will look for a key labeled `:addr_line1`
+* `with` the method name you want to call to lookup/parse an attribute
+
+##### attributes
+
+The same as attribute except you can pass in multiple keys.
+
+
+```ruby
+attributes :first_name, :last_name
+attributes :line1, :line2, :city, :state :prefix: :addr_
+```
+
+##### belongs_to
+
+A standard belongs_to relationship.  Instead of grabbing a single key from the payload, expects to grab a hash.
+
+```ruby
+belongs_to :team
+```
+
+###### Arguments
+
+<table>
+  <thead>
+    <th>name</th>
+    <th>type</th>
+    <th>description</th>
+    <th>required</th>
+  </thead>
+  <tbody>
+    <tr>
+      <td>tranform</td>
+      <td>symbol</td>
+      <td>The inflection you want called on the key value. ex: `underscore`, `camelcase`</td>
+      <td>false</td>
+    </tr>
+    <tr>
+      <td>block</td>
+      <td>proc</td>
+      <td>A custom proc passed the input request and the key the return value will be stored under.</td>
+      <td>false</td>
+    </tr>
+  </tbody>
+</table>
+
+##### has_one
+
+Just an alias for `#belongs_to`
+
+##### has_many
+
+A standard has_many relationship.  Instead of grabbing a single key from the payload, expects to grab an array.
+
+```ruby
+has_many :pets
+```
+
+###### Arguments
+
+<table>
+  <thead>
+    <th>name</th>
+    <th>type</th>
+    <th>description</th>
+    <th>required</th>
+  </thead>
+  <tbody>
+    <tr>
+      <td>tranform</td>
+      <td>symbol</td>
+      <td>The inflection you want called on the key value. ex: `underscore`, `camelcase`</td>
+      <td>false</td>
+    </tr>
+    <tr>
+      <td>block</td>
+      <td>proc</td>
+      <td>A custom proc passed the input request and the key the return value will be stored under.</td>
+      <td>false</td>
+    </tr>
+  </tbody>
+</table>
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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 the created tag, 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/limited-effort/snfoil-controller. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/limited-effort/snfoil-controller/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [Apache 2 License](https://opensource.org/licenses/Apache-2.0).
+
+## Code of Conduct
+
+Everyone interacting in the Snfoil::Controller project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/limited-effort/snfoil-controller/blob/main/CODE_OF_CONDUCT.md).

data/lib/snfoil/controller/version.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Copyright 2021 Matthew Howes
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#   http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module SnFoil
+  module Controller
+    VERSION = '1.0.0'
+  end
+end

data/lib/snfoil/controller.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Copyright 2021 Matthew Howes, Cliff Campbell
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#   http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'active_support/concern'
+require 'snfoil/context'
+
+module SnFoil
+  # ActiveSupport::Concern for Controller functionality
+  # A SnFoil::Controller is essentially a context but instead of using #action uses a more simplified workflow
+  # called #endpoint.  The method or block passed to endpoint is ultimately what renders.
+  # #endpoint creates the following intervals:
+  # * setup_*
+  # * process_*
+  #
+  # This concern also adds the following class methods
+  # * context - The context associated with the controller to process the business logic
+  # * deserializer - the deserializer associated with the controller to allow list incoming params
+  # * endpoint - helper function to build endpoint methods
+  # * serializer - The serializer associated to render the context's output
+  #
+  # @author Matthew Howes
+  #
+  # @since 0.1.0
+  module Controller
+    extend ActiveSupport::Concern
+
+    class Error < RuntimeError; end
+
+    included do
+      include SnFoil::Context
+
+      module_eval do
+        def entity
+          @entity ||= if defined? current_entity
+                        current_entity
+                      elsif defined? current_user
+                        current_user
+                      end
+        end
+      end
+    end
+
+    class_methods do
+      attr_reader :snfoil_endpoints, :snfoil_context,
+                  :snfoil_serializer, :snfoil_serializer_block,
+                  :snfoil_deserializer, :snfoil_deserializer_block
+
+      def context(klass = nil)
+        raise SnFoil::Controller::Error, "context already defined for #{self}" if @snfoil_context
+
+        @snfoil_context = klass
+      end
+
+      def serializer(klass = nil, &block)
+        raise SnFoil::Controller::Error, "serializer already defined for #{self}" if @snfoil_serializer || @snfoil_serializer_block
+
+        @snfoil_serializer = klass
+        @snfoil_serializer_block = block
+      end
+
+      def deserializer(klass = nil, &block)
+        raise SnFoil::Controller::Error, "deserializer already defined for #{self}" if @snfoil_deserializer || @snfoil_deserializer_block
+
+        @snfoil_deserializer = klass
+        @snfoil_deserializer_block = block
+      end
+
+      def endpoint(name, **options, &block)
+        (@snfoil_endpoints ||= {})[name] =
+          options.merge(controller_action: name, method: options[:with], block: block)
+
+        interval "setup_#{name}"
+        interval "process_#{name}"
+
+        define_endpoint_method(name)
+      end
+    end
+
+    def serialize(object, **options)
+      serializer = options.fetch(:serializer) { self.class.snfoil_serializer }
+      return object unless serializer
+
+      exec_serialize(serializer, object, **options)
+    end
+
+    def deserialize(params, **options)
+      deserializer = options.fetch(:deserializer) { self.class.snfoil_deserializer }
+      return params unless deserializer
+
+      exec_deserialize(deserializer, params, **options)
+    end
+
+    def run_context(context: nil, context_action: nil, controller_action: nil, **_options)
+      (context || self.class.snfoil_context).new(entity).send(context_action || controller_action)
+    end
+
+    protected
+
+    class_methods do
+      def define_endpoint_method(name)
+        define_method(name) do |**options|
+          options = options.merge self.class.snfoil_endpoints[name]
+          options = run_interval("setup_#{name}", **options)
+          options = run_interval("process_#{name}", **options)
+          exec_render(**options)
+        end
+      end
+    end
+
+    private
+
+    def exec_render(method: nil, block: nil, **options)
+      return send(method, **options) if method
+
+      instance_exec(**options, &block)
+    end
+
+    def exec_serialize(serializer, object, **options)
+      serializer_block = options.fetch(:serialize) { self.class.snfoil_serializer_block }
+      if options[:serialize_with]
+        send(options[:serialize_with], object, serializer, **options, current_entity: entity)
+      elsif serializer_block
+        instance_exec(object, serializer, **options, current_entity: entity, &serializer_block)
+      else
+        serializer.new(object, **options, current_entity: entity).to_hash
+      end
+    end
+
+    def exec_deserialize(deserializer, params, **options)
+      deserializer_block = options.fetch(:deserialize) { self.class.snfoil_deserializer_block }
+      if options[:deserialize_with]
+        send(options[:deserialize_with], params, deserializer, **options, current_entity: entity)
+      elsif deserializer_block
+        instance_exec(params, deserializer, **options, current_entity: entity, &deserializer_block)
+      else
+        deserializer.new(params, **options, current_entity: entity).to_hash
+      end
+    end
+  end
+end