praxis 2.0.pre.10 → 2.0.pre.15

data/tasks/thor/example.rb

@@ -33,16 +33,22 @@ module PraxisGen
       puts
       puts "  cd #{app_name}"
       puts "  bundle"
-      puts "  bundle exec rake db:create db:migrate db:seed  # To create/migrate/seed the dev DB"
-      puts "  bundle exec rackup                             # To start the web server"
+      puts "  bundle exec rake db:recreate   # To create/migrate/seed the dev DB"
+      puts "  bundle exec rackup             # To start the web server"
       puts  
       puts "From another terminal/app, use curl (or your favorite HTTP client) to retrieve data from the API"
       puts "  For example: "
-      puts "  Get all users without filters or limit, and display only uid, and last_name fields"
-      puts "  curl -H 'X-Api-Version: 1' http://localhost:9292/users?fields=uid,last_name"
+      puts "  Get all users without filters or limit, and display only id, and first_name fields"
+      puts "  curl -G -H 'X-Api-Version: 1' http://localhost:9292/users \\"
+      puts "    --data-urlencode \"fields=id,first_name\""
       puts
-      puts "  Get the last 5 users, ordered by last_name (descending),  and display only uid, and last_name fields"
-      puts "  curl -H 'X-Api-Version: 1' 'http://localhost:9292/users?fields=uid,last_name&order=-last_name&pagination=by%3Dlast_name,items%3D5' "
+      puts "  Get the last 5 users, with last_names starting with \"L\" ordered by first_name (descending)"
+      puts "  and display only id, first_name, last_name, and email fields"
+      puts "  curl -G -H 'X-Api-Version: 1' http://localhost:9292/users \\"
+      puts "    --data-urlencode \"filters=last_name=L*\" \\"
+      puts "    --data-urlencode \"pagination=by=first_name,items=5\" \\"
+      puts "    --data-urlencode \"order=-first_name\" \\"      
+      puts "    --data-urlencode \"fields=id,first_name,last_name,email\""
       puts "  (Note: To list all routes use: bundle exec rake praxis:routes)"
       puts
       nil

data/tasks/thor/model.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PraxisGen
+  class Model < Thor
+    require 'active_support/inflector'
+    include Thor::Actions
+    
+    def self.source_root
+      File.dirname(__FILE__) + "/templates/generator/scaffold"
+    end
+
+    desc "gmodel", "Generates a skeleton model file under app/models for ActiveRecord or Sequel."
+    argument :model_name, required: true
+    option :orm, required: false, default: 'activerecord', enum: ['activerecord','sequel']
+    def g
+      #self.class.check_name(model_name)
+      template_file = \
+        if options[:orm] == 'activerecord'
+          'models/active_record.rb'
+        else
+          'models/sequel.rb'
+        end
+      puts "Generating Model for #{model_name}"        
+      template template_file, "app/models/#{model_name}.rb"
+      nil
+    end
+    # Helper functions (which are available in the ERB contexts)
+    no_commands do
+      def model_class
+        model_name.camelize
+      end
+    end
+
+    # TODO: do we want the argument to be camelcase? or snake case?
+    def self.check_name(name)
+      sanitized = name.downcase.gsub(/[^a-z0-9_]/, '')
+      raise "Please use only downcase letters, numbers and underscores for the model" unless sanitized == name
+    end
+  end
+end

data/tasks/thor/scaffold.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module PraxisGen
+  class Scaffold < Thor
+    require 'active_support/inflector'
+    include Thor::Actions
+    
+    attr_reader :actions_hash
+
+    def self.source_root
+      File.dirname(__FILE__) + "/templates/generator/scaffold"
+    end
+
+    desc "g","Generates an API design and implementation scaffold for managing a collection of <collection_name>"
+    argument :collection_name, required: true
+    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
+      self.class.check_name(collection_name)
+      @actions_hash = self.class.compose_actions_hash(options[:actions])
+      env_rb = Pathname.new(destination_root)+Pathname.new("config/environment.rb")
+      @pagination_plugin_found = File.open(env_rb).grep(/Praxis::Plugins::PaginationPlugin.*/).reject{|l| l.strip[0] == '#'}.present?
+      if options[:design]
+        say_status 'Design', "Generating scaffold for #{plural_class}", :blue
+        template 'design/media_types/item.rb', "design/#{version_dir}/media_types/#{collection_name.singularize}.rb"
+        template 'design/endpoints/collection.rb', "design/#{version_dir}/endpoints/#{collection_name}.rb"
+      end
+      if options[:implementation]
+        say_status 'Implement', "Generating scaffold for #{plural_class}", :blue
+        if options[:resource]
+          base_resource = Pathname.new(destination_root)+Pathname.new("app/#{version_dir}/resources/base.rb")
+          unless base_resource.exist?
+            # Copy an appropriate base resource for the version (resources within same version must share same base)
+            say_status "NOTE:", 
+              "Creating a base resource file for resources to inherit from (at 'app/#{version_dir}/resources/base.rb')", 
+              :yellow
+            say_status "", 
+              "If you had already other resources in the app, change them to derive from this Base"
+            template 'implementation/resources/base.rb', "app/#{version_dir}/resources/base.rb"
+          end
+          template 'implementation/resources/item.rb', "app/#{version_dir}/resources/#{collection_name.singularize}.rb"
+        end
+        template 'implementation/controllers/collection.rb', "app/#{version_dir}/controllers/#{collection_name}.rb"
+      end
+      nil
+    end
+
+    # Helper functions (which are available in the ERB contexts)
+    no_commands do
+      def plural_class
+        collection_name.camelize
+      end
+    
+      def singular_class
+        collection_name.singularize.camelize
+      end
+      
+      def version
+        options[:version]
+      end
+
+      def version_module
+        "V#{version}"
+      end
+    
+      def version_dir
+        version_module.camelize(:lower)
+      end
+
+      def action_enabled?(action)
+        @actions_hash[action.to_sym]
+      end
+
+      def pagination_enabled?
+        @pagination_plugin_found
+      end
+    end
+
+    def self.compose_actions_hash(actions_opt)
+      required = { index: true, show: true }
+      case actions_opt
+      when nil
+        required
+      when 'cr'
+        required.merge(create: true)
+      when 'cru'
+        required.merge(create: true, update: true)
+      when 'crud'
+        required.merge(create: true, update: true, delete: true)
+      when 'u'
+        required.merge(update: true)
+      when 'ud'
+        required.merge(update: true, delete: true)
+      when 'd'
+        required.merge(delete: true)
+      else
+        raise "actions option does not support the string #{actions_opt}"
+      end
+    end
+
+    def self.check_name(name)
+      sanitized = name.downcase.gsub(/[^a-z0-9_]/, '')
+      # TODO: bail or support CamelCase collections (for now only snake case)
+      raise "Please use only downcase letters, numbers and underscores for the collection" unless sanitized == name
+    end
+  end
+end

data/tasks/thor/templates/generator/empty_app/config/environment.rb

@@ -18,6 +18,7 @@ Praxis::Application.configure do |application|
   #     map :models, 'models/**/*'
   #     map :responses, '**/responses/**/*'
   #     map :exceptions, '**/exceptions/**/*'
+  #     map :concerns, '**/concerns/**/*'
   #     map :resources, '**/resources/**/*'
   #     map :controllers, '**/controllers/**/*'
   #   end

data/tasks/thor/templates/generator/example_app/Rakefile

@@ -32,10 +32,17 @@ namespace :db do
     puts "Database migrated."
   end
 
+  desc 'Fully receate, migrate and seed the DB'
+  task :recreate do
+    Rake::Task['db:drop'].invoke rescue nil
+    Rake::Task['db:create'].invoke
+    Rake::Task['db:migrate'].invoke
+    Rake::Task['db:seed'].invoke
+  end
+
   desc 'seed with example data'
   task seed: 'praxis:environment' do
-    require_relative 'spec/helpers/database_helper'
-    DatabaseHelper.seed!
+    require_relative 'db/seeds.rb'
   end
 
   desc 'drops current database'

data/tasks/thor/templates/generator/example_app/app/v1/concerns/controller_base.rb

@@ -0,0 +1,24 @@
+module V1
+  module Concerns
+    module ControllerBase
+      extend ActiveSupport::Concern
+      # Controller concen that wraps an API with a transaction, and automatically rolls it back
+      # for non-2xx (or 3xx) responses
+      included do
+        around :action do |controller, callee|
+          begin
+            # TODO: Support Sequel as well
+            ActiveRecord::Base.transaction do
+              callee.call
+              res = controller.response
+              # Force a rollback for non 2xx or 3xx responses
+              raise ActiveRecord::Rollback unless res.status >= 200 && res.status < 400
+            end
+          rescue ActiveRecord::Rollback
+            # No need to do anything, let the responses flow normally
+          end
+        end
+      end
+    end
+  end
+end

data/tasks/thor/templates/generator/example_app/app/v1/concerns/href.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module V1
+  module Resources
+    module Concerns
+      module Href
+        extend ActiveSupport::Concern
+
+        # Base module where the href concern will grab constants from
+        included do
+          def self.base_module
+            ::V1
+          end
+        end
+
+        module ClassMethods
+          def endpoint_path_template
+            # memoize a templated path for an endpoint, like
+            # /im/contacts/%{id}
+            return @endpoint_path_template if @endpoint_path_template
+
+            path = self.base_module.const_get(:Endpoints).const_get(model.name.split(':').last.pluralize).canonical_path.route.path
+            @endpoint_path_template = path.names.inject(path.to_s) { |p, name| p.sub(':' + name, "%{#{name}}") }
+          end
+        end
+
+        def href
+          format(self.class.endpoint_path_template, id: id)
+        end
+      end
+    end
+  end
+end

data/tasks/thor/templates/generator/example_app/app/v1/controllers/users.rb

@@ -4,8 +4,8 @@ module V1
   module Controllers
     class Users
       include Praxis::Controller
-      include Praxis::Extensions::Rendering
-      
+      include Concerns::ControllerBase
+
       implements V1::Endpoints::Users
 
       def index

data/tasks/thor/templates/generator/example_app/app/v1/resources/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../concerns/href'
+
+module V1
+  module Resources
+    class Base < Praxis::Mapper::Resource
+      include Resources::Concerns::Href
+
+      # Base for all V1 resources.
+      # Resources withing a single version should have resource mappings separate from other versions
+      # and the Mapper::Resource will appropriately maintain different model_maps for each Base classes
+    end
+  end
+end

data/tasks/thor/templates/generator/example_app/app/v1/resources/user.rb

@@ -2,42 +2,21 @@
 
 module V1
   module Resources
-    class User < Praxis::Mapper::Resource
+    class User < Base
       model ::User
 
-      # Mappings for the allowed filterd
+      # Mappings for the allowed filters
       filters_mapping(
-        'email': 'email',
-        'first_name': 'first_name',        
-        # Complex (convoluted?) mapping of state, just to show how we can modify and adapt the values/fields/operators
-        'state': lambda do |spec|
-          case spec[:value].to_s
-          when 'pending' # Pending users do not have a uuid
-            { name: :uuid, value: nil, op: spec[:op] }
-          when 'active' # Active users do not have a uuid (so "flip" the original equality condition)
-            opposite_op = spec[:op] == '=' ? '!=' : '='
-            { name: :uuid, value: nil, op: opposite_op }
-          else
-            raise "Cannot filter users by state #{spec[:value]}"
-          end
-        end,
+        'uuid': 'uuid',
+        'first_name': 'first_name',
+        'last_name': 'last_name',
+        'email': 'email'
       )
 
-      # Example of a property that depends on a differently named DB field
-      property :uid, dependencies: %i[id]
       # To compute the full_name (method below) we need to load first and last names from the DB
       property :full_name, dependencies: %i[first_name last_name]
 
-      def uid
-        id # underlying id field of the model
-      end
-
-      # Computed attribute: if uuid nil, user in in a pending stat, else active
-      def state 
-        self.uuid.nil? ? 'pending' : 'active'
-      end
-
-      # Computed attribute the combines first and last
+      # Computed attribute that combines first and last
       def full_name
         [first_name, last_name].join(' ')
       end

data/tasks/thor/templates/generator/example_app/config.ru

@@ -8,10 +8,9 @@ Bundler.require(:default, ENV['RACK_ENV'])
 # API field selection (a la GraphQL) - for querying and rendering
 # API filtering extensions (to add "where clauses") in listings
 # Views and partial rendering (for ActiveRecord models)
-
 require 'praxis/plugins/mapper_plugin'
 require 'praxis/mapper/active_model_compat'
-require 'praxis/extensions/field_selection'
+# Want to take advantage of the pagination and sorting extensions as well
 require 'praxis/plugins/pagination_plugin'
 
 # Start the sqlite DB

data/tasks/thor/templates/generator/example_app/config/environment.rb

@@ -3,8 +3,8 @@ Praxis::Application.configure do |application|
 
   # Configure the Mapper plugin (if we want to use all the filtering/field_selection extensions)
   application.bootloader.use Praxis::Plugins::MapperPlugin
-  # Cconfigure the Pagination plugin (if we want to use all the pagination/ordering extensions)
-  application.bootloader.use Praxis::Plugins::PaginationPlugin, {
+  # Configure the Pagination plugin (if we want to use all the pagination/ordering extensions)
+  application.bootloader.use Praxis::Plugins::PaginationPlugin, **{
     # max_items: 500,  # Unlimited by default,
     # default_page_size: 100,
     # paging_default_mode: {by: :id},
@@ -33,6 +33,7 @@ Praxis::Application.configure do |application|
   #     map :models, 'models/**/*'
   #     map :responses, '**/responses/**/*'
   #     map :exceptions, '**/exceptions/**/*'
+  #     map :concerns, '**/concerns/**/*'
   #     map :resources, '**/resources/**/*'
   #     map :controllers, '**/controllers/**/*'
   #   end

data/tasks/thor/templates/generator/example_app/db/migrate/20201010101010_create_users_table.rb

@@ -3,9 +3,10 @@
 class CreateUsersTable < ActiveRecord::Migration[5.2]
   def change
     create_table :users do |table|
-      table.column :uuid, :integer
-      table.column :first_name, :string
+      table.column :uuid, :string, null: false
+      table.column :first_name, :string, null: false
       table.column :last_name, :string
+      table.column :email, :string
     end
   end
 end

data/tasks/thor/templates/generator/example_app/db/seeds.rb

@@ -0,0 +1,6 @@
+
+require_relative '../spec/helpers/database_helper'
+# Invoke the encapsulated seed class...
+DatabaseHelper.seed!
+
+# Add more seeds here..

data/tasks/thor/templates/generator/example_app/design/v1/endpoints/users.rb

@@ -4,7 +4,6 @@ module V1
   module Endpoints
     class Users
       include Praxis::EndpointDefinition
-      # include AuthenticatedEndpoint
 
       media_type MediaTypes::User
       version '1'
@@ -18,15 +17,16 @@ module V1
           attribute :fields, Praxis::Types::FieldSelector.for(MediaTypes::User),
                     description: 'Fields with which to render the result.'
           attribute :filters, Praxis::Types::FilteringParams.for(MediaTypes::User) do
-            filter 'state', using: ['=', '!=']
+            filter 'uuid', using: ['=', '!=']
             filter 'first_name', using: ['=', '!='], fuzzy: true
             filter 'last_name', using: ['=', '!='], fuzzy: true
+            filter 'email', using: ['=', '!=']
           end
           attribute :pagination, Praxis::Types::PaginationParams.for(MediaTypes::User) do
-            by_fields :uid, :first_name, :last_name
+            by_fields :uuid, :first_name, :last_name
           end
           attribute :order, Praxis::Extensions::Pagination::OrderingParams.for(MediaTypes::User) do
-            by_fields :uid, :last_name, :first_name
+            by_fields :uuid, :last_name, :first_name
           end          
         end
         response :ok, media_type: Praxis::Collection.of(MediaTypes::User)

data/tasks/thor/templates/generator/example_app/design/v1/media_types/user.rb

@@ -9,16 +9,11 @@ module V1
       description 'A user in the system'
 
       attributes do
-        attribute :uid, String
+        attribute :id, Integer
         attribute :uuid, String
         attribute :email, String
         attribute :first_name, String
         attribute :last_name, String
-        attribute :state, String, values: %i[pending active]
-      end
-
-      default_fieldset do
-        attribute :uid
       end
     end
   end