praxis 2.0.pre.8 → 2.0.pre.13

data/lib/praxis/finalizable.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+module Praxis
+  module Finalizable
+    def self.extended(klass)
+      klass.module_eval do
+        @finalizable = Set.new
+      end
+    end
+
+    def inherited(base)
+      @finalizable << base
+      base.instance_variable_set(:@finalizable, @finalizable)
+      base.instance_variable_set(:@finalized, false)
+    end
+
+    def finalizable
+      @finalizable
+    end
+
+    def finalized?
+      @finalized
+    end
+
+    def _finalize!
+      @finalized = true
+    end
+
+    def finalize!
+      finalizable.reject(&:finalized?).each(&:_finalize!)
+
+      finalize! unless finalizable.all?(&:finalized?)
+    end
+  end
+end

data/lib/praxis/mapper/active_model_compat.rb

@@ -23,6 +23,10 @@ module Praxis
           Praxis::Extensions::FieldSelection::ActiveRecordQuerySelector
         end
 
+        def _pagination_query_builder_class
+          Praxis::Extensions::Pagination::ActiveRecordPaginationHandler
+        end
+
         def _praxis_associations
           orig = self.reflections.clone
 

data/lib/praxis/mapper/resource.rb

@@ -30,6 +30,7 @@ module Praxis::Mapper
         end
 
         @properties = self.superclass.properties.clone
+        @_filters_map = {}
       end
 
     end
@@ -197,7 +198,7 @@ module Praxis::Mapper
 
     # TODO: this shouldn't be needed if we incorporate it with the properties of the mapper...
     # ...maybe what this means is that we can change it for a better DSL in the resource?
-    def self.filters_mapping(definition)
+    def self.filters_mapping(definition={})
       @_filters_map = \
         case definition
         when Hash
@@ -211,7 +212,9 @@ module Praxis::Mapper
 
     def self.craft_filter_query(base_query, filters:) # rubocop:disable Metrics/AbcSize
       if filters 
-        raise "Must define the mapping of filters if want to use Filtering for resource: #{self}" unless @_filters_map
+        unless @_filters_map
+          raise "To use API filtering, you must define the mapping of api-names to resource properties (using the `filters_mapping` method in #{self})"
+        end
         debug = Praxis::Application.instance.config.mapper.debug_queries
         base_query = model._filter_query_builder_class.new(query: base_query, model: model, filters_map: @_filters_map, debug: debug).generate(filters)
       end
@@ -228,6 +231,19 @@ module Praxis::Mapper
       base_query
     end
 
+    def self.craft_pagination_query(base_query, pagination: ) # rubocop:disable Metrics/AbcSize
+      handler_klass = model._pagination_query_builder_class
+      return base_query unless (handler_klass && (pagination.paginator || pagination.order))
+
+      # Gather and save the count if required
+      if pagination.paginator&.total_count
+        pagination.total_count = handler_klass.count(base_query.dup)
+      end
+      
+      base_query = handler_klass.order(base_query, pagination.order)
+      handler_klass.paginate(base_query, pagination)
+    end
+
     def initialize(record)
       @record = record
     end

data/lib/praxis/mapper/selector_generator.rb

@@ -48,7 +48,7 @@ module Praxis::Mapper
         new_fields_as_hash = association[:remote_key_columns].each_with_object({}) do|name, hash|
           hash[name] = true
         end
-        fields.merge!(new_fields_as_hash) 
+        fields = fields.merge(new_fields_as_hash) 
       end
 
       node.add(fields) unless fields == true
@@ -141,6 +141,7 @@ module Praxis::Mapper
     def add(resource, fields)
       @root = SelectorGeneratorNode.new(resource)
       @root.add(fields)
+      self
     end
 
     def selectors

data/lib/praxis/mapper/sequel_compat.rb

@@ -7,6 +7,9 @@ module Praxis::Mapper
 
     included do
       attr_accessor :_resource
+      class <<self  
+        alias_method :find_by, :find # Easy way to be method compatible with AR
+      end       
     end
 
     module ClassMethods
@@ -19,6 +22,10 @@ module Praxis::Mapper
         Praxis::Extensions::FieldSelection::SequelQuerySelector
       end
 
+      def _pagination_query_builder_class
+        Praxis::Extensions::Pagination::SequelPaginationHandler
+      end
+
       def _praxis_associations
         orig = self.association_reflections.clone
         orig.each do |k,v|

data/lib/praxis/media_type.rb

@@ -34,8 +34,9 @@ module Praxis
   #         description: 'The factory in which this widget was produced'
   #     end
   #
-  #     # All resources should have a default view
-  #     view :default do
+  #     # All resources will be assigned a default_fieldset (with only non-blueprint attributes)
+  #     # But one can explicitly tailor that by using the `default_fieldset` DSL
+  #     default_fieldset do
   #       attribute :id
   #       attribute :color
   #       attribute :material
@@ -44,72 +45,6 @@ module Praxis
   class MediaType < Praxis::Blueprint
 
     include Types::MediaTypeCommon
-
-    class FieldResolver
-      def self.resolve(type,fields)
-        self.new.resolve(type,fields)
-      end
-
-      attr_reader :history
-
-      def initialize
-        @history = Hash.new do |hash,key|
-          hash[key] = Hash.new
-        end
-      end
-
-      def resolve(type,fields)
-        history_key = fields
-        history_type = type
-        if fields.kind_of?(Array)
-          loop do
-            type = type.member_attribute.type
-            fields = fields.first
-            break unless fields.kind_of?(Array)
-          end
-        end
-
-        return true if fields == true
-
-        if history[history_type].include? history_key
-          return history[history_type][history_key]
-        end
-
-        result = history[history_type][history_key] = {}
-
-
-        fields.each do |name, sub_fields|
-
-          new_type = type.attributes[name].type
-          result[name] = resolve(new_type, sub_fields)
-        end
-
-        result
-      end
-
-      # perform a deep recursive *in place* merge
-      # form all values in +source+ onto +target+
-      #
-      # note: can not use ActiveSupport's Hash#deep_merge! because it does not
-      # properly do a recursive `deep_merge!`, but instead does `deep_merge`,
-      # which destroys the self-referential behavior of field hashes.
-      #
-      # note: unlike Hash#merge, doesn't take a block.
-      def deep_merge(target, source)
-        source.each do |current_key, source_value|
-          target_value = target[current_key]
-
-          target[current_key] = if target_value.is_a?(Hash) && source_value.is_a?(Hash)
-            deep_merge(target_value, source_value)
-          else
-            source_value
-          end
-        end
-        target
-      end
-
-    end
-
   end
 
 end

data/lib/praxis/plugin_concern.rb

@@ -11,7 +11,7 @@ module Praxis
       PLUGIN_CLASSES = [
         :Request,
         :Controller,
-        :ResourceDefinition,
+        :EndpointDefinition,
         :ActionDefinition,
         :Response,
         :ApiGeneralInfo

data/lib/praxis/plugins/mapper_plugin.rb

@@ -1,11 +1,23 @@
 require 'singleton'
-require 'praxis/extensions/attribute_filtering'
 
-module Praxis
+require 'praxis/extensions/field_selection'
+
+module Praxis  
   module Plugins
     module MapperPlugin
       include Praxis::PluginConcern
 
+      # The Mapper plugin is an overarching set of things to include in your application
+      # when you want to use the rendring, field_selection, filtering (and potentially pagination) extensions
+      # To use the plugin, set it up like any other plugin by registering to the bootloader.
+      # Typically you'd do that in environment.rb, inside the `Praxis::Application.configure do |application|` block, by:
+      #   application.bootloader.use Praxis::Plugins::MapperPlugin
+      #
+      # The plugin accepts only 1 configuration option thus far, which you can set inside the same block as:
+      #   application.config.mapper.debug_queries = true
+      # when debug_queries is set to true, the system will output information about the expanded fields 
+      # and associations that the system ihas calculated necessary to pull from the DB, based on the requested
+      # API fields, API filters and `property` dependencies defined in the domain models (i.e., resources)
       class Plugin < Praxis::Plugin
         include Singleton
 
@@ -29,36 +41,33 @@ module Praxis
         extend ActiveSupport::Concern
 
         included do
+          include Praxis::Extensions::Rendering
           include Praxis::Extensions::FieldExpansion
         end
 
-        def set_selectors
-          return unless self.media_type.respond_to?(:domain_model) &&
-            self.media_type.domain_model < Praxis::Mapper::Resource
-
-          resolved = Praxis::MediaType::FieldResolver.resolve(self.media_type, self.expanded_fields)
-          selector_generator.add(self.media_type.domain_model, resolved)
-        end
-
         def build_query(base_query) # rubocop:disable Metrics/AbcSize
           domain_model = self.media_type&.domain_model
           raise "No domain model defined for #{self.name}. Cannot use the attribute filtering helpers without it" unless domain_model
           
           filters = request.params.filters if request.params&.respond_to?(:filters)
+          # Handle filters
           base_query = domain_model.craft_filter_query( base_query , filters: filters )
-
+          # Handle field and nested field selection
           base_query = domain_model.craft_field_selection_query(base_query, selectors: selector_generator.selectors)
+          # handle pagination and ordering if the pagination extention is included
+          base_query = domain_model.craft_pagination_query(base_query, pagination: _pagination)  if self.respond_to?(:_pagination)
 
-          # TODO: handle pagination and ordering
           base_query
         end
 
         def selector_generator
-          @selector_generator ||= Praxis::Mapper::SelectorGenerator.new
-        end
+          return unless self.media_type.respond_to?(:domain_model) &&
+            self.media_type.domain_model < Praxis::Mapper::Resource
 
+          @selector_generator ||= \
+            Praxis::Mapper::SelectorGenerator.new.add(self.media_type.domain_model, self.expanded_fields)
+        end
       end
-
     end
   end
 end

data/lib/praxis/plugins/pagination_plugin.rb

@@ -1,14 +1,45 @@
 require 'singleton'
 require 'praxis/extensions/pagination'
 
-# Simple plugin concept
+# The PaginationPlugin can be configured to take advantage of adding pagination and sorting to
+# your DB queries.
+# When combined with the MapperPlugin, there is no extra configuration that needs to be done for
+# the system to appropriately identify the pagination and order parameters in the API, and translate
+# that in to the appropriate queries to fetch.
+# 
+# To use this plugin without the MapperPlugin (probably a rare case), one can apply the appropriate
+# clauses onto a query, by directly calling (in the controller) the `craft_pagination_query` method
+# of the domain_model associated to the controller's mediatype.
+# For example, here's how you can manually use this extension in a fictitious users index action:
+# def index
+#   base_query = User.all # Start by not excluding any user
+#   domain_model = self.media_type.domain_model
+#   objs = domain_model.craft_pagination_query(base_query, pagination: _pagination)
+#   display(objs)
+# end
+# 
+# This plugin accepts configuration about the default behavior of pagination.
+# Any of these configs can individually be overidden when defining each Pagination/Order parameters
+# in any of the Endpoint actions.
+#
 # Example configuration for this plugin
 # Praxis::Application.configure do |application|
 #   application.bootloader.use Praxis::Plugins::PaginationPlugin, {
+#     # The maximum number of results that a paginated response will ever allow
 #     max_items: 500,  # Unlimited by default,
+#     # The default page size to use when no `items` is specified
 #     default_page_size: 100,
-#     disallow_paging_by_default: false,
-#     # See all available options below
+#     # Disallows the use of the page type pagination mode when true (i.e., using 'page=' parameter)
+#     disallow_paging_by_default: true, # Default false
+#     # Disallows the use of the cursor type pagination mode when true (i.e., using 'by=' or 'from=' parameter)
+#     disallow_cursor_by_default: true, # Default false
+#     # The default mode params to use 
+#     paging_default_mode: {by: :uuid}, # Default {by: :uid}
+#     # Weather or not to enforce that all requested sort fields are part of the media_type attributes
+#     # when false (not enforced) only the first field would be checked
+#     sorting: {
+#       enforce_all_fields: false       # Default true 
+#     }
 #   end
 # end
 #
@@ -39,7 +70,6 @@ module Praxis
             attribute :paging_default_mode, Hash, default: Praxis::Types::PaginationParams.paging_default_mode
             attribute :disallow_paging_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_paging_by_default
             attribute :disallow_cursor_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_cursor_by_default
-            attribute :disallow_cursor_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_cursor_by_default
             attribute :sorting do
               attribute :enforce_all_fields, Attributor::Boolean, default: Praxis::Types::OrderingParams.enforce_all_fields
             end

data/lib/praxis/renderer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Praxis
+  class Renderer
+    attr_reader :include_nil
+    attr_reader :cache
+
+    class CircularRenderingError < StandardError
+      attr_reader :object
+      attr_reader :context
+
+      def initialize(object, context)
+        @object = object
+        @context = context
+
+        first = Attributor.humanize_context(context[0..10])
+        last = Attributor.humanize_context(context[-5..-1])
+        pretty_context = "#{first}...#{last}"
+        super("SystemStackError in rendering #{object.class} with context: #{pretty_context}")
+      end
+    end
+
+    def initialize(include_nil: false)
+      @cache = Hash.new do |hash, key|
+        hash[key] = {}
+      end
+
+      @include_nil = include_nil
+    end
+
+    # Renders an object using a given list of fields.
+    #
+    # @param [Object] object the object to render
+    # @param [Hash] fields the correct set of fields, as from FieldExpander
+    def render(object, fields, context: Attributor::DEFAULT_ROOT_CONTEXT)
+      if object.is_a? Praxis::Blueprint
+        @cache[object._cache_key][fields] ||= _render(object, fields, context: context)
+      else
+        if object.class < Attributor::Collection
+          object.each_with_index.collect do |sub_object, i|
+            sub_context = context + ["at(#{i})"]
+            render(sub_object, fields, context: sub_context)
+          end
+        else
+          _render(object, fields, context: context)
+        end
+      end
+    rescue SystemStackError
+      raise CircularRenderingError.new(object, context)      
+    end
+
+    def _render(object, fields, context: Attributor::DEFAULT_ROOT_CONTEXT)
+      if fields == true
+        return case object
+               when Attributor::Dumpable
+                 object.dump
+               else
+                 object
+               end
+      end
+
+      fields.each_with_object({}) do |(key, subfields), hash|
+        begin
+          value = object._get_attr(key)
+        rescue => e
+          raise Attributor::DumpError.new(context: context, name: key, type: object.class, original_exception: e)
+        end
+
+        if value.nil?
+          hash[key] = nil if self.include_nil
+          next
+        end
+
+        if subfields == true
+          hash[key] = case value
+                      when Attributor::Dumpable
+                        value.dump
+                      else
+                        value
+                      end
+        else
+          new_context = context + [key]
+          hash[key] = render(value, subfields, context: new_context)
+        end
+      end
+    end
+  end
+end