{"id":13878700,"url":"https://github.com/antulik/active_interaction-extras","last_synced_at":"2025-07-16T14:32:51.051Z","repository":{"id":38242416,"uuid":"134802911","full_name":"antulik/active_interaction-extras","owner":"antulik","description":"Useful extensions for active_interaction gem","archived":false,"fork":false,"pushed_at":"2024-09-26T04:12:30.000Z","size":88,"stargazers_count":52,"open_issues_count":5,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-31T13:59:05.686Z","etag":null,"topics":["activemodel","extension","ruby","service-object"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antulik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-25T04:21:31.000Z","updated_at":"2024-10-25T16:44:03.000Z","dependencies_parsed_at":"2024-01-13T20:38:03.999Z","dependency_job_id":"561e9ce6-17af-41a8-95ec-d538e84485f8","html_url":"https://github.com/antulik/active_interaction-extras","commit_stats":{"total_commits":59,"total_committers":7,"mean_commits":8.428571428571429,"dds":"0.11864406779661019","last_synced_commit":"c645764c48e050a78ccf7014b57c197deedc153e"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antulik%2Factive_interaction-extras","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antulik%2Factive_interaction-extras/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antulik%2Factive_interaction-extras/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antulik%2Factive_interaction-extras/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antulik","download_url":"https://codeload.github.com/antulik/active_interaction-extras/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226138849,"owners_count":17579496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activemodel","extension","ruby","service-object"],"created_at":"2024-08-06T08:01:57.102Z","updated_at":"2024-11-24T07:31:16.126Z","avatar_url":"https://github.com/antulik.png","language":"Ruby","readme":"# ActiveInteraction::Extras\n\n[![Gem Version](https://badge.fury.io/rb/active_interaction-extras.svg)](https://badge.fury.io/rb/active_interaction-extras) ![CI build](https://github.com/antulik/active_interaction-extras/actions/workflows/ci.yml/badge.svg)\n\nThis gem contains the collection of useful extensions to [active_interaction](https://github.com/AaronLasseigne/active_interaction) gem.\n\n- [Installation](#installation)\n- [Basic Usage](#basic-usage)\n- [Filters](#filters)\n    - [Anything](#anything)\n    - [UUID](#uuid)\n- [Filter Extensions](#filter-extensions)\n    - [Hash: auto strip](#hash-auto-strip)\n    - [Object: multiple classes](#object-multiple-classes)\n- [Extensions](#extensions)\n  - [Filter alias](#filter-alias)\n  - [Halt](#halt)\n  - [ModelFields](#modelfields)\n  - [RunCallback](#runcallback)\n  - [StrongParams](#strongparams)\n  - [Transaction](#transaction)\n- [Jobs](#jobs)\n  - [ActiveJob](#activejob)\n  - [Sidekiq](#sidekiq)\n- [RSpec](#rspec)\n\n## Installation\n\n```ruby\ngem 'active_interaction-extras'\n```\n\n## Basic Usage\n\n```ruby\n# app/services/application_interaction.rb\nclass ApplicationInteraction \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::All\nend\n```\n\n## Filters\n\nThese new filters are added automatically when gem is loaded.\n\n### Anything\n\nAnything filter accepts as you guest it - anything.\n\n```ruby\nclass Service \u003c ActiveInteraction::Base\n  anything :model\nend\n```\n\n### UUID\n\n```ruby\nclass Service \u003c ActiveInteraction::Base\n  uuid :id\nend\n```\n\n## Filter Extensions\n\nYou can load all filter extensions with:\n\n```ruby\n# config/initializers/active_interaction.rb\nrequire 'active_interaction/extras/filter_extensions'\n```\n\n### Hash: auto strip\n\nThis small extensions allows to accept full hashes without explicit `strip` option.\n\n```ruby\nclass Service \u003c ActiveInteraction::Base\n  hash :options_a, strip: false # (Before) Accept all keys\n  \n  hash :options_b # (After) Accept all keys\n  \n  hash :options_c do # (Before and After) Accept only specified keys\n    string :name\n  end\nend\n```\n\n### Object: multiple classes\n\nThis extension allows using `object` filter with multiple classes.\n\n```ruby\nclass Service \u003c ActiveInteraction::Base\n  object :user, class: [User, AdminUser]\nend\n```\n\n\n## Extensions\n\n### Filter Alias\n\n```ruby\nclass Service \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::FilterAlias\n  \n  hash :params, as: :user_attributes\n\n  def execute\n    user_attributes == params # =\u003e true\n  end\nend\n```\n\n### Halt\n\n```ruby\nclass Service \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::Halt\n\n  def execute\n    other_method\n    puts('finished') # this won't be called\n  end\n\n  def other_method\n    errors.add :base, :invalid\n    halt! if errors.any?\n    # or\n    halt_if_errors!\n  end\nend\n```\n\n### ModelFields\n\n```ruby\nclass UserForm \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::ModelFields\n\n  anything :user\n\n  model_fields(:user) do\n    string :first_name\n    string :last_name\n  end\n\n  def execute\n    model_fields(:user)                   # =\u003e {:first_name=\u003e\"Albert\", :last_name=\u003e\"Balk\"}\n    any_changed?(:first_name, :last_name) # =\u003e true\n    given_model_fields(:user)             # =\u003e {:first_name=\u003e\"Albert\"}\n    changed_model_fields(:user)           # =\u003e {:first_name=\u003e\"Albert\"}\n  end\nend\n\nuser = OpenStruct.new(first_name: 'Sam', last_name: 'Balk')\n\nUserForm.new(user: user).first_name # =\u003e 'Sam'\nUserForm.run!(user: user, first_name: 'Albert')\n```\n\n### RunCallback\n\n```ruby\nclass Service \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::RunCallback\n\n  after_run do\n    # LogAttempt.log\n  end\n\n  after_successful_run do\n    # Email.deliver\n  end\n\n  after_failed_run do\n    # NotifyAdminEmail.deliver\n  end\n\n  def execute\n  end\nend\n```\n\n### StrongParams\n\n```ruby\nclass UpdateUserForm \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::StrongParams\n\n  string :first_name, default: nil, permit: true\n  string :last_name, default: nil\n\n  def execute\n    first_name # =\u003e 'Allowed'\n    last_name  # =\u003e nil\n  end\nend\n\nUpdateUserForm.new.to_model.model_name.param_key # =\u003e 'update_user_form'\n\nform_params = ActionController::Parameters.new(\n  update_user_form: {\n    first_name: 'Allowed',\n    last_name: 'Not allowed',\n  },\n)\n\nService.run(params: form_params)\n\n# OR\nform_params = ActionController::Parameters.new(\n  first_name: 'Allowed',\n  last_name: 'Not allowed',\n)\n\nService.run(form_params: form_params)\n```\n\n### Transaction\n\n```ruby\nclass UpdateUserForm \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::Transaction\n\n  run_in_transaction!\n\n  def execute\n    Comment.create! # succeeds\n\n    errors.add(:base, :invalid)\n  end\nend\n\nUpdateUserForm.run\nComment.count # =\u003e 0\n```\n\n## Jobs\n\nYou no longer need to create a separate Job class for the each interaction. This Job extension automatically converts interactions to background jobs. By convention each interaction will have a nested `Job` class which will be inherited from the parent interaction `Job` class (e.g. `ApplicationInteraction::Job`). \n\n### ActiveJob\n\n```ruby\nclass ApplicationInteraction \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::ActiveJob\n\n  class Job \u003c ActiveJob::Base\n    include ActiveInteraction::Extras::ActiveJob::Perform\n  end\nend\n\nclass DoubleService \u003c ApplicationInteraction\n  integer :x\n\n  def execute\n    x + x\n  end\nend\n\nDoubleService.delay.run(x: 2) # queues to run in background\nDoubleService.delay(queue: 'low_priority', wait: 1.minute).run(x: 2)\n```\n\nIn ActiveJob mode `delay` method accepts anything ActiveJob `set` [method](https://edgeapi.rubyonrails.org/classes/ActiveJob/Core/ClassMethods.html#method-i-set) does. (`wait`, `wait_until`, `queue`, `priority`)\n\n### Sidekiq\n\nYou can use sidekiq directly if you need more control. Sidekiq integration comes with default GlobalID support.\n\n```ruby\nclass ApplicationInteraction \u003c ActiveInteraction::Base\n  include ActiveInteraction::Extras::Sidekiq\n\n  class Job\n    include Sidekiq::Worker\n    include ActiveInteraction::Extras::Sidekiq::Perform\n  end\nend\n\nclass DoubleService \u003c ApplicationInteraction\n  job do\n    sidekiq_options retry: 1 # configure sidekiq options\n  end\n\n  integer :x\n\n  def execute\n    x + x\n  end\nend\n\nDoubleService.delay.run(x: 2) # queues to run in background\nDoubleService.delay(queue: 'low_priority', wait: 1.minute).run(x: 2)\n```\n\nIn Sidekiq mode `delay` method accepts anything sidekiq `set` [method](https://github.com/mperham/sidekiq/wiki/Advanced-Options#workers) does (`queue`, `retry`, `backtrace`, etc). Plus two additional `wait` and `wait_until`.\n\n```ruby\n# Advance usage: retry based on given params\nclass DoubleService \u003c ApplicationInteraction\n  job do\n    sidekiq_options(retry: -\u003e(job) {\n      params = deserialize_active_job_args(job)\n      params[:x]\n    })\n  end\n\n  integer :x\n\n  def execute\n    x + x\n  end\nend\n```\n\n```ruby\n# Advance usage: Rescue the job but not service\nclass DoubleService \u003c ApplicationInteraction\n  job do\n    def perform(*args)\n      super\n    rescue StandardError =\u003e e\n      params = deserialize_active_job_args(args)\n      params[:x]\n    end\n  end\n\n  integer :x\n\n  def execute\n    raise\n  end\nend\n\nDoubleService.run # =\u003e RuntimeError\nDoubleService.delay.perform_now(x: 2) # =\u003e returns 2\n```\n\n## Rspec\n\n```ruby\nclass SomeService \u003c ActiveInteraction::Base\n  integer :x\nend\n\nRSpec.describe SomeService do\n  include ActiveInteraction::Extras::Rspec\n\n  it 'works' do\n    expect_to_execute(SomeService,\n      with: [{ x: 1 }]\n      return: :asd\n    )\n\n    result = SomeService.run! x: 1\n\n    expect(result).to eq :asd\n  end\n\n  it 'lists all mocks' do\n    # allow_to_run\n    # allow_to_execute\n    # allow_to_delay_run\n    # allow_to_delay_execute\n\n    # expect_to_run / expect_not_to_run / expect_to_not_run\n    # expect_to_execute\n    # expect_to_delay_run / expect_not_to_run_delayed / expect_to_not_run_delayed\n    # expect_to_delay_execute\n  end\nend\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/antulik/active_interaction-extras. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Credits\n\n* ActiveInteraction::Extras is brought to you by [Anton Katunin](https://github.com/antulik) and was originally built at [CarNextDoor](https://www.carnextdoor.com.au/).\n* Further improvements to this gem brought to you by [Anton Katunin](https://github.com/antulik) once again and the [Split Payments team](https://github.com/splitpayments/split).\n\n## Code of Conduct\n\nEveryone interacting in the ActiveInteraction::Extras project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/antulik/active_interaction-extras/blob/master/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantulik%2Factive_interaction-extras","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantulik%2Factive_interaction-extras","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantulik%2Factive_interaction-extras/lists"}