servus 0.1.3 → 0.1.5

data/lib/generators/servus/event_handler/event_handler_generator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Servus
+  module Generators
+    # Rails generator for creating Servus event handlers.
+    #
+    # Generates an event handler class and spec file.
+    #
+    # @example Generate an event handler
+    #   rails g servus:event_handler user_created
+    #
+    # @example Generated files
+    #   app/events/user_created_handler.rb
+    #   spec/app/events/user_created_handler_spec.rb
+    #
+    # @see https://guides.rubyonrails.org/generators.html
+    class EventHandlerGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :no_docs, type: :boolean,
+                             default: false,
+                             desc: 'Skip documentation comments in generated files'
+
+      # Creates the event handler and spec files.
+      #
+      # @return [void]
+      def create_handler_file
+        template 'handler.rb.erb', handler_path
+        template 'handler_spec.rb.erb', handler_spec_path
+      end
+
+      private
+
+      # Returns the path for the handler file.
+      #
+      # @return [String] handler file path
+      # @api private
+      def handler_path
+        File.join(Servus.config.events_dir, "#{file_name}_handler.rb")
+      end
+
+      # Returns the path for the handler spec file.
+      #
+      # @return [String] spec file path
+      # @api private
+      def handler_spec_path
+        File.join('spec', Servus.config.events_dir, "#{file_name}_handler_spec.rb")
+      end
+
+      # Returns the handler class name.
+      #
+      # @return [String] handler class name
+      # @api private
+      def handler_class_name
+        "#{class_name}Handler"
+      end
+    end
+  end
+end

data/lib/generators/servus/event_handler/templates/handler.rb.erb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+<%- unless options[:no_docs] -%>
+# Handles the :<%= file_name %> event by invoking configured services.
+#
+# EventHandlers subscribe to a single event and declaratively map it to one or
+# more service invocations. This provides clean separation between event emission
+# (what happened) and event handling (what to do about it).
+#
+# @example Basic usage
+#   class <%= handler_class_name %> < Servus::EventHandler
+#     handles :<%= file_name %>
+#
+#     # Invoke a service when this event fires
+#     invoke SendEmail::Service, async: true do |payload|
+#       { user_id: payload[:user_id], email: payload[:email] }
+#     end
+#   end
+#
+# @example Multiple service invocations
+#   invoke SendWelcomeEmail::Service, async: true, queue: :mailers do |payload|
+#     { user_id: payload[:user_id] }
+#   end
+#
+#   invoke TrackAnalytics::Service, async: true do |payload|
+#     { event: '<%= file_name %>', user_id: payload[:user_id] }
+#   end
+#
+# @example Conditional invocation
+#   invoke GrantRewards::Service, if: ->(payload) { payload[:premium] } do |payload|
+#     { user_id: payload[:user_id] }
+#   end
+#
+# @example With payload schema validation
+#   schema payload: {
+#     type: 'object',
+#     required: ['user_id'],
+#     properties: {
+#       user_id: { type: 'integer' },
+#       email: { type: 'string', format: 'email' }
+#     }
+#   }
+#
+# @example Emit this event from anywhere
+#   # From controllers, jobs, rake tasks, etc.
+#   <%= handler_class_name %>.emit({ user_id: 123, email: 'user@example.com' })
+#
+# Available options for `invoke`:
+# - async: true          - Invoke service asynchronously via ActiveJob
+# - queue: :queue_name   - Specify ActiveJob queue (requires async: true)
+# - if: ->(payload) {}   - Condition that must be true to invoke
+# - unless: ->(payload) {} - Condition that must be false to invoke
+#
+# @see Servus::EventHandler
+# @see Servus::Events::Bus
+<%- end -%>
+class <%= handler_class_name %> < Servus::EventHandler
+  handles :<%= file_name %>
+
+<%- unless options[:no_docs] -%>
+  # TODO: Define payload schema (optional but recommended)
+  # schema payload: {
+  #   type: 'object',
+  #   required: ['required_field'],
+  #   properties: {
+  #     required_field: { type: 'string' }
+  #   }
+  # }
+
+  # TODO: Add service invocations
+  # invoke YourService, async: true do |payload|
+  #   {
+  #     # Map event payload to service arguments
+  #     argument_name: payload[:field_name]
+  #   }
+  # end
+<%- end -%>
+  schema payload: {
+    type: 'object',
+    description: 'JSON schema for the <%= handler_class_name %> event payload',
+  }
+
+  # invoke ExampleService, async: true do |payload|
+  #   { example_arg: payload[:example_field] }
+  # end
+end

data/lib/generators/servus/event_handler/templates/handler_spec.rb.erb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= handler_class_name %> do
+<%- unless options[:no_docs] -%>
+  # Test that the handler invokes the correct services with properly mapped arguments.
+  #
+  # Example test pattern:
+  #   it 'invokes YourService with correct arguments' do
+  #     expect(YourService).to receive(:call_async).with(user_id: 123)
+  #     described_class.handle({ user_id: 123, email: 'test@example.com' })
+  #   end
+  #
+  # For testing event emission from controllers/jobs:
+  #   include Servus::Testing::EventHelpers
+  #
+  #   it 'emits <%= file_name %> event' do
+  #     servus_expect_event(:<%= file_name %>)
+  #       .with_payload(hash_including(user_id: 123))
+  #       .when { YourController.new.create }
+  #   end
+
+<%- end -%>
+  let(:payload) do
+    {
+      # TODO: Add sample payload fields
+      # user_id: 123,
+      # email: 'test@example.com'
+    }
+  end
+
+<%- unless options[:no_docs] -%>
+  # TODO: Add tests for service invocations
+  # it 'invokes YourService with mapped arguments' do
+  #   expect(YourService).to receive(:call_async).with(user_id: payload[:user_id])
+  #   described_class.handle(payload)
+  # end
+
+  # TODO: Test conditional logic if using :if or :unless
+  # it 'skips invocation when condition is false' do
+  #   expect(YourService).not_to receive(:call_async)
+  #   described_class.handle(payload.merge(premium: false))
+  # end
+<%- else -%>
+  # Add your tests here
+<%- end -%>
+end

data/lib/generators/servus/service/service_generator.rb

@@ -2,12 +2,37 @@
 
 module Servus
   module Generators
-    # Servus Generator
+    # Rails generator for creating Servus service objects.
+    #
+    # Generates a complete service structure including:
+    # - Service class file
+    # - RSpec test file
+    # - JSON schema files for arguments and results
+    #
+    # @example Generate a service
+    #   rails g servus:service namespace/do_something_helpful user amount
+    #
+    # @example Generated files
+    #   app/services/namespace/do_something_helpful/service.rb
+    #   spec/services/namespace/do_something_helpful/service_spec.rb
+    #   app/schemas/services/namespace/do_something_helpful/arguments.json
+    #   app/schemas/services/namespace/do_something_helpful/result.json
+    #
+    # @see https://guides.rubyonrails.org/generators.html
     class ServiceGenerator < Rails::Generators::NamedBase
       source_root File.expand_path('templates', __dir__)
 
       argument :parameters, type: :array, default: [], banner: 'parameter'
 
+      class_option :no_docs, type: :boolean,
+                             default: false,
+                             desc: 'Skip documentation comments in generated files'
+
+      # Creates all service-related files.
+      #
+      # Generates the service class, spec file, and schema files from templates.
+      #
+      # @return [void]
       def create_service_file
         template 'service.rb.erb', service_path
         template 'service_spec.rb.erb', service_path_spec
@@ -19,40 +44,82 @@ module Servus
 
       private
 
+      # Returns the path for the service file.
+      #
+      # @return [String] service file path
+      # @api private
       def service_path
         "app/services/#{file_path}/service.rb"
       end
 
+      # Returns the path for the service spec file.
+      #
+      # @return [String] spec file path
+      # @api private
       def service_path_spec
         "spec/services/#{file_path}/service_spec.rb"
       end
 
+      # Returns the path for the result schema file.
+      #
+      # @return [String] result schema path
+      # @api private
       def service_result_schema_path
         "app/schemas/services/#{file_path}/result.json"
       end
 
+      # Returns the path for the arguments schema file.
+      #
+      # @return [String] arguments schema path
+      # @api private
       def service_arguments_shecma_path
         "app/schemas/services/#{file_path}/arguments.json"
       end
 
+      # Returns the service class name with ::Service appended.
+      #
+      # @return [String] service class name
+      # @api private
       def service_class_name
         "#{class_name}::Service"
       end
 
+      # Returns the fully-qualified service class name.
+      #
+      # @return [String] fully-qualified class name
+      # @api private
       def service_full_class_name
         service_class_name.include?('::') ? service_class_name : "::#{service_class_name}"
       end
 
+      # Generates the parameter list for the initialize method.
+      #
+      # @return [String] parameter list with keyword syntax
+      # @example
+      #   parameter_list # => "(user:, amount:)"
+      # @api private
       def parameter_list
         return '' if parameters.empty?
 
         "(#{parameters.map { |param| "#{param}:" }.join(', ')})"
       end
 
+      # Generates instance variable assignments for initialize method.
+      #
+      # @return [String] multi-line instance variable assignments
+      # @example
+      #   initialize_params # => "@user = user\n    @amount = amount"
+      # @api private
       def initialize_params
         parameters.map { |param| "@#{param} = #{param}" }.join("\n    ")
       end
 
+      # Generates attr_reader declarations for parameters.
+      #
+      # @return [String] attr_reader declaration or empty string
+      # @example
+      #   attr_readers # => "attr_reader :user, :amount"
+      # @api private
       def attr_readers
         return '' if parameters.empty?
 

data/lib/generators/servus/service/templates/arguments.json.erb

@@ -1,15 +1,24 @@
 {
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "<%= service_class_name %> Arguments",
+  "description": "JSON Schema for validating <%= service_class_name %> input arguments",
   "type": "object",
   "properties": {
-    <%- parameters.each do |param| %>
-      "<%= param %>": {
-        "type": "UNDECLARED_TYPE"
-      }
-    <% end %>
+<%- parameters.each_with_index do |param, index| -%>
+    "<%= param %>": {
+      "type": "string",
+      "description": "TODO: Describe the <%= param %> parameter"
+    }<%= index < parameters.length - 1 ? ',' : '' %>
+<%- end -%>
+<%- if parameters.empty? -%>
   },
+<%- else -%>
+  },
+<%- end -%>
   "required": [
-    <%- parameters.each do |param| %>
-      "<%= param %>",
-    <% end %>
-  ]
-}
+<%- parameters.each_with_index do |param, index| -%>
+    "<%= param %>"<%= index < parameters.length - 1 ? ',' : '' %>
+<%- end -%>
+  ],
+  "additionalProperties": false
+}

data/lib/generators/servus/service/templates/result.json.erb

@@ -1,4 +1,10 @@
 {
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "<%= service_class_name %> Result",
+  "description": "JSON Schema for validating <%= service_class_name %> result data",
   "type": "object",
-  "properties": {}
-}
+  "properties": {
+  },
+  "required": [],
+  "additionalProperties": true
+}

data/lib/generators/servus/service/templates/service.rb.erb

@@ -1,12 +1,109 @@
+# frozen_string_literal: true
+
+<%- unless options[:no_docs] -%>
+# Performs <%= file_name.humanize.downcase %> operations.
+#
+# Services encapsulate business logic with automatic validation, logging,
+# benchmarking, and error handling. They return Response objects indicating
+# success or failure.
+#
+# @example Basic usage
+#   result = <%= service_full_class_name %>.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: value" }.join(', ') %>)
+#
+#   if result.success?
+#     result.data # => { ... }
+#   else
+#     result.error.message # => "Error description"
+#   end
+#
+<%- unless parameters.empty? -%>
+# @example With all parameters
+#   result = <%= service_full_class_name %>.call(
+<%- parameters.each do |param| -%>
+#     <%= param %>: <%= param %>_value<%= param == parameters.last ? '' : ',' %>
+<%- end -%>
+#   )
+#
+<%- end -%>
+# @example Async execution (via ActiveJob)
+#   <%= service_full_class_name %>.call_async(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: value" }.join(', ') %>)
+#
+# @example With event emission
+#   class <%= service_class_name %> < Servus::Base
+#     emits :completed, on: :success
+#     emits :failed, on: :failure
+#     # ...
+#   end
+#
+# @see Servus::Base
+# @see Servus::Support::Response
+<%- end -%>
 module <%= class_name %>
-  class Service < Servus::ApplicationService
+  class Service < Servus::Base
+<%- unless options[:no_docs] -%>
+    # TODO: Define argument validation schema (optional but recommended)
+    # schema arguments: {
+    #   type: 'object',
+<%- if parameters.any? -%>
+    #   required: [<%= parameters.map { |p| "'#{p}'" }.join(', ') %>],
+<%- else -%>
+    #   required: [],
+<%- end -%>
+    #   properties: {
+<%- parameters.each do |param| -%>
+    #     <%= param %>: { type: 'string' }<%= param == parameters.last ? '' : ',' %>
+<%- end -%>
+<%- if parameters.empty? -%>
+    #     # property_name: { type: 'string' }
+<%- end -%>
+    #   }
+    # }
+
+    # TODO: Define result validation schema (optional)
+    # schema result: {
+    #   type: 'object',
+    #   required: [],
+    #   properties: {
+    #     # result_field: { type: 'string' }
+    #   }
+    # }
+
+<%- end -%>
+<%- unless options[:no_docs] -%>
+    # Initializes the service with required parameters.
+    #
+<%- parameters.each do |param| -%>
+    # @param <%= param %> [Object] TODO: document this parameter
+<%- end -%>
+<%- if parameters.empty? -%>
+    # @param args [Hash] service arguments
+<%- end -%>
+<%- end -%>
     def initialize<%= parameter_list %>
-      <%= initialize_params %>
+      <%= initialize_params.empty? ? '# TODO: Initialize instance variables' : initialize_params %>
     end
+
+<%- unless options[:no_docs] -%>
+    # Executes the service logic.
+    #
+    # @return [Servus::Support::Response] success or failure response
+    #
+    # @example Returning success
+    #   success({ user_id: 123, status: 'active' })
+    #
+    # @example Returning failure
+    #   failure('Something went wrong')
+    #
+    # @example Returning typed failure
+    #   failure('Not found', type: Servus::Support::Errors::NotFoundError)
+<%- end -%>
     def call
-      # Implement service logic here
+      # TODO: Implement service logic here
       success({})
     end
-    <%= attr_readers %>
+
+    private
+
+    <%= attr_readers.empty? ? '# TODO: Add attr_readers for instance variables' : attr_readers %>
   end
-end
+end

data/lib/generators/servus/service/templates/service_spec.rb.erb

@@ -1,9 +1,70 @@
-require "rails_helper"
+# frozen_string_literal: true
+
+require 'rails_helper'
 
 RSpec.describe <%= service_full_class_name %> do
-  describe "#call" do
-    it "does something" do
-      # Add expectations here
-    end
+<%- unless options[:no_docs] -%>
+  # Test the service by calling it with valid arguments and asserting on the result.
+  #
+  # Example test patterns:
+  #
+  #   it 'returns success with expected data' do
+  #     result = described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: #{p}_value" }.join(', ') %>)
+  #
+  #     expect(result).to be_success
+  #     expect(result.data).to include(expected_key: expected_value)
+  #   end
+  #
+  #   it 'returns failure when validation fails' do
+  #     result = described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: invalid_value" }.join(', ') %>)
+  #
+  #     expect(result).to be_failure
+  #     expect(result.error.message).to eq('Expected error message')
+  #   end
+  #
+  # For testing async execution:
+  #   it 'enqueues the service job' do
+  #     expect {
+  #       described_class.call_async(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: #{p}_value" }.join(', ') %>)
+  #     }.to have_enqueued_job(Servus::ServiceJob)
+  #   end
+  #
+  # For testing event emissions:
+  #   include Servus::Testing::EventHelpers
+  #
+  #   it 'emits expected event on success' do
+  #     servus_expect_event(:event_name)
+  #       .with_payload(hash_including(key: value))
+  #       .when { described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: value" }.join(', ') %>) }
+  #   end
+
+<%- end -%>
+<%- if parameters.any? -%>
+  let(:<%= parameters.first %>) { nil } # TODO: Set valid test value
+<%- parameters[1..-1]&.each do |param| -%>
+  let(:<%= param %>) { nil } # TODO: Set valid test value
+<%- end -%>
+
+<%- end -%>
+  describe '#call' do
+<%- unless options[:no_docs] -%>
+    # TODO: Add success case test
+    # it 'returns success with expected data' do
+    #   result = described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: #{p}" }.join(', ') %>)
+    #
+    #   expect(result).to be_success
+    #   expect(result.data).to include(key: value)
+    # end
+
+    # TODO: Add failure case test
+    # it 'returns failure when conditions are not met' do
+    #   result = described_class.call(<%= parameters.empty? ? '' : parameters.map { |p| "#{p}: invalid_#{p}" }.join(', ') %>)
+    #
+    #   expect(result).to be_failure
+    #   expect(result.error.message).to eq('Expected error')
+    # end
+<%- else -%>
+    # Add your tests here
+<%- end -%>
   end
-end
+end