rails_async_methods 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 672c0a204c6d32b0c4b33f9da9b1c9964afc45d9626128ddccf52f77a12bd8c1
+  data.tar.gz: a4cf18a167be4b327aaab34b49875280444fb7f6f52743a85aa1564f2cba2f33
+SHA512:
+  metadata.gz: 650de1333dc34b7d8307508d12f4d49eda5ab5e249342727500b7431a4fd81d6ae66cd8d9ad3d5a28a06c2000d24dff7dd7ed625cad55bdb8dfb755a6c8cbd61
+  data.tar.gz: 1e17bb9130bbfef087ebc8cfe86051284c44a12c0234287373dd63536157b47a2bbc31f320a129827c38a0950266b792ebe77bb746360466e8884ea92fb3913e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 benngarcia
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,107 @@
+# RailsAsyncMethods
+Rails Async Methods is an opinionated gem meant to remove boilerplate while creating asynchronous rails jobs. It provides a declaritive interface for converting any model method into an asychronous method by provided an abstracted wrapper around rails ActiveJob API.
+
+## Usage
+```ruby
+class User
+  def example_method
+    # logic...
+  end
+end
+async :example_method
+```
+This will give you access to ```user_instance.async_example_method```, which when called will use ActiveJob's API to create an ActiveJob with your backend of choice and call the example_method when the job is ran.
+
+One important distinction is that for a method call like
+```ruby
+def example_method_with_args(a:, b:)
+  #logic
+end
+async :example_method_with_args
+```
+the ```async_example_method_with_args``` method will have a signature that matches the original method. This makes testing and debugging during development faster, as both sync and async method calls will fail when called instead of silently failing as an active job.
+
+### Options
+
+You can pass the following options to your async declaration.
+
+- prefix: specifies a prefix other than ```async_```, i.e.
+```ruby
+async :example_method, prefix: :asynchrounous_
+
+user_instance.asynchronous_example_method
+```
+
+- job: use a custom job other than the generated ```RailsAsyncMethods::AbstractJob``` - see section on Custom Jobs below i.e.
+```ruby
+async :example_method, job: CustomExampleMethodJob
+```
+
+- ActiveJob configurations
+    - queue: specify a custom queue
+    - wait_until: specify a date for the job to run at
+    - wait: give an amount of time for the job to wait until executing
+    - priority: delayed job priority
+```ruby
+async :example_method, queue: :fast, wait_until: 1.week.from_now, wait: 1.week, priority: 1
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_async_methods"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Then, run the generator
+```bash
+$ rails generate rails_async_methods
+```
+
+Or install it yourself as:
+```bash
+$ gem install rails_async_methods
+```
+
+## Extras
+
+### Custom Jobs
+While you can implement any custom job, and have it implement the perform method with this signature.
+```ruby
+def perform(receiver, method, *args, **kwargs)
+  receiver.send(method, *args, **kwargs)
+end
+```
+
+I would instead recommend inherting from the generated ActiveJob, i.e.
+
+```ruby
+class RailsAsyncMethods::CustomJob < RailsAsyncMethods::AbstractJob
+  around_perform :do_special_thing
+
+  private
+  def do_special_thing
+    # Special Things
+  end
+end
+```
+
+## Contributing
+Contributions Welcome! Please create an issue first, and then fork and create a PR. 
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Why?
+You don't need to move 1-2 LOC out of your model. If it's larger, use a service object. Either way, your controllers and requests should be interacting with resources typically. They should not need to know about Jobs/Service/Other Design Pattern implementations of interacting with your resources. In this line of thinking, most calls that interact with a resource should be called on that resource's model. Thus, Job's that wrap 1-2 LOC or a call to a Service object are unneccesary boilerplate.
+
+So, either write your minimal logic in the model, or use whatever refactoring you deem necessary, but leave the model as the entry point for interacting with the resource. Then, declare that method as Async when you need fit.
+
+I told you this gem is opinionated.
+
+Also, the existing alternatives override the method's name, leading to confusion as what appears to be synchronous was made asyncronous. 

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/generators/rails_async_methods_generator.rb

@@ -0,0 +1,18 @@
+class RailsAsyncMethodsGenerator < Rails::Generators::Base
+  desc "This generator creates the base abstract job for the rails_async_methods gem"
+  def create_abstract_job
+    file_path = "app/jobs/rails_async_methods/abstract_job.rb"
+    return if File.exist? file_path
+
+    create_file file_path,
+      <<~FILE
+        class RailsAsyncMethods::AbstractJob < ApplicationJob
+          queue_as :default
+
+          def perform(receiver, method, *args, **kwargs)
+            receiver.send(method, *args, **kwargs)
+          end
+        end
+      FILE
+  end
+end

data/lib/rails_async_methods/active_job_options_parser.rb

@@ -0,0 +1,45 @@
+module RailsAsyncMethods
+  class ActiveJobOptionsParser
+    SET_OPTIONS = %i[queue wait_until wait priority].freeze
+
+    attr_reader :prefix, :queue, :wait_until, :wait, :priority, :job
+    STRING_ARG_SEPERATOR = [':', ','].freeze
+
+    def initialize(opts={})
+      @prefix = method_prefix(opts[:prefix])
+      @queue = opts[:queue]
+      @wait_until = opts[:wait_until].to_f if opts[:wait_until]
+      @wait = opts[:wait].seconds.from_now.to_f if opts[:wait]
+      @priority = opts[:priority].to_i if opts[:priority]
+      @job = get_job_obj(opts[:job])
+    end
+
+    def to_h
+      valid_instance_values
+    end
+
+    def to_s
+      return '' if valid_instance_values.empty?
+
+      valid_instance_values.to_s
+    end
+
+    private
+
+    def valid_instance_values
+      Hash[SET_OPTIONS.filter_map { |name| [name, send(name)] unless send(name).nil? }]
+    end
+
+    def method_prefix(prefix)
+      return 'async_' if prefix.nil? || prefix.empty?
+
+      (prefix.is_a? Symbol) ? prefix.to_s : prefix
+    end
+
+    def get_job_obj(job)
+      return RailsAsyncMethods::AbstractJob if job.nil?
+
+      (job.is_a? Symbol) ? Object.const_get(job) : job
+    end
+  end
+end

data/lib/rails_async_methods/async_method.rb

@@ -0,0 +1,46 @@
+require 'rails_async_methods/parameter_parser'
+require 'rails_async_methods/active_job_options_parser'
+
+module RailsAsyncMethods
+  module AsyncMethod
+    extend ActiveSupport::Concern
+
+    class NotPersistedError < StandardError; end
+
+    class_methods do
+      # Supported Options
+      # wait: Pass Date
+      def async(method_name, opts={})
+        raise NoMethodError unless method_defined?(method_name)
+        unbound_method = instance_method(method_name.to_sym)
+
+        parsed_method_arguments = RailsAsyncMethods::ParameterParser.new(unbound_method.parameters)
+        active_job_arguments = RailsAsyncMethods::ActiveJobOptionsParser.new(opts)
+
+        if parsed_method_arguments.empty?
+          define_method "#{active_job_arguments.prefix.concat(method_name.to_s)}" do
+            raise NotPersistedError, 'Instance must be persisted to run asynchronously' unless persisted?
+            raise TypeError, 'Cannot pass a block to an asynchronous method' if block_given?
+
+            active_job_arguments.job.set(**active_job_arguments.to_h).perform_later(self, method_name)
+          end
+        else
+          stringified_method_body = begin
+            <<~RUBY
+              define_method "#{active_job_arguments.prefix.concat(method_name.to_s)}" do |#{parsed_method_arguments.as_argument_string}|
+                raise NotPersistedError, "Instance must be persisted to run asynchronously" unless persisted?
+                raise TypeError, "Cannot pass a block to an asynchronous methods" if block_given?
+
+                positional_args, keyword_args = parsed_method_arguments.arg_values_for_job { |argument| binding.local_variable_get(argument) }
+                #{active_job_arguments.job}
+                  .set(#{active_job_arguments})
+                  .perform_later(self, method_name, *positional_args, **keyword_args)
+              end
+            RUBY
+          end
+          module_eval stringified_method_body, *unbound_method.source_location
+        end
+      end
+    end
+  end
+end

data/lib/rails_async_methods/parameter_parser.rb

@@ -0,0 +1,64 @@
+module RailsAsyncMethods
+  class ParameterParser
+    REQ_POS_DELIMETER = ','.freeze
+    OPT_POS_DELIMETER = '=nil,'.freeze
+    REST_POS_DELIMETER = ['*', ','].freeze
+    REQ_KEY_DELIMETER = ':,'.freeze
+    OPT_KEY_DELIMETER = ':nil,'.freeze
+    REST_KEY_DELIMETER = ['**', ','].freeze
+    BLOCK_DELIMETER = '&'.freeze
+    attr_reader :parameters
+
+    def initialize(parameters)
+      @parameters = parameters
+    end
+
+    def empty?
+      parameters.empty?
+    end
+
+    def as_argument_string
+      return '' if @parameters.empty?
+
+      parameters.map { |type, name| to_argument_string(type, name)}.join.chomp(',')
+    end
+
+    def arg_values_for_job(&block)
+      final_arg_values = [[], {}]
+      @parameters.each do |type, name|
+        case type
+        when :req, :opt
+          final_arg_values[0].append(block.call(name))
+        when :rest
+          final_arg_values[0].append(*block.call(name))
+        when :keyreq, :key
+          final_arg_values[1].merge!(name => block.call(name))
+        when :keyrest
+          final_arg_values[1].merge!(block.call(name))
+        end
+      end
+      final_arg_values
+    end
+
+    private
+
+    def to_argument_string(type, name)
+      case type
+      when :req
+        name.to_s.concat(REQ_POS_DELIMETER)
+      when :opt
+        name.to_s.concat(OPT_POS_DELIMETER)
+      when :keyreq
+        name.to_s.concat(REQ_KEY_DELIMETER)
+      when :key
+        name.to_s.concat(OPT_KEY_DELIMETER)
+      when :rest
+        name.to_s.prepend(REST_POS_DELIMETER[0]).concat(REST_POS_DELIMETER[1])
+      when :keyrest
+        name.to_s.prepend(REST_KEY_DELIMETER[0]).concat(REST_KEY_DELIMETER[1])
+      when :block
+        name.to_s.prepend(BLOCK_DELIMETER)
+      end
+    end
+  end
+end

data/lib/rails_async_methods/version.rb

@@ -0,0 +1,3 @@
+module RailsAsyncMethods
+  VERSION = "0.1.0"
+end

data/lib/rails_async_methods.rb

@@ -0,0 +1,9 @@
+require "rails_async_methods/version"
+
+module RailsAsyncMethods
+  autoload :AsyncMethod, 'rails_async_methods/async_method'
+end
+
+ActiveSupport.on_load(:active_record) do
+  include RailsAsyncMethods::AsyncMethod
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: rails_async_methods
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- benngarcia
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-05-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.2.4
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Utilizes the ActiveJob api to provide async callers and receivers without
+  duplicating code.
+email:
+- beng4606@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/generators/rails_async_methods_generator.rb
+- lib/rails_async_methods.rb
+- lib/rails_async_methods/active_job_options_parser.rb
+- lib/rails_async_methods/async_method.rb
+- lib/rails_async_methods/parameter_parser.rb
+- lib/rails_async_methods/version.rb
+homepage: https://github.com/benngarcia/rails_async_methods
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/benngarcia/rails_async_methods
+  changelog_uri: https://github.com/benngarcia/rails_async_methods/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Quickly, create async callers and receivers for your rails methods, because
+  y'know DRY.
+test_files: []