jsonapionify 0.11.11 → 0.12.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NGNhMGNhNzcwZDMxOGZkYTA3MzBhZWIzNDhiZDlhODEyNjUwYzZkMw==
+    NWMyMjExNTU5ZmE5NzgyMWYyN2E4ZjFmZGFmY2FkN2I0MTZlZDliYw==
   data.tar.gz: !binary |-
-    MzFmOWY1MDZkODE2ODU4NGZjYjYzNmQ3ZWIyNmJhNGQ4ZWFjNTExMA==
+    NDM2YzE2YjRhMzIzNzNhNWZlNGZmNmY0NmExOWQ5NTUwOGI4ZmMzMQ==
 SHA512:
   metadata.gz: !binary |-
-    N2MzN2UyZjYzYjMwMjE4NTdmYjFjMTgyYzdjNDA0NDUwNTlmMDliOWQ0ZDUy
-    MTk2MTBhZjA0MWNkNThiMDhjZmVhYTRiNzBlYmNkOGE3ZWY2OWZkZGM1ZmNj
-    ODVmMzFlNGRmMDJmYTQ0ZWJlZjNmOTM5YTFhYjYyYTJjZmVhYjU=
+    ZTM3ZTczNTQzZTUwN2Q1MmVmNTAwNWI0ZGEzN2E2MjYwMTM4MzhjZTJlYjVk
+    NTNiYTEyZWZjMTgwN2M0OWY5MzBmMjY1MGNhNzFmNjUxOTM1ZTkxYzZiYjU5
+    MWQ5Y2Q0ZmY5MzYyOWRiZDFjYjJhMjRjYjgwNDRmYjBlMGY3MTk=
   data.tar.gz: !binary |-
-    ODI2NWRiMWZhMTYxMWIzNmQwOTg4MmRlMTI0MjJhZDljNTM0NzNmZTY5Y2Zm
-    MjA4OGJlOTFkZDA5M2U5ZTkyMWU0NzgzNGI1OWVhMWEyYmRkNjM2ZTI3YjJj
-    NTdkMjM3ZWZhYThhY2Y2MTRmMWVlZGIzZDU3ZmQ0ZjJkZGMzNTE=
+    OTI0Y2Q0NGZlZDA3MjYzMmVmNWE4OGVmYmExY2JlMDJiNjc4MzE5ODk5OGQ3
+    M2VmY2U4ZGUxZGI4ZjE3YzAxNjdiMjVkNzJmYWU5ZmZjOTczYzExMzFiMzI4
+    NzdhYzcxOTMwY2M5MjQ3ZjAwYjQxNzlhMzY0ZGRkYmY1MjIyODg=

data/README.md

@@ -29,6 +29,9 @@ And then execute:
 
 ## Usage
 
+Below is a high level overview of all the available methods. For for detail see
+the yard documentation and the [examples](examples).
+
 ### APIs
 
 Api Definitions are the basis of JSONApi's DSL. They encompass resources that are available and can be run as standalone rack apps or be mounted within a rails app.

data/examples/example_api.rb

@@ -0,0 +1,80 @@
+## Apis
+
+class ExampleApi < JSONAPIonify::Base
+
+end
+
+## Resources
+# Resources are what the api serves up to represent data within your application.
+
+# **define_resource**<br />
+# Calling `define_resource` on an Api class will define a resource.
+# This will not only define the resource, but add routes to the api to access
+# the resouce. By default only the **`read`** route (`GET /:resource/:id`) is
+# added when you define a resource. Additional routes will have to be specified
+# in the resource definition.
+ExampleApi.define_resource :users do
+
+  ### Resource Setup
+  # Resources require a default setup that defines how the resource interacts
+  # with the data model.
+
+  # **scope**<br />
+  # Scope defines the model/object that the resource will represent. By default,
+  # it will try to find a class that matches the resource name. In this example
+  # resource, `:users` would implicitly look for a `User` class.
+  scope { User }
+
+  ### Attributes
+  # Attributes define the fields that can be set set on a resource on a request
+  # and what is provided back to the client in a response.
+
+  # **attribute**<br />
+  # Attributes can be defined within a resources definition using the `attribute`
+  # method within a resource definition block.
+  attribute :first_name, types.String, "The user's first name.", read: true, write: true, hidden: false, required: false do |name, instance, context|
+    instance.send(name)
+  end
+
+  # Basic attibutes only require a name, a type and a description. By default
+  # the resolution of the attribute is invoked by calling a method matching
+  # the attributes name on the instance of the resource.
+  attribute :last_name, types.String, "The users last name."
+
+  # Sometimes you wish to present information that may not be in the model.
+  # For this reason, you can define a block on the attribute which will tell
+  # the api how to fetch the value for that attibute. These attributes will
+  # default to being readonly attibutes.
+  attribute :full_name, types.String, "The user's full name." do |attr_name, instance, context|
+    "#{instance.first_name} #{instance.last_name}"
+  end
+
+  # Some attributes may be required for certain actions. In this case we
+  # can use the required keyword. `true` can be passed to require on all
+  # actions, or an action name or array of action names can be passed to
+  # target specific actions.
+  attribute :email, types.String, "The user's email address.", required: true
+
+  # Some attributes may be write only attributes, these attributes may
+  # include information we never want to send back in a response, such as
+  # passwords. `false` can be passed to prevent write on all actions, or an
+  # action name or array of action names can be passed to whitelist specific
+  # actions.
+  attribute :password, types.String, "The user's password", required: :create, read: false
+
+  # Some attributes may need to be read only attributes, such as timestamps
+  # or other attributes our application controls and should not be set by
+  # the end user. `false` can be passed to prevent write on all
+  # actions, or an action name or array of action names can be passed to
+  # whitelist specific actions.
+  attribute :updated_at, types.TimeString, "The last time the user was updated", write: false
+
+  # Some attributes may be tied to "expensive" calls. Rather than optimize
+  # your queries to allow for these attributes to be less expensive, we can
+  # simply hide the attributes by default. And they can only be used by
+  # utlizing [sparce fieldsets](http://jsonapi.org/format/#fetching-sparse-fieldsets).
+  # `true` can be passed to hide on all actions, or an action name or array of
+  # action names can be passed to target specific actions.
+  attribute :friends_count, types.Integer, "The number of friends for a user", write: false, hidden: [:list]
+
+end

data/jsonapionify.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'mime-types'
 
   spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'yard'
   spec.add_development_dependency 'pry-byebug'
   spec.add_development_dependency 'rocco'
   spec.add_development_dependency 'bundler', '~> 1.10'

data/lib/jsonapionify/api/action/documentation.rb

@@ -63,8 +63,8 @@ module JSONAPIonify::Api
         end
         defs[:_is_example_]         = Context.new(readonly: true) { true }
         defs[:collection]           = Context.new(&collection_context)
-        defs[:paginated_collection] = Context.new { |context| context.collection }
-        defs[:instance]             = Context.new(readonly: true) { |context| context.collection.first }
+        defs[:paginated_collection] = Context.new { |collection:| collection }
+        defs[:instance]             = Context.new(readonly: true) { |collection:| collection.first }
         defs[:owner_context]        = Context.new(readonly: true) { ContextDelegate::Mock.new } if defs.has_key? :owner_context
       end
     end

data/lib/jsonapionify/api/attribute.rb

@@ -7,6 +7,7 @@ module JSONAPIonify::Api
 
     include Documentation
     using UnstrictProc
+    using JSONAPIonify::DestructuredProc
     attr_reader :name, :type, :description, :read, :write, :required, :hidden, :block
 
     def initialize(
@@ -29,7 +30,7 @@ module JSONAPIonify::Api
       @description       = description&.freeze
       @example           = example&.freeze
       @read              = read&.freeze
-      @write             = write&.freeze
+      @write             = (!block && write)&.freeze
       @required          = required&.freeze
       @block             = block&.freeze
       @writeable_actions = write
@@ -86,7 +87,7 @@ module JSONAPIonify::Api
         return example(example_id)
       end
       block = self.block || proc { |attr, i| i.send attr }
-      type.dump block.unstrict.call(self.name, instance, context)
+      type.dump block.unstrict.destructure.call(self.name, instance, context)
     rescue JSONAPIonify::Types::DumpError => ex
       error_block =
         context.resource.class.error_definitions[:attribute_type_error]

data/lib/jsonapionify/api/context.rb

@@ -1,18 +1,23 @@
 module JSONAPIonify::Api
   class Context
+    using JSONAPIonify::DestructuredProc
 
     def initialize(readonly: false, persisted: false, existing_context: nil, &block)
       @readonly         = readonly
       @persisted        = persisted
       @existing_context = existing_context
-      @block            = block
+      @block            = block || proc {}
     end
 
     def call(instance, delegate)
       existing_context = @existing_context || proc {}
       existing_block   = proc { existing_context.call(instance, delegate) }
-      block            = @block || proc {}
-      instance.instance_exec(delegate, existing_block, &block)
+      begin
+        instance.instance_exec(delegate, existing_block, &@block.destructure(0))
+      rescue => e
+        e.backtrace.unshift @block.source_location.join(':') + ":in (context)"
+        raise e
+      end
     end
 
     def readonly?

data/lib/jsonapionify/api/context_delegate.rb

@@ -60,5 +60,11 @@ module JSONAPIonify::Api
       to_s.chomp('>') << " memoed: #{@memo.keys.inspect}, persisted: #{@persisted_memo.keys.inspect}, overridden: #{@overrides.keys}" << '>'
     end
 
+    private
+
+    def __has_context?(name)
+      [@definitions, @overrides, @memo, @persisted_memo].map(&:keys).reduce(:|).include? name
+    end
+
   end
 end

data/lib/jsonapionify/api/relationship.rb

@@ -27,12 +27,12 @@ module JSONAPIonify::Api
         rel.owner.new(request: request).exec { |c| c }
       end
 
-      context(:owner_context, readonly: true, persisted: true) do |context|
-        owner_context_proc.call(context.request)
+      context(:owner_context, readonly: true, persisted: true) do |request:|
+        owner_context_proc.call(request)
       end
 
-      context(:owner, readonly: true, persisted: true) do |context|
-        context.owner_context.instance
+      context(:owner, readonly: true, persisted: true) do |owner_context:|
+        owner_context.instance
       end
 
       context(:id, readonly: true, persisted: true) do
@@ -65,11 +65,10 @@ module JSONAPIonify::Api
 
     attr_reader :owner, :class_proc, :name, :resolve, :hidden
 
-    def initialize(owner, name, resource: nil, includable: false, hidden: :list, resolve: proc { |n, o| o.send(n) }, &block)
+    def initialize(owner, name, resource: nil, hidden: :list, resolve: proc { |n, o| o.send(n) }, &block)
       @class_proc = block || proc {}
       @owner      = owner
       @name       = name
-      @includable = includable
       @resource   = resource || name
       @resolve    = resolve
       @hidden     = !!hidden && (hidden == true || Array.wrap(hidden))
@@ -99,9 +98,5 @@ module JSONAPIonify::Api
       owner.api.resource(@resource)
     end
 
-    def includable?
-      !!@includable
-    end
-
   end
 end

data/lib/jsonapionify/api/relationship/many.rb

@@ -1,5 +1,21 @@
 module JSONAPIonify::Api
   class Relationship::Many < Relationship
+    using JSONAPIonify::DestructuredProc
+
+    DEFAULT_REPLACE_COMMIT = proc { |scope:, request_instances:|
+      to_add    = request_instances - scope
+      to_delete = scope - request_instances
+      to_delete.each { |instance| scope.delete(instance) }
+      scope.concat to_add
+    }
+
+    DEFAULT_ADD_COMMIT = proc { |scope:, request_instances:|
+      scope.concat request_instances
+    }
+
+    DEFAULT_REMOVE_COMMIT = proc { |scope:, request_instances:|
+      request_instances.each { |instance| scope.delete(instance) }
+    }
 
     prepend_class do
       rel = self.rel
@@ -15,13 +31,14 @@ module JSONAPIonify::Api
           cacheable:    true,
           prepend:      'relationships'
         }
-        define_action(:show, 'GET', **options, &block).response status: 200 do |context|
-          context.response_object[:data] = build_resource_identifier_collection(collection: context.collection)
-          context.response_object.to_json
+        define_action(:show, 'GET', **options, &block).response status: 200 do |collection:, response_object:|
+          response_object[:data] = build_resource_identifier_collection(collection: collection)
+          response_object.to_json
         end
       end
 
       define_singleton_method(:replace) do |content_type: nil, callbacks: true, &block|
+        block ||= DEFAULT_REPLACE_COMMIT
         options = {
           content_type:  content_type,
           callbacks:     callbacks,
@@ -29,13 +46,14 @@ module JSONAPIonify::Api
           prepend:       'relationships',
           example_input: :resource_identifier
         }
-        define_action(:replace, 'PATCH', **options, &block).response status: 200 do |context|
-          context.response_object[:data] = build_resource_identifier_collection(collection: context.collection)
-          context.response_object.to_json
+        define_action(:replace, 'PATCH', **options, &block).response status: 200 do |collection:, response_object:|
+          response_object[:data] = build_resource_identifier_collection(collection: collection)
+          response_object.to_json
         end
       end
 
       define_singleton_method(:add) do |content_type: nil, callbacks: true, &block|
+        block ||= DEFAULT_ADD_COMMIT
         options = {
           content_type:  content_type,
           callbacks:     callbacks,
@@ -43,13 +61,14 @@ module JSONAPIonify::Api
           prepend:       'relationships',
           example_input: :resource_identifier
         }
-        define_action(:add, 'POST', **options, &block).response status: 200 do |context|
-          context.response_object[:data] = build_resource_identifier_collection(collection: context.collection)
-          context.response_object.to_json
+        define_action(:add, 'POST', **options, &block).response status: 200 do |collection:, response_object:|
+          response_object[:data] = build_resource_identifier_collection(collection: collection)
+          response_object.to_json
         end
       end
 
       define_singleton_method(:remove) do |content_type: nil, callbacks: true, &block|
+        block ||= DEFAULT_REMOVE_COMMIT
         options           = {
           content_type:  content_type,
           callbacks:     callbacks,
@@ -58,14 +77,27 @@ module JSONAPIonify::Api
           example_input: :resource_identifier
         }
         options[:prepend] = 'relationships'
-        define_action(:remove, 'DELETE', **options, &block).response status: 200 do |context|
-          context.response_object[:data] = build_resource_identifier_collection(collection: context.collection)
-          context.response_object.to_json
+        define_action(:remove, 'DELETE', **options, &block).response status: 200 do |collection:, response_object:|
+          response_object[:data] = build_resource_identifier_collection(collection: collection)
+          response_object.to_json
         end
       end
 
-      context :scope do |context|
-        instance_exec(rel.name, context.owner, context, &rel.resolve)
+      context :scope do |context, owner:|
+        instance_exec(rel.name, owner, context, &rel.resolve.destructure)
+      end
+
+      after :commit_add, :commit_remove, :commit_replace do |owner:|
+        if defined?(ActiveRecord) && owner.is_a?(ActiveRecord::Base)
+          # Collect Errors
+          if owner.errors.present?
+            owner.errors.messages.each do |attr, messages|
+              messages.each do |message|
+                error :invalid_attribute, attr, message
+              end
+            end
+          end
+        end
       end
 
       show

data/lib/jsonapionify/api/relationship/one.rb

@@ -1,5 +1,14 @@
 module JSONAPIonify::Api
   class Relationship::One < Relationship
+    using JSONAPIonify::DestructuredProc
+
+    DEFAULT_REPLACE_COMMIT = proc { |owner:, request_instance:|
+      # Set the association
+      owner.send "#{self.class.rel.name}=", request_instance
+
+      # Save the instance
+      owner.save if owner.respond_to? :save
+    }
 
     prepend_class do
       rel = self.rel
@@ -16,27 +25,41 @@ module JSONAPIonify::Api
           cacheable:    true,
           prepend:      'relationships'
         }
-        define_action(:show, 'GET', **options, &block).response status: 200 do |context|
-          context.response_object[:data] = build_resource_identifier(instance: context.instance)
-          context.response_object.to_json
+        define_action(:show, 'GET', **options, &block).response status: 200 do |response_object:, instance:|
+          response_object[:data] = build_resource_identifier(instance: instance)
+          response_object.to_json
         end
       end
 
       define_singleton_method(:replace) do |content_type: nil, callbacks: true, &block|
+        block ||= DEFAULT_REPLACE_COMMIT
         options = {
           content_type: content_type,
           callbacks:    callbacks,
           cacheable:    false,
           prepend:      'relationships'
         }
-        define_action(:replace, 'PATCH', **options, &block).response status: 200 do |context|
-          context.response_object[:data] = build_resource_identifier(instance: context.instance)
-          context.response_object.to_json
+        define_action(:replace, 'PATCH', **options, &block).response status: 200 do |response_object:, instance:|
+          response_object[:data] = build_resource_identifier(instance: instance)
+          response_object.to_json
         end
       end
 
-      context :instance do |context|
-        instance_exec rel.name, context.owner, context, &rel.resolve
+      context :instance do |context, owner:|
+        instance_exec(rel.name, owner, context, &rel.resolve.destructure)
+      end
+
+      after :commit_replace do |owner:|
+        if defined?(ActiveRecord) && owner.is_a?(ActiveRecord::Base)
+          # Collect Errors
+          if owner.errors.present?
+            owner.errors.messages.each do |attr, messages|
+              messages.each do |message|
+                error :invalid_attribute, attr, message
+              end
+            end
+          end
+        end
       end
 
       show

data/lib/jsonapionify/api/resource.rb

@@ -7,8 +7,9 @@ module JSONAPIonify::Api
     extend JSONAPIonify::Autoload
     autoload_all
 
-    extend Definitions
+    include Callbacks
     extend ClassMethods
+    extend Definitions
     extend Documentation
 
     include ErrorHandling
@@ -44,7 +45,7 @@ module JSONAPIonify::Api
       cacheable: true,
       action: nil
     )
-      context_overrides[:action_name] = action.name if action
+      context_overrides[:action_name] ||= action.name if action
       @__context                      = ContextDelegate.new(
         request,
         self,
@@ -61,9 +62,5 @@ module JSONAPIonify::Api
       extend Caching if cacheable
     end
 
-    def action_name
-      action&.name
-    end
-
   end
 end