light-services 2.2 → 3.0.0

data/docs/context.md

@@ -0,0 +1,128 @@
+# Context
+
+Context allows services to be run within the same execution scope, enabling shared state and coordinated transactions.
+
+## Key Features
+
+- Services share arguments marked as `context: true`
+- If any service fails, the entire context fails and rolls back database changes
+
+## How to Run Services in the Same Context
+
+To run a service in the same context, call `with(self)` before the `#run` method.
+
+## Context Rollback
+
+### Example:
+
+Let's say we have two services: `User::Create` and `Profile::Create`. We want to ensure that if either service fails, all database changes are rolled back.
+
+```ruby
+class User::Create < ApplicationService
+  # Arguments
+  arg :attributes, type: Hash
+
+  # Steps
+  step :create_user
+  step :create_profile
+  step :send_welcome_email
+
+  # Outputs
+  output :user, type: User
+  output :profile, type: Profile
+
+  def create_user
+    self.user = User.create!(attributes)
+  end
+
+  def create_profile
+    service = Profile::Create
+      .with(self) # This runs the service in the same context
+      .run(user:)
+
+    self.profile = service.profile
+  end
+
+  # If the Profile::Create service fails, this step and any following steps won't execute
+  # And all database changes will be rolled back
+  def send_welcome_email
+    # We don't run this service in the same context
+    # Because we don't care too much if it fails
+    service = Mailer::SendWelcomeEmail.run(user:)
+
+    # Handle the failure manually if needed
+    if service.failed?
+      # Handle the failure
+    end
+  end
+end
+```
+
+## Context Arguments
+
+Context arguments are shared between services running in the same context. This can make them a bit less predictable and harder to test.
+
+It's recommended to use context arguments only when necessary and keep them as close to the root service as possible. For example, you can use them to share `current_user` or `current_organization` between services.
+
+```ruby
+class ApplicationService < Light::Services::Base
+  arg :current_user, type: User, context: true
+end
+```
+
+```ruby
+class Comment::Create < ApplicationService
+  # Arguments
+  # We don't need to specify current_user here
+  # as it's automatically inherited from the ApplicationService
+  arg :post_id, type: Integer
+  arg :text, type: String
+  arg :subscribe, type: [TrueClass, FalseClass]
+
+  # Steps
+  step :create_comment
+  step :subscribe_to_post, if: :subscribe?
+
+  private
+
+  def create_comment
+    # ...
+  end
+
+  def subscribe_to_post
+    Post::Subscribe
+      .with(self) # Run service in the same context
+      .run(post_id:) # We omit current_user here as context will handle it for us
+
+    # If we run Post::Subscribe without `with(self)`
+    # It'll fail because it won't have information about the `current_user`
+  end
+end
+```
+
+```ruby
+class Post::Subscribe < ApplicationService
+  # Arguments
+  arg :post_id, type: Integer
+
+  # Steps
+  step :subscribe
+
+  private
+
+  def subscribe
+    # We have access to current_user here because we run it in the same context
+    #
+    # Even if we would run this service without context this won't be a problem
+    # because we specified this argument in top-level service (ApplicationService)
+    current_user.subscriptions.create!(post_id:)
+  end
+end
+```
+
+# What's Next?
+
+The next step is to learn about error handling in Light Service.
+
+[Next: Errors](errors.md)
+

data/docs/crud.md

@@ -0,0 +1,525 @@
+# CRUD
+
+In this recipe we'll create top-level CRUD services to manage our records.
+
+This approach has been tested in production for many years and has saved significant time and effort.
+
+## Why
+
+We want to put all the common logic for creating, updating, destroying and finding records in one place.
+
+We want to minimize possibility of a mistake by putting logic as close to core as possible.
+
+## How to use it in controllers
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    render json: crud_find_all(Post)
+  end
+
+  def show
+    render json: crud_find(Post)
+  end
+
+  def create
+    render_service crud_create(Post)
+  end
+
+  def update
+    render_service crud_update(Post)
+  end
+
+  def destroy
+    render_service crud_destroy(Post)
+  end
+end
+```
+
+{% hint style="info" %}
+`render_service` method is a method from [Rendering Services](service-rendering.md) recipe.
+{% endhint %}
+
+## How to use it in services
+
+```ruby
+class ParseProfiles < ApplicationService
+  # ...
+
+  def create_profiles
+    profiles.each do |profile|
+      # Create profile service is automatically run within the same context
+      create(
+        Profile,
+        name: profile.name,
+        age: profile.age,
+      )
+    end
+  end
+end
+```
+
+## Customization
+
+You don't need to create a new service for every CRUD operation. But you can create a service for specific model if you need to customize the behavior.
+
+Just create a service called `{Model}::Create`, `{Model}::Update`, `{Model}::Destroy` and inherit from `CreateRecordService`, `UpdateRecordService`, `DestroyRecordService` respectively.
+
+For example:
+
+**Adding additional steps to create user:**
+
+```ruby
+class User::Create < CreateRecordService
+  step :create_profile
+
+  private
+
+  def create_profile
+    create!(Profile, user:)
+  end
+end
+```
+
+**Setting default attributes:**
+
+```ruby
+class Post::Create < CreateRecordService
+  private
+
+  def default_attributes
+    { status: :draft }
+  end
+end
+```
+
+**Override attributes:**
+
+```ruby
+class Post::Update < UpdateRecordService
+  private
+
+  def override_attributes
+    { updated_by: current_user }
+  end
+end
+```
+
+**Skipping step:**
+
+```ruby
+class Post::Destroy < DestroyRecordService
+  remove_step :authorize
+end
+```
+
+## Code
+
+{% hint style="info" %}
+This code is just a starting point. You can customize it to fit your needs.
+{% endhint %}
+
+{% hint style="info" %}
+You need to add `Pundit Authorization` and `Request Concern` to make this code work.
+{% endhint %}
+
+**app/services/create\_record\_service.rb:**
+
+```ruby
+class CreateRecordService < ApplicationService
+  # Arguments
+  arg :record_class, type: Class, default: -> { self.class.module_parent }
+  arg :attributes, type: Hash, default: {}
+
+  # Steps
+  step :create_alias
+  step :authorize_user
+  step :initialize_record
+  step :assign_attributes
+  step :save_record
+
+  # Outputs
+  output :record
+
+  private
+
+  # Create a readable alias for the record based on the class name (e.g. `user` for `User`)
+  def create_alias
+    define_singleton_method(record_class.to_s.underscore) { record }
+  end
+
+  # Check if the user is authorized to create a record
+  def authorize_user
+    auth(record_class, :create?)
+  end
+
+  # Initialize a new record
+  def initialize_record
+    self.record = record_class.new
+  end
+
+  # Assign attributes to the record
+  def assign_attributes
+    assign_attributes = default_attributes
+      .merge(params_attributes)
+      .merge(attributes)
+      .merge(override_attributes)
+
+    record.assign_attributes(assign_attributes)
+  end
+
+  # Save the record
+  def save_record
+    record.save_with!(self)
+  end
+
+  # Extract permitted attributes using Pundit
+  def params_attributes
+    return {} if !attributes.nil? && !(attributes.respond_to?(:empty?) && attributes.empty?)
+
+    permitted_attributes(record, :create)
+  rescue ActionController::ParameterMissing
+    {}
+  rescue Pundit::NotDefinedError
+    raise unless system
+
+    {}
+  end
+
+  # Default attributes, which can be overridden in subclasses
+  def default_attributes
+    {}
+  end
+
+  # Override attributes, which can be overridden in subclasses
+  def override_attributes
+    {}
+  end
+end
+```
+
+**app/services/update\_record\_service.rb:**
+
+```ruby
+class UpdateRecordService < ApplicationService
+  # Arguments
+  arg :record, type: ActiveRecord::Base
+  arg :attributes, type: Hash, default: {}
+
+  # Steps
+  step :create_alias
+  step :validate_record_class
+  step :authorize_user
+  step :assign_attributes
+  step :save_record
+
+  private
+
+  # Create a readable alias for the record based on the class name (e.g. `user` for `User`)
+  def create_alias
+    define_singleton_method(record.class.to_s.underscore) { record }
+  end
+
+  # Make sure record is an instance of the correct class
+  def validate_record_class
+    return if self.class.module_parent == Object # No parent module
+    return if self.class.module_parent == record.class
+
+    errors.add(:base, "record must be #{self.class.module_parent}")
+  end
+
+  # Check if the user is authorized to update this record
+  def authorize_user
+    auth(record, :update?) if attributes.nil? || (attributes.respond_to?(:empty?) && attributes.empty?)
+  end
+
+  # Assign attributes to the record
+  def assign_attributes
+    assign_attributes = default_attributes
+      .merge(params_attributes)
+      .merge(attributes)
+      .merge(override_attributes)
+
+    record.assign_attributes(assign_attributes)
+  end
+
+  # Save the record
+  def save_record
+    record.save!
+  rescue ActiveRecord::RecordInvalid
+    errors.copy_from(record)
+  end
+
+  # Extract permitted attributes from params using Pundit
+  def params_attributes
+    return {} if !attributes.nil? && !(attributes.respond_to?(:empty?) && attributes.empty?)
+
+    permitted_attributes(record, :update)
+  rescue ActionController::ParameterMissing
+    {}
+  rescue Pundit::NotDefinedError
+    raise unless system
+
+    {}
+  end
+
+  # Default attributes, which can be overridden in subclasses
+  def default_attributes
+    {}
+  end
+
+  # Overridden attributes, which can be overridden in subclasses
+  def override_attributes
+    {}
+  end
+end
+```
+
+**app/services/destroy\_record\_service.rb:**
+
+```ruby
+class DestroyRecordService < ApplicationService
+  # Arguments
+  arg :record, type: ActiveRecord::Base
+  arg :attributes, type: Hash, default: {}
+
+  # Steps
+  step :create_alias
+  step :authorize_user
+  step :destroy_record
+
+  private
+
+  # Create a readable alias for the record based on the class name (e.g. `user` for `User`)
+  def create_alias
+    define_singleton_method(record.class.to_s.underscore) { record }
+  end
+
+  # Check if the user is authorized to update this record
+  def authorize_user
+    auth(record, :destroy?)
+  end
+
+  # Delete the record
+  def destroy_record
+    record.destroy!
+  rescue ActiveRecord::RecordNotDestroyed
+    errors.copy_from(record)
+  end
+end
+```
+
+**app/controller/application\_controller.rb:**
+
+```ruby
+class ApplicationController < ActionController::Base
+  # Includes
+  include CRUDControllers
+  include AuthenticateUser
+
+  private
+
+  def service_args(hash = {})
+    hash.reverse_merge(
+      params:,
+      request:,
+      current_user:,
+      current_administrator:,
+    )
+  end
+end
+```
+
+**app/controllers/concerns/crud\_controllers.rb:**
+
+```ruby
+module CRUDControllers
+  extend ActiveSupport::Concern
+
+  included do
+    def crud_find(klass, args = {})
+      crud_service(
+        klass,
+        "Find",
+        FindRecordService,
+        args.merge(record_class: klass),
+      ).record
+    end
+
+    def crud_find_all(klass, args = {})
+      crud_service(
+        klass,
+        "FindAll",
+        FindAllRecordsService,
+        args.merge(record_class: klass),
+      ).scope
+    end
+
+    def crud_create(klass, args = {})
+      crud_service(
+        klass,
+        "Create",
+        CreateRecordService,
+        args.merge(record_class: klass),
+      )
+    end
+
+    def crud_update(record, args = {})
+      crud_service(
+        record.class,
+        "Update",
+        UpdateRecordService,
+        args.merge(record:),
+      )
+    end
+
+    def crud_destroy(record, args = {})
+      crud_service(
+        record.class,
+        "Destroy",
+        DestroyRecordService,
+        args.merge(record:),
+      )
+    end
+
+    private
+
+    def crud_service(klass, class_postfix, default_class, args)
+      begin
+        service_class = "#{klass}::#{class_postfix}".constantize
+      rescue NameError
+        service_class = default_class
+      end
+
+      service_class.run(service_args(args))
+    end
+  end
+end
+```
+
+**app/services/application\_service.rb:**
+
+```ruby
+class ApplicationService < Light::Services::Base
+  # Includes
+  include CRUDServices
+  include RequestConcern
+end
+```
+
+**app/services/concerns/crud\_services.rb:**
+
+```ruby
+module CRUDServices
+  extend ActiveSupport::Concern
+
+  included do
+    def find(klass, args = {})
+      run_service(
+        klass,
+        "Find",
+        FindRecordService,
+        args.merge(record_class: klass),
+      )
+    end
+
+    def find_all(klass, args = {})
+      args.reverse_merge!(no_filters: true)
+
+      run_service(
+        klass,
+        "FindAll",
+        FindAllRecordsService,
+        args.merge(record_class: klass),
+        plural_output: true,
+      )
+    end
+
+    def create(klass, attributes = {}, args = {})
+      run_service(
+        klass,
+        "Create",
+        CreateRecordService,
+        args.merge(record_class: klass, attributes:),
+      )
+    end
+
+    def create!(klass, attributes = {}, args = {})
+      create(klass, attributes, args.merge(raise_on_error: true))
+    end
+
+    def update(record, attributes = {}, args = {})
+      run_service(
+        record.class,
+        "Update",
+        UpdateRecordService,
+        args.merge(record:, attributes:),
+      )
+    end
+
+    def update!(record, attributes = {}, args = {})
+      update(record, attributes, args.merge(raise_on_error: true))
+    end
+
+    def destroy(record, args = {})
+      run_service(
+        record.class,
+        "Destroy",
+        DestroyRecordService,
+        args.merge(record:),
+      )
+    end
+
+    def destroy!(record, args = {})
+      destroy(record, args.merge(raise_on_error: true))
+    end
+
+    def create_or_update!(klass, record, attributes = {}, args = {})
+      if record
+        update!(record, attributes, args)
+      else
+        create!(klass, attributes, args)
+      end
+    end
+
+    private
+
+    def resource_name(klass, plural: false)
+      name = klass.name.demodulize.underscore
+      plural ? name.pluralize : name
+    end
+
+    def run_service(klass, class_postfix, default_class, args, opts = {})
+      begin
+        service_class = "#{klass}::#{class_postfix}".constantize
+      rescue NameError
+        service_class = default_class
+      end
+
+      service_class
+        .with(self)
+        .run(args)
+        .public_send(resource_name(klass, plural: opts[:plural_output]))
+    end
+  end
+end
+```
+
+**app/services/concerns/request\_concern.rb:**
+
+```ruby
+module RequestConcern
+  extend ActiveSupport::Concern
+
+  included do
+    arg :params, type: [Hash, ActionController::Parameters], default: ActionController::Parameters.new({}), context: true
+    arg :request, type: ActionDispatch::Request, default: ActionDispatch::Request.new({}), context: true
+  end
+end
+```
+
+## What's Next?
+
+Learn how to render service results cleanly in your controllers:
+
+[Next: Service Rendering](service-rendering.md)