praxis 2.0.pre.10 → 2.0.pre.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd76d8bd13954d5607d009ee37ff7fc1a8ef8a2c6c8c87544dddaee332d984bf
-  data.tar.gz: 719bffed7ea98fe42d7c620cd4377c4201c9d23e49a9777e981647d671b39ffd
+  metadata.gz: 7bbd374311046cf8d12c68d564382de6cbfd0c1032c45bbc8c1ac00d7a02e68a
+  data.tar.gz: e33676f45266facdbcae595c2c05ca94ae8dfa34134aa9e4113e5a5d9d729052
 SHA512:
-  metadata.gz: 18e87e4563faa7a1ffbba174634f1ebabe57320b8324e4ac23a711f5785906482412db711c83308ff87264d48cc496f8bd118b5a5ac77f1d6bd8f09e543f90ed
-  data.tar.gz: 9da869a6acecf7c04273ef7dc0519be0cf8b3d00c29df16c851df04f5ea52d7cf4d62123e25533b8887c0a30b940155abfbd812f4fe2b347d1139df91e3e124f
+  metadata.gz: 5db86e95bd0b723560036435ded99b893fd92bd55f20dc4b49e326d96e7c9422549124ba986eb3248ff746d6bf928a60e6677b854c8761a34c026c7430a578bb
+  data.tar.gz: 39677f252617f79d3d054fd2286562d3355310d8161096c7c73294d2b242cee4ebdf749b462d7f1c5261fc487e80ba473dcd258dcb77a510c47db7e698275cad

data/.travis.yml

@@ -1,10 +1,8 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.4
-  - 2.5
   - 2.6
-  - 2.7
+  - 2.7  
 script:
   - bundle exec rspec spec
 branches:

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## next
 
+## 2.0.pre.11
+
+- Remove MapperPlugin's `set_selectors` (made `selector_generator` lazy instead), and ensure it includes the rendering extensions to the Controllers. Less things to configure if you opt into the Mapper way.
+- Built scaffolding generator for quickly creating a new API endpoint in the praxis binary (it builds endpoint+mediatype+controller+resource at one, with useful base code and comments)
+- Dropped support for Ruby 2.4 and 2.5 as some of the newest dependent gems are dropping it as well.
+- Simplify filters_mapping definition, by not requiring to define same-name mappings if the underlying model has an attribute with the same exact name. i.e., a `name: :name` entry is not necessary if the model has a `:name` attribute.
+
+## 2.0.pre.10
+
 - Simple, but pervasive breaking change: Rename `ResourceDefinition` to `EndpointDefinition` (but same functionality).
 - Remove all deprecated features (and raise error describing it's not supported yet)
 - Remove `Links` and `LinkBuilder`. Those seem unnecessary from a Framework point of view as they aren't clear most

data/bin/praxis

@@ -46,7 +46,7 @@ class PraxisGenerator < Thor
   def routes
   end
 
-  desc "docs [generate|browser|package]", <<-EOF  
+  desc "docs [generate|browser|package]", <<~EOF
   Generates API documentation and a Web App to inspect it
     generate - Generates the JSON docs
     browser  - (default) Generates JSON docs, and automatically starts a Web app to browse them.
@@ -81,7 +81,64 @@ class PraxisGenerator < Thor
     gen = ::PraxisGen::Example.new([app_name])
     gen.destination_root = app_name
     gen.invoke(:example)
-  end  
+  end
+
+  desc_for "g COLLECTION_NAME", ::PraxisGen::Scaffold, :g
+  # Cannot use the argument below or it will apply to all commands (the action in the class has it)
+  # argument :collection_name, required: false
+  # The options, however, since they're optional are fine (But need to be duplicated from the class :( )
+  option :version, required: false, default: '1',
+          desc: 'Version string for the API endpoint. This also dictates the directory structure (i.e., v1/endpoints/...))'
+  option :design, type: :boolean, default: true,
+          desc: 'Include the Endpoint and MediaType files for the collection'
+  option :implementation, type: :boolean, default: true,
+          desc: 'Include the Controller and (possibly the) Resource files for the collection (see --no-resource)'
+  option :resource, type: :boolean, default: true,
+          desc: 'Disable (or enable) the creation of the Resource files when generating implementation'
+  option :model, type: :string, enum: ['activerecord','sequel'],
+          desc: 'It also generates a model for the given ORM. An empty --model flag will default to activerecord'
+  option :actions, type: :string, default: 'crud', enum: ['cr','cru','crud','u','ud','d'],
+          desc: 'Specifies the actions to generate for the API. cr=create, u=update, d=delete. Index and show actions are always generated'
+  def g(*args)
+    # Because we cannot share the :collection_name argument, we need to do this check here, before
+    # we "parse" it and pass it to the g command
+    unless args.size == 1
+      ::PraxisGen::Scaffold.command_help(shell,:g)
+      exit 1
+    end
+
+    collection_name,_ = args
+    ::PraxisGen::Scaffold.new([collection_name],options).invoke(:g)
+    if options[:model]
+      # Make it easy to be able to both enable or not enable the creation of the model, by passing --model=...
+      # but also make it easy so that if there is no value for it, it default to activerecord
+      opts = {orm: options[:model] }
+      opts[:orm] = 'activerecord' if opts[:orm] == 'model' # value is model param passed by no value
+      ::PraxisGen::Model.new([collection_name.singularize],opts).invoke(:g)
+    end
+  end
+
+  # Initially, the idea was to build some quick model generator, but I think it's better to keep it
+  # simple and just use the scaffold generator with `--no-implementation --no-design --model` instead
+  # Left here in case we want to rescue it
+  # desc_for "gmodel MODEL_NAME", ::PraxisGen::Model, :g
+  # # Cannot use the argument below or it will apply to all commands (the action in the class has it)
+  # # argument :collection_name, required: false
+  # # The options, however, since they're optional are fine (But need to be duplicated from the class :( )
+  # option :orm, required: false, default: 'activerecord', enum: ['activerecord','sequel'],
+  #         desc: 'Type of ORM model to create.'
+  # def gmodel(*args)
+  #   # Because we cannot share the :collection_name argument, we need to do this check here, before
+  #   # we "parse" it and pass it to the g command
+  #   unless args.size == 1
+  #     ::PraxisGen::Model.command_help(shell,:g)
+  #     exit 1
+  #   end
+
+  #   model_name,_ = args
+  #   ::PraxisGen::Model.new([model_name],options).invoke(:g)
+  # end
+
 end
     
 PraxisGenerator.start(ARGV)

data/lib/praxis/bootloader_stages/environment.rb

@@ -33,6 +33,7 @@ module Praxis
             map :models, 'models/**/*'
             map :responses, '**/responses/**/*'
             map :exceptions, '**/exceptions/**/*'
+            map :concerns, '**/concerns/**/*'
             map :resources, '**/resources/**/*'
             map :controllers, '**/controllers/**/*'
           end

data/lib/praxis/docs/open_api_generator.rb

@@ -244,7 +244,7 @@ module Praxis
         resources_by_version.keys.each do |version|
           FileUtils.mkdir_p @doc_root_dir + '/' + version
         end
-        FileUtils.mkdir_p @doc_root_dir + '/unversioned'
+        FileUtils.mkdir_p @doc_root_dir + '/unversioned' if resources_by_version.keys.include?('n/a')
       end
 
       def normalize_media_types( mtis )

data/lib/praxis/extensions/attribute_filtering/active_record_filter_query_builder.rb

@@ -5,27 +5,43 @@ module Praxis
     module AttributeFiltering
       ALIAS_TABLE_PREFIX = ''
       require_relative 'active_record_patches'
+      # Helper class that can present an SqlLiteral string which we have already quoted
+      # ... but! that can properly provide a "to_sym" that has the value unquoted
+      # This is necessary as (the latest AR code):
+      # * does not carry over "references" in joins if they are not SqlLiterals
+      # * but, at the same time, it indexes the references using the .to_sym value (which is really expected to be the normal string, without quotes)
+      # If we pass a normal SqlLiteral, instead of our wrapper, without quoting the table, the current AR code will never quote it to form the 
+      # SQL string, as it's already a literal...so our "/" type separators as names won't work without quoting.
+      class QuasiSqlLiteral < Arel::Nodes::SqlLiteral
+        def initialize(quoted:, symbolized:)
+          @symbolized = symbolized
+          super(quoted)
+        end
+        def to_sym
+          @symbolized
+        end
+      end
 
       class ActiveRecordFilterQueryBuilder
-      attr_reader :query, :model, :attr_to_column
+      attr_reader :query, :model, :filters_map
 
         # Base query to build upon
         def initialize(query: , model:, filters_map:, debug: false)
           @query = query
           @model = model
-          @attr_to_column = filters_map
+          @filters_map = filters_map
           @logger = debug ? Logger.new(STDOUT) : nil
         end
         
-        def debug(msg)
-          @logger && @logger.info(msg)
+        def debug_query(msg, query)
+          @logger.info(msg + query.to_sql) if @logger
         end
 
         def generate(filters)
           # Resolve the names and values first, based on filters_map
           root_node = _convert_to_treenode(filters)
           craft_filter_query(root_node, for_model: @model)
-          debug("SQL due to filters: #{@query.all.to_sql}")
+          debug_query("SQL due to filters: ", @query.all)
           @query
         end
 
@@ -45,13 +61,30 @@ module Praxis
 
         private
 
+        def _mapped_filter(name)
+          target = @filters_map[name]
+          unless target
+            if @model.attribute_names.include?(name.to_s)
+              # Cache it in the filters mapping (to avoid later lookups), and return it.
+              @filters_map[name] = name
+              target = name
+            end
+          end
+          return target
+        end
+
         # Resolve and convert from filters, to a more manageable and param-type-independent structure
         def _convert_to_treenode(filters)
           # Resolve the names and values first, based on filters_map
           resolved_array = []
           filters.parsed_array.each do |filter|
-            mapped_value = attr_to_column[filter[:name]]
-            raise "Filtering by #{filter[:name]} not allowed (no mapping found)" unless mapped_value
+            mapped_value = _mapped_filter(filter[:name])
+            unless mapped_value
+              msg = "Filtering by #{filter[:name]} is not allowed. No implementation mapping defined for it has been found \
+                and there is not a model attribute with this name either.\n" \
+                "Please add a mapping for #{filter[:name]} in the `filters_mapping` method of the appropriate Resource class"
+              raise msg
+            end
             bindings_array = \
               if mapped_value.is_a?(Proc)
                 result = mapped_value.call(filter)
@@ -85,7 +118,7 @@ module Praxis
         end
 
         def add_clause(column_prefix:, column_object:, op:, value:)
-          @query = @query.references(column_prefix) #Mark where clause referencing the appropriate alias
+          @query = @query.references(build_reference_value(column_prefix)) #Mark where clause referencing the appropriate alias
           likeval = get_like_value(value)
           case op
             when '!' # name! means => name IS NOT NULL (and the incoming value is nil)
@@ -165,6 +198,22 @@ module Praxis
             likeval
           end
         end
+
+        # The value that we need to stick in the references method is different in the latest Rails
+        maj, min, _ = ActiveRecord.gem_version.segments
+        if maj == 5 || (maj == 6 && min == 0)
+          # In AR 6 (and 6.0) the references are simple strings
+          def build_reference_value(column_prefix)
+            column_prefix
+          end
+        else
+          # The latest AR versions discard passing references to joins when they're not SqlLiterals ... so let's wrap it
+          # with our class, so that it is a literal (already quoted), but that can still provide the expected "symbol" without quotes
+          # so that our aliasing code can match it.
+          def build_reference_value(column_prefix)
+            QuasiSqlLiteral.new(quoted: query.connection.quote_table_name(column_prefix), symbolized: column_prefix.to_sym)
+          end
+        end
       end
     end
   end

data/lib/praxis/extensions/attribute_filtering/sequel_filter_query_builder.rb

@@ -9,7 +9,7 @@ module Praxis
       class << self
         def for(definition)
           Class.new(self) do
-            @attr_to_column = case definition
+            @filters_map = case definition
                               when Hash
                                 definition
                               when Array
@@ -18,7 +18,7 @@ module Praxis
                                 raise "Cannot use FilterQueryBuilder.of without passing an array or a hash (Got: #{definition.class.name})"
                               end
             class << self
-              attr_reader :attr_to_column
+              attr_reader :filters_map
             end
           end
         end
@@ -33,13 +33,18 @@ module Praxis
       end
 
       # By default we'll simply use the incoming op and value, and will map
-      # the attribute based on what's on the `attr_to_column` hash
+      # the attribute based on what's on the `filters_map` definition
       def generate(filters)
         raise "Not refactored yet!"
         seen_associations = Set.new
         filters.each do |(attr, spec)|
-          column_name = attr_to_column[attr]
-          raise "Filtering by #{attr} not allowed (no mapping found)" unless column_name
+          column_name = _mapped_filter(attr)
+          unless column_name
+            msg = "Filtering by #{attr} is not allowed. No implementation mapping defined for it has been found \
+              and there is not a model attribute with this name either.\n" \
+              "Please add a mapping for #{attr} in the `filters_mapping` method of the appropriate Resource class"
+            raise msg
+          end          
           if column_name.is_a?(Proc)
             bindings = column_name.call(spec)
             # A hash of bindings, consisting of a key with column name and a value to the query value
@@ -64,9 +69,16 @@ module Praxis
         add_clause(attr: column_name, op: op, value: value)
       end
 
-      def attr_to_column
-        # Class method defined by the subclassing Class (using .for)
-        self.class.attr_to_column
+      def _mapped_filter(name)
+        target = self.class.filters_map[name]
+        unless target
+          if @model.attribute_names.include?(name.to_s)
+            # Cache it in the filters mapping (to avoid later lookups), and return it.
+            self.class.filters_map[name] = name
+            target = name
+          end
+        end
+        return target
       end
 
       # Private to try to funnel all column names through `generate` that restricts

data/lib/praxis/extensions/pagination.rb

@@ -14,10 +14,9 @@ module Praxis
     module Pagination
       extend ActiveSupport::Concern
       # This PaginatedController concern should be added to controllers that have actions that define the
-      # pagination and order parameters so that calling `paginate( query: <base_query>, table: <main_table_name> )`
-      # would handle all the required logic for paginating, ordering and generating the Link and TotalCount headers.
-      # This assumes that the query object are chainable and based on ActiveRecord at the moment (although that logic)
-      # can be easily applied to other chainable query proxies.
+      # pagination and order parameters so that one can call the domain model to craft the query
+      # `domain_model.craft_pagination_query(base_query, pagination: _pagination)`
+      # This will handle all the required logic for paginating, ordering and generating the Link and TotalCount headers.
       #
       # Here's a simple example on how to use it for a fake Items controller
       # class Items < V1::Controllers::BaseController
@@ -29,7 +28,8 @@ module Praxis
       #
       #   def index(filters: nil, pagination: nil, order: nil,  **_args)
       #     items = current_user.items.all
-      #     items = _craft_pagination_query( query: items)
+      #     domain_model = self.media_type.domain_model
+      #     items = domain_model.craft_pagination_query( query: items, pagination: _pagination)
       #
       #     display(items)
       #   end
@@ -71,33 +71,6 @@ module Praxis
         @_pagination = PaginationStruct.new(pagination[:paginator], pagination[:order])
       end
 
-      # Main entrypoint: Handles all pagination pieces
-      # takes:
-      # * the query to build from and the table
-      # * the request (for link header generation)
-      # * requires the _pagination variable to be there (set by this module) to return the pagination struct
-      def _craft_pagination_query(query:, type: :active_record)
-        handler_klass = \
-          case type
-          when :active_record
-            ActiveRecordPaginationHandler
-          when :sequel
-            SequelPaginationHandler
-          else
-            raise "Attempting to use pagination but Active Record or Sequel gems found"
-          end
- 
-        # Gather and save the count if required
-        if _pagination.paginator&.total_count
-          _pagination.total_count = handler_klass.count(query.dup)
-        end
-        
-        query = handler_klass.order(query, _pagination.order)
-        # Maybe this is a class instance instead of a class method?...(of the appropriate AR/Sequel type)...
-        # self.class.paginate(query, table, _pagination)
-        handler_klass.paginate(query, _pagination)
-      end
-
       def build_pagination_headers(pagination:, current_url:, current_query_params:)
         links = if pagination.paginator.by
                   # We're assuming that the last element has a "symbol/string" field with the same name of the "by" pagination.

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

@@ -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|