jsonapi-realizer 4.4.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a8bebae1837baec43c16e73cc362203f65387459f992a81732d035ffdb0c61e
-  data.tar.gz: dad4dfe6f56dd8c85f35c9e3f829939d5278e652f7489d9a01958d15071e3aa8
+  metadata.gz: 56892c3c8c68851f388d17eb94937a079fadddb1490cac12f45f46497a4b9f5b
+  data.tar.gz: 46e26b62903cf861f7114b44a762912608fe52100674cad749e63e68ac6c731a
 SHA512:
-  metadata.gz: 101883f640d8a56b561212abc84fd4cdf34613b41a0f14e6d8625eb6439b31c1e236eece7663366aa1ba6b7660279da05547d1f9eba9050ded2a12c04aa4fec4
-  data.tar.gz: cb0f5eb6555aa35c64e7b8bafbeced9bad365ff337bd26ea5a023e26e529a6ecd3b3c2f4cde93de4090f9243d31df486b28a2f59dd99c02dac73f9c6488ca60c
+  metadata.gz: 355c9f15d66d5784a95731bb81f1977f7adc8da4e28e4c470d9fe90ebe697d8583f3c0262ee8d9c2c524c83869ccde408b4b6d78199f2655b64700507d85720a
+  data.tar.gz: 7faacba0d5f46021462ba6722a2305f5eff92c7cad9bad7bdf5411cd6bbeaff06ab84ec0651fa939e406875b5d2b275b2e448f39d7b9c1a0436acc5ce3529ec9

data/README.md

@@ -48,12 +48,12 @@ class ProfileRealizer
 end
 ```
 
-You can define special properties on attributes and relationships realizers:
+You can define aliases for these properties:
 
 ``` ruby
-has_many :doctors, as: :users, includable: false
+has_many :doctors, as: :users
 
-has :title, selectable: false
+has :title, as: :name
 ```
 
 Once you've designed your resources, we just need to use them! In this example, we'll use controllers from Rails:
@@ -78,73 +78,6 @@ end
 
 Notice that we pass `realization.model` to `ProcessPhotosService`, that's because `jsonapi-realizer` doesn't do the act of saving, creating, or destroying! We just ready up the records for you to handle (including errors).
 
-### Policies
-
-Most times you will want to control what a person sees when they as for your data. We have created interfaces for this use-case and we'll show how you can use pundit (or any PORO) to constrain your in/out.
-
-First up is the policy itself:
-
-``` ruby
-class PhotoPolicy < ApplicationPolicy
-  class Scope < ApplicationPolicy::Scope
-    def resolve
-      case
-      when relation.with_role_state?(:administrator)
-        relation
-      when requester.with_onboarding_state?(:completed)
-        relation.where(photographer: requester)
-      else
-        relation.none
-      end
-    end
-
-    def sanitize(action, params)
-      case action
-      when :index
-        params.permit(:fields, :include, :filter)
-      else
-        params
-      end
-    end
-  end
-
-  def index?
-    requester.with_onboarding_state?(:completed)
-  end
-end
-```
-
-``` ruby
-class PhotoRealizer
-  include JSONAPI::Realizer::Resource
-
-  register :photos, class_name: "Photo", adapter: :active_record
-
-  has_one :photographer, as: :profiles
-
-  has :title
-  has :src
-end
-```
-
-``` ruby
-class PhotosController < ApplicationController
-  def index
-    # See: pundit for `policy_scope()`
-    realization = JSONAPI::Realizer.index(
-      policy(Photo).sanitize(:index, params),
-      headers: request.headers,
-      type: :posts,
-      scope: policy_scope(Photo)
-    )
-
-    # See: pundit for `authorize()`
-    authorize(realization.relation)
-
-    render json: JSONAPI::Serializer.serialize(realization.models, is_collection: true)
-  end
-end
-```
 
 ### Adapters
 
@@ -155,14 +88,14 @@ There are two core adapters:
 
 An adapter must provide the following interfaces:
 
-  0. `find_via`, describes how to find the model
-  0. `find_many_via`, describes how to find many models
-  0. `assign_attributes_via`, describes how to write a set of properties
-  0. `assign_relationships_via`, describes how to write a set of relationships
+  0. `find_one`, describes how to find the model
+  0. `find_many`, describes how to find many models
+  0. `write_attributes`, describes how to write a set of properties
+  0. `write_relationships`, describes how to write a set of relationships
   0. `includes_via`, describes how to eager include related models
-  0. `sparse_fields_via`, describes how to only return certain fields
+  0. `sparse_fields`, describes how to only return certain fields
 
-You can also provide custom adapter interfaces like below, which will use `active_record`'s `find_many_via`, `assign_relationships_via`, `update_via`, `includes_via`, and `sparse_fields_via`:
+You can also provide custom adapter interfaces like below, which will use `active_record`'s `find_many`, `write_relationships`, `update_via`, `includes_via`, and `sparse_fields`:
 
 ``` ruby
 class PhotoRealizer
@@ -170,11 +103,11 @@ class PhotoRealizer
 
   register :photos, class_name: "Photo", adapter: :active_record
 
-  adapter.find_via do |model_class, id|
+  adapter.find_one do |model_class, id|
     model_class.where { id == id or slug == id }.first
   end
 
-  adapter.assign_attributes_via do |model, attributes|
+  adapter.write_attributes do |model, attributes|
     model.update_columns(attributes)
   end
 
@@ -303,38 +236,14 @@ end
 
 ### jsonapi-home
 
-I'm already using jsonapi-realizer and it's sister project jsonapi-serializers in a new gem of mine that allows services to be discoverable: [jsonapi-home](https://github.com/krainboltgreene/jsonapi-home).
-
-### Notes
-
-A successful JSON:API request can be annotated as:
-
-```
-JSONAPIRequest -> (BusinessLayer -> JSONAPIRequest -> (Record | Array<Record>)) -> JSONAPIResponse
-```
-
-The `jsonapi-serializers` library provides this shape:
-
-```
-JSONAPIRequest -> (Record | Array<Record>) -> JSONAPIResponse
-```
-
-But it leaves fetching/creating/updating/destroying the records up to you! This is where jsonapi-realizer comes into play, as it provides this shape:
-
-```
-BusinessLayer -> JSONAPIRequest -> (Record | Array<Record>)
-```
+I'm already using jsonapi-realizer and it's sister project jsonapi-serializers in a new gem of mine that allows services to be discoverable: [jsonapi-home](https://github.com/krainboltgreene/jsonapi-home.rb).
 
 
 ## Installing
 
 Add this line to your application's Gemfile:
 
-    gem "jsonapi-realizer", "4.1.0"
-
-And then execute:
-
-    $ bundle
+    $ bundle add jsonapi-realizer
 
 Or install it yourself with:
 

data/lib/jsonapi/realizer.rb

@@ -1,36 +1,37 @@
-require "ostruct"
-require "active_support/concern"
-require "active_support/core_ext/enumerable"
-require "active_support/core_ext/string"
+require("ostruct")
+require("addressable")
+require("active_model")
+require("active_support/concern")
+require("active_support/core_ext/enumerable")
+require("active_support/core_ext/string")
+require("active_support/core_ext/module")
 
 module JSONAPI
   MEDIA_TYPE = "application/vnd.api+json" unless const_defined?("MEDIA_TYPE")
 
   module Realizer
-    require_relative "realizer/version"
-    require_relative "realizer/error"
-    require_relative "realizer/action"
-    require_relative "realizer/adapter"
-    require_relative "realizer/resource"
+    require_relative("realizer/version")
+    require_relative("realizer/error")
+    require_relative("realizer/configuration")
+    require_relative("realizer/controller")
 
-    def self.create(payload, headers:, scope: nil)
-      enact(Action::Create.new(payload: payload, headers: headers, scope: scope))
-    end
-
-    def self.update(payload, headers:, scope: nil)
-      enact(Action::Update.new(payload: payload, headers: headers, scope: scope))
-    end
+    @configuration ||= Configuration.new(
+      :default_invalid_content_type_exception => JSONAPI::Realizer::Error::InvalidContentTypeHeader,
+      :default_missing_content_type_exception => JSONAPI::Realizer::Error::MissingContentTypeHeader,
+      :default_identifier => :id,
+      :adapter_mappings => {}
+    )
 
-    def self.show(payload, headers:, type:, scope: nil)
-      enact(Action::Show.new(payload: payload, headers: headers, type: type, scope: scope))
-    end
-
-    def self.index(payload, headers:, type:, scope: nil)
-      enact(Action::Index.new(payload: payload, headers: headers, type: type, scope: scope))
-    end
+    require_relative("realizer/adapter")
+    require_relative("realizer/context")
+    require_relative("realizer/resource")
 
-    private_class_method def self.enact(action)
-      action.tap(&:call)
+    def self.configuration
+      if block_given?
+        yield(@configuration)
+      else
+        @configuration
+      end
     end
   end
 end

data/lib/jsonapi/realizer/action.rb

@@ -16,9 +16,9 @@ module JSONAPI
         @payload = payload
 
         raise Error::MissingAcceptHeader unless @headers.key?("Accept")
-        raise Error::InvalidAcceptHeader unless @headers.fetch("Accept") == JSONAPI::MEDIA_TYPE
+        raise Error::InvalidAcceptHeader, given: @headers.fetch("Accept"), wanted: JSONAPI::MEDIA_TYPE unless @headers.fetch("Accept") == JSONAPI::MEDIA_TYPE
         raise Error::IncludeWithoutDataProperty if @payload.key?("include") && !@payload.key?("data")
-        raise Error::MalformedDataRootProperty if @payload.key?("data") && !(data.kind_of?(Array) || data.kind_of?(Hash) || data.nil?)
+        raise Error::MalformedDataRootProperty, given: data if @payload.key?("data") && !(data.kind_of?(Array) || data.kind_of?(Hash) || data.nil?)
       end
 
       def call; end

data/lib/jsonapi/realizer/adapter.rb

@@ -1,75 +1,38 @@
 module JSONAPI
   module Realizer
     class Adapter
-      require_relative "adapter/active_record"
-      require_relative "adapter/memory"
+      include(ActiveModel::Model)
+
+      require_relative("adapter/active_record")
 
       MAPPINGS = {
-        memory: JSONAPI::Realizer::Adapter::MEMORY,
-        active_record: JSONAPI::Realizer::Adapter::ACTIVE_RECORD,
+        :active_record => JSONAPI::Realizer::Adapter::ActiveRecord
       }
+      private_constant :MAPPINGS
 
-      def initialize(interface)
-        if JSONAPI::Realizer::Adapter::MAPPINGS.key?(interface.to_sym)
-          instance_eval(&JSONAPI::Realizer::Adapter::MAPPINGS.fetch(interface.to_sym))
-        else
-          raise ArgumentError, "you've given an invalid adapter alias: #{interface}, we support #{JSONAPI::Realizer::Adapter::MAPPINGS.keys}"
-        end
+      attr_accessor :interface
 
-        raise ArgumentError, "need to provide a Adapter.find_via interface" unless instance_variable_defined?(:@find_via_call)
-        raise ArgumentError, "need to provide a Adapter.find_many_via_call interface" unless instance_variable_defined?(:@find_many_via_call)
-        raise ArgumentError, "need to provide a Adapter.assign_attributes_via interface" unless instance_variable_defined?(:@assign_attributes_via_call)
-        raise ArgumentError, "need to provide a Adapter.assign_relationships_via interface" unless instance_variable_defined?(:@assign_relationships_via_call)
-        raise ArgumentError, "need to provide a Adapter.sparse_fields interface" unless instance_variable_defined?(:@sparse_fields_call)
-        raise ArgumentError, "need to provide a Adapter.include_via interface" unless instance_variable_defined?(:@include_via_call)
-      end
+      validates_presence_of(:interface)
 
-      def find_via(&callback)
-        @find_via_call = callback
-      end
+      def initialize(interface:)
+        super(interface: interface)
 
-      def find_many_via(&callback)
-        @find_many_via_call = callback
-      end
+        validate!
 
-      def assign_attributes_via(&callback)
-        @assign_attributes_via_call = callback
-      end
+        mappings = MAPPINGS.merge(JSONAPI::Realizer.configuration.adapter_mappings).with_indifferent_access
 
-      def assign_relationships_via(&callback)
-        @assign_relationships_via_call = callback
-      end
-
-      def sparse_fields(&callback)
-        @sparse_fields_call = callback
-      end
-
-      def include_via(&callback)
-        @include_via_call = callback
-      end
-
-      def find_via_call(model_class, id)
-        @find_via_call.call(model_class, id)
-      end
-
-      def find_many_via_call(model_class)
-        @find_many_via_call.call(model_class)
-      end
-
-      def assign_attributes_via_call(model, attributes)
-        @assign_attributes_via_call.call(model, attributes)
-      end
-
-      def assign_relationships_via_call(model, relationships)
-        @assign_relationships_via_call.call(model, relationships)
-      end
+        unless mappings.key?(interface)
+          raise(ArgumentError, "you've given an invalid adapter alias: #{interface}, we support #{mappings.keys.to_sentence}")
+        end
 
-      def sparse_fields_call(model_class, fields)
-        @sparse_fields_call.call(model_class, fields)
-      end
+        self.singleton_class.prepend(mappings.fetch(interface))
 
-      def include_via_call(model_class, includes)
-        @include_via_call.call(model_class, includes)
+        raise(ArgumentError, "need to provide a Adapter#find_one interface") unless respond_to?(:find_one)
+        raise(ArgumentError, "need to provide a Adapter#find_many interface") unless respond_to?(:find_many)
+        raise(ArgumentError, "need to provide a Adapter#write_attributes interface") unless respond_to?(:write_attributes)
+        raise(ArgumentError, "need to provide a Adapter#write_relationships interface") unless respond_to?(:write_relationships)
+        raise(ArgumentError, "need to provide a Adapter#include_relationships interface") unless respond_to?(:include_relationships)
+        raise(ArgumentError, "need to provide a Adapter#paginate interface") unless respond_to?(:paginate)
       end
     end
   end

data/lib/jsonapi/realizer/adapter/active_record.rb

@@ -1,35 +1,56 @@
 module JSONAPI
   module Realizer
     class Adapter
-      ACTIVE_RECORD = Proc.new do
-        find_many_via do |model_class|
-          model_class.all
+      module ActiveRecord
+        def find_many(scope)
+          scope.all
         end
 
-        find_via do |model_class, id|
-          model_class.find(id)
+        def find_one(scope, id)
+          scope.find(id)
         end
 
-        assign_attributes_via do |model, attributes|
+        def filtering(scope, filters)
+          scope.where(filters.slice(*scope.column_names))
+        end
+
+        def sorting(scope, sorts)
+          scope.order(
+            *sorts.
+              map do |(keychain, direction)|
+                [keychain, if direction == "-" then :DESC else :ASC end]
+              end.
+              map do |(keychain, direction)|
+                [keychain.map {|key| key.inspect}.join("."), direction]
+              end.
+              map do |pair|
+                Arel.sql(pair.join(" "))
+              end
+          )
+        end
+
+        def paginate(scope, per, offset)
+          scope.page(offset).per(per)
+        end
+
+        def write_attributes(model, attributes)
           model.assign_attributes(attributes)
         end
 
-        assign_relationships_via do |model, relationships|
+        def write_relationships(model, relationships)
           model.assign_attributes(relationships)
         end
 
-        sparse_fields do |model_class, fields|
-          model_class.select(fields)
+        def include_relationships(scope, includes)
+          scope.eager_load(*includes.map(&method(:arel_chain)))
         end
 
-        include_via do |model_class, includes|
-          model_class.includes(includes.map(&(recursively_nest = -> (chains) do
-            if chains.size == 1
-              chains.first
-            else
-              {chains.first => recursively_nest.call(chains.drop(1))}
-            end
-          end)))
+        private def arel_chain(chains)
+          if chains.size == 1
+            chains.first
+          else
+            {chains.first => arel_chain(chains.drop(1))}
+          end
         end
       end
     end

data/lib/jsonapi/realizer/adapter_spec.rb

@@ -1,4 +1,5 @@
-require "spec_helper"
+require("spec_helper")
+
+RSpec.describe(JSONAPI::Realizer::Adapter) do
 
-RSpec.describe JSONAPI::Realizer::Adapter do
 end

data/lib/jsonapi/realizer/configuration.rb

@@ -0,0 +1,22 @@
+module JSONAPI
+  module Realizer
+    class Configuration
+      include(ActiveModel::Model)
+
+      attr_accessor(:default_origin)
+      attr_accessor(:default_identifier)
+      attr_accessor(:adapter_mappings)
+      attr_accessor(:default_missing_content_type_exception)
+      attr_accessor(:default_invalid_content_type_exception)
+
+      validates_presence_of(:default_missing_content_type_exception)
+      validates_presence_of(:default_invalid_content_type_exception)
+
+      def initialize(**keyword_arguments)
+        super(**keyword_arguments)
+
+        validate!
+      end
+    end
+  end
+end